Attach and Safely Remove a systemd Portable Service

You will finish with a controlled workflow for inspecting a portable service image, attaching its matching units, starting one deliberately, checking the result, and detaching it again. The examples use portablectl with the systemd 255.4-1ubuntu8.17 package installed on this machine.

Allow about twenty minutes, plus time to understand the image you have been given. You need a Linux host using systemd, the systemd-container package, a portable service image, and root access for attach, detach and service-management operations. This guide does not create an image or invent a unit name. It uses an existing image path represented by IMAGE_PATH.

1. Check the installed service and command

The manpage describes systemd-portabled as a system service for attaching, detaching and inspecting portable service images. Most of its interface is exposed through portablectl. Check the package and command as ordinary, read-only operations:

$ systemctl --version
systemd 255
$ dpkg-query -W -f='${Package} ${Version}\n' systemd-container
systemd-container 255.4-1ubuntu8.17
$ command -v portablectl
/usr/bin/portablectl
$ systemctl status systemd-portabled.service --no-pager

The service may be inactive until a request needs it. That is not, by itself, a failure. The unit is activated through its D-Bus service name when portablectl talks to it. If the command reports a missing unit or executable, stop here and install the distribution package that supplies systemd-portabled before continuing.

2. Inspect the image without attaching it

Set an explicit path. A path containing a slash is unambiguous and avoids portablectl searching its portable-image paths by name:

$ IMAGE_PATH='/srv/portables/REPLACE-ME.raw'
$ sudo portablectl inspect "$IMAGE_PATH"
Image:
        ...
        Units:
        ...

The exact summary depends on the image. The useful questions are whether it contains a valid os-release, which service, socket, target, timer or path units match, and which unit prefix you intend to attach. For a fuller review, use --cat to display the image's os-release data and matching unit contents:

$ sudo portablectl inspect --cat "$IMAGE_PATH"

A suitable image normally contains an OS tree or raw disk image, an os-release file, and at least one matching unit. Inspecting does not copy units to the host and does not start a service. If inspection fails, do not try --force as a diagnostic shortcut. Fix the image or its path first.

3. Attach only the units you reviewed

By default, attach derives a prefix from the image filename and copies matching .service, .socket, .target, .timer and .path units into the host's attached-unit directory. A version suffix after an underscore is ignored when deriving that prefix. Pass a prefix explicitly when the filename does not make the intended selection obvious:

$ sudo portablectl attach "$IMAGE_PATH" SERVICE_PREFIX
  ✓ Image SERVICE_PREFIX.raw attached successfully

The success wording can vary with the systemd build. The important result is a zero exit status. The operation creates host-side unit copies and drop-ins, including the image root setting and a security profile. It normally reloads the system manager. It does not enable or start the copied units unless you ask for --enable or --now.

Do not combine this first attach with --now. Starting image code is a separate decision. If you need a reboot-only test, --runtime keeps the attachment under /run until the next reboot. It is still a live host change and should be removed deliberately when testing is complete.

$ portablectl is-attached "$IMAGE_PATH"
yes
$ systemctl cat SERVICE_PREFIX.service
$ systemctl daemon-reload

portablectl is-attached is a query. systemctl cat lets you confirm the selected unit and its drop-ins before starting it. The final reload is harmless but normally unnecessary after a successful attach; it is shown as an explicit checkpoint when you are reviewing a machine manually.

4. Start and verify the service separately

Start the exact unit you reviewed. This is an elevated, service-disrupting action because it can launch a daemon and bind resources:

$ sudo systemctl start SERVICE_PREFIX.service
$ systemctl is-active SERVICE_PREFIX.service
active
$ systemctl status SERVICE_PREFIX.service --no-pager

Use journalctl -u SERVICE_PREFIX.service to investigate a failed start. An active unit proves that systemd accepted the start and the process is still considered running; it does not prove that the daemon is healthy for clients. Verify the daemon's own health check, listening socket or expected log message when the service provides one.

Portable services are regular systemd services rooted in the image, not a separate virtual machine. The default portable profile applies restrictions; trusted, strict and nonetwork have materially different security consequences. Treat a profile selection as a security decision and review the resulting unit properties before production use.

5. Stop and detach to undo the host change

When testing is finished, stop the unit before removal. If you enabled it, disable it as well:

$ sudo systemctl disable --now SERVICE_PREFIX.service
$ sudo portablectl detach "$IMAGE_PATH" SERVICE_PREFIX
$ portablectl is-attached "$IMAGE_PATH"
no

detach removes the copied unit files, drop-ins and any image symlink created for the attachment. With --runtime, the files were under /run and disappear at reboot, but an explicit detach still makes the current state clear. If you did not enable the unit, use sudo systemctl stop SERVICE_PREFIX.service instead of the combined disable command.

6. Replace an image with reattach

For a reviewed replacement at a new versioned filename, reattach combines detach and attach. It is available in the installed systemd 255 interface:

$ sudo portablectl reattach '/srv/portables/SERVICE_PREFIX_REPLACE.raw' SERVICE_PREFIX
$ portablectl is-attached '/srv/portables/SERVICE_PREFIX_REPLACE.raw'
yes

Do not remove the old image until the replacement has been verified and detached from any old reference. Without --now, reattach changes the attached units but does not start them. Plan the service stop, restart and rollback behaviour yourself, especially if the daemon owns state or a listening endpoint.