| # 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 |
