[Openvpn-devel,v2] man: Clarify IV_HWADDR

Message ID 20210709134849.161728-1-openvpn@sf.lists.topphemmelig.net
State Accepted
Headers show
Series [Openvpn-devel,v2] man: Clarify IV_HWADDR | expand

Commit Message

David Sommerseth July 9, 2021, 3:48 a.m. UTC
From: David Sommerseth <davids@openvpn.net>

The IV_HWADDR description was only partially correct, as there are more
implementations using other values than the MAC address of the default

The intention of this value is to provide a unique identifier of the
client and on some platforms this is not possible to retrieve other than
to generate this information.

The 64 bytes limitation is an arbitrary value, it is not enforced by
OpenVPN 2.x.  But it was considered a good idea to at least have some
reasonable upper limit of how long this string can be, at least for
those implementing support for this information.

Signed-off-by: David Sommerseth <davids@openvpn.net>


v2 - Implement further clarifications from Gert
 doc/man-sections/server-options.rst | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)


Gert Doering July 9, 2021, 4:41 a.m. UTC | #1
Acked-by: Gert Doering <gert@greenie.muc.de>

Your patch has been applied to the master and release/2.5 branch.

commit 51d85a9d287f44c373eaa514c6a52e1078c27c43 (master)
commit 6204dc7cb8e1731fc0fdf6c2fcd016f9c049ac69 (release/2.5)
Author: David Sommerseth
Date:   Fri Jul 9 15:48:49 2021 +0200

     man: Clarify IV_HWADDR

     Signed-off-by: David Sommerseth <davids@openvpn.net>
     Acked-by: Gert Doering <gert@greenie.muc.de>
     Message-Id: <20210709134849.161728-1-openvpn@sf.lists.topphemmelig.net>
     URL: https://www.mail-archive.com/openvpn-devel@lists.sourceforge.net/msg22625.html
     Signed-off-by: Gert Doering <gert@greenie.muc.de>

kind regards,

Gert Doering


diff --git a/doc/man-sections/server-options.rst b/doc/man-sections/server-options.rst
index 047f2270..71547335 100644
--- a/doc/man-sections/server-options.rst
+++ b/doc/man-sections/server-options.rst
@@ -467,8 +467,14 @@  fast hardware. SSL/TLS authentication must be used in this mode.
   When ``--push-peer-info`` is enabled the additional information consists
   of the following data:
-  :code:`IV_HWADDR=<mac address>`
-        The MAC address of clients default gateway
+  :code:`IV_HWADDR=<string>`
+        This is intended to be a unique and persistent ID of the client.
+        The string value can be any readable ASCII string up to 64 bytes.
+        OpenVPN 2.x and some other implementations use the MAC address of
+        the client's interface used to reach the default gateway. If this
+        string is generated by the client, it should be consistent and
+        preserved across independent session and preferably
+        re-installations and upgrades.
   :code:`IV_SSL=<version string>`
         The ssl version used by the client, e.g.