man/systemd-escape.1

   1 '\" t
   2 .TH "SYSTEMD\-ESCAPE" "1" "" "systemd 218" "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 system unit names
  24 .SH "SYNOPSIS"
  25 .HP \w'\fBsystemd\-escape\ \fR\fB[OPTIONS...]\fR\fB\ \fR\fB[STRING...]\fR\ 'u
  26 \fBsystemd\-escape \fR\fB[OPTIONS...]\fR\fB \fR\fB[STRING...]\fR
  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 the other\&. 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 a special mode of escaping is applied instead, which assumes a string to be already escaped but will escape everything that appears obviously non\-escaped\&.
  39 .SH "OPTIONS"
  40 .PP
  41 The following options are understood:
  42 .PP
  43 \fB\-\-suffix=\fR
  44 .RS 4
  45 Appends the specified unit type suffix to the escaped string\&. Takes one of the unit types supported by systemd, such as
  46 "\&.service"
  47 or
  48 "\&.mount"\&. May not be used in conjunction with
  49 \fB\-\-template=\fR,
  50 \fB\-\-unescape\fR
  51 or
  52 \fB\-\-mangle\fR\&.
  53 .RE
  54 .PP
  55 \fB\-\-template=\fR
  56 .RS 4
  57 Inserts the escaped strings in a unit name template\&. Takes a unit name template such as
  58 foobar@\&.service
  59 May not be used in conjunction with
  60 \fB\-\-suffix=\fR,
  61 \fB\-\-unescape\fR
  62 or
  63 \fB\-\-mangle\fR\&.
  64 .RE
  65 .PP
  66 \fB\-\-path\fR, \fB\-p\fR
  67 .RS 4
  68 When escaping or unescaping a string, assume it refers to a file system path\&. This enables special processing of the initial
  69 "/"
  70 of the path\&.
  71 .RE
  72 .PP
  73 \fB\-\-unescape\fR
  74 .RS 4
  75 Instead of escaping the specified strings, undo the escaping, reversing the operation\&. May not be used in conjunction with
  76 \fB\-\-suffix=\fR,
  77 \fB\-\-template=\fR
  78 or
  79 \fB\-\-mangle\fR\&.
  80 .RE
  81 .PP
  82 \fB\-\-mangle\fR
  83 .RS 4
  84 Like
  85 \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
  86 \fB\-\-suffix=\fR,
  87 \fB\-\-template=\fR
  88 or
  89 \fB\-\-unescape\fR\&.
  90 .RE
  91 .PP
  92 \fB\-h\fR, \fB\-\-help\fR
  93 .RS 4
  94 Print a short help text and exit\&.
  95 .RE
  96 .PP
  97 \fB\-\-version\fR
  98 .RS 4
  99 Print a short version string and exit\&.
 100 .RE
 101 .SH "EXAMPLES"
 102 .PP
 103 Escape a single string:
 104 .sp
 105 .if n \{\
 106 .RS 4
 107 .\}
 108 .nf
 109 $ systemd\-escape \*(AqHallöchen, Meister\*(Aq
 110 Hall\exc3\exb6chen\ex2c\ex20Meister
 111 .fi
 112 .if n \{\
 113 .RE
 114 .\}
 115 .PP
 116 To undo escaping on a single string:
 117 .sp
 118 .if n \{\
 119 .RS 4
 120 .\}
 121 .nf
 122 $ systemd\-escape \-u \*(AqHall\exc3\exb6chen\ex2c\ex20Meister\*(Aq
 123 Hallöchen, Meister
 124 .fi
 125 .if n \{\
 126 .RE
 127 .\}
 128 .PP
 129 To generate the mount unit for a path:
 130 .sp
 131 .if n \{\
 132 .RS 4
 133 .\}
 134 .nf
 135 $ systemd\-escape \-p \-\-suffix=mount "/tmp//waldi/foobar/"
 136 tmp\-waldi\-foobar\&.mount
 137 .fi
 138 .if n \{\
 139 .RE
 140 .\}
 141 .PP
 142 To generate instance names of three strings
 143 .sp
 144 .if n \{\
 145 .RS 4
 146 .\}
 147 .nf
 148 $ systemd\-escape \-\-template=systemd\-nspawn@\&.service \*(AqMy Container 1\*(Aq \*(Aqcontainerb\*(Aq \*(Aqcontainer/III\*(Aq
 149 systemd\-nspawn@My\ex20Container\ex201\&.service systemd\-nspawn@containerb\&.service systemd\-nspawn@container\-III\&.service
 150 .fi
 151 .if n \{\
 152 .RE
 153 .\}
 154 .SH "EXIT STATUS"
 155 .PP
 156 On success, 0 is returned, a non\-zero failure code otherwise\&.
 157 .SH "SEE ALSO"
 158 .PP
 159 \fBsystemd\fR(1),
 160 \fBsystemctl\fR(1)