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">
6 SPDX-License-Identifier: LGPL-2.1+
8 This file is part of systemd.
10 Copyright 2014 Lennart Poettering
13 <refentry id=
"systemd-escape"
14 xmlns:
xi=
"http://www.w3.org/2001/XInclude">
17 <title>systemd-escape
</title>
18 <productname>systemd
</productname>
22 <contrib>Developer
</contrib>
23 <firstname>Lennart
</firstname>
24 <surname>Poettering
</surname>
25 <email>lennart@poettering.net
</email>
31 <refentrytitle>systemd-escape
</refentrytitle>
32 <manvolnum>1</manvolnum>
36 <refname>systemd-escape
</refname>
37 <refpurpose>Escape strings for usage in systemd unit names
</refpurpose>
42 <command>systemd-escape
</command>
43 <arg choice=
"opt" rep=
"repeat">OPTIONS
</arg>
44 <arg choice=
"opt" rep=
"repeat">STRING
</arg>
49 <title>Description
</title>
51 <para><command>systemd-escape
</command> may be used to escape
52 strings for inclusion in systemd unit names. The command may be
53 used to escape and to undo escaping of strings.
</para>
55 <para>The command takes any number of strings on the command line,
56 and will process them individually, one after another. It will
57 output them separated by spaces to stdout.
</para>
59 <para>By default, this command will escape the strings passed,
60 unless
<option>--unescape
</option> is passed which results in the
61 inverse operation being applied. If
<option>--mangle
</option> is given, a
62 special mode of escaping is applied instead, which assumes the
63 string is already escaped but will escape everything that
64 appears obviously non-escaped.
</para>
66 <para>For details on the escaping and unescaping algorithms see the relevant section in
67 <citerefentry><refentrytitle>systemd.unit
</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
</para>
71 <title>Options
</title>
73 <para>The following options are understood:
</para>
77 <term><option>--suffix=
</option></term>
79 <listitem><para>Appends the specified unit type suffix to the
80 escaped string. Takes one of the unit types supported by
81 systemd, such as
<literal>service
</literal> or
82 <literal>mount
</literal>. May not be used in conjunction with
83 <option>--template=
</option>,
<option>--unescape
</option> or
84 <option>--mangle
</option>.
</para></listitem>
88 <term><option>--template=
</option></term>
90 <listitem><para>Inserts the escaped strings in a unit name
91 template. Takes a unit name template such as
92 <filename>foobar@.service
</filename>. May not be used in
93 conjunction with
<option>--suffix=
</option>,
94 <option>--unescape
</option> or
95 <option>--mangle
</option>.
</para></listitem>
99 <term><option>--path
</option></term>
100 <term><option>-p
</option></term>
102 <listitem><para>When escaping or unescaping a string, assume it refers to a file system path. This eliminates
103 leading, trailing or duplicate
<literal>/
</literal> characters and rejects
<literal>.
</literal> and
104 <literal>..
</literal> path components. This is particularly useful for generating strings suitable for
105 unescaping with the
<literal>%f
</literal> specifier in unit files, see
106 <citerefentry><refentrytitle>systemd.unit
</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
111 <term><option>--unescape
</option></term>
113 <listitem><para>Instead of escaping the specified strings,
114 undo the escaping, reversing the operation. May not be used in
115 conjunction with
<option>--suffix=
</option>,
116 <option>--template=
</option> or
117 <option>--mangle
</option>.
</para></listitem>
121 <term><option>--mangle
</option></term>
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></listitem>
131 <xi:include href=
"standard-options.xml" xpointer=
"help" />
132 <xi:include href=
"standard-options.xml" xpointer=
"version" />
138 <title>Examples
</title>
140 <para>To escape a single string:
</para>
141 <programlisting>$ systemd-escape 'Hallöchen, Meister'
142 Hall\xc3\xb6chen\x2c\x20Meister
</programlisting>
144 <para>To undo escaping on a single string:
</para>
145 <programlisting>$ systemd-escape -u 'Hall\xc3\xb6chen\x2c\x20Meister'
146 Hallöchen, Meister
</programlisting>
148 <para>To generate the mount unit for a path:
</para>
149 <programlisting>$ systemd-escape -p --suffix=mount
"/tmp//waldi/foobar/"
150 tmp-waldi-foobar.mount
</programlisting>
152 <para>To generate instance names of three strings:
</para>
153 <programlisting>$ systemd-escape --template=systemd-nspawn@.service 'My Container
1' 'containerb' 'container/III'
154 systemd-nspawn@My\x20Container\x201.service systemd-nspawn@containerb.service systemd-nspawn@container-III.service
</programlisting>
158 <title>Exit status
</title>
160 <para>On success,
0 is returned, a non-zero failure code
165 <title>See Also
</title>
167 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
168 <citerefentry><refentrytitle>systemd.unit
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
169 <citerefentry><refentrytitle>systemctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>