-<?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'
<refentryinfo>
<title>portablectl</title>
<productname>systemd</productname>
-
- <authorgroup>
- <author>
- <contrib>Developer</contrib>
- <firstname>Lennart</firstname>
- <surname>Poettering</surname>
- <email>lennart@poettering.net</email>
- </author>
- </authorgroup>
</refentryinfo>
<refmeta>
<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
</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>
+
+ <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>
projects / thirdparty / systemd.git / blobdiff