Diff for "Incus" - Debian Wiki

Differences between revisions 20 and 21

Incus is a community fork of LXD, a next generation system container and virtual machine manager. Debian packages LTS releases of Incus, beginning with trixie.

Contents

Supported versions of Incus
Installation
Known issues
References
Debian-specific information

Supported versions of Incus

Incus (upstream) has the following releases:

Version	EOL	In Debian release
6.0 LTS	~April 2029	Trixie (anticipated; as of January 2024, pre-LTS version 0.4 is packaged)

Installation

Installing on Debian is as simple as installing the incus package:

```
sudo apt install incus
```

Incus initialization

If you wish to migrate existing containers or VMs from LXD, please refer to the next section. Otherwise, after installing Incus you must perform an initial configuration:

```
sudo incus admin init
```

Migrating from LXD

Incus includes a tool named lxd-to-incus which can be used to convert an existing LXD installation into an Incus one.

For this to work properly, you should install Incus but not initialize it. Instead, make sure that both incus info and lxc info both work properly, then run lxd-to-incus to migrate your data.

This process transfers the entire database and all storage from LXD to Incus, resulting in an identical setup after the migration.

For further information, please view the migration HOWTO.

$/!\$ This should be considered a destructive action from LXD's perspective. Afterwards the LXD daemon may not properly start, and running lxc list will be empty. It is recommend that the LXD packages be purged as part of running lxd-to-incus, or by hand immediately following the migration.

Configuration

Incus's default bridge networking requires the dnsmasq-base package to be installed. If you chose to install Incus without its recommended packages and intend to use the default bridge, you must first install dnsmasq-base for networking to work correctly.

If you wish to allow non-root users to interact with Incus via the local Unix socket, you must add them to the incus group:

```
    sudo usermod -aG incus <username>
```

Access via the incus group grants restricted access to Incus, allowing members to run most commands, except incus admin. For the vast majority of use cases, this is the preferred setup.

Alternatively, if you wish to allow non-root users full administrative access to Incus via the local Unix socket, you must add them to the incus-admin group:

    sudo usermod -aG incus-admin <username>

$/!\$ From the upstream documentation, be aware that local access to Incus through the Unix socket via the incus-admin group always grants full access to Incus. This includes the ability to attach file system paths or devices to any instance as well as tweak the security features on any instance. Therefore, you should only give access to users who would be trusted with root access to the host.

Storage backends

Incus supports several storage backends. When installing, Incus will suggest the necessary packages to enable all storage backends, but in brief:

btrfs requires the btrfs-progs package
ceph/cephfs require the ceph-common package
lvm requires the lvm2 package
zfs requires the zfsutils-linux package

After installing one or more of those additional packages, be sure to restart the Incus service so it picks up the additional storage backend(s).

Virtual machines

Incus optionally can create virtual machine instances utilizing QEMU. To enable this capability, on the host system install the desired qemu-system-<arch> package(s) and the incus-agent package. Then, restart the Incus service. You will now be able to create virtual machine instances by passing the --vm flag in your creation command.

Loki integration disabled

For the time being, Loki logging integration is disabled, due to the build dependency golang-github-grafana-dskit not being packaged. For updates on that, please see 1001989.

Known issues

Incus 0.4 has a bug with uidmapping when using incus-user. Upon starting a container, you will receive an error "newuidmap failed to write mapping". To work around this, prior to creating any containers run incus profile unset default raw.idmap. This has been fixed in the main branch, and will be fixed in the 0.5 release.
Running Incus and Docker on the same host can cause connectivity issues. A common reason for these issues is that Docker sets the FORWARD policy to DROP, which prevents Incus from forwarding traffic and thus causes the instances to lose network connectivity. There are two different ways you can fix this:
- As outlined in bug 865975, message 91, you can add net.ipv4.ip_forward=1 to /etc/sysctl.conf which will create a FORWARD policy that docker can use. Docker then won't set the FORWARD chain to DROP when it starts up.
- Alternately, you can use the following command to explicitly allow network traffic from your network bridge to your external network interface: iptables -I DOCKER-USER -i <network_bridge> -o <external_interface> -j ACCEPT (from the upstream Incus documentation)
If the apparmor package is not installed on the host system, containers will fail to start unless their configuration is modified to include lxc.apparmor.profile=unconfined; this has been reported upstream at https://github.com/lxc/lxc/issues/4150.

References

Debian-specific information

Bugs
package tracker
Manpages
security tracker

-  ⇤ ← Revision 20 as of 2024-01-06 01:37:26 → 
  Size: 2132
  Editor: MathiasGibbens
  Comment:
+   ← Revision 21 as of 2024-01-13 14:48:37 → ⇥
  Size: 6453
  Editor: MathiasGibbens
  Comment: Rewrite page to reflect Incus inclusion in Debian
-Deletions are marked like this.
+Additions are marked like this.
 Line 1:
-'''Incus''' is a community-fork of the LXD project: https://linuxcontainers.org/incus/.
+'''Incus''' is a community fork of LXD, a next generation system container and virtual machine manager. Debian packages LTS releases of Incus, beginning with [[DebianTrixie|trixie]].
 Line 3:
-@freee and @gibmat are working on packaging Incus for Debian, and currently this page serves as a ''TODO'' of blocking tasks.
+<<TableOfContents(3)>>
 Line 5:
-Main ITP bug: DebianBug:1042989
-Line 7:
+Line 6:
-== Dependencies that need to be packaged / updated ==
+== Supported versions of Incus ==
-Line 9:
+Line 8:
- * golang-github-grafana-dskit (ITP DebianBug:1001989)
  * Depends on DebianPkg:golang-github-go-redis-redis-dev (>= 8.11.5)
  * Depends on golang-github-hashicorp-consul-dev, which was RM'ed in DebianBug:1055054
  * Might depend on DebianPkg:golang-github-sercand-kuberesolver-dev (>= 5.1.1)
  * Patches applied to use older versions of grpc and etcd as currently packaged
+Incus (upstream) has the following releases:
-Line 15:
+Line 10:
- * lxd (need to add a golang-github-canonical-lxd-dev binary package)
  * Currently in NEW queue
+|| Version || EOL                                                      || In Debian release                                                         ||
|| 6.0 LTS || [[https://github.com/lxc/incus/milestone/6|~April 2029]] || Trixie (anticipated; as of January 2024, pre-LTS version 0.4 is packaged) ||
-Line 18:
+Line 13:
-== Other things to resolve ==
+== Installation ==
-Line 20:
+Line 15:
- * Both LXD and Incus build a `fuidshift` binary. How do we want to handle this packaging conflict?
+Installing on Debian is as simple as installing the DebianPkg:incus package:
-Line 22:
+Line 17:
-== Old notes ==
+    {{{
sudo apt install incus
}}}
-Line 24:
+Line 21:
-=== golang-github-hashicorp-golang-lru-dev ===
+=== Incus initialization ===
-Line 26:
+Line 23:
-Somehow @gibmat missed that golang-github-hashicorp-golang-lru-v2-dev was already packaged, so the work below isn't directly on the critical path for Incus.
+If you wish to migrate existing containers or VMs from LXD, please refer to the next section. Otherwise, after installing Incus you must perform an initial configuration:
-Line 28:
+Line 25:
-golang-github-hashicorp-golang-lru-dev has several reverse build dependencies that will need to be updated along with it. v2 of the lru library switched to using generics, which is the main source of build failures in its rdeps:
+    {{{
sudo incus admin init
}}}
-Line 30:
+Line 29:
- * golang-github-hashicorp-golang-lru (0.5.4-3 -> 2.0.7-1; changes staged in salsa)
  * delve
  * golang-github-gcla-gowid (1.4.0-1 -> 1.4.0-2; changes staged in salsa)
   * termshark (2.4.0-1 -> 2.4.0-2; changes staged in salsa)
  * golang-github-hashicorp-go-immutable-radix (1.3.1-3 -> 2.1.0-1; changes staged in salsa)
   * deck
   * dnscrypt-proxy
   * docker.io
   * goiardi
   * golang-github-armon-go-metrics (0.4.1-1 -> 0.4.1-2; changes staged in salsa -- there are 38 rdeps on this package, so for now just do a minimal patch and later we can update to the latest version)
   * golang-github-hashicorp-go-memdb (TBD, likely needs work)
   * prometheus-alertmanager
  * golang-github-throttled-throttled
  * syncthing
+=== Migrating from LXD ===

Incus includes a tool named `lxd-to-incus` which can be used to convert an existing LXD installation into an Incus one.

For this to work properly, you should install Incus but not initialize it. Instead, make sure that both `incus info` and `lxc info` both work properly, then run `lxd-to-incus` to migrate your data.

This process transfers the entire database and all storage from LXD to Incus, resulting in an identical setup after the migration.

For further information, please view the [[https://linuxcontainers.org/incus/docs/main/howto/server_migrate_lxd/|migration HOWTO]].

/!\ This should be considered a destructive action from LXD's perspective. Afterwards the LXD daemon may not properly start, and running `lxc list` will be empty. It is recommend that the LXD packages be purged as part of running `lxd-to-incus`, or by hand immediately following the migration.

=== Configuration ===

Incus's default bridge networking requires the DebianPkg:dnsmasq-base package to be installed. If you chose to install Incus without its recommended packages and intend to use the default bridge, you must first install dnsmasq-base for networking to work correctly.

If you wish to allow non-root users to interact with Incus via the local Unix socket, you must add them to the `incus` group:

    {{{
    sudo usermod -aG incus <username>
}}}

Access via the incus group grants restricted access to Incus, allowing members to run most commands, except `incus admin`. For the vast majority of use cases, this is the preferred setup.

Alternatively, if you wish to allow non-root users full administrative access to Incus via the local Unix socket, you must add them to the `incus-admin` group:

    {{{
    sudo usermod -aG incus-admin <username>
}}}

/!\ From the [[https://linuxcontainers.org/incus/docs/main/security/|upstream documentation]], be aware that local access to Incus through the Unix socket via the `incus-admin` group always grants full access to Incus. This includes the ability to attach file system paths or devices to any instance as well as tweak the security features on any instance. Therefore, you should only give access to users who would be trusted with root access to the host.

=== Storage backends ===

Incus supports several storage backends. When installing, Incus will suggest the necessary packages to enable all storage backends, but in brief:

  * btrfs requires the DebianPkg:btrfs-progs package
  * ceph/cephfs require the DebianPkg:ceph-common package
  * lvm requires the DebianPkg:lvm2 package
  * zfs requires the DebianPkg:zfsutils-linux package

After installing one or more of those additional packages, be sure to restart the Incus service so it picks up the additional storage backend(s).

=== Virtual machines ===

Incus optionally can create virtual machine instances utilizing QEMU. To enable this capability, on the host system install the desired qemu-system-<arch> package(s) and the DebianPkg:incus-agent package. Then, restart the Incus service. You will now be able to create virtual machine instances by passing the `--vm` flag in your creation command.

=== Loki integration disabled ===

For the time being, Loki logging integration is disabled, due to the build dependency golang-github-grafana-dskit not being packaged. For updates on that, please see DebianBug:1001989.

== Known issues ==

  * Incus 0.4 has a bug with uidmapping when using `incus-user`. Upon starting a container, you will receive an error "newuidmap failed to write mapping". To work around this, prior to creating any containers run `incus profile unset default raw.idmap`. This has been fixed in the main branch, and will be fixed in the 0.5 release.

  * Running Incus and Docker on the same host can cause connectivity issues. A common reason for these issues is that Docker sets the FORWARD policy to DROP, which prevents Incus from forwarding traffic and thus causes the instances to lose network connectivity. There are two different ways you can fix this:

    * As outlined in bug DebianBug:865975, message 91, you can add `net.ipv4.ip_forward=1` to /etc/sysctl.conf which will create a FORWARD policy that docker can use. Docker then won't set the FORWARD chain to DROP when it starts up.

    * Alternately, you can use the following command to explicitly allow network traffic from your network bridge to your external network interface: `iptables -I DOCKER-USER -i <network_bridge> -o <external_interface> -j ACCEPT` (from the [[https://linuxcontainers.org/incus/docs/main/howto/network_bridge_firewalld/#prevent-connectivity-issues-with-incus-and-docker|upstream Incus documentation]])

  * If the DebianPkg:apparmor package is not installed on the host system, containers will fail to start unless their configuration is modified to include `lxc.apparmor.profile=unconfined`; this has been reported upstream at https://github.com/lxc/lxc/issues/4150.


== References ==

 * [[https://linuxcontainers.org/incus/|Incus Homepage]]
 * [[https://linuxcontainers.org/incus/docs/main/tutorial/first_steps/|First steps with Incus]]
 * [[https://github.com/lxc/incus|Upstream git repository]]

== Debian-specific information ==

 [[DebianBug:incus|Bugs]]

 [[DebianPts:incus|package tracker]]

 [[DebianMan:incus|Manpages]]

 [[https://security-tracker.debian.org/tracker/source-package/incus|security tracker]]