From 2651d037518bbcfab06d6d070b86fcf667942e97 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Thu, 26 Oct 2017 12:22:38 +0200 Subject: [PATCH] man: extend documentation on the unit name escaping logic --- man/systemd-escape.xml | 15 ++++++++++----- man/systemd.unit.xml | 46 ++++++++++++++++++++++++++++------------------ 2 files changed, 38 insertions(+), 23 deletions(-) diff --git a/man/systemd-escape.xml b/man/systemd-escape.xml index fb20d2d..a2f2b92 100644 --- a/man/systemd-escape.xml +++ b/man/systemd-escape.xml @@ -73,6 +73,9 @@ special mode of escaping is applied instead, which assumes the string is already escaped but will escape everything that appears obviously non-escaped. + + For details on the escaping and unescaping algorithms see the relevant section in + systemd.unit5. @@ -107,11 +110,12 @@ - When escaping or unescaping a string, assume - it refers to a file system path. This eliminates leading, - trailing or duplicate / characters - and rejects . and .. - path components. + When escaping or unescaping a string, assume it refers to a file system path. This eliminates + leading, trailing or duplicate / characters and rejects . and + .. path components. This is particularly useful for generating strings suitable for + unescaping with the %f specifier in unit files, see + systemd.unit5. + @@ -172,6 +176,7 @@ systemd-nspawn@My\x20Container\x201.service systemd-nspawn@containerb.service sy See Also systemd1, + systemd.unit5, systemctl1 diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml index b9991be..d6feaa1 100644 --- a/man/systemd.unit.xml +++ b/man/systemd.unit.xml @@ -213,22 +213,6 @@ socket-based activation which make dependencies implicit, resulting in a both simpler and more flexible system. - Some unit names reflect paths existing in the file system - namespace. Example: a device unit - dev-sda.device refers to a device with the - device node /dev/sda in the - file system namespace. If this applies, a special way to escape - the path name is used, so that the result is usable as part of a - filename. Basically, given a path, "/" is replaced by "-", and all - other characters which are not ASCII alphanumerics are replaced by - C-style "\x2d" escapes (except that "_" is never replaced and "." - is only replaced when it would be the first character in the - escaped path). The root directory "/" is encoded as single dash, - while otherwise the initial and ending "/" are removed from all - paths during transformation. This escaping is reversible. Properly - escaped paths can be generated using the - systemd-escape1 - command. Optionally, units may be instantiated from a template file at runtime. This allows creation of @@ -266,6 +250,32 @@ + String Escaping for Inclusion in Unit Names + + Sometimes it is useful to convert arbitrary strings into unit names. To facilitate this, a method of string + escaping is used, in order to map strings containing arbitrary byte values (except NUL) into valid unit names and + their restricted character set. A common special case are unit names that reflect paths to objects in the file + system hierarchy. Example: a device unit dev-sda.device refers to a device with the device + node /dev/sda in the file system. + + The escaping algorithm operates as follows: given a string, any / character is replaced by + -, and all other characters which are not ASCII alphanumerics or _ are + replaced by C-style \x2d escapes. In addition, . is replaced with such a + C-style escape when it would appear as the first character in the escaped string. + + When the input qualifies as absolute file system path, this algorithm is extended slightly: the path to the + root directory / is encoded as single dash -. In addition, any leading, + trailing or duplicate / characters are removed from the string before transformation. Example: + /foo//bar/baz/ becomes foo-bar-baz. + + This escaping is fully reversible, as long as it is known whether the escaped string was a path (the + unescaping results are different for paths and non-path strings). The + systemd-escape1 command may be + used to apply and reverse escaping on arbitrary strings. Use systemd-escape --path to escape + path strings, and systemd-escape without otherwise. + + + Implicit Dependencies A number of unit dependencies are implicitly established, @@ -1241,7 +1251,7 @@ %N Unescaped full unit name - Same as %n, but with escaping undone + Same as %n, but with escaping undone. This undoes the escaping used when generating unit names from arbitrary strings (see above). %p @@ -1266,7 +1276,7 @@ %f Unescaped filename - This is either the unescaped instance name (if applicable) with / prepended (if applicable), or the unescaped prefix name prepended with /. + This is either the unescaped instance name (if applicable) with / prepended (if applicable), or the unescaped prefix name prepended with /. This implements unescaping according to the rules for escaping absolute file system paths discussed above. %t -- 2.7.4