From 83f72cd65fb85d3eb57efde78790bb05f3474e9b Mon Sep 17 00:00:00 2001
From: Lennart Poettering <lennart@poettering.net>
Date: Mon, 8 Oct 2018 18:43:14 +0200
Subject: [PATCH] man,docs: document the new unit file directory for attached
 images

---
 docs/PORTABLE_SERVICES.md | 15 ++++++++-------
 man/portablectl.xml       | 16 +++++++++++-----
 man/systemd.unit.xml      |  2 ++
 3 files changed, 21 insertions(+), 12 deletions(-)

diff --git a/docs/PORTABLE_SERVICES.md b/docs/PORTABLE_SERVICES.md
index 18332444472..55397f46391 100644
--- a/docs/PORTABLE_SERVICES.md
+++ b/docs/PORTABLE_SERVICES.md
@@ -98,16 +98,17 @@ This command does the following:
    `foobar@.{service|socket|target|timer|path}` as well as
    `foobar.*.{service|socket|target|timer|path}` and
    `foobar.{service|socket|target|timer|path}` are copied out. These unit files
-   are placed in `/etc/systemd/system/` like regular unit files. Within the
-   images the unit files are looked for at the usual locations, i.e. in
-   `/usr/lib/systemd/system/` and `/etc/systemd/system/` and so on, relative to
-   the image's root.
+   are placed in `/etc/systemd/system.attached/` (which is part of the normal
+   unit file search path of PID 1, and thus loaded exactly like regular unit
+   files). Within the images the unit files are looked for at the usual
+   locations, i.e. in `/usr/lib/systemd/system/` and `/etc/systemd/system/` and
+   so on, relative to the image's root.
 
 3. For each such unit file a drop-in file is created. Let's say
    `foobar-waldo.service` was one of the unit files copied to
-   `/etc/systemd/system/`, then a drop-in file
-   `/etc/systemd/system/foobar-waldo.service.d/20-portable.conf` is created,
-   containing a few lines of additional configuration:
+   `/etc/systemd/system.attached/`, then a drop-in file
+   `/etc/systemd/system.attached/foobar-waldo.service.d/20-portable.conf` is
+   created, containing a few lines of additional configuration:
 
    ```
    [Service]
diff --git a/man/portablectl.xml b/man/portablectl.xml
index 24b9f4ead18..33b14ea0653 100644
--- a/man/portablectl.xml
+++ b/man/portablectl.xml
@@ -101,9 +101,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>
@@ -167,8 +167,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
@@ -330,6 +332,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>
diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml
index c615739e335..aa2700d5477 100644
--- a/man/systemd.unit.xml
+++ b/man/systemd.unit.xml
@@ -44,7 +44,9 @@
 <filename>/run/systemd/transient/*</filename>
 <filename>/run/systemd/generator.early/*</filename>
 <filename>/etc/systemd/system/*</filename>
+<filename>/etc/systemd/systemd.attached/*</filename>
 <filename>/run/systemd/system/*</filename>
+<filename>/run/systemd/systemd.attached/*</filename>
 <filename>/run/systemd/generator/*</filename>
 <filename>…</filename>
 <filename>/usr/lib/systemd/system/*</filename>
-- 
2.47.3