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