Skip to content

Commit fafc5f0

Browse files
stgraberstgraber
authored
Merge pull request lxc#480 from gibmat/add-system-docs
Add system configuration docs
2 parents b3004ae + 9a0def8 commit fafc5f0

File tree

14 files changed

+568
-58
lines changed

14 files changed

+568
-58
lines changed

‎doc/.wordlist.txt‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,9 @@ customizer
55
db
66
dbx
77
DCO
8+
decrypt
89
DHCP
10+
DNS
911
ECDSA
1012
FAT
1113
formatters
@@ -14,6 +16,7 @@ GiB
1416
Github
1517
Incus
1618
IncusOS
19+
IPv
1720
iSCSI
1821
ISO
1922
JSON
@@ -24,19 +27,24 @@ LLDP
2427
LLMs
2528
LUKS
2629
LVM
30+
MAC
31+
MACs
2732
MOK
33+
MTU
2834
Multipath
2935
Netbird
3036
NTP
3137
NVMe
3238
OEM
3339
OVN
3440
OVS
41+
parsable
3542
PCR
3643
PCRs
3744
PK
3845
preseed
3946
Proxmox
47+
raidz
4048
RSA
4149
SLAAC
4250
struct
@@ -53,6 +61,7 @@ UEFI
5361
UKI
5462
USBIP
5563
VLAN
64+
VLANs
5665
VMware
5766
YAML
5867
ZFS

‎doc/reference/api.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,9 @@
11
# REST API
22

3-
**WARNING** The IncusOS debug API endpoints have no guarantee of API stability, and should not be used
3+
```{warning}
4+
The IncusOS debug API endpoints have no guarantee of API stability, and should not be used
45
in normal day-to-day operations.
6+
```
57

68
<link rel="stylesheet" type="text/css" href="../../_static/swagger-ui/swagger-ui.css" ></link>
79
<link rel="stylesheet" type="text/css" href="../../_static/swagger-override.css" ></link>

‎doc/reference/system.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,11 @@
33
```{toctree}
44
:maxdepth: 1
55
6+
Backup/Restore </reference/system/backup>
67
Logging </reference/system/logging>
78
Network </reference/system/network>
9+
Power </reference/system/power>
10+
Providers </reference/system/providers>
811
Resources </reference/system/resources>
912
Security </reference/system/security>
1013
Storage </reference/system/storage>

‎doc/reference/system/backup.md‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
# Backup/Restore
2+
3+
IncusOS can perform a system-level backup of its configuration and state. This backup can then be restored at a later point in time. Additionally, a full factory reset can be performed which will bring IncusOS back to a clean state as if it had just been installed.
4+
5+
```{important}
6+
The system-level backup doesn't include information from any installed applications. Each application has its own backup/restore functionality which can be used in conjunction with the system-level backup to perform a comprehensive system backup.
7+
```
8+
9+
## Backup
10+
11+
```{important}
12+
An IncusOS backup will contain its current state as well as copies of the encryption key(s) for any local storage pool(s). As such, the backup should not be stored in any publicly-accessible location.
13+
```
14+
15+
Create the backup by running
16+
17+
```
18+
incus admin os system backup backup.tar.gz
19+
```
20+
21+
## Restore
22+
23+
```{warning}
24+
Restoring a backup will overwrite any existing OS-level state and potentially one or more encryption keys. As such, use caution when restoring.
25+
```
26+
27+
### Configuration options
28+
29+
The following "skip" options can be set when restoring a backup:
30+
31+
* `encryption-recovery-keys`: Don't overwrite any existing main system drive encryption recovery keys.
32+
33+
* `local-data-encryption-key`: Don't overwrite the local storage pool's encryption key.
34+
35+
* `network-macs`: Don't use any hard-coded MACs from the backup, but rather attempt to determine the proper MACs from the existing interfaces.
36+
37+
### Examples
38+
39+
Restore the back up by running
40+
41+
```
42+
incus admin os system restore backup.tar.gz
43+
```
44+
45+
## Factory reset
46+
47+
```{warning}
48+
A factory reset will erase all data on the main system drive. This includes any installed applications, their configuration and the system-level state and configuration.
49+
50+
User-created local storage pools will be untouched, but will be unable to be imported when the system reboots. Be certain you have a copy of each local storage pool's encryption key __before__ performing the factory reset.
51+
```
52+
53+
### Configuration options
54+
55+
The following configuration options can be set when performing a factory reset:
56+
57+
*`allow_tpm_reset_failure`: If `true`, ignore failures when resetting TPM state.
58+
59+
* `seeds`: A map of seeds to write to the seed partition just before rebooting the system. This can be useful to change/update existing seed data when the system configures itself after booting.
60+
61+
* `wipe_existing_seeds`: If `true`, wipe any existing seed data that may be present in the seed partition.
62+
63+
### Examples
64+
65+
Perform a basic reset that will reuse any existing seed data by running
66+
67+
```
68+
incus admin os system factory-reset
69+
```
70+
71+
Perform a reset that allows TPM failure, wipes any existing seeds, and configures a basic Incus application upon reboot by running
72+
73+
```
74+
incus admin os system factory-reset -d '{"allow_tpm_reset_failure":true,"wipe_existing_seeds":true,"seeds":{"incus":{"apply_defaults":true}}}'
75+
```

‎doc/reference/system/logging.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,13 @@
11
# Logging
2+
3+
IncusOS can be configured to log to a remote syslog server.
4+
5+
## Configuration options
6+
7+
The following configuration options can be set:
8+
9+
* `address`: The remote syslog server IP address.
10+
11+
* `protocol`: The protocol to use when connecting to the remote syslog server.
12+
13+
* `log_format`: The format of log entries to use.

‎doc/reference/system/network.md‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,87 @@
11
# Network
2+
3+
IncusOS supports complex network configurations consisting of interfaces, bonds, and VLANs. By default, IncusOS will configure each discovered interface to automatically acquire IPv4/IPv6 addresses, DNS, and NTP information from the local network. More complex network setups can be configured via an [install seed](../seed.md), or post-install via the network API.
4+
5+
Before applying any new/updated network configuration, basic validation checks are performed. If this check fails, or the network fails to come up properly as reported by `systemd-networkd`, the changes will be reverted to minimize the chance of accidentally knocking the IncusOS system offline.
6+
7+
Be aware that changing network configuration may result in a brief period of time when the system is unreachable over the network.
8+
9+
## Configuration options
10+
11+
Interfaces, bonds, and VLANs have a significant number of fields, which are largely self-descriptive and can be viewed in the [API definition](https://github.com/lxc/incus-os/blob/main/incus-osd/api/system_network.go).
12+
13+
One special feature of note is the handling of hardware addresses (MACs). Both interfaces and bonds associate their configuration with the hardware address, which can be specified in two ways:
14+
15+
* Raw MAC: Specify the hardware address directly, such as `10:66:6a:e5:6a:1c`.
16+
17+
* Interface name: If an interface name is provided, such as `enp5s0`, at startup IncusOS will attempt to get its MAC address and substitute that value in the configuration. This is useful when installing IncusOS across multiple physically identical servers with only a single [install seed](../seed.md).
18+
19+
The following configuration options can be set:
20+
21+
* `interfaces`: Zero or more interfaces that should be configured for the system.
22+
23+
* `bonds`: Zero or more bonds that should be configured for the system.
24+
25+
* `vlans`: Zero or more VLANs that should be configured for the system.
26+
27+
* `dns`: Optionally, configure custom DNS information for the system.
28+
29+
* `ntp`: Optionally, configure custom NTP server(s) for the system.
30+
31+
* `proxy`: Optionally, configure a proxy for the system.
32+
33+
### Examples
34+
35+
Configure two network interfaces, one with IPv4 and the other with IPv6:
36+
37+
```
38+
{
39+
"interfaces": [
40+
{"name": "ip4iface",
41+
"hwaddr": "enp5s0",
42+
"addresses": ["dhcp4"]},
43+
{"name": "ip6iface",
44+
"hwaddr": "enp6s0",
45+
"addresses": ["slaac"]}
46+
]
47+
}
48+
```
49+
50+
Configure a VLAN with ID 123 on top of an active-backup bond composed of two interfaces with MTU of 9000 and LLDP enabled:
51+
52+
```
53+
{
54+
"bonds": [
55+
{"name:", "management",
56+
"mode": "active-backup",
57+
"mtu": 9000,
58+
"lldp": true,
59+
"members": ["enp5s0", "enp6s0"],
60+
"roles": ["management", "interfaces"]
61+
}
62+
],
63+
"vlans": [
64+
{"name": "uplink",
65+
"parent": "management",
66+
"id": 123,
67+
"addresses": ["dhcp4", "slaac"]
68+
}
69+
]
70+
}
71+
```
72+
73+
Configure custom DNS and NTP for IncusOS:
74+
75+
```
76+
{
77+
"dns": {
78+
"hostname": "server01",
79+
"domain": "example.com",
80+
"search_domains": ["example.com", "example.org"],
81+
"nameservers": ["ns1.example.com", "ns2.example.com"]
82+
},
83+
"ntp": {
84+
"timeservers": ["ntp.example.com"]
85+
}
86+
}
87+
```

‎doc/reference/system/power.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# Power
2+
3+
## Rebooting IncusOS
4+
5+
IncusOS can be rebooted via
6+
7+
```
8+
incus admin os system reboot
9+
```
10+
11+
## Powering off IncusOS
12+
13+
IncusOS can be safely powered off via
14+
15+
```
16+
incus admin os system poweroff
17+
```

‎doc/reference/system/providers.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Providers
2+
3+
IncusOS receives [updates](update.md) from the currently configured provider. Two providers are supported:
4+
5+
* `images`: The default IncusOS provider, which fetches updates from the [Linux Containers {abbr}`CDN (Content Delivery Network)`](https://images.linuxcontainers.org/os/).
6+
7+
* `operations-center`: When IncusOS is deployed in a managed environment controlled by [Operations Center](../applications/operations-center.md), it is registered with the `operations-center` provider. This allows an administrator to centrally control all IncusOS systems, even in restricted or air-gaped environments that may not have Internet access.
8+
9+
## Configuration options
10+
11+
The following configuration options can be set:
12+
13+
* `name`: The name of the provider. One of `images`, `operations-center`, or `local`. `local` is intended for use by developers working on IncusOS.
14+
15+
* `config`: A map of provider-specific configuration key-value pairs.

‎doc/reference/system/resources.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,11 @@
11
# Resources
2+
3+
A detailed low-level dump of information about the IncusOS system hardware can be obtained by running
4+
5+
```
6+
incus admin os system show resources
7+
```
8+
9+
## Configuration options
10+
11+
There are no configuration options for this read-only system information.

‎doc/reference/system/security.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,25 @@
11
# Security
2+
3+
IncusOS has a fairly robust [security setup](../security.md) that is enforced on all systems. Under normal operation, IncusOS relies on the TPM to automatically unlock the main system drive, which in turn holds the encryption keys for any [local storage pools](storage.md).
4+
5+
As part of its first boot, IncusOS generates a strong recovery key that can be used to decrypt the main system drive in recovery scenarios, such accidental TPM reset or needing to perform offline data recovery. Additional recovery keys can be added if desired. It is imperative to protect the recovery key(s) in a manner consistent with the importance of data stored on the corresponding IncusOS system.
6+
7+
The recovery key(s) can be retrieved by running
8+
9+
```
10+
incus admin os system show security
11+
```
12+
13+
## Configuration options
14+
15+
The following configuration options can be set:
16+
17+
* `encryption_recovery_keys`: An array of one or more encryption recovery keys for the IncusOS main system drive. At least one recovery key must always be provided, but no length or complexity policy is enforced by IncusOS. Any existing recovery key(s) not present in the array will be removed, and any new key(s) will be added.
18+
19+
## Resetting TPM bindings
20+
21+
If IncusOS fails to automatically unlock the main system drive, after booing using a recovery key, it is possible to forcefully reset the TPM bindings:
22+
23+
```
24+
incus admin os system tpm-rebind
25+
```

0 commit comments

Comments
 (0)