Project: lxd (Runtime / Container Runtime)
File: packaging.md

Below are a few recommendations for packagers of Incus. Following those recommendations should provide a more predictable experience across Linux distributions. 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`. 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. 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. 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) There are two ways to provide the `incus-agent` binary. 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. 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 `INCUSAGENTPATH` 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`. 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. 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.