diff options
author | Lennart Poettering <lennart@poettering.net> | 2017-10-26 12:22:38 +0200 |
---|---|---|
committer | Lennart Poettering <lennart@poettering.net> | 2017-11-10 19:45:29 +0100 |
commit | 2651d037518bbcfab06d6d070b86fcf667942e97 (patch) | |
tree | b304b2445faa53332b41b1605a24809d718743c1 | |
parent | 40b1a32ca854b5ce29029d358c924e1b18f4a1d0 (diff) | |
download | systemd-2651d037518bbcfab06d6d070b86fcf667942e97.tar.gz |
man: extend documentation on the unit name escaping logic
-rw-r--r-- | man/systemd-escape.xml | 15 | ||||
-rw-r--r-- | 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 fb20d2d94f..a2f2b9242f 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.</para> + + <para>For details on the escaping and unescaping algorithms see the relevant section in + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> </refsect1> <refsect1> @@ -107,11 +110,12 @@ <term><option>--path</option></term> <term><option>-p</option></term> - <listitem><para>When escaping or unescaping a string, assume - it refers to a file system path. This eliminates leading, - trailing or duplicate <literal>/</literal> characters - and rejects <literal>.</literal> and <literal>..</literal> - path components.</para></listitem> + <listitem><para>When escaping or unescaping a string, assume it refers to a file system path. This eliminates + leading, trailing or duplicate <literal>/</literal> characters and rejects <literal>.</literal> and + <literal>..</literal> path components. This is particularly useful for generating strings suitable for + unescaping with the <literal>%f</literal> specifier in unit files, see + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + </para></listitem> </varlistentry> <varlistentry> @@ -172,6 +176,7 @@ systemd-nspawn@My\x20Container\x201.service systemd-nspawn@containerb.service sy <title>See Also</title> <para> <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> </para> </refsect1> diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml index b9991bee76..d6feaa1817 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.</para> - <para>Some unit names reflect paths existing in the file system - namespace. Example: a device unit - <filename>dev-sda.device</filename> refers to a device with the - device node <filename noindex='true'>/dev/sda</filename> 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 - <citerefentry><refentrytitle>systemd-escape</refentrytitle><manvolnum>1</manvolnum></citerefentry> - command.</para> <para>Optionally, units may be instantiated from a template file at runtime. This allows creation of @@ -266,6 +250,32 @@ </refsect1> <refsect1> + <title>String Escaping for Inclusion in Unit Names</title> + + <para>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 <filename>dev-sda.device</filename> refers to a device with the device + node <filename noindex='true'>/dev/sda</filename> in the file system.</para> + + <para>The escaping algorithm operates as follows: given a string, any <literal>/</literal> character is replaced by + <literal>-</literal>, and all other characters which are not ASCII alphanumerics or <literal>_</literal> are + replaced by C-style <literal>\x2d</literal> escapes. In addition, <literal>.</literal> is replaced with such a + C-style escape when it would appear as the first character in the escaped string.</para> + + <para>When the input qualifies as absolute file system path, this algorithm is extended slightly: the path to the + root directory <literal>/</literal> is encoded as single dash <literal>-</literal>. In addition, any leading, + trailing or duplicate <literal>/</literal> characters are removed from the string before transformation. Example: + <filename>/foo//bar/baz/</filename> becomes <literal>foo-bar-baz</literal>.</para> + + <para>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 + <citerefentry><refentrytitle>systemd-escape</refentrytitle><manvolnum>1</manvolnum></citerefentry> command may be + used to apply and reverse escaping on arbitrary strings. Use <command>systemd-escape --path</command> to escape + path strings, and <command>systemd-escape</command> without <option>--path</option> otherwise.</para> + </refsect1> + + <refsect1> <title>Implicit Dependencies</title> <para>A number of unit dependencies are implicitly established, @@ -1241,7 +1251,7 @@ <row> <entry><literal>%N</literal></entry> <entry>Unescaped full unit name</entry> - <entry>Same as <literal>%n</literal>, but with escaping undone</entry> + <entry>Same as <literal>%n</literal>, but with escaping undone. This undoes the escaping used when generating unit names from arbitrary strings (see above). </entry> </row> <row> <entry><literal>%p</literal></entry> @@ -1266,7 +1276,7 @@ <row> <entry><literal>%f</literal></entry> <entry>Unescaped filename</entry> - <entry>This is either the unescaped instance name (if applicable) with <filename>/</filename> prepended (if applicable), or the unescaped prefix name prepended with <filename>/</filename>.</entry> + <entry>This is either the unescaped instance name (if applicable) with <filename>/</filename> prepended (if applicable), or the unescaped prefix name prepended with <filename>/</filename>. This implements unescaping according to the rules for escaping absolute file system paths discussed above.</entry> </row> <row> <entry><literal>%t</literal></entry> |