]>
Commit | Line | Data |
---|---|---|
514094f9 | 1 | <?xml version='1.0'?> |
3a54a157 | 2 | <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" |
eea10b26 | 3 | "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> |
db9ecf05 | 4 | <!-- SPDX-License-Identifier: LGPL-2.1-or-later --> |
a8c42bb8 LP |
5 | |
6 | <refentry id="portablectl" conditional='ENABLE_PORTABLED' | |
7 | xmlns:xi="http://www.w3.org/2001/XInclude"> | |
8 | ||
9 | <refentryinfo> | |
10 | <title>portablectl</title> | |
11 | <productname>systemd</productname> | |
a8c42bb8 LP |
12 | </refentryinfo> |
13 | ||
14 | <refmeta> | |
15 | <refentrytitle>portablectl</refentrytitle> | |
16 | <manvolnum>1</manvolnum> | |
17 | </refmeta> | |
18 | ||
19 | <refnamediv> | |
20 | <refname>portablectl</refname> | |
21 | <refpurpose>Attach, detach or inspect portable service images</refpurpose> | |
22 | </refnamediv> | |
23 | ||
24 | <refsynopsisdiv> | |
25 | <cmdsynopsis> | |
26 | <command>portablectl</command> | |
27 | <arg choice="opt" rep="repeat">OPTIONS</arg> | |
28 | <arg choice="req">COMMAND</arg> | |
29 | <arg choice="opt" rep="repeat">NAME</arg> | |
30 | </cmdsynopsis> | |
31 | </refsynopsisdiv> | |
32 | ||
33 | <refsect1> | |
34 | <title>Description</title> | |
35 | ||
36 | <para><command>portablectl</command> may be used to attach, detach or inspect portable service images. It's | |
37 | primarily a command interfacing with | |
38 | <citerefentry><refentrytitle>systemd-portabled.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> | |
39 | ||
40 | <para>Portable service images contain an OS file system tree along with | |
41 | <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> unit file | |
42 | information. A service image may be "attached" to the local system. If attached, a set of unit files are copied | |
43 | from the image to the host, and extended with <varname>RootDirectory=</varname> or <varname>RootImage=</varname> | |
44 | assignments (in case of service units) pointing to the image file or directory, ensuring the services will run | |
45 | within the file system context of the image.</para> | |
46 | ||
47 | <para>Portable service images are an efficient way to bundle multiple related services and other units together, | |
c959e178 | 48 | and transfer them as a whole between systems. When these images are attached to the local system, the contained units |
a8c42bb8 | 49 | may run in most ways like regular system-provided units, either with full privileges or inside strict sandboxing, |
e91aa2ea | 50 | depending on the selected configuration. For more details, see |
8b9f0921 | 51 | <ulink url="https://systemd.io/PORTABLE_SERVICES">Portable Services Documentation</ulink>.</para> |
a8c42bb8 | 52 | |
c959e178 | 53 | <para>Portable service images may be of the following kinds:</para> |
a8c42bb8 LP |
54 | |
55 | <itemizedlist> | |
56 | <listitem><para>Directory trees containing an OS, including the top-level directories <filename>/usr/</filename>, | |
57 | <filename>/etc/</filename>, and so on.</para></listitem> | |
58 | ||
59 | <listitem><para>btrfs subvolumes containing OS trees, similar to normal directory trees.</para></listitem> | |
60 | ||
61 | <listitem><para>Binary "raw" disk images containing MBR or GPT partition tables and Linux file system | |
787dfb82 | 62 | partitions. (These must be regular files, with the <filename>.raw</filename> suffix.)</para></listitem> |
a8c42bb8 LP |
63 | </itemizedlist> |
64 | ||
65 | </refsect1> | |
66 | ||
a8c42bb8 LP |
67 | <refsect1> |
68 | <title>Commands</title> | |
69 | ||
70 | <para>The following commands are understood:</para> | |
71 | ||
72 | <variablelist> | |
73 | ||
74 | <varlistentry> | |
75 | <term><command>list</command></term> | |
76 | ||
77 | <listitem><para>List available portable service images. This will list all portable service images discovered | |
78 | in the portable image search paths (see below), along with brief metadata and state information. Note that many | |
79 | of the commands below may both operate on images inside and outside of the search paths. This command is hence | |
80 | mostly a convenience option, the commands are generally not restricted to what this list | |
ec07c3c8 AK |
81 | shows.</para> |
82 | ||
83 | <xi:include href="version-info.xml" xpointer="v239"/></listitem> | |
a8c42bb8 LP |
84 | </varlistentry> |
85 | ||
86 | <varlistentry> | |
87 | <term><command>attach</command> <replaceable>IMAGE</replaceable> [<replaceable>PREFIX…</replaceable>]</term> | |
88 | ||
89 | <listitem><para>Attach a portable service image to the host system. Expects a file system path to a portable | |
90 | service image file or directory as first argument. If the specified path contains no slash character | |
91 | (<literal>/</literal>) it is understood as image filename that is searched for in the portable service image | |
92 | search paths (see below). To reference a file in the current working directory prefix the filename with | |
93 | <literal>./</literal> to avoid this search path logic.</para> | |
94 | ||
95 | <para>When a portable service is attached four operations are executed:</para> | |
96 | ||
97 | <orderedlist> | |
98 | ||
99 | <listitem><para>All unit files of types <filename>.service</filename>, <filename>.socket</filename>, | |
100 | <filename>.target</filename>, <filename>.timer</filename> and <filename>.path</filename> which match the | |
101 | indicated unit file name prefix are copied from the image to the host's | |
83f72cd6 LP |
102 | <filename>/etc/systemd/system.attached/</filename> directory (or |
103 | <filename>/run/systemd/system.attached/</filename> — depending whether <option>--runtime</option> is | |
b5f8a35f | 104 | specified, see below), which is included in the built-in unit search path of the system service |
83f72cd6 | 105 | manager.</para></listitem> |
a8c42bb8 LP |
106 | |
107 | <listitem><para>For unit files of type <filename>.service</filename> a drop-in is added to these copies that | |
108 | adds <varname>RootDirectory=</varname> or <varname>RootImage=</varname> settings (see | |
109 | <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> for | |
110 | details), that ensures these services are run within the file system of the originating portable service | |
111 | image.</para></listitem> | |
112 | ||
113 | <listitem><para>A second drop-in is created: the "profile" drop-in, that may contain additional security | |
114 | settings (and other settings). A number of profiles are available by default but administrators may define | |
115 | their own ones. See below.</para></listitem> | |
116 | ||
117 | <listitem><para>If the portable service image file is not already in the search path (see below), a symbolic | |
118 | link to it is created in <filename>/etc/portables/</filename> or | |
119 | <filename>/run/portables/</filename>, to make sure it is included in it.</para></listitem> | |
120 | </orderedlist> | |
121 | ||
122 | <para>By default all unit files whose names start with a prefix generated from the image's file name are copied | |
123 | out. Specifically, the prefix is determined from the image file name with any suffix such as | |
e9dd6984 | 124 | <filename>.raw</filename> removed, truncated at the first occurrence of an underscore character |
a8c42bb8 LP |
125 | (<literal>_</literal>), if there is one. The underscore logic is supposed to be used to versioning so that the |
126 | an image file <filename>foobar_47.11.raw</filename> will result in a unit file matching prefix of | |
127 | <filename>foobar</filename>. This prefix is then compared with all unit files names contained in the image in | |
128 | the usual directories, but only unit file names where the prefix is followed by <literal>-</literal>, | |
129 | <literal>.</literal> or <literal>@</literal> are considered. Example: if a portable service image file is named | |
130 | <filename>foobar_47.11.raw</filename> then by default all its unit files with names such as | |
131 | <filename>foobar-quux-waldi.service</filename>, <filename>foobar.service</filename> or | |
132 | <filename>foobar@.service</filename> will be considered. It's possible to override the matching prefix: all | |
133 | strings listed on the command line after the image file name are considered prefixes, overriding the implicit | |
134 | logic where the prefix is derived from the image file name.</para> | |
135 | ||
136 | <para>By default, after the unit files are attached the service manager's configuration is reloaded, except | |
b5f8a35f | 137 | when <option>--no-reload</option> is specified (see below). This ensures that the new units made available to |
a8c42bb8 | 138 | the service manager are seen by it.</para> |
e2c1ddcc | 139 | |
0923b425 | 140 | <para>If <option>--now</option> and/or <option>--enable</option> are passed, the portable services are |
31c33315 LB |
141 | immediately started (blocking operation unless <option>--no-block</option> is passed) and/or enabled after |
142 | attaching the image.</para> | |
ec07c3c8 | 143 | |
8257508c LB |
144 | <xi:include href="vpick.xml" xpointer="image"/> |
145 | <xi:include href="vpick.xml" xpointer="directory"/> | |
ec07c3c8 | 146 | <xi:include href="version-info.xml" xpointer="v239"/> |
a8c42bb8 LP |
147 | </listitem> |
148 | </varlistentry> | |
149 | ||
150 | <varlistentry> | |
e2c1ddcc | 151 | <term><command>detach</command> <replaceable>IMAGE</replaceable> [<replaceable>PREFIX…</replaceable>]</term> |
a8c42bb8 LP |
152 | |
153 | <listitem><para>Detaches a portable service image from the host. This undoes the operations executed by the | |
154 | <command>attach</command> command above, and removes the unit file copies, drop-ins and image symlink | |
155 | again. This command expects an image name or path as parameter. Note that if a path is specified only the last | |
156 | component of it (i.e. the file or directory name itself, not the path to it) is used for finding matching unit | |
5e2b0e1c | 157 | files. This is a convenience feature to allow all arguments passed as <command>attach</command> also to |
ec07c3c8 AK |
158 | <command>detach</command>.</para> |
159 | ||
0923b425 | 160 | <para>If <option>--now</option> and/or <option>--enable</option> are passed, the portable services are |
31c33315 LB |
161 | immediately stopped (blocking operation) and/or disabled before detaching the image. Prefix(es) are also accepted, |
162 | to be used in case the unit names do not match the image name as described in the <command>attach</command>.</para> | |
d9655d11 DT |
163 | |
164 | <xi:include href="version-info.xml" xpointer="v239"/></listitem> | |
a8c42bb8 LP |
165 | </varlistentry> |
166 | ||
e26fe5f9 LB |
167 | <varlistentry> |
168 | <term><command>reattach</command> <replaceable>IMAGE</replaceable> [<replaceable>PREFIX…</replaceable>]</term> | |
169 | ||
170 | <listitem><para>Detaches an existing portable service image from the host, and immediately attaches it again. | |
171 | This is useful in case the image was replaced. Running units are not stopped during the process. Partial matching, | |
172 | to allow for different versions in the image name, is allowed: only the part before the first <literal>_</literal> | |
173 | character has to match. If the new image doesn't exist, the existing one will not be detached. The parameters | |
ec07c3c8 AK |
174 | follow the same syntax as the <command>attach</command> command.</para> |
175 | ||
0923b425 | 176 | <para>If <option>--now</option> and/or <option>--enable</option> are passed, the portable services are |
e26fe5f9 LB |
177 | immediately stopped if removed, started and/or enabled if added, or restarted if updated. Prefixes are also |
178 | accepted, in the same way as described in the <command>attach</command> case.</para> | |
d9655d11 DT |
179 | |
180 | <xi:include href="version-info.xml" xpointer="v248"/></listitem> | |
e26fe5f9 LB |
181 | </varlistentry> |
182 | ||
a8c42bb8 LP |
183 | <varlistentry> |
184 | <term><command>inspect</command> <replaceable>IMAGE</replaceable> [<replaceable>PREFIX…</replaceable>]</term> | |
185 | ||
186 | <listitem><para>Extracts various metadata from a portable service image and presents it to the | |
187 | caller. Specifically, the | |
188 | <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry> file of the | |
189 | image is retrieved as well as all matching unit files. By default a short summary showing the most relevant | |
190 | metadata in combination with a list of matching unit files is shown (that is the unit files | |
191 | <command>attach</command> would install to the host system). If combined with <option>--cat</option> (see | |
192 | above), the <filename>os-release</filename> data and the units files' contents is displayed unprocessed. This | |
193 | command is useful to determine whether an image qualifies as portable service image, and which unit files are | |
194 | included. This command expects the path to the image as parameter, optionally followed by a list of unit file | |
195 | prefixes to consider, similar to the <command>attach</command> command described above.</para> | |
ec07c3c8 AK |
196 | |
197 | <xi:include href="version-info.xml" xpointer="v239"/> | |
a8c42bb8 LP |
198 | </listitem> |
199 | </varlistentry> | |
200 | ||
201 | <varlistentry> | |
202 | <term><command>is-attached</command> <replaceable>IMAGE</replaceable></term> | |
203 | ||
204 | <listitem><para>Determines whether the specified image is currently attached or not. Unless combined with the | |
205 | <option>--quiet</option> switch this will show a short state identifier for the image. Specifically:</para> | |
206 | ||
207 | <table> | |
208 | <title>Image attachment states</title> | |
209 | <tgroup cols='2'> | |
210 | <colspec colname='state'/> | |
211 | <colspec colname='description'/> | |
212 | <thead> | |
213 | <row> | |
214 | <entry>State</entry> | |
215 | <entry>Description</entry> | |
216 | </row> | |
217 | </thead> | |
218 | <tbody> | |
219 | <row> | |
220 | <entry><option>detached</option></entry> | |
221 | <entry>The image is currently not attached.</entry> | |
222 | </row> | |
223 | <row> | |
224 | <entry><option>attached</option></entry> | |
225 | <entry>The image is currently attached, i.e. its unit files have been made available to the host system.</entry> | |
226 | </row> | |
227 | <row> | |
228 | <entry><option>attached-runtime</option></entry> | |
1b2ad5d9 | 229 | <entry>Like <option>attached</option>, but the unit files have been made available transiently only, i.e. the <command>attach</command> command has been invoked with the <option>--runtime</option> option.</entry> |
a8c42bb8 LP |
230 | </row> |
231 | <row> | |
232 | <entry><option>enabled</option></entry> | |
233 | <entry>The image is currently attached, and at least one unit file associated with it has been enabled.</entry> | |
234 | </row> | |
235 | <row> | |
236 | <entry><option>enabled-runtime</option></entry> | |
f32d15b0 | 237 | <entry>Like <option>enabled</option>, but the unit files have been made available transiently only, i.e. the <command>attach</command> command has been invoked with the <option>--runtime</option> option.</entry> |
a8c42bb8 LP |
238 | </row> |
239 | <row> | |
240 | <entry><option>running</option></entry> | |
241 | <entry>The image is currently attached, and at least one unit file associated with it is running.</entry> | |
242 | </row> | |
243 | <row> | |
244 | <entry><option>running-runtime</option></entry> | |
245 | <entry>The image is currently attached transiently, and at least one unit file associated with it is running.</entry> | |
246 | </row> | |
247 | </tbody> | |
248 | </tgroup> | |
249 | </table> | |
250 | ||
ec07c3c8 AK |
251 | <xi:include href="version-info.xml" xpointer="v239"/> |
252 | ||
a8c42bb8 LP |
253 | </listitem> |
254 | </varlistentry> | |
255 | ||
256 | <varlistentry> | |
257 | <term><command>read-only</command> <replaceable>IMAGE</replaceable> [<replaceable>BOOL</replaceable>]</term> | |
258 | ||
259 | <listitem><para>Marks or (unmarks) a portable service image read-only. Takes an image name, followed by a | |
260 | boolean as arguments. If the boolean is omitted, positive is implied, i.e. the image is marked | |
ec07c3c8 AK |
261 | read-only.</para> |
262 | ||
263 | <xi:include href="version-info.xml" xpointer="v239"/></listitem> | |
a8c42bb8 LP |
264 | </varlistentry> |
265 | ||
266 | <varlistentry> | |
267 | <term><command>remove</command> <replaceable>IMAGE</replaceable>…</term> | |
268 | ||
269 | <listitem><para>Removes one or more portable service images. Note that this command will only remove the | |
1b2ad5d9 | 270 | specified image path itself — it refers to a symbolic link then the symbolic link is removed and not the |
ec07c3c8 AK |
271 | image it points to.</para> |
272 | ||
273 | <xi:include href="version-info.xml" xpointer="v239"/></listitem> | |
a8c42bb8 LP |
274 | </varlistentry> |
275 | ||
276 | <varlistentry> | |
c2b67dc6 | 277 | <term><command>set-limit</command> [<replaceable>IMAGE</replaceable>] <replaceable>BYTES</replaceable></term> |
a8c42bb8 LP |
278 | |
279 | <listitem><para>Sets the maximum size in bytes that a specific portable service image, or all images, may grow | |
280 | up to on disk (disk quota). Takes either one or two parameters. The first, optional parameter refers to a | |
281 | portable service image name. If specified, the size limit of the specified image is changed. If omitted, the | |
282 | overall size limit of the sum of all images stored locally is changed. The final argument specifies the size | |
283 | limit in bytes, possibly suffixed by the usual K, M, G, T units. If the size limit shall be disabled, specify | |
284 | <literal>-</literal> as size.</para> | |
285 | ||
286 | <para>Note that per-image size limits are only supported on btrfs file systems. Also, depending on | |
287 | <varname>BindPaths=</varname> settings in the portable service's unit files directories from the host might be | |
288 | visible in the image environment during runtime which are not affected by this setting, as only the image | |
ec07c3c8 AK |
289 | itself is counted against this limit.</para> |
290 | ||
291 | <xi:include href="version-info.xml" xpointer="v239"/></listitem> | |
a8c42bb8 LP |
292 | </varlistentry> |
293 | ||
294 | </variablelist> | |
295 | ||
296 | </refsect1> | |
297 | ||
e1fac8a6 ZJS |
298 | <refsect1> |
299 | <title>Options</title> | |
300 | ||
301 | <para>The following options are understood:</para> | |
302 | ||
303 | <variablelist> | |
304 | <varlistentry> | |
305 | <term><option>-q</option></term> | |
306 | <term><option>--quiet</option></term> | |
307 | ||
ec07c3c8 AK |
308 | <listitem><para>Suppresses additional informational output while running.</para> |
309 | ||
310 | <xi:include href="version-info.xml" xpointer="v239"/></listitem> | |
e1fac8a6 ZJS |
311 | </varlistentry> |
312 | ||
313 | <varlistentry> | |
314 | <term><option>-p</option> <replaceable>PROFILE</replaceable></term> | |
9bfabe14 | 315 | <term><option>--profile=<replaceable>PROFILE</replaceable></option></term> |
e1fac8a6 ZJS |
316 | |
317 | <listitem><para>When attaching an image, select the profile to use. By default the <literal>default</literal> | |
ec07c3c8 AK |
318 | profile is used. For details about profiles, see below.</para> |
319 | ||
320 | <xi:include href="version-info.xml" xpointer="v239"/></listitem> | |
e1fac8a6 ZJS |
321 | </varlistentry> |
322 | ||
323 | <varlistentry> | |
324 | <term><option>--copy=</option></term> | |
325 | ||
82047a6a LB |
326 | <listitem><para>When attaching an image, select whether to prefer copying or symlinking of files |
327 | installed into the host system. Takes one of <literal>copy</literal> (files will be copied), | |
328 | <literal>symlink</literal> (to prefer creation of symbolic links), <literal>auto</literal> for an | |
329 | intermediary mode where security profile drop-ins and images are symlinked while unit files are | |
330 | copied, or <literal>mixed</literal> (since v256) where security profile drop-ins are symlinked while | |
331 | unit files and images are copied. Note that this option expresses a preference only, in cases where | |
332 | symbolic links cannot be created — for example when the image operated on is a raw disk image, and | |
333 | hence not directly referentiable from the host file system — copying of files is used | |
ec07c3c8 AK |
334 | unconditionally.</para> |
335 | ||
336 | <xi:include href="version-info.xml" xpointer="v239"/></listitem> | |
e1fac8a6 ZJS |
337 | </varlistentry> |
338 | ||
339 | <varlistentry> | |
340 | <term><option>--runtime</option></term> | |
341 | ||
342 | <listitem><para>When specified the unit and drop-in files are placed in | |
343 | <filename>/run/systemd/system.attached/</filename> instead of | |
344 | <filename>/etc/systemd/system.attached/</filename>. Images attached with this option set hence remain attached | |
ec07c3c8 AK |
345 | only until the next reboot, while they are normally attached persistently.</para> |
346 | ||
347 | <xi:include href="version-info.xml" xpointer="v239"/></listitem> | |
e1fac8a6 ZJS |
348 | </varlistentry> |
349 | ||
350 | <varlistentry> | |
351 | <term><option>--no-reload</option></term> | |
352 | ||
353 | <listitem><para>Don't reload the service manager after attaching or detaching a portable service | |
354 | image. Normally the service manager is reloaded to ensure it is aware of added or removed unit | |
ec07c3c8 AK |
355 | files.</para> |
356 | ||
357 | <xi:include href="version-info.xml" xpointer="v239"/></listitem> | |
e1fac8a6 ZJS |
358 | </varlistentry> |
359 | ||
360 | <varlistentry> | |
361 | <term><option>--cat</option></term> | |
362 | ||
363 | <listitem><para>When inspecting portable service images, show the (unprocessed) contents of the metadata files | |
364 | pulled from the image, instead of brief summaries. Specifically, this will show the | |
365 | <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry> and unit file | |
ec07c3c8 AK |
366 | contents of the image.</para> |
367 | ||
368 | <xi:include href="version-info.xml" xpointer="v239"/></listitem> | |
e1fac8a6 ZJS |
369 | </varlistentry> |
370 | ||
e2c1ddcc LB |
371 | <varlistentry> |
372 | <term><option>--enable</option></term> | |
373 | ||
ec07c3c8 AK |
374 | <listitem><para>Immediately enable/disable the portable service after attaching/detaching.</para> |
375 | ||
376 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
e2c1ddcc LB |
377 | </varlistentry> |
378 | ||
379 | <varlistentry> | |
380 | <term><option>--now</option></term> | |
381 | ||
e26fe5f9 | 382 | <listitem><para>Immediately start/stop/restart the portable service after attaching/before |
ec07c3c8 AK |
383 | detaching/after upgrading.</para> |
384 | ||
385 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
e2c1ddcc LB |
386 | </varlistentry> |
387 | ||
31c33315 LB |
388 | <varlistentry> |
389 | <term><option>--no-block</option></term> | |
390 | ||
ec07c3c8 AK |
391 | <listitem><para>Don't block waiting for attach --now to complete.</para> |
392 | ||
393 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
31c33315 LB |
394 | </varlistentry> |
395 | ||
966d7977 LB |
396 | <varlistentry> |
397 | <term><option>--clean</option></term> | |
398 | ||
399 | <listitem><para>When detaching ensure the configuration, state, logs, cache, and runtime data | |
400 | directories of the portable service are removed from the host system.</para> | |
401 | ||
402 | <xi:include href="version-info.xml" xpointer="v256"/></listitem> | |
403 | </varlistentry> | |
404 | ||
907952bb | 405 | <varlistentry> |
9bfabe14 | 406 | <term><option>--extension=<replaceable>PATH</replaceable></option></term> |
907952bb LB |
407 | |
408 | <listitem><para>Add an additional image <replaceable>PATH</replaceable> as an overlay on | |
409 | top of <replaceable>IMAGE</replaceable> when attaching/detaching. This argument can be specified | |
410 | multiple times, in which case the order in which images are laid down follows the rules specified in | |
411 | <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> | |
e91aa2ea | 412 | for the <varname>ExtensionImages=</varname> directive and for the |
cc59d101 | 413 | <citerefentry><refentrytitle>systemd-sysext</refentrytitle><manvolnum>8</manvolnum></citerefentry> and |
db776f69 | 414 | <citerefentry><refentrytitle>systemd-confext</refentrytitle><manvolnum>8</manvolnum></citerefentry> tools. |
0923b425 | 415 | The images must contain an <filename>extension-release</filename> file with metadata that matches |
e91aa2ea | 416 | what is defined in the <filename>os-release</filename> of <replaceable>IMAGE</replaceable>. See: |
9c8b6eaa | 417 | <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry>. |
2ef20244 LB |
418 | Images can be block images, btrfs subvolumes or directories. For more information on portable |
419 | services with extensions, see the <literal>Extension Images</literal> paragraph on | |
8b9f0921 | 420 | <ulink url="https://systemd.io/PORTABLE_SERVICES">Portable Services Documentation</ulink>. |
9c8b6eaa | 421 | </para> |
907952bb LB |
422 | |
423 | <para>Note that the same extensions have to be specified, in the same order, when attaching | |
ec07c3c8 AK |
424 | and detaching.</para> |
425 | ||
8257508c LB |
426 | <xi:include href="vpick.xml" xpointer="image"/> |
427 | <xi:include href="vpick.xml" xpointer="directory"/> | |
ec07c3c8 | 428 | <xi:include href="version-info.xml" xpointer="v249"/></listitem> |
907952bb LB |
429 | </varlistentry> |
430 | ||
ace212f5 LB |
431 | <varlistentry> |
432 | <term><option>--force</option></term> | |
433 | ||
434 | <listitem><para>Skip safety checks and attach or detach images (with extensions) without first ensuring | |
06768b90 LB |
435 | that the units are not running, and do not insist that the |
436 | <filename>extension-release.<replaceable>NAME</replaceable></filename> file in the extension image has | |
ec07c3c8 AK |
437 | to match the image filename.</para> |
438 | ||
439 | <xi:include href="version-info.xml" xpointer="v252"/></listitem> | |
ace212f5 LB |
440 | </varlistentry> |
441 | ||
e1fac8a6 ZJS |
442 | <xi:include href="user-system-options.xml" xpointer="host" /> |
443 | <xi:include href="user-system-options.xml" xpointer="machine" /> | |
444 | ||
445 | <xi:include href="standard-options.xml" xpointer="no-pager" /> | |
446 | <xi:include href="standard-options.xml" xpointer="no-legend" /> | |
447 | <xi:include href="standard-options.xml" xpointer="no-ask-password" /> | |
448 | <xi:include href="standard-options.xml" xpointer="help" /> | |
449 | <xi:include href="standard-options.xml" xpointer="version" /> | |
450 | </variablelist> | |
451 | </refsect1> | |
452 | ||
a8c42bb8 LP |
453 | <refsect1> |
454 | <title>Files and Directories</title> | |
455 | ||
456 | <para>Portable service images are preferably stored in <filename>/var/lib/portables/</filename>, but are also | |
457 | searched for in <filename>/etc/portables/</filename>, <filename>/run/systemd/portables/</filename>, | |
458 | <filename>/usr/local/lib/portables/</filename> and <filename>/usr/lib/portables/</filename>. It's recommended not | |
459 | to place image files directly in <filename>/etc/portables/</filename> or | |
460 | <filename>/run/systemd/portables/</filename> (as these are generally not suitable for storing large or non-textual | |
461 | data), but use these directories only for linking images located elsewhere into the image search path.</para> | |
83f72cd6 LP |
462 | |
463 | <para>When a portable service image is attached, matching unit files are copied onto the host into the | |
464 | <filename>/etc/systemd/system.attached/</filename> and <filename>/run/systemd/system.attached/</filename> | |
465 | directories. When an image is detached, the unit files are removed again from these directories.</para> | |
a8c42bb8 LP |
466 | </refsect1> |
467 | ||
468 | <refsect1> | |
469 | <title>Profiles</title> | |
470 | ||
471 | <para>When portable service images are attached a "profile" drop-in is linked in, which may be used to enforce | |
472 | additional security (and other) restrictions locally. Four profile drop-ins are defined by default, and shipped in | |
473 | <filename>/usr/lib/systemd/portable/profile/</filename>. Additional, local profiles may be defined by placing them | |
474 | in <filename>/etc/systemd/portable/profile/</filename>. The default profiles are:</para> | |
475 | ||
476 | <table> | |
477 | <title>Profiles</title> | |
478 | <tgroup cols='2'> | |
479 | <colspec colname='state'/> | |
480 | <colspec colname='description'/> | |
481 | <thead> | |
482 | <row> | |
483 | <entry>Name</entry> | |
484 | <entry>Description</entry> | |
485 | </row> | |
486 | </thead> | |
487 | <tbody> | |
488 | <row> | |
489 | <entry><filename>default</filename></entry> | |
490 | <entry>This is the default profile if no other profile name is set via the <option>--profile=</option> (see above). It's fairly restrictive, but should be useful for common, unprivileged system workloads. This includes write access to the logging framework, as well as IPC access to the D-Bus system.</entry> | |
491 | </row> | |
492 | <row> | |
493 | <entry><filename>nonetwork</filename></entry> | |
494 | <entry>Very similar to <filename>default</filename>, but networking is turned off for any services of the portable service image.</entry> | |
495 | </row> | |
496 | <row> | |
497 | <entry><filename>strict</filename></entry> | |
498 | <entry>A profile with very strict settings. This profile excludes IPC (D-Bus) and network access.</entry> | |
499 | </row> | |
500 | <row> | |
501 | <entry><filename>trusted</filename></entry> | |
502 | <entry>A profile with very relaxed settings. In this profile the services run with full privileges.</entry> | |
503 | </row> | |
504 | </tbody> | |
505 | </tgroup> | |
506 | </table> | |
507 | ||
e9dd6984 | 508 | <para>For details on these profiles and their effects see their precise definitions, |
a8c42bb8 LP |
509 | e.g. <filename>/usr/lib/systemd/portable/profile/default/service.conf</filename> and similar.</para> |
510 | </refsect1> | |
511 | ||
512 | <refsect1> | |
513 | <title>Exit status</title> | |
514 | ||
515 | <para>On success, 0 is returned, a non-zero failure code otherwise.</para> | |
516 | </refsect1> | |
517 | ||
4ef3ca34 | 518 | <xi:include href="common-variables.xml" /> |
a8c42bb8 LP |
519 | |
520 | <refsect1> | |
521 | <title>See Also</title> | |
13a69c12 DT |
522 | <para><simplelist type="inline"> |
523 | <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member> | |
524 | <member><citerefentry><refentrytitle>systemd-sysext</refentrytitle><manvolnum>8</manvolnum></citerefentry></member> | |
525 | <member><citerefentry><refentrytitle>org.freedesktop.portable1</refentrytitle><manvolnum>5</manvolnum></citerefentry></member> | |
526 | <member><citerefentry><refentrytitle>systemd-portabled.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member> | |
fd571c9d | 527 | <member><citerefentry><refentrytitle>importctl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member> |
13a69c12 | 528 | </simplelist></para> |
a8c42bb8 LP |
529 | </refsect1> |
530 | ||
531 | </refentry> |