Getting Started with Incus on Fedora

First time initialization

Add user account to incus-admin group. This user will have administration permissions in Incus:

# usermod -a -G incus-admin <user>

Set sub{u,g}id range for mapping container users/groups to host UIDs/GIDs. For more information see man (5) subuid.

# echo "root:1000000:1000000000" >> /etc/subuid
# echo "root:1000000:1000000000" >> /etc/subgid

Enable and start the Incus daemon:

# systemctl enable --now incus

Run the daemon initialization (see Incus: Initial Configuration for more information):

# incus admin init

If the host runs firewalld the Incus bridge (defaults to incusbr0) must be added to the trusted zone otherwise the containers won't be able to communicate:

# firewall-cmd --zone=trusted --change-interface=incusbr0 --permanent
# firewall-cmd --reload

Start your first container

List available default images:

$ incus image list images:

Start your first container:

$ incus launch images:fedora/39

Start your first virtual machine

Ensure you have the necessary packages installed. See the Installation Instructions.

First create a new profile for your virtual machine(s):

$ incus profile create virtualmachine
$ incus profile edit virtualmachine

Now paste the profile definition. This will store the cloud-init configuration. Import is that secure boot must be disabled because Fedora is missing the corresponding UEFI files. You can also add SSH public keys or many other cloud-init definitions:

config:
  security.secureboot: "false"
  user.user-data: |
    #cloud-config
    ssh_pwauth: yes
    users:
    - name: vagrant
      passwd: "$6$wBwgyPQYbcR2au8u$r/2VnQJGak0OSH794cO2Glcnowu6joy4XSAYMEEUnVfPRuMVbMl.a3R.qy0GldG9XxhI3jbOBDobhwZFXSvC21"
      lock_passwd: false
      shell: /bin/bash
      sudo: ALL=(ALL) NOPASSWD:ALL
description: Incus profile for virtual machines
devices:
  config:
    source: cloud-init:config
    type: disk
  eth0:
    nictype: bridged
    parent: incusbr0
    type: nic
  root:
    path: /
    pool: default
    type: disk
name: virtualmachine
used_by: []

Launch the virtual machine by passing the new profile and the --vm flag:

$ incus launch images:fedora/39/cloud --profile virtualmachine --vm

Manage less privileged Incus users

You can also have less privileged users which are restricted to manage container or VM instances in a user-specific Incus project. Such users must be added to the incus group:

# usermod -a -G incus <user>

Add a UID/GID mapping for the unprivileged user:

# echo "root:1000:1" >> /etc/subuid
# echo "root:1001:1" >> /etc/subgid

Ensure the incus-user daemon is enabled and running:

# systemctl enable --now incus-user

Now the user can define its own profiles and instances and other users cannot interfere with it.

Serve documentation via Incus API

It's possible to serve the Incus documentation available via incus-doc RPM via the Incus API:

# dnf install incus-doc

If not already done enable network access to the Incus API. E.g.:

# incus config set core.https_address :8443
# systemctl restart incus

Eventually the documentation is exposed via /documentation endpoint (e.g. https://localhost:8443/documentation).