Official NixOS Wiki

Incus: Difference between revisions

← Older edit
DHCP (talk | contribs)
232 edits
VisualWikitext
Kagura (talk | contribs)
1 edit
Tags: Mobile edit Mobile web edit
DHCP (talk | contribs)
232 edits
m style fixes
 
(7 intermediate revisions by 6 users not shown)
Line 1: Line 1:
Incus is a next generation system container and virtual machine manager. It is a community driven alternative to Canonical's LXD, keeping the Apache-2.0 license.
[https://linuxcontainers.org/incus/ {{PAGENAME}}] (<s>[[wikipedia:en:LXC#LXD]]</s>) is a next generation system container and virtual machine manager. It is a community driven alternative to Canonical's [[LXD]], keeping the Apache-2.0 license.


This document aims to provide NixOS specific information related to Incus. For non-NixOS specific documentation, please see the upstream documentation: https://linuxcontainers.org/incus/docs/main/
This document aims to provide NixOS specific information related to Incus. For non-NixOS specific documentation, please see the upstream documentation: https://linuxcontainers.org/incus/docs/main/
Line 5: Line 5:
== Installation ==
== Installation ==
The service can be enabled and started by adding the service to your NixOS configuration. It must still be initialized.
The service can be enabled and started by adding the service to your NixOS configuration. It must still be initialized.
virtualisation.incus.enable = true;
<syntaxhighlight lang=nix>
To provide non-root access to the Incus server, you will want to add your user to the incus-admin group. Don't forget to logout and log back in.
virtualisation.incus.enable = true;
users.users.YOUR_USERNAME.extraGroups = ["incus-admin"];
networking.nftables.enable = true;
You should now be able to use the incus client to talk to the server.<syntaxhighlight lang="shell-session">
</syntaxhighlight>
 
See [[#Networking/Firewall]] for more information on the latter option.
 
To provide non-root access to the Incus server, you will want to add your user to the incus-admin group. Don't forget to reboot.
<syntaxhighlight lang=nix>
users.users.YOUR_USERNAME.extraGroups = ["incus-admin"];
</syntaxhighlight>
You should now be able to use the incus client to talk to the server.
<syntaxhighlight lang="shell-session">
[root@nixos:/etc/nixos]# incus version
[root@nixos:/etc/nixos]# incus version
If this is your first time running Incus on this machine, you should also run: incus admin init
If this is your first time running Incus on this machine, you should also run: incus admin init
Line 26: Line 35:
=== Minimal ===
=== Minimal ===
The simplest way to initialize, Incus will provide a basic directory backed storage pool and a bridged NAT network with DHCP.  
The simplest way to initialize, Incus will provide a basic directory backed storage pool and a bridged NAT network with DHCP.  
incus admin init --minimal
 
<syntaxhighlight lang=console>
$ incus admin init --minimal
</syntaxhighlight>


=== Preseed ===
=== Preseed ===
Line 72: Line 84:


== Networking/Firewall ==
== Networking/Firewall ==
When using Incus on NixOS, nftables is required to ensure broadest compatibility with other services that manage firewall rules from release 24.05. Trying to use iptables will fail eval, and this can be fixed by switching to nftables and for simple firewalls should be a drop-in replacement for iptables.<syntaxhighlight lang="nix">
When using Incus on NixOS, nftables is required to ensure broadest compatibility with other services that manage firewall rules. Trying to use iptables will fail eval, and this can be fixed by switching to nftables and for simple firewalls should be a drop-in replacement for iptables.<syntaxhighlight lang="nix">
networking.nftables.enable = true;
networking.nftables.enable = true;
</syntaxhighlight>
</syntaxhighlight>
Line 85: Line 97:
];
];
</syntaxhighlight>
</syntaxhighlight>
OR, the entire intreface can be trusted. <syntaxhighlight lang="nix">
OR, the entire interface can be trusted. <syntaxhighlight lang="nix">
networking.firewall.trustedInterfaces = [ "incusbr0" ];
networking.firewall.trustedInterfaces = [ "incusbr0" ];
</syntaxhighlight>
Prior to version [https://nixos.org/blog/announcements/2023/nixos-2311/ NixOS 23.11 "Tapir"] the default behavior of the NixOS nftables [[Firewall]] implementation was to flush the full ruleset at any change to the nftables rules. This behavior has since been changed; however, for back-portability, it still persists in configurations with a {{nixos:option|system.stateVersion}} value set prior to <code>"23.11"</code>. This often results in the Incus ruleset table (named "incus") being wiped, resulting in loss of connectivity across VMs and containers. To prevent this from occurring on affected NixOS instances, the new implementation has to be enabled manually.<syntaxhighlight lang="nix">
networking.nftables.flushRuleset = false;
</syntaxhighlight>
</syntaxhighlight>


Line 92: Line 107:
To launch a new NixOS container use the following command.
To launch a new NixOS container use the following command.


<pre>
<syntaxhighlight lang=shell-session>
incus launch images:nixos/unstable nixos -c security.nesting=true
$ incus launch images:nixos/unstable nixos -c security.nesting=true
</pre>
</syntaxhighlight>


A NixOS virtual machine is launched with the following.
A NixOS virtual machine is launched with the following.
incus launch --vm images:nixos/unstable nixos -c security.secureboot=false
 
<syntaxhighlight lang=console>
$ incus launch --vm images:nixos/unstable nixos -c security.secureboot=false
</syntaxhighlight>


== NixOS Images ==
== NixOS Images ==
Line 116: Line 134:
Container and VM images are built by Hydra as part of the [https://github.com/NixOS/nixpkgs/blob/master/nixos/release.nix NixOS release].
Container and VM images are built by Hydra as part of the [https://github.com/NixOS/nixpkgs/blob/master/nixos/release.nix NixOS release].


https://hydra.nixos.org/job/nixos/trunk-combined/nixos.lxdContainerImage.x86_64-linux
https://hydra.nixos.org/job/nixos/trunk-combined/nixos.incusContainerImage.x86_64-linux
 
https://hydra.nixos.org/job/nixos/trunk-combined/nixos.lxdVirtualMachineImage.x86_64-linux
 


https://hydra.nixos.org/job/nixos/trunk-combined/nixos.incusVirtualMachineImage.x86_64-linux


The LXC Image Server then consumes them and repackages them using their CI.
The LXC Image Server then consumes them and repackages them using their CI.
Line 132: Line 148:
=== VMs ===
=== VMs ===
All the necessary build infrastructure exists in nixpkgs to build custom images.
All the necessary build infrastructure exists in nixpkgs to build custom images.


Define some NixOS systems.<syntaxhighlight lang="nix">
Define some NixOS systems.<syntaxhighlight lang="nix">
Line 153: Line 167:
     system = "x86_64-linux";
     system = "x86_64-linux";
     modules = [
     modules = [
       "${inputs.nixpkgs}/nixos/modules/virtualisation/lxd-virtual-machine.nix"
       "${inputs.nixpkgs}/nixos/modules/virtualisation/incus-virtual-machine.nix"
       (
       (
         { pkgs, ... }:
         { pkgs, ... }:
Line 171: Line 185:
/nix/store/2snjw9y8brfh5gia44jv6bhdhmmdydva-tarball
/nix/store/2snjw9y8brfh5gia44jv6bhdhmmdydva-tarball


</syntaxhighlight>Finally, you can manually import into an Incus storage pool and used to launch instances.<syntaxhighlight lang="bash">
</syntaxhighlight>Finally, you can manually import into an Incus storage pool and used to launch instances.
<syntaxhighlight lang=console>
$ incus image import --alias nixos-gen/custom/jellyfin /nix/store/2snjw9y8brfh5gia44jv6bhdhmmdydva-tarball/tarball/nixos-system-x86_64-linux.tar.xz /nix/store/znk28bp34bycb3h5k0byb61bwda23q5l-nixos-disk-image/nixos.qcow2
$ incus image import --alias nixos-gen/custom/jellyfin /nix/store/2snjw9y8brfh5gia44jv6bhdhmmdydva-tarball/tarball/nixos-system-x86_64-linux.tar.xz /nix/store/znk28bp34bycb3h5k0byb61bwda23q5l-nixos-disk-image/nixos.qcow2
 
</syntaxhighlight>
 
To build and import the VM in one command, follow the steps below.
 
<syntaxhighlight lang=console>
 
 
</syntaxhighlight>To build and import the VM in one command, follow the steps below.<syntaxhighlight lang="bash">
$ incus image import --alias nixos-gen/custom/jellyfin $(nix build .#nixosConfigurations.vm.config.system.build.metadata --print-out-paths)/tarball/nixos-system-x86_64-linux.tar.xz $(nix build .#nixosConfigurations.vm.config.system.build.qemuImage --print-out-paths)/nixos.qcow2
$ incus image import --alias nixos-gen/custom/jellyfin $(nix build .#nixosConfigurations.vm.config.system.build.metadata --print-out-paths)/tarball/nixos-system-x86_64-linux.tar.xz $(nix build .#nixosConfigurations.vm.config.system.build.qemuImage --print-out-paths)/nixos.qcow2


# Image imported with fingerprint: ***
$ # Image imported with fingerprint: ***
</syntaxhighlight>You can verify the import with the commands below. <syntaxhighlight lang="bash">
</syntaxhighlight>
You can verify the import with the commands below.
<syntaxhighlight lang=shell-session>
$ incus image list nixos/custom/vm
$ incus image list nixos/custom/vm
+------------------------+--------------+--------+--------------------------------------------------+--------------+-----------+-----------+----------------------+
+------------------------+--------------+--------+--------------------------------------------------+--------------+-----------+-----------+----------------------+
Line 201: Line 215:


=== Containers ===
=== Containers ===
<syntaxhighlight lang="bash">
<syntaxhighlight lang="console">
$ nix build .#nixosConfigurations.container.config.system.build.squashfs --print-out-paths
$ nix build .#nixosConfigurations.container.config.system.build.squashfs --print-out-paths
/nix/store/24djf2qlpkyh29va8z6pxrqp8x5z6xyv-nixos-lxc-image-x86_64-linux.img
/nix/store/24djf2qlpkyh29va8z6pxrqp8x5z6xyv-nixos-lxc-image-x86_64-linux.img
Line 227: Line 241:
/run/current-system/sw/bin/vim
/run/current-system/sw/bin/vim


</syntaxhighlight>Or, the all in one command:<syntaxhighlight lang="bash">
</syntaxhighlight>Or, the all in one command:<syntaxhighlight lang="console">
incus image import --alias nixos/custom/vm $(nix build .#nixosConfigurations.vm.config.system.build.metadata --print-out-paths)/tarball/nixos-system-x86_64-linux.tar.xz $(nix build .#nixosConfigurations.vm.config.system.build.qemuImage --print-out-paths)/nixos.qcow2
$ incus image import --alias nixos/custom/vm $(nix build .#nixosConfigurations.vm.config.system.build.metadata --print-out-paths)/tarball/nixos-system-x86_64-linux.tar.xz $(nix build .#nixosConfigurations.vm.config.system.build.qemuImage --print-out-paths)/nixos.qcow2
</syntaxhighlight>
</syntaxhighlight>
[[Category:Server]]
[[Category:Server]]
[[Category:Container]]
[[Category:Container]]
[[Category:Virtualization]]
Retrieved from "https://wiki.nixos.org/wiki/Incus"