systemd-escape

Escape the given text

$ systemd-escape [text]

$ systemd-escape [[-u|--unescape]] [text]

$ systemd-escape [[-p|--path]] [text]

$ systemd-escape --suffix [suffix] [text]

$ systemd-escape --template [template] [text]

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

-p, --path
    Escapes the input STRING for use in file system paths. This is useful when a unit name needs to be derived directly from a path.

-u, --unit
    Escapes the input STRING for use in systemd unit names. This is the default mode if neither --path nor --unit is specified and the input contains path separators.

--suffix=SUFFIX
    When escaping for a unit name, append the specified SUFFIX (e.g., '.service', '.mount') to the escaped string.

--template=TEMPLATE
    When escaping for a unit name, use the specified TEMPLATE unit name (e.g., 'getty@.service'). The escaped string will be inserted into the template.

--unescape
    Performs the reverse operation: unescapes the input STRING. This converts a systemd-escaped string back to its original form.

-h, --help
    Shows a short help text and exits.

--version
    Shows a short version string and exits.

systemd-escape is a utility command designed to escape or unescape strings for use in systemd unit names, paths, or other systemd-specific contexts. Systemd units often need to be dynamically generated or referenced based on arbitrary strings, such as file paths or network interface names. However, not all characters are valid within unit names or filenames, especially when using paths directly as unit identifiers. This command ensures that any problematic characters (like '/', ':', or spaces) are converted into a safe, unambiguous format that systemd can correctly interpret and reverse. It's particularly useful when creating instantiated unit files (e.g., service@.service) where the instance name is derived from a path or other string containing special characters. By providing an escaped string, systemd can reliably map it to a valid unit name or file path.

The escaping rules used by systemd-escape are specific to systemd's internal conventions and may differ significantly from other escaping mechanisms (e.g., URL encoding, shell escaping, JSON escaping). It should only be used for strings intended for systemd unit names or path components. Attempting to use this for general string escaping or for systems not managed by systemd will likely lead to incorrect results.

systemd-escape replaces characters that are not alphanumeric or '.', '-', '_' with C-style backslash escapes. For example, '/' becomes '\x2f', and a space becomes '\x20'. This ensures that the resulting string is valid for use as a filename or unit name and can be unambiguously reversed.

One common use case is creating 'template' units (e.g., systemd-escape --template='my-service@.service' /path/to/resource) which generate specific unit names like my-service@path-to-resource.service. This allows scripts to dynamically activate units based on external factors without manually managing complex escaping logic.

systemd-escape is an integral part of the systemd suite, which was initially released in 2010. Its necessity arose from systemd's design philosophy of allowing dynamic and flexible unit management, often tying unit names to real-world entities like file paths, mount points, or device names. To achieve this safely and reliably, a consistent method for converting arbitrary strings into valid, unique, and predictable unit identifiers was required, leading to the development of this dedicated escape utility.

systemctl(1), systemd.unit(5), systemd.path(5), systemd.service(8)