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 ++++++++++++++++++++++++++++++++++++++--------- man/sd_notify.xml | 31 +++++++++-- man/systemd-activate.xml | 13 +++++ man/systemd.socket.xml | 23 ++++++-- man/systemd.xml | 1 + 5 files changed, 168 insertions(+), 33 deletions(-) (limited to 'man') 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 diff --git a/man/sd_notify.xml b/man/sd_notify.xml index 14030f56b1..2d73c27f62 100644 --- a/man/sd_notify.xml +++ b/man/sd_notify.xml @@ -1,4 +1,4 @@ - + @@ -229,6 +229,27 @@ below. + + FDNAME=... + + When used in combination with + FDSTORE=1 specifies a name for the + submitted file descriptors. This name is passed to the service + during activation, and may be queried using + sd_listen_fds_with_names3. File + descriptors submitted without this field set, will implicitly + get the name stored assigned. Note that if + multiple file descriptors are submitted at once the specified + name will be assigned to all of them. In order to assign + different names to submitted file descriptors, submit them in + seperate invocations of + sd_pid_notify_with_fds(). The name may + consist of any ASCII characters, but must not contain control + characters or :. It may not be longer than + 255 characters. If a submitted name does not follow these + restrictions it is ignored. + + It is recommended to prefix variable names that are not @@ -358,7 +379,7 @@ in order to continue operation after a service restart without losing state use FDSTORE=1: - sd_pid_notify_with_fds(0, 0, "FDSTORE=1", &fd, 1); + sd_pid_notify_with_fds(0, 0, "FDSTORE=1\nFDNAME=foobar", &fd, 1); @@ -367,9 +388,11 @@ systemd1, sd-daemon3, + sd_listen_fds3, + sd_listen_fds_with_names3, + sd_watchdog_enabled3, daemon7, - systemd.service5, - sd_watchdog_enabled3 + systemd.service5 diff --git a/man/systemd-activate.xml b/man/systemd-activate.xml index 3b854fd8ec..90e974c991 100644 --- a/man/systemd-activate.xml +++ b/man/systemd-activate.xml @@ -115,6 +115,16 @@ + + NAME + + Specify a name for the activation file + descriptors. This is equivalent to setting + FileDescriptorName= in socket unit files, and + enables use of + sd_listen_fds_with_names3. + + @@ -126,6 +136,7 @@ $LISTEN_FDS $LISTEN_PID + $LISTEN_FDNAMES See sd_listen_fds3. @@ -165,6 +176,8 @@ systemd1, systemd.socket5, systemd.service5, + sd_listen_fds3, + sd_listen_fds_with_names3, cat1 diff --git a/man/systemd.socket.xml b/man/systemd.socket.xml index 212764075d..46a47b2d95 100644 --- a/man/systemd.socket.xml +++ b/man/systemd.socket.xml @@ -1,4 +1,4 @@ - + @@ -748,6 +748,22 @@ list. + + FileDescriptorName= + Assigns a name to all file descriptors this + socket unit encapsulates. This is useful to help activated + services to identify specific file descriptors, if multiple + are passed. Services may use the + sd_listen_fds_with_names3 + call to acquire the names configured for the received file + descriptors. Names may contain any ASCII character, but must + exclude control characters or :, and must + be at most 255 characters in length. If this setting is not + used the file descriptor name defaults to the name of the + socket unit, including its .socket + suffix. + + Check @@ -768,9 +784,10 @@ systemd.kill5, systemd.resource-control5, systemd.service5, - systemd.directives7 + systemd.directives7, + sd_listen_fds3, + sd_listen_fds_with_names3 - For more extensive descriptions see the "systemd for Developers" series: Socket Activation, diff --git a/man/systemd.xml b/man/systemd.xml index 9e927c3204..391333bfb4 100644 --- a/man/systemd.xml +++ b/man/systemd.xml @@ -835,6 +835,7 @@ $LISTEN_PID $LISTEN_FDS + $LISTEN_FDNAMES Set by systemd for supervised processes during socket-based activation. See -- cgit v1.2.3-54-g00ecf From 213cf5b1f27a077f1cf61a185d0bb7468c3d5380 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Tue, 6 Oct 2015 10:03:58 +0200 Subject: man: add "systemd-analyze set-log-target" to synopsis too It's already documented in prose, now add it to the synopsis too. --- man/systemd-analyze.xml | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'man') diff --git a/man/systemd-analyze.xml b/man/systemd-analyze.xml index 632e6363f6..d2db265f58 100644 --- a/man/systemd-analyze.xml +++ b/man/systemd-analyze.xml @@ -95,6 +95,12 @@ set-log-level LEVEL + + systemd-analyze + OPTIONS + set-log-target + TARGET + systemd-analyze OPTIONS -- cgit v1.2.3-54-g00ecf