New upstream version 2.5.4upstream/2.5.4

13 files changed, 1257 insertions, 645 deletions

diff --git a/doc/Makefile.am b/doc/Makefile.am
index e411f5f..1e4fcde 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -5,21 +5,28 @@
 #             packet encryption, packet authentication, and
 #             packet compression.
 #
-#  Copyright (C) 2002-2020 OpenVPN Inc <sales@openvpn.net>
+#  Copyright (C) 2002-2021 OpenVPN Inc <sales@openvpn.net>
 #  Copyright (C) 2006-2012 Alon Bar-Lev <alon.barlev@gmail.com>
 #
 
-MAINTAINERCLEANFILES = \
-	$(srcdir)/Makefile.in
-
 SUBDIRS = doxygen
 
+#
+# List of man and HTML pages we build when rst2man/rst2html is available
+#
+# NOTE: Remember to add source .rst files to $(dist_noinst_DATA) below
+#       This could be automated with GNU Make, but we need BSD Make support
+#
+build_man_pages = openvpn.8 openvpn-examples.5
+build_html_pages = openvpn.8.html openvpn-examples.5.html
+
 dist_doc_DATA = \
 	management-notes.txt gui-notes.txt
 
 dist_noinst_DATA = \
 	README.plugins interactive-service-notes.rst \
 	openvpn.8.rst \
+	openvpn-examples.5.rst \
 	man-sections/advanced-options.rst \
 	man-sections/client-options.rst \
 	man-sections/connection-profiles.rst \
@@ -45,33 +52,41 @@ dist_noinst_DATA = \
 	man-sections/vpn-network-options.rst \
 	man-sections/windows-options.rst
 
-openvpn.8 :
+
+######  GENERIC  RULES  ##########
+
+SUFFIXES = .8.rst .8 .8.html .5.rst .5 .5.html
+
+MAINTAINERCLEANFILES = \
+	$(srcdir)/Makefile.in
+
+.8.rst.8 .5.rst.5 :
 if HAVE_PYDOCUTILS
-	$(RST2MAN) $(srcdir)/$@.rst > $@
+	$(RST2MAN) $< > $@
 else
-	@echo "Missing python-docutils - skipping man page generation"
+	@echo "Missing python-docutils - skipping man page generation ($@)"
 endif
 
-openvpn.8.html:
+.8.rst.8.html .5.rst.5.html :
 if HAVE_PYDOCUTILS
-	$(RST2HTML) $(srcdir)/openvpn.8.rst > $@
+	$(RST2HTML) $< > $@
 else
-	@echo "Missing python-docutils - skipping man/html page generation"
+	@echo "Missing python-docutils - skipping html page generation ($@)"
 endif
 
+
 if HAVE_PYDOCUTILS
-dist_noinst_DATA += openvpn.8
-dist_html_DATA = openvpn.8.html
+dist_noinst_DATA += $(build_man_pages)
+dist_html_DATA = $(build_html_pages)
 
 # Failsafe - do not delete these files unless we can recreate them
-CLEANFILES = \
-	 openvpn.8 openvpn.8.html
+CLEANFILES = $(build_man_pages) $(build_html_pages)
 
 endif
 
 if WIN32
 else
-dist_man_MANS = openvpn.8
+dist_man_MANS = $(build_man_pages)
 endif
 
-dist-hook : openvpn.8 openvpn.8.html
+dist-hook : $(build_man_pages) $(build_html_pages)
diff --git a/doc/Makefile.in b/doc/Makefile.in
index 3d1c968..ef41a37 100644
--- a/doc/Makefile.in
+++ b/doc/Makefile.in
@@ -1,7 +1,7 @@
-# Makefile.in generated by automake 1.16.1 from Makefile.am.
+# Makefile.in generated by automake 1.16.2 from Makefile.am.
 # @configure_input@
 
-# Copyright (C) 1994-2018 Free Software Foundation, Inc.
+# Copyright (C) 1994-2020 Free Software Foundation, Inc.
 
 # This Makefile.in is free software; the Free Software Foundation
 # gives unlimited permission to copy and/or distribute it,
@@ -21,7 +21,7 @@
 #             packet encryption, packet authentication, and
 #             packet compression.
 #
-#  Copyright (C) 2002-2020 OpenVPN Inc <sales@openvpn.net>
+#  Copyright (C) 2002-2021 OpenVPN Inc <sales@openvpn.net>
 #  Copyright (C) 2006-2012 Alon Bar-Lev <alon.barlev@gmail.com>
 #
 
@@ -99,7 +99,7 @@ PRE_UNINSTALL = :
 POST_UNINSTALL = :
 build_triplet = @build@
 host_triplet = @host@
-@HAVE_PYDOCUTILS_TRUE@am__append_1 = openvpn.8
+@HAVE_PYDOCUTILS_TRUE@am__append_1 = $(build_man_pages)
 subdir = doc
 ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
 am__aclocal_m4_deps = $(top_srcdir)/m4/ax_emptyarray.m4 \
@@ -173,15 +173,16 @@ am__uninstall_files_from_dir = { \
     || { echo " ( cd '$$dir' && rm -f" $$files ")"; \
          $(am__cd) "$$dir" && rm -f $$files; }; \
   }
+man5dir = $(mandir)/man5
+am__installdirs = "$(DESTDIR)$(man5dir)" "$(DESTDIR)$(man8dir)" \
+	"$(DESTDIR)$(docdir)" "$(DESTDIR)$(htmldir)"
 man8dir = $(mandir)/man8
-am__installdirs = "$(DESTDIR)$(man8dir)" "$(DESTDIR)$(docdir)" \
-	"$(DESTDIR)$(htmldir)"
 NROFF = nroff
 MANS = $(dist_man_MANS)
-am__dist_html_DATA_DIST = openvpn.8.html
+am__dist_html_DATA_DIST = openvpn.8.html openvpn-examples.5.html
 am__dist_noinst_DATA_DIST = README.plugins \
 	interactive-service-notes.rst openvpn.8.rst \
-	man-sections/advanced-options.rst \
+	openvpn-examples.5.rst man-sections/advanced-options.rst \
 	man-sections/client-options.rst \
 	man-sections/connection-profiles.rst \
 	man-sections/encryption-options.rst man-sections/examples.rst \
@@ -198,7 +199,7 @@ am__dist_noinst_DATA_DIST = README.plugins \
 	man-sections/unsupported-options.rst \
 	man-sections/virtual-routing-and-forwarding.rst \
 	man-sections/vpn-network-options.rst \
-	man-sections/windows-options.rst openvpn.8
+	man-sections/windows-options.rst openvpn.8 openvpn-examples.5
 DATA = $(dist_doc_DATA) $(dist_html_DATA) $(dist_noinst_DATA)
 RECURSIVE_CLEAN_TARGETS = mostlyclean-recursive clean-recursive	\
   distclean-recursive maintainer-clean-recursive
@@ -425,6 +426,7 @@ plugindir = @plugindir@
 prefix = @prefix@
 program_transform_name = @program_transform_name@
 psdir = @psdir@
+runstatedir = @runstatedir@
 sampledir = @sampledir@
 sbindir = @sbindir@
 sharedstatedir = @sharedstatedir@
@@ -436,15 +438,22 @@ tmpfilesdir = @tmpfilesdir@
 top_build_prefix = @top_build_prefix@
 top_builddir = @top_builddir@
 top_srcdir = @top_srcdir@
-MAINTAINERCLEANFILES = \
-	$(srcdir)/Makefile.in
-
 SUBDIRS = doxygen
+
+#
+# List of man and HTML pages we build when rst2man/rst2html is available
+#
+# NOTE: Remember to add source .rst files to $(dist_noinst_DATA) below
+#       This could be automated with GNU Make, but we need BSD Make support
+#
+build_man_pages = openvpn.8 openvpn-examples.5
+build_html_pages = openvpn.8.html openvpn-examples.5.html
 dist_doc_DATA = \
 	management-notes.txt gui-notes.txt
 
 dist_noinst_DATA = README.plugins interactive-service-notes.rst \
-	openvpn.8.rst man-sections/advanced-options.rst \
+	openvpn.8.rst openvpn-examples.5.rst \
+	man-sections/advanced-options.rst \
 	man-sections/client-options.rst \
 	man-sections/connection-profiles.rst \
 	man-sections/encryption-options.rst man-sections/examples.rst \
@@ -462,16 +471,21 @@ dist_noinst_DATA = README.plugins interactive-service-notes.rst \
 	man-sections/virtual-routing-and-forwarding.rst \
 	man-sections/vpn-network-options.rst \
 	man-sections/windows-options.rst $(am__append_1)
-@HAVE_PYDOCUTILS_TRUE@dist_html_DATA = openvpn.8.html
 
-# Failsafe - do not delete these files unless we can recreate them
-@HAVE_PYDOCUTILS_TRUE@CLEANFILES = \
-@HAVE_PYDOCUTILS_TRUE@	 openvpn.8 openvpn.8.html
+######  GENERIC  RULES  ##########
+SUFFIXES = .8.rst .8 .8.html .5.rst .5 .5.html
+MAINTAINERCLEANFILES = \
+	$(srcdir)/Makefile.in
+
+@HAVE_PYDOCUTILS_TRUE@dist_html_DATA = $(build_html_pages)
 
-@WIN32_FALSE@dist_man_MANS = openvpn.8
+# Failsafe - do not delete these files unless we can recreate them
+@HAVE_PYDOCUTILS_TRUE@CLEANFILES = $(build_man_pages) $(build_html_pages)
+@WIN32_FALSE@dist_man_MANS = $(build_man_pages)
 all: all-recursive
 
 .SUFFIXES:
+.SUFFIXES: .8.rst .8 .8.html .5.rst .5 .5.html
 $(srcdir)/Makefile.in:  $(srcdir)/Makefile.am  $(am__configure_deps)
 	@for dep in $?; do \
 	  case '$(am__configure_deps)' in \
@@ -507,6 +521,49 @@ mostlyclean-libtool:
 
 clean-libtool:
 	-rm -rf .libs _libs
+install-man5: $(dist_man_MANS)
+	@$(NORMAL_INSTALL)
+	@list1=''; \
+	list2='$(dist_man_MANS)'; \
+	test -n "$(man5dir)" \
+	  && test -n "`echo $$list1$$list2`" \
+	  || exit 0; \
+	echo " $(MKDIR_P) '$(DESTDIR)$(man5dir)'"; \
+	$(MKDIR_P) "$(DESTDIR)$(man5dir)" || exit 1; \
+	{ for i in $$list1; do echo "$$i"; done;  \
+	if test -n "$$list2"; then \
+	  for i in $$list2; do echo "$$i"; done \
+	    | sed -n '/\.5[a-z]*$$/p'; \
+	fi; \
+	} | while read p; do \
+	  if test -f $$p; then d=; else d="$(srcdir)/"; fi; \
+	  echo "$$d$$p"; echo "$$p"; \
+	done | \
+	sed -e 'n;s,.*/,,;p;h;s,.*\.,,;s,^[^5][0-9a-z]*$$,5,;x' \
+	      -e 's,\.[0-9a-z]*$$,,;$(transform);G;s,\n,.,' | \
+	sed 'N;N;s,\n, ,g' | { \
+	list=; while read file base inst; do \
+	  if test "$$base" = "$$inst"; then list="$$list $$file"; else \
+	    echo " $(INSTALL_DATA) '$$file' '$(DESTDIR)$(man5dir)/$$inst'"; \
+	    $(INSTALL_DATA) "$$file" "$(DESTDIR)$(man5dir)/$$inst" || exit $$?; \
+	  fi; \
+	done; \
+	for i in $$list; do echo "$$i"; done | $(am__base_list) | \
+	while read files; do \
+	  test -z "$$files" || { \
+	    echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(man5dir)'"; \
+	    $(INSTALL_DATA) $$files "$(DESTDIR)$(man5dir)" || exit $$?; }; \
+	done; }
+
+uninstall-man5:
+	@$(NORMAL_UNINSTALL)
+	@list=''; test -n "$(man5dir)" || exit 0; \
+	files=`{ for i in $$list; do echo "$$i"; done; \
+	l2='$(dist_man_MANS)'; for i in $$l2; do echo "$$i"; done | \
+	  sed -n '/\.5[a-z]*$$/p'; \
+	} | sed -e 's,.*/,,;h;s,.*\.,,;s,^[^5][0-9a-z]*$$,5,;x' \
+	      -e 's,\.[0-9a-z]*$$,,;$(transform);G;s,\n,.,'`; \
+	dir='$(DESTDIR)$(man5dir)'; $(am__uninstall_files_from_dir)
 install-man8: $(dist_man_MANS)
 	@$(NORMAL_INSTALL)
 	@list1=''; \
@@ -758,7 +815,7 @@ check: check-recursive
 all-am: Makefile $(MANS) $(DATA)
 installdirs: installdirs-recursive
 installdirs-am:
-	for dir in "$(DESTDIR)$(man8dir)" "$(DESTDIR)$(docdir)" "$(DESTDIR)$(htmldir)"; do \
+	for dir in "$(DESTDIR)$(man5dir)" "$(DESTDIR)$(man8dir)" "$(DESTDIR)$(docdir)" "$(DESTDIR)$(htmldir)"; do \
 	  test -z "$$dir" || $(MKDIR_P) "$$dir"; \
 	done
 install: install-recursive
@@ -830,7 +887,7 @@ install-info: install-info-recursive
 
 install-info-am:
 
-install-man: install-man8
+install-man: install-man5 install-man8
 
 install-pdf: install-pdf-recursive
 
@@ -861,7 +918,7 @@ ps-am:
 uninstall-am: uninstall-dist_docDATA uninstall-dist_htmlDATA \
 	uninstall-man
 
-uninstall-man: uninstall-man8
+uninstall-man: uninstall-man5 uninstall-man8
 
 .MAKE: $(am__recursive_targets) install-am install-strip
 
@@ -873,26 +930,27 @@ uninstall-man: uninstall-man8
 	install-data-am install-dist_docDATA install-dist_htmlDATA \
 	install-dvi install-dvi-am install-exec install-exec-am \
 	install-html install-html-am install-info install-info-am \
-	install-man install-man8 install-pdf install-pdf-am install-ps \
-	install-ps-am install-strip installcheck installcheck-am \
-	installdirs installdirs-am maintainer-clean \
-	maintainer-clean-generic mostlyclean mostlyclean-generic \
-	mostlyclean-libtool pdf pdf-am ps ps-am tags tags-am uninstall \
-	uninstall-am uninstall-dist_docDATA uninstall-dist_htmlDATA \
-	uninstall-man uninstall-man8
+	install-man install-man5 install-man8 install-pdf \
+	install-pdf-am install-ps install-ps-am install-strip \
+	installcheck installcheck-am installdirs installdirs-am \
+	maintainer-clean maintainer-clean-generic mostlyclean \
+	mostlyclean-generic mostlyclean-libtool pdf pdf-am ps ps-am \
+	tags tags-am uninstall uninstall-am uninstall-dist_docDATA \
+	uninstall-dist_htmlDATA uninstall-man uninstall-man5 \
+	uninstall-man8
 
 .PRECIOUS: Makefile
 
 
-openvpn.8 :
-@HAVE_PYDOCUTILS_TRUE@	$(RST2MAN) $(srcdir)/$@.rst > $@
-@HAVE_PYDOCUTILS_FALSE@	@echo "Missing python-docutils - skipping man page generation"
+.8.rst.8 .5.rst.5 :
+@HAVE_PYDOCUTILS_TRUE@	$(RST2MAN) $< > $@
+@HAVE_PYDOCUTILS_FALSE@	@echo "Missing python-docutils - skipping man page generation ($@)"
 
-openvpn.8.html:
-@HAVE_PYDOCUTILS_TRUE@	$(RST2HTML) $(srcdir)/openvpn.8.rst > $@
-@HAVE_PYDOCUTILS_FALSE@	@echo "Missing python-docutils - skipping man/html page generation"
+.8.rst.8.html .5.rst.5.html :
+@HAVE_PYDOCUTILS_TRUE@	$(RST2HTML) $< > $@
+@HAVE_PYDOCUTILS_FALSE@	@echo "Missing python-docutils - skipping html page generation ($@)"
 
-dist-hook : openvpn.8 openvpn.8.html
+dist-hook : $(build_man_pages) $(build_html_pages)
 
 # Tell versions [3.59,3.63) of GNU make to not export all variables.
 # Otherwise a system limit (for SysV at least) may be exceeded.
diff --git a/doc/doxygen/Makefile.am b/doc/doxygen/Makefile.am
index 299a76c..82d909d 100644
--- a/doc/doxygen/Makefile.am
+++ b/doc/doxygen/Makefile.am
@@ -5,7 +5,7 @@
 #             packet encryption, packet authentication, and
 #             packet compression.
 #
-#  Copyright (C) 2017-2018 Fox-IT B.V. <openvpn@fox-it.com>
+#  Copyright (C) 2017-2021 Fox-IT B.V. <openvpn@foxcrypto.com>
 #
 
 MAINTAINERCLEANFILES = \
diff --git a/doc/doxygen/Makefile.in b/doc/doxygen/Makefile.in
index b1f3786..48bd413 100644
--- a/doc/doxygen/Makefile.in
+++ b/doc/doxygen/Makefile.in
@@ -1,7 +1,7 @@
-# Makefile.in generated by automake 1.16.1 from Makefile.am.
+# Makefile.in generated by automake 1.16.2 from Makefile.am.
 # @configure_input@
 
-# Copyright (C) 1994-2018 Free Software Foundation, Inc.
+# Copyright (C) 1994-2020 Free Software Foundation, Inc.
 
 # This Makefile.in is free software; the Free Software Foundation
 # gives unlimited permission to copy and/or distribute it,
@@ -21,7 +21,7 @@
 #             packet encryption, packet authentication, and
 #             packet compression.
 #
-#  Copyright (C) 2017-2018 Fox-IT B.V. <openvpn@fox-it.com>
+#  Copyright (C) 2017-2021 Fox-IT B.V. <openvpn@foxcrypto.com>
 #
 VPATH = @srcdir@
 am__is_gnu_make = { \
@@ -306,6 +306,7 @@ plugindir = @plugindir@
 prefix = @prefix@
 program_transform_name = @program_transform_name@
 psdir = @psdir@
+runstatedir = @runstatedir@
 sampledir = @sampledir@
 sbindir = @sbindir@
 sharedstatedir = @sharedstatedir@
diff --git a/doc/man-sections/client-options.rst b/doc/man-sections/client-options.rst
index af21fbc..c5b7ad9 100644
--- a/doc/man-sections/client-options.rst
+++ b/doc/man-sections/client-options.rst
@@ -50,6 +50,14 @@ configuration.
   after a failed auth. Older clients will keep using the token value and
   react according to ``--auth-retry``
 
+--auth-token-user base64username
+  Companion option to ``--auth-token``. This options allows to override
+  the username used by the client when reauthenticating with the ``auth-token``.
+  It also allows to use ``--auth-token`` in setups that normally do not use
+  username and password.
+
+  The username has to be base64 encoded.
+
 --auth-user-pass
   Authenticate with server using username/password.
 
diff --git a/doc/man-sections/server-options.rst b/doc/man-sections/server-options.rst
index 5a68945..ac0df55 100644
--- a/doc/man-sections/server-options.rst
+++ b/doc/man-sections/server-options.rst
@@ -487,11 +487,21 @@ fast hardware. SSL/TLS authentication must be used in this mode.
         The UI version of a UI if one is running, for example
         :code:`de.blinkt.openvpn 0.5.47` for the Android app.
 
+  :code:`IV_SSO=[crtext,][openurl,][proxy_url]`
+        Additional authentication methods supported by the client.
+        This may be set by the client UI/GUI using ``--setenv``
+
   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.
diff --git a/doc/management-notes.txt b/doc/management-notes.txt
index 50f0f56..c203442 100644
--- a/doc/management-notes.txt
+++ b/doc/management-notes.txt
@@ -199,7 +199,7 @@ Command examples:
 COMMAND -- kill
 ---------------
 
-In server mode, kill a particlar client instance.
+In server mode, kill a particular client instance.
 
 Command examples:
 
@@ -407,6 +407,7 @@ RECONNECTING  -- A restart has occurred.
 EXITING       -- A graceful exit is in progress.
 RESOLVE       -- (Client only) DNS lookup
 TCP_CONNECT   -- (Client only) Connecting to TCP server
+AUTH_PENDING  -- (Client only) Authentication pending
 
 Command examples:
 
@@ -437,6 +438,11 @@ Fields (e)-(h) are shown for CONNECTED state,
 (e) is available starting from OpenVPN 2.1
 (f)-(i) are available starting from OpenVPN 2.4
 
+For AUTH_PENDING, if (c) is present, it would read
+as "timeout number" where number is the number of seconds
+before authentication will timeout. It is printed as an
+unsigned integer (%u).
+
 Real-time state notifications will have a ">STATE:" prefix
 prepended to them.
 
@@ -608,55 +614,90 @@ COMMAND -- client-pending-auth  (OpenVPN 2.5 or higher)
 Instruct OpenVPN server to send AUTH_PENDING and INFO_PRE message
 to signal a pending authenticating to the client. A pending auth means
 that the connecting requires extra authentication like a one time
-password or doing a single sign one via web.
+password or doing a single sign on via web.
+
+    client-pending-auth {CID} {EXTRA} {TIMEOUT}
+
+The server will send AUTH_PENDING and INFO_PRE,{EXTRA} to the client. If the
+client supports accepting keywords to AUTH_PENDING (announced via IV_PROTO),
+TIMEOUT parameter will be also be announced to the client to allow it to modify
+its own timeout. The client is expected to inform the user that authentication
+is pending and display the extra information and also show the user the
+remaining time to complete the auth if applicable.
+
+Receiving an AUTH_PENDING message will make the client change its timeout to
+the timeout proposed by the server, even if the timeout is shorter.
+If the client does not receive a packet from the server for hand-window the
+connection times out regardless of the timeout. This ensures that the connection
+still times out relatively quickly in case of network problems. The client will
+continuously send PULL_REQUEST messages to the server until the timeout is reached.
+This message also triggers an ACK message from the server that resets the
+hand-window based timeout.
 
-    client-pending-auth {CID} {EXTRA}
+Both client and server limit the maximum timeout to the smaller value of half the
+--tls-reneg minimum time and --hand-window time (defaults to 60s).
 
-The server will send AUTH_PENDING and INFO_PRE,{EXTRA} to the client.
-The client is expected to inform the user that authentication is pending and
-display the extra information. For the format of EXTRA see below
-For the OpenVPN server this is stateless operation and needs to be
-followed by a client-deny/client-auth[-nt] command (that is the result of the
-out of band authentication).
+For the format of {EXTRA} see below. For OpenVPN server this is a stateless
+operation and needs to be followed by a client-deny/client-auth[-nt] command
+(that is the result of the out of band authentication).
 
 Before issuing a client-pending-auth to a client instead of a
 client-auth/client-deny, the server should check the IV_SSO
-environment variable if the method is support. The currently
-defined method are crtext for challenge/response using text
-(e.g. TOTP), openurl and proxy_url for opening an URL in the client to
+environment variable for whether the method is supported. Currently
+defined methods are crtext for challenge/response using text
+(e.g., TOTP), openurl and proxy_url for opening a URL in the client to
 continue authentication. A client supporting the first two methods would
 set
 
     setenv IV_SSO openurl,crtext
 
 The variable name IV_SSO is historic as AUTH_PENDING was first used
-to signal single sign on support. To keep compatiblity with existing
+to signal single sign on support. To keep compatibility with existing
 implementations the name IV_SSO is kept in lieu of a better name.
 
+The management interface of the client receives notification of
+pending auth via
+
+>STATE:datetime,AUTH_PENDING,[timeout number]
+
+If {EXTRA} is present the client is informed using INFOMSG
+notification as
+
+>INFOMSG:{EXTRA}
+
+where {EXTRA} is formatted as received from the server.
+Currently defined formats for {EXTRA} are detailed below.
+
 openurl
 ========
 For a web based extra authentication (like for
-SSO/SAML) EXTRA should be
+SSO/SAML) {EXTRA} should be
 
     OPEN_URL:url
 
-and client should ask to the user to open the URL to continue.
+and client should ask the user to open the URL to continue.
 
 The space in a control message is limited, so this url should be kept
-short to avoid issues. If a loger url is required a URL that redirects
+short to avoid issues. If a longer url is required a URL that redirects
 to the longer URL should be sent instead.
 
-url_proxy
+A complete documentation how URLs should be handled on the client is available
+in the openvpn3 repository:
+
+https://github.com/OpenVPN/openvpn3/blob/master/doc/webauth.md
+
+proxy_url
 ========
-To avoid issues with OpenVPN connection persist-tun and not able
-to reach the web server, a variant of openurl via a HTTPS
-Proxy exists. The client should announce url_proxy in its IV_SSO
-and parse the PROXY_URL message. The format is
+This is a variant of openurl that allows opening a url via an
+HTTP proxy. It could be used to avoid issues with OpenVPN connection's
+persist-tun that may cause the web server to be unreachable.
+The client should announce proxy_url in its IV_SSO and parse the
+PROXY_URL message. The format of {EXTRA} in this case is
 
     PROXY_URL:<proxy>:<proxy_port>:<proxyuser_base64>:<proxy_password_base64>:url
 
-The proxy should be a literal IPv4 address or IPv6 address in [] to avoid
-ambiguity in parsing. A literal IP address is preferred as DNS might not be 
+The proxy should be a literal IPv4 address or IPv6 address enclosed in [] to avoid
+ambiguity in parsing. A literal IP address is preferred as DNS might not be
 available when the client needs to open the url. The IP address will usually
 be the address that client uses to connect to the VPN server. For dual-homed
 VPN servers, the server should respond with the same address that the client
@@ -664,19 +705,18 @@ connects to.
 
 This address is also usually excluded from being redirected over the VPN
 by a host route. If the platform (like Android) uses another way of protecting
-the VPN connection routing loops the client needs to also exclude the
+the VPN connection from routing loops, the client needs to also exclude the
 connection to the proxy in the same manner.
 
 Should another IP be used, then the VPN configuration should include a route
-statement to exclude that route from being routed over the VPN.
+statement to exclude that address from being routed over the VPN.
 
 crtext
 =======
-
-The format of EXTRA is similar to the already used two step authentication
+The format of {EXTRA} is similar to the already used two step authentication
 described in Challenge/Response Protocol section of this document. Since
-most of the fields are not necessary or can be infered only the <flags>
-and <challgenge_text> fields are used:
+most of the fields are not necessary or can be inferred, only the <flags>
+and <challenge_text> fields are used:
 
     CR_TEXT:<flags>:<challenge_text>
 
@@ -686,7 +726,8 @@ and <challgenge_text> fields are used:
 
 <challenge_text>: the challenge text to be shown to the user.
 
-
+The client should return the response to the crtext challenge
+using the cr-response command.
 
 COMMAND -- client-deny  (OpenVPN 2.1 or higher)
 -----------------------------------------------
@@ -904,17 +945,18 @@ To accept connecting to the host and port directly, use this command:
 
 COMMAND -- cr-response (OpenVPN 2.5 or higher)
 -------------------------------------------------
-Provides support for sending responses a challenge/response
-query via INFOMSG,CR_TEXT. The response should be base64 encoded:
+Provides support for sending responses to a challenge/response
+query via INFOMSG,CR_TEXT (client-only). The response should
+be base64 encoded:
 
   cr-response SGFsbG8gV2VsdCE=
 
-The document is intended to be used after the client received a
-CR_TEXT challenge (see send-pending-auth section). The answer is
-the answer to the challenge and depends on the challenge itself
-for a TOTP challenge this would the number encoded as base64 or
-just a string for a challenge like "what day is it today?".
-
+This command is intended to be used after the client receives a
+CR_TEXT challenge (see client-pending-auth section). The argument
+to cr-response is the base64 encoded answer to the challenge and
+depends on the challenge itself. For a TOTP challenge this would be
+a number encoded as base64; for a challenge like "what day is it today?"
+it would be a string encoded as base64.
 
 COMMAND -- pk-sig (OpenVPN 2.5 or higher, management version > 1)
 COMMAND -- rsa-sig (OpenVPN 2.3 or higher, management version <= 1)
@@ -1055,6 +1097,9 @@ PASSWORD -- Used to tell the management interface client that OpenVPN
 STATE    -- Shows the current OpenVPN state, as controlled
             by the "state" command.
 
+INFOMSG  -- Authentication related info from server such as
+            CR_TEXT or OPEN_URL. See description under client-pending-auth
+
 The CLIENT notification
 -----------------------
 
@@ -1112,14 +1157,15 @@ CLIENT notification types:
    >CLIENT:ENV,...
    >CLIENT:ENV,END
 
-   Using the cr-response command on the client side will trigger this
+   Use of the cr-response command on the client side will trigger this
    message on the server side.
 
-   CR_RESPONSE notification. The >CR_RESPONSE fulfils the same purpose as the
+   CR_RESPONSE notification fulfills the same purpose as the
    CRV1 response in the traditional challenge/response. See that section
-   below for more details. Since this still uses the same cid as the original
-   response, we do not use the username and opaque session data in this
-   response but only contains the actual response.
+   below for more details. Since this uses the same cid as in the original
+   client-pending-auth challenge,  we do not include the username and opaque
+   session data in this notification. The string {response_base64} only contains
+   the actual response received from the client.
 
    It is important to note that OpenVPN2 merely passes the authentication
    information and does not do any further checks. (E.g. if a CR was issued
@@ -1127,7 +1173,7 @@ CLIENT notification types:
    data has a valid base64 encoding)
 
    This interface should be be sufficient for almost all challenge/response
-   system that can be implemented with a single round and base64 encoding the
+   system that can be implemented with a single round and base64 encoding of the
    response. Mechanisms that need multiple rounds or more complex answers
    should implement a different response type than CR_RESPONSE.
 
diff --git a/doc/openvpn-examples.5 b/doc/openvpn-examples.5
new file mode 100644
index 0000000..c9d5488
--- /dev/null
+++ b/doc/openvpn-examples.5
@@ -0,0 +1,374 @@
+.\" Man page generated from reStructuredText.
+.
+.TH OPENVPN EXAMPLES 5 "" "" "Configuration files"
+.SH NAME
+openvpn examples \- Secure IP tunnel daemon
+.
+.nr rst2man-indent-level 0
+.
+.de1 rstReportMargin
+\\$1 \\n[an-margin]
+level \\n[rst2man-indent-level]
+level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
+-
+\\n[rst2man-indent0]
+\\n[rst2man-indent1]
+\\n[rst2man-indent2]
+..
+.de1 INDENT
+.\" .rstReportMargin pre:
+. RS \\$1
+. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
+. nr rst2man-indent-level +1
+.\" .rstReportMargin post:
+..
+.de UNINDENT
+. RE
+.\" indent \\n[an-margin]
+.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.nr rst2man-indent-level -1
+.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
+..
+.SH INTRODUCTION
+.sp
+This man page gives a few simple examples to create OpenVPN setups and configuration files.
+.SH EXAMPLES
+.sp
+Prior to running these examples, you should have OpenVPN installed on
+two machines with network connectivity between them. If you have not yet
+installed OpenVPN, consult the INSTALL file included in the OpenVPN
+distribution.
+.SS Firewall Setup:
+.sp
+If firewalls exist between the two machines, they should be set to
+forward the port OpenVPN is configured to use, in both directions.
+The default for OpenVPN is 1194/udp.  If you do not have control
+over the firewalls between the two machines, you may still be able to
+use OpenVPN by adding \fB\-\-ping 15\fP to each of the \fBopenvpn\fP commands
+used below in the examples (this will cause each peer to send out a UDP
+ping to its remote peer once every 15 seconds which will cause many
+stateful firewalls to forward packets in both directions without an
+explicit firewall rule).
+.sp
+Please see your operating system guides for how to configure the firewall
+on your systems.
+.SS VPN Address Setup:
+.sp
+For purposes of our example, our two machines will be called
+\fBbob.example.com\fP and \fBalice.example.com\fP\&. If you are constructing a
+VPN over the internet, then replace \fBbob.example.com\fP and
+\fBalice.example.com\fP with the internet hostname or IP address that each
+machine will use to contact the other over the internet.
+.sp
+Now we will choose the tunnel endpoints. Tunnel endpoints are private IP
+addresses that only have meaning in the context of the VPN. Each machine
+will use the tunnel endpoint of the other machine to access it over the
+VPN. In our example, the tunnel endpoint for bob.example.com will be
+10.4.0.1 and for alice.example.com, 10.4.0.2.
+.sp
+Once the VPN is established, you have essentially created a secure
+alternate path between the two hosts which is addressed by using the
+tunnel endpoints. You can control which network traffic passes between
+the hosts (a) over the VPN or (b) independently of the VPN, by choosing
+whether to use (a) the VPN endpoint address or (b) the public internet
+address, to access the remote host. For example if you are on
+bob.example.com and you wish to connect to \fBalice.example.com\fP via
+\fBssh\fP without using the VPN (since \fBssh\fP has its own built\-in security)
+you would use the command \fBssh alice.example.com\fP\&. However in the same
+scenario, you could also use the command \fBtelnet 10.4.0.2\fP to create a
+telnet session with alice.example.com over the VPN, that would use the
+VPN to secure the session rather than \fBssh\fP\&.
+.sp
+You can use any address you wish for the tunnel endpoints but make sure
+that they are private addresses (such as those that begin with 10 or
+192.168) and that they are not part of any existing subnet on the
+networks of either peer, unless you are bridging. If you use an address
+that is part of your local subnet for either of the tunnel endpoints,
+you will get a weird feedback loop.
+.SS Example 1: A simple tunnel without security
+.sp
+On bob:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+openvpn \-\-remote alice.example.com \-\-dev tun1 \e
+         \-\-ifconfig 10.4.0.1 10.4.0.2 \-\-verb 9
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+On alice:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+openvpn \-\-remote bob.example.com \-\-dev tun1 \e
+         \-\-ifconfig 10.4.0.2 10.4.0.1 \-\-verb 9
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Now verify the tunnel is working by pinging across the tunnel.
+.sp
+On bob:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+ping 10.4.0.2
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+On alice:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+ping 10.4.0.1
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The \fB\-\-verb 9\fP option will produce verbose output, similar to the
+\fBtcpdump\fP(8) program. Omit the \fB\-\-verb 9\fP option to have OpenVPN run
+quietly.
+.SS Example 2: A tunnel with static\-key security (i.e. using a pre\-shared secret)
+.sp
+First build a static key on bob.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+openvpn \-\-genkey \-\-secret key
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+This command will build a key file called \fBkey\fP (in ascii format). Now
+copy \fBkey\fP to \fBalice.example.com\fP over a secure medium such as by using
+the \fBscp\fP(1) program.
+.sp
+On bob:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+openvpn \-\-remote alice.example.com \-\-dev tun1  \e
+         \-\-ifconfig 10.4.0.1 10.4.0.2 \-\-verb 5 \e
+         \-\-secret key
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+On alice:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+openvpn \-\-remote bob.example.com \-\-dev tun1   \e
+        \-\-ifconfig 10.4.0.2 10.4.0.1 \-\-verb 5 \e
+        \-\-secret key
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Now verify the tunnel is working by pinging across the tunnel.
+.sp
+On bob:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+ping 10.4.0.2
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+On alice:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+ping 10.4.0.1
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Example 3: A tunnel with full TLS\-based security
+.sp
+For this test, we will designate \fBbob\fP as the TLS client and \fBalice\fP
+as the TLS server.
+.INDENT 0.0
+.TP
+.B \fINote:\fP
+The client or server designation only has
+meaning for the TLS subsystem. It has no bearing on OpenVPN\(aqs
+peer\-to\-peer, UDP\-based communication model.*
+.UNINDENT
+.sp
+First, build a separate certificate/key pair for both bob and alice (see
+above where \fB\-\-cert\fP is discussed for more info). Then construct
+Diffie Hellman parameters (see above where \fB\-\-dh\fP is discussed for
+more info). You can also use the included test files \fBclient.crt\fP,
+\fBclient.key\fP, \fBserver.crt\fP, \fBserver.key\fP and
+\fBca.crt\fP\&. The \fB\&.crt\fP files are certificates/public\-keys, the
+\fB\&.key\fP files are private keys, and \fBca.crt\fP is a certification
+authority who has signed both \fBclient.crt\fP and \fBserver.crt\fP\&.
+For Diffie Hellman parameters you can use the included file
+\fBdh2048.pem\fP\&.
+.INDENT 0.0
+.TP
+.B \fIWARNING:\fP
+All client, server, and certificate authority certificates
+and keys included in the OpenVPN distribution are totally
+insecure and should be used for testing only.
+.UNINDENT
+.sp
+On bob:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+openvpn \-\-remote alice.example.com \-\-dev tun1    \e
+        \-\-ifconfig 10.4.0.1 10.4.0.2             \e
+        \-\-tls\-client \-\-ca ca.crt                 \e
+        \-\-cert client.crt \-\-key client.key       \e
+        \-\-reneg\-sec 60 \-\-verb 5
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+On alice:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+openvpn \-\-remote bob.example.com \-\-dev tun1      \e
+        \-\-ifconfig 10.4.0.2 10.4.0.1             \e
+        \-\-tls\-server \-\-dh dh1024.pem \-\-ca ca.crt \e
+        \-\-cert server.crt \-\-key server.key       \e
+        \-\-reneg\-sec 60 \-\-verb 5
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Now verify the tunnel is working by pinging across the tunnel.
+.sp
+On bob:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+ping 10.4.0.2
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+On alice:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+ping 10.4.0.1
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Notice the \fB\-\-reneg\-sec 60\fP option we used above. That tells OpenVPN
+to renegotiate the data channel keys every minute. Since we used
+\fB\-\-verb 5\fP above, you will see status information on each new key
+negotiation.
+.sp
+For production operations, a key renegotiation interval of 60 seconds is
+probably too frequent. Omit the \fB\-\-reneg\-sec 60\fP option to use
+OpenVPN\(aqs default key renegotiation interval of one hour.
+.SS Routing:
+.sp
+Assuming you can ping across the tunnel, the next step is to route a
+real subnet over the secure tunnel. Suppose that bob and alice have two
+network interfaces each, one connected to the internet, and the other to
+a private network. Our goal is to securely connect both private
+networks. We will assume that bob\(aqs private subnet is \fI10.0.0.0/24\fP and
+alice\(aqs is \fI10.0.1.0/24\fP\&.
+.sp
+First, ensure that IP forwarding is enabled on both peers. On Linux,
+enable routing:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+echo 1 > /proc/sys/net/ipv4/ip_forward
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+This setting is not persistent.  Please see your operating systems
+documentation how to properly configure IP forwarding, which is also
+persistent through system boots.
+.sp
+If your system is configured with a firewall.  Please see your operating
+systems guide on how to configure the firewall.  You typically want to
+allow traffic coming from and going to the tun/tap adapter OpenVPN is
+configured to use.
+.sp
+On bob:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+route add \-net 10.0.1.0 netmask 255.255.255.0 gw 10.4.0.2
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+On alice:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+route add \-net 10.0.0.0 netmask 255.255.255.0 gw 10.4.0.1
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Now any machine on the \fI10.0.0.0/24\fP subnet can access any machine on the
+\fI10.0.1.0/24\fP subnet over the secure tunnel (or vice versa).
+.sp
+In a production environment, you could put the route command(s) in a
+script and execute with the \fB\-\-up\fP option.
+.\" Generated by docutils manpage writer.
+.
diff --git a/doc/openvpn-examples.5.html b/doc/openvpn-examples.5.html
new file mode 100644
index 0000000..a0dac40
--- /dev/null
+++ b/doc/openvpn-examples.5.html
@@ -0,0 +1,582 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<meta name="generator" content="Docutils 0.16: http://docutils.sourceforge.net/" />
+<title>openvpn examples</title>
+<style type="text/css">
+
+/*
+:Author: David Goodger (goodger@python.org)
+:Id: $Id: html4css1.css 7952 2016-07-26 18:15:59Z milde $
+:Copyright: This stylesheet has been placed in the public domain.
+
+Default cascading style sheet for the HTML output of Docutils.
+
+See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
+customize this style sheet.
+*/
+
+/* used to remove borders from tables and images */
+.borderless, table.borderless td, table.borderless th {
+  border: 0 }
+
+table.borderless td, table.borderless th {
+  /* Override padding for "table.docutils td" with "! important".
+     The right padding separates the table cells. */
+  padding: 0 0.5em 0 0 ! important }
+
+.first {
+  /* Override more specific margin styles with "! important". */
+  margin-top: 0 ! important }
+
+.last, .with-subtitle {
+  margin-bottom: 0 ! important }
+
+.hidden {
+  display: none }
+
+.subscript {
+  vertical-align: sub;
+  font-size: smaller }
+
+.superscript {
+  vertical-align: super;
+  font-size: smaller }
+
+a.toc-backref {
+  text-decoration: none ;
+  color: black }
+
+blockquote.epigraph {
+  margin: 2em 5em ; }
+
+dl.docutils dd {
+  margin-bottom: 0.5em }
+
+object[type="image/svg+xml"], object[type="application/x-shockwave-flash"] {
+  overflow: hidden;
+}
+
+/* Uncomment (and remove this text!) to get bold-faced definition list terms
+dl.docutils dt {
+  font-weight: bold }
+*/
+
+div.abstract {
+  margin: 2em 5em }
+
+div.abstract p.topic-title {
+  font-weight: bold ;
+  text-align: center }
+
+div.admonition, div.attention, div.caution, div.danger, div.error,
+div.hint, div.important, div.note, div.tip, div.warning {
+  margin: 2em ;
+  border: medium outset ;
+  padding: 1em }
+
+div.admonition p.admonition-title, div.hint p.admonition-title,
+div.important p.admonition-title, div.note p.admonition-title,
+div.tip p.admonition-title {
+  font-weight: bold ;
+  font-family: sans-serif }
+
+div.attention p.admonition-title, div.caution p.admonition-title,
+div.danger p.admonition-title, div.error p.admonition-title,
+div.warning p.admonition-title, .code .error {
+  color: red ;
+  font-weight: bold ;
+  font-family: sans-serif }
+
+/* Uncomment (and remove this text!) to get reduced vertical space in
+   compound paragraphs.
+div.compound .compound-first, div.compound .compound-middle {
+  margin-bottom: 0.5em }
+
+div.compound .compound-last, div.compound .compound-middle {
+  margin-top: 0.5em }
+*/
+
+div.dedication {
+  margin: 2em 5em ;
+  text-align: center ;
+  font-style: italic }
+
+div.dedication p.topic-title {
+  font-weight: bold ;
+  font-style: normal }
+
+div.figure {
+  margin-left: 2em ;
+  margin-right: 2em }
+
+div.footer, div.header {
+  clear: both;
+  font-size: smaller }
+
+div.line-block {
+  display: block ;
+  margin-top: 1em ;
+  margin-bottom: 1em }
+
+div.line-block div.line-block {
+  margin-top: 0 ;
+  margin-bottom: 0 ;
+  margin-left: 1.5em }
+
+div.sidebar {
+  margin: 0 0 0.5em 1em ;
+  border: medium outset ;
+  padding: 1em ;
+  background-color: #ffffee ;
+  width: 40% ;
+  float: right ;
+  clear: right }
+
+div.sidebar p.rubric {
+  font-family: sans-serif ;
+  font-size: medium }
+
+div.system-messages {
+  margin: 5em }
+
+div.system-messages h1 {
+  color: red }
+
+div.system-message {
+  border: medium outset ;
+  padding: 1em }
+
+div.system-message p.system-message-title {
+  color: red ;
+  font-weight: bold }
+
+div.topic {
+  margin: 2em }
+
+h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
+h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
+  margin-top: 0.4em }
+
+h1.title {
+  text-align: center }
+
+h2.subtitle {
+  text-align: center }
+
+hr.docutils {
+  width: 75% }
+
+img.align-left, .figure.align-left, object.align-left, table.align-left {
+  clear: left ;
+  float: left ;
+  margin-right: 1em }
+
+img.align-right, .figure.align-right, object.align-right, table.align-right {
+  clear: right ;
+  float: right ;
+  margin-left: 1em }
+
+img.align-center, .figure.align-center, object.align-center {
+  display: block;
+  margin-left: auto;
+  margin-right: auto;
+}
+
+table.align-center {
+  margin-left: auto;
+  margin-right: auto;
+}
+
+.align-left {
+  text-align: left }
+
+.align-center {
+  clear: both ;
+  text-align: center }
+
+.align-right {
+  text-align: right }
+
+/* reset inner alignment in figures */
+div.align-right {
+  text-align: inherit }
+
+/* div.align-center * { */
+/*   text-align: left } */
+
+.align-top    {
+  vertical-align: top }
+
+.align-middle {
+  vertical-align: middle }
+
+.align-bottom {
+  vertical-align: bottom }
+
+ol.simple, ul.simple {
+  margin-bottom: 1em }
+
+ol.arabic {
+  list-style: decimal }
+
+ol.loweralpha {
+  list-style: lower-alpha }
+
+ol.upperalpha {
+  list-style: upper-alpha }
+
+ol.lowerroman {
+  list-style: lower-roman }
+
+ol.upperroman {
+  list-style: upper-roman }
+
+p.attribution {
+  text-align: right ;
+  margin-left: 50% }
+
+p.caption {
+  font-style: italic }
+
+p.credits {
+  font-style: italic ;
+  font-size: smaller }
+
+p.label {
+  white-space: nowrap }
+
+p.rubric {
+  font-weight: bold ;
+  font-size: larger ;
+  color: maroon ;
+  text-align: center }
+
+p.sidebar-title {
+  font-family: sans-serif ;
+  font-weight: bold ;
+  font-size: larger }
+
+p.sidebar-subtitle {
+  font-family: sans-serif ;
+  font-weight: bold }
+
+p.topic-title {
+  font-weight: bold }
+
+pre.address {
+  margin-bottom: 0 ;
+  margin-top: 0 ;
+  font: inherit }
+
+pre.literal-block, pre.doctest-block, pre.math, pre.code {
+  margin-left: 2em ;
+  margin-right: 2em }
+
+pre.code .ln { color: grey; } /* line numbers */
+pre.code, code { background-color: #eeeeee }
+pre.code .comment, code .comment { color: #5C6576 }
+pre.code .keyword, code .keyword { color: #3B0D06; font-weight: bold }
+pre.code .literal.string, code .literal.string { color: #0C5404 }
+pre.code .name.builtin, code .name.builtin { color: #352B84 }
+pre.code .deleted, code .deleted { background-color: #DEB0A1}
+pre.code .inserted, code .inserted { background-color: #A3D289}
+
+span.classifier {
+  font-family: sans-serif ;
+  font-style: oblique }
+
+span.classifier-delimiter {
+  font-family: sans-serif ;
+  font-weight: bold }
+
+span.interpreted {
+  font-family: sans-serif }
+
+span.option {
+  white-space: nowrap }
+
+span.pre {
+  white-space: pre }
+
+span.problematic {
+  color: red }
+
+span.section-subtitle {
+  /* font-size relative to parent (h1..h6 element) */
+  font-size: 80% }
+
+table.citation {
+  border-left: solid 1px gray;
+  margin-left: 1px }
+
+table.docinfo {
+  margin: 2em 4em }
+
+table.docutils {
+  margin-top: 0.5em ;
+  margin-bottom: 0.5em }
+
+table.footnote {
+  border-left: solid 1px black;
+  margin-left: 1px }
+
+table.docutils td, table.docutils th,
+table.docinfo td, table.docinfo th {
+  padding-left: 0.5em ;
+  padding-right: 0.5em ;
+  vertical-align: top }
+
+table.docutils th.field-name, table.docinfo th.docinfo-name {
+  font-weight: bold ;
+  text-align: left ;
+  white-space: nowrap ;
+  padding-left: 0 }
+
+/* "booktabs" style (no vertical lines) */
+table.docutils.booktabs {
+  border: 0px;
+  border-top: 2px solid;
+  border-bottom: 2px solid;
+  border-collapse: collapse;
+}
+table.docutils.booktabs * {
+  border: 0px;
+}
+table.docutils.booktabs th {
+  border-bottom: thin solid;
+  text-align: left;
+}
+
+h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
+h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
+  font-size: 100% }
+
+ul.auto-toc {
+  list-style-type: none }
+
+</style>
+</head>
+<body>
+<div class="document" id="openvpn-examples">
+<h1 class="title">openvpn examples</h1>
+<h2 class="subtitle" id="secure-ip-tunnel-daemon">Secure IP tunnel daemon</h2>
+<table class="docinfo" frame="void" rules="none">
+<col class="docinfo-name" />
+<col class="docinfo-content" />
+<tbody valign="top">
+<tr class="manual-section field"><th class="docinfo-name">Manual section:</th><td class="field-body">5</td>
+</tr>
+<tr class="manual-group field"><th class="docinfo-name">Manual group:</th><td class="field-body">Configuration files</td>
+</tr>
+</tbody>
+</table>
+<div class="section" id="introduction">
+<h1>INTRODUCTION</h1>
+<p>This man page gives a few simple examples to create OpenVPN setups and configuration files.</p>
+</div>
+<div class="section" id="examples">
+<h1>EXAMPLES</h1>
+<p>Prior to running these examples, you should have OpenVPN installed on
+two machines with network connectivity between them. If you have not yet
+installed OpenVPN, consult the INSTALL file included in the OpenVPN
+distribution.</p>
+<div class="section" id="firewall-setup">
+<h2>Firewall Setup:</h2>
+<p>If firewalls exist between the two machines, they should be set to
+forward the port OpenVPN is configured to use, in both directions.
+The default for OpenVPN is 1194/udp.  If you do not have control
+over the firewalls between the two machines, you may still be able to
+use OpenVPN by adding <tt class="docutils literal"><span class="pre">--ping</span> 15</tt> to each of the <tt class="docutils literal">openvpn</tt> commands
+used below in the examples (this will cause each peer to send out a UDP
+ping to its remote peer once every 15 seconds which will cause many
+stateful firewalls to forward packets in both directions without an
+explicit firewall rule).</p>
+<p>Please see your operating system guides for how to configure the firewall
+on your systems.</p>
+</div>
+<div class="section" id="vpn-address-setup">
+<h2>VPN Address Setup:</h2>
+<p>For purposes of our example, our two machines will be called
+<tt class="docutils literal">bob.example.com</tt> and <tt class="docutils literal">alice.example.com</tt>. If you are constructing a
+VPN over the internet, then replace <tt class="docutils literal">bob.example.com</tt> and
+<tt class="docutils literal">alice.example.com</tt> with the internet hostname or IP address that each
+machine will use to contact the other over the internet.</p>
+<p>Now we will choose the tunnel endpoints. Tunnel endpoints are private IP
+addresses that only have meaning in the context of the VPN. Each machine
+will use the tunnel endpoint of the other machine to access it over the
+VPN. In our example, the tunnel endpoint for bob.example.com will be
+10.4.0.1 and for alice.example.com, 10.4.0.2.</p>
+<p>Once the VPN is established, you have essentially created a secure
+alternate path between the two hosts which is addressed by using the
+tunnel endpoints. You can control which network traffic passes between
+the hosts (a) over the VPN or (b) independently of the VPN, by choosing
+whether to use (a) the VPN endpoint address or (b) the public internet
+address, to access the remote host. For example if you are on
+bob.example.com and you wish to connect to <tt class="docutils literal">alice.example.com</tt> via
+<tt class="docutils literal">ssh</tt> without using the VPN (since <strong>ssh</strong> has its own built-in security)
+you would use the command <tt class="docutils literal">ssh alice.example.com</tt>. However in the same
+scenario, you could also use the command <tt class="docutils literal">telnet 10.4.0.2</tt> to create a
+telnet session with alice.example.com over the VPN, that would use the
+VPN to secure the session rather than <tt class="docutils literal">ssh</tt>.</p>
+<p>You can use any address you wish for the tunnel endpoints but make sure
+that they are private addresses (such as those that begin with 10 or
+192.168) and that they are not part of any existing subnet on the
+networks of either peer, unless you are bridging. If you use an address
+that is part of your local subnet for either of the tunnel endpoints,
+you will get a weird feedback loop.</p>
+</div>
+<div class="section" id="example-1-a-simple-tunnel-without-security">
+<h2>Example 1: A simple tunnel without security</h2>
+<p>On bob:</p>
+<pre class="literal-block">
+openvpn --remote alice.example.com --dev tun1 \
+         --ifconfig 10.4.0.1 10.4.0.2 --verb 9
+</pre>
+<p>On alice:</p>
+<pre class="literal-block">
+openvpn --remote bob.example.com --dev tun1 \
+         --ifconfig 10.4.0.2 10.4.0.1 --verb 9
+</pre>
+<p>Now verify the tunnel is working by pinging across the tunnel.</p>
+<p>On bob:</p>
+<pre class="literal-block">
+ping 10.4.0.2
+</pre>
+<p>On alice:</p>
+<pre class="literal-block">
+ping 10.4.0.1
+</pre>
+<p>The <tt class="docutils literal"><span class="pre">--verb</span> 9</tt> option will produce verbose output, similar to the
+<tt class="docutils literal">tcpdump</tt>(8) program. Omit the <tt class="docutils literal"><span class="pre">--verb</span> 9</tt> option to have OpenVPN run
+quietly.</p>
+</div>
+<div class="section" id="example-2-a-tunnel-with-static-key-security-i-e-using-a-pre-shared-secret">
+<h2>Example 2: A tunnel with static-key security (i.e. using a pre-shared secret)</h2>
+<p>First build a static key on bob.</p>
+<pre class="literal-block">
+openvpn --genkey --secret key
+</pre>
+<p>This command will build a key file called <tt class="docutils literal">key</tt> (in ascii format). Now
+copy <tt class="docutils literal">key</tt> to <tt class="docutils literal">alice.example.com</tt> over a secure medium such as by using
+the <tt class="docutils literal">scp</tt>(1) program.</p>
+<p>On bob:</p>
+<pre class="literal-block">
+openvpn --remote alice.example.com --dev tun1  \
+         --ifconfig 10.4.0.1 10.4.0.2 --verb 5 \
+         --secret key
+</pre>
+<p>On alice:</p>
+<pre class="literal-block">
+openvpn --remote bob.example.com --dev tun1   \
+        --ifconfig 10.4.0.2 10.4.0.1 --verb 5 \
+        --secret key
+</pre>
+<p>Now verify the tunnel is working by pinging across the tunnel.</p>
+<p>On bob:</p>
+<pre class="literal-block">
+ping 10.4.0.2
+</pre>
+<p>On alice:</p>
+<pre class="literal-block">
+ping 10.4.0.1
+</pre>
+</div>
+<div class="section" id="example-3-a-tunnel-with-full-tls-based-security">
+<h2>Example 3: A tunnel with full TLS-based security</h2>
+<p>For this test, we will designate <tt class="docutils literal">bob</tt> as the TLS client and <tt class="docutils literal">alice</tt>
+as the TLS server.</p>
+<dl class="docutils">
+<dt><em>Note:</em></dt>
+<dd>The client or server designation only has
+meaning for the TLS subsystem. It has no bearing on OpenVPN's
+peer-to-peer, UDP-based communication model.*</dd>
+</dl>
+<p>First, build a separate certificate/key pair for both bob and alice (see
+above where <tt class="docutils literal"><span class="pre">--cert</span></tt> is discussed for more info). Then construct
+Diffie Hellman parameters (see above where <tt class="docutils literal"><span class="pre">--dh</span></tt> is discussed for
+more info). You can also use the included test files <code>client.crt</code>,
+<code>client.key</code>, <code>server.crt</code>, <code>server.key</code> and
+<code>ca.crt</code>. The <tt class="docutils literal">.crt</tt> files are certificates/public-keys, the
+<tt class="docutils literal">.key</tt> files are private keys, and <code>ca.crt</code> is a certification
+authority who has signed both <code>client.crt</code> and <code>server.crt</code>.
+For Diffie Hellman parameters you can use the included file
+<code>dh2048.pem</code>.</p>
+<dl class="docutils">
+<dt><em>WARNING:</em></dt>
+<dd>All client, server, and certificate authority certificates
+and keys included in the OpenVPN distribution are totally
+insecure and should be used for testing only.</dd>
+</dl>
+<p>On bob:</p>
+<pre class="literal-block">
+openvpn --remote alice.example.com --dev tun1    \
+        --ifconfig 10.4.0.1 10.4.0.2             \
+        --tls-client --ca ca.crt                 \
+        --cert client.crt --key client.key       \
+        --reneg-sec 60 --verb 5
+</pre>
+<p>On alice:</p>
+<pre class="literal-block">
+openvpn --remote bob.example.com --dev tun1      \
+        --ifconfig 10.4.0.2 10.4.0.1             \
+        --tls-server --dh dh1024.pem --ca ca.crt \
+        --cert server.crt --key server.key       \
+        --reneg-sec 60 --verb 5
+</pre>
+<p>Now verify the tunnel is working by pinging across the tunnel.</p>
+<p>On bob:</p>
+<pre class="literal-block">
+ping 10.4.0.2
+</pre>
+<p>On alice:</p>
+<pre class="literal-block">
+ping 10.4.0.1
+</pre>
+<p>Notice the <tt class="docutils literal"><span class="pre">--reneg-sec</span> 60</tt> option we used above. That tells OpenVPN
+to renegotiate the data channel keys every minute. Since we used
+<tt class="docutils literal"><span class="pre">--verb</span> 5</tt> above, you will see status information on each new key
+negotiation.</p>
+<p>For production operations, a key renegotiation interval of 60 seconds is
+probably too frequent. Omit the <tt class="docutils literal"><span class="pre">--reneg-sec</span> 60</tt> option to use
+OpenVPN's default key renegotiation interval of one hour.</p>
+</div>
+<div class="section" id="routing">
+<h2>Routing:</h2>
+<p>Assuming you can ping across the tunnel, the next step is to route a
+real subnet over the secure tunnel. Suppose that bob and alice have two
+network interfaces each, one connected to the internet, and the other to
+a private network. Our goal is to securely connect both private
+networks. We will assume that bob's private subnet is <em>10.0.0.0/24</em> and
+alice's is <em>10.0.1.0/24</em>.</p>
+<p>First, ensure that IP forwarding is enabled on both peers. On Linux,
+enable routing:</p>
+<pre class="literal-block">
+echo 1 &gt; /proc/sys/net/ipv4/ip_forward
+</pre>
+<p>This setting is not persistent.  Please see your operating systems
+documentation how to properly configure IP forwarding, which is also
+persistent through system boots.</p>
+<p>If your system is configured with a firewall.  Please see your operating
+systems guide on how to configure the firewall.  You typically want to
+allow traffic coming from and going to the tun/tap adapter OpenVPN is
+configured to use.</p>
+<p>On bob:</p>
+<pre class="literal-block">
+route add -net 10.0.1.0 netmask 255.255.255.0 gw 10.4.0.2
+</pre>
+<p>On alice:</p>
+<pre class="literal-block">
+route add -net 10.0.0.0 netmask 255.255.255.0 gw 10.4.0.1
+</pre>
+<p>Now any machine on the <em>10.0.0.0/24</em> subnet can access any machine on the
+<em>10.0.1.0/24</em> subnet over the secure tunnel (or vice versa).</p>
+<p>In a production environment, you could put the route command(s) in a
+script and execute with the <tt class="docutils literal"><span class="pre">--up</span></tt> option.</p>
+</div>
+</div>
+</div>
+</body>
+</html>
diff --git a/doc/openvpn-examples.5.rst b/doc/openvpn-examples.5.rst
new file mode 100644
index 0000000..988b602
--- /dev/null
+++ b/doc/openvpn-examples.5.rst
@@ -0,0 +1,17 @@
+===============================
+ openvpn examples
+===============================
+-------------------------
+ Secure IP tunnel daemon
+-------------------------
+
+:Manual section: 5
+:Manual group: Configuration files
+
+
+INTRODUCTION
+============
+
+This man page gives a few simple examples to create OpenVPN setups and configuration files.
+
+.. include:: man-sections/examples.rst
diff --git a/doc/openvpn.8 b/doc/openvpn.8
index 57d94ea..ceb6348 100644
--- a/doc/openvpn.8
+++ b/doc/openvpn.8
@@ -1031,6 +1031,14 @@ Newer clients (2.4.7+) will fall back to the original password method
 after a failed auth. Older clients will keep using the token value and
 react according to \fB\-\-auth\-retry\fP
 .TP
+.BI \-\-auth\-token\-user \ base64username
+Companion option to \fB\-\-auth\-token\fP\&. This options allows to override
+the username used by the client when reauthenticating with the \fBauth\-token\fP\&.
+It also allows to use \fB\-\-auth\-token\fP in setups that normally do not use
+username and password.
+.sp
+The username has to be base64 encoded.
+.TP
 .B \-\-auth\-user\-pass
 Authenticate with server using username/password.
 .sp
@@ -2076,14 +2084,24 @@ The client announces the list of supported ciphers configured with the
 .B \fBIV_GUI_VER=<gui_id> <version>\fP
 The UI version of a UI if one is running, for example
 \fBde.blinkt.openvpn 0.5.47\fP for the Android app.
+.TP
+.B \fBIV_SSO=[crtext,][openurl,][proxy_url]\fP
+Additional authentication methods supported by the client.
+This may be set by the client UI/GUI using \fB\-\-setenv\fP
 .UNINDENT
 .sp
 When \fB\-\-push\-peer\-info\fP is enabled the additional information consists
 of the following data:
 .INDENT 7.0
 .TP
-.B \fBIV_HWADDR=<mac address>\fP
-The MAC address of clients default gateway
+.B \fBIV_HWADDR=<string>\fP
+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\(aqs 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.
 .TP
 .B \fBIV_SSL=<version string>\fP
 The ssl version used by the client, e.g.
@@ -6637,343 +6655,6 @@ Causes OpenVPN to display its current statistics (to the syslog file if
 .B \fBSIGINT\fP, \fBSIGTERM\fP
 Causes OpenVPN to exit gracefully.
 .UNINDENT
-.SH EXAMPLES
-.sp
-Prior to running these examples, you should have OpenVPN installed on
-two machines with network connectivity between them. If you have not yet
-installed OpenVPN, consult the INSTALL file included in the OpenVPN
-distribution.
-.SS Firewall Setup:
-.sp
-If firewalls exist between the two machines, they should be set to
-forward the port OpenVPN is configured to use, in both directions.
-The default for OpenVPN is 1194/udp.  If you do not have control
-over the firewalls between the two machines, you may still be able to
-use OpenVPN by adding \fB\-\-ping 15\fP to each of the \fBopenvpn\fP commands
-used below in the examples (this will cause each peer to send out a UDP
-ping to its remote peer once every 15 seconds which will cause many
-stateful firewalls to forward packets in both directions without an
-explicit firewall rule).
-.sp
-Please see your operating system guides for how to configure the firewall
-on your systems.
-.SS VPN Address Setup:
-.sp
-For purposes of our example, our two machines will be called
-\fBbob.example.com\fP and \fBalice.example.com\fP\&. If you are constructing a
-VPN over the internet, then replace \fBbob.example.com\fP and
-\fBalice.example.com\fP with the internet hostname or IP address that each
-machine will use to contact the other over the internet.
-.sp
-Now we will choose the tunnel endpoints. Tunnel endpoints are private IP
-addresses that only have meaning in the context of the VPN. Each machine
-will use the tunnel endpoint of the other machine to access it over the
-VPN. In our example, the tunnel endpoint for bob.example.com will be
-10.4.0.1 and for alice.example.com, 10.4.0.2.
-.sp
-Once the VPN is established, you have essentially created a secure
-alternate path between the two hosts which is addressed by using the
-tunnel endpoints. You can control which network traffic passes between
-the hosts (a) over the VPN or (b) independently of the VPN, by choosing
-whether to use (a) the VPN endpoint address or (b) the public internet
-address, to access the remote host. For example if you are on
-bob.example.com and you wish to connect to \fBalice.example.com\fP via
-\fBssh\fP without using the VPN (since \fBssh\fP has its own built\-in security)
-you would use the command \fBssh alice.example.com\fP\&. However in the same
-scenario, you could also use the command \fBtelnet 10.4.0.2\fP to create a
-telnet session with alice.example.com over the VPN, that would use the
-VPN to secure the session rather than \fBssh\fP\&.
-.sp
-You can use any address you wish for the tunnel endpoints but make sure
-that they are private addresses (such as those that begin with 10 or
-192.168) and that they are not part of any existing subnet on the
-networks of either peer, unless you are bridging. If you use an address
-that is part of your local subnet for either of the tunnel endpoints,
-you will get a weird feedback loop.
-.SS Example 1: A simple tunnel without security
-.sp
-On bob:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-openvpn \-\-remote alice.example.com \-\-dev tun1 \e
-         \-\-ifconfig 10.4.0.1 10.4.0.2 \-\-verb 9
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-On alice:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-openvpn \-\-remote bob.example.com \-\-dev tun1 \e
-         \-\-ifconfig 10.4.0.2 10.4.0.1 \-\-verb 9
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-Now verify the tunnel is working by pinging across the tunnel.
-.sp
-On bob:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-ping 10.4.0.2
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-On alice:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-ping 10.4.0.1
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-The \fB\-\-verb 9\fP option will produce verbose output, similar to the
-\fBtcpdump\fP(8) program. Omit the \fB\-\-verb 9\fP option to have OpenVPN run
-quietly.
-.SS Example 2: A tunnel with static\-key security (i.e. using a pre\-shared secret)
-.sp
-First build a static key on bob.
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-openvpn \-\-genkey \-\-secret key
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-This command will build a key file called \fBkey\fP (in ascii format). Now
-copy \fBkey\fP to \fBalice.example.com\fP over a secure medium such as by using
-the \fBscp\fP(1) program.
-.sp
-On bob:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-openvpn \-\-remote alice.example.com \-\-dev tun1  \e
-         \-\-ifconfig 10.4.0.1 10.4.0.2 \-\-verb 5 \e
-         \-\-secret key
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-On alice:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-openvpn \-\-remote bob.example.com \-\-dev tun1   \e
-        \-\-ifconfig 10.4.0.2 10.4.0.1 \-\-verb 5 \e
-        \-\-secret key
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-Now verify the tunnel is working by pinging across the tunnel.
-.sp
-On bob:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-ping 10.4.0.2
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-On alice:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-ping 10.4.0.1
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.SS Example 3: A tunnel with full TLS\-based security
-.sp
-For this test, we will designate \fBbob\fP as the TLS client and \fBalice\fP
-as the TLS server.
-.INDENT 0.0
-.TP
-.B \fINote:\fP
-The client or server designation only has
-meaning for the TLS subsystem. It has no bearing on OpenVPN\(aqs
-peer\-to\-peer, UDP\-based communication model.*
-.UNINDENT
-.sp
-First, build a separate certificate/key pair for both bob and alice (see
-above where \fB\-\-cert\fP is discussed for more info). Then construct
-Diffie Hellman parameters (see above where \fB\-\-dh\fP is discussed for
-more info). You can also use the included test files \fBclient.crt\fP,
-\fBclient.key\fP, \fBserver.crt\fP, \fBserver.key\fP and
-\fBca.crt\fP\&. The \fB\&.crt\fP files are certificates/public\-keys, the
-\fB\&.key\fP files are private keys, and \fBca.crt\fP is a certification
-authority who has signed both \fBclient.crt\fP and \fBserver.crt\fP\&.
-For Diffie Hellman parameters you can use the included file
-\fBdh2048.pem\fP\&.
-.INDENT 0.0
-.TP
-.B \fIWARNING:\fP
-All client, server, and certificate authority certificates
-and keys included in the OpenVPN distribution are totally
-insecure and should be used for testing only.
-.UNINDENT
-.sp
-On bob:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-openvpn \-\-remote alice.example.com \-\-dev tun1    \e
-        \-\-ifconfig 10.4.0.1 10.4.0.2             \e
-        \-\-tls\-client \-\-ca ca.crt                 \e
-        \-\-cert client.crt \-\-key client.key       \e
-        \-\-reneg\-sec 60 \-\-verb 5
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-On alice:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-openvpn \-\-remote bob.example.com \-\-dev tun1      \e
-        \-\-ifconfig 10.4.0.2 10.4.0.1             \e
-        \-\-tls\-server \-\-dh dh1024.pem \-\-ca ca.crt \e
-        \-\-cert server.crt \-\-key server.key       \e
-        \-\-reneg\-sec 60 \-\-verb 5
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-Now verify the tunnel is working by pinging across the tunnel.
-.sp
-On bob:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-ping 10.4.0.2
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-On alice:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-ping 10.4.0.1
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-Notice the \fB\-\-reneg\-sec 60\fP option we used above. That tells OpenVPN
-to renegotiate the data channel keys every minute. Since we used
-\fB\-\-verb 5\fP above, you will see status information on each new key
-negotiation.
-.sp
-For production operations, a key renegotiation interval of 60 seconds is
-probably too frequent. Omit the \fB\-\-reneg\-sec 60\fP option to use
-OpenVPN\(aqs default key renegotiation interval of one hour.
-.SS Routing:
-.sp
-Assuming you can ping across the tunnel, the next step is to route a
-real subnet over the secure tunnel. Suppose that bob and alice have two
-network interfaces each, one connected to the internet, and the other to
-a private network. Our goal is to securely connect both private
-networks. We will assume that bob\(aqs private subnet is \fI10.0.0.0/24\fP and
-alice\(aqs is \fI10.0.1.0/24\fP\&.
-.sp
-First, ensure that IP forwarding is enabled on both peers. On Linux,
-enable routing:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-echo 1 > /proc/sys/net/ipv4/ip_forward
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-This setting is not persistent.  Please see your operating systems
-documentation how to properly configure IP forwarding, which is also
-persistent through system boots.
-.sp
-If your system is configured with a firewall.  Please see your operating
-systems guide on how to configure the firewall.  You typically want to
-allow traffic coming from and going to the tun/tap adapter OpenVPN is
-configured to use.
-.sp
-On bob:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-route add \-net 10.0.1.0 netmask 255.255.255.0 gw 10.4.0.2
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-On alice:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-route add \-net 10.0.0.0 netmask 255.255.255.0 gw 10.4.0.1
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-Now any machine on the \fI10.0.0.0/24\fP subnet can access any machine on the
-\fI10.0.1.0/24\fP subnet over the secure tunnel (or vice versa).
-.sp
-In a production environment, you could put the route command(s) in a
-script and execute with the \fB\-\-up\fP option.
 .SH FAQ
 .sp
 \fI\%https://community.openvpn.net/openvpn/wiki/FAQ\fP
@@ -6998,6 +6679,7 @@ repository.
 Report all bugs to the OpenVPN team \fI\%info@openvpn.net\fP
 .SH SEE ALSO
 .sp
+\fBopenvpn\-examples\fP(5),
 \fBdhcpcd\fP(8),
 \fBifconfig\fP(8),
 \fBopenssl\fP(1),
diff --git a/doc/openvpn.8.html b/doc/openvpn.8.html
index 6ca509d..1c0c65e 100644
--- a/doc/openvpn.8.html
+++ b/doc/openvpn.8.html
@@ -3,7 +3,7 @@
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
 <head>
 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<meta name="generator" content="Docutils 0.15.2: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.16: http://docutils.sourceforge.net/" />
 <title>openvpn</title>
 <style type="text/css">
 
@@ -1244,6 +1244,15 @@ after a failed auth. Older clients will keep using the token value and
 react according to <tt class="docutils literal"><span class="pre">--auth-retry</span></tt></p>
 </td></tr>
 <tr><td class="option-group" colspan="2">
+<kbd><span class="option">--auth-token-user <var>base64username</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Companion option to <tt class="docutils literal"><span class="pre">--auth-token</span></tt>. This options allows to override
+the username used by the client when reauthenticating with the <tt class="docutils literal"><span class="pre">auth-token</span></tt>.
+It also allows to use <tt class="docutils literal"><span class="pre">--auth-token</span></tt> in setups that normally do not use
+username and password.</p>
+<p class="last">The username has to be base64 encoded.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
 <kbd><span class="option">--auth-user-pass</span></kbd></td>
 </tr>
 <tr><td>&nbsp;</td><td><p class="first">Authenticate with server using username/password.</p>
@@ -2082,12 +2091,21 @@ the server, a value of 2 or greater indicates client supports
 <dt><code>IV_GUI_VER=&lt;gui_id&gt; &lt;version&gt;</code></dt>
 <dd>The UI version of a UI if one is running, for example
 <code>de.blinkt.openvpn 0.5.47</code> for the Android app.</dd>
+<dt><code>IV_SSO=[crtext,][openurl,][proxy_url]</code></dt>
+<dd>Additional authentication methods supported by the client.
+This may be set by the client UI/GUI using <tt class="docutils literal"><span class="pre">--setenv</span></tt></dd>
 </dl>
 <p>When <tt class="docutils literal"><span class="pre">--push-peer-info</span></tt> is enabled the additional information consists
 of the following data:</p>
 <dl class="last docutils">
-<dt><code>IV_HWADDR=&lt;mac address&gt;</code></dt>
-<dd>The MAC address of clients default gateway</dd>
+<dt><code>IV_HWADDR=&lt;string&gt;</code></dt>
+<dd>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.</dd>
 <dt><code>IV_SSL=&lt;version string&gt;</code></dt>
 <dd>The ssl version used by the client, e.g.
 <code>OpenSSL 1.0.2f 28 Jan 2016</code>.</dd>
@@ -5821,206 +5839,6 @@ See <tt class="docutils literal"><span class="pre">--ipchange</span></tt> for mo
 <dd>Causes OpenVPN to exit gracefully.</dd>
 </dl>
 </div>
-<div class="section" id="examples">
-<h1>EXAMPLES</h1>
-<p>Prior to running these examples, you should have OpenVPN installed on
-two machines with network connectivity between them. If you have not yet
-installed OpenVPN, consult the INSTALL file included in the OpenVPN
-distribution.</p>
-<div class="section" id="firewall-setup">
-<h2>Firewall Setup:</h2>
-<p>If firewalls exist between the two machines, they should be set to
-forward the port OpenVPN is configured to use, in both directions.
-The default for OpenVPN is 1194/udp.  If you do not have control
-over the firewalls between the two machines, you may still be able to
-use OpenVPN by adding <tt class="docutils literal"><span class="pre">--ping</span> 15</tt> to each of the <tt class="docutils literal">openvpn</tt> commands
-used below in the examples (this will cause each peer to send out a UDP
-ping to its remote peer once every 15 seconds which will cause many
-stateful firewalls to forward packets in both directions without an
-explicit firewall rule).</p>
-<p>Please see your operating system guides for how to configure the firewall
-on your systems.</p>
-</div>
-<div class="section" id="vpn-address-setup">
-<h2>VPN Address Setup:</h2>
-<p>For purposes of our example, our two machines will be called
-<tt class="docutils literal">bob.example.com</tt> and <tt class="docutils literal">alice.example.com</tt>. If you are constructing a
-VPN over the internet, then replace <tt class="docutils literal">bob.example.com</tt> and
-<tt class="docutils literal">alice.example.com</tt> with the internet hostname or IP address that each
-machine will use to contact the other over the internet.</p>
-<p>Now we will choose the tunnel endpoints. Tunnel endpoints are private IP
-addresses that only have meaning in the context of the VPN. Each machine
-will use the tunnel endpoint of the other machine to access it over the
-VPN. In our example, the tunnel endpoint for bob.example.com will be
-10.4.0.1 and for alice.example.com, 10.4.0.2.</p>
-<p>Once the VPN is established, you have essentially created a secure
-alternate path between the two hosts which is addressed by using the
-tunnel endpoints. You can control which network traffic passes between
-the hosts (a) over the VPN or (b) independently of the VPN, by choosing
-whether to use (a) the VPN endpoint address or (b) the public internet
-address, to access the remote host. For example if you are on
-bob.example.com and you wish to connect to <tt class="docutils literal">alice.example.com</tt> via
-<tt class="docutils literal">ssh</tt> without using the VPN (since <strong>ssh</strong> has its own built-in security)
-you would use the command <tt class="docutils literal">ssh alice.example.com</tt>. However in the same
-scenario, you could also use the command <tt class="docutils literal">telnet 10.4.0.2</tt> to create a
-telnet session with alice.example.com over the VPN, that would use the
-VPN to secure the session rather than <tt class="docutils literal">ssh</tt>.</p>
-<p>You can use any address you wish for the tunnel endpoints but make sure
-that they are private addresses (such as those that begin with 10 or
-192.168) and that they are not part of any existing subnet on the
-networks of either peer, unless you are bridging. If you use an address
-that is part of your local subnet for either of the tunnel endpoints,
-you will get a weird feedback loop.</p>
-</div>
-<div class="section" id="example-1-a-simple-tunnel-without-security">
-<h2>Example 1: A simple tunnel without security</h2>
-<p>On bob:</p>
-<pre class="literal-block">
-openvpn --remote alice.example.com --dev tun1 \
-         --ifconfig 10.4.0.1 10.4.0.2 --verb 9
-</pre>
-<p>On alice:</p>
-<pre class="literal-block">
-openvpn --remote bob.example.com --dev tun1 \
-         --ifconfig 10.4.0.2 10.4.0.1 --verb 9
-</pre>
-<p>Now verify the tunnel is working by pinging across the tunnel.</p>
-<p>On bob:</p>
-<pre class="literal-block">
-ping 10.4.0.2
-</pre>
-<p>On alice:</p>
-<pre class="literal-block">
-ping 10.4.0.1
-</pre>
-<p>The <tt class="docutils literal"><span class="pre">--verb</span> 9</tt> option will produce verbose output, similar to the
-<tt class="docutils literal">tcpdump</tt>(8) program. Omit the <tt class="docutils literal"><span class="pre">--verb</span> 9</tt> option to have OpenVPN run
-quietly.</p>
-</div>
-<div class="section" id="example-2-a-tunnel-with-static-key-security-i-e-using-a-pre-shared-secret">
-<h2>Example 2: A tunnel with static-key security (i.e. using a pre-shared secret)</h2>
-<p>First build a static key on bob.</p>
-<pre class="literal-block">
-openvpn --genkey --secret key
-</pre>
-<p>This command will build a key file called <tt class="docutils literal">key</tt> (in ascii format). Now
-copy <tt class="docutils literal">key</tt> to <tt class="docutils literal">alice.example.com</tt> over a secure medium such as by using
-the <tt class="docutils literal">scp</tt>(1) program.</p>
-<p>On bob:</p>
-<pre class="literal-block">
-openvpn --remote alice.example.com --dev tun1  \
-         --ifconfig 10.4.0.1 10.4.0.2 --verb 5 \
-         --secret key
-</pre>
-<p>On alice:</p>
-<pre class="literal-block">
-openvpn --remote bob.example.com --dev tun1   \
-        --ifconfig 10.4.0.2 10.4.0.1 --verb 5 \
-        --secret key
-</pre>
-<p>Now verify the tunnel is working by pinging across the tunnel.</p>
-<p>On bob:</p>
-<pre class="literal-block">
-ping 10.4.0.2
-</pre>
-<p>On alice:</p>
-<pre class="literal-block">
-ping 10.4.0.1
-</pre>
-</div>
-<div class="section" id="example-3-a-tunnel-with-full-tls-based-security">
-<h2>Example 3: A tunnel with full TLS-based security</h2>
-<p>For this test, we will designate <tt class="docutils literal">bob</tt> as the TLS client and <tt class="docutils literal">alice</tt>
-as the TLS server.</p>
-<dl class="docutils">
-<dt><em>Note:</em></dt>
-<dd>The client or server designation only has
-meaning for the TLS subsystem. It has no bearing on OpenVPN's
-peer-to-peer, UDP-based communication model.*</dd>
-</dl>
-<p>First, build a separate certificate/key pair for both bob and alice (see
-above where <tt class="docutils literal"><span class="pre">--cert</span></tt> is discussed for more info). Then construct
-Diffie Hellman parameters (see above where <tt class="docutils literal"><span class="pre">--dh</span></tt> is discussed for
-more info). You can also use the included test files <code>client.crt</code>,
-<code>client.key</code>, <code>server.crt</code>, <code>server.key</code> and
-<code>ca.crt</code>. The <tt class="docutils literal">.crt</tt> files are certificates/public-keys, the
-<tt class="docutils literal">.key</tt> files are private keys, and <code>ca.crt</code> is a certification
-authority who has signed both <code>client.crt</code> and <code>server.crt</code>.
-For Diffie Hellman parameters you can use the included file
-<code>dh2048.pem</code>.</p>
-<dl class="docutils">
-<dt><em>WARNING:</em></dt>
-<dd>All client, server, and certificate authority certificates
-and keys included in the OpenVPN distribution are totally
-insecure and should be used for testing only.</dd>
-</dl>
-<p>On bob:</p>
-<pre class="literal-block">
-openvpn --remote alice.example.com --dev tun1    \
-        --ifconfig 10.4.0.1 10.4.0.2             \
-        --tls-client --ca ca.crt                 \
-        --cert client.crt --key client.key       \
-        --reneg-sec 60 --verb 5
-</pre>
-<p>On alice:</p>
-<pre class="literal-block">
-openvpn --remote bob.example.com --dev tun1      \
-        --ifconfig 10.4.0.2 10.4.0.1             \
-        --tls-server --dh dh1024.pem --ca ca.crt \
-        --cert server.crt --key server.key       \
-        --reneg-sec 60 --verb 5
-</pre>
-<p>Now verify the tunnel is working by pinging across the tunnel.</p>
-<p>On bob:</p>
-<pre class="literal-block">
-ping 10.4.0.2
-</pre>
-<p>On alice:</p>
-<pre class="literal-block">
-ping 10.4.0.1
-</pre>
-<p>Notice the <tt class="docutils literal"><span class="pre">--reneg-sec</span> 60</tt> option we used above. That tells OpenVPN
-to renegotiate the data channel keys every minute. Since we used
-<tt class="docutils literal"><span class="pre">--verb</span> 5</tt> above, you will see status information on each new key
-negotiation.</p>
-<p>For production operations, a key renegotiation interval of 60 seconds is
-probably too frequent. Omit the <tt class="docutils literal"><span class="pre">--reneg-sec</span> 60</tt> option to use
-OpenVPN's default key renegotiation interval of one hour.</p>
-</div>
-<div class="section" id="routing">
-<h2>Routing:</h2>
-<p>Assuming you can ping across the tunnel, the next step is to route a
-real subnet over the secure tunnel. Suppose that bob and alice have two
-network interfaces each, one connected to the internet, and the other to
-a private network. Our goal is to securely connect both private
-networks. We will assume that bob's private subnet is <em>10.0.0.0/24</em> and
-alice's is <em>10.0.1.0/24</em>.</p>
-<p>First, ensure that IP forwarding is enabled on both peers. On Linux,
-enable routing:</p>
-<pre class="literal-block">
-echo 1 &gt; /proc/sys/net/ipv4/ip_forward
-</pre>
-<p>This setting is not persistent.  Please see your operating systems
-documentation how to properly configure IP forwarding, which is also
-persistent through system boots.</p>
-<p>If your system is configured with a firewall.  Please see your operating
-systems guide on how to configure the firewall.  You typically want to
-allow traffic coming from and going to the tun/tap adapter OpenVPN is
-configured to use.</p>
-<p>On bob:</p>
-<pre class="literal-block">
-route add -net 10.0.1.0 netmask 255.255.255.0 gw 10.4.0.2
-</pre>
-<p>On alice:</p>
-<pre class="literal-block">
-route add -net 10.0.0.0 netmask 255.255.255.0 gw 10.4.0.1
-</pre>
-<p>Now any machine on the <em>10.0.0.0/24</em> subnet can access any machine on the
-<em>10.0.1.0/24</em> subnet over the secure tunnel (or vice versa).</p>
-<p>In a production environment, you could put the route command(s) in a
-script and execute with the <tt class="docutils literal"><span class="pre">--up</span></tt> option.</p>
-</div>
-</div>
 <div class="section" id="faq">
 <h1>FAQ</h1>
 <p><a class="reference external" href="https://community.openvpn.net/openvpn/wiki/FAQ">https://community.openvpn.net/openvpn/wiki/FAQ</a></p>
@@ -6049,7 +5867,8 @@ repository.</p>
 </div>
 <div class="section" id="see-also">
 <h1>SEE ALSO</h1>
-<p><tt class="docutils literal">dhcpcd</tt>(8),
+<p><tt class="docutils literal"><span class="pre">openvpn-examples</span></tt>(5),
+<tt class="docutils literal">dhcpcd</tt>(8),
 <tt class="docutils literal">ifconfig</tt>(8),
 <tt class="docutils literal">openssl</tt>(1),
 <tt class="docutils literal">route</tt>(8),
diff --git a/doc/openvpn.8.rst b/doc/openvpn.8.rst
index db81274..9954674 100644
--- a/doc/openvpn.8.rst
+++ b/doc/openvpn.8.rst
@@ -86,7 +86,6 @@ placed in a configuration file.
 .. include:: man-sections/connection-profiles.rst
 .. include:: man-sections/inline-files.rst
 .. include:: man-sections/signals.rst
-.. include:: man-sections/examples.rst
 
 
 FAQ
@@ -134,6 +133,7 @@ Report all bugs to the OpenVPN team info@openvpn.net
 SEE ALSO
 ========
 
+``openvpn-examples``\(5),
 ``dhcpcd``\(8),
 ``ifconfig``\(8),
 ``openssl``\(1),