Incus

Incus is a manager/hypervisor for containers (via LXC) and virtual-machines (via QEMU).

It is a fork of LXD by the original maintainers. Documentation from the LXD wiki page is still largely relevant and encouraged reading.

Installation

Install the incus package, then enable the incus.socket.

Alternatively, you can enable/start the incus.service directly, in case you want instances to autostart for example.

To delegate container creation to users, enable/start the incus-user.socket unit. See #Accessing Incus as an unprivileged user for group delegation.

Migrating from LXD

If you wish to migrate from an existing LXD installation, you should do so at this point, as the migration tool will only run against an empty target Incus server.

After verifying that both the lxc info and incus info commands are running correctly, read the upstream documentation about the process, and afterwards run the migration tool:

# lxd-to-incus

Configuration

Unprivileged containers

It is recommended to use unprivileged containers (See Linux Containers#Privileged or unprivileged containers for an explanation of the difference).

For this, modify both /etc/subuid and /etc/subgid (if these files are not present, create them) to contain the mapping to the containerized uid/gid pairs for each user who shall be able to run the containers. The example below is simply for the root user (and systemd system unit):

You can either use usermod as follows:

usermod -v 1000000-1000999999 -w 1000000-1000999999 root

Or modify the above mentioned files directly as follows:

/etc/subuid

root:1000000:1000000000

/etc/subgid

root:1000000:1000000000

Now, every container will be started unprivileged by default.

For the alternative, see LXD#Privileged containers.

Configure Incus

On the first start, Incus needs to be configured.

Run as root:

# incus admin init

This will start an interactive configuration guide in the terminal, that covers different topics like storages, networks etc.
You can find an overview in the official Getting Started Guide.

Accessing Incus as an unprivileged user

Incus defines two user groups:

incus "allows basic user access, no configuration and all actions restricted to a per-user project."
incus-admin "allows full control over Incus."

To control Incus without having to run all commands as root, add your user to these groups.

Warning: Anyone added to the incus-admin group is root equivalent. For more information, see [1] and [2].

Usage

Overview of commands

You can get an overview of all available commands by typing:

$ incus

Create a container

You can create a container with incus launch, for example:

$ incus launch ubuntu:20.04

Container are based on images, that are downloaded from image servers or remote LXD servers.

You can see the list of already added servers with:

$ incus remote list

You can list all images on a server with incus image list, for example:

$ incus image list images:

This will show you all images on one of the default servers: images.linuxcontainers.org

You can also search for images by adding terms like the distribution name:

$ incus image list images:debian

Launch a container with an image from a specific server with:

$ incus launch servername:imagename

For example:

$ incus launch images:centos/8/amd64 centos

To create an amd64 Arch container:

$ incus launch images:archlinux/current/amd64 arch

Tips and tricks

Access the containers by name on the host

This assumes that you are using the default bridge that it is named incusbr0 and that you are using systemd-resolved.

# systemd-resolve --interface incusbr0 --set-domain '~incus' --set-dns $(incus network get incusbr0 ipv4.address | cut -d / -f 1)

You can now access the containers by name:

$ ping containername.incus

Troubleshooting

Starting a virtual machine fails

If you see the error:

Error: Couldn't find one of the required UEFI firmware files: [{code:OVMF_CODE.4MB.fd vars:OVMF_VARS.4MB.ms.fd} {code:OVMF_CODE.2MB.fd vars:OVMF_VARS.2MB.ms.fd} {code:OVMF_CODE.fd vars:OVMF_VARS.ms.fd} {code:OVMF_CODE.fd vars:qemu.nvram}]

It's because Arch Linux does not distribute secure boot signed ovmf firmware. To boot virtual machines, you need to disable secure boot for the time being:

$ incus launch ubuntu:18.04 test-vm --vm -c security.secureboot=false

This can also be added to the default profile by doing:

$ incus profile set default security.secureboot=false

Incus does not respect Shell's environment proxy variables

Examples are incus launch or incus image commands not using value of *_proxy/*_PROXY variables when downloading images.

Incus implements a server-client paradigm. It simply means that operations are done by incusd acting as the Incus server — usually running in the background, unless invoked from an interactive shell. And incus commandline interface is used to communicate with Incus server acting as the Incus client.

That makes incusd, typically started as a service, not inheriting shell's environment variables of the client. But respecting variables of the environment that it's invoked from, instead.[3] In Arch Linux, Incus server is started by systemd.

There can be many workarounds to this difficulty, following exist some examples. See Incus's issue#574 for more information.

Temporary

Import Shell variables to systemd's environment

First, export *_PROXY variables:

$ export ALL_PROXY="socks://proxy_server_address:port/"

Import them to systemd's environment:

# systemctl import-environment ALL_PROXY

Re/start incus.service unit.

Tip: Use systemctl unset-environment command to unset a variable and restart the service.

Persistent

Edit incus service unit

If you want Incus daemon to always start with some static environment variables, like *_proxy, you can use Environment directive of systemd. systemctl set-property command cannot manipulate Environment directive. Edit incus.service and add Environment key with appropriate variable=value pair. For example:

# systemctl edit incus.service

...

[Service]
Environment=ALL_PROXY="socks://proxy_server_address:port/"

...

Use Incus core.proxy options

One can make Incus server use a desired proxy with configuring Incus's server with core.proxy options. For instance:

# incus config set core.proxy_http "proxy_address:proxy_port"

Note: core.proxy options have global scopes. I.e. they apply to cluster members, immediately.

Uninstall

Stop and disable the services. Then uninstall the incus package.

If you want to remove all data:

# rm -r /var/lib/incus

If you used any of the example networking configuration, you should remove those as well.