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+ -->
   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></listitem>
  69       </varlistentry>
  70
  71       <varlistentry>
  72         <term><option>--template=</option></term>
  73
  74         <listitem><para>Inserts the escaped strings in a unit name
  75         template. Takes a unit name template such as
  76         <filename>foobar@.service</filename>. With
  77         <option>--unescape</option>, expects instantiated unit names
  78         for this template and extracts and unescapes just the instance
  79         part. May not be used in conjunction with
  80         <option>--suffix=</option>,
  81         <option>--instance</option> or
  82         <option>--mangle</option>.</para></listitem>
  83       </varlistentry>
  84
  85       <varlistentry>
  86         <term><option>--path</option></term>
  87         <term><option>-p</option></term>
  88
  89         <listitem><para>When escaping or unescaping a string, assume it refers to a file system path. This eliminates
  90         leading, trailing or duplicate <literal>/</literal> characters and rejects <literal>.</literal> and
  91         <literal>..</literal> path components. This is particularly useful for generating strings suitable for
  92         unescaping with the <literal>%f</literal> specifier in unit files, see
  93         <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
  94         </para></listitem>
  95       </varlistentry>
  96
  97       <varlistentry>
  98         <term><option>--unescape</option></term>
  99         <term><option>-u</option></term>
 100
 101         <listitem><para>Instead of escaping the specified strings,
 102         undo the escaping, reversing the operation. May not be used in
 103         conjunction with <option>--suffix=</option> or
 104         <option>--mangle</option>.</para></listitem>
 105       </varlistentry>
 106
 107       <varlistentry>
 108         <term><option>--mangle</option></term>
 109         <term><option>-m</option></term>
 110
 111         <listitem><para>Like <option>--escape</option>, but only
 112         escape characters that are obviously not escaped yet, and
 113         possibly automatically append an appropriate unit type suffix
 114         to the string. May not be used in conjunction with
 115         <option>--suffix=</option>, <option>--template=</option> or
 116         <option>--unescape</option>.</para></listitem>
 117       </varlistentry>
 118
 119       <varlistentry>
 120         <term><option>--instance</option></term>
 121
 122         <listitem><para>With <option>--unescape</option>, unescape
 123         and print only the instance part of an instantiated unit name
 124         template. Results in an error for an uninstantiated template
 125         like <filename>ssh@.service</filename> or a non-template name
 126         like <filename>ssh.service</filename>.
 127         Must be used in conjunction with <option>--unescape</option>
 128         and may not be used in conjunction with
 129         <option>--template</option>.</para></listitem>
 130       </varlistentry>
 131
 132       <xi:include href="standard-options.xml" xpointer="help" />
 133       <xi:include href="standard-options.xml" xpointer="version" />
 134     </variablelist>
 135
 136   </refsect1>
 137
 138   <refsect1>
 139     <title>Examples</title>
 140
 141     <para>To escape a single string:</para>
 142     <programlisting>$ systemd-escape 'Hallöchen, Meister'
 143 Hall\xc3\xb6chen\x2c\x20Meister</programlisting>
 144
 145     <para>To undo escaping on a single string:</para>
 146     <programlisting>$ systemd-escape -u 'Hall\xc3\xb6chen\x2c\x20Meister'
 147 Hallöchen, Meister</programlisting>
 148
 149     <para>To generate the mount unit for a path:</para>
 150     <programlisting>$ systemd-escape -p --suffix=mount "/tmp//waldi/foobar/"
 151 tmp-waldi-foobar.mount</programlisting>
 152
 153     <para>To generate instance names of three strings:</para>
 154     <programlisting>$ systemd-escape --template=systemd-nspawn@.service 'My Container 1' 'containerb' 'container/III'
 155 systemd-nspawn@My\x20Container\x201.service systemd-nspawn@containerb.service systemd-nspawn@container-III.service</programlisting>
 156
 157     <para>To extract the instance part of an instantiated unit:</para>
 158     <programlisting>$ systemd-escape -u --instance 'systemd-nspawn@My\x20Container\x201.service'
 159 My Container 1</programlisting>
 160
 161     <para>To extract the instance part of an instance of a particular template:</para>
 162     <programlisting>$ systemd-escape -u --template=systemd-nspawn@.service 'systemd-nspawn@My\x20Container\x201.service'
 163 My Container 1</programlisting>
 164   </refsect1>
 165
 166   <refsect1>
 167     <title>Exit status</title>
 168
 169     <para>On success, 0 is returned, a non-zero failure code
 170     otherwise.</para>
 171   </refsect1>
 172
 173   <refsect1>
 174     <title>See Also</title>
 175     <para>
 176       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 177       <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 178       <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 179     </para>
 180   </refsect1>
 181
 182 </refentry>