man/systemd-escape.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <!--
   6   SPDX-License-Identifier: LGPL-2.1+
   7 -->
   8
   9 <refentry id="systemd-escape"
  10     xmlns:xi="http://www.w3.org/2001/XInclude">
  11
  12   <refentryinfo>
  13     <title>systemd-escape</title>
  14     <productname>systemd</productname>
  15   </refentryinfo>
  16
  17   <refmeta>
  18     <refentrytitle>systemd-escape</refentrytitle>
  19     <manvolnum>1</manvolnum>
  20   </refmeta>
  21
  22   <refnamediv>
  23     <refname>systemd-escape</refname>
  24     <refpurpose>Escape strings for usage in systemd unit names</refpurpose>
  25   </refnamediv>
  26
  27   <refsynopsisdiv>
  28     <cmdsynopsis>
  29       <command>systemd-escape</command>
  30       <arg choice="opt" rep="repeat">OPTIONS</arg>
  31       <arg choice="opt" rep="repeat">STRING</arg>
  32     </cmdsynopsis>
  33   </refsynopsisdiv>
  34
  35   <refsect1>
  36     <title>Description</title>
  37
  38     <para><command>systemd-escape</command> may be used to escape
  39     strings for inclusion in systemd unit names. The command may be
  40     used to escape and to undo escaping of strings.</para>
  41
  42     <para>The command takes any number of strings on the command line,
  43     and will process them individually, one after another. It will
  44     output them separated by spaces to stdout.</para>
  45
  46     <para>By default, this command will escape the strings passed,
  47     unless <option>--unescape</option> is passed which results in the
  48     inverse operation being applied. If <option>--mangle</option> is given, a
  49     special mode of escaping is applied instead, which assumes the
  50     string is already escaped but will escape everything that
  51     appears obviously non-escaped.</para>
  52
  53     <para>For details on the escaping and unescaping algorithms see the relevant section in
  54     <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
  55   </refsect1>
  56
  57   <refsect1>
  58     <title>Options</title>
  59
  60     <para>The following options are understood:</para>
  61
  62     <variablelist>
  63       <varlistentry>
  64         <term><option>--suffix=</option></term>
  65
  66         <listitem><para>Appends the specified unit type suffix to the
  67         escaped string. Takes one of the unit types supported by
  68         systemd, such as <literal>service</literal> or
  69         <literal>mount</literal>. May not be used in conjunction with
  70         <option>--template=</option>, <option>--unescape</option> or
  71         <option>--mangle</option>.</para></listitem>
  72       </varlistentry>
  73
  74       <varlistentry>
  75         <term><option>--template=</option></term>
  76
  77         <listitem><para>Inserts the escaped strings in a unit name
  78         template. Takes a unit name template such as
  79         <filename>foobar@.service</filename>. May not be used in
  80         conjunction with <option>--suffix=</option>,
  81         <option>--unescape</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>,
 104         <option>--template=</option> or
 105         <option>--mangle</option>.</para></listitem>
 106       </varlistentry>
 107
 108       <varlistentry>
 109         <term><option>--mangle</option></term>
 110         <term><option>-m</option></term>
 111
 112         <listitem><para>Like <option>--escape</option>, but only
 113         escape characters that are obviously not escaped yet, and
 114         possibly automatically append an appropriate unit type suffix
 115         to the string. May not be used in conjunction with
 116         <option>--suffix=</option>, <option>--template=</option> or
 117         <option>--unescape</option>.</para></listitem>
 118       </varlistentry>
 119
 120       <xi:include href="standard-options.xml" xpointer="help" />
 121       <xi:include href="standard-options.xml" xpointer="version" />
 122     </variablelist>
 123
 124   </refsect1>
 125
 126   <refsect1>
 127     <title>Examples</title>
 128
 129     <para>To escape a single string:</para>
 130     <programlisting>$ systemd-escape 'Hallöchen, Meister'
 131 Hall\xc3\xb6chen\x2c\x20Meister</programlisting>
 132
 133     <para>To undo escaping on a single string:</para>
 134     <programlisting>$ systemd-escape -u 'Hall\xc3\xb6chen\x2c\x20Meister'
 135 Hallöchen, Meister</programlisting>
 136
 137     <para>To generate the mount unit for a path:</para>
 138     <programlisting>$ systemd-escape -p --suffix=mount "/tmp//waldi/foobar/"
 139 tmp-waldi-foobar.mount</programlisting>
 140
 141     <para>To generate instance names of three strings:</para>
 142     <programlisting>$ systemd-escape --template=systemd-nspawn@.service 'My Container 1' 'containerb' 'container/III'
 143 systemd-nspawn@My\x20Container\x201.service systemd-nspawn@containerb.service systemd-nspawn@container-III.service</programlisting>
 144   </refsect1>
 145
 146   <refsect1>
 147     <title>Exit status</title>
 148
 149     <para>On success, 0 is returned, a non-zero failure code
 150     otherwise.</para>
 151   </refsect1>
 152
 153   <refsect1>
 154     <title>See Also</title>
 155     <para>
 156       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 157       <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 158       <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 159     </para>
 160   </refsect1>
 161
 162 </refentry>