Exercise: System Container (Incus) Introduction

Installation and Initialization

A hands-on exercise to install Incus, the modern system container manager, and initialize it to prepare for launching full Linux operating systems as lightweight containers.

1 Purpose

This exercise introduces you to Incus, a powerful tool for creating and managing system containers. Unlike the single-process application containers you used with Podman, Incus containers behave like full, lightweight virtual machines. This exercise guides you through installing the Incus software, initializing the service, and viewing the available operating system images.

2 What You’ll Accomplish

By the end of this exercise, you will be able to:

• Add a COPR repository to install software on Fedora.
• Install the Incus packages.
• Initialize the Incus daemon.
• List available system container images from the official remote.

NoteLearning Outcomes

This exercise maps to the following program and course learning outcomes:

• Course Learning Outcomes (CLOs):
  • 1. Identify hardware and basic network components: This exercise introduces system containers, a modern virtualization technology that provides a lightweight alternative to full VMs.

TipLearning Objectives, KSAs, and Technologies

This exercise develops the following skills, which align with the O*NET SOC Code 15-1232.00 for Computer User Support Specialists.

Learning Objective	O*NET KSAs	Technologies Used
Install and initialize Incus system containers.	Knowledge: Computers & Electronics Skills: None	Incus, COPR
List available system container images.	Knowledge: Computers & Electronics Abilities: Information Ordering	incus image list

3 Prerequisites

This exercise requires a running Fedora 42 virtual machine with sudo privileges and internet access.

4 Step-by-Step Guide

Open a terminal window in your Fedora VM to begin.

4.1 Step 1: Enable the Incus COPR Repository

Incus is not in the main Fedora repositories yet, but it is available through a COPR (Cool Other Package Repo). COPR is a Fedora-sponsored system that allows developers to provide their own software repositories.

1. Run the following command to enable the official Incus repository:

   sudo dnf copr enable ganto/incus

   Press y to confirm when prompted.

4.2 Step 2: Install Incus

With the repository enabled, you can now install the Incus packages.

1. Run the installation command:

   sudo dnf install -y incus

4.3 Step 3: Initialize the Incus Daemon

Before you can use Incus, you must perform a one-time initialization. This sets up the necessary storage pools and network bridges. We will use the --auto flag to accept the recommended defaults, which is perfect for a simple laptop setup.

1. Run the initialization command:

   sudo incus admin init --auto

2. The command will print out the configuration it is applying. This process may take a minute or two to complete.

4.4 Step 4: Add Your User to the incus-admin Group

To use the incus command without sudo for every operation, you must add your user to the incus-admin group.

1. Run the usermod command:

   sudo usermod -a -G incus-admin $USER

2. Log Out and Log Back In: For the group change to take effect, you must fully log out of your Fedora session and log back in.

4.5 Step 5: List Available OS Images

After logging back in, you can interact with Incus. Let’s see what operating systems are available to launch as system containers.

1. Run the incus image list command. The images: remote is the official repository for Incus images.

   incus image list images:

2. Analyze the Output: You will see a very long list of available operating systems, including different versions of Ubuntu, Debian, Fedora, CentOS, and more. This demonstrates the wide variety of full Linux systems you can run as lightweight containers. You can use q to quit the list view.

4.6 Step 6: Launch an Ubuntu System Container with Incus and Verify the OS

Now that you’ve explored Incus images, let’s launch a real Incus system container running Ubuntu, get a shell inside it, and confirm the OS version from within the container.

1. Find a suitable Ubuntu image from the images: remote (choose an alias from the list):

incus image list images: | grep -i ubuntu

Note the alias shown in the output (examples include ubuntu/24.04 or ubuntu/22.04).

2. Launch a new instance using the chosen alias. Replace <ALIAS> with the alias you picked and ubuntu-test with any name you prefer:

WarningTroubleshooting: Incus idmap setup on Fedora

If you see an error like System doesn't have a functional idmap setup when launching a container, check these requirements:

1. Mapping helpers must be setuid root:

sudo chmod u+s /usr/bin/newuidmap /usr/bin/newgidmap

Run ls -l /usr/bin/newuidmap /usr/bin/newgidmap and confirm the permissions show -rwsr-xr-x (the s is required).

2. You must have entries in /etc/subuid and /etc/subgid for your user and for root if Incus runs as root:

grep "^$USER:" /etc/subuid /etc/subgid
grep "^root:" /etc/subuid /etc/subgid

If missing, add (for your user):

sudo sh -c "echo '$USER:100000:65536' >> /etc/subuid"
sudo sh -c "echo '$USER:100000:65536' >> /etc/subgid"

And for root (required if Incus runs as root, which is the default on Fedora):

sudo sh -c "echo 'root:100000:65536' >> /etc/subuid"
sudo sh -c "echo 'root:100000:65536' >> /etc/subgid"

3. Restart Incus after making changes:

sudo systemctl restart incus

4. If it still fails:

• Check the output of incus --version and sudo journalctl -u incus --no-pager -n 50 for more details.
• Some Fedora kernels do not expose kernel.unprivileged_userns_clone; this is normal and not a blocker if the other requirements are met.
• If you are running in a VM or container, ensure nesting and user namespaces are enabled in your virtualization settings.

If you continue to see the error after following all steps, consult the Incus documentation for your Fedora version or check for open issues upstream.

WarningTroubleshooting: Incus network does not show DHCP enabled

If your Incus network does not show DHCP: true when you run incus network show incusbr0 (or your bridge name), containers will not receive IP addresses automatically.

To enable DHCP:

1. Edit the network and enable DHCP:

incus network edit incusbr0

Add or set these lines in the YAML editor:

config:
  ipv4.address: auto
  ipv4.dhcp: "true"
  ipv6.address: none

Save and exit the editor.

2. Restart the network (dnsmasq will restart automatically):

incus network detach-profile incusbr0 default
incus network attach-profile incusbr0 default

3. Restart your container:

incus restart ubuntu-test
incus list ubuntu-test

Your container should now receive an IP address from the Incus bridge.

WarningTroubleshooting: Fedora firewalld may block DHCP for Incus containers

Fedora’s firewalld can block DHCP traffic (UDP ports 67/68) between Incus containers and the bridge, preventing containers from receiving IP addresses.

To test if firewalld is the issue:

1. Check firewalld status:

sudo systemctl status firewalld
sudo firewall-cmd --list-all

2. Temporarily stop firewalld to test DHCP:

sudo systemctl stop firewalld
incus restart ubuntu-test
incus list ubuntu-test

If the container now gets an IP address, firewalld was blocking DHCP.

3. To allow DHCP and Incus bridge traffic permanently, you must start firewalld before using firewall-cmd:

sudo systemctl start firewalld
sudo firewall-cmd --zone=trusted --add-interface=incusbr0 --permanent
sudo firewall-cmd --zone=trusted --add-port=67/udp --permanent
sudo firewall-cmd --zone=trusted --add-port=68/udp --permanent
sudo firewall-cmd --reload

This ensures Incus containers can receive DHCP addresses even with firewalld enabled.

Example:

incus launch images:ubuntu/25.04 ubuntu-test

3. Get an interactive shell inside the running instance:

incus exec ubuntu-test -- /bin/bash

(If incus shell ubuntu-test is available on your system, that is an alternative shorthand.)

4. Inside the instance, verify the operating system version:

cat /etc/os-release

You should see PRETTY_NAME, VERSION_ID, and related fields confirming the Ubuntu release.

5. (Optional) Run hostnamectl to see container-specific details:

hostnamectl

The output will show Chassis: container and other details that highlight the OS is running inside a container, not on bare metal or a VM. This is a useful way to confirm the environment from inside the shell.

6. When finished, exit the shell and remove the instance (either stop then delete, or force-delete):

exit
incus delete --force ubuntu-test

This step uses an Incus system container (a full OS instance managed like a lightweight VM), so you can see and interact with the entire filesystem and init system just like a virtual machine. ## Reflect and Review

ImportantReflection: 3-2-1

Now that you have completed this exercise, reflect on your experience in your Microsoft Teams Student Notebook:

• 3 new commands you used (dnf copr, incus admin init, incus image list).
• 2 operating systems you saw in the image list.
• 1 question you still have about the difference between Incus and Podman.

TipCheck on Learning

Answer these questions in your notebook to solidify your understanding:

1. What is a COPR repository?
2. What is the purpose of the sudo incus admin init --auto command?
3. Why do you need to log out and log back in after being added to the incus-admin group?
4. What command would you use to see the list of official Incus OS images?