Packaging recommendations

Below are a few recommendations for packagers of Incus.

Following those recommendations should provide a more predictable experience across Linux distributions.

Packages

It’s usually a good idea to at least split things into an incus and incus-client package. The latter allows for installing just the incus command line tool without bringing the daemon and its dependencies.

Additionally, it may be useful to have an incus-tools package with some of the less commonly used tools like fuidshift, lxc-to-incus, incus-benchmark and incus-migrate.

Groups

Two groups should be provided:

  • incus-admin which grants access to the unix.socket socket and effectively grants full control over Incus.

  • incus which grants access to the user.socket socket which provides users with a restricted Incus project.

Init scripts

The following assumes the use of systemd. Distributions not using systemd should try to stick to a similar naming scheme but will likely see some differences on things like socket activation.

  • incus.service is the main unit that starts and stops the incusd daemon.

  • incus.socket is the socket-activation unit for the incus.service unit. If present, incus.service should not be made to start on its own.

  • incus-user.service is the unit responsible for starting and stopping the incus-user daemon.

  • incus-user.socket is the socket-activation unit for the incus-user.service unit. If present, incus-user.service should not be made to start on its own.

  • incus-startup.service uses the incusd activateifneeded command to trigger daemon startup if it is required. It also calls incusd shutdown to handle orderly shutdown of instances on host shutdown.

Binaries

The incusd and incus-user daemons should be kept outside of the user’s PATH. The same is true of incus-agent which needs to be available in the daemon’s PATH but not be visible to users.

The main binary that should be made visible to users is incus.

On top of those, the following optional binaries may also be made available:

  • fuidshift (should be kept to root only)

  • incus-benchmark

  • incus-migrate

  • lxc-to-incus

  • lxd-to-incus (should be kept to root only)

Incus agent binaries

There are two ways to provide the incus-agent binary.

Single agent setup

The simplest way is to have incus-agent be available in the PATH of incusd.

In this scenario the agent should be a static build of incus-agent for the primary architecture of the system.

Multiple agent setup

Alternatively, it’s possible to provide multiple builds of the incus-agent binary, offering support for multiple architectures or operating systems.

To do that, the INCUS_AGENT_PATH environment variable should be set for the incusd process and point to a path that includes the incus-agent builds.

Those builds should be named after the operating system name and architecture. For example incus-agent.linux.x86_64, incus-agent.linux.i686 or incus-agent.linux.aarch64.

Documentation

Web documentation

Incus can serve its own documentation when the network listener is enabled (core.https_address).

For that to work, the documentation provided in the release tarball should be shipped as part of the package and its path be passed to Incus through the INCUS_DOCUMENTATION environment variable.

Manual pages

While we don’t specifically write full manpage entries for Incus, it is possible to generate those from the CLI.

Running incus manpage --all --format=man /target/path will generate a separate page for each command/sub-command.

This is effectively the same as what’s otherwise made available through --help, so unless a distribution packaging policy requires all binaries have manpages, it’s usually best to rely on --help and help sub-commands.