path: root/upstream/fedora-rawhide/man1/systemd-escape.1

'\" t
.TH "SYSTEMD\-ESCAPE" "1" "" "systemd 255" "systemd-escape"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
systemd-escape \- Escape strings for usage in systemd unit names
.SH "SYNOPSIS"
.HP \w'\fBsystemd\-escape\fR\ 'u
\fBsystemd\-escape\fR [OPTIONS...] [STRING...]
.SH "DESCRIPTION"
.PP
\fBsystemd\-escape\fR
may be used to escape strings for inclusion in systemd unit names\&. The command may be used to escape and to undo escaping of strings\&.
.PP
The command takes any number of strings on the command line, and will process them individually, one after another\&. It will output them separated by spaces to stdout\&.
.PP
By default, this command will escape the strings passed, unless
\fB\-\-unescape\fR
is passed which results in the inverse operation being applied\&. If
\fB\-\-mangle\fR
is given, a special mode of escaping is applied instead, which assumes the string is already escaped but will escape everything that appears obviously non\-escaped\&.
.PP
For details on the escaping and unescaping algorithms see the relevant section in
\fBsystemd.unit\fR(5)\&.
.SH "OPTIONS"
.PP
The following options are understood:
.PP
\fB\-\-suffix=\fR
.RS 4
Appends the specified unit type suffix to the escaped string\&. Takes one of the unit types supported by systemd, such as
"service"
or
"mount"\&. May not be used in conjunction with
\fB\-\-template=\fR,
\fB\-\-unescape\fR
or
\fB\-\-mangle\fR\&.
.sp
Added in version 216\&.
.RE
.PP
\fB\-\-template=\fR
.RS 4
Inserts the escaped strings in a unit name template\&. Takes a unit name template such as
foobar@\&.service\&. With
\fB\-\-unescape\fR, expects instantiated unit names for this template and extracts and unescapes just the instance part\&. May not be used in conjunction with
\fB\-\-suffix=\fR,
\fB\-\-instance\fR
or
\fB\-\-mangle\fR\&.
.sp
Added in version 216\&.
.RE
.PP
\fB\-\-path\fR, \fB\-p\fR
.RS 4
When escaping or unescaping a string, assume it refers to a file system path\&. This simplifies the path (leading, trailing, and duplicate
"/"
characters are removed, no\-op path
"\&."
components are removed, and for absolute paths, leading
"\&.\&."
components are removed)\&. After the simplification, the path must not contain
"\&.\&."\&.
.sp
This is particularly useful for generating strings suitable for unescaping with the
"%f"
specifier in unit files, see
\fBsystemd.unit\fR(5)\&.
.sp
Added in version 216\&.
.RE
.PP
\fB\-\-unescape\fR, \fB\-u\fR
.RS 4
Instead of escaping the specified strings, undo the escaping, reversing the operation\&. May not be used in conjunction with
\fB\-\-suffix=\fR
or
\fB\-\-mangle\fR\&.
.sp
Added in version 216\&.
.RE
.PP
\fB\-\-mangle\fR, \fB\-m\fR
.RS 4
Like
\fB\-\-escape\fR, but only escape characters that are obviously not escaped yet, and possibly automatically append an appropriate unit type suffix to the string\&. May not be used in conjunction with
\fB\-\-suffix=\fR,
\fB\-\-template=\fR
or
\fB\-\-unescape\fR\&.
.sp
Added in version 216\&.
.RE
.PP
\fB\-\-instance\fR
.RS 4
With
\fB\-\-unescape\fR, unescape and print only the instance part of an instantiated unit name template\&. Results in an error for an uninstantiated template like
ssh@\&.service
or a non\-template name like
ssh\&.service\&. Must be used in conjunction with
\fB\-\-unescape\fR
and may not be used in conjunction with
\fB\-\-template\fR\&.
.sp
Added in version 240\&.
.RE
.PP
\fB\-h\fR, \fB\-\-help\fR
.RS 4
Print a short help text and exit\&.
.RE
.PP
\fB\-\-version\fR
.RS 4
Print a short version string and exit\&.
.RE
.SH "EXAMPLES"
.PP
To escape a single string:
.sp
.if n \{\
.RS 4
.\}
.nf
$ systemd\-escape \*(AqHallöchen, Meister\*(Aq
Hall\exc3\exb6chen\ex2c\ex20Meister
.fi
.if n \{\
.RE
.\}
.PP
To undo escaping on a single string:
.sp
.if n \{\
.RS 4
.\}
.nf
$ systemd\-escape \-u \*(AqHall\exc3\exb6chen\ex2c\ex20Meister\*(Aq
Hallöchen, Meister
.fi
.if n \{\
.RE
.\}
.PP
To generate the mount unit for a path:
.sp
.if n \{\
.RS 4
.\}
.nf
$ systemd\-escape \-p \-\-suffix=mount "/tmp//waldi/foobar/"
tmp\-waldi\-foobar\&.mount
.fi
.if n \{\
.RE
.\}
.PP
To generate instance names of three strings:
.sp
.if n \{\
.RS 4
.\}
.nf
$ systemd\-escape \-\-template=systemd\-nspawn@\&.service \*(AqMy Container 1\*(Aq \*(Aqcontainerb\*(Aq \*(Aqcontainer/III\*(Aq
systemd\-nspawn@My\ex20Container\ex201\&.service systemd\-nspawn@containerb\&.service systemd\-nspawn@container\-III\&.service
.fi
.if n \{\
.RE
.\}
.PP
To extract the instance part of an instantiated unit:
.sp
.if n \{\
.RS 4
.\}
.nf
$ systemd\-escape \-u \-\-instance \*(Aqsystemd\-nspawn@My\ex20Container\ex201\&.service\*(Aq
My Container 1
.fi
.if n \{\
.RE
.\}
.PP
To extract the instance part of an instance of a particular template:
.sp
.if n \{\
.RS 4
.\}
.nf
$ systemd\-escape \-u \-\-template=systemd\-nspawn@\&.service \*(Aqsystemd\-nspawn@My\ex20Container\ex201\&.service\*(Aq
My Container 1
.fi
.if n \{\
.RE
.\}
.SH "EXIT STATUS"
.PP
On success, 0 is returned, a non\-zero failure code otherwise\&.
.SH "SEE ALSO"
.PP
\fBsystemd\fR(1),
\fBsystemd.unit\fR(5),
\fBsystemctl\fR(1)