Attach and Inspect Portable Services Safely with portablectl

By the end of this guide you will be able to inspect a systemd portable service image, attach its matching units, check the resulting state, and detach it cleanly. The examples use the locally installed systemd 255 package and take about 10 minutes if you already have a suitable image. You need a portable service image and root access for changes to the system; inspection and listing are normally harmless to run first.

What the portable1 interface controls

org.freedesktop.portable1 is the D-Bus interface exposed by systemd-portabled.service. It is the service API, not a configuration file that you edit. The practical command-line client is portablectl, which asks portabled to list, inspect, attach, detach, reattach, remove and limit portable images.

A portable image is an operating-system tree, btrfs subvolume, or raw disk image containing unit files and the files needed by those units. Attaching it makes selected .service, .socket, .target, .timer and .path units available to the host. Service units receive settings such as RootDirectory= or RootImage= so they run against the image's filesystem.

Checkpoint: confirm the client and package version before relying on a feature. This machine reports systemd 255:

$ portablectl --version
systemd 255 (255.4-1ubuntu8.17)

1. List images without changing anything

Start with the image search paths. The preferred storage directory is /var/lib/portables/; other paths include /etc/portables/, /run/systemd/portables/, /usr/local/lib/portables/ and /usr/lib/portables/. The latter link-oriented paths are not good places for large image data.

$ portablectl --no-pager list
No images.

The output above is valid when no images are discovered. On a populated host, the listing includes brief image metadata and attachment state. This command does not attach anything. If your image lives elsewhere, you can still pass its full path to later commands.

2. Inspect the image before attaching it

Replace the placeholder with a path you trust. Inspection reads the image's os-release data and matching unit metadata; it does not install those units on the host. If the filename has no slash, portablectl searches its portable image paths. Prefix a file in the current directory with ./ to avoid that search behaviour.

$ portablectl --no-pager inspect /path/to/example_1.raw
NAME=example_1
TYPE=raw
...

$ portablectl --no-pager --cat inspect /path/to/example_1.raw

The short form is useful for checking which units would match. The --cat form prints the unprocessed os-release and unit-file contents, so treat anything in the image as data to review, not as instructions to run. If the image name does not produce the units you expect, pass one or more explicit prefixes after the image path:

$ portablectl --no-pager inspect /path/to/example_1.raw example

3. Choose the attachment boundary

The default profile is called default. It is intended for common unprivileged workloads and allows access to the logging framework and the system D-Bus. The nonetwork profile disables networking, strict is more restrictive and excludes network and D-Bus access, and trusted runs with full privileges. Choose deliberately: a profile is part of the service's security boundary.

By default, attachment is persistent. Use --runtime to put the attached unit files under /run/systemd/system.attached/; they then disappear at the next reboot. The --copy preference can be copy, symlink or auto. Raw images may force copying even when symlinking was requested.

4. Attach selected units

Attaching changes the host and normally requires elevated privileges. It copies matching unit files and drop-ins, may create a link into /etc/portables/ or /run/portables/, and reloads the service manager. Do not add --now until you have reviewed the image and are ready for its service to start.

$ sudo portablectl --no-pager \
    --profile=default --copy=auto \
    attach /path/to/example_1.raw example
Created symlink ...
Created ...

The exact change lines depend on the image. A successful command exits with status zero. If the image contains a unit already present on the system, attachment fails rather than silently replacing it. Resolve the name collision or choose a narrower prefix. When you do want an immediate start, use --now only after checking the unit names:

$ sudo portablectl --no-pager --now attach /path/to/example_1.raw example
$ systemctl status example.service

5. Verify the state and available units

Ask portabled for the image state. The useful states are detached, attached, attached-runtime, enabled, enabled-runtime, running and running-runtime. The state describes the image as a whole, so also inspect the particular unit if you used --now.

$ portablectl --no-pager is-attached /path/to/example_1.raw
attached
$ systemctl cat example.service

If is-attached reports a runtime state, the attachment is not persistent. If systemctl cat cannot find the unit, revisit the prefix used during attachment and the image inspection output. Do not infer success merely from a link in an image directory.

6. Detach and recover safely

Detaching removes the copied units, drop-ins and image link. It cannot normally proceed while a contained unit is running. Stop the service first, then detach with the same image name or path and prefix:

$ sudo systemctl stop example.service
$ sudo portablectl --no-pager detach /path/to/example_1.raw example
Removed ...
$ portablectl --no-pager is-attached /path/to/example_1.raw
detached

If the image was attached with --runtime, repeat that option when detaching so the intended runtime attachment is selected. If you used --extension=, repeat every extension in the same order. Extensions are overlaid images and their extension-release metadata must match the main image; the documented --force option bypasses safety checks and should be reserved for a reviewed recovery procedure, not a first attempt.

Done means

• You inspected the image and confirmed the expected os-release and unit names.
• You selected a profile, copy mode and persistent or runtime scope consciously.
• portablectl is-attached reports the state you intended.
• The service is healthy if it was started, and you know which command stops it.
• Detaching leaves the image at detached before you remove or replace it.