From 8dd4c05b5495c7ffe0f12ace87e71abe17bd0a0e Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Sun, 4 Oct 2015 17:36:19 +0200 Subject: core: add support for naming file descriptors passed using socket activation This adds support for naming file descriptors passed using socket activation. The names are passed in a new $LISTEN_FDNAMES= environment variable, that matches the existign $LISTEN_FDS= one and contains a colon-separated list of names. This also adds support for naming fds submitted to the per-service fd store using FDNAME= in the sd_notify() message. This also adds a new FileDescriptorName= setting for socket unit files to set the name for fds created by socket units. This also adds a new call sd_listen_fds_with_names(), that is similar to sd_listen_fds(), but also returns the names of the fds. systemd-activate gained the new --fdname= switch to specify a name for testing socket activation. This is based on #1247 by Maciej Wereski. Fixes #1247. --- man/sd_listen_fds.xml | 133 ++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 107 insertions(+), 26 deletions(-) (limited to 'man/sd_listen_fds.xml') diff --git a/man/sd_listen_fds.xml b/man/sd_listen_fds.xml index 9b9705eb2e..ea55671e4f 100644 --- a/man/sd_listen_fds.xml +++ b/man/sd_listen_fds.xml @@ -1,4 +1,4 @@ - + @@ -45,6 +45,7 @@ sd_listen_fds + sd_listen_fds_with_names SD_LISTEN_FDS_START Check for file descriptors passed by the system manager @@ -59,23 +60,26 @@ int sd_listen_fds int unset_environment + + + int sd_listen_fds_with_names + int unset_environment + char*** names + Description - sd_listen_fds() shall be called by a - daemon to check for file descriptors passed by the init system as - part of the socket-based activation logic. - - If the unset_environment parameter is - non-zero, sd_listen_fds() will unset the - $LISTEN_FDS and $LISTEN_PID - environment variables before returning (regardless of whether the - function call itself succeeded or not). Further calls to - sd_listen_fds() will then fail, but the - variables are no longer inherited by child processes. + sd_listen_fds() may be invoked by a + daemon to check for file descriptors passed by the service manager as + part of the socket-based activation logic. It returns the number + of received file descriptors. If no file descriptors have been + received zero is returned. The first file descriptor may be found + at file descriptor number 3 + (i.e. SD_LISTEN_FDS_START), the remaining + descriptors follow at 4, 5, 6, ..., if any. If a daemon receives more than one file descriptor, they will be passed in the same order as configured in the systemd @@ -108,12 +112,86 @@ FDSTORE=1 messages, these file descriptors are passed last, in arbitrary order, and with duplicates removed. + + If the unset_environment parameter is + non-zero, sd_listen_fds() will unset the + $LISTEN_FDS, $LISTEN_PID and + $LISTEN_FDNAMES environment variables before + returning (regardless of whether the function call itself + succeeded or not). Further calls to + sd_listen_fds() will then return zero, but the + variables are no longer inherited by child processes. + + sd_listen_fds_with_names() is like + sd_listen_fds() but optionally also returns + an array of strings with identification names for the passed file + descriptors, if that is available, and the + names parameter is non-NULL. This + information is read from the $LISTEN_FDNAMES + variable, which may contain a colon-separated list of names. For + socket-activated services, these names may be configured with the + FileDescriptorName= setting in socket unit + files, see + systemd.socket5 + for details. For file descriptors pushed into the file descriptor + store (see above) the name is set via the + FDNAME= field transmitted via + sd_pid_notify_with_fds(). The primary usecase + for these names are services which accept a variety of file + descriptors which are not recognizable with functions like + sd_is_socket() alone, and thus require + identification via a name. It is recommended to rely on named file + descriptors only if identification via + sd_is_socket() and related calls is not + sufficient. Note that the names used are not unique in any + way. The returned array of strings has as many entries as file + descriptors has been received, plus a final NULL pointer + terminating the array. The caller needs to free the array itself + and each of its elements with libc's free() + call after use. If the names parameter is + NULL the call is entirely equivalent to + sd_listen_fds(). + + Under specific conditions the following automatic file + descriptor names are returned: + + + + <command>Special names</command> + + + + + + Name + Description + + + + + unknown + The process received no name for the specific file descriptor from the service manager. + + + + stored + The file descriptor originates in the service manager's per-service file descriptor store, and the FDNAME= field was absent when the file descriptor was submitted to the service manager. + + + + connection + The service was activated in per-connection style using Accept=yes in the socket unit file, and the file descriptor is the connection socket. + + + +
+ Return Value - On failure, this call returns a negative errno-style error + On failure, these calls returns a negative errno-style error code. If $LISTEN_FDS/$LISTEN_PID was not set or was not correctly set for this daemon and hence no file @@ -128,13 +206,16 @@ - Internally, this function checks whether the - $LISTEN_PID environment variable equals the - daemon PID. If not, it returns immediately. Otherwise, it parses - the number passed in the $LISTEN_FDS + Internally, sd_listen_fds() checks + whether the $LISTEN_PID environment variable + equals the daemon PID. If not, it returns immediately. Otherwise, + it parses the number passed in the $LISTEN_FDS environment variable, then sets the FD_CLOEXEC flag for the parsed number of file descriptors starting from SD_LISTEN_FDS_START. - Finally, it returns the parsed number. + Finally, it returns the parsed + number. sd_listen_fds_with_names() does the + same but also parses $LISTEN_FDNAMES if + set. @@ -144,15 +225,14 @@ $LISTEN_PID $LISTEN_FDS + $LISTEN_FDNAMES - Set by the init system - for supervised processes that use - socket-based activation. This - environment variable specifies the - data - sd_listen_fds() - parses. See above for - details. + Set by the service manager for supervised + processes that use socket-based activation. This environment + variable specifies the data + sd_listen_fds() and + sd_listen_fds_with_names() parses. See + above for details. @@ -167,6 +247,7 @@ sd_is_socket3, sd_is_socket_inet3, sd_is_socket_unix3, + sd_pid_notify_with_fds3, daemon7, systemd.service5, systemd.socket5 -- cgit v1.2.3-54-g00ecf