docs: comprehensively document what a minimal portable service image needs to include

The docs were incomplete on this. Let's fix that.

Fixes: #11870

1 files changed, 32 insertions, 7 deletions

diff --git a/docs/PORTABLE_SERVICES.md b/docs/PORTABLE_SERVICES.md
index 5b6c085af0..631d063b01 100644
--- 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
+/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