SD_VARLINK_SERVER_NEW(3)

✨ sd_varlink_server_new ✨

okay bestie, welcome to the sd_varlink_server_new(3) page 💅 it's a systemd man page, it lives in section 3, and it's all about birthing a brand new Varlink server object. let's get into it 🫶

---

🌸 NAME 🌸

sd_varlink_server_new — allocate a Varlink server object, like, the whole entire thing 🎀

---

🦋 SYNOPSIS 🦋

#include <systemd/sd-varlink.h>

int sd_varlink_server_new(sd_varlink_server** ret,
                          sd_varlink_server_flags_t flags);

---

💖 DESCRIPTION 💖

so sd_varlink_server_new() allocates a shiny new Varlink server object for you. and like, initially it does not listen on any socket or file descriptor — it's just vibing there, existing, unbound, no cap. the freshly allocated server object gets handed back to you in the ret parameter. when you're done with it (and bestie, you will be done with it), use sd_varlink_server_unref() to release the server object again 💅

these are the flags you can pass in the flags parameter, and honestly? each one is kind of iconic:

• SD_VARLINK_SERVER_ROOT_ONLY — only allows connections from UID 0, aka the root user 👑. this has two effects: any incoming connection gets authenticated via SO_PEERCRED to make sure the UID the kernel reports is zero, and if that check fails the connection is immediately terminated, no discussion, blocked 💀. plus, when binding a socket inode in the file system, the access mode is set to 0600 (instead of 0666). and heads up — if you use this option, connections on non-AF_UNIX sockets or via pipes are never permitted. ever. periodt.
• SD_VARLINK_SERVER_MYSELF_ONLY — very similar to SD_VARLINK_SERVER_ROOT_ONLY, but instead it enforces that the connecting client's UID must match the server's UID (i.e. the UID this function is invoked as). for servers that run as UID 0, these two flags are literally equivalent. and if you specify both flags in combination, then connections are allowed by both UID 0 and the server's own UID — best of both worlds, slay ✨
• SD_VARLINK_SERVER_ACCOUNT_UID — if set, connection accounting per client UID is enabled, and a limit on concurrent connections from the same UID gets enforced. you can set that limit via sd_varlink_server_set_connections_per_uid_max(), and it defaults to 3/4th of the total concurrent connection limit, which you can set via sd_varlink_server_set_connections_max() 🍓
• SD_VARLINK_SERVER_INHERIT_USERDATA — if set, the user data field for incoming connection (i.e. sd_varlink) objects (as settable via sd_varlink_set_userdata()) is automatically set to the userdata field of the server (i.e. sd_varlink_server) object (as settable via sd_varlink_server_set_userdata()). if you don't specify this flag, the connection's user data field will just default to NULL. sad, but fine 🥲
• SD_VARLINK_SERVER_INPUT_SENSITIVE — marks all incoming method call parameters as security sensitive (equivalent to calling sd_json_variant_sensitive()). this is so useful for services that deal with secrets and similar stuff, because it ensures the parameters are kept out of debug logging, and the memory used by the parameters is erased after use 🔐. secrets stay secret, as they should 💜
• SD_VARLINK_SERVER_ALLOW_FD_PASSING_INPUT — if set, allows receiving UNIX file descriptors via the connections, equivalent to calling sd_varlink_set_allow_fd_passing_input() immediately for each incoming connection. note that this only has an effect if AF_UNIX sockets are used for communication 📎
• SD_VARLINK_SERVER_ALLOW_FD_PASSING_OUTPUT — similar, but this one controls sending of UNIX file descriptors 📤
• SD_VARLINK_SERVER_FD_PASSING_INPUT_STRICT — this flag can be used in conjunction with SD_VARLINK_SERVER_ALLOW_FD_PASSING_INPUT. if you do, file descriptor passing is turned off on the listening sockets already, ensuring that the connection sockets derived from it at no time have file descriptor passing enabled. but if SD_VARLINK_SERVER_ALLOW_FD_PASSING_INPUT is used without SD_VARLINK_SERVER_FD_PASSING_INPUT_STRICT, then a choice of when to prohibit or allow file descriptor passing can still be made after the connection came in — however, that permits a time window where file descriptors might already be enqueued, that then need to be dropped again 😬 so like, know what you're doing, bestie
• SD_VARLINK_SERVER_HANDLE_SIGINT — if set, and sd_varlink_server_loop_auto() is used, incoming SIGINT process signals will be caught gracefully and cause the event loop to exit cleanly 🧚
• SD_VARLINK_SERVER_HANDLE_SIGTERM — similar, but does the same thing for SIGTERM 🌈

---

⭐ RETURN VALUE ⭐

on success, sd_varlink_server_new() returns a non-negative integer 🎉 on failure, it returns a negative errno-style error code 😭

🙈 Errors

returned errors may indicate the following problems:

• -EINVAL — an argument is invalid. rude, but okay.

---

👑 NOTES 👑

the functions described here are available as a shared library, which you can compile against and link 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. like, do it at the beginning, before the chaos starts, fr fr 💀

---

📜 HISTORY 📜

sd_varlink_server_new() was added in version 257. she's new-ish, she's cute, she's here 🌸

---

🔥 SEE ALSO 🔥

systemd(1), sd-varlink(3)

---

and that's the whole page bestie!! 💖 this was systemd 262.1, from the SD_VARLINK_SERVER_NEW(3) era — go forth and allocate your servers, you've got this 🫶✨💅