Add WireGuard network support

doc/.wordlist.txt

@@ -373,3 +373,7 @@ Zettabyte
 ZFS
 zpool
 zpools
+WireGuard
+OpenVPN
+IPsec
+wireguard

doc/config_options.txt

@@ -1429,6 +1429,127 @@ The custom policy routing table ID to add IPv6 static routes to (in addition to
 ```
 
 <!-- config group devices-nic_sriov end -->
+<!-- config group devices-nic_wireguard start -->
+```{config:option} host_name devices-nic_wireguard
+:default: "randomly assigned"
+:shortdesc: "The name of the interface on the host"
+:type: "string"
+
+```
+
+```{config:option} hwaddr devices-nic_wireguard
+:default: "randomly assigned"
+:shortdesc: "The MAC address of the new interface"
+:type: "string"
+
+```
+
+```{config:option} ipv4.gateway devices-nic_wireguard
+:default: "auto"
+:shortdesc: "Whether to add an automatic default IPv4 gateway (can be `auto` or `none`)"
+:type: "string"
+
+```
+
+```{config:option} ipv4.host_tables devices-nic_wireguard
+:default: "254"
+:shortdesc: "Comma-delimited list of routing tables IDs to add IPv4 static routes to"
+:type: "string"
+
+```
+
+```{config:option} ipv4.neighbor_probe devices-nic_wireguard
+:default: "true"
+:shortdesc: "Whether to probe the parent network for IPv4 address availability using ARP"
+:type: "bool"
+
+```
+
+```{config:option} ipv4.routes devices-nic_wireguard
+:shortdesc: "Comma-delimited list of IPv4 static routes to add on host to NIC"
+:type: "string"
+
+```
+
+```{config:option} ipv6.gateway devices-nic_wireguard
+:default: "auto"
+:shortdesc: "Whether to add an automatic default IPv6 gateway (can be `auto` or `none`)"
+:type: "string"
+
+```
+
+```{config:option} ipv6.host_tables devices-nic_wireguard
+:default: "254"
+:shortdesc: "Comma-delimited list of routing tables IDs to add IPv6 static routes to"
+:type: "string"
+
+```
+
+```{config:option} ipv6.neighbor_probe devices-nic_wireguard
+:default: "true"
+:shortdesc: "Whether to probe the parent network for IPv6 address availability using NDP"
+:type: "bool"
+
+```
+
+```{config:option} ipv6.routes devices-nic_wireguard
+:shortdesc: "Comma-delimited list of IPv6 static routes to add on host to NIC"
+:type: "string"
+
+```
+
+```{config:option} limits.egress devices-nic_wireguard
+:shortdesc: "I/O limit in bit/s for outgoing traffic (various suffixes supported, see {ref}`instances-limit-units`)"
+:type: "string"
+
+```
+
+```{config:option} limits.ingress devices-nic_wireguard
+:shortdesc: "I/O limit in bit/s for incoming traffic (various suffixes supported, see {ref}`instances-limit-units`)"
+:type: "string"
+
+```
+
+```{config:option} limits.max devices-nic_wireguard
+:shortdesc: "I/O limit in bit/s for both incoming and outgoing traffic (same as setting both limits.ingress and limits.egress)"
+:type: "string"
+
+```
+
+```{config:option} limits.priority devices-nic_wireguard
+:shortdesc: "The priority for outgoing traffic, to be used by the kernel queuing discipline to prioritize network packets"
+:type: "integer"
+
+```
+
+```{config:option} mtu devices-nic_wireguard
+:default: "parent MTU"
+:shortdesc: "The Maximum Transmit Unit (MTU) of the new interface"
+:type: "integer"
+
+```
+
+```{config:option} name devices-nic_wireguard
+:default: "kernel assigned"
+:shortdesc: "The name of the interface inside the instance"
+:type: "string"
+
+```
+
+```{config:option} network devices-nic_wireguard
+:required: "yes"
+:shortdesc: "The managed WireGuard network to link the device to"
+:type: "string"
+
+```
+
+```{config:option} vrf devices-nic_wireguard
+:shortdesc: "The VRF on the host in which the host-side interface and routes are created"
+:type: "string"
+
+```
+
+<!-- config group devices-nic_wireguard end -->
 <!-- config group devices-pci start -->
 ```{config:option} address devices-pci
 :required: "yes"
@@ -4137,6 +4258,89 @@ User keys can be used in search.
 ```
 
 <!-- config group network_sriov-common end -->
+<!-- config group network_wireguard-common start -->
+```{config:option} interface network_wireguard-common
+:condition: "-"
+:defaultdesc: "Network name"
+:shortdesc: "WireGuard interface name"
+:type: "string"
+
+```
+
+```{config:option} ipv4.address network_wireguard-common
+:condition: "-"
+:shortdesc: "Comma-separated list of IPv4 addresses and CIDR for the WireGuard interface (e.g., 10.0.0.1/24)"
+:type: "string"
+
+```
+
+```{config:option} ipv6.address network_wireguard-common
+:condition: "-"
+:shortdesc: "Comma-separated list of IPv6 addresses and CIDR for the WireGuard interface (e.g., 2001:db8::1/64)"
+:type: "string"
+
+```
+
+```{config:option} listen_port network_wireguard-common
+:condition: "-"
+:defaultdesc: "Auto-assigned by WireGuard"
+:shortdesc: "UDP port to listen on. If not specified or set to 0, WireGuard will automatically assign an available port."
+:type: "integer"
+
+```
+
+```{config:option} mtu network_wireguard-common
+:condition: "-"
+:defaultdesc: "`1420`"
+:shortdesc: "The MTU of the WireGuard interface"
+:type: "integer"
+
+```
+
+```{config:option} private_key network_wireguard-common
+:condition: "-"
+:shortdesc: "WireGuard private key (base64 encoded). If not provided, one will be generated."
+:type: "string"
+
+```
+
+```{config:option} user.* network_wireguard-common
+:shortdesc: "User-provided free-form key/value pairs"
+:type: "string"
+
+```
+
+<!-- config group network_wireguard-common end -->
+<!-- config group network_wireguard-peers start -->
+```{config:option} peers.NAME.allowed_ips network_wireguard-peers
+:condition: "-"
+:shortdesc: "Allowed IPs for peer NAME (comma-separated CIDR addresses)"
+:type: "string"
+
+```
+
+```{config:option} peers.NAME.endpoint network_wireguard-peers
+:condition: "-"
+:shortdesc: "Endpoint address for peer NAME (IP:port or hostname:port)"
+:type: "string"
+
+```
+
+```{config:option} peers.NAME.persistent_keepalive network_wireguard-peers
+:condition: "-"
+:shortdesc: "Persistent keep-alive interval in seconds for peer NAME"
+:type: "integer"
+
+```
+
+```{config:option} peers.NAME.public_key network_wireguard-peers
+:condition: "-"
+:shortdesc: "Public key of peer NAME"
+:type: "string"
+
+```
+
+<!-- config group network_wireguard-peers end -->
 <!-- config group network_zone-common start -->
 ```{config:option} dns.nameservers network_zone-common
 :required: "no"

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:
 
@@ -203,6 +204,28 @@ Note that using `none` with either `ipv4.address` or `ipv6.address` needs the ot
 There is currently no way for OVN to disable IP allocation just on IPv4 or IPv6.
 ```
 
+(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 uses an existing WireGuard network and creates a routed connection to it.
+WireGuard is a modern, fast, and secure VPN tunnel that uses state-of-the-art cryptography.
+
+WireGuard networks operate at layer 3 (network layer), making them suitable for routing traffic 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-physical)=
 ### `nictype`: `physical`
 

doc/reference/network_wireguard.md

@@ -0,0 +1,87 @@
+(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 -->
+```
+
+You can also configure peers for the `wireguard` network type. Each peer can have the following configuration options:
+
+% Include content from [config_options.txt](../config_options.txt)
+```{include} ../config_options.txt
+    :start-after: <!-- config group network_wireguard-peers start -->
+    :end-before: <!-- config group network_wireguard-peers 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.