# lxc/incus-os architecture

> Architecture diagram of the GitHub repository lxc/incus-os, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lxc/incus-os
- Repository: https://github.com/lxc/incus-os

## Overview

##### Main Components

a. Boot Process Components:
- UEFI Secure Boot System
- TPM Module
- dm-verity Verification Layer
- A/B Update Mechanism

b. Core System Components:
- Base Debian Testing System
- Incus Container Runtime
- System Services (systemd)
- Network Configuration

c. Security Components:
- Disk Encryption Layer
- Secure Boot Key Management
- TPM State Management
- Measurement Verification

##### Key Relationships to Highlight

- How TPM measurements flow through the boot process
- Verification chain from Secure Boot to dm-verity
- Demonstrate the A/B update path
- Container runtime interaction with the base system

##### Important Details

- Partition layout (based on mkosi.repart configurations)
- System service dependencies (from systemd units)
- Network configuration flow
- Security verification chains

##### Notes for Implementation

- Keep the boot process flow clear and prominent
- Immutable nature of the system
- Clear boundaries between immutable and persistent storage
- Security verification points

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Styles
    classDef hardware fill:#d9d9d9,stroke:#333
    classDef security fill:#ffcccc,stroke:#333
    classDef system fill:#cce5ff,stroke:#333
    classDef container fill:#ccffcc,stroke:#333
    classDef update fill:#ffffcc,stroke:#333

    %% Layer 1 - Hardware & Boot
    subgraph HardwareLayer["Hardware & Boot Layer"]
        UEFI["UEFI Secure Boot"]
        TPM["TPM Module"]
        ESP["ESP Partition"]
        USR["USR Partition"]
        ROOT["Root Partition"]
    end

    %% Layer 2 - System Security
    subgraph SecurityLayer["System Security Layer"]
        DMV["dm-verity Verification"]
        DISK_ENC["Disk Encryption"]
        SB_KEYS["Secure Boot Keys"]
        TPM_STATE["TPM State Management"]
    end

    %% Layer 3 - Base System
    subgraph BaseSystem["Base System Layer"]
        DEBIAN["Debian Testing Base"]
        SYSTEMD["System Services"]
        NETWORK["Network Configuration"]
    end

    %% Layer 4 - Container Runtime
    subgraph ContainerLayer["Container Runtime Layer"]
        INCUS["Incus Runtime"]
        STORAGE["Storage Management"]
        CONTAINER_MGT["Container Management"]
    end

    %% Layer 5 - Update System
    subgraph UpdateLayer["Update System Layer"]
        AB_SYSTEM["A/B Partition Scheme"]
        UPDATE_VERIFY["Update Verification"]
        ROLLBACK["Rollback Capability"]
    end

    %% Relationships
    UEFI --> TPM
    UEFI --> ESP
    TPM --> DMV
    DMV --> USR
    DMV --> ROOT
    
    SB_KEYS --> UEFI
    TPM_STATE --> TPM
    
    DEBIAN --> SYSTEMD
    SYSTEMD --> NETWORK
    
    DEBIAN --> INCUS
    INCUS --> STORAGE
    INCUS --> CONTAINER_MGT
    
    AB_SYSTEM --> UPDATE_VERIFY
    UPDATE_VERIFY --> ROLLBACK
    UPDATE_VERIFY --> DMV

    %% Click Events
    click UEFI "https://github.com/lxc/incus-os/blob/main/mkosi.repart/00-esp.conf"
    click DMV "https://github.com/lxc/incus-os/blob/main/mkosi.repart/10-usr-verity-sig.conf"
    click AB_SYSTEM "https://github.com/lxc/incus-os/blob/main/mkosi.images/base/mkosi.extra/usr/lib/sysupdate.d/10-usr-verity-sig.transfer"
    click DEBIAN "https://github.com/lxc/incus-os/blob/main/mkosi.images/base/mkosi.conf.d/00-distro.conf"
    click INCUS "https://github.com/lxc/incus-os/blob/main/mkosi.images/base/mkosi.conf.d/20-incus-deps.conf"
    click NETWORK "https://github.com/lxc/incus-os/blob/main/mkosi.images/base/mkosi.extra/usr/lib/systemd/network/10-enp5s0.network"
    click SYSTEMD "https://github.com/lxc/incus-os/tree/main/mkosi.images/base/mkosi.extra/usr/lib/systemd/system/"
    click ROOT "https://github.com/lxc/incus-os/blob/main/mkosi.images/base/mkosi.extra/usr/lib/repart.d/40-root.conf"
    click UPDATE_VERIFY "https://github.com/lxc/incus-os/tree/main/scripts/update-image"

    %% Legend
    subgraph Legend
        H1["Hardware Component"]:::hardware
        S1["Security Component"]:::security
        SY1["System Component"]:::system
        C1["Container Component"]:::container
        U1["Update Component"]:::update
    end

    %% Class assignments
    class UEFI,TPM,ESP,USR,ROOT hardware
    class DMV,DISK_ENC,SB_KEYS,TPM_STATE security
    class DEBIAN,SYSTEMD,NETWORK system
    class INCUS,STORAGE,CONTAINER_MGT container
    class AB_SYSTEM,UPDATE_VERIFY,ROLLBACK update
```
