diff options
Diffstat (limited to 'upstream/fedora-40/man1/systemd-escape.1')
| -rw-r--r-- | upstream/fedora-40/man1/systemd-escape.1 | 223 |
1 files changed, 223 insertions, 0 deletions
diff --git a/upstream/fedora-40/man1/systemd-escape.1 b/upstream/fedora-40/man1/systemd-escape.1 new file mode 100644 index 00000000..a69c2c8d --- /dev/null +++ b/upstream/fedora-40/man1/systemd-escape.1 @@ -0,0 +1,223 @@ +'\" 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) |