Recently, the larger LXD project was transferred to Canonical. Due to a change in licensing after the transition, LXD is no longer viable to use; however, a fork of LXD called incus was made by the original development team, which we can safely consume.

However, this means that updating the manager is not as straightforward as it may seem. In this guide, we will help you transition your v1.X.X.X install to v2.X.X.X.

Install incus

First, install incus:

  1. Gentoo: root # emerge incus
  2. Arch: root # pacman -S incus
  3. Ubuntu: root # apt install incus

After that, make sure your user is in the incus and incus-admin groups:

  1. root # usermod -a -G incus,incus-admin my-user

At this point, it is recommended to reboot/log out of the session to update the groups.

Finally, start the Incus daemon and set it to launch by default:

  1. OpenRC: root # /etc/init.d/incus start && rc-service add incus default
  2. systemd: root # systemctl start incus.service && systemctl enable incus.service

Next, set up the incus daemon:

  1. Initialise the daemon: incus admin init --auto --storage-backend=dir
  2. Set up the network bridge settings: incus network set incusbr0 ipv6.nat=false ipv6.address=none
  3. Restart the daemon:
    1. OpenRC: root # /etc/init.d/incus restart
    2. systemd: root # systemctl restart incus.service

Transfer containers from LXD to Incus

First, we have to connect LXD with Incus:

  1. Configure them to listen on the same network: lxc config set core.https_address :8444 && incus config set core.https_address :8443
  2. Add LXD remote in Incus: incus remote add my-lxd unix:///var/lib/lxd/unix.socket. Note: the location may be different, i.e. /var/snap/lxd/common/lxd/
  3. List the LXD containers from Incus: incus list my-lxd:. If all is successful, they should appear.
  4. Stop all active LXD containers using: lxc stop <container-name-here>
  5. Transfer the container: incus move my-lxd:<container-name-here> local:
  6. Finally, close the connection: lxc config unset core.https_address && incus config unset core.https_address

Update the application

Now, update the application to v2.X.X.X. All code referencing LXD has now been transferred to incus, so not much has to be done.

Bonus: Transferring virtual machines from LXD to Incus

This bonus chapter is for users who also have LXD VMs that they want to transfer to Incus.

Creating a test VM

First, we need to check if Incus is capable of creating a VM. Simply run incus create test-vm --vm --empty. If the VM was created successfully, go to the next heading.

If you get an error like the following:

Error: Failed creating instance record: Instance type "virtual-machine" is not supported on this server: QEMU failed to run feature checks

Stop the Incus service:

  1. OpenRC: root # /etc/init.d/incus stop
  2. SystemD: root # systemctl stop incus.service

Next, run the Incus daemon from a terminal: root # incusd.

This should produce an understandable error. One of the most common ones is the following:

ERROR  [2024-02-26T18:56:09+02:00] Unable to run feature checks during QEMU initialisation: Unable to locate a UEFI firmware

This is fixed by adding an environment variable that points to the edk2 directory that holds the OVMF_CODE.fd & OVMF_VARS.fd files:

export INCUS_OVMF_PATH=/usr/share/edk2-ovmf

Check with your local system, as it's usually either edk2 or edk2-ovmf. Additionally, make sure you have the edk2-ovmf package installed.

With the new environment variable, the empty container should be created without an issue.

Transferring the VM

Do the following:

  1. Make sure the Incus daemon is running and that you can create a VM
  2. Expose Incus to the network: incus config set core.https_address :8443
  3. Run incus-migrate
  4. Enter your local IP: Please provide Incus server URL: 0.0.0.0
  5. Accept the fingerprint
  6. Select option 1 to use a token.
  7. In a separate terminal, generate a token using incus config trust add local:0.0.0.0:8443
  8. Paste the token output into the wizard
  9. Select option 2 for a virtual machine
  10. Set the name of the VM
  11. Find the location of the image of your LXD VM, usually under /var/lib/lxd/virtual-machines/<insert-vm-name>/<image-name>.img.
  12. Paste the location into the wizard
  13. Disable UEFI Secure Boot
  14. Select option 3 and set your CPU core allowance. Example: limits.cpu=12
  15. Select option 3 and set your RAM allowance. Example: limits.memory=16GiB
  16. Select option 1 and wait for the VM to be migrated
  17. Once migrated, try launching the VM using Incus