|
HTML rendering created 2026-09-09 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|
|
NAME | SYNOPSIS | DESCRIPTION | RECOGNIZING VARLINK SOCKET INODES | NOTES | DIRECTORIES | SEE ALSO | NOTES | COLOPHON |
|
|
|
SD-VARLINK(3) sd-varlink SD-VARLINK(3)
sd-varlink - APIs for Varlink IPC
#include <systemd/sd-varlink.h>
pkg-config --cflags --libs libsystemd
sd-varlink.h is part of libsystemd(3) and provides APIs for
implementing Varlink IPC clients and services. See
https://varlink.org/ for more information about Varlink IPC.
Varlink IPC uses JSON[1] as marshalling format. The sd-varlink API
relies on the sd-json(3) 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) tool makes the functionality implemented by
sd-varlink available from the command line.
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)).
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) 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".
Functions described here are available as a shared library, which
can be compiled against and linked to with the
libsystemd pkg-config(1) file.
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.
/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.
systemd(1), sd-event(3), sd-json(3), varlinkctl(1),
systemd.socket(5), sd-bus(3), pkg-config(1)
1. JSON
https://json.org/
This page is part of the systemd (systemd system and service
manager) project. Information about the project can be found at
⟨http://www.freedesktop.org/wiki/Software/systemd⟩. If you have a
bug report for this manual page, see
⟨http://www.freedesktop.org/wiki/Software/systemd/#bugreports⟩.
This page was obtained from the project's upstream Git repository
⟨https://github.com/systemd/systemd.git⟩ on 2026-08-04. (At that
time, the date of the most recent commit that was found in the
repository was 2026-08-03.) If you discover any rendering
problems in this HTML version of the page, or you believe there is
a better or more up-to-date source for the page, or you have
corrections or improvements to the information in this COLOPHON
(which is not part of the original manual page), send a mail to
man-pages@man7.org
systemd 262~devel SD-VARLINK(3)
Pages that refer to this page: libsystemd(3), sd-bus(3), sd-json(3), sd_json_dispatch_string(3), sd_varlink_call_and_upgrade(3), sd_varlink_connect_address(3), sd_varlink_is_connected(3), sd_varlink_push_fd(3), sd_varlink_reply_and_upgrade(3), sd_varlink_send(3), sd_varlink_server_listen_address(3), sd_varlink_server_new(3), sd_varlink_set_description(3), sd_varlink_set_relative_timeout(3), systemd.directives(7), systemd.index(7)
|
HTML rendering created 2026-09-09 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|