portablectl

List available portable service images discovered in the portable image search paths

$ portablectl list

$ portablectl attach [path/to/image]

$ portablectl detach [path/to/image|image_name]

$ portablectl inspect [path/to/image]

$ portablectl is-attached [path/to/image|image_name]

portablectl [OPTIONS...] COMMAND [ARGUMENTS...]

portablectl list [NAME...]
portablectl status [NAME...]
portablectl attach IMAGE [NAME]
portablectl detach [NAME...]
portablectl import PATH [NAME] [--reflink[=BOOL]]
portablectl reflink SOURCE DESTINATION
portablectl remove [NAME...]
portablectl update
portablectl reload

COMMAND
    The specific operation to perform (e.g., attach, detach, list, import, remove).

ARGUMENTS
    Arguments specific to the chosen command, such as image paths or portable service names.

--root=PATH
    Operate on a different root directory for portable images, instead of the default /var/lib/portable.

--force, -f
    Force the operation, overriding certain checks or warnings.

--json=MODE
    Show output as JSON, with different modes like 'pretty' or 'short'.

--no-pager
    Do not pipe output into a pager.

--help, -h
    Display a brief help message and exit.

--version
    Show version information and exit.

--reflink[=BOOL]
    For import, use reflink (copy-on-write) if the underlying filesystem supports it (e.g., Btrfs, XFS). Default is true.

--dry-run
    For import or remove, perform a trial run without making actual changes.

--read-only
    For attach, mount the portable image in read-only mode.

--template=NAME
    For attach, specify a different systemd unit template to use for the portable service.

portablectl is a command-line utility used to manage portable services and disk images on Linux systems. It is a component of systemd-portabled, a daemon that allows systemd units (services, sockets, etc.) to be encapsulated within a disk image and run independently from the host's /usr or /etc hierarchies.

This enables applications or entire environments to be easily moved between systems without complex installation procedures or dependency conflicts. The command facilitates attaching, detaching, importing, and removing these portable images. When an image is 'attached,' its contents become available to the host system via a bind mount, and its systemd units can be started and managed like any other systemd service, but with their root directory relocated to the image. This provides a lightweight container-like environment without requiring a full container runtime. Its primary goal is to simplify application deployment and migration across different Linux distributions and versions.

• Most portablectl operations (e.g., attach, import, remove) require root privileges.
• Portable images are typically stored in /var/lib/portable by default.
• The reflink functionality for efficient copying requires filesystems that support copy-on-write (e.g., Btrfs, XFS).
• portablectl provides lightweight service encapsulation, not a full container solution. It's designed for systemd service portability rather than comprehensive process isolation or virtualization.
• Portable services run with systemd, and their privileges should be carefully considered to maintain host security.

A portable service is a systemd unit (or set of units) along with its dependencies (binaries, libraries, configuration) encapsulated within a single disk image. This image can then be 'attached' to a host system, making the service available to systemd without requiring the host to have all dependencies installed globally or interfering with the host's filesystem hierarchy.

By default, portablectl manages and stores portable images within the /var/lib/portable directory on the host system. When an image is attached, it creates a bind mount point under this directory, making its internal filesystem accessible to the host and allowing systemd to find and manage its services.

portablectl is an integral part of the systemd project and was introduced with the systemd-portabled daemon, which became available around systemd version 248 (released in late 2020 / early 2021). Its development aimed to provide a lightweight mechanism for distributing and running systemd services in a portable manner. This simplifies application deployment by leveraging native Linux kernel features like bind mounts and namespaces, offering a less resource-intensive alternative to traditional container runtimes for simple service isolation and portability.

systemd-portabled(8), systemd.portable(5), systemd(1), btrfs(8)