1PORTABLECTL(1) portablectl PORTABLECTL(1)
2
6 portablectl - Attach, detach or inspect portable service images
7
9 portablectl [OPTIONS...] {COMMAND} [NAME...]
10
12 portablectl may be used to attach, detach or inspect portable service
13 images. It's primarily a command interfacing with systemd-
14 portabled.service(8).
15 Portable service images contain an OS file system tree along with
17 systemd(1) unit file information. A service image may be "attached" to
18 the local system. If attached, a set of unit files are copied from the
19 image to the host, and extended with RootDirectory= or RootImage=
20 assignments (in case of service units) pointing to the image file or
21 directory, ensuring the services will run within the file system
22 context of the image.
23 Portable service images are an efficient way to bundle multiple related
25 services and other units together, and transfer them as a whole between
26 systems. When these images are attached the local system the contained
27 units may run in most ways like regular system-provided units, either
28 with full privileges or inside strict sandboxing, depending on the
29 selected configuration.
30 Specifically portable service images may be of the following kind:
32 · Directory trees containing an OS, including the top-level
34 directories /usr/, /etc/, and so on.
35 · btrfs subvolumes containing OS trees, similar to normal directory
37 trees.
38 · Binary "raw" disk images containing MBR or GPT partition tables and
40 Linux file system partitions. (These must be regular files, with
41 the .raw suffix.)
42
44 The following options are understood:
45 -q, --quiet
47 Suppresses additional informational output while running.
48 -p PROFILE, --profile=PROFILE
50 When attaching an image, select the profile to use. By default the
51 "default" profile is used. For details about profiles, see below.
52 --copy=
54 When attaching an image, select whether to prefer copying or
55 symlinking of files installed into the host system. Takes one of
56 "copy" (to prefer copying of files), "symlink" (to prefer creation
57 of symbolic links) or "auto" for an intermediary mode where
58 security profile drop-ins are symlinked while unit files are
59 copied. Note that this option expresses a preference only, in cases
60 where symbolic links cannot be created — for example when the image
61 operated on is a raw disk image, and hence not directly
62 referentiable from the host file system — copying of files is used
63 unconditionally.
64 --runtime
66 When specified the unit and drop-in files are placed in
67 /run/systemd/system.attached/ instead of
68 /etc/systemd/system.attached/. Images attached with this option set
69 hence remain attached only until the next reboot, while they are
70 normally attached persistently.
71 --no-reload
73 Don't reload the service manager after attaching or detaching a
74 portable service image. Normally the service manager is reloaded to
75 ensure it is aware of added or removed unit files.
76 --cat
78 When inspecting portable service images, show the (unprocessed)
79 contents of the metadata files pulled from the image, instead of
80 brief summaries. Specifically, this will show the os-release(5) and
81 unit file contents of the image.
82 -H, --host=
84 Execute the operation remotely. Specify a hostname, or a username
85 and hostname separated by "@", to connect to. The hostname may
86 optionally be suffixed by a port ssh is listening on, seperated by
87 ":", and then a container name, separated by "/", which connects
88 directly to a specific container on the specified host. This will
89 use SSH to talk to the remote machine manager instance. Container
90 names may be enumerated with machinectl -H HOST. Put IPv6 addresses
91 in brackets.
92 -M, --machine=
94 Execute operation on a local container. Specify a container name to
95 connect to.
96 --no-pager
98 Do not pipe output into a pager.
99 --no-legend
101 Do not print the legend, i.e. column headers and the footer with
102 hints.
103 --no-ask-password
105 Do not query the user for authentication for privileged operations.
106 -h, --help
108 Print a short help text and exit.
109 --version
111 Print a short version string and exit.
112
114 The following commands are understood:
115 list
117 List available portable service images. This will list all portable
118 service images discovered in the portable image search paths (see
119 below), along with brief metadata and state information. Note that
120 many of the commands below may both operate on images inside and
121 outside of the search paths. This command is hence mostly a
122 convenience option, the commands are generally not restricted to
123 what this list shows.
124 attach IMAGE [PREFIX...]
126 Attach a portable service image to the host system. Expects a file
127 system path to a portable service image file or directory as first
128 argument. If the specified path contains no slash character ("/")
129 it is understood as image filename that is searched for in the
130 portable service image search paths (see below). To reference a
131 file in the current working directory prefix the filename with "./"
132 to avoid this search path logic.
133 When a portable service is attached four operations are executed:
135 1. All unit files of types .service, .socket, .target, .timer and
137 .path which match the indicated unit file name prefix are
138 copied from the image to the host's
139 /etc/systemd/system.attached/ directory (or
140 /run/systemd/system.attached/ — depending whether --runtime is
141 specified, see above), which is included in the built-in unit
142 search path of the system service manager.
143 2. For unit files of type .service a drop-in is added to these
145 copies that adds RootDirectory= or RootImage= settings (see
146 systemd.unit(5) for details), that ensures these services are
147 run within the file system of the originating portable service
148 image.
149 3. A second drop-in is created: the "profile" drop-in, that may
151 contain additional security settings (and other settings). A
152 number of profiles are available by default but administrators
153 may define their own ones. See below.
154 4. If the portable service image file is not already in the search
156 path (see below), a symbolic link to it is created in
157 /etc/portables/ or /run/portables/, to make sure it is included
158 in it.
159 By default all unit files whose names start with a prefix generated
161 from the image's file name are copied out. Specifically, the prefix
162 is determined from the image file name with any suffix such as .raw
163 removed, truncated at the first occurrence of and underscore
164 character ("_"), if there is one. The underscore logic is supposed
165 to be used to versioning so that the an image file foobar_47.11.raw
166 will result in a unit file matching prefix of foobar. This prefix
167 is then compared with all unit files names contained in the image
168 in the usual directories, but only unit file names where the prefix
169 is followed by "-", "." or "@" are considered. Example: if a
170 portable service image file is named foobar_47.11.raw then by
171 default all its unit files with names such as
172 foobar-quux-waldi.service, foobar.service or foobar@.service will
173 be considered. It's possible to override the matching prefix: all
174 strings listed on the command line after the image file name are
175 considered prefixes, overriding the implicit logic where the prefix
176 is derived from the image file name.
177 By default, after the unit files are attached the service manager's
179 configuration is reloaded, except when --no-reload is specified
180 (see above). This ensures that the new units made available to the
181 service manager are seen by it.
182 detach IMAGE
184 Detaches a portable service image from the host. This undoes the
185 operations executed by the attach command above, and removes the
186 unit file copies, drop-ins and image symlink again. This command
187 expects an image name or path as parameter. Note that if a path is
188 specified only the last component of it (i.e. the file or directory
189 name itself, not the path to it) is used for finding matching unit
190 files. This is a convencience feature to allow all arguments passed
191 as attach also to detach.
192 inspect IMAGE [PREFIX...]
194 Extracts various metadata from a portable service image and
195 presents it to the caller. Specifically, the os-release(5) file of
196 the image is retrieved as well as all matching unit files. By
197 default a short summary showing the most relevant metadata in
198 combination with a list of matching unit files is shown (that is
199 the unit files attach would install to the host system). If
200 combined with --cat (see above), the os-release data and the units
201 files' contents is displayed unprocessed. This command is useful to
202 determine whether an image qualifies as portable service image, and
203 which unit files are included. This command expects the path to the
204 image as parameter, optionally followed by a list of unit file
205 prefixes to consider, similar to the attach command described
206 above.
207 is-attached IMAGE
209 Determines whether the specified image is currently attached or
210 not. Unless combined with the --quiet switch this will show a short
211 state identifier for the image. Specifically:
212 Table 1. Image attachment states
214 ┌─────────────────┬────────────────────────────┐
215 │State │ Description │
216 ├─────────────────┼────────────────────────────┤
217 │detached │ The image is currently not │
218 │ │ attached. │
219 ├─────────────────┼────────────────────────────┤
220 │attached │ The image is currently │
221 │ │ attached, i.e. its unit │
222 │ │ files have been made │
223 │ │ available to the host │
224 │ │ system. │
225 ├─────────────────┼────────────────────────────┤
226 │attached-runtime │ Like attached, but the │
227 │ │ unit files have been made │
228 │ │ available transiently │
229 │ │ only, i.e. the attach │
230 │ │ command has been invoked │
231 │ │ with the --runtime option. │
232 ├─────────────────┼────────────────────────────┤
233 │enabled │ The image is currently │
234 │ │ attached, and at least one │
235 │ │ unit file associated with │
236 │ │ it has been enabled. │
237 ├─────────────────┼────────────────────────────┤
238 │enabled-runtime │ Like enabled, but the the │
239 │ │ unit files have been made │
240 │ │ available transiently │
241 │ │ only, i.e. the attach │
242 │ │ command has been invoked │
243 │ │ with the --runtime option. │
244 ├─────────────────┼────────────────────────────┤
245 │running │ The image is currently │
246 │ │ attached, and at least one │
247 │ │ unit file associated with │
248 │ │ it is running. │
249 ├─────────────────┼────────────────────────────┤
250 │running-runtime │ The image is currently │
251 │ │ attached transiently, and │
252 │ │ at least one unit file │
253 │ │ associated with it is │
254 │ │ running. │
255 └─────────────────┴────────────────────────────┘
256 read-only IMAGE [BOOL]
258 Marks or (unmarks) a portable service image read-only. Takes an
259 image name, followed by a boolean as arguments. If the boolean is
260 omitted, positive is implied, i.e. the image is marked read-only.
261 remove IMAGE...
263 Removes one or more portable service images. Note that this command
264 will only remove the specified image path itself — it refers to a
265 symbolic link then the symbolic link is removed and not the image
266 it points to.
267 set-limit [IMAGE] BYTES
269 Sets the maximum size in bytes that a specific portable service
270 image, or all images, may grow up to on disk (disk quota). Takes
271 either one or two parameters. The first, optional parameter refers
272 to a portable service image name. If specified, the size limit of
273 the specified image is changed. If omitted, the overall size limit
274 of the sum of all images stored locally is changed. The final
275 argument specifies the size limit in bytes, possibly suffixed by
276 the usual K, M, G, T units. If the size limit shall be disabled,
277 specify "-" as size.
278 Note that per-image size limits are only supported on btrfs file
280 systems. Also, depending on BindPaths= settings in the portable
281 service's unit files directories from the host might be visible in
282 the image environment during runtime which are not affected by this
283 setting, as only the image itself is counted against this limit.
284
286 Portable service images are preferably stored in /var/lib/portables/,
287 but are also searched for in /etc/portables/, /run/systemd/portables/,
288 /usr/local/lib/portables/ and /usr/lib/portables/. It's recommended not
289 to place image files directly in /etc/portables/ or
290 /run/systemd/portables/ (as these are generally not suitable for
291 storing large or non-textual data), but use these directories only for
292 linking images located elsewhere into the image search path.
293 When a portable service image is attached, matching unit files are
295 copied onto the host into the /etc/systemd/system.attached/ and
296 /run/systemd/system.attached/ directories. When an image is detached,
297 the unit files are removed again from these directories.
298
300 When portable service images are attached a "profile" drop-in is linked
301 in, which may be used to enforce additional security (and other)
302 restrictions locally. Four profile drop-ins are defined by default, and
303 shipped in /usr/lib/systemd/portable/profile/. Additional, local
304 profiles may be defined by placing them in
305 /etc/systemd/portable/profile/. The default profiles are:
306 Table 2. Profiles
308 ┌──────────┬────────────────────────────┐
309 │Name │ Description │
310 ├──────────┼────────────────────────────┤
311 │default │ This is the default │
312 │ │ profile if no other │
313 │ │ profile name is set via │
314 │ │ the --profile= (see │
315 │ │ above). It's fairly │
316 │ │ restrictive, but should be │
317 │ │ useful for common, │
318 │ │ unprivileged system │
319 │ │ workloads. This includes │
320 │ │ write access to the │
321 │ │ logging framework, as well │
322 │ │ as IPC access to the D-Bus │
323 │ │ system. │
324 ├──────────┼────────────────────────────┤
325 │nonetwork │ Very similar to default, │
326 │ │ but networking is turned │
327 │ │ off for any services of │
328 │ │ the portable service │
329 │ │ image. │
330 ├──────────┼────────────────────────────┤
331 │strict │ A profile with very strict │
332 │ │ settings. This profile │
333 │ │ excludes IPC (D-Bus) and │
334 │ │ network access. │
335 ├──────────┼────────────────────────────┤
336 │trusted │ A profile with very │
337 │ │ relaxed settings. In this │
338 │ │ profile the services run │
339 │ │ with full privileges. │
340 └──────────┴────────────────────────────┘
341 For details on this profiles, and their effects please have a look at
343 their precise definitions, e.g.
344 /usr/lib/systemd/portable/profile/default/service.conf and similar.
345
347 On success, 0 is returned, a non-zero failure code otherwise.
348
350 $SYSTEMD_PAGER
351 Pager to use when --no-pager is not given; overrides $PAGER. If
352 neither $SYSTEMD_PAGER nor $PAGER are set, a set of well-known
353 pager implementations are tried in turn, including less(1) and
354 more(1), until one is found. If no pager implementation is
355 discovered no pager is invoked. Setting this environment variable
356 to an empty string or the value "cat" is equivalent to passing
357 --no-pager.
358 $SYSTEMD_LESS
360 Override the options passed to less (by default "FRSXMK").
361 If the value of $SYSTEMD_LESS does not include "K", and the pager
363 that is invoked is less, Ctrl+C will be ignored by the executable.
364 This allows less to handle Ctrl+C itself.
365 $SYSTEMD_LESSCHARSET
367 Override the charset passed to less (by default "utf-8", if the
368 invoking terminal is determined to be UTF-8 compatible).
369
371 systemd(1), systemd-portabled.service(8)
372systemd 241 PORTABLECTL(1)