systemd-escape.xml revision 9869e75929acd9377aa460074334d8523cf8e822
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering This file is part of systemd.
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering Copyright 2014 Lennart Poettering
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering systemd is free software; you can redistribute it and/or modify it
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering under the terms of the GNU Lesser General Public License as published by
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering the Free Software Foundation; either version 2.1 of the License, or
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering (at your option) any later version.
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering systemd is distributed in the hope that it will be useful, but
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering WITHOUT ANY WARRANTY; without even the implied warranty of
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering Lesser General Public License for more details.
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering You should have received a copy of the GNU Lesser General Public License
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering along with systemd; If not, see <http://www.gnu.org/licenses/>.
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering xmlns:xi="http://www.w3.org/2001/XInclude">
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering <refentryinfo>
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering </authorgroup>
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering </refentryinfo>
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering <refentrytitle>systemd-escape</refentrytitle>
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering <refpurpose>Escape strings for usage in system unit names</refpurpose>
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering <refsynopsisdiv>
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering <command>systemd-escape <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="opt" rep="repeat">STRING</arg></command>
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering </cmdsynopsis>
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering </refsynopsisdiv>
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering <para><command>systemd-escape</command> may be used to
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering escape strings for inclusion in systemd unit
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering names. The command may be used to escape and to undo
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering escaping of strings.</para>
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering <para>The command takes any number of strings on the
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering command line, and will process them individually, one
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering after the other. It will output them separated by
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering spaces to stdout.</para>
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering <para>By default this command will escape the strings
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering passed, unless <option>--unescape</option> is passed
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering which results in the inverse operation being
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering applied. If <option>--mangle</option> a special mode
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering of escaping is applied instead, which assumes a string
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering to be already escaped but will escape everything that
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering appears obviously non-escaped.</para>
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering <para>The following options are understood:</para>
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering <variablelist>
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering <varlistentry>
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering unit type suffix to the escaped
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering string. Takes one of the unit types
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering supported by systemd, such as
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering used in conjunction with
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering <option>--mangle</option>.</para></listitem>
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering </varlistentry>
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering <varlistentry>
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering <term><option>--template=</option></term>
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering strings in a unit name template. Takes
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering a unit name template such as
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering May not be used in conjunction with
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering <option>--mangle</option>.</para></listitem>
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering </varlistentry>
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering <varlistentry>
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering unescaping a string, assume it refers
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering to a file system path. This enables
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering special processing of the initial
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering </varlistentry>
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering <varlistentry>
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering the specified strings, undo the
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering escaping, reversing the operation. May
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering not be used in conjunction with
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering <option>--mangle</option>.</para></listitem>
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering </varlistentry>
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering <varlistentry>
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering escape characters that are obviously
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering not escaped yet, and possibly
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering automatically append an appropriate
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering unit type suffix to the string. May
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering not be used in conjunction with
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering <option>--unescape</option>.</para></listitem>
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering </varlistentry>
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering <xi:include href="standard-options.xml" xpointer="help" />
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering <xi:include href="standard-options.xml" xpointer="version" />
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering </variablelist>
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering <programlisting>$ systemd-escape 'Hallöchen, Meister'
9869e75929acd9377aa460074334d8523cf8e822Lennart PoetteringHall\xc3\xb6chen\x2c\x20Meister</programlisting>
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering <para>To undo escaping on a single string:</para>
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering <programlisting>$ systemd-escape -u 'Hall\xc3\xb6chen\x2c\x20Meister'
9869e75929acd9377aa460074334d8523cf8e822Lennart PoetteringHallöchen, Meister</programlisting>
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering <para>To generate the mount unit for a path:</para>
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering <programlisting>$ systemd-escape -p --suffix=mount "/tmp//waldi/foobar/"
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering <para>To generate instance names of three strings</para>
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering <programlisting>$ systemd-escape --template=systemd-nspawn@.service 'My Container 1' 'containerb' 'container/III'
9869e75929acd9377aa460074334d8523cf8e822Lennart Poetteringsystemd-nspawn@My\x20Container\x201.service systemd-nspawn@containerb.service systemd-nspawn@container-III.service</programlisting>
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering <para>On success, 0 is returned, a non-zero failure
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering code otherwise.</para>
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
9869e75929acd9377aa460074334d8523cf8e822Lennart Poettering <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>