docs/PORTABLE_SERVICES.md

@@ -19,18 +19,19 @@ The primary tool for interacting with Portable Services is `portablectl`,
 and they are managed by the `systemd-portabled` service.
 
 Portable services don't bring anything inherently new to the table. All they do
-is put together known concepts to cover a specific set of use-cases in a
+is put together known concepts in a slightly nicer way to cover a specific set
-sligtly nicer way.
+of use-cases in a nicer way.
 
 ## So, what *is* a "Portable Service"?
 
-A portable service is ultimately just an OS tree, either inside of a directory,
+A portable service is ultimately just an OS tree, either inside of a directory
-or inside a raw disk image containing a Linux file system. This tree is called
+tree, or inside a raw disk image (or a set of images that get layered, see
-the "image". It can be "attached" or "detached" from the system. When
+[Layered Images](#layered-images)) containing a Linux file system. This tree is called the
-"attached", specific systemd units from the image are made available on the
+"image". It can be "attached" or "detached" from the system. When "attached"
-host system, then behaving pretty much exactly like locally installed system
+specific systemd units from the image are made available on the host system,
-services. When "detached", these units are removed again from the host, leaving
+then behaving pretty much exactly like locally installed system services. When
-no artifacts around (except maybe messages they might have logged).
+"detached" these units are removed again from the host, leaving no artifacts
+around (except maybe messages they might have logged).
 
 The OS tree/image can be created with any tool of your choice. For example, you
 can use `dnf --installroot=` if you like, or `debootstrap`, the image format is
@@ -42,9 +43,6 @@ particularly nice tool for creating suitable images is
 [mkosi](https://github.com/systemd/mkosi), but many other existing tools will
 do too.
 
-Portable services may also be constructed from layers, similarly to container
-environments. See [Extension Images](#extension-images) below.
-
 If you so will, "Portable Services" are a nicer way to manage chroot()
 environments, with better security, tooling and behavior.
 
@@ -54,25 +52,25 @@ environments, with better security, tooling and behavior.
 systemd-nspawn/LXC-type OS containers, for Docker/rkt-like micro service
 containers, and even certain 'lightweight' VM runtimes.
 
-"Portable services" do not provide a fully isolated environment to the payload,
+The "portable service" concept ultimately will not provide a fully isolated
-like containers mostly intend to. Instead, they are more like regular system
+environment to the payload, like containers mostly intend to. Instead they are
-services, can be controlled with the same tools, are exposed the same way in
+from the beginning more alike regular system services, can be controlled with
-all infrastructure, and so on. The main difference is that they use a different
+the same tools, are exposed the same way in all infrastructure and so on. Their
-root directory than the rest of the system. Hence, the intent is not to run
+main difference is that they use a different root directory than the rest of the
-code in a different, isolated environment from the host — like most containers
+system. Hence, the intention is not to run code in a different, isolated world
-would — but to run it in the same environment, but with stricter access
+from the host — like most containers would do it — but to run it in the same
-controls on what the service can see and do.
+world, but with stricter access controls on what the service can see and do.
 
-One point of differentiation: since programs running as "portable services" are
+As one point of differentiation: as programs run as "portable services" are
-pretty much regular system services, they won't run as PID 1 (like they would
+pretty much regular system services, they won't run as PID 1 (like Docker would
-under Docker), but as normal processes. A corollary of that is that they aren't
+do it), but as normal processes. A corollary of that is that they aren't supposed
-supposed to manage anything in their own environment (such as the network) as
+to manage anything in their own environment (such as the network) as the
-the execution environment is mostly shared with the rest of the system.
+execution environment is mostly shared with the rest of the system.
 
 The primary focus use-case of "portable services" is to extend the host system
 with encapsulated extensions, but provide almost full integration with the rest
-of the system, though possibly restricted by security knobs. This focus
+of the system, though possibly restricted by effective security knobs. This
-includes system extensions otherwise sometimes called "super-privileged
+focus includes system extensions otherwise sometimes called "super-privileged
 containers".
 
 Note that portable services are only available for system services, not for
@@ -85,20 +83,21 @@ If you have a portable service image, maybe in a raw disk image called
 `foobar_0.7.23.raw`, then attaching the services to the host is as easy as:
 
 ```
-# portablectl attach foobar_0.7.23.raw
+# /usr/lib/systemd/portablectl attach foobar_0.7.23.raw
 ```
 
 This command does the following:
 
-1. It dissects the image, checks and validates the `os-release` file of the
+1. It dissects the image, checks and validates the `/etc/os-release`
-   image, and looks for all included unit files.
+   (or `/usr/lib/os-release`, see below)  data of the image, and looks for
+   all included unit files.
 
 2. It copies out all unit files with a suffix of `.service`, `.socket`,
    `.target`, `.timer` and `.path`. whose name begins with the image's name
-   (with `.raw` removed), truncated at the first underscore if there is one.
+   (with the .raw removed), truncated at the first underscore (if there is
-   This prefix name generated from the image name must be followed by a ".",
+   one). This prefix name generated from the image name must be followed by a
-   "-" or "@" character in the unit name. Or in other words, given the image
+   ".", "-" or "@" character in the unit name. Or in other words, given the
-   name of `foobar_0.7.23.raw` all unit files matching
+   image name of `foobar_0.7.23.raw` all unit files matching
    `foobar-*.{service|socket|target|timer|path}`,
    `foobar@.{service|socket|target|timer|path}` as well as
    `foobar.*.{service|socket|target|timer|path}` and
@@ -124,32 +123,33 @@ This command does the following:
 
 4. For each such unit a "profile" drop-in is linked in. This "profile" drop-in
    generally contains security options that lock down the service. By default
-   the `default` profile is used, which provides a medium level of security.
+   the `default` profile is used, which provides a medium level of
-   There's also `trusted`, which runs the service with no restrictions, i.e. in
+   security. There's also `trusted` which runs the service at the highest
-   the host file system root and with full privileges. The `strict` profile
+   privileges, i.e. host's root and everything. The `strict` profile comes with
-   comes with the toughest security restrictions. Finally, `nonetwork` is like
+   the toughest security restrictions. Finally, `nonetwork` is like `default`
-   `default` but without network access. Users may define their own profiles
+   but without network access. Users may define their own profiles too (or
-   too (or modify the existing ones).
+   modify the existing ones)
 
 And that's already it.
 
 Note that the images need to stay around (and in the same location) as long as the
 portable service is attached. If an image is moved, the `RootImage=` line
-written to the unit drop-in would point to an non-existent path, and break
+written to the unit drop-in would point to an non-existing place, and break the
-access to the image.
+logic.
 
 The `portablectl detach` command executes the reverse operation: it looks for
-the drop-ins and the unit files associated with the image, and removes them.
+the drop-ins and the unit files associated with the image, and removes them
+again.
 
 Note that `portablectl attach` won't enable or start any of the units it copies
 out by default, but `--enable` and `--now` parameter are available as shortcuts.
 The same is true for the opposite `detach` operation.
 
-The `portablectl reattach` command combines a `detach` with an `attach`. It is
+A `portablectl reattach` command is made available to combine a `detach` with an
-useful in case an image gets upgraded, as it allows performing a `restart`
+`attach`, and it is useful in case an image gets upgraded, as it allows a to
-operation on the units instead of `stop` plus `start`, thus providing lower
+perform a `restart` operation on the unit(s) instead of `stop` plus `start`,
-downtime and avoiding losing runtime state associated with the unit such as the
+thus providing lower downtime and avoiding losing runtime state associated with
-file descriptor store.
+the unit such as the file descriptor store.
 
 ## Requirements on Images
 
@@ -159,8 +159,8 @@ requirements are made for an image that can be attached/detached with
 `portablectl`.
 
 1. It must contain an executable that shall be invoked, along with all its
-   dependencies. Any binary code needs to be compiled for an architecture
+   dependencies. If binary code, the code needs to be compiled for an
-   compatible with the host.
+   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
@@ -195,9 +195,9 @@ requirements are made for an image that can be attached/detached with
    distribution's documentation.
 
 Note that images created by tools such as `debootstrap`, `dnf --installroot=`
-or `mkosi` generally satisfy all of the above. If you wonder what the most
+or `mkosi` generally qualify for all of the above in one way or another. If you
-minimal image would be that complies with the requirements above, it could
+wonder what the most minimal image would be that complies with the requirements
-consist of this:
+above, it could consist of this:
 
 ```
 /usr/bin/minimald                            # a statically compiled binary
@@ -221,9 +221,9 @@ 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 will be automatically created.
+overmounted from the host do not exist yet they are automatically created. On
-On read-only, immutable images (e.g. squashfs images) all files and directories
+read-only, immutable images (e.g. squashfs images) all files and directories to
-to over-mount must exist already.
+over-mount must exist already.
 
 Note that as no new image format or metadata is defined, it's very
 straightforward to define images than can be made use of in a number of
@@ -242,9 +242,9 @@ single, unified image that:
 4. Can be booted directly on bare-metal systems.
 
 Of course, to facilitate 2, 3 and 4 you need to include an init system in the
-image. To facilitate 3 and 4 you also need to include a boot loader in the
+image. To facility 3 and 4 you also need to include a boot loader in the
-image. As mentioned, `mkosi -b` takes care of all of that for you, but any
+image. As mentioned `mkosi -b` takes care of all of that for you, but any other
-other image generator should work too.
+image generator should work too.
 
 ## Extension Images
 
@@ -255,10 +255,10 @@ portable services can share the same 'runtime' image (libraries, tools) without
 having to include everything each time, with the layering happening only at runtime.
 The `--extension` parameter of `portablectl` can be used to specify as many upper
 layers as desired. On top of the requirements listed in the previous section, the
-following must be also be observed:
+following must be also be observed.
 
-1. The base/OS image must contain an `os-release file`, either in `/etc/os-release`
+1. The base/OS image must contain an os-release file, either in `/etc/os-release` or
-   or `/usr/lib/os-release`, in the standard format.
+   `/usr/lib/os-release`. The file should follow the standard format.
 
 2. The upper extension(s) image(s) must contain an extension-release file in
    `/usr/lib/extension-release.d/`, with an `ID=` and `SYSEXT_LEVEL=`/`VERSION_ID=`
@@ -270,14 +270,14 @@ following must be also be observed:
    with the right name prefix and suffix (see above).
 
 ```
-# portablectl attach --extension foobar_0.7.23.raw debian-runtime_11.1.raw foobar
+# /usr/lib/systemd/portablectl attach --extension foobar_0.7.23.raw debian-runtime_11.1.raw foobar
-# portablectl attach --extension barbaz_7.0.23.raw debian-runtime_11.1.raw barbaz
+# /usr/lib/systemd/portablectl attach --extension barbaz_7.0.23.raw debian-runtime_11.1.raw barbaz
 ```
 
 ## Execution Environment
 
 Note that the code in portable service images is run exactly like regular
-services. Hence there's no new execution environment to consider. And, unlike
+services. Hence there's no new execution environment to consider. Oh, unlike
 Docker would do it, as these are regular system services they aren't run as PID
 1 either, but with regular PID values.
 
@@ -294,12 +294,12 @@ subsystem are available to the service.
 
 Sometimes it makes sense to instantiate the same set of services multiple
 times. The portable service concept does not introduce a new logic for this. It
-is recommended to use the regular systemd unit templating for this, i.e. to
+is recommended to use the regular unit templating of systemd for this, i.e. to
 include template units such as `foobar@.service`, so that instantiation is as
 simple as:
 
 ```
-# portablectl attach foobar_0.7.23.raw
+# /usr/lib/systemd/portablectl attach foobar_0.7.23.raw
 # systemctl enable --now foobar@instancea.service
 # systemctl enable --now foobar@instanceb.service
 …

src/core/load-fragment.c

@@ -800,7 +800,7 @@ int config_parse_exec(
                 if (!separate_argv0) {
                         char *w = NULL;
 
-                        if (!GREEDY_REALLOC0(n, nlen + 2))
+                        if (!GREEDY_REALLOC(n, nlen + 2))
                                 return log_oom();
 
                         w = strdup(path);
@@ -832,7 +832,7 @@ int config_parse_exec(
                                 p += 2;
                                 p += strspn(p, WHITESPACE);
 
-                                if (!GREEDY_REALLOC0(n, nlen + 2))
+                                if (!GREEDY_REALLOC(n, nlen + 2))
                                         return log_oom();
 
                                 w = strdup(";");

src/shared/libfido2-util.c

@@ -58,7 +58,6 @@ bool (*sym_fido_dev_is_fido2)(const fido_dev_t *) = NULL;
 int (*sym_fido_dev_make_cred)(fido_dev_t *, fido_cred_t *, const char *) = NULL;
 fido_dev_t* (*sym_fido_dev_new)(void) = NULL;
 int (*sym_fido_dev_open)(fido_dev_t *, const char *) = NULL;
-int (*sym_fido_dev_close)(fido_dev_t *) = NULL;
 const char* (*sym_fido_strerr)(int) = NULL;
 
 int dlopen_libfido2(void) {
@@ -107,7 +106,6 @@ int dlopen_libfido2(void) {
                         DLSYM_ARG(fido_dev_make_cred),
                         DLSYM_ARG(fido_dev_new),
                         DLSYM_ARG(fido_dev_open),
-                        DLSYM_ARG(fido_dev_close),
                         DLSYM_ARG(fido_strerr));
 }
 

src/shared/libfido2-util.h

@@ -60,7 +60,6 @@ extern bool (*sym_fido_dev_is_fido2)(const fido_dev_t *);
 extern int (*sym_fido_dev_make_cred)(fido_dev_t *, fido_cred_t *, const char *);
 extern fido_dev_t* (*sym_fido_dev_new)(void);
 extern int (*sym_fido_dev_open)(fido_dev_t *, const char *);
-extern int (*sym_fido_dev_close)(fido_dev_t *);
 extern const char* (*sym_fido_strerr)(int);
 
 int dlopen_libfido2(void);
@@ -76,10 +75,8 @@ static inline void fido_assert_free_wrapper(fido_assert_t **p) {
 }
 
 static inline void fido_dev_free_wrapper(fido_dev_t **p) {
-        if (*p) {
+        if (*p)
-                sym_fido_dev_close(*p);
                 sym_fido_dev_free(p);
-        }
 }
 
 static inline void fido_cred_free_wrapper(fido_cred_t **p) {

test/TEST-06-SELINUX/test.sh

@@ -46,11 +46,11 @@ test_append_files() {
         cp systemd_test.te "$workspace/systemd-test-module"
         cp systemd_test.if "$workspace/systemd-test-module"
         cp systemd_test.fc "$workspace/systemd-test-module"
-        image_install -o sesearch
+        dracut_install -o sesearch
-        image_install runcon
+        dracut_install runcon
-        image_install checkmodule semodule semodule_package m4 make load_policy sefcontext_compile
+        dracut_install checkmodule semodule semodule_package m4 make load_policy sefcontext_compile
-        image_install -o /usr/libexec/selinux/hll/pp # Fedora/RHEL/...
+        dracut_install -o /usr/libexec/selinux/hll/pp # Fedora/RHEL/...
-        image_install -o /usr/lib/selinux/hll/pp     # Debian/Ubuntu/...
+        dracut_install -o /usr/lib/selinux/hll/pp     # Debian/Ubuntu/...
     )
 }
 

test/TEST-13-NSPAWN-SMOKE/test.sh

@@ -17,12 +17,12 @@ test_append_files() {
         inst_simple "$busybox" "$(dirname $busybox)/busybox"
 
         if selinuxenabled >/dev/null; then
-            image_install selinuxenabled
+            dracut_install selinuxenabled
             cp -ar /etc/selinux "$workspace/etc/selinux"
         fi
 
         "$TEST_BASE_DIR/create-busybox-container" "$workspace/testsuite-13.nc-container"
-        initdir="$workspace/testsuite-13.nc-container" image_install nc ip md5sum
+        initdir="$workspace/testsuite-13.nc-container" dracut_install nc ip md5sum
     )
 }
 

test/TEST-55-OOMD/test.sh

@@ -11,7 +11,7 @@ test_append_files() {
     # Create a swap device
     (
         mkswap "${LOOPDEV:?}p2"
-        image_install swapon swapoff
+        dracut_install swapon swapoff
 
         cat >>"${initdir:?}/etc/fstab" <<EOF
 UUID=$(blkid -o value -s UUID "${LOOPDEV}p2")    none    swap    defaults 0 0

test/test-functions

@@ -707,9 +707,9 @@ setup_selinux() {
     mkdir -p "$initdir/usr/lib/systemd/tests/testdata/units/basic.target.wants"
     ln -sf ../autorelabel.service "$initdir/usr/lib/systemd/tests/testdata/units/basic.target.wants/"
 
-    image_install "${fixfiles_tools[@]}"
+    dracut_install "${fixfiles_tools[@]}"
-    image_install fixfiles
+    dracut_install fixfiles
-    image_install sestatus
+    dracut_install sestatus
 }
 
 install_valgrind() {
@@ -721,16 +721,16 @@ install_valgrind() {
     local valgrind_bins valgrind_libs valgrind_dbg_and_supp
 
     valgrind_bins="$(strace -e execve valgrind /bin/true 2>&1 >/dev/null | perl -lne 'print $1 if /^execve\("([^"]+)"/')"
-    image_install "$valgrind_bins"
+    dracut_install "$valgrind_bins"
 
     valgrind_libs="$(LD_DEBUG=files valgrind /bin/true 2>&1 >/dev/null | perl -lne 'print $1 if m{calling init: (/.*vgpreload_.*)}')"
-    image_install "$valgrind_libs"
+    dracut_install "$valgrind_libs"
 
     valgrind_dbg_and_supp="$(
         strace -e open valgrind /bin/true 2>&1 >/dev/null |
         perl -lne 'if (my ($fname) = /^open\("([^"]+).*= (?!-)\d+/) { print $fname if $fname =~ /debug|\.supp$/ }'
     )"
-    image_install "$valgrind_dbg_and_supp"
+    dracut_install "$valgrind_dbg_and_supp"
 }
 
 create_valgrind_wrapper() {
@@ -753,7 +753,7 @@ create_asan_wrapper() {
 
     # clang: install llvm-symbolizer to generate useful reports
     # See: https://clang.llvm.org/docs/AddressSanitizer.html#symbolizing-the-reports
-    [[ "$ASAN_COMPILER" == "clang" ]] && image_install "llvm-symbolizer"
+    [[ "$ASAN_COMPILER" == "clang" ]] && dracut_install "llvm-symbolizer"
 
     cat >"$asan_wrapper" <<EOF
 #!/usr/bin/env bash
@@ -869,15 +869,15 @@ EOF
 
 install_fs_tools() {
     dinfo "Install fsck"
-    image_install /sbin/fsck*
+    dracut_install /sbin/fsck*
-    image_install -o /bin/fsck*
+    dracut_install -o /bin/fsck*
 
     # fskc.reiserfs calls reiserfsck. so, install it
-    image_install -o reiserfsck
+    dracut_install -o reiserfsck
 
     # we use mkfs in system-repart tests
-    image_install /sbin/mkfs.ext4
+    dracut_install /sbin/mkfs.ext4
-    image_install /sbin/mkfs.vfat
+    dracut_install /sbin/mkfs.vfat
 }
 
 install_modules() {
@@ -1424,7 +1424,7 @@ install_plymouth() {
     # if [ -x /usr/libexec/plymouth/plymouth-populate-initrd ]; then
     #     PLYMOUTH_POPULATE_SOURCE_FUNCTIONS="$TEST_BASE_DIR/test-functions" \
     #         /usr/libexec/plymouth/plymouth-populate-initrd -t $initdir
-    #         image_install plymouth plymouthd
+    #         dracut_install plymouth plymouthd
     # else
         rm -f "${initdir:?}"/{usr/lib,lib,etc}/systemd/system/plymouth* "$initdir"/{usr/lib,lib,etc}/systemd/system/*/plymouth*
     # fi
@@ -1490,15 +1490,15 @@ install_config_files() {
 
 install_basic_tools() {
     dinfo "Install basic tools"
-    image_install "${BASICTOOLS[@]}"
+    dracut_install "${BASICTOOLS[@]}"
-    image_install -o sushell
+    dracut_install -o sushell
     # in Debian ldconfig is just a shell script wrapper around ldconfig.real
-    image_install -o ldconfig.real
+    dracut_install -o ldconfig.real
 }
 
 install_debug_tools() {
     dinfo "Install debug tools"
-    image_install "${DEBUGTOOLS[@]}"
+    dracut_install "${DEBUGTOOLS[@]}"
 
     if get_bool "$INTERACTIVE_DEBUG"; then
         # Set default TERM from vt220 to linux, so at least basic key shortcuts work
@@ -1521,7 +1521,7 @@ install_libnss() {
     # install libnss_files for login
     local NSS_LIBS
     mapfile -t NSS_LIBS < <(LD_DEBUG=files getent passwd 2>&1 >/dev/null | sed -n '/calling init: .*libnss_/ {s!^.* /!/!; p}')
-    image_install "${NSS_LIBS[@]}"
+    dracut_install "${NSS_LIBS[@]}"
 }
 
 install_dbus() {
@@ -1613,7 +1613,7 @@ install_pam() {
 
     # pam_unix depends on unix_chkpwd.
     # see http://www.linux-pam.org/Linux-PAM-html/sag-pam_unix.html
-    image_install -o unix_chkpwd
+    dracut_install -o unix_chkpwd
 
     # set empty root password for easy debugging
     sed -i 's/^root:x:/root::/' "${initdir:?}/etc/passwd"
@@ -1682,7 +1682,7 @@ install_terminfo() {
     for terminfodir in /lib/terminfo /etc/terminfo /usr/share/terminfo; do
         [ -f "${terminfodir}/l/linux" ] && break
     done
-    image_install -o "${terminfodir}/l/linux"
+    dracut_install -o "${terminfodir}/l/linux"
 }
 
 has_user_dbus_socket() {
@@ -1759,7 +1759,7 @@ inst_libs() {
             dfatal "Missing a shared library required by $bin."
             dfatal "Run \"ldd $bin\" to find out what it is."
             dfatal "$line"
-            dfatal "Cannot create a test image."
+            dfatal "dracut cannot create an initrd."
             exit 1
         fi
     done < <(LC_ALL=C ldd "$bin" 2>/dev/null)
@@ -2149,7 +2149,7 @@ inst_binary() {
             dfatal "Missing a shared library required by $bin."
             dfatal "Run \"ldd $bin\" to find out what it is."
             dfatal "$line"
-            dfatal "Cannot create a test image."
+            dfatal "dracut cannot create an initrd."
             exit 1
         fi
     done < <(LC_ALL=C ldd "$bin" 2>/dev/null)
@@ -2209,7 +2209,7 @@ inst_rule_programs() {
         fi
 
         #dinfo "Installing $_bin due to it's use in the udev rule $(basename $1)"
-        image_install "$bin"
+        dracut_install "$bin"
     done
 }
 
@@ -2297,10 +2297,10 @@ inst_any() {
     return 1
 }
 
-# image_install [-o ] <file> [<file> ... ]
+# dracut_install [-o ] <file> [<file> ... ]
-# Install <file> to the test image
+# Install <file> to the initramfs image
 # -o optionally install the <file> and don't fail, if it is not there
-image_install() {
+dracut_install() {
     local optional=no
     local prog="${1:?}"