| # SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause) | |
| --- | |
| name: wireguard | |
| protocol: genetlink-legacy | |
| doc: | | |
| **Netlink protocol to control WireGuard network devices.** | |
| The below enums and macros are for interfacing with WireGuard, using generic | |
| netlink, with family ``WG_GENL_NAME`` and version ``WG_GENL_VERSION``. It | |
| defines two commands: get and set. Note that while they share many common | |
| attributes, these two commands actually accept a slightly different set of | |
| inputs and outputs. These differences are noted under the individual | |
| attributes. | |
| c-family-name: wg-genl-name | |
| c-version-name: wg-genl-version | |
| max-by-define: true | |
| definitions: | |
| - | |
| name-prefix: wg- | |
| name: key-len | |
| type: const | |
| value: 32 | |
| - | |
| name: --kernel-timespec | |
| type: struct | |
| header: linux/time_types.h | |
| members: | |
| - | |
| name: sec | |
| type: u64 | |
| doc: Number of seconds, since UNIX epoch. | |
| - | |
| name: nsec | |
| type: u64 | |
| doc: Number of nanoseconds, after the second began. | |
| - | |
| name: wgdevice-flags | |
| name-prefix: wgdevice-f- | |
| enum-name: wgdevice-flag | |
| type: flags | |
| entries: | |
| - replace-peers | |
| - | |
| name: wgpeer-flags | |
| name-prefix: wgpeer-f- | |
| enum-name: wgpeer-flag | |
| type: flags | |
| entries: | |
| - remove-me | |
| - replace-allowedips | |
| - update-only | |
| - | |
| name: wgallowedip-flags | |
| name-prefix: wgallowedip-f- | |
| enum-name: wgallowedip-flag | |
| type: flags | |
| entries: | |
| - remove-me | |
| attribute-sets: | |
| - | |
| name: wgdevice | |
| enum-name: wgdevice-attribute | |
| name-prefix: wgdevice-a- | |
| attr-cnt-name: --wgdevice-a-last | |
| attributes: | |
| - | |
| name: unspec | |
| type: unused | |
| value: 0 | |
| - | |
| name: ifindex | |
| type: u32 | |
| - | |
| name: ifname | |
| type: string | |
| checks: | |
| max-len: 15 | |
| - | |
| name: private-key | |
| type: binary | |
| doc: Set to all zeros to remove. | |
| display-hint: hex | |
| checks: | |
| exact-len: wg-key-len | |
| - | |
| name: public-key | |
| type: binary | |
| display-hint: hex | |
| checks: | |
| exact-len: wg-key-len | |
| - | |
| name: flags | |
| type: u32 | |
| doc: | | |
| ``0`` or ``WGDEVICE_F_REPLACE_PEERS`` if all current peers should be | |
| removed prior to adding the list below. | |
| enum: wgdevice-flags | |
| - | |
| name: listen-port | |
| type: u16 | |
| doc: Set as ``0`` to choose randomly. | |
| - | |
| name: fwmark | |
| type: u32 | |
| doc: Set as ``0`` to disable. | |
| - | |
| name: peers | |
| type: indexed-array | |
| sub-type: nest | |
| nested-attributes: wgpeer | |
| doc: | | |
| The index/type parameter is unused on ``SET_DEVICE`` operations and is | |
| zero on ``GET_DEVICE`` operations. | |
| - | |
| name: wgpeer | |
| enum-name: wgpeer-attribute | |
| name-prefix: wgpeer-a- | |
| attr-cnt-name: --wgpeer-a-last | |
| attributes: | |
| - | |
| name: unspec | |
| type: unused | |
| value: 0 | |
| - | |
| name: public-key | |
| type: binary | |
| display-hint: hex | |
| checks: | |
| exact-len: wg-key-len | |
| - | |
| name: preshared-key | |
| type: binary | |
| doc: Set as all zeros to remove. | |
| display-hint: hex | |
| checks: | |
| exact-len: wg-key-len | |
| - | |
| name: flags | |
| type: u32 | |
| doc: | | |
| ``0`` and/or ``WGPEER_F_REMOVE_ME`` if the specified peer should not | |
| exist at the end of the operation, rather than added/updated and/or | |
| ``WGPEER_F_REPLACE_ALLOWEDIPS`` if all current allowed IPs of this | |
| peer should be removed prior to adding the list below and/or | |
| ``WGPEER_F_UPDATE_ONLY`` if the peer should only be set if it already | |
| exists. | |
| enum: wgpeer-flags | |
| - | |
| name: endpoint | |
| type: binary | |
| doc: struct sockaddr_in or struct sockaddr_in6 | |
| checks: | |
| min-len: 16 | |
| - | |
| name: persistent-keepalive-interval | |
| type: u16 | |
| doc: Set as ``0`` to disable. | |
| - | |
| name: last-handshake-time | |
| type: binary | |
| struct: --kernel-timespec | |
| checks: | |
| exact-len: 16 | |
| - | |
| name: rx-bytes | |
| type: u64 | |
| - | |
| name: tx-bytes | |
| type: u64 | |
| - | |
| name: allowedips | |
| type: indexed-array | |
| sub-type: nest | |
| nested-attributes: wgallowedip | |
| doc: | | |
| The index/type parameter is unused on ``SET_DEVICE`` operations and is | |
| zero on ``GET_DEVICE`` operations. | |
| - | |
| name: protocol-version | |
| type: u32 | |
| doc: | | |
| Should not be set or used at all by most users of this API, as the | |
| most recent protocol will be used when this is unset. Otherwise, | |
| must be set to ``1``. | |
| - | |
| name: wgallowedip | |
| enum-name: wgallowedip-attribute | |
| name-prefix: wgallowedip-a- | |
| attr-cnt-name: --wgallowedip-a-last | |
| attributes: | |
| - | |
| name: unspec | |
| type: unused | |
| value: 0 | |
| - | |
| name: family | |
| type: u16 | |
| doc: IP family, either ``AF_INET`` or ``AF_INET6``. | |
| - | |
| name: ipaddr | |
| type: binary | |
| doc: Either ``struct in_addr`` or ``struct in6_addr``. | |
| display-hint: ipv4-or-v6 | |
| checks: | |
| min-len: 4 | |
| - | |
| name: cidr-mask | |
| type: u8 | |
| - | |
| name: flags | |
| type: u32 | |
| doc: | | |
| ``WGALLOWEDIP_F_REMOVE_ME`` if the specified IP should be removed; | |
| otherwise, this IP will be added if it is not already present. | |
| enum: wgallowedip-flags | |
| operations: | |
| enum-name: wg-cmd | |
| name-prefix: wg-cmd- | |
| list: | |
| - | |
| name: get-device | |
| value: 0 | |
| doc: | | |
| Retrieve WireGuard device | |
| ~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| The command should be called with one but not both of: | |
| - ``WGDEVICE_A_IFINDEX`` | |
| - ``WGDEVICE_A_IFNAME`` | |
| The kernel will then return several messages (``NLM_F_MULTI``). It is | |
| possible that all of the allowed IPs of a single peer will not fit | |
| within a single netlink message. In that case, the same peer will be | |
| written in the following message, except it will only contain | |
| ``WGPEER_A_PUBLIC_KEY`` and ``WGPEER_A_ALLOWEDIPS``. This may occur | |
| several times in a row for the same peer. It is then up to the receiver | |
| to coalesce adjacent peers. Likewise, it is possible that all peers will | |
| not fit within a single message. So, subsequent peers will be sent in | |
| following messages, except those will only contain ``WGDEVICE_A_IFNAME`` | |
| and ``WGDEVICE_A_PEERS``. It is then up to the receiver to coalesce | |
| these messages to form the complete list of peers. | |
| Since this is an ``NLA_F_DUMP`` command, the final message will always | |
| be ``NLMSG_DONE``, even if an error occurs. However, this ``NLMSG_DONE`` | |
| message contains an integer error code. It is either zero or a negative | |
| error code corresponding to the errno. | |
| attribute-set: wgdevice | |
| flags: [uns-admin-perm] | |
| dump: | |
| pre: wg-get-device-start | |
| post: wg-get-device-done | |
| request: | |
| attributes: | |
| - ifindex | |
| - ifname | |
| reply: &all-attrs | |
| attributes: | |
| - ifindex | |
| - ifname | |
| - private-key | |
| - public-key | |
| - flags | |
| - listen-port | |
| - fwmark | |
| - peers | |
| - | |
| name: set-device | |
| value: 1 | |
| doc: | | |
| Set WireGuard device | |
| ~~~~~~~~~~~~~~~~~~~~ | |
| This command should be called with a wgdevice set, containing one but | |
| not both of ``WGDEVICE_A_IFINDEX`` and ``WGDEVICE_A_IFNAME``. | |
| It is possible that the amount of configuration data exceeds that of the | |
| maximum message length accepted by the kernel. In that case, several | |
| messages should be sent one after another, with each successive one | |
| filling in information not contained in the prior. Note that if | |
| ``WGDEVICE_F_REPLACE_PEERS`` is specified in the first message, it | |
| probably should not be specified in fragments that come after, so that | |
| the list of peers is only cleared the first time but appended after. | |
| Likewise for peers, if ``WGPEER_F_REPLACE_ALLOWEDIPS`` is specified in | |
| the first message of a peer, it likely should not be specified in | |
| subsequent fragments. | |
| If an error occurs, ``NLMSG_ERROR`` will reply containing an errno. | |
| attribute-set: wgdevice | |
| flags: [uns-admin-perm] | |
| do: | |
| request: *all-attrs |