Improve documentation for override-username

- Mention that pushing auth-token-user only happens when OpenVPN also
  generates the auth-token.
- mention that OpenVPN will only accept the original and overridden username
  from a client
- suggest to use auth-token-user when a user generates the auth-token

Change-Id: Ifc7443974345042ab9945d6a10e1d1b4525e5e05
Signed-off-by: Arne Schwabe <arne@rfc2549.org>
Acked-by: Frank Lichtenheld <frank@lichtenheld.com>
Message-Id: <20250324135441.26725-1-gert@greenie.muc.de>
URL: https://www.mail-archive.com/openvpn-devel@lists.sourceforge.net/msg31210.html
Signed-off-by: Gert Doering <gert@greenie.muc.de>

diff --git a/doc/man-sections/server-options.rst b/doc/man-sections/server-options.rst
index e93b04d892b9bea926d4c280d40136d0e0a821ba..ccc13744d658e76dffb27184e0bedfd2742b2483 100644 (file)
--- a/doc/man-sections/server-options.rst
+++ b/doc/man-sections/server-options.rst
@@ -432,7 +432,12 @@ fast hardware. SSL/TLS authentication must be used in this mode.
 
   The changed username will be picked up by the status output and also by
   the ``--auth-gen-token`` option. It will also be pushed to the client
-  using ``--auth-token-user``.
+  using ``--auth-token-user`` if ``--auth-gen-token`` is enabled.
+
+  Internally on all subsequent renegotiations the client provided username
+  will be replaced by the username provided by ``--override-username``.
+  If the client changes to a username that is different from both the initial
+  and the overridden username, the client will be rejected.
 
   Special care should be taken that both the initial username of the client
   and the overridden username are handled correctly when using
@@ -444,6 +449,10 @@ fast hardware. SSL/TLS authentication must be used in this mode.
   can be used for ``--auth-gen-token`` to allow providing a username in
   these scenarios.
 
+  If the ``--auth-token`` directive is pushed by another script/plugin or
+  management interface, consider also generating and pushing
+  ``--auth-token-user``.
+
 --port-share args
   Share OpenVPN TCP with another service