Merge pull request #13102 from mbiebl/nologin-path

[thirdparty/systemd.git] / man / portablectl.xml

diff --git a/man/portablectl.xml b/man/portablectl.xml
index 0571c9d7c45379700319012ec9368eb13ecee18a..01f6a1deeac8be623b7303a44d64922a7469ea3b 100644 (file)
--- a/man/portablectl.xml
+++ b/man/portablectl.xml
@@ -1,7 +1,6 @@
-<?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'
@@ -10,15 +9,6 @@
   <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>
@@ -68,7 +58,7 @@
       <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>
@@ -110,9 +100,9 @@
         <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>
+        <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>
@@ -176,8 +166,10 @@
           <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
@@ -196,7 +188,7 @@
 
         <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 occurence of and underscore character
+        <filename>.raw</filename> removed, truncated at the first occurrence of and 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
@@ -269,7 +261,7 @@
               </row>
               <row>
                 <entry><option>attached-runtime</option></entry>
-                <entry>Like <option>attached</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>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>
               </row>
               <row>
                 <entry><option>enabled</option></entry>
@@ -306,7 +298,7 @@
         <term><command>remove</command> <replaceable>IMAGE</replaceable>…</term>
 
         <listitem><para>Removes one or more portable service images. Note that this command will only remove the
-        specified image path itself — it it refers to a symbolic link then the symbolic link is removed and not the
+        specified image path itself — it refers to a symbolic link then the symbolic link is removed and not the
         image it points to.</para></listitem>
       </varlistentry>
 
@@ -339,6 +331,10 @@
     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>