github-personal/incus-os
1
0
Fork 0
mirror of https://github.com/outbackdingo/incus-os.git synced 2026-01-27 10:19:24 +00:00
Code Issues Packages Projects Releases Wiki Activity

doc: Re-structure documentation

Browse Source 
Signed-off-by: Stéphane Graber <stgraber@stgraber.org>
This commit is contained in:
Stéphane Graber
2025-11-04 17:36:45 -05:00
parent b665e2a7e8
commit a4c739dbe6
38 changed files with 319 additions and 191 deletions
Download Patch File Download Diff File Expand all files Collapse all files

37
CONTRIBUTING.md
View File

@@ -1,24 +1,39 @@
# Contributing
## Pull requests
## Pull requests:
Changes to this project should be proposed as pull requests on Github at:
<https://github.com/lxc/incus-os>
Changes to this project should be proposed as pull requests on Github
at: <https://github.com/lxc/incus-os>
Proposed changes will then go through code review there and once acked, be merged in the main branch.
Proposed changes will then go through code review there and once acked,
be merged in the main branch.
## Code of Conduct
When contributing, you must adhere to the Code of Conduct, which is available at:
<https://github.com/lxc/incus-os/blob/main/CODE_OF_CONDUCT.md>
## License and copyright:
## License and copyright
By default, any contribution to this project is made under the Apache
2.0 license.
By default, any contribution to this project is made under the Apache 2.0 license.
The author of a change remains the copyright holder of their code
(no copyright assignment).
The author of a change remains the copyright holder of their code (no copyright assignment).
## No Large Language Models (LLMs) or AI tools
## Developer Certificate of Origin:
All contributions to this project are expected to be done by human
beings or through standard predictable tooling (e.g. scripts, formatters, ...).
We expect all contributors to be able to reason about the code that they
contribute and explain why they're taking a particular approach.
LLMs and similar predictive tools have the annoying tendency of
producing large amount of low quality code with subtle issues which end
up taking the maintainers more time to debug than it would have taken to
write the code by hand in the first place.
Any attempt at hiding the use of LLMs or similar tools in IncusOS contributions
will result in a revert of the affected changes and a ban from the project.
## Developer Certificate of Origin
To improve tracking of contributions to this project we use the DCO 1.1
and use a "sign-off" procedure for all changes going into the branch.

34
doc/contributing.md Normal file
View File

@@ -0,0 +1,34 @@
% Include content from [../CONTRIBUTING.md](../CONTRIBUTING.md)
```{include} ../CONTRIBUTING.md
```
## Building locally
You can build IncusOS locally. Only users specifically interested in the
development and testing of new IncusOS features should need to do this.
Building your own images requires a current version of `mkosi`, and should work
on most Linux distributions, with Debian/Ubuntu being the most well-tested.
After cloning the repository from GitHub, simply run:
make
By default the build will produce a raw image in the `mkosi.output/` directory,
suitable for writing to a USB stick. It is also possible to build an ISO
image if you need to boot from a (virtual) CD-ROM device:
make build-iso
## Testing
To test a locally built raw image in an Incus virtual machine, run:
make test
After IncusOS has completed its installation and is running in the virtual machine, to load
applications run:
make test-applications
To test the update process, build a new image and update to it with:
make
make test-update

37
doc/flasher-tool.md
View File

@@ -1,37 +0,0 @@
# Flasher tool
The [flasher tool](https://github.com/lxc/incus-os/tree/main/incus-osd/cmd/flasher-tool)
is a user-friendly way to provide install configuration for IncusOS.
## Usage
go build ./cmd/flasher-tool/
./flasher-tool
You will first be prompted for the image format you want to use, either ISO
(default) or raw disk image. Note that the ISO isn't a hybrid image; if you
want to boot from a USB stick you should choose the raw disk image format.
The flasher tool will then connect to the Linux Containers CDN and download the
latest release.
Once downloaded, you will be presented with an interactive menu you can use to
customize the install options.
After writing the image and exiting, you can then install IncusOS from the
resulting image.
## Environment variables
Three special environment variables are recognized by the flasher tool, which can be
used to provide defaults:
- `INCUSOS_IMAGE`: Specifies a local IncusOS install image to work with, and will
disable checking the Linux Containers CDN for a newer version.
- `INCUSOS_IMAGE_FORMAT`: When downloading from the Linux Containers CDN, specifies
the IncusOS install image format (`iso` or `img`) to fetch, and will disable
prompting the user for this information.
- `INCUSOS_SEED_TAR`: Specifies a user-created [install seed](install-seed.md)
archive to write to the install image. Disables all prompting of the user, and is
considered an advanced option.

10
doc/getting-started.md Normal file
View File

@@ -0,0 +1,10 @@
# Getting started
```{toctree}
:maxdepth: 1
System requirements </getting-started/requirements>
Getting an image </getting-started/download>
Installing </getting-started/installation>
Accessing the system </getting-started/access>
```

44
doc/basic-install-steps.md → doc/getting-started/access.md
View File

@@ -1,46 +1,4 @@
# Basic install steps
This provides a brief, high-level overview of how one might install a stand-alone
IncusOS server, add its Incus as a remote, and retrieve the encryption
recovery key.
## Install configuration
First, generate an Incus client certificate/key pair if needed:
incus remote generate-certificate
Using the web-based [IncusOS Customizer](https://incusos-customizer.linuxcontainers.org/ui/),
provide your client certificate and download the resulting installation image.
Alternatively, using the [flasher tool](flasher-tool.md), enable the Incus
application and then provide this basic Incus preseed configuration, substituting
your local client certificate (`~/.config/incus/client.crt`):
```
apply_defaults: true
preseed:
certificates:
- name: demo
type: client
certificate: |
-----BEGIN CERTIFICATE-----
MIIB4TCCAWagAwIBAgIQVrBNb+LgEvX/aDNNOLM2iTAKBggqhkjOPQQDAzA4MRkw
FwYDVQQKExBMaW51eCBDb250YWluZXJzMRswGQYDVQQDDBJnaWJtYXRAZnV0dXJm
dXNpb24wHhcNMjUwNjA1MTgwODAwWhcNMzUwNjAzMTgwODAwWjA4MRkwFwYDVQQK
ExBMaW51eCBDb250YWluZXJzMRswGQYDVQQDDBJnaWJtYXRAZnV0dXJmdXNpb24w
djAQBgcqhkjOPQIBBgUrgQQAIgNiAAS8Tsj87gyhkR6gUoTa9dooWhwApI9MlsZS
M9HkNdgLG+0d2yU3JXru4AbCD+pslsL5mnSjbmF7BhqSAT0opQtyFMfB7hrCJkVB
nnebLNOqzrOVnxYqnD1HnfKo6RVmXpGjNTAzMA4GA1UdDwEB/wQEAwIFoDATBgNV
HSUEDDAKBggrBgEFBQcDAjAMBgNVHRMBAf8EAjAAMAoGCCqGSM49BAMDA2kAMGYC
MQC/Y4nAuV09z/zeh0aN+XV+kI9WLnITFprSHREIaES3r49cTkpoV8wFCwdLjbSb
NwECMQCx5H/H3hyXJen3uLbqRxTzw5jjx1M4dO4fru+VmoOKmTSmKVq3r2j449iD
GrzY7EQ=
-----END CERTIFICATE-----
```
Once you have your IncusOS install media, install it on your selected system.
## Add remote IncusOS
# Accessing the system
After the install completes, you will be shown a list of IP addresses in the
network configuration footer. Pick one and add IncusOS as a remote Incus
server:

73
doc/getting-started/download.md Normal file
View File

@@ -0,0 +1,73 @@
# Getting an image
ISO and raw images are distributed via the [Linux Containers {abbr}`CDN (Content Delivery Network)`](https://images.linuxcontainers.org/os/).
IncusOS doesn't feature a traditional installer, and relies on an [installation seed](../reference/seed.md)
to provide configuration details and defaults during install. This install
seed can be manually crafted, or you can use either of the two utilities
described below to automate the process.
There are two more user-friendly methods to get an IncusOS install image:
- A web-based customization tool
- A command line flasher tool
In either case, you will need to provide an initial trusted client certificate.
You can get yours by running
incus remote get-client-certificate
## IncusOS customizer
The web-based [IncusOS customizer](https://incusos-customizer.linuxcontainers.org/ui/)
is the most user-friendly way to get an IncusOS install image. The web page
will let you make a few simple selections, then directly download an install
image that's ready for immediate use.
## Flasher tool
The flasher tool is provided for more advanced users who need
to perform more customizations of the install seed than the web-based customizer
supports.
It can be built and run on a system with the Go compiler installed using:
go install github.com/lxc/incus-os/incus-osd/cmd/flasher-tool@latest
flasher-tool
when run, you will first be prompted for the image format you want to use, either ISO
(default) or raw disk image. Note that the ISO isn't a hybrid image; if you
want to boot from a USB stick you should choose the raw disk image format.
The flasher tool will then connect to the Linux Containers CDN and download the
latest release.
Once downloaded, you will be presented with an interactive menu you can use to
customize the install options.
To get your certificate trusted by Incus during installation, you'll
have to provide an Incus seed like this, substituting your certificate:
```
apply_defaults: true
preseed:
certificates:
- name: demo
type: client
certificate: |
-----BEGIN CERTIFICATE-----
MIIB4TCCAWagAwIBAgIQVrBNb+LgEvX/aDNNOLM2iTAKBggqhkjOPQQDAzA4MRkw
FwYDVQQKExBMaW51eCBDb250YWluZXJzMRswGQYDVQQDDBJnaWJtYXRAZnV0dXJm
dXNpb24wHhcNMjUwNjA1MTgwODAwWhcNMzUwNjAzMTgwODAwWjA4MRkwFwYDVQQK
ExBMaW51eCBDb250YWluZXJzMRswGQYDVQQDDBJnaWJtYXRAZnV0dXJmdXNpb24w
djAQBgcqhkjOPQIBBgUrgQQAIgNiAAS8Tsj87gyhkR6gUoTa9dooWhwApI9MlsZS
M9HkNdgLG+0d2yU3JXru4AbCD+pslsL5mnSjbmF7BhqSAT0opQtyFMfB7hrCJkVB
nnebLNOqzrOVnxYqnD1HnfKo6RVmXpGjNTAzMA4GA1UdDwEB/wQEAwIFoDATBgNV
HSUEDDAKBggrBgEFBQcDAjAMBgNVHRMBAf8EAjAAMAoGCCqGSM49BAMDA2kAMGYC
MQC/Y4nAuV09z/zeh0aN+XV+kI9WLnITFprSHREIaES3r49cTkpoV8wFCwdLjbSb
NwECMQCx5H/H3hyXJen3uLbqRxTzw5jjx1M4dO4fru+VmoOKmTSmKVq3r2j449iD
GrzY7EQ=
-----END CERTIFICATE-----
```
After writing the image and exiting, you can then install IncusOS from the
resulting image.

10
doc/getting-started/installation.md Normal file
View File

@@ -0,0 +1,10 @@
# Installing IncusOS
```{toctree}
:maxdepth: 1
Installing on hardware </getting-started/installation/physical>
Installing on Proxmox </getting-started/installation/virtual-proxmox>
Installing on Incus </getting-started/installation/virtual-incus>
Installing on VMware </getting-started/installation/virtual-vmware>
```

1
doc/getting-started/installation/physical.md Normal file
View File

@@ -0,0 +1 @@
# Installing on a physical machine

1
doc/getting-started/installation/virtual-incus.md Normal file
View File

@@ -0,0 +1 @@
# Installing in an Incus virtual machine

1
doc/getting-started/installation/virtual-proxmox.md Normal file
View File

@@ -0,0 +1 @@
# Installing in a Proxmox virtual machine

1
doc/getting-started/installation/virtual-vmware.md Normal file
View File

@@ -0,0 +1 @@
# Installing in a VMware virtual machine

14
doc/getting-started/requirements.md Normal file
View File

@@ -0,0 +1,14 @@
# System requirements
IncusOS is designed to provide an extremely secure environment in which to
run Incus. It requires a lot of modern system features and will not function
properly on older unsupported systems.
Minimum system requirements:
- Modern Intel/AMD (`x86_64`) or ARM (`aarch64`) system
- For `x86_64`, the CPU must support `x86_64_v3`
- Support for UEFI with Secure Boot
- {abbr}`TPM (Trusted Platform Module)` 2.0 security module
- At least 4GiB of RAM (for system use only)
- At least 50GiB of storage
- At least one wired network port

161
doc/index.md
View File

@@ -1,120 +1,105 @@
# IncusOS
IncusOS is still in early alpha development. The instructions below are
there to help try it out, mostly for testing purposes as new features get
added.
IncusOS is an immutable OS solely designed around safely and reliably
running Incus. It uses modern security features like UEFI Secure Boot
and TPM to provide a safe boot experience and seamless full disk
encryption.
## System Requirements
Updates are applied atomically using an A/B scheme allowing for an easy
revert in case of problems.
IncusOS is designed to provide an extremely secure environment in which to
run Incus. It requires a lot of modern system features and will not function
properly on older unsupported systems.
The system itself is completely locked down with no local or remote
shell, only an authenticated REST API to access Incus and manage the OS
through it.
The installed system is only reachable through Incus; there is no local shell
access or remote access through SSH. You will need to provide a trusted Incus
client certificate when preparing your install media so you can connect to
the system post install.
IncusOS is ideal for anyone who's focused on building and running
infrastructure on top of Incus and wants the underlying infrastructure
to be reliable and easy to update.
Minimum system requirements:
All IncusOS servers are guaranteed to be running bit for bit the same
software, eliminating any deployment variance and making it trivial to
scale or re-deploy even large number of servers.
- Modern x86_64 or arm64 system (5 years old at most)
- Support for UEFI with Secure Boot
- {abbr}`TPM (Trusted Platform Module)` 2.0 security module
- At least 50GiB of storage
- At least one wired network port
## Core features
## Installation
ISO and raw images are distributed via the [Linux Containers {abbr}`CDN (Content Delivery Network)`](https://images.linuxcontainers.org/os/).
Main design features:
There are two more user-friendly methods to get an IncusOS install image: a
web-based customization tool and a command line flasher tool.
- Boot safety (UEFI Secure Boot and TPM 2.0 measurements)
- Full disk encryption (TPM backed LUKS and ZFS encryption)
- Immutable (A/B partition scheme, all OS partitions read-only and signed)
- Locked down (API only management)
- Designed for modern Intel/AMD or ARM systems
IncusOS doesn't feature a traditional installer, and relies on an [install seed](install-seed.md)
to provide configuration details and defaults during install. This install
seed can be manually crafted, or you can use either of the two utilities
described below to automate the process.
Storage features:
After configuring your IncusOS image, you can then boot and IncusOS will
automatically install itself. Upon reboot, IncusOS will automatically start
up and will by default check for updates every six hours.
- Automatic local ZFS pool
- Support for complex ZFS pool creation on additional disks
- Fiber Channel & Multipath support
- NVME-over-TCP support
- iSCSI support
- Clustered LVM support (on top of Fiber Channel, NVME-over-TCP or iSCSI)
- Ceph support for software defined storage (Linstor coming soon)
If the raw image is written to a sufficiently large writable medium (at least
50GiB), such as a USB stick or hard drive, without any install seed IncusOS
will automatically resize on first boot and start running directly from that
media.
Network features:
### IncusOS customizer
- Automatic VLAN-aware bridging making it easy to attach instances to any interface
- Link aggregation support (both passive and negotiated)
- LLDP support
- Support for enterprise proxy servers (including Kerberos authentication)
- Robust NTP support
- Remote logging support through syslog (UDP, TCP, TLS)
- OVS/OVN support for software defined networking
- Native support for Tailscale (Netbird coming soon)
The web-based [IncusOS customizer](https://incusos-customizer.linuxcontainers.org/ui/)
is the most user-friendly way to get an IncusOS install image. The web page
will let you make a few simple selections, then directly download an install
image that's ready for immediate use.
### Flasher tool
Management features:
A [flasher tool](flasher-tool.md) is provided for more advanced users who need
to perform more customizations of the install seed than the web-based customizer
supports. The flasher can be built by running `go build ./cmd/flasher-tool/`.
- Central management through Operations Center
- Backup/Restore of both the main OS config and individual application data
- Factory reset of either the whole OS or individual applications
- Flexible update management
## Building locally
You can build IncusOS locally. Only users specifically interested in the
development and testing of new IncusOS features should need to do this.
Building your own images requires a current version of `mkosi`, and should work
on most Linux distributions, with Debian/Ubuntu being the most well-tested.
## Technical details
IncusOS is built on top of Debian 13 with our own Incus and kernel builds.
After cloning the repository from GitHub, simply run:
In addition to running Incus itself, IncusOS can also be used as the
underlying OS to run Operations Center and Migration Manager, allowing
for an easy migration from a VMware or similar environment over to
Incus.
make
We make extensive use of systemd's modern OS features to build our
images, handle updates and take care of things like first boot
partitioning and TPM backed disk encryption.
By default the build will produce a raw image in the `mkosi.output/` directory,
suitable for writing to a USB stick. It is also possible to build an ISO
image if you need to boot from a (virtual) CD-ROM device:
make build-iso
## Updates and release cadence
We currently maintain two update channels for IncusOS:
## Testing
Currently all development and testing of IncusOS is done through Incus virtual machines.
These instructions assume a functional Incus environment with virtual machine support.
- stable
- testing
### Local builds
To test a locally built raw image in an Incus virtual machine, run:
All installations default to the `stable` channel which typically sees
at least one weekly update to pick up the latest stable bugfix release
of the Linux kernel as well as any relevant security issues.
make test
The `testing` channel sees much more frequent builds, typically once a
day.
After IncusOS has completed its installation and is running in the virtual machine, to load
applications run:
IncusOS systems default to checking for updates every 6 hours and will
automatically update Incus itself with a very short API downtime (no
impact to running instances) and will stage any OS update to be booted
upon reboot.
make test-applications
To test the update process, build a new image and update to it with:
make
make test-update
### Using official releases
A script is available to test IncusOS using the public releases. It depends on
the flasher tool being available to automate the download of the latest IncusOS
release.
Creating a new IncusOS virtual machine can be done with:
./scripts/spawn-image NAME
This will retrieve the most recent image from the Linux Containers CDN and
create a virtual machine. It will also automatically load the relevant packages (currently
just `incus`).
The virtual machine will automatically check for updates every 6 hours with the OS updates
applying on reboot.
Configuration options are available to change the update frequency or
disable automatic updates altogether as well as specifying scheduled
downtime periods to apply the application updates.
```{toctree}
:hidden:
:titlesonly:
self
basic-install-steps
flasher-tool
secure-boot
system-recovery
install-seed
rest-api
Getting started </getting-started>
Reference </reference>
Contributing </contributing>
Support </support>
```

13
doc/reference.md Normal file
View File

@@ -0,0 +1,13 @@
# Reference
```{toctree}
:maxdepth: 1
Applications </reference/applications>
Services </reference/services>
System configuration </reference/system>
API </reference/api>
Recovery </reference/recovery>
Seed </reference/seed>
Security </reference/security>
```

4
doc/rest-api.md → doc/reference/api.md
View File

@@ -1,10 +1,8 @@
# IncusOS API
# REST API
**WARNING** The IncusOS debug API endpoints have no guarantee of API stability, and should not be used
in normal day-to-day operations.
## API
<link rel="stylesheet" type="text/css" href="../_static/swagger-ui/swagger-ui.css" ></link>
<link rel="stylesheet" type="text/css" href="../_static/swagger-override.css" ></link>
<div id="swagger-ui"></div>

9
doc/reference/applications.md Normal file
View File

@@ -0,0 +1,9 @@
# Applications
```{toctree}
:maxdepth: 1
Incus </reference/applications/incus>
Migration Manager </reference/applications/migration-manager>
Operations Center </reference/applications/operations-center>
```

1
doc/reference/applications/incus.md Normal file
View File

@@ -0,0 +1 @@
# Incus

1
doc/reference/applications/migration-manager.md Normal file
View File

@@ -0,0 +1 @@
# Migration Manager

1
doc/reference/applications/operations-center.md Normal file
View File

@@ -0,0 +1 @@
# Operations Center

2
doc/system-recovery.md → doc/reference/recovery.md
View File

@@ -1,4 +1,4 @@
# IncusOS System Recovery
# System recovery
IncusOS is designed to be fairly resilient to failures, but there may be times when
your system misbehaves. Here are some suggestions that might be useful if you ever

4
doc/secure-boot.md → doc/reference/security.md
View File

@@ -1,5 +1,5 @@
# Secure Boot details
This document outlines how IncusOS utilizes Secure Boot. A basic understanding of Secure Boot concepts and how a TPM works is assumed.
# System security
IncusOS actively relies on both UEFI Secure Boot and TPM for its boot security and encryption.
## Assumptions

12
doc/install-seed.md → doc/reference/seed.md
View File

@@ -1,9 +1,9 @@
# Install Seed
IncusOS depends on an "install seed" to automate the installation process. Most
users should either use the web-based [IncusOS customizer](https://incusos-customizer.linuxcontainers.org/ui/)
or the [flasher tool](flasher-tool.md) which provide a simple way to configure
the install seed without requiring detailed understanding of the technical details
below.
# Installation seed
IncusOS depends on an "install seed" to automate the installation process.
That seed is normally automatically generated when [getting an image](../getting-started/download.md).
For more advanced use, it's possible to provide your own seed data using the information below.
## Format and location
The install seed is a simple tar archive consisting of one or more JSON or YAML

13
doc/reference/services.md Normal file
View File

@@ -0,0 +1,13 @@
# Services
```{toctree}
:maxdepth: 1
Ceph </reference/services/ceph>
iSCSI </reference/services/iscsi>
LVM </reference/services/lvm>
Multipath </reference/services/multipath>
NVMe </reference/services/nvme>
OVN </reference/services/ovn>
USBIP </reference/services/usbip>
```

1
doc/reference/services/ceph.md Normal file
View File

@@ -0,0 +1 @@
# Ceph

1
doc/reference/services/iscsi.md Normal file
View File

@@ -0,0 +1 @@
# iSCSI

1
doc/reference/services/lvm.md Normal file
View File

@@ -0,0 +1 @@
# LVM

1
doc/reference/services/multipath.md Normal file
View File

@@ -0,0 +1 @@
# Multipath

1
doc/reference/services/nvme.md Normal file
View File

@@ -0,0 +1 @@
# NVMe

1
doc/reference/services/ovn.md Normal file
View File

@@ -0,0 +1 @@
# OVN

1
doc/reference/services/usbip.md Normal file
View File

@@ -0,0 +1 @@
# USBIP

12
doc/reference/system.md Normal file
View File

@@ -0,0 +1,12 @@
# System configuration
```{toctree}
:maxdepth: 1
Logging </reference/system/logging>
Network </reference/system/network>
Resources </reference/system/resources>
Security </reference/system/security>
Storage </reference/system/storage>
Update </reference/system/update>
```

1
doc/reference/system/logging.md Normal file
View File

@@ -0,0 +1 @@
# Logging

1
doc/reference/system/network.md Normal file
View File

@@ -0,0 +1 @@
# Network

1
doc/reference/system/resources.md Normal file
View File

@@ -0,0 +1 @@
# Resources

1
doc/reference/system/security.md Normal file
View File

@@ -0,0 +1 @@
# Security

1
doc/reference/system/storage.md Normal file
View File

@@ -0,0 +1 @@
# Storage

1
doc/reference/system/update.md Normal file
View File

@@ -0,0 +1 @@
# Update

1
doc/support.md Normal file
View File

@@ -0,0 +1 @@
# Support