Debian Codegraph @

upstream/debian-unstable/man1/systemd-escape.1

raw
1 '\" t
2 .TH "SYSTEMD\-ESCAPE" "1" "" "systemd 261~rc3" "systemd-escape"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 systemd-escape \- Escape strings for usage in systemd unit names
24 .SH "SYNOPSIS"
25 .HP \w'\fBsystemd\-escape\fR\ 'u
26 \fBsystemd\-escape\fR [OPTIONS...] [STRING...]
27 .SH "DESCRIPTION"
28 .PP
29 \fBsystemd\-escape\fR
30 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\&.
31 .PP
32 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\&.
33 .PP
34 By default, this command will escape the strings passed, unless
35 \fB\-\-unescape\fR
36 is passed which results in the inverse operation being applied\&. If
37 \fB\-\-mangle\fR
38 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\&.
39 .PP
40 For details on the escaping and unescaping algorithms see the relevant section in
41 \fBsystemd.unit\fR(5)\&.
42 .SH "OPTIONS"
43 .PP
44 The following options are understood:
45 .PP
46 \fB\-\-suffix=\fR
47 .RS 4
48 Appends the specified unit type suffix to the escaped string\&. Takes one of the unit types supported by systemd, such as
49 "service"
50 or
51 "mount"\&. May not be used in conjunction with
52 \fB\-\-template=\fR,
53 \fB\-\-unescape\fR
54 or
55 \fB\-\-mangle\fR\&.
56 .sp
57 Added in version 216\&.
58 .RE
59 .PP
60 \fB\-\-template=\fR
61 .RS 4
62 Inserts the escaped strings in a unit name template\&. Takes a unit name template such as
63 foobar@\&.service\&. With
64 \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
65 \fB\-\-suffix=\fR,
66 \fB\-\-instance\fR
67 or
68 \fB\-\-mangle\fR\&.
69 .sp
70 Added in version 216\&.
71 .RE
72 .PP
73 \fB\-\-path\fR, \fB\-p\fR
74 .RS 4
75 When escaping or unescaping a string, assume it refers to a file system path\&. This simplifies the path (leading, trailing, and duplicate
76 "/"
77 characters are removed, no\-op path
78 "\&."
79 components are removed, and for absolute paths, leading
80 "\&.\&."
81 components are removed)\&. After the simplification, the path must not contain
82 "\&.\&."\&.
83 .sp
84 This is particularly useful for generating strings suitable for unescaping with the
85 "%f"
86 specifier in unit files, see
87 \fBsystemd.unit\fR(5)\&.
88 .sp
89 Added in version 216\&.
90 .RE
91 .PP
92 \fB\-\-unescape\fR, \fB\-u\fR
93 .RS 4
94 Instead of escaping the specified strings, undo the escaping, reversing the operation\&. May not be used in conjunction with
95 \fB\-\-suffix=\fR
96 or
97 \fB\-\-mangle\fR\&.
98 .sp
99 Added in version 216\&.
100 .RE
101 .PP
102 \fB\-\-mangle\fR, \fB\-m\fR
103 .RS 4
104 Like
105 \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
106 \fB\-\-suffix=\fR,
107 \fB\-\-template=\fR
108 or
109 \fB\-\-unescape\fR\&.
110 .sp
111 Added in version 216\&.
112 .RE
113 .PP
114 \fB\-\-instance\fR
115 .RS 4
116 With
117 \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
118 ssh@\&.service
119 or a non\-template name like
120 ssh\&.service\&. Must be used in conjunction with
121 \fB\-\-unescape\fR
122 and may not be used in conjunction with
123 \fB\-\-template\fR\&.
124 .sp
125 Added in version 240\&.
126 .RE
127 .PP
128 \fB\-h\fR, \fB\-\-help\fR
129 .RS 4
130 Print a short help text and exit\&.
131 .RE
132 .PP
133 \fB\-\-version\fR
134 .RS 4
135 Print a short version string and exit\&.
136 .RE
137 .SH "EXAMPLES"
138 .PP
139 To escape a single string:
140 .sp
141 .if n \{\
142 .RS 4
143 .\}
144 .nf
145 $ systemd\-escape \*(AqHallöchen, Meister\*(Aq
146 Hall\exc3\exb6chen\ex2c\ex20Meister
147 .fi
148 .if n \{\
149 .RE
150 .\}
151 .PP
152 To undo escaping on a single string:
153 .sp
154 .if n \{\
155 .RS 4
156 .\}
157 .nf
158 $ systemd\-escape \-u \*(AqHall\exc3\exb6chen\ex2c\ex20Meister\*(Aq
159 Hallöchen, Meister
160 .fi
161 .if n \{\
162 .RE
163 .\}
164 .PP
165 To generate the mount unit for a path:
166 .sp
167 .if n \{\
168 .RS 4
169 .\}
170 .nf
171 $ systemd\-escape \-p \-\-suffix=mount "/tmp//waldi/foobar/"
172 tmp\-waldi\-foobar\&.mount
173 .fi
174 .if n \{\
175 .RE
176 .\}
177 .PP
178 To generate instance names of three strings:
179 .sp
180 .if n \{\
181 .RS 4
182 .\}
183 .nf
184 $ systemd\-escape \-\-template=systemd\-nspawn@\&.service \*(AqMy Container 1\*(Aq \*(Aqcontainerb\*(Aq \*(Aqcontainer/III\*(Aq
185 systemd\-nspawn@My\ex20Container\ex201\&.service systemd\-nspawn@containerb\&.service systemd\-nspawn@container\-III\&.service
186 .fi
187 .if n \{\
188 .RE
189 .\}
190 .PP
191 To extract the instance part of an instantiated unit:
192 .sp
193 .if n \{\
194 .RS 4
195 .\}
196 .nf
197 $ systemd\-escape \-u \-\-instance \*(Aqsystemd\-nspawn@My\ex20Container\ex201\&.service\*(Aq
198 My Container 1
199 .fi
200 .if n \{\
201 .RE
202 .\}
203 .PP
204 To extract the instance part of an instance of a particular template:
205 .sp
206 .if n \{\
207 .RS 4
208 .\}
209 .nf
210 $ systemd\-escape \-u \-\-template=systemd\-nspawn@\&.service \*(Aqsystemd\-nspawn@My\ex20Container\ex201\&.service\*(Aq
211 My Container 1
212 .fi
213 .if n \{\
214 .RE
215 .\}
216 .SH "EXIT STATUS"
217 .PP
218 On success, 0 is returned, a non\-zero failure code otherwise\&.
219 .SH "SEE ALSO"
220 .PP
221 \fBsystemd\fR(1), \fBsystemd.unit\fR(5), \fBsystemctl\fR(1)