--- name: "sd-varlink" section: "3" platform: "linux" package: "systemd-libs" version: "262.1-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/sd-varlink" --- # sd-varlink(3) APIs for Varlink IPC ## NAME sd-varlink - APIs for Varlink IPC ## SYNOPSIS ``` #include ``` **pkg-config --cflags --libs libsystemd** ## DESCRIPTION sd-varlink.h is part of [**libsystemd**(3)](/libsystemd/3.md) 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. Varlink IPC uses **JSON**\[3\] as marshalling format. The sd-varlink API relies on the [**sd-json**(3)](/sd-json/3.md) API for JSON serialization, deserialization and manipulation. 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. The [**varlinkctl**(1)](/varlinkctl/1.md) tool makes the functionality implemented by sd-varlink available from the command line. ## RECOGNIZING VARLINK SOCKET INODES 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)](/varlinkctl/1.md)). Four distinct roles are defined: **Table 1. *user.varlink* extended attribute roles** | | | | --- | --- | | **Attribute value** | **Meaning** | | "client" | Set on the connecting end of a connection, i.e. a socket created via **socket()** + **connect()**. Only for inodes on the anonymous socket file system ("sockfs"). | | "server" | Set on the serving end of a connection, i.e. a socket obtained via **accept()** on a listening socket. Only for inodes on the anonymous socket file system ("sockfs"). | | "listen" | Set on a listening socket, i.e. a socket created via **socket()** + **listen()**. Only for inodes on the anonymous socket file system ("sockfs"). | | "entrypoint" | Set on the entrypoint socket inode, i.e. the socket node bound into the regular file system that clients connect to. Unlike the other three, this attribute lives on a real file-system inode (not on "sockfs") and is hence visible to any process that can resolve the socket path. | 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)](/systemd.socket/5.md) for details. Specifically, for socket units for which *Accept=no* is set: ``` ... [Socket] SocketMode=0644 XAttrEntryPoint=user.varlink=entrypoint XAttrListen=user.varlink=listen ... ``` For socket units which have *Accept=yes*: ``` ... [Socket] Accept=yes SocketMode=0644 XAttrEntryPoint=user.varlink=entrypoint XAttrListen=user.varlink=listen XAttrAccept=user.varlink=server ... ``` 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". ## NOTES Functions described here are available as a shared library, which can be compiled against and linked to with the **libsystemd** [**pkg-config**(1)](/pkg-config/1.md) file. The code described here uses [**getenv**(3)](/getenv/3.md), which is declared to be not multi-thread-safe. This means that the code calling the functions described here must not call [**setenv**(3)](/setenv/3.md) 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. ## DIRECTORIES /usr/lib/systemd/varlink-bridges/ When **sd\_varlink\_connect\_url()** encounters a URL with a scheme that is not natively supported, it looks for a bridge helper binary named after the URL scheme in this directory. The binary is invoked the same way as "exec:" binaries but with the full URL passed as the first command line argument. For example, if **varlinkctl introspect https://example.com/ws/sockets/io.systemd.Hostname** is called, **varlinkctl** will look for an executable /usr/lib/systemd/varlink-bridges/https and invoke it with "https://example.com/ws/sockets/io.systemd.Hostname" as its only argument. ## SEE ALSO [**systemd**(1)](/systemd/1.md), [**sd-event**(3)](/sd-event/3.md), [**sd-json**(3)](/sd-json/3.md), [**varlinkctl**(1)](/varlinkctl/1.md), [**systemd.socket**(5)](/systemd.socket/5.md), [**sd-bus**(3)](/sd-bus/3.md), [**pkg-config**(1)](/pkg-config/1.md) ## NOTES - 1\. Varlink IPC https://varlink.org/ - 2\. UAPI.20 Varlink IPC https://uapi-group.org/specifications/specs/varlink/ - 3\. JSON https://json.org/