-<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+<?xml version='1.0'?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
-
<!-- SPDX-License-Identifier: LGPL-2.1+ -->
<refentry id="portablectl" conditional='ENABLE_PORTABLED'
<listitem><para>btrfs subvolumes containing OS trees, similar to normal directory trees.</para></listitem>
<listitem><para>Binary "raw" disk images containing MBR or GPT partition tables and Linux file system
- partitions.</para></listitem>
+ partitions. (These must be regular files, with the <filename>.raw</filename> suffix.)</para></listitem>
</itemizedlist>
</refsect1>
- <refsect1>
- <title>Options</title>
-
- <para>The following options are understood:</para>
-
- <variablelist>
- <varlistentry>
- <term><option>-q</option></term>
- <term><option>--quiet</option></term>
-
- <listitem><para>Suppresses additional informational output while running.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>-p</option> <replaceable>PROFILE</replaceable></term>
- <term><option>--profile=</option><replaceable>PROFILE</replaceable></term>
-
- <listitem><para>When attaching an image, select the profile to use. By default the <literal>default</literal>
- profile is used. For details about profiles, see below.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--copy=</option></term>
-
- <listitem><para>When attaching an image, select whether to prefer copying or symlinking of files installed into
- the host system. Takes one of <literal>copy</literal> (to prefer copying of files), <literal>symlink</literal>
- (to prefer creation of symbolic links) or <literal>auto</literal> for an intermediary mode where security
- profile drop-ins are symlinked while unit files are copied. Note that this option expresses a preference only,
- in cases where symbolic links cannot be created — for example when the image operated on is a raw disk image,
- and hence not directly referentiable from the host file system — copying of files is used
- unconditionally.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--runtime</option></term>
-
- <listitem><para>When specified the unit and drop-in files are placed in
- <filename>/run/systemd/system/</filename> instead of <filename>/etc/systemd/system/</filename>. Images attached
- with this option set hence remain attached only until the next reboot, while they are normally attached
- persistently.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--no-reload</option></term>
-
- <listitem><para>Don't reload the service manager after attaching or detaching a portable service
- image. Normally the service manager is reloaded to ensure it is aware of added or removed unit
- files.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--cat</option></term>
-
- <listitem><para>When inspecting portable service images, show the (unprocessed) contents of the metadata files
- pulled from the image, instead of brief summaries. Specifically, this will show the
- <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry> and unit file
- contents of the image.</para></listitem>
- </varlistentry>
-
- <xi:include href="user-system-options.xml" xpointer="host" />
- <xi:include href="user-system-options.xml" xpointer="machine" />
-
- <xi:include href="standard-options.xml" xpointer="no-pager" />
- <xi:include href="standard-options.xml" xpointer="no-legend" />
- <xi:include href="standard-options.xml" xpointer="no-ask-password" />
- <xi:include href="standard-options.xml" xpointer="help" />
- <xi:include href="standard-options.xml" xpointer="version" />
- </variablelist>
- </refsect1>
-
<refsect1>
<title>Commands</title>
<listitem><para>All unit files of types <filename>.service</filename>, <filename>.socket</filename>,
<filename>.target</filename>, <filename>.timer</filename> and <filename>.path</filename> which match the
indicated unit file name prefix are copied from the image to the host's
- <filename>/etc/systemd/system/</filename> directory (or <filename>/run/systemd/system/</filename> — depending
- whether <option>--runtime</option> is specified, see above).</para></listitem>
+ <filename>/etc/systemd/system.attached/</filename> directory (or
+ <filename>/run/systemd/system.attached/</filename> — depending whether <option>--runtime</option> is
+ specified, see above), which is included in the built-in unit search path of the system service
+ manager.</para></listitem>
<listitem><para>For unit files of type <filename>.service</filename> a drop-in is added to these copies that
adds <varname>RootDirectory=</varname> or <varname>RootImage=</varname> settings (see
<para>By default all unit files whose names start with a prefix generated from the image's file name are copied
out. Specifically, the prefix is determined from the image file name with any suffix such as
- <filename>.raw</filename> removed, truncated at the first occurrence of and underscore character
+ <filename>.raw</filename> removed, truncated at the first occurrence of an underscore character
(<literal>_</literal>), if there is one. The underscore logic is supposed to be used to versioning so that the
an image file <filename>foobar_47.11.raw</filename> will result in a unit file matching prefix of
<filename>foobar</filename>. This prefix is then compared with all unit files names contained in the image in
<para>By default, after the unit files are attached the service manager's configuration is reloaded, except
when <option>--no-reload</option> is specified (see above). This ensures that the new units made available to
the service manager are seen by it.</para>
+
+ <para>If <option>--now</option> and/or <option>--enable</option> are passed, the portable service(s) are
+ immediately started (blocking operation unless <option>--no-block</option> is passed) and/or enabled after
+ attaching the image.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><command>detach</command> <replaceable>IMAGE</replaceable></term>
+ <term><command>detach</command> <replaceable>IMAGE</replaceable> [<replaceable>PREFIX…</replaceable>]</term>
<listitem><para>Detaches a portable service image from the host. This undoes the operations executed by the
<command>attach</command> command above, and removes the unit file copies, drop-ins and image symlink
component of it (i.e. the file or directory name itself, not the path to it) is used for finding matching unit
files. This is a convencience feature to allow all arguments passed as <command>attach</command> also to
<command>detach</command>.</para></listitem>
+
+ <para>If <option>--now</option> and/or <option>--enable</option> are passed, the portable service(s) are
+ immediately stopped (blocking operation) and/or disabled before detaching the image. Prefix(es) are also accepted,
+ to be used in case the unit names do not match the image name as described in the <command>attach</command>.</para>
</varlistentry>
<varlistentry>
</row>
<row>
<entry><option>enabled-runtime</option></entry>
- <entry>Like <option>enabled</option>, but the 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>
+ <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>
</row>
<row>
<entry><option>running</option></entry>
</refsect1>
+ <refsect1>
+ <title>Options</title>
+
+ <para>The following options are understood:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><option>-q</option></term>
+ <term><option>--quiet</option></term>
+
+ <listitem><para>Suppresses additional informational output while running.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-p</option> <replaceable>PROFILE</replaceable></term>
+ <term><option>--profile=</option><replaceable>PROFILE</replaceable></term>
+
+ <listitem><para>When attaching an image, select the profile to use. By default the <literal>default</literal>
+ profile is used. For details about profiles, see below.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--copy=</option></term>
+
+ <listitem><para>When attaching an image, select whether to prefer copying or symlinking of files installed into
+ the host system. Takes one of <literal>copy</literal> (to prefer copying of files), <literal>symlink</literal>
+ (to prefer creation of symbolic links) or <literal>auto</literal> for an intermediary mode where security
+ profile drop-ins are symlinked while unit files are copied. Note that this option expresses a preference only,
+ in cases where symbolic links cannot be created — for example when the image operated on is a raw disk image,
+ and hence not directly referentiable from the host file system — copying of files is used
+ unconditionally.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--runtime</option></term>
+
+ <listitem><para>When specified the unit and drop-in files are placed in
+ <filename>/run/systemd/system.attached/</filename> instead of
+ <filename>/etc/systemd/system.attached/</filename>. Images attached with this option set hence remain attached
+ only until the next reboot, while they are normally attached persistently.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--no-reload</option></term>
+
+ <listitem><para>Don't reload the service manager after attaching or detaching a portable service
+ image. Normally the service manager is reloaded to ensure it is aware of added or removed unit
+ files.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--cat</option></term>
+
+ <listitem><para>When inspecting portable service images, show the (unprocessed) contents of the metadata files
+ pulled from the image, instead of brief summaries. Specifically, this will show the
+ <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry> and unit file
+ contents of the image.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--enable</option></term>
+
+ <listitem><para>Immediately enable/disable the portable service after attaching/detaching.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--now</option></term>
+
+ <listitem><para>Immediately start/stop the portable service after attaching/before detaching.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--no-block</option></term>
+
+ <listitem><para>Don't block waiting for attach --now to complete.</para></listitem>
+ </varlistentry>
+
+ <xi:include href="user-system-options.xml" xpointer="host" />
+ <xi:include href="user-system-options.xml" xpointer="machine" />
+
+ <xi:include href="standard-options.xml" xpointer="no-pager" />
+ <xi:include href="standard-options.xml" xpointer="no-legend" />
+ <xi:include href="standard-options.xml" xpointer="no-ask-password" />
+ <xi:include href="standard-options.xml" xpointer="help" />
+ <xi:include href="standard-options.xml" xpointer="version" />
+ </variablelist>
+ </refsect1>
+
<refsect1>
<title>Files and Directories</title>
to place image files directly in <filename>/etc/portables/</filename> or
<filename>/run/systemd/portables/</filename> (as these are generally not suitable for storing large or non-textual
data), but use these directories only for linking images located elsewhere into the image search path.</para>
+
+ <para>When a portable service image is attached, matching unit files are copied onto the host into the
+ <filename>/etc/systemd/system.attached/</filename> and <filename>/run/systemd/system.attached/</filename>
+ directories. When an image is detached, the unit files are removed again from these directories.</para>
</refsect1>
<refsect1>
</tgroup>
</table>
- <para>For details on this profiles, and their effects please have a look at their precise definitions,
+ <para>For details on these profiles and their effects see their precise definitions,
e.g. <filename>/usr/lib/systemd/portable/profile/default/service.conf</filename> and similar.</para>
</refsect1>
projects / thirdparty / systemd.git / blobdiff