Skip to content

Incus Container Management Guide

Incus Overview

Incus is a modern container and virtual machine manager that provides a unified experience for running and managing your compute resources. It's a powerful, community-driven project that emerged from the LXD ecosystem.

The LXD → Incus Story

Incus is a fork of LXD, created by the original LXD team after Canonical changed LXD's direction. The community has largely migrated to Incus, which continues the original vision of LXD with:

  • Community governance instead of corporate control
  • Faster development and innovation
  • Better packaging and distribution
  • Seamless migration from LXD to Incus

Basic Container Operations

Image and Container Management

Container Lifecycle
incus image alias list images:  #(1)!
incus info <name>  #(2)!
incus config edit <name>  #(3)!
incus config show <name>  #(4)!
incus exec <name> bash  #(5)!
  1. List available container images with their aliases
  2. Show detailed information about a specific container
  3. Edit container configuration in your default editor
  4. Display current container configuration
  5. Execute an interactive bash shell inside the container

Launch New Containers

Container Creation
incus launch images:debian/12 <name>  #(1)!
incus config set <name> environment.LC_ALL=en_US.UTF-8  #(2)!
incus list  #(3)!
  1. Launch new Debian 12 container with specified name
  2. Set locale environment variable inside container
  3. List all containers with their status

Resource Limits & Performance

Memory and CPU Limits

Resource Constraints
incus config set <name> limits.memory 512MB  #(1)!
incus config set <name> limits.cpu 2  #(2)!
incus config set <name> limits.cpu.allowance 50%  #(3)!
incus config set <name> limits.memory.swap false  #(4)!
  1. Limit container memory usage to 512MB
  2. Restrict container to use maximum 2 CPU cores
  3. Allow container to use only 50% of allocated CPU time
  4. Disable swap usage for this container

Storage I/O Limits

Storage Bandwidth
incus config device set <name> root limits.read 30MB  #(1)!
incus config device set <name> root limits.write 10MB  #(2)!
  1. Limit read bandwidth to 30MB/s
  2. Limit write bandwidth to 10MB/s
I/O Operations Per Second
incus config device set <name> root limits.read 20Iops  #(1)!
incus config device set <name> root limits.write 10Iops  #(2)!
  1. Limit read operations to 20 IOPS
  2. Limit write operations to 10 IOPS

Storage Size Management

Storage Allocation
incus config device override <name> root size=20GB  #(1)!
  1. Set container root filesystem size to 20GB

Network Configuration

Bandwidth Control

Network Limits
incus profile device set default eth0 limits.ingress 100Mbit  #(1)!
incus profile device set default eth0 limits.egress 100Mbit  #(2)!
  1. Limit incoming network traffic to 100Mbit/s
  2. Limit outgoing network traffic to 100Mbit/s

Security and Isolation

Port Isolation
incus config device set <name> eth0 security.port_isolation=true  #(1)!
incus profile device set default eth0 security.port_isolation=true  #(2)!
  1. Enable port isolation for specific container
  2. Set port isolation as default for all new containers

Port Isolation

When enabled, containers cannot communicate with other containers that also have port isolation enabled. This provides additional network security between workloads.

Privileged Containers

Launch Privileged Container

Privileged Mode
incus launch ubuntu:22.04 test -c security.privileged=true -c security.nesting=true  #(1)!
  1. Creates privileged container with nesting support for Docker/systemd

Security Considerations

Privileged containers run with full system privileges and can access host resources. Only use when absolutely necessary and understand the security implications.

Port Forwarding

SSH Port Forward
incus config device add test ssh proxy listen=tcp:0.0.0.0:2222 connect=tcp:127.0.0.1:22  #(1)!
  1. Forward host port 2222 to container's SSH port 22

Storage Management

Storage Volumes

Storage Operations
incus storage volume list <storagename>  #(1)!
incus storage volume create local backups  #(2)!
incus config set storage.backups_volume local/backups  #(3)!
  1. List all volumes in specified storage pool
  2. Create new storage volume named "backups"
  3. Configure Incus to use this volume for backups

Image Storage Configuration

Image Storage
incus storage volume create local images  #(1)!
incus config set storage.images_volume local/images  #(2)!
  1. Create dedicated volume for container images
  2. Configure Incus to store downloaded images here

Device Mounting

Mount Host Directory
incus config device add $containerName $deviceName disk source=/home/foo path=/home/foo  #(1)!
  1. Mount host directory /home/foo into container
Mount Raw Device
incus config device add $containerName $deviceName disk source=/dev/<disk> path=/home/foo  #(1)!
  1. Mount raw block device directly into container

System Configuration

Important Paths

Default Incus data directory:

Incus Data Directory
/var/lib/incus/

Container Setup Essentials

Essential packages for new container deployments:

Essential Packages
apt update && apt install -y \
  vim \
  postfix \
  logrotate \
  etckeeper \
  iputils-ping \
  dnsutils

Package Descriptions

  • vim - Text editor for configuration
  • postfix - Mail transfer agent for notifications
  • logrotate - Log file management
  • etckeeper - Version control for /etc
  • iputils-ping - Network connectivity testing
  • dnsutils - DNS lookup tools

Initial Configuration Steps

Post-Installation Tasks

  1. Enable journald for proper logging
  2. Set hostname (create /etc/hostname on Arch Linux)
  3. Configure postfix for mail delivery

Legacy Container Cleanup

For older container images, disable unused getty services:

Disable Getty Services
sed -i 's/^tty/# tty/g' /etc/inittab  #(1)!
systemctl disable getty@tty{1..4}  #(2)!
reboot  #(3)!
  1. Comment out tty entries in inittab
  2. Disable getty services on virtual terminals
  3. Restart container to apply changes

Nginx Proxy Configuration

When running web services behind a reverse proxy:

Real IP Configuration
set_real_ip_from W.X.Y.Z;           # Replace with your proxy IP
real_ip_header X-Forwarded-For;

log_format custom '$http_x_forwarded_for - $remote_user [$time_local] '
  '"$request" $status $body_bytes_sent '
  '"$http_referer" "$http_user_agent"';

access_log /var/log/nginx/access.log custom;

Proxy Configuration

  • Replace W.X.Y.Z with your reverse proxy's IP address
  • This logs real client IPs instead of proxy IPs
  • Essential for proper access logging and security

Migration from LXD

Seamless Migration

Migration Process

Migrating from LXD to Incus is straightforward:

  1. Backup your LXD data using lxd export
  2. Install Incus on your system
  3. Import containers using incus import
  4. Verify functionality and update scripts

Command Compatibility

Most LXD commands work in Incus by simply replacing lxc with incus:

Command Migration Examples
# LXD → Incus
lxc list        →  incus list
lxc info        →  incus info
lxc config      →  incus config
lxc exec        →  incus exec

Additional Resources

Best Practices

  • Use unprivileged containers whenever possible
  • Implement regular backup strategies
  • Monitor resource usage to optimize performance
  • Configure proper networking for security
  • Keep Incus updated for latest features and security fixes

Getting Help