Skip to content

Commit 3c85d24

Browse files
stgraberstgraber
authored
Merge pull request #581 from gibmat/doc-updates
Documentation updates and cleanup
2 parents c236b71 + 4b7baff commit 3c85d24

10 files changed

Lines changed: 129 additions & 99 deletions

File tree

‎doc/getting-started/access.md‎

Lines changed: 88 additions & 91 deletions
Original file line numberDiff line numberDiff line change
@@ -14,66 +14,74 @@ This can be done by looking at the bottom of the screen on the running system.
1414

1515
The documentation below uses `192.0.2.100` as the IP address of the IncusOS system.
1616

17-
## From the command line
17+
## Connecting to IncusOS
18+
19+
`````{tabs}
20+
21+
````{group-tab} Command line
1822
After the install completes, you will be shown a list of IP addresses in the
1923
network configuration footer. Pick one and add IncusOS as a remote Incus
2024
server:
2125
22-
```
23-
$ incus remote add IncusOS 192.0.2.100
24-
Certificate fingerprint: 80d569e9244a421f3a3d60d46631eb717f8a0a480f2f23ee729a4c1c016875f7
25-
ok (y/n/[fingerprint])? y
26-
27-
$ incus remote list
28-
+-----------------+------------------------------------+---------------+-------------+--------+--------+--------+
29-
| NAME | URL | PROTOCOL | AUTH TYPE | PUBLIC | STATIC | GLOBAL |
30-
+-----------------+------------------------------------+---------------+-------------+--------+--------+--------+
31-
| IncusOS | https://10.234.136.23:8443 | incus | tls | NO | NO | NO |
32-
+-----------------+------------------------------------+---------------+-------------+--------+--------+--------+
33-
| images | https://images.linuxcontainers.org | simplestreams | none | YES | NO | NO |
34-
+-----------------+------------------------------------+---------------+-------------+--------+--------+--------+
35-
| local (current) | unix:// | incus | file access | NO | YES | NO |
36-
+-----------------+------------------------------------+---------------+-------------+--------+--------+--------+
37-
38-
```
26+
$ incus remote add IncusOS 192.0.2.100
27+
Certificate fingerprint: 80d569e9244a421f3a3d60d46631eb717f8a0a480f2f23ee729a4c1c016875f7
28+
ok (y/n/[fingerprint])? y
29+
30+
$ incus remote list
31+
+-----------------+------------------------------------+---------------+-------------+--------+--------+--------+
32+
| NAME | URL | PROTOCOL | AUTH TYPE | PUBLIC | STATIC | GLOBAL |
33+
+-----------------+------------------------------------+---------------+-------------+--------+--------+--------+
34+
| IncusOS | https://192.0.2.100:8443 | incus | tls | NO | NO | NO |
35+
+-----------------+------------------------------------+---------------+-------------+--------+--------+--------+
36+
| images | https://images.linuxcontainers.org | simplestreams | none | YES | NO | NO |
37+
+-----------------+------------------------------------+---------------+-------------+--------+--------+--------+
38+
| local (current) | unix:// | incus | file access | NO | YES | NO |
39+
+-----------------+------------------------------------+---------------+-------------+--------+--------+--------+
3940
4041
Once the remote is added, you can interact with it like any other Incus server:
4142
42-
```
43-
$ incus launch images:debian/trixie IncusOS:trixie
44-
Launching trixie
45-
46-
$ incus list
47-
+---------------+---------+------------------------+--------------------------------------------------+-----------------+-----------+
48-
| NAME | STATE | IPV4 | IPV6 | TYPE | SNAPSHOTS |
49-
+---------------+---------+------------------------+--------------------------------------------------+-----------------+-----------+
50-
| test-incus-os | RUNNING | 10.25.170.1 (incusbr0) | fd42:612d:f700:5f6e::1 (incusbr0) | VIRTUAL-MACHINE | 0 |
51-
| | | 10.234.136.23 (enp5s0) | fd42:3cfb:8972:3990:1266:6aff:feab:9439 (enp5s0) | | |
52-
+---------------+---------+------------------------+--------------------------------------------------+-----------------+-----------+
53-
54-
$ incus list IncusOS:
55-
+--------+---------+----------------------+------------------------------------------------+-----------+-----------+
56-
| NAME | STATE | IPV4 | IPV6 | TYPE | SNAPSHOTS |
57-
+--------+---------+----------------------+------------------------------------------------+-----------+-----------+
58-
| trixie | RUNNING | 10.25.170.218 (eth0) | fd42:612d:f700:5f6e:1266:6aff:fe39:d31f (eth0) | CONTAINER | 0 |
59-
+--------+---------+----------------------+------------------------------------------------+-----------+-----------+
60-
61-
```
62-
63-
## From the web
43+
$ incus launch images:debian/trixie IncusOS:trixie
44+
Launching trixie
45+
46+
$ incus list
47+
+---------------+---------+------------------------+--------------------------------------------------+-----------------+-----------+
48+
| NAME | STATE | IPV4 | IPV6 | TYPE | SNAPSHOTS |
49+
+---------------+---------+------------------------+--------------------------------------------------+-----------------+-----------+
50+
| test-incus-os | RUNNING | 10.25.170.1 (incusbr0) | fd42:612d:f700:5f6e::1 (incusbr0) | VIRTUAL-MACHINE | 0 |
51+
| | | 192.0.2.100 (enp5s0) | fd42:3cfb:8972:3990:1266:6aff:feab:9439 (enp5s0) | | |
52+
+---------------+---------+------------------------+--------------------------------------------------+-----------------+-----------+
53+
54+
$ incus list IncusOS:
55+
+--------+---------+----------------------+------------------------------------------------+-----------+-----------+
56+
| NAME | STATE | IPV4 | IPV6 | TYPE | SNAPSHOTS |
57+
+--------+---------+----------------------+------------------------------------------------+-----------+-----------+
58+
| trixie | RUNNING | 10.25.170.218 (eth0) | fd42:612d:f700:5f6e:1266:6aff:fe39:d31f (eth0) | CONTAINER | 0 |
59+
+--------+---------+----------------------+------------------------------------------------+-----------+-----------+
60+
````
61+
62+
````{group-tab} Web interface
6463
The Incus UI is also available for web access.
6564
6665
For this to work, the client certificate provided at image creation time
6766
must be imported as a user certificate in your web browser.
6867
69-
The exact process to do this varies between browsers and operating
70-
systems, but generally involves generating a PKCS#12 certificate from
71-
the separate `client.crt` and `client.key`, then importing that in the
72-
web browser's certificate store.
68+
```{tip}
69+
The exact process of adding a user certificate varies between browsers
70+
and operating systems, but generally involves importing a PKCS#12 certificate
71+
into the web browser's certificate store.
7372
74-
Once this is done, you can access the UI at `https://192.0.2.100:8443`
73+
A PKCS#12 certificate can be generated from the Incus client key/certificate
74+
pair by running
75+
76+
openssl pkcs12 -export -inkey ~/.config/incus/client.key -in ~/.config/incus/client.crt -out ~/.config/incus/client.pfx
77+
```
78+
79+
Once the user certificate is imported, you can access the UI at `https://192.0.2.100:8443`
7580
7681
![Incus UI with running instances](../images/incus-webui-instances.png)
82+
````
83+
84+
`````
7785

7886
## Fetching the encryption recovery key
7987

@@ -86,50 +94,39 @@ This step is currently only possible through the command line client.
8694
```
8795

8896
```
89-
$ incus query IncusOS:/os/1.0/system/security
90-
{
91-
"config": {
92-
"encryption_recovery_keys": [
93-
"fkrjjenn-tbtjbjgh-jtvvchjr-ctienevu-crknfkvi-vjlvblhl-kbneribu-htjtldch"
94-
]
95-
},
96-
"state": {
97-
"encrypted_volumes": [
98-
{
99-
"state": "unlocked (TPM)",
100-
"volume": "root"
101-
},
102-
{
103-
"state": "unlocked (TPM)",
104-
"volume": "swap"
105-
}
106-
],
107-
"encryption_recovery_keys_retrieved": true,
108-
"pool_recovery_keys": {
109-
"local": "F7zrtdHEaivKqofZbVFs2EeANyK77DbLi6Z8sqYVhr0="
110-
},
111-
"secure_boot_certificates": [
112-
{
113-
"fingerprint": "26dce4dbb3de2d72bd16ae91a85cfeda84535317d3ee77e0d4b2d65e714cf111",
114-
"issuer": "CN=Incus OS - Secure Boot E1,O=Linux Containers",
115-
"subject": "CN=Incus OS - Secure Boot PK R1,O=Linux Containers",
116-
"type": "PK"
117-
},
118-
{
119-
"fingerprint": "9a42866f496834bde7e1b26a862b1e1b6dea7b78b91a948aecfc4e6ef79ea6c1",
120-
"issuer": "CN=Incus OS - Secure Boot E1,O=Linux Containers",
121-
"subject": "CN=Incus OS - Secure Boot KEK R1,O=Linux Containers",
122-
"type": "KEK"
123-
},
124-
{
125-
"fingerprint": "21b6f423cf80fe6c436dfea0683460312f276debe2a14285bfdc22da2d00fc20",
126-
"issuer": "CN=Incus OS - Secure Boot E1,O=Linux Containers",
127-
"subject": "CN=Incus OS - Secure Boot 2025 R1,O=Linux Containers",
128-
"type": "db"
129-
}
130-
],
131-
"secure_boot_enabled": true,
132-
"tpm_status": "ok"
133-
}
134-
}
97+
$ incus admin os system security show
98+
WARNING: The IncusOS API and configuration is subject to change
99+
100+
config:
101+
encryption_recovery_keys:
102+
- fkrjjenn-tbtjbjgh-jtvvchjr-ctienevu-crknfkvi-vjlvblhl-kbneribu-htjtldch
103+
state:
104+
encrypted_volumes:
105+
- state: unlocked (TPM)
106+
volume: root
107+
- state: unlocked (TPM)
108+
volume: swap
109+
encryption_recovery_keys_retrieved: true
110+
pool_recovery_keys:
111+
local: F7zrtdHEaivKqofZbVFs2EeANyK77DbLi6Z8sqYVhr0=
112+
secure_boot_certificates:
113+
- fingerprint: 26dce4dbb3de2d72bd16ae91a85cfeda84535317d3ee77e0d4b2d65e714cf111
114+
issuer: CN=Incus OS - Secure Boot E1,O=Linux Containers
115+
subject: CN=Incus OS - Secure Boot PK R1,O=Linux Containers
116+
type: PK
117+
- fingerprint: 9a42866f496834bde7e1b26a862b1e1b6dea7b78b91a948aecfc4e6ef79ea6c1
118+
issuer: CN=Incus OS - Secure Boot E1,O=Linux Containers
119+
subject: CN=Incus OS - Secure Boot KEK R1,O=Linux Containers
120+
type: KEK
121+
- fingerprint: 21b6f423cf80fe6c436dfea0683460312f276debe2a14285bfdc22da2d00fc20
122+
issuer: CN=Incus OS - Secure Boot E1,O=Linux Containers
123+
subject: CN=Incus OS - Secure Boot 2025 R1,O=Linux Containers
124+
type: db
125+
- fingerprint: 2243c49fcf6f84fe670f100ecafa801389dc207536cb9ca87aa2c062ddebfde5
126+
issuer: CN=Incus OS - Secure Boot E1,O=Linux Containers
127+
subject: CN=Incus OS - Secure Boot 2026 R1,O=Linux Containers
128+
type: db
129+
secure_boot_enabled: true
130+
tpm_status: ok
131+
135132
```

‎doc/reference/applications.md‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,9 +7,9 @@ The primary application is responsible for listening on the network and
77
for handling user authentication. It then provides access to the IncusOS
88
management API through its own API.
99

10-
IncusOS also supports additional (non-primary) applications which can
11-
extend the base system (for example for debugging) or provide additional
12-
features to another application.
10+
IncusOS also supports [additional](applications/non-primary.md) (non-primary)
11+
applications which can extend the base system (for example for debugging) or
12+
provide additional features to another application.
1313

1414
```{toctree}
1515
:maxdepth: 1
@@ -19,4 +19,6 @@ Migration Manager </reference/applications/migration-manager>
1919
Operations Center </reference/applications/operations-center>
2020
2121
Shared API </reference/applications/shared-api>
22+
23+
Non-primary applications </reference/applications/non-primary>
2224
```

‎doc/reference/applications/debug.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Debug
2+
3+
The Debug application provides several additional tools that can be useful for developers working on debugging issues in an IncusOS system:
4+
5+
* `htop`
6+
* `ifstat`
7+
* `iputils-ping`
8+
* `nano`
9+
* `mtr-tiny`
10+
* `net-tools`
11+
* `netcat-openbsd`
12+
* `procps`
13+
* `strace`
14+
* `tcpdump`

‎doc/reference/applications/incus-ceph.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Incus Ceph
2+
3+
The Incus Ceph (`incus-ceph`) application installs the Ceph client for Incus deployments needing to use [Ceph storage](../services/ceph.md).

‎doc/reference/applications/incus-linstor.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Incus Linstor
2+
3+
The Incus Linstor (`incus-linstor`) application installs Linstor satellite support for Incus deployments needing to use [Linstor storage](../services/linstor.md).

‎doc/reference/applications/incus.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -28,5 +28,5 @@ Important seed fields include:
2828

2929
Two additional applications exist which extend the main Incus application:
3030

31-
* `incus-ceph`: Adds Ceph client support
32-
* `incus-linstor`: Add Linstor satellite support
31+
* `incus-ceph`: Adds [Ceph](../services/ceph.md) client support
32+
* `incus-linstor`: Adds [Linstor](../services/linstor.md) satellite support

‎doc/reference/applications/non-primary.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Non-primary applications
2+
3+
IncusOS uses non-primary applications to enhance the functionality of a primary application or provide debugging support.
4+
5+
```{toctree}
6+
:maxdepth: 1
7+
8+
Debug </reference/applications/debug>
9+
Incus-Ceph </reference/applications/incus-ceph>
10+
Incus-Linstor </reference/applications/incus-linstor>
11+
```

‎doc/reference/services/ceph.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Ceph
22

3-
The [Ceph](https://ceph.io/) service allows connecting a Ceph storage cluster.
3+
The [Ceph](https://ceph.io/) service allows connecting a Ceph storage cluster. In addition to Incus, the `incus-ceph` application must be installed to enable this service.
44

55
## Configuration options
66

‎doc/reference/services/linstor.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Linstor
22

3-
The [Linstor](https://linbit.com/linstor/) service allows connecting a Linstor deployment.
3+
The [Linstor](https://linbit.com/linstor/) service allows connecting a Linstor deployment. In addition to Incus, the `incus-linstor` application must be installed to enable this service.
44

55
## Configuration options
66

‎doc/reference/system/backup.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,7 @@ User-created storage pools will be untouched, but will be unable to be imported
5454

5555
The following configuration options can be set when performing a factory reset:
5656

57-
*`allow_tpm_reset_failure`: If `true`, ignore failures when resetting TPM state.
57+
* `allow_tpm_reset_failure`: If `true`, ignore failures when resetting TPM state.
5858

5959
* `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.
6060

0 commit comments

Comments
 (0)