diff --git a/doc/.wordlist.txt b/doc/.wordlist.txt index a985fbf..c4c93c0 100644 --- a/doc/.wordlist.txt +++ b/doc/.wordlist.txt @@ -46,7 +46,9 @@ MOK MTU multipath Multipath +NAT'ed Netbird +NICs NTP NVMe OCI @@ -62,6 +64,7 @@ PK PKCS Pre preseed +proxied Proxmox Proxmox's raidz @@ -84,6 +87,7 @@ UKI Uncheck Unencrypted unencrypted +unmanaged USBIP VirtIO VirtualBox diff --git a/doc/index.md b/doc/index.md index 2087451..43d22d6 100644 --- a/doc/index.md +++ b/doc/index.md @@ -97,6 +97,7 @@ downtime periods to apply the application updates. self Getting started +Tutorials Reference Contributing Support diff --git a/doc/reference/api.md b/doc/reference/api.md index 401b5fd..5d5c70a 100644 --- a/doc/reference/api.md +++ b/doc/reference/api.md @@ -1,5 +1,11 @@ # REST API +```{note} +The IncusOS API is typically proxied through an installed application, such as [Incus](applications/incus.md). + +If interacting with the API manually, you will need to prefix `/os/` to correctly reach the IncusOS endpoints. For example, to get a list of applications you could run `curl https://1.2.3.4:8443/os/1.0/applications`. +``` + ```{warning} The IncusOS debug API endpoints have no guarantee of API stability, and should not be used in normal day-to-day operations. diff --git a/doc/reference/system/network.md b/doc/reference/system/network.md index 1d713bf..684a471 100644 --- a/doc/reference/system/network.md +++ b/doc/reference/system/network.md @@ -6,6 +6,10 @@ Before applying any new/updated network configuration, basic validation checks a Be aware that changing network configuration may result in a brief period of time when the system is unreachable over the network. +```{note} +IncusOS automatically configures each interface and bond as a network bridge. This allows for easy out-of-the-box configuration of bridged NICs for containers and virtual machines. +``` + ## Configuration options 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). diff --git a/doc/tutorials.md b/doc/tutorials.md new file mode 100644 index 0000000..6c81de8 --- /dev/null +++ b/doc/tutorials.md @@ -0,0 +1,7 @@ +# Tutorials +The following tutorials demonstrate various ways to configure and use IncusOS. + +```{toctree} +:maxdepth: 1 +Network: Directly attach instances to host network +``` diff --git a/doc/tutorials/network-direct-attach.md b/doc/tutorials/network-direct-attach.md new file mode 100644 index 0000000..652c983 --- /dev/null +++ b/doc/tutorials/network-direct-attach.md @@ -0,0 +1,99 @@ +# Directly attach instances to host network + +When running [Incus](../reference/applications/incus.md) on IncusOS, by default you will get a NAT'ed bridged network `incusbr0`: + +``` +gibmat@futurfusion:~$ incus network list ++----------+--------+---------+----------------+---------------------------+----------------------------+---------+---------+ +| NAME | TYPE | MANAGED | IPV4 | IPV6 | DESCRIPTION | USED BY | STATE | ++----------+--------+---------+----------------+---------------------------+----------------------------+---------+---------+ +| incusbr0 | bridge | YES | 10.89.179.1/24 | fd42:e1a1:408f:710a::1/64 | Local network bridge (NAT) | 1 | CREATED | ++----------+--------+---------+----------------+---------------------------+----------------------------+---------+---------+ +``` + +However, sometimes you may want to attach a container or virtual machine directly to the host's network. This is easily accomplished by assigning the `instances` role to the appropriate interfaces or bonds. + +First, get the current IncusOS network configuration: + +``` +gibmat@futurfusion:~$ incus admin os system show network +WARNING: The IncusOS API and configuration is subject to change + +config: + interfaces: + - addresses: + - dhcp4 + - slaac + hwaddr: 10:66:6a:1f:50:b7 + lldp: false + name: enp5s0 + required_for_online: "no" +state: + interfaces: + enp5s0: + addresses: + - 10.234.136.193 + - fd42:3cfb:8972:3990:1266:6aff:fe1f:50b7 + hwaddr: 10:66:6a:1f:50:b7 + mtu: 1500 + roles: + - management + - cluster + routes: + - to: default + via: 10.234.136.1 + speed: "-1" + state: routable + stats: + rx_bytes: 60644 + rx_errors: 0 + tx_bytes: 113337 + tx_errors: 0 + type: interface +``` + +Then, edit the interface and/or bond to add the appropriate role by running `incus admin os system edit network`: + +``` +config: + interfaces: + - addresses: + - dhcp4 + - slaac + hwaddr: 10:66:6a:1f:50:b7 + lldp: false + name: enp5s0 + required_for_online: "no" + roles: + - instances +``` + +After the configuration change is applied, a new unmanaged bridge will appear: + +``` +gibmat@futurfusion:~$ incus network list ++----------+--------+---------+----------------+---------------------------+----------------------------+---------+---------+ +| NAME | TYPE | MANAGED | IPV4 | IPV6 | DESCRIPTION | USED BY | STATE | ++----------+--------+---------+----------------+---------------------------+----------------------------+---------+---------+ +| enp5s0 | bridge | NO | | | | 0 | | ++----------+--------+---------+----------------+---------------------------+----------------------------+---------+---------+ +| incusbr0 | bridge | YES | 10.89.179.1/24 | fd42:e1a1:408f:710a::1/64 | Local network bridge (NAT) | 1 | CREATED | ++----------+--------+---------+----------------+---------------------------+----------------------------+---------+---------+ +``` + +Now, you can configure an instance to directly connect to the host's physical network: + +``` +gibmat@futurfusion:~$ incus launch images:debian/13 debian-nat +Launching debian-nat +gibmat@futurfusion:~$ incus launch images:debian/13 debian-direct --network enp5s0 +Launching debian-direct +gibmat@futurfusion:~$ incus list ++---------------+---------+-----------------------+------------------------------------------------+-----------+-----------+ +| NAME | STATE | IPV4 | IPV6 | TYPE | SNAPSHOTS | ++---------------+---------+-----------------------+------------------------------------------------+-----------+-----------+ +| debian-direct | RUNNING | 10.234.136.199 (eth0) | fd42:3cfb:8972:3990:1266:6aff:fe71:14e0 (eth0) | CONTAINER | 0 | ++---------------+---------+-----------------------+------------------------------------------------+-----------+-----------+ +| debian-nat | RUNNING | 10.89.179.217 (eth0) | fd42:e1a1:408f:710a:1266:6aff:fef6:4995 (eth0) | CONTAINER | 0 | ++---------------+---------+-----------------------+------------------------------------------------+-----------+-----------+ +```