sd_varlink_connect_address

systemd

sd_varlink_connect_exec

sd_varlink_connect_url

sd_varlink_connect_fd

sd_varlink_connect_fd_pair

Create a Varlink connection object and connect it to a service

#include <systemd/sd-varlink.h>

struct ucred; /* defined in <sys/socket.h> */

int

sd_varlink_connect_address

sd_varlink **

ret

const char *

address

int

sd_varlink_connect_exec

sd_varlink **

ret

const char *

command

char **

argv

int

sd_varlink_connect_url

sd_varlink **

ret

const char *

url

int

sd_varlink_connect_fd

sd_varlink **

ret

int

sd_varlink_connect_fd_pair

sd_varlink **

ret

int

input_fd

int

output_fd

const struct ucred *

override_ucred

Description

These five functions allocate a new client-side Varlink connection object and connect it to a Varlink service. They differ only in how the service to talk to is specified. On success, a reference to the new connection object is returned in ret; the caller owns this reference and must eventually release it with sd_varlink_unref(3), sd_varlink_close_unref(3) or sd_varlink_flush_close_unref(3).

All five functions return immediately; none of them blocks waiting for the connection to be fully established. For socket-based connections the actual connect() may still be in progress when the function returns (see below); the connection object handles the completion transparently.

The returned connection object is not attached to any event loop. There are three ways to drive it: attach it to an sd-event(3) loop with sd_varlink_attach_event(3); run its I/O manually via sd_varlink_process(3) and sd_varlink_wait(3); or simply issue blocking method calls. In particular it is perfectly fine to follow any of these connection functions directly with a synchronous, blocking call such as sd_varlink_call(3), which internally drives the connection (including completing a still-pending connect()) and returns once the reply has been received. In that case no explicit event loop integration or manual processing is required.

sd_varlink_connect_address() connects to an AF_UNIX stream socket whose address is given as a string in address. The address must begin either with / (to reference a socket in the file system) or with @ (to reference a socket in the abstract namespace, with the remainder of the string used as the abstract name). It must be at least two characters long. No other forms are accepted (in particular, relative paths are refused). Abstract namespace names that embed NUL bytes cannot be expressed through this interface. If a file system socket path is too long to fit into a sockaddr_un structure, the connection is established transparently via an O_PATH indirection, so overlong paths work.

sd_varlink_connect_exec() forks off a child process and speaks the Varlink protocol with it over a connected AF_UNIX SOCK_STREAM socket pair. command is the program to execute; it is looked up in $PATH in the usual way (i.e. via execvp(3)). argv is the argument vector (a NULL-terminated string array) to pass to the child as its argv[]; if it is NULL or empty, an argument vector consisting of just command is synthesized. The connected socket is handed to the child as file descriptor 3 using the sd_listen_fds(3) protocol, i.e. the child is invoked with $LISTEN_FDS set to 1, $LISTEN_FDNAMES set to varlink, and the appropriate $LISTEN_PID (and, where available, $LISTEN_PIDFDID) variables. The command and argv strings are copied into the connection object, so the caller may free or modify them once the function returns.

sd_varlink_connect_url() is a higher-level interface that parses a service address string with a leading scheme and dispatches to the appropriate transport. Despite the name, these strings are not Internet URLs in the sense of the relevant RFCs. The following schemes are understood natively:

unix:<PATH>
Connects to an AF_UNIX socket, equivalent to passing <PATH> to sd_varlink_connect_address(). <PATH> must either be an absolute, normalized file system path, or begin with @ for an abstract namespace socket (for which no path normalization checks are applied).

exec:<PATH>
Forks off the executable at <PATH>, equivalent to passing it to sd_varlink_connect_exec() with no extra arguments. <PATH> must be an absolute, normalized path.

ssh:<HOST>:<PATH>; ssh-unix:<HOST>:<PATH>
Connects to an AF_UNIX socket at the absolute, normalized path <PATH> on the remote SSH host <HOST>. This relies on OpenSSH 9.4 or newer on the server side. Abstract namespace sockets are not supported for this transport. ssh: and ssh-unix: are synonyms.

ssh-exec:<HOST>:<COMMAND>
Invokes <COMMAND> (a command line, split on whitespace with shell-style quoting and unescaping) on the remote SSH host <HOST> and speaks the Varlink protocol over its standard input and output.

If the scheme is none of the above but is otherwise a syntactically valid URL scheme, sd_varlink_connect_url() looks for a bridge helper binary of that name in the directory configured via $SYSTEMD_VARLINK_BRIDGES_DIR (see below). If found and executable, it is invoked like an exec: transport, with the complete, unmodified URL passed as its sole command line argument. This allows additional transports to be plugged in out of tree.

For the natively supported schemes, URL parameterization using ;, ? or # is rejected (these are reserved for possible future use). A vsock: scheme is not currently supported.

sd_varlink_connect_fd() turns an already existing, already connected file descriptor fd into a Varlink connection. The descriptor is used for both reading and writing. It may refer to a connected stream socket, but also to a pipe or other bidirectional file descriptor.

sd_varlink_connect_fd_pair() is like sd_varlink_connect_fd(), but accepts a separate input_fd (used for reading from the peer) and output_fd (used for writing to the peer). This is useful when the two directions are backed by different descriptors, for example a pair of pipes, or the standard output and standard input of a co-process. The two descriptors may also be identical, which is exactly what sd_varlink_connect_fd() does internally. If override_ucred is non-NULL, the peer credentials reported for the connection (as returned e.g. by sd_varlink_get_peer_uid(3)) are taken from the supplied ucred structure instead of being queried from the socket via SO_PEERCRED. This is primarily useful when the descriptors are not sockets (and hence carry no kernel-supplied peer credentials), or when the credentials need to be overridden for other reasons. If override_ucred is NULL, peer credentials are determined from the socket as usual.

sd_varlink_connect_fd() and sd_varlink_connect_fd_pair() take over ownership of the descriptors passed to them: the descriptors are closed automatically when the connection object is freed, and the caller must not close them itself. On failure ownership remains with the caller.

The connection objects created by sd_varlink_connect_exec(), and by the exec:, ssh:/ssh-unix:, ssh-exec: and bridge-helper paths of sd_varlink_connect_url(), are bound to the lifetime of the spawned child process. When such a connection object is freed, the associated child process is sent SIGTERM and reaped. The child is also configured to receive SIGTERM if the calling process dies.

Return Value

On success, these functions return a non-negative integer and store a pointer to the new connection object in ret. On failure, they return a negative errno-style error code and leave ret unchanged.

Errors

Returned errors may indicate the following problems:

-EINVAL
A required argument is NULL, or the supplied address, command, or URL is malformed. This includes addresses that do not begin with / or @, abstract namespace names that do not fit into a sockaddr_un structure, and — for sd_varlink_connect_url() — file system paths that are not absolute or not normalized.

-EBADF
For sd_varlink_connect_fd() and sd_varlink_connect_fd_pair(): a supplied file descriptor is negative.

-EPROTONOSUPPORT
For sd_varlink_connect_url(): the URL contains no : separator, uses an unsupported scheme for which no bridge helper binary is available, or makes use of the reserved ;, ? or # URL parameterization characters with a natively supported scheme.

-ENOMEM
Memory allocation failed.

In addition, these functions may propagate any error returned by the underlying system calls they use, such as socket(2), connect(2), fork(2), pipe(2) and the various execution helpers.

Environment

$SYSTEMD_SSH
Used by the ssh:/ssh-unix: and ssh-exec: transports of sd_varlink_connect_url() to override the ssh binary to invoke. May be a plain file name (looked up in $PATH) or an absolute path.

$SYSTEMD_VARLINK_BRIDGES_DIR
Overrides the directory in which sd_varlink_connect_url() looks up bridge helper binaries for non-native URL schemes. Defaults to /usr/lib/systemd/varlink-bridges/.

Files

/usr/lib/systemd/varlink-bridges/
Default directory searched for bridge helper binaries when sd_varlink_connect_url() encounters a URL with a scheme that is not natively supported. See sd-varlink(3) for details.

History

sd_varlink_connect_address(), sd_varlink_connect_exec(), sd_varlink_connect_url(), sd_varlink_connect_fd() and sd_varlink_connect_fd_pair() were added in version 257.