Merge pull request #12954 from keszybz/var-log-dir

[thirdparty/systemd.git] / docs / PORTABLE_SERVICES.md

diff --git a/docs/PORTABLE_SERVICES.md b/docs/PORTABLE_SERVICES.md
index 5b6c085af096859cdc38c39aaad3db3025de5199..194ef5bcdbbaad16f73665640e689ed4ca82a70e 100644 (file)
--- a/docs/PORTABLE_SERVICES.md
+++ b/docs/PORTABLE_SERVICES.md
@@ -153,9 +153,9 @@ images should just work the way they are. Specifically, the following
 requirements are made for an image that can be attached/detached with
 `portablectl`.
 
-1. It must contain a binary (and its dependencies) that shall be invoked,
-   including all its dependencies. If binary code, the code needs to be
-   compiled for an architecture compatible with the host.
+1. It must contain an executable that shall be invoked, along with all its
+   dependencies. If binary code, the code needs to be compiled for an
+   architecture compatible with the host.
 
 2. The image must either be a plain sub-directory (or btrfs subvolume)
    containing the binaries and its dependencies in a classic Linux OS tree, or
@@ -177,15 +177,35 @@ requirements are made for an image that can be attached/detached with
 5. The image must contain the files `/etc/resolv.conf` and `/etc/machine-id`
    (empty files are ok), they will be bind mounted from the host at runtime.
 
-Note that generally images created by tools such as `debootstrap`, `dnf
---installroot=` or `mkosi` qualify for all of the above in one way or
-another. If you wonder what the most minimal image would be that complies with
-the requirements above, it could consist of this:
+6. The image must contain directories `/proc/`, `/sys/`, `/dev/`, `/run/`,
+   `/tmp/`, `/var/tmp/` that can be mounted over with the corresponding version
+   from the host.
+
+7. The OS might require other files or directories to be in place. For example,
+   if the image is built based on glibc, the dynamic loader needs to be
+   available in `/lib/ld-linux.so.2` or `/lib64/ld-linux-x86-64.so.2` (or
+   similar, depending on architecture), and if the distribution implements a
+   merged `/usr/` tree, this means `/lib` and/or `/lib64` need to be symlinks
+   to their respective counterparts below `/usr/`. For details see your
+   distribution's documentation.
+
+Note that images created by tools such as `debootstrap`, `dnf --installroot=`
+or `mkosi` generally qualify for all of the above in one way or another. If you
+wonder what the most minimal image would be that complies with the requirements
+above, it could consist of this:
 
 ```
-/usr/bin/minimald                        # a statically compiled binary
-/usr/lib/systemd/minimal-test.service    # the unit file for the service, with ExecStart=/usr/bin/minimald
-/usr/lib/os-release                      # an os-release file explaining what this is
+/usr/bin/minimald                            # a statically compiled binary
+/usr/lib/systemd/system/minimal-test.service # the unit file for the service, with ExecStart=/usr/bin/minimald
+/usr/lib/os-release                          # an os-release file explaining what this is
+/etc/resolv.conf                             # empty file to mount over with host's version
+/etc/machine-id                              # ditto
+/proc/                                       # empty directory to use as mount point for host's API fs
+/sys/                                        # ditto
+/dev/                                        # ditto
+/run/                                        # ditto
+/tmp/                                        # ditto
+/var/tmp/                                    # ditto
 ```
 
 And that's it.
@@ -195,6 +215,11 @@ own. If they do, it's fine, it will be ignored by the portable service logic,
 but they generally don't have to, and it might make sense to avoid any, to keep
 images minimal.
 
+If the image is writable, and some of the files or directories that are
+overmounted from the host do not exist yet they are automatically created. On
+read-only, immutable images (e.g. squashfs images) all files and directories to
+over-mount must exist already.
+
 Note that as no new image format or metadata is defined, it's very
 straight-forward to define images than can be made use of it a number of
 different ways. For example, by using `mkosi -b` you can trivially build a