From 1e46eb5971f83d57b320082862cc1174120e1d9c Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Mon, 23 Apr 2018 19:21:27 +0200 Subject: [PATCH 1/5] doc: clarify the intended audience of CGROUP_DELEGATION.md There was some confusion about who is the intended audience. Let's clarify that early on, to ensure people aren't disappointed. --- doc/CGROUP_DELEGATION.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/doc/CGROUP_DELEGATION.md b/doc/CGROUP_DELEGATION.md index 3124eabcc0..f78211b3a0 100644 --- a/doc/CGROUP_DELEGATION.md +++ b/doc/CGROUP_DELEGATION.md @@ -1,5 +1,8 @@ # Control Group APIs and Delegation +*Intended audience: hackers working on userspace subsystems that require direct +cgroup access, such as container managers and similar.* + So you are wondering about resource management with systemd, you know Linux control groups (cgroups) a bit and are trying to integrate your software with what systemd has to offer there. Here's a bit of documentation about the From 3e0bff7d0b812357c43aa831c57a34f00cdf2f31 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Mon, 23 Apr 2018 19:25:23 +0200 Subject: [PATCH 2/5] man: document BSD exit codes in systemd.exec(5) too Our own tools use them now, and we probably should encourage that, hence let's document them along with the other exit codes we use. --- man/systemd.exec.xml | 92 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 92 insertions(+) diff --git a/man/systemd.exec.xml b/man/systemd.exec.xml index b2ac0a2655..1a01a7f75f 100644 --- a/man/systemd.exec.xml +++ b/man/systemd.exec.xml @@ -2612,6 +2612,98 @@ StandardInputData=SWNrIHNpdHplIGRhIHVuJyBlc3NlIEtsb3BzLAp1ZmYgZWVtYWwga2xvcHAncy + + Finally, the BSD operating systems define a set of exit codes, typically defined on Linux systems too: + + + BSD exit codes + + + + Exit Code + Symbolic Name + Description + + + + + 64 + EX_USAGE + Command line usage error + + + 65 + EX_DATAERR + Data format error + + + 66 + EX_NOINPUT + Cannot open input + + + 67 + EX_NOUSER + Addressee unknown + + + 68 + EX_NOHOST + Host name unknown + + + 69 + EX_UNAVAILABLE + Service unavailable + + + 70 + EX_SOFTWARE + internal software error + + + 71 + EX_OSERR + System error (e.g., can't fork) + + + 72 + EX_OSFILE + Critical OS file missing + + + 73 + EX_CANTCREAT + Can't create (user) output file + + + 74 + EX_IOERR + Input/output error + + + 75 + EX_TEMPFAIL + Temporary failure; user is invited to retry + + + 76 + EX_PROTOCOL + Remote error in protocol + + + 77 + EX_NOPERM + Permission denied + + + 78 + EX_CONFIG + Configuration error + + + +
From 0a233ba1795fc526e8b604da9893ee3e3a6702c3 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Mon, 23 Apr 2018 19:26:25 +0200 Subject: [PATCH 3/5] exit-status: list BSD exit codes too Let's optionally translate BSD exit codes to error strings too. My first approach on adding this was to turn ExitStatusLevel into a bitmask rather than a linear level, with one bit for the various feature bits. However, the exit code ranges are generally not defined independently from each other, i.e. our own ones are defined with the LSB ones in mind, and most sets are defined with the ISO C ones. Hence, instead I changed the existing hierarchy of MINIMAL, SYSTEMD, LSB with an alias of FULL == LSB, only slightly by seperating FULL and LSB into two separate levels, so that there's now: 1. MINIMAL (only EXIT_SUCCESS/EXIT_FAILURE) 2. SYSTEMD (incorporating our own exit codes) 3. LSB (like SYSTEMD but adding in LSB service exit codes) 4. FULL (like FULL but adding BSD exit codes) Note that across the codebase only FULL, SYSTEMD, and MINIMAL are used, depending on context, how much we know about the process and whether we are logging for debugging purposes or not. This means the LSB level wouldn't really have to be separate, but it appeared careless to me to fold it into FULL along with the BSD exit codes. Note that this commit doesn't change much for regular codepaths: the FULL exit status level is only used during debug logging, as a helper to the user reading the debug logs. --- src/basic/exit-status.c | 76 +++++++++++++++++++++++++++++++++++++---- src/basic/exit-status.h | 8 ++--- 2 files changed, 73 insertions(+), 11 deletions(-) diff --git a/src/basic/exit-status.c b/src/basic/exit-status.c index 3827f254fa..c2064b7ef1 100644 --- a/src/basic/exit-status.c +++ b/src/basic/exit-status.c @@ -7,6 +7,7 @@ #include #include +#include #include "exit-status.h" #include "macro.h" @@ -14,10 +15,21 @@ const char* exit_status_to_string(int status, ExitStatusLevel level) { - /* We cast to int here, so that -Wenum doesn't complain that - * EXIT_SUCCESS/EXIT_FAILURE aren't in the enum */ + /* Exit status ranges: + * + * 0…1 │ ISO C, EXIT_SUCCESS + EXIT_FAILURE + * 2…7 │ LSB exit codes for init scripts + * 8…63 │ (Currently unmapped) + * 64…78 │ BSD defined exit codes + * 79…199 │ (Currently unmapped) + * 200…241 │ systemd's private error codes (might be extended to 254 in future development) + * 242…254 │ (Currently unmapped, but see above) + * 255 │ (We should probably stay away from that one, it's frequently used by applications to indicate an + * │ exit reason that cannot really be expressed in a single exit status value — such as a propagated + * │ signal or such) + */ - switch (status) { + switch (status) { /* We always cover the ISO C ones */ case EXIT_SUCCESS: return "SUCCESS"; @@ -26,8 +38,8 @@ const char* exit_status_to_string(int status, ExitStatusLevel level) { return "FAILURE"; } - if (IN_SET(level, EXIT_STATUS_SYSTEMD, EXIT_STATUS_LSB)) { - switch (status) { + if (IN_SET(level, EXIT_STATUS_SYSTEMD, EXIT_STATUS_LSB, EXIT_STATUS_FULL)) { + switch (status) { /* Optionally we cover our own ones */ case EXIT_CHDIR: return "CHDIR"; @@ -151,8 +163,8 @@ const char* exit_status_to_string(int status, ExitStatusLevel level) { } } - if (level == EXIT_STATUS_LSB) { - switch (status) { + if (IN_SET(level, EXIT_STATUS_LSB, EXIT_STATUS_FULL)) { + switch (status) { /* Optionally we support LSB ones */ case EXIT_INVALIDARGUMENT: return "INVALIDARGUMENT"; @@ -174,6 +186,56 @@ const char* exit_status_to_string(int status, ExitStatusLevel level) { } } + if (level == EXIT_STATUS_FULL) { + switch (status) { /* Optionally, we support BSD exit statusses */ + + case EX_USAGE: + return "USAGE"; + + case EX_DATAERR: + return "DATAERR"; + + case EX_NOINPUT: + return "NOINPUT"; + + case EX_NOUSER: + return "NOUSER"; + + case EX_NOHOST: + return "NOHOST"; + + case EX_UNAVAILABLE: + return "UNAVAILABLE"; + + case EX_SOFTWARE: + return "SOFTWARE"; + + case EX_OSERR: + return "OSERR"; + + case EX_OSFILE: + return "OSFILE"; + + case EX_CANTCREAT: + return "CANTCREAT"; + + case EX_IOERR: + return "IOERR"; + + case EX_TEMPFAIL: + return "TEMPFAIL"; + + case EX_PROTOCOL: + return "PROTOCOL"; + + case EX_NOPERM: + return "NOPERM"; + + case EX_CONFIG: + return "CONFIG"; + } + } + return NULL; } diff --git a/src/basic/exit-status.h b/src/basic/exit-status.h index 28a427bc98..9686e31e06 100644 --- a/src/basic/exit-status.h +++ b/src/basic/exit-status.h @@ -29,10 +29,10 @@ enum { EXIT_NOTCONFIGURED = 6, EXIT_NOTRUNNING = 7, - /* The LSB suggests that error codes >= 200 are "reserved". We - * use them here under the assumption that they hence are - * unused by init scripts. */ + /* BSD's sysexits.h defines a couple EX_xyz exit codes in the range 64 … 78 */ + /* The LSB suggests that error codes >= 200 are "reserved". We use them here under the assumption that they + * hence are unused by init scripts. */ EXIT_CHDIR = 200, EXIT_NICE, EXIT_FDS, @@ -81,7 +81,7 @@ typedef enum ExitStatusLevel { EXIT_STATUS_MINIMAL, /* only cover libc EXIT_STATUS/EXIT_FAILURE */ EXIT_STATUS_SYSTEMD, /* cover libc and systemd's own exit codes */ EXIT_STATUS_LSB, /* cover libc, systemd's own and LSB exit codes */ - EXIT_STATUS_FULL = EXIT_STATUS_LSB + EXIT_STATUS_FULL, /* cover libc, systemd's own, LSB and BSD (EX_xyz) exit codes */ } ExitStatusLevel; typedef struct ExitStatusSet { From 46b073298f71034bafd6f007d6b7e796e12153f2 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Tue, 24 Apr 2018 11:51:21 +0200 Subject: [PATCH 4/5] man: don't claim we'd set XDG_SEAT and XDG_VTNR as part of service management Previously, reading through systemd.exec(5) one might get the idea that XDG_SEAT and XDG_VTNR are part of the service management logic, but they are not, they are only set if pam_systemd is part of a PAM stack an pam_systemd is used. Hence, let's drop these env vars from the list of env vars, and instead add a paragraph after the list mentioning that pam_systemd might add more systemd-specific env vars if included in the PAM stack for a service that uses PAMName=. --- man/systemd.exec.xml | 35 +++++++++++++++-------------------- 1 file changed, 15 insertions(+), 20 deletions(-) diff --git a/man/systemd.exec.xml b/man/systemd.exec.xml index 1a01a7f75f..2d0e6772ce 100644 --- a/man/systemd.exec.xml +++ b/man/systemd.exec.xml @@ -1972,7 +1972,9 @@ StandardInputData=SWNrIHNpdHplIGRhIHVuJyBlc3NlIEtsb3BzLAp1ZmYgZWVtYWwga2xvcHAncy Variables read from files specified via EnvironmentFile= in the unit file - Variables set by any PAM modules in case PAMName= is in effect, cf. pam_env8 + Variables set by any PAM modules in case PAMName= is in effect, + cf. pam_env8 If the same environment variables are set by multiple of these sources, the later source — according to the @@ -1980,7 +1982,8 @@ StandardInputData=SWNrIHNpdHplIGRhIHVuJyBlc3NlIEtsb3BzLAp1ZmYgZWVtYWwga2xvcHAncy UnsetEnvironment= are removed again from the compiled environment variable list, immediately before it is passed to the executed process. - The following select environment variables are set by the service manager itself for each invoked process: + The following select environment variables are set or propagated by the service manager for each invoked + process: @@ -2031,24 +2034,11 @@ StandardInputData=SWNrIHNpdHplIGRhIHVuJyBlc3NlIEtsb3BzLAp1ZmYgZWVtYWwga2xvcHAncy $XDG_RUNTIME_DIR - The directory for volatile state. Set for the - user systemd instance, and also in user - sessions. See - pam_systemd8. - - - - - $XDG_SESSION_ID - $XDG_SEAT - $XDG_VTNR - - The identifier of the session, the seat name, - and virtual terminal of the session. Set by - pam_systemd8 - for login sessions. $XDG_SEAT and - $XDG_VTNR will only be set when attached to - a seat and a tty. + The directory to use for runtime objects (such as IPC objects) and volatile state. Set for all + services run by the user systemd instance, as well as any system services that use + PAMName= with a PAM stack that includes pam_systemd. See below and + pam_systemd8 for more + information. @@ -2302,6 +2292,11 @@ StandardInputData=SWNrIHNpdHplIGRhIHVuJyBlc3NlIEtsb3BzLAp1ZmYgZWVtYWwga2xvcHAncy + + For system services, when PAMName= is enabled and pam_systemd is part + of the selected PAM stack, additional environment variables defined by systemd may be set for + services. Specifically, these are $XDG_SEAT, $XDG_VTNR, see + pam_systemd8 for details. From 702bd55cfb532ec49695893a92c3e2b7059633fc Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Fri, 27 Apr 2018 17:29:38 +0200 Subject: [PATCH 5/5] journal-send: drop redundant parenthesis As suggested in @keszybz' comments on #8840 --- src/journal/journal-send.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/journal/journal-send.c b/src/journal/journal-send.c index e0526a02ca..ad7a5ea09c 100644 --- a/src/journal/journal-send.c +++ b/src/journal/journal-send.c @@ -518,7 +518,7 @@ _public_ int sd_journal_sendv_with_location( assert_return(iov, -EINVAL); assert_return(n > 0, -EINVAL); - niov = newa(struct iovec, (n + 3)); + niov = newa(struct iovec, n + 3); memcpy(niov, iov, sizeof(struct iovec) * n); ALLOCA_CODE_FUNC(f, func);