Attach Portable Services Safely with portablectl

Someone hands you a raw disk image and expects it to run here, and portablectl is what attaches it without hand-copying units around. This guide inspects a portable service image, attaches its matching units, checks the result, then detaches it cleanly. Allow about 10 minutes if you already have a suitable image.

You need a portable service image and root access for any change. 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: a service API, not a config file you edit by hand. The 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 plus whatever those units need. Attaching it makes selected .service, .socket, .target, .timer and .path units available to the host. Service units get settings such as RootDirectory= or RootImage= so they run against the image's own filesystem.

Checkpoint: confirm the client and package version before relying on any 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 a good place for large image data.

$ portablectl --no-pager list
No images.

That output is valid when no images are discovered. On a populated host, the listing includes brief metadata and attachment state. This command attaches nothing. 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 image paths, so prefix a file in the current directory with ./ to avoid that search.

$ 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 tells you 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 instructions to run. If the image name does not surface 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 default: intended for common unprivileged workloads, with access to the logging framework and system D-Bus. nonetwork disables networking, strict is tighter still and excludes network and D-Bus access, and trusted runs with full privileges. Choose deliberately: the profile is part of the service's security boundary, not a formality.

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

4. Attach selected units

Attaching changes the host and normally needs 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 outright rather than silently replacing it: resolve the name collision or use a narrower prefix. When you do want an immediate start, add --now only after you have checked 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 values are detached, attached, attached-runtime, enabled, enabled-runtime, running and running-runtime. The state describes the image as a whole, so also check the specific 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 will not survive a reboot. If systemctl cat cannot find the unit, revisit the prefix you used during attachment and the earlier inspection output. Do not infer success from a link showing up in an image directory: check the state directly.

6. Detach and recover safely

Detaching removes the copied units, drop-ins and image link. It normally cannot proceed while a contained unit is running, so stop the service first:

$ 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. 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 those safety checks and belongs in a reviewed recovery procedure, not a first attempt.