.. SPDX-License-Identifier: GPL-2.0
.. NOTE: This document was auto-generated.


=====================================
Family ``ovpn`` netlink specification
=====================================


.. contents:: :depth: 3


-------
Summary
-------


Netlink protocol to control OpenVPN network devices

----------
Operations
----------


.. _ovpn-operation-peer-new:

peer-new
========
Add a remote peer

:attribute-set: :ref:`ovpn-attribute-set-ovpn`
:flags: [``admin-perm``]
:do:
    **pre**
        ovpn-nl-pre-doit

    **post**
        ovpn-nl-post-doit

    **request**
        :attributes: [``ifindex``, ``peer``]



.. _ovpn-operation-peer-set:

peer-set
========
modify a remote peer

:attribute-set: :ref:`ovpn-attribute-set-ovpn`
:flags: [``admin-perm``]
:do:
    **pre**
        ovpn-nl-pre-doit

    **post**
        ovpn-nl-post-doit

    **request**
        :attributes: [``ifindex``, ``peer``]



.. _ovpn-operation-peer-get:

peer-get
========
Retrieve data about existing remote peers (or a specific one)

:attribute-set: :ref:`ovpn-attribute-set-ovpn`
:flags: [``admin-perm``]
:do:
    **pre**
        ovpn-nl-pre-doit

    **post**
        ovpn-nl-post-doit

    **request**
        :attributes: [``ifindex``, ``peer``]

    **reply**
        :attributes: [``peer``]

:dump:
    **request**
        :attributes: [``ifindex``]

    **reply**
        :attributes: [``peer``]



.. _ovpn-operation-peer-del:

peer-del
========
Delete existing remote peer

:attribute-set: :ref:`ovpn-attribute-set-ovpn`
:flags: [``admin-perm``]
:do:
    **pre**
        ovpn-nl-pre-doit

    **post**
        ovpn-nl-post-doit

    **request**
        :attributes: [``ifindex``, ``peer``]



.. _ovpn-operation-peer-del-ntf:

peer-del-ntf
============
Notification about a peer being deleted

:notify: peer-get
:mcgrp: peers


.. _ovpn-operation-key-new:

key-new
=======
Add a cipher key for a specific peer

:attribute-set: :ref:`ovpn-attribute-set-ovpn`
:flags: [``admin-perm``]
:do:
    **pre**
        ovpn-nl-pre-doit

    **post**
        ovpn-nl-post-doit

    **request**
        :attributes: [``ifindex``, ``keyconf``]



.. _ovpn-operation-key-get:

key-get
=======
Retrieve non-sensitive data about peer key and cipher

:attribute-set: :ref:`ovpn-attribute-set-ovpn`
:flags: [``admin-perm``]
:do:
    **pre**
        ovpn-nl-pre-doit

    **post**
        ovpn-nl-post-doit

    **request**
        :attributes: [``ifindex``, ``keyconf``]

    **reply**
        :attributes: [``keyconf``]



.. _ovpn-operation-key-swap:

key-swap
========
Swap primary and secondary session keys for a specific peer

:attribute-set: :ref:`ovpn-attribute-set-ovpn`
:flags: [``admin-perm``]
:do:
    **pre**
        ovpn-nl-pre-doit

    **post**
        ovpn-nl-post-doit

    **request**
        :attributes: [``ifindex``, ``keyconf``]



.. _ovpn-operation-key-swap-ntf:

key-swap-ntf
============
Notification about key having exhausted its IV space and requiring renegotiation

:notify: key-get
:mcgrp: peers


.. _ovpn-operation-key-del:

key-del
=======
Delete cipher key for a specific peer

:attribute-set: :ref:`ovpn-attribute-set-ovpn`
:flags: [``admin-perm``]
:do:
    **pre**
        ovpn-nl-pre-doit

    **post**
        ovpn-nl-post-doit

    **request**
        :attributes: [``ifindex``, ``keyconf``]




----------------
Multicast groups
----------------


- peers

-----------
Definitions
-----------


.. _ovpn-definition-nonce-tail-size:

nonce-tail-size
===============
:type: const
:value: 8


.. _ovpn-definition-cipher-alg:

cipher-alg
==========
:type: enum


:entries:
    - ``none``
    - ``aes-gcm``
    - ``chacha20-poly1305``


.. _ovpn-definition-del-peer-reason:

del-peer-reason
===============
:type: enum


:entries:
    - ``teardown``
    - ``userspace``
    - ``expired``
    - ``transport-error``
    - ``transport-disconnect``


.. _ovpn-definition-key-slot:

key-slot
========
:type: enum


:entries:
    - ``primary``
    - ``secondary``



--------------
Attribute sets
--------------


.. _ovpn-attribute-set-peer:

peer
====
id (``u32``)
~~~~~~~~~~~~
:doc: The unique ID of the peer in the device context. To be used to identify peers during operations for a specific device


remote-ipv4 (``u32``)
~~~~~~~~~~~~~~~~~~~~~
:doc: The remote IPv4 address of the peer
:byte-order: big-endian
:display-hint: ipv4


remote-ipv6 (``binary``)
~~~~~~~~~~~~~~~~~~~~~~~~
:doc: The remote IPv6 address of the peer
:display-hint: ipv6


remote-ipv6-scope-id (``u32``)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:doc: The scope id of the remote IPv6 address of the peer (RFC2553)


remote-port (``u16``)
~~~~~~~~~~~~~~~~~~~~~
:doc: The remote port of the peer
:byte-order: big-endian


socket (``u32``)
~~~~~~~~~~~~~~~~
:doc: The socket to be used to communicate with the peer


socket-netnsid (``s32``)
~~~~~~~~~~~~~~~~~~~~~~~~
:doc: The ID of the netns the socket assigned to this peer lives in


vpn-ipv4 (``u32``)
~~~~~~~~~~~~~~~~~~
:doc: The IPv4 address assigned to the peer by the server
:byte-order: big-endian
:display-hint: ipv4


vpn-ipv6 (``binary``)
~~~~~~~~~~~~~~~~~~~~~
:doc: The IPv6 address assigned to the peer by the server
:display-hint: ipv6


local-ipv4 (``u32``)
~~~~~~~~~~~~~~~~~~~~
:doc: The local IPv4 to be used to send packets to the peer (UDP only)
:byte-order: big-endian
:display-hint: ipv4


local-ipv6 (``binary``)
~~~~~~~~~~~~~~~~~~~~~~~
:doc: The local IPv6 to be used to send packets to the peer (UDP only)
:display-hint: ipv6


local-port (``u16``)
~~~~~~~~~~~~~~~~~~~~
:doc: The local port to be used to send packets to the peer (UDP only)
:byte-order: big-endian


keepalive-interval (``u32``)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:doc: The number of seconds after which a keep alive message is sent to the peer


keepalive-timeout (``u32``)
~~~~~~~~~~~~~~~~~~~~~~~~~~~
:doc: The number of seconds from the last activity after which the peer is assumed dead


del-reason (``u32``)
~~~~~~~~~~~~~~~~~~~~
:doc: The reason why a peer was deleted
:enum: :ref:`ovpn-definition-del-peer-reason`


vpn-rx-bytes (``uint``)
~~~~~~~~~~~~~~~~~~~~~~~
:doc: Number of bytes received over the tunnel


vpn-tx-bytes (``uint``)
~~~~~~~~~~~~~~~~~~~~~~~
:doc: Number of bytes transmitted over the tunnel


vpn-rx-packets (``uint``)
~~~~~~~~~~~~~~~~~~~~~~~~~
:doc: Number of packets received over the tunnel


vpn-tx-packets (``uint``)
~~~~~~~~~~~~~~~~~~~~~~~~~
:doc: Number of packets transmitted over the tunnel


link-rx-bytes (``uint``)
~~~~~~~~~~~~~~~~~~~~~~~~
:doc: Number of bytes received at the transport level


link-tx-bytes (``uint``)
~~~~~~~~~~~~~~~~~~~~~~~~
:doc: Number of bytes transmitted at the transport level


link-rx-packets (``uint``)
~~~~~~~~~~~~~~~~~~~~~~~~~~
:doc: Number of packets received at the transport level


link-tx-packets (``uint``)
~~~~~~~~~~~~~~~~~~~~~~~~~~
:doc: Number of packets transmitted at the transport level


.. _ovpn-attribute-set-keyconf:

keyconf
=======
peer-id (``u32``)
~~~~~~~~~~~~~~~~~
:doc: The unique ID of the peer in the device context. To be used to identify peers during key operations


slot (``u32``)
~~~~~~~~~~~~~~
:doc: The slot where the key should be stored
:enum: :ref:`ovpn-definition-key-slot`


key-id (``u32``)
~~~~~~~~~~~~~~~~
:doc: The unique ID of the key in the peer context. Used to fetch the correct key upon decryption


cipher-alg (``u32``)
~~~~~~~~~~~~~~~~~~~~
:doc: The cipher to be used when communicating with the peer
:enum: :ref:`ovpn-definition-cipher-alg`


encrypt-dir (``nest``)
~~~~~~~~~~~~~~~~~~~~~~
:doc: Key material for encrypt direction
:nested-attributes: :ref:`ovpn-attribute-set-keydir`


decrypt-dir (``nest``)
~~~~~~~~~~~~~~~~~~~~~~
:doc: Key material for decrypt direction
:nested-attributes: :ref:`ovpn-attribute-set-keydir`


.. _ovpn-attribute-set-keydir:

keydir
======
cipher-key (``binary``)
~~~~~~~~~~~~~~~~~~~~~~~
:doc: The actual key to be used by the cipher


nonce-tail (``binary``)
~~~~~~~~~~~~~~~~~~~~~~~
:doc: Random nonce to be concatenated to the packet ID, in order to obtain the actual cipher IV


.. _ovpn-attribute-set-ovpn:

ovpn
====
ifindex (``u32``)
~~~~~~~~~~~~~~~~~
:doc: Index of the ovpn interface to operate on


peer (``nest``)
~~~~~~~~~~~~~~~
:doc: The peer object containing the attributed of interest for the specific operation
:nested-attributes: :ref:`ovpn-attribute-set-peer`


keyconf (``nest``)
~~~~~~~~~~~~~~~~~~
:doc: Peer specific cipher configuration
:nested-attributes: :ref:`ovpn-attribute-set-keyconf`

