1PORTABLECTL(1)                    portablectl                   PORTABLECTL(1)
2
3
4

NAME

6       portablectl - Attach, detach or inspect portable service images
7

SYNOPSIS

9       portablectl [OPTIONS...] {COMMAND} [NAME...]
10

DESCRIPTION

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
16       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
24       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
31       Specifically portable service images may be of the following kind:
32
33       ·   Directory trees containing an OS, including the top-level
34           directories /usr/, /etc/, and so on.
35
36       ·   btrfs subvolumes containing OS trees, similar to normal directory
37           trees.
38
39       ·   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

OPTIONS

44       The following options are understood:
45
46       -q, --quiet
47           Suppresses additional informational output while running.
48
49       -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
53       --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
65       --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
72       --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
77       --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
83       -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
93       -M, --machine=
94           Execute operation on a local container. Specify a container name to
95           connect to.
96
97       --no-pager
98           Do not pipe output into a pager.
99
100       --no-legend
101           Do not print the legend, i.e. column headers and the footer with
102           hints.
103
104       --no-ask-password
105           Do not query the user for authentication for privileged operations.
106
107       -h, --help
108           Print a short help text and exit.
109
110       --version
111           Print a short version string and exit.
112

COMMANDS

114       The following commands are understood:
115
116       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
125       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
134           When a portable service is attached four operations are executed:
135
136            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
144            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
150            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
155            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
160           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
178           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
183       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
193       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
208       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
213           Table 1. Image attachment states
214           ┌─────────────────┬────────────────────────────┐
215State            Description                
216           ├─────────────────┼────────────────────────────┤
217detached         │ The image is currently not │
218           │                 │ attached.                  │
219           ├─────────────────┼────────────────────────────┤
220attached         │ The image is currently     │
221           │                 │ attached, i.e. its unit    │
222           │                 │ files have been made       │
223           │                 │ available to the host      │
224           │                 │ system.                    │
225           ├─────────────────┼────────────────────────────┤
226attached-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           ├─────────────────┼────────────────────────────┤
233enabled          │ The image is currently     │
234           │                 │ attached, and at least one │
235           │                 │ unit file associated with  │
236           │                 │ it has been enabled.       │
237           ├─────────────────┼────────────────────────────┤
238enabled-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           ├─────────────────┼────────────────────────────┤
245running          │ The image is currently     │
246           │                 │ attached, and at least one │
247           │                 │ unit file associated with  │
248           │                 │ it is running.             │
249           ├─────────────────┼────────────────────────────┤
250running-runtime  │ The image is currently     │
251           │                 │ attached transiently, and  │
252           │                 │ at least one unit file     │
253           │                 │ associated with it is      │
254           │                 │ running.                   │
255           └─────────────────┴────────────────────────────┘
256
257       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
262       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
268       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
279           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

FILES AND DIRECTORIES

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
294       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

PROFILES

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
307       Table 2. Profiles
308       ┌──────────┬────────────────────────────┐
309Name      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
342       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

EXIT STATUS

347       On success, 0 is returned, a non-zero failure code otherwise.
348

ENVIRONMENT

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
359       $SYSTEMD_LESS
360           Override the options passed to less (by default "FRSXMK").
361
362           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
366       $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

SEE ALSO

371       systemd(1), systemd-portabled.service(8)
372
373
374
375systemd 241                                                     PORTABLECTL(1)
Impressum