DOCSEARCHbyAlgolia
Submit Docs

IncusOS Documentation

repository·main·Indexed 21 days ago

https://github.com/lxc/incus-os

An immutable operating system based on Debian 13, purpose-built to host the Incus server. It emphasizes security via UEFI Secure Boot and TPM 2.0, supporting amd64 and arm64 architectures. The documentation covers installation on physical hardware and virtual platforms (such as Proxmox, VMware, and Hyper-V), remote management via the Incus CLI and web interface, and build tools including the incus-osd image-publisher and flasher-tool.

Tokens
50K
Snippets
163
Records
276
Agent score
76%

What's inside IncusOS

  1. Overview of IncusOS design and features

    main

    IncusOS is an immutable operating system designed specifically to run Incus reliably and safely. It is built on Debian 13 with custom Incus and kernel builds.

    Key Design Principles:

    • Security: Uses UEFI Secure Boot and TPM 2.0 for safe boot and TPM-backed full disk encryption (LUKS and ZFS).
    • Immutability: Employs an A/B partition scheme where all OS partitions are read-only and signed. Updates are applied atomically, allowing for easy reverts.
    • Locked Down Management: The system has no local or remote shell. Management is performed exclusively through an authenticated REST API.
    • Reliability: Guarantees bit-for-bit identical software across all servers to eliminate deployment variance.

    Core Capabilities:

    • Storage: Supports automatic local ZFS pools, complex ZFS configurations, Fiber Channel, Multipath, NVMe-over-TCP, iSCSI, Clustered LVM, Ceph, and Linstor.
    • Networking: Features VLAN-aware bridging, link aggregation, LLDP, enterprise proxy support (including Kerberos), OVS/OVN, and native support for Tailscale and NetBird.
    • Management: Supports central management via Operations Center, backup/restore of OS and application data, factory resets, and flexible update management.

  2. Overview of IncusOS

    main

    IncusOS is an immutable operating system image specifically designed to run the Incus server. It is built on Debian 13 using mkosi and focuses on providing a fast, secure, and reliable environment for Incus.

    Key security features include:

    • Active reliance on UEFI Secure Boot for boot security.
    • Support for TPM 2.0 for disk encryption.

    Supported architectures:

    • amd64 (x86_64)
    • arm64

  4. Supported installation platforms for IncusOS

    main

    IncusOS supports a wide range of deployment targets across physical hardware, cloud providers, and various virtualization platforms:

    Physical & Cloud

    • Physical hardware
    • Hetzner
    • OpenStack
    • Scaleway

    Virtualization Platforms

    • Incus
    • libvirt
    • Proxmox
    • UTM
    • VirtualBox
    • VMware
    • VMware Fusion
    • Hyper-V

  5. Understand the IncusOS management daemon

    main

    IncusOS is managed by a central management daemon. This daemon is responsible for the lifecycle and orchestration of the system, including:

    • Application & Service Management: Starting and stopping various applications and services.
    • System Infrastructure: Bringing up system networking and storage.
    • Maintenance: Handling system updates.
    • Security: Managing encryption keys.

    Each core system function (such as Network, Storage, or Security) maintains its own independent state, configuration, and set of available actions.

  6. Running IncusOS in a degraded security state

    main

    For homelab or evaluation purposes, IncusOS can run in a 'degraded security state'. This occurs if you use either Secure Boot disabled or a software-backed TPM.

    Critical Constraints:

    • You cannot run with both Secure Boot disabled and a software-backed TPM simultaneously.
    • Running in this state weakens the overall security of the IncusOS server and is generally not supported in enterprise deployments.
    • Systems in a degraded state may be treated differently by the Operations Center or other products interacting with the IncusOS API.

  7. How network roles work in IncusOS

    main

    IncusOS uses roles to control how network devices (interfaces, bonds, VLANs, or WireGuard) are utilized by the system. Assigning roles allows you to partition network traffic for specific system functions.

    Available roles:

    • cluster: Used for internal cluster communication.
    • instances: Makes the device available for Incus containers or virtual machines.
    • management: Used for system management.
    • storage: Used for network-attached storage connectivity.

    Default Behavior:

    • If no roles are manually configured, IncusOS automatically assigns cluster and management to all interfaces.
    • If you assign only the management role, the cluster role is automatically added to those interfaces.

  8. Understand Migration Manager default network configuration

    main

    If no preseed configuration is provided during installation, Migration Manager defaults to the following network behavior:

    • Listening Port: 8443
    • Network Interface: All network interfaces (0.0.0.0)
    • Authentication: Any client certificate included in the trusted_client_certificates array will be granted access to the API and Web UI.

  9. Understand the IncusOS release model

    main

    IncusOS follows a rolling release model. A new stable release is tagged at least once a week to incorporate the latest bug fixes for the Linux kernel, Incus, and other shipped components.

    Important Note on Support Channels:

    • Stable Releases: This is the only officially supported channel. Always ensure your system is running the latest stable release before reporting an issue.
    • Testing Channel: The testing update channel is not supported. It should only be used for development and debugging on non-critical systems.

  10. Understand the IncusOS partitioning scheme

    main

    IncusOS uses systemd-repart to automatically partition the main system drive during the first boot. The layout is designed for A/B redundancy, security via encryption, and automated updates.

    Partition Layout:

    • EFI ESP (2GiB): Contains signed UKI images for booting.
    • Seed data (100MiB): Used during initial installation or factory resets.
    • A-side/B-side Root Partitions: Each side includes a signing partition (16KiB), a hashes partition (100MiB), and the root partition itself (1GiB).
    • LUKS encrypted swap (4GiB): Encrypted swap space.
    • LUKS encrypted ext4 system data (25 GiB): Holds system data not part of the immutable images.
    • ZFS encrypted pool "local": Consumes all remaining disk space.
    EFI ESP (2GiB)
seed data (100MiB)
A-side root partition signing (16kiB)
A-side root partition hashes (100MiB)
A-side root partition (1GiB)
B-side root partition signing (16KiB)
B-side root partition hashes (100MiB)
B-side root partition (1GiB)
LUKS encrypted swap (4GiB)
LUKS encrypted ext4 system data (25 GiB)
ZFS encrypted pool "local" (remaining space)

  11. Requirements for encryption recovery keys

    main

    When providing encryption_recovery_keys in the SystemSecurityConfig, each key must pass a complexity policy. If a key fails these checks, the configuration update will be rejected with an error.

    Complexity Policy:

    • Minimum 15 characters in length.
    • Must contain at least one special character.
    • Must consist of at least five unique characters.
    • Additional simple complexity checks are applied by the system.

  12. Configure IncusOS kernel settings

    main
    IncusOS allows adjusting kernel-level settings via the SystemKernelConfig struct. Note that some changes may require a system reboot to take full effect. Configuration is divided into module blacklisting, memory management, network tuning, and PCI device configuration.