SYSTEMD-ESCAPE(1)

💅 SYSTEMD-ESCAPE(1) — the systemd-escape page, bestie edition

okay so picture this: you're in the systemd-escape(1) manual, and honestly? it's giving ✨glow-up✨. this little icon does exactly one thing and does it gorgeously — it escapes strings so they can live inside systemd unit names, and it can un-escape them too. no cap. 🎀

---

✨ NAME ✨

systemd-escape — escape strings for usage in systemd unit names 🦋

---

🫶 SYNOPSIS 🫶

systemd-escape [OPTIONS...] STRING...

systemd-escape [OPTIONS...] --stdin

---

🌸 DESCRIPTION 🌸

so like, systemd-escape is here to escape strings so they can be safely included in systemd unit names, and also to undo that escaping when you need the original string back. both directions, she's versatile, she's multi-talented. 💖

you can hand her any number of strings on the command line and she'll process them one after another, individually, like the queen she is — outputting them separated by spaces to stdout. but if you pass --stdin, she stops reading the command line and instead reads strings from standard input, one per line, and writes the result for each input line on its own separate output line. yes bestie, a full glow-up pipeline. ✨

by default she escapes whatever you give her — unless you pass --unescape, in which case she does the exact inverse operation. and if you give her --mangle, she switches into a special escaping mode that assumes the string is already escaped, but will escape everything that appears obviously non-escaped. it's giving "i trust you but also let me double-check". 🙈

for the full tea on the escaping and unescaping algorithms, go read the relevant section in systemd.unit(5). iykyk. 💅

---

💅 OPTIONS 💅

here's everything she understands, every single one, no skipping, we don't do that here:

• --suffix= — appends the unit type suffix you specify to the escaped string. it takes one of the unit types systemd supports, like "service" or "mount". you cannot use this with --template=, --unescape or --mangle. pick a lane bestie. 🚫

Added in version 216.

• --template= — inserts the escaped strings into a unit name template. it takes a unit name template like foobar@.service. when combined with --unescape, she expects instantiated unit names for that template and pulls out + unescapes just the instance part. may not be used together with --suffix=, --instance or --mangle. 🎀

Added in version 216.

• --stdin — read strings from standard input, one per line, instead of from the command line. the line ending is not included in the string to escape or unescape, and the result for each line goes on its own separate output line. this option may not be combined with command line strings. 🌈

Added in version 262.

• --path, -p — 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 all that simplification, the path must not contain "..". 🛑

this is especially useful for generating strings that you can later unescape with the "%f" specifier in unit files — see systemd.unit(5) for that.

Added in version 216.

• --unescape, -u — instead of escaping the strings you gave her, undo the escaping, reversing the operation. may not be used together with --suffix= or --mangle. 💫

Added in version 216.

• --mangle, -m — like --escape, but she only escapes characters that are obviously not escaped yet, and possibly automatically appends an appropriate unit type suffix to the string. may not be used together with --suffix=, --template= or --unescape. ✨

Added in version 216.

• --instance — with --unescape, unescape and print only the instance part of an instantiated unit name template. it results in an error for an uninstantiated template like ssh@.service or a non-template name like ssh.service. must be used together with --unescape and may not be used together with --template. 😭

Added in version 240.

• -h, --help — print a short help text and exit. the classic. 🫶
• --version — print a short version string and exit. 🏷️

---

🌟 EXAMPLES 🌟

to escape a single string:

$ systemd-escape 'Hallöchen, Meister'
Hall\xc3\xb6chen\x2c\x20Meister

to undo escaping on a single string:

$ systemd-escape -u 'Hall\xc3\xb6chen\x2c\x20Meister'
Hallöchen, Meister

to generate the mount unit for a path:

$ systemd-escape -p --suffix=mount "/tmp//waldi/foobar/"
tmp-waldi-foobar.mount

to generate instance names of three strings:

$ systemd-escape --template=systemd-nspawn@.service 'My Container 1' 'containerb' 'container/III'
systemd-nspawn@My\x20Container\x201.service systemd-nspawn@containerb.service systemd-nspawn@container-III.service

to generate instance names from standard input:

$ printf '%s\n' 'My Container 1' 'container/III' | systemd-escape --stdin --template=systemd-nspawn@.service
systemd-nspawn@My\x20Container\x201.service
systemd-nspawn@container-III.service

to extract the instance part of an instantiated unit:

$ systemd-escape -u --instance 'systemd-nspawn@My\x20Container\x201.service'
My Container 1

to extract the instance part of an instance of a particular template:

$ systemd-escape -u --template=systemd-nspawn@.service 'systemd-nspawn@My\x20Container\x201.service'
My Container 1

---

🎯 EXIT STATUS 🎯

on success, 0 is returned. otherwise? a non-zero failure code. she's honest like that. 💀

---

👀 SEE ALSO 👀

systemd(1), systemd.unit(5), systemctl(1)

---

and that's the whole page bestie — this was systemd 262.1 energy from the systemd-escape(1) manual, so go forth and escape your strings, you absolute main character. mwah. 💖✨🎀