sd-varlink(3)

.SH "NAME" sd-varlink - APIs for Varlink IPC

.SH "SYNOPSIS"

#include <systemd/sd-varlink.h>

.HP 912u

pkg-config --cflags --libs libsystemd

.SH "DESCRIPTION"

.PP sd-varlink.h is part of libsystemd(3) and provides APIs for implementing Varlink IPC clients and services. See Varlink IPC[1] for more information about Varlink IPC, as well as the UAPI.20 Varlink IPC[2] specification.

.PP Varlink IPC uses JSON[3] as marshalling format. The sd-varlink API relies on the sd-json(3) API for JSON serialization, deserialization and manipulation.

.PP Canonical encoding rules: sd-varlink omits the "parameters" member on the wire in replies, errors, and notifications when there are no parameters to transmit. This reduces message size and avoids ambiguity. Receivers must be tolerant and accept any of the following encodings for the absence of parameters: an omitted "parameters" key (preferred), a JSON null value, or an empty object {}. When decoding, sd-varlink treats JSON null as if the member was omitted.

.PP The varlinkctl(1) tool makes the functionality implemented by sd-varlink available from the command line.

.SH "RECOGNIZING VARLINK SOCKET INODES"

.PP On kernels that support extended attributes on socket inodes (available since Linux 7.0), sd-varlink automatically tags the AF_UNIX socket inodes it creates and manages with the user.varlink extended attribute. The attribute records the role the socket plays in the Varlink communication, allowing other processes to discover and classify Varlink sockets, for example via varlinkctl list-sockets (see varlinkctl(1)).

.PP Four distinct roles are defined:

.sp
Table 1. user.varlink extended attribute roles

.PP Note that for socket activated Varlink services it is recommended to set these extended attributes via XAttrEntryPoint=, XAttrListen= and XAttrAccept= settings on the socket units, see systemd.socket(5) for details. Specifically, for socket units for which Accept=no is set:

...
[Socket]
SocketMode=0644
XAttrEntryPoint=user.varlink=entrypoint
XAttrListen=user.varlink=listen
...

.PP For socket units which have Accept=yes:

...
[Socket]
Accept=yes
SocketMode=0644
XAttrEntryPoint=user.varlink=entrypoint
XAttrListen=user.varlink=listen
XAttrAccept=user.varlink=server
...

.PP Note that for Varlink sockets that shall not be world-accessible it is recommended to unset the relevant "w" bits in the socket access mode, but to keep the relevant "r" bits set. As the access check done by connect() looks for the "w" bits, this does not make the service unnecessarily accessible, however it has the benefit that the extended attributes that identify the socket as Varlink-related may still be read by other users (as that's restricted by the "r" bit). Or in other words, it's recommended to set SocketMode=0644 for services that shall not be accessible to arbitrary users, rather than SocketMode=0600.

.SH "NOTES"

.PP Functions described here are available as a shared library, which can be compiled against and linked to with the libsystemd pkg-config(1) file.

.PP The code described here uses getenv(3), which is declared to be not multi-thread-safe. This means that the code calling the functions described here must not call setenv(3) from a parallel thread. It is recommended to only do calls to setenv() from an early phase of the program when no other threads have been started.

.SH "DIRECTORIES"

.PP /usr/lib/systemd/varlink-bridges/