Add WireGuard network support

- Introduced a new network type: WireGuard.
- Updated network type definitions and handling in various components.
- Implemented the `nicWireguard` device type for managing WireGuard interfaces.
- Added validation and configuration logic for WireGuard networks.
- Enhanced network loading and management to include WireGuard functionality.

This update allows users to create and manage WireGuard networks within the system, expanding the networking capabilities significantly.

Signed-off-by: Salem Yaslem <[email protected]>

Author: xlmnxp

doc/explanation/networks.md

@@ -80,6 +80,16 @@ Incus supports the following network types:
   This means that you can create your own OVN network as a non-admin user, even in a restricted project.
   ```
 
+{ref}`network-wireguard`
+: % Include content from [../reference/network_wireguard.md](../reference/network_wireguard.md)
+  ```{include} ../reference/network_wireguard.md
+      :start-after: <!-- Include start wireguard intro -->
+      :end-before: <!-- Include end wireguard intro -->
+  ```
+
+  In Incus context, the `wireguard` network type creates a WireGuard VPN interface that instances can connect to.
+  WireGuard operates at layer 3 (network layer), making it suitable for secure VPN connections.
+
 ### External networks
 
 % Include content from [../reference/network_external.md](../reference/network_external.md)

doc/howto/network_create.md

@@ -29,6 +29,9 @@ The following network types are available:
 * - `physical`
   - {ref}`network-physical`
   - {ref}`network-physical-options`
+* - `wireguard`
+  - {ref}`network-wireguard`
+  - {ref}`network-wireguard-options`
 
 ```
 

doc/reference/devices_nic.md

@@ -53,6 +53,7 @@ The following NICs can be added using the `nictype` or `network` options:
 The following NICs can be added using only the `network` option:
 
 - [`ovn`](nic-ovn): Uses an existing OVN network and creates a virtual device pair to connect the instance to it.
+- [`wireguard`](nic-wireguard): Uses an existing WireGuard network and creates a routed connection to it.
 
 The following NICs can be added using only the `nictype` option:
 
@@ -294,6 +295,37 @@ NIC devices of type `p2p` have the following device options:
 You can select this NIC type only through the `nictype` option.
 ```
 
+A `routed` NIC creates a virtual device pair to connect the host to the instance and sets up static routes and proxy ARP/NDP entries to allow the instance to join the network of a designated parent interface.
+
+(nic-wireguard)=
+### `nictype`: `wireguard`
+
+```{note}
+You can select this NIC type only through the `network` option (see {ref}`network-wireguard` for information about the managed `wireguard` network).
+```
+
+A `wireguard` NIC connects an instance to a WireGuard VPN network.
+The instance will automatically receive an IP address from the WireGuard network's address range if not manually specified.
+
+WireGuard operates at layer 3 (network layer), making it suitable for secure VPN connections between instances and remote peers.
+
+#### Device options
+
+NIC devices of type `wireguard` have the following device options:
+
+% Include content from [config_options.txt](../config_options.txt)
+```{include} ../config_options.txt
+    :start-after: <!-- config group devices-nic_wireguard start -->
+    :end-before: <!-- config group devices-nic_wireguard end -->
+```
+
+(nic-routed)=
+### `nictype`: `routed`
+
+```{note}
+You can select this NIC type only through the `nictype` option.
+```
+
 A `routed` NIC creates a virtual device pair to connect the host to the instance and sets up static routes and proxy ARP/NDP entries to allow the instance to join the network of a designated parent interface.
 For containers it uses a virtual Ethernet device pair, and for VMs it uses a TAP device.
 
@@ -359,6 +391,68 @@ NIC devices of type `routed` have the following device options:
 
 ## `bridged`, `macvlan` or `ipvlan` for connection to physical network
 
+The `bridged`, `macvlan` and `ipvlan` interface types can be used to connect to an existing physical network.
+However, it differs from `ipvlan` because it does not need IPVLAN support in the kernel, and the host and the instance can communicate with each other.
+
+This NIC type respects `netfilter` rules on the host and uses the host's routing table to route packets, which can be useful if the host is connected to multiple networks.
+
+IP addresses, gateways and routes
+: You must manually specify the IP addresses (using `ipv4.address` and/or `ipv6.address`) before the instance is started.
+
+  For containers, the NIC configures the following link-local gateway IPs on the host end and sets them as the default gateways in the container's NIC interface:
+
+      169.254.0.1
+      fe80::1
+
+  For VMs, the gateways must be configured manually or via a mechanism like `cloud-init` (see the {ref}`how to guide <instances-routed-nic-vm>`).
+
+  ```{note}
+  If your container image is configured to perform DHCP on the interface, it will likely remove the automatically added configuration.
+  In this case, you must configure the IP addresses and gateways manually or via a mechanism like `cloud-init`.
+  ```
+
+  The NIC type configures static routes on the host pointing to the instance's `veth` interface for all of the instance's IPs.
+
+Multiple IP addresses
+: Each NIC device can have multiple IP addresses added to it.
+
+  However, it might be preferable to use multiple `routed` NIC interfaces instead.
+  In this case, set the `ipv4.gateway` and `ipv6.gateway` values to `none` on any subsequent interfaces to avoid default gateway conflicts.
+  Also consider specifying a different host-side address for these subsequent interfaces using `ipv4.host_address` and/or `ipv6.host_address`.
+
+Parent interface
+: This NIC can operate with and without a `parent` network interface set.
+
+: With the `parent` network interface set, proxy ARP/NDP entries of the instance's IPs are added to the parent interface, which allows the instance to join the parent interface's network at layer 2.
+: To enable this, the following network configuration must be applied on the host via `sysctl`:
+
+   - When using IPv4 addresses:
+
+     ```
+     net.ipv4.conf.<parent>.forwarding=1
+     ```
+
+   - When using IPv6 addresses:
+
+     ```
+     net.ipv6.conf.all.forwarding=1
+     net.ipv6.conf.<parent>.forwarding=1
+     net.ipv6.conf.all.proxy_ndp=1
+     net.ipv6.conf.<parent>.proxy_ndp=1
+     ```
+
+#### Device options
+
+NIC devices of type `routed` have the following device options:
+
+% Include content from [config_options.txt](../config_options.txt)
+```{include} ../config_options.txt
+    :start-after: <!-- config group devices-nic_routed start -->
+    :end-before: <!-- config group devices-nic_routed end -->
+```
+
+## `bridged`, `macvlan` or `ipvlan` for connection to physical network
+
 The `bridged`, `macvlan` and `ipvlan` interface types can be used to connect to an existing physical network.
 
 `macvlan` effectively lets you fork your physical NIC, getting a second interface that is then used by the instance.

doc/reference/network_wireguard.md

@@ -0,0 +1,80 @@
+(network-wireguard)=
+# WireGuard network
+
+<!-- Include start wireguard intro -->
+{abbr}`WireGuard` is a modern, fast, and secure VPN tunnel that uses state-of-the-art cryptography.
+It is designed to be faster, simpler, and more secure than IPsec and OpenVPN.
+See [`www.wireguard.com`](https://www.wireguard.com/) for more information.
+<!-- Include end wireguard intro -->
+
+The `wireguard` network type allows you to create a WireGuard VPN interface that instances can connect to using the `wireguard` NIC type.
+This enables secure point-to-point and site-to-site VPN connections.
+
+WireGuard networks operate at layer 3 (network layer), making them suitable for routing traffic between instances and remote peers.
+
+```{note}
+WireGuard requires the `wireguard-tools` package to be installed on the host system.
+```
+
+(network-wireguard-options)=
+## Configuration options
+
+The following configuration key namespaces are currently supported for the `wireguard` network type:
+
+- `user` (free-form key/value for user metadata)
+
+```{note}
+{{note_ip_addresses_CIDR}}
+```
+
+The following configuration options are available for the `wireguard` network type:
+
+% Include content from [config_options.txt](../config_options.txt)
+```{include} ../config_options.txt
+    :start-after: <!-- config group network_wireguard-common start -->
+    :end-before: <!-- config group network_wireguard-common end -->
+```
+
+(network-wireguard-features)=
+## Supported features
+
+The following features are supported for the `wireguard` network type:
+
+- **Node-specific configuration**: Each cluster member can have different WireGuard interface configurations
+- **Network peering**: WireGuard networks support peering with remote WireGuard peers
+
+(network-wireguard-examples)=
+## Examples
+
+### Create a basic WireGuard network
+
+```bash
+incus network create wg0 --type=wireguard ipv4.address=10.0.0.1/24
+```
+
+### Create a WireGuard network with IPv6
+
+```bash
+incus network create wg0 --type=wireguard ipv4.address=10.0.0.1/24 ipv6.address=2001:db8::1/64
+```
+
+### Create a WireGuard network with a peer
+
+```bash
+incus network create wg0 --type=wireguard \
+  ipv4.address=10.0.0.1/24 \
+  private_key="<base64_private_key>" \
+  peers.remote.public_key="<base64_public_key>" \
+  peers.remote.allowed_ips="10.0.0.0/24" \
+  peers.remote.endpoint="192.168.1.100:51820" \
+  peers.remote.persistent_keepalive=25
+```
+
+### Connect an instance to a WireGuard network
+
+```bash
+incus launch images:ubuntu/jammy/cloud myinstance --network=wg0
+```
+
+The instance will automatically receive an IP address from the WireGuard network's address range.
+

internal/server/db/networks.go

@@ -561,11 +561,12 @@ type NetworkType int
 
 // Network types.
 const (
-	NetworkTypeBridge   NetworkType = iota // Network type bridge.
-	NetworkTypeMacvlan                     // Network type macvlan.
-	NetworkTypeSriov                       // Network type sriov.
-	NetworkTypeOVN                         // Network type ovn.
-	NetworkTypePhysical                    // Network type physical.
+	NetworkTypeBridge    NetworkType = iota // Network type bridge.
+	NetworkTypeMacvlan                      // Network type macvlan.
+	NetworkTypeSriov                        // Network type sriov.
+	NetworkTypeOVN                          // Network type ovn.
+	NetworkTypePhysical                     // Network type physical.
+	NetworkTypeWireguard                    // Network type wireguard.
 )
 
 // NetworkNode represents a network node.
@@ -693,6 +694,8 @@ func networkFillType(network *api.Network, netType NetworkType) {
 		network.Type = "ovn"
 	case NetworkTypePhysical:
 		network.Type = "physical"
+	case NetworkTypeWireguard:
+		network.Type = "wireguard"
 	default:
 		network.Type = "" // Unknown
 	}

internal/server/device/device_load.go

@@ -38,6 +38,8 @@ func newByType(state *state.State, projectName string, conf deviceConfig.Device)
 			dev = &nicBridged{}
 		case "routed":
 			dev = &nicRouted{}
+		case "wireguard":
+			dev = &nicWireguard{}
 		case "macvlan":
 			dev = &nicMACVLAN{}
 		case "sriov":