portablectl: Managing Portable Service Images

Introduction

portablectl is a systemd utility for managing portable service images on Linux. It helps you discover, attach, inspect, and detach portable services without installing full packages.

Quick start: core commands

These commands form the core workflow when working with portable service images.

List available portable images

portablectl list

This shows portable images discovered in the search paths. If nothing appears, you may need to add or update search paths.

Attach a portable image to the host

portablectl attach /path/to/image

Attaches the specified portable image so its service(s) can run on the host. Be sure the image is compatible with your system and architecture.

Detach a portable image from the host

portablectl detach /path/to/image-or-image-name

Detaches the image, stopping any services provided by it. You can specify either the image path or its name as shown by the attach step.

Inspect an image for details

portablectl inspect /path/to/image

Displays metadata, such as the image name, version, and service configuration. Useful for verification before attach.

Check if an image is attached

portablectl is-attached /path/to/image-or-image-name

Returns a simple yes/no indicating whether the image is currently attached to the host.

Practical workflow example

  1. Discover available images:
portablectl list
  1. Inspect a candidate to confirm details:
portablectl inspect /path/to/image
  1. Attach the image if you’re ready:
portablectl attach /path/to/image
  1. Verify attachment:
portablectl is-attached /path/to/image
  1. When done, detach:
portablectl detach /path/to/image

Common pitfalls

  • Incorrect path or image name: Ensure you’re using the exact path or name shown by portablectl list/inspect.
  • Attaching incompatible images: Check architecture and OS compatibility in the image metadata before attach.
  • Not updating search paths: If list is empty, you may need to add search paths or refresh caches.
  • Permissions: Running portablectl generally requires root or appropriate user privileges.

Tips and best practices

  • Always inspect before attach to avoid surprises.
  • Use is-attached to script validation steps in automation.
  • Keep portable images up to date; periodic updates help avoid stale images.

Further reading

For more details and advanced usage, see the systemd portablectl documentation:

See Also