man/systemd-escape.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   5
   6 <refentry id="systemd-escape"
   7     xmlns:xi="http://www.w3.org/2001/XInclude">
   8
   9   <refentryinfo>
  10     <title>systemd-escape</title>
  11     <productname>systemd</productname>
  12   </refentryinfo>
  13
  14   <refmeta>
  15     <refentrytitle>systemd-escape</refentrytitle>
  16     <manvolnum>1</manvolnum>
  17   </refmeta>
  18
  19   <refnamediv>
  20     <refname>systemd-escape</refname>
  21     <refpurpose>Escape strings for usage in systemd unit names</refpurpose>
  22   </refnamediv>
  23
  24   <refsynopsisdiv>
  25     <cmdsynopsis>
  26       <command>systemd-escape</command>
  27       <arg choice="opt" rep="repeat">OPTIONS</arg>
  28       <arg choice="opt" rep="repeat">STRING</arg>
  29     </cmdsynopsis>
  30   </refsynopsisdiv>
  31
  32   <refsect1>
  33     <title>Description</title>
  34
  35     <para><command>systemd-escape</command> may be used to escape
  36     strings for inclusion in systemd unit names. The command may be
  37     used to escape and to undo escaping of strings.</para>
  38
  39     <para>The command takes any number of strings on the command line,
  40     and will process them individually, one after another. It will
  41     output them separated by spaces to stdout.</para>
  42
  43     <para>By default, this command will escape the strings passed,
  44     unless <option>--unescape</option> is passed which results in the
  45     inverse operation being applied. If <option>--mangle</option> is given, a
  46     special mode of escaping is applied instead, which assumes the
  47     string is already escaped but will escape everything that
  48     appears obviously non-escaped.</para>
  49
  50     <para>For details on the escaping and unescaping algorithms see the relevant section in
  51     <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
  52   </refsect1>
  53
  54   <refsect1>
  55     <title>Options</title>
  56
  57     <para>The following options are understood:</para>
  58
  59     <variablelist>
  60       <varlistentry>
  61         <term><option>--suffix=</option></term>
  62
  63         <listitem><para>Appends the specified unit type suffix to the
  64         escaped string. Takes one of the unit types supported by
  65         systemd, such as <literal>service</literal> or
  66         <literal>mount</literal>. May not be used in conjunction with
  67         <option>--template=</option>, <option>--unescape</option> or
  68         <option>--mangle</option>.</para>
  69
  70         <xi:include href="version-info.xml" xpointer="v216"/></listitem>
  71       </varlistentry>
  72
  73       <varlistentry>
  74         <term><option>--template=</option></term>
  75
  76         <listitem><para>Inserts the escaped strings in a unit name
  77         template. Takes a unit name template such as
  78         <filename>foobar@.service</filename>. With
  79         <option>--unescape</option>, expects instantiated unit names
  80         for this template and extracts and unescapes just the instance
  81         part. May not be used in conjunction with
  82         <option>--suffix=</option>,
  83         <option>--instance</option> or
  84         <option>--mangle</option>.</para>
  85
  86         <xi:include href="version-info.xml" xpointer="v216"/></listitem>
  87       </varlistentry>
  88
  89       <varlistentry>
  90         <term><option>--path</option></term>
  91         <term><option>-p</option></term>
  92
  93         <listitem><para>When escaping or unescaping a string, assume it refers to a file system path. This
  94         simplifies the path (leading, trailing, and duplicate <literal>/</literal> characters are removed,
  95         no-op path <literal>.</literal> components are removed, and for absolute paths, leading
  96         <literal>..</literal> components are removed). After the simplification, the path must not contain
  97         <literal>..</literal>.</para>
  98
  99         <para>This is particularly useful for generating strings suitable for unescaping with the
 100         <literal>%f</literal> specifier in unit files, see
 101         <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
 102         </para>
 103
 104         <xi:include href="version-info.xml" xpointer="v216"/></listitem>
 105       </varlistentry>
 106
 107       <varlistentry>
 108         <term><option>--unescape</option></term>
 109         <term><option>-u</option></term>
 110
 111         <listitem><para>Instead of escaping the specified strings,
 112         undo the escaping, reversing the operation. May not be used in
 113         conjunction with <option>--suffix=</option> or
 114         <option>--mangle</option>.</para>
 115
 116         <xi:include href="version-info.xml" xpointer="v216"/></listitem>
 117       </varlistentry>
 118
 119       <varlistentry>
 120         <term><option>--mangle</option></term>
 121         <term><option>-m</option></term>
 122
 123         <listitem><para>Like <option>--escape</option>, but only
 124         escape characters that are obviously not escaped yet, and
 125         possibly automatically append an appropriate unit type suffix
 126         to the string. May not be used in conjunction with
 127         <option>--suffix=</option>, <option>--template=</option> or
 128         <option>--unescape</option>.</para>
 129
 130         <xi:include href="version-info.xml" xpointer="v216"/></listitem>
 131       </varlistentry>
 132
 133       <varlistentry>
 134         <term><option>--instance</option></term>
 135
 136         <listitem><para>With <option>--unescape</option>, unescape
 137         and print only the instance part of an instantiated unit name
 138         template. Results in an error for an uninstantiated template
 139         like <filename>ssh@.service</filename> or a non-template name
 140         like <filename>ssh.service</filename>.
 141         Must be used in conjunction with <option>--unescape</option>
 142         and may not be used in conjunction with
 143         <option>--template</option>.</para>
 144
 145         <xi:include href="version-info.xml" xpointer="v240"/></listitem>
 146       </varlistentry>
 147
 148       <xi:include href="standard-options.xml" xpointer="help" />
 149       <xi:include href="standard-options.xml" xpointer="version" />
 150     </variablelist>
 151
 152   </refsect1>
 153
 154   <refsect1>
 155     <title>Examples</title>
 156
 157     <para>To escape a single string:</para>
 158     <programlisting>$ systemd-escape 'Hallöchen, Meister'
 159 Hall\xc3\xb6chen\x2c\x20Meister</programlisting>
 160
 161     <para>To undo escaping on a single string:</para>
 162     <programlisting>$ systemd-escape -u 'Hall\xc3\xb6chen\x2c\x20Meister'
 163 Hallöchen, Meister</programlisting>
 164
 165     <para>To generate the mount unit for a path:</para>
 166     <programlisting>$ systemd-escape -p --suffix=mount "/tmp//waldi/foobar/"
 167 tmp-waldi-foobar.mount</programlisting>
 168
 169     <para>To generate instance names of three strings:</para>
 170     <programlisting>$ systemd-escape --template=systemd-nspawn@.service 'My Container 1' 'containerb' 'container/III'
 171 systemd-nspawn@My\x20Container\x201.service systemd-nspawn@containerb.service systemd-nspawn@container-III.service</programlisting>
 172
 173     <para>To extract the instance part of an instantiated unit:</para>
 174     <programlisting>$ systemd-escape -u --instance 'systemd-nspawn@My\x20Container\x201.service'
 175 My Container 1</programlisting>
 176
 177     <para>To extract the instance part of an instance of a particular template:</para>
 178     <programlisting>$ systemd-escape -u --template=systemd-nspawn@.service 'systemd-nspawn@My\x20Container\x201.service'
 179 My Container 1</programlisting>
 180   </refsect1>
 181
 182   <refsect1>
 183     <title>Exit status</title>
 184
 185     <para>On success, 0 is returned, a non-zero failure code
 186     otherwise.</para>
 187   </refsect1>
 188
 189   <refsect1>
 190     <title>See Also</title>
 191     <para>
 192       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 193       <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 194       <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 195     </para>
 196   </refsect1>
 197
 198 </refentry>