Incus¶

In this article

• Incus. Key Features
• Deployment Features
• Getting Started After Deploying Incus
• Initial Infrastructure Setup
• Creating and Managing Containers
• Managing Container Configuration
• Working with Snapshots and Migration
• Managing Images
• Network Interaction
• Storage Management
• Configuring NAT and Routing
• Ordering a Server with Incus using API

Incus. Key Features¶

• Container and VM Management: Incus allows running Linux system containers and full-fledged QEMU/KVM virtual machines through a single interface.
• Process Isolation: Containers operate in an isolated environment with their own file systems, network interfaces, and processes.
• Network Capabilities: Built-in support for various types of networks - bridges, NAT, VLANs, overlay networks for containers.
• Storage Management: Flexible storage pool system supporting different backends - dir, btrfs, ZFS, LVM.
• Snapshots and Migration: Creation of container state snapshots, live migration between hosts without stopping services.
• Configuration Profiles: Reusable profiles for quick deployment of containers with predefined parameters.
• Resource Limitation: Precise control over CPU, memory, disk I/O, and network bandwidth for each container.
• REST API: Full-featured HTTP API for automation and integration with external systems.
• Web Interface: Built-in web management panel for visual infrastructure control.
• Image Library: Access to an extensive collection of ready-made images of various Linux distributions.
• Clustering: Ability to combine multiple hosts into a single cluster for distributed management.

Deployment Features¶

Main Incus Paths and Files:

• Primary Configuration File: /etc/default/incus
• Data Directory: /var/lib/incus
• Storage Pools: /var/lib/incus/storage-pools/
• Containers: /var/lib/incus/containers/
• Images: /var/lib/incus/images/
• Log File: /var/log/incus/incusd.log
• System Services: /usr/lib/systemd/system/incus*.service
• Sysctl Configuration: /etc/sysctl.d/50-incus.conf
• User Configuration: /root/.config/incus/

Getting Started After Deploying Incus¶

After payment, an email notification will be sent to the address specified at registration indicating that the server is ready for operation. It will include the VPS IP address and credentials for access. Our company's clients manage equipment through the Server Management Panel and API — Invapi.

Authentication data can be found either in the Info >> Tags tab of the server management panel or in the sent email:

• Link to Access the Incus Web Interface: in tag webpanel (port 8443, HTTPS)

When first accessing the Incus web interface, the browser will warn about an insecure connection due to the self-signed certificate. You must accept the certificate to continue:

After accepting the certificate, the login page will open. Click the Login with TLS button to start the authentication process:

The system will redirect you to the page for adding an existing certificate:

Select the Trust token tab and follow the instructions:

1. In the server terminal, execute the command to generate a token:

   incus config trust add myclient
   

2. The system will generate a token that needs to be copied:

   

3. Paste the obtained token into the corresponding text field on the authentication page and click Import.

After successful authentication, the main web interface page with the list of instances will open.

Creating a New Container via Web Interface¶

To create a new container, click the Create instance button in the upper right corner of the interface:

An instance creation form with several configuration sections will open. To select a base image, click the Browse images button. An image selection window with filters by distribution, release, variant, architecture, and type will open:

The following configuration sections are available:

• Main configuration — basic container parameters: name, description, instance type (container or virtual machine), base image, and assigned profiles;
• Devices — container device management:
• Disk — disk device and mount point configuration;
• Network — network interface configuration;
• GPU — connecting graphic accelerators;
• Proxy — port forwarding configuration between host and container;
• Other — additional device types;
• Resource limits — resource limitation: processor (CPU), RAM, disk I/O operations;
• Security policies — security policies: isolation configuration, privileges, and security profiles (AppArmor, SELinux);
• Snapshots — container state snapshot management for backup and recovery;
• Migration — container migration parameters between hosts;
• Boot — boot settings: boot device order, autostart on system startup;
• Cloud init — automatic container initialization configuration via cloud-init (users, network, packages, scripts).

Select the desired image by clicking the Select button next to it:

After selecting an image, fill in the basic parameters:

• Instance name — container name;
• Description — description (optional);
• Instance type — instance type (Container or Virtual Machine);
• Profiles — configuration profiles.

To start the container immediately after creation, click Create and start. To create without starting, use the Create button.

Container Status Monitoring¶

During container deployment, the image download progress is displayed. The "Setting up" status with download progress indication shows the current instance creation progress. After installation is complete, the status will change to "Running" with a green indicator:

Service Management¶

Checking status:

systemctl status incus

Restarting service:

systemctl restart incus

Stopping service:

systemctl stop incus

Starting service:

systemctl start incus

Viewing logs:

journalctl -u incus -f

tail -f /var/log/incus/incusd.log

Initial Infrastructure Setup¶

After server deployment, it is recommended to perform initial Incus infrastructure setup.

Creating a Storage Pool¶

A storage pool defines where container data will be stored:

incus storage create default dir source=/var/lib/incus/storage-pools/default

Checking created storage pools:

incus storage list

To view detailed information about a pool:

incus storage show default

Network Configuration¶

Creating a NAT bridge for containers with automatic IPv4 addressing:

incus network create incusbr0 ipv4.address=auto ipv6.address=none

Checking network settings:

incus network list

Viewing network configuration:

incus network show incusbr0

Configuring the Default Profile¶

The default profile defines the basic configuration for new containers. Adding a root disk to the profile:

incus profile device add default root disk path=/ pool=default

Adding a network interface to the profile:

incus profile device add default eth0 nic network=incusbr0

Checking profile configuration:

incus profile show default

Creating and Managing Containers¶

Creating a Container¶

Example of creating a Debian 12 container with resource limits:

incus launch images:debian/12 deb12 --profile default \
  -c limits.cpu=2 -c limits.memory=2GiB

Command parameters:

• images:debian/12 - image from public repository
• deb12 - container name
• --profile default - using default profile
• -c limits.cpu=2 - limit to 2 CPU cores
• -c limits.memory=2GiB - memory limit of 2 GB

Viewing Containers¶

List of all instances:

incus list

The output will contain information about status, IP addresses, and type of each container.

Managing Container State¶

Starting a container:

incus start <name>

Stopping a container:

incus stop <name>

Restarting a container:

incus restart <name>

Deleting a container (requires stopping):

incus delete <name>

Force deleting a running container:

incus delete <name> --force

Container Access¶

Connecting via bash:

incus exec deb12 -- bash

Connecting to TTY console:

incus console deb12

To exit the console, use the key combination Ctrl+a q.

Port Forwarding¶

To access services inside a container from an external network, port forwarding is used through a proxy device:

incus config device add deb12 web proxy \
  listen=tcp:0.0.0.0:8080 connect=tcp:127.0.0.1:80

This command forwards host port 8080 to container port 80.

Example for multiple ports:

HTTP:

incus config device add mycontainer http proxy \
  listen=tcp:0.0.0.0:80 connect=tcp:127.0.0.1:80

HTTPS:

incus config device add mycontainer https proxy \
  listen=tcp:0.0.0.0:443 connect=tcp:127.0.0.1:443

SSH:

incus config device add mycontainer ssh proxy \
  listen=tcp:0.0.0.0:2222 connect=tcp:127.0.0.1:22

Managing Container Configuration¶

Viewing Configuration¶

Viewing full expanded container configuration:

incus config show <name> --expanded

Viewing basic configuration without profiles:

incus config show <name>

Changing Parameters¶

Setting configuration parameters:

CPU limitation:

incus config set <name> limits.cpu=4

Memory limitation:

incus config set <name> limits.memory=4GiB

Disk I/O limitation:

incus config set <name> limits.disk.priority=5

Container autostart:

incus config set <name> boot.autostart=true

Adding Devices¶

General syntax for adding devices:

incus config device add <name> <device-name> <type> key=value

Examples:

Adding an additional disk:

incus config device add mycontainer data disk \
  source=/data/mycontainer pool=default

Adding an additional network interface:

incus config device add mycontainer eth1 nic \
  network=incusbr1 name=eth1

Mounting a host directory in a container:

incus config device add mycontainer shared disk \
  source=/host/path path=/container/path

Removing a device:

incus config device remove <name> <device-name>

Working with Snapshots and Migration¶

Creating Snapshots¶

Snapshots allow saving container state for subsequent recovery:

incus snapshot <name> <snapshot-name>

Example:

incus snapshot deb12 before-update

List of container snapshots:

incus info <name>

Restoring from a Snapshot¶

incus restore <name> <snapshot-name>

Example:

incus restore deb12 before-update

Deleting a snapshot:

incus delete <name>/<snapshot-name>

Renaming and Copying¶

Renaming a container:

incus move <name> <newname>

Copying a container on the same host:

incus copy <name> <newname>

Copying a container to another Incus host:

incus copy <name> <remote>:<newname>

To work with remote hosts, you must first add a remote:

incus remote add myremote https://remote-ip:8443

Managing Images¶

Viewing Images¶

List of local images:

incus image list

List of images in remote repository:

incus image list images:

Searching for a specific distribution:

incus image list images: debian

incus image list images: ubuntu

Copying Images¶

Copying an image from public repository with auto-update:

incus image copy images:debian/12 local: --auto-update

Copying an image with alias:

incus image copy images:debian/12 local: --alias debian12

Creating an Image from a Container¶

incus publish <container-name> --alias my-custom-image

Deleting Images¶

incus image delete <image-fingerprint>

or by alias:

incus image delete <alias>

Network Interaction¶

Network Management¶

List of networks:

incus network list

Viewing network configuration:

incus network show <network-name>

Creating a new network:

# Creating a bridge network
incus network create mybr0 \
  ipv4.address=10.10.10.1/24 \
  ipv4.nat=true \
  ipv6.address=none

# Creating a macvlan network
incus network create mymacvlan \
  type=macvlan \
  parent=eth0

Editing a network:

incus network edit <network-name>

Deleting a network:

incus network delete <network-name>

Network Forwarding Rules¶

Creating a forwarding rule for port forwarding:

incus network forward create incusbr0 <external-ip>

incus network forward port add incusbr0 <external-ip> tcp 80 <container-ip> 80

Storage Management¶

Managing Storage Pools¶

List of pools:

incus storage list

Viewing pool information:

incus storage show <pool-name>

Creating a storage pool:

Dir-based pool:

incus storage create mypool dir source=/var/lib/incus/pools/mypool

Btrfs pool:

incus storage create mybtrfs btrfs source=/dev/sdb

ZFS pool:

incus storage create myzfs zfs source=/dev/sdc

Editing a pool:

incus storage edit <pool-name>

Deleting a pool:

incus storage delete <pool-name>

Managing Volumes¶

Creating a custom volume:

incus storage volume create <pool-name> <volume-name>

List of volumes in a pool:

incus storage volume list <pool-name>

Attaching a volume to a container:

incus config device add <container> <device-name> disk \
  pool=<pool-name> \
  source=<volume-name> \
  path=/mount/path

Copying a volume:

incus storage volume copy <pool>/<volume> <pool>/<new-volume>

Deleting a volume:

incus storage volume delete <pool-name> <volume-name>

Configuring NAT and Routing¶

In some cases, manual NAT and routing rule configuration may be required to provide container network access to the external network.

Switching to nftables¶

update-alternatives --set iptables /usr/sbin/iptables-nft

update-alternatives --set ip6tables /usr/sbin/ip6tables-nft

update-alternatives --set arptables /usr/sbin/arptables-nft

update-alternatives --set ebtables /usr/sbin/ebtables-nft

Enabling IP forwarding¶

sysctl -w net.ipv4.ip_forward=1

For permanent application, add to /etc/sysctl.conf:

net.ipv4.ip_forward=1

Restarting Incus after changes:

systemctl restart incus

Configuring NAT Table¶

Creating NAT table and POSTROUTING chain:

nft add table ip nat

nft add chain ip nat POSTROUTING '{ type nat hook postrouting priority srcnat; }'

Adding masquerade rule for container subnet:

nft add rule ip nat POSTROUTING oifname "ens1" ip saddr 10.1.4.0/24 counter masquerade

Configuring FORWARD Chain¶

Creating filter table and FORWARD chain:

nft add table ip filter

nft add chain ip filter FORWARD '{ type filter hook forward priority 0; policy accept; }'

Adding rules to allow traffic:

Allow traffic from containers outward:

nft insert rule ip filter FORWARD iifname "incusbr0" oifname "ens1" accept

Allow established/related traffic back:

nft insert rule ip filter FORWARD iifname "ens1" oifname "incusbr0" ct state established,related accept

Checking nftables Rules¶

Viewing all rules:

nft list ruleset

Saving rules (for Debian/Ubuntu):

Installing package for saving rules:

apt-get install nftables

Saving current rules:

nft list ruleset > /etc/nftables.conf

Enabling autoload:

systemctl enable nftables

Ordering a Server with Incus using API¶

To install this software using the API, follow these instructions.

Some of the content on this page was created or translated using AI.