summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorBernhard Schmidt <berni@debian.org>2020-09-01 16:53:32 +0200
committerBernhard Schmidt <berni@debian.org>2020-09-01 16:53:32 +0200
commit886dccf631de661ea1b4c8017de98b88b93d7f1c (patch)
tree2f74f9b3f93a35591ffdb305e3e2876cbb9a0c1d /doc
parent9ce71e1c58a83737b045861173254911fda9a76a (diff)
parent57f0b7b331088e489e93ae89ee0aed98381d8806 (diff)
Update upstream source from tag 'upstream/2.5_beta3'
Update to upstream version '2.5~beta3' with Debian dir 08bf4b8b33e73a97458e7fd53ec989aa541745cd
Diffstat (limited to 'doc')
-rw-r--r--doc/Makefile.in899
-rw-r--r--doc/README.man22
-rw-r--r--doc/android.txt101
-rw-r--r--doc/doxygen/Makefile.in532
-rw-r--r--doc/doxygen/doc_compression.h91
-rw-r--r--doc/doxygen/doc_control_processor.h184
-rw-r--r--doc/doxygen/doc_control_tls.h104
-rw-r--r--doc/doxygen/doc_data_control.h102
-rw-r--r--doc/doxygen/doc_data_crypto.h70
-rw-r--r--doc/doxygen/doc_eventloop.h66
-rw-r--r--doc/doxygen/doc_external_multiplexer.h45
-rw-r--r--doc/doxygen/doc_fragmentation.h95
-rw-r--r--doc/doxygen/doc_internal_multiplexer.h43
-rw-r--r--doc/doxygen/doc_key_generation.h148
-rw-r--r--doc/doxygen/doc_mainpage.h161
-rw-r--r--doc/doxygen/doc_memory_management.h98
-rw-r--r--doc/doxygen/doc_protocol_overview.h195
-rw-r--r--doc/doxygen/doc_reliable.h48
-rw-r--r--doc/doxygen/doc_tunnel_state.h154
-rw-r--r--doc/keying-material-exporter.txt137
-rw-r--r--doc/man-sections/cipher-negotiation.rst96
-rw-r--r--doc/man-sections/vpn-network-options.rst23
-rw-r--r--doc/openvpn.86954
-rw-r--r--doc/openvpn.8.html6023
-rw-r--r--doc/tls-crypt-v2.txt189
25 files changed, 14425 insertions, 2155 deletions
diff --git a/doc/Makefile.in b/doc/Makefile.in
new file mode 100644
index 0000000..beabdc0
--- /dev/null
+++ b/doc/Makefile.in
@@ -0,0 +1,899 @@
+# Makefile.in generated by automake 1.16.1 from Makefile.am.
+# @configure_input@
+
+# Copyright (C) 1994-2018 Free Software Foundation, Inc.
+
+# This Makefile.in is free software; the Free Software Foundation
+# gives unlimited permission to copy and/or distribute it,
+# with or without modifications, as long as this notice is preserved.
+
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY, to the extent permitted by law; without
+# even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+# PARTICULAR PURPOSE.
+
+@SET_MAKE@
+
+#
+# OpenVPN -- An application to securely tunnel IP networks
+# over a single UDP port, with support for SSL/TLS-based
+# session authentication and key exchange,
+# packet encryption, packet authentication, and
+# packet compression.
+#
+# Copyright (C) 2002-2020 OpenVPN Inc <sales@openvpn.net>
+# Copyright (C) 2006-2012 Alon Bar-Lev <alon.barlev@gmail.com>
+#
+
+VPATH = @srcdir@
+am__is_gnu_make = { \
+ if test -z '$(MAKELEVEL)'; then \
+ false; \
+ elif test -n '$(MAKE_HOST)'; then \
+ true; \
+ elif test -n '$(MAKE_VERSION)' && test -n '$(CURDIR)'; then \
+ true; \
+ else \
+ false; \
+ fi; \
+}
+am__make_running_with_option = \
+ case $${target_option-} in \
+ ?) ;; \
+ *) echo "am__make_running_with_option: internal error: invalid" \
+ "target option '$${target_option-}' specified" >&2; \
+ exit 1;; \
+ esac; \
+ has_opt=no; \
+ sane_makeflags=$$MAKEFLAGS; \
+ if $(am__is_gnu_make); then \
+ sane_makeflags=$$MFLAGS; \
+ else \
+ case $$MAKEFLAGS in \
+ *\\[\ \ ]*) \
+ bs=\\; \
+ sane_makeflags=`printf '%s\n' "$$MAKEFLAGS" \
+ | sed "s/$$bs$$bs[$$bs $$bs ]*//g"`;; \
+ esac; \
+ fi; \
+ skip_next=no; \
+ strip_trailopt () \
+ { \
+ flg=`printf '%s\n' "$$flg" | sed "s/$$1.*$$//"`; \
+ }; \
+ for flg in $$sane_makeflags; do \
+ test $$skip_next = yes && { skip_next=no; continue; }; \
+ case $$flg in \
+ *=*|--*) continue;; \
+ -*I) strip_trailopt 'I'; skip_next=yes;; \
+ -*I?*) strip_trailopt 'I';; \
+ -*O) strip_trailopt 'O'; skip_next=yes;; \
+ -*O?*) strip_trailopt 'O';; \
+ -*l) strip_trailopt 'l'; skip_next=yes;; \
+ -*l?*) strip_trailopt 'l';; \
+ -[dEDm]) skip_next=yes;; \
+ -[JT]) skip_next=yes;; \
+ esac; \
+ case $$flg in \
+ *$$target_option*) has_opt=yes; break;; \
+ esac; \
+ done; \
+ test $$has_opt = yes
+am__make_dryrun = (target_option=n; $(am__make_running_with_option))
+am__make_keepgoing = (target_option=k; $(am__make_running_with_option))
+pkgdatadir = $(datadir)/@PACKAGE@
+pkgincludedir = $(includedir)/@PACKAGE@
+pkglibdir = $(libdir)/@PACKAGE@
+pkglibexecdir = $(libexecdir)/@PACKAGE@
+am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd
+install_sh_DATA = $(install_sh) -c -m 644
+install_sh_PROGRAM = $(install_sh) -c
+install_sh_SCRIPT = $(install_sh) -c
+INSTALL_HEADER = $(INSTALL_DATA)
+transform = $(program_transform_name)
+NORMAL_INSTALL = :
+PRE_INSTALL = :
+POST_INSTALL = :
+NORMAL_UNINSTALL = :
+PRE_UNINSTALL = :
+POST_UNINSTALL = :
+build_triplet = @build@
+host_triplet = @host@
+@HAVE_PYDOCUTILS_TRUE@am__append_1 = openvpn.8
+subdir = doc
+ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
+am__aclocal_m4_deps = $(top_srcdir)/m4/ax_emptyarray.m4 \
+ $(top_srcdir)/m4/ax_socklen_t.m4 \
+ $(top_srcdir)/m4/ax_varargs.m4 $(top_srcdir)/m4/libtool.m4 \
+ $(top_srcdir)/m4/ltoptions.m4 $(top_srcdir)/m4/ltsugar.m4 \
+ $(top_srcdir)/m4/ltversion.m4 $(top_srcdir)/m4/lt~obsolete.m4 \
+ $(top_srcdir)/m4/pkg.m4 $(top_srcdir)/version.m4 \
+ $(top_srcdir)/compat.m4 $(top_srcdir)/configure.ac
+am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \
+ $(ACLOCAL_M4)
+DIST_COMMON = $(srcdir)/Makefile.am $(dist_doc_DATA) \
+ $(am__dist_html_DATA_DIST) $(am__dist_noinst_DATA_DIST) \
+ $(am__DIST_COMMON)
+mkinstalldirs = $(install_sh) -d
+CONFIG_HEADER = $(top_builddir)/config.h \
+ $(top_builddir)/include/openvpn-plugin.h
+CONFIG_CLEAN_FILES =
+CONFIG_CLEAN_VPATH_FILES =
+AM_V_P = $(am__v_P_@AM_V@)
+am__v_P_ = $(am__v_P_@AM_DEFAULT_V@)
+am__v_P_0 = false
+am__v_P_1 = :
+AM_V_GEN = $(am__v_GEN_@AM_V@)
+am__v_GEN_ = $(am__v_GEN_@AM_DEFAULT_V@)
+am__v_GEN_0 = @echo " GEN " $@;
+am__v_GEN_1 =
+AM_V_at = $(am__v_at_@AM_V@)
+am__v_at_ = $(am__v_at_@AM_DEFAULT_V@)
+am__v_at_0 = @
+am__v_at_1 =
+SOURCES =
+DIST_SOURCES =
+RECURSIVE_TARGETS = all-recursive check-recursive cscopelist-recursive \
+ ctags-recursive dvi-recursive html-recursive info-recursive \
+ install-data-recursive install-dvi-recursive \
+ install-exec-recursive install-html-recursive \
+ install-info-recursive install-pdf-recursive \
+ install-ps-recursive install-recursive installcheck-recursive \
+ installdirs-recursive pdf-recursive ps-recursive \
+ tags-recursive uninstall-recursive
+am__can_run_installinfo = \
+ case $$AM_UPDATE_INFO_DIR in \
+ n|no|NO) false;; \
+ *) (install-info --version) >/dev/null 2>&1;; \
+ esac
+am__vpath_adj_setup = srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`;
+am__vpath_adj = case $$p in \
+ $(srcdir)/*) f=`echo "$$p" | sed "s|^$$srcdirstrip/||"`;; \
+ *) f=$$p;; \
+ esac;
+am__strip_dir = f=`echo $$p | sed -e 's|^.*/||'`;
+am__install_max = 40
+am__nobase_strip_setup = \
+ srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*|]/\\\\&/g'`
+am__nobase_strip = \
+ for p in $$list; do echo "$$p"; done | sed -e "s|$$srcdirstrip/||"
+am__nobase_list = $(am__nobase_strip_setup); \
+ for p in $$list; do echo "$$p $$p"; done | \
+ sed "s| $$srcdirstrip/| |;"' / .*\//!s/ .*/ ./; s,\( .*\)/[^/]*$$,\1,' | \
+ $(AWK) 'BEGIN { files["."] = "" } { files[$$2] = files[$$2] " " $$1; \
+ if (++n[$$2] == $(am__install_max)) \
+ { print $$2, files[$$2]; n[$$2] = 0; files[$$2] = "" } } \
+ END { for (dir in files) print dir, files[dir] }'
+am__base_list = \
+ sed '$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;s/\n/ /g' | \
+ sed '$$!N;$$!N;$$!N;$$!N;s/\n/ /g'
+am__uninstall_files_from_dir = { \
+ test -z "$$files" \
+ || { test ! -d "$$dir" && test ! -f "$$dir" && test ! -r "$$dir"; } \
+ || { echo " ( cd '$$dir' && rm -f" $$files ")"; \
+ $(am__cd) "$$dir" && rm -f $$files; }; \
+ }
+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_noinst_DATA_DIST = README.plugins \
+ interactive-service-notes.rst openvpn.8.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 \
+ man-sections/generic-options.rst man-sections/inline-files.rst \
+ man-sections/link-options.rst man-sections/log-options.rst \
+ man-sections/management-options.rst \
+ man-sections/network-config.rst \
+ man-sections/pkcs11-options.rst \
+ man-sections/plugin-options.rst \
+ man-sections/protocol-options.rst \
+ man-sections/proxy-options.rst man-sections/renegotiation.rst \
+ man-sections/signals.rst man-sections/script-options.rst \
+ man-sections/server-options.rst man-sections/tls-options.rst \
+ 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
+DATA = $(dist_doc_DATA) $(dist_html_DATA) $(dist_noinst_DATA)
+RECURSIVE_CLEAN_TARGETS = mostlyclean-recursive clean-recursive \
+ distclean-recursive maintainer-clean-recursive
+am__recursive_targets = \
+ $(RECURSIVE_TARGETS) \
+ $(RECURSIVE_CLEAN_TARGETS) \
+ $(am__extra_recursive_targets)
+AM_RECURSIVE_TARGETS = $(am__recursive_targets:-recursive=) TAGS CTAGS \
+ distdir distdir-am
+am__tagged_files = $(HEADERS) $(SOURCES) $(TAGS_FILES) $(LISP)
+# Read a list of newline-separated strings from the standard input,
+# and print each of them once, without duplicates. Input order is
+# *not* preserved.
+am__uniquify_input = $(AWK) '\
+ BEGIN { nonempty = 0; } \
+ { items[$$0] = 1; nonempty = 1; } \
+ END { if (nonempty) { for (i in items) print i; }; } \
+'
+# Make sure the list of sources is unique. This is necessary because,
+# e.g., the same source file might be shared among _SOURCES variables
+# for different programs/libraries.
+am__define_uniq_tagged_files = \
+ list='$(am__tagged_files)'; \
+ unique=`for i in $$list; do \
+ if test -f "$$i"; then echo $$i; else echo $(srcdir)/$$i; fi; \
+ done | $(am__uniquify_input)`
+ETAGS = etags
+CTAGS = ctags
+DIST_SUBDIRS = $(SUBDIRS)
+am__DIST_COMMON = $(dist_man_MANS) $(srcdir)/Makefile.in
+DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST)
+am__relativize = \
+ dir0=`pwd`; \
+ sed_first='s,^\([^/]*\)/.*$$,\1,'; \
+ sed_rest='s,^[^/]*/*,,'; \
+ sed_last='s,^.*/\([^/]*\)$$,\1,'; \
+ sed_butlast='s,/*[^/]*$$,,'; \
+ while test -n "$$dir1"; do \
+ first=`echo "$$dir1" | sed -e "$$sed_first"`; \
+ if test "$$first" != "."; then \
+ if test "$$first" = ".."; then \
+ dir2=`echo "$$dir0" | sed -e "$$sed_last"`/"$$dir2"; \
+ dir0=`echo "$$dir0" | sed -e "$$sed_butlast"`; \
+ else \
+ first2=`echo "$$dir2" | sed -e "$$sed_first"`; \
+ if test "$$first2" = "$$first"; then \
+ dir2=`echo "$$dir2" | sed -e "$$sed_rest"`; \
+ else \
+ dir2="../$$dir2"; \
+ fi; \
+ dir0="$$dir0"/"$$first"; \
+ fi; \
+ fi; \
+ dir1=`echo "$$dir1" | sed -e "$$sed_rest"`; \
+ done; \
+ reldir="$$dir2"
+ACLOCAL = @ACLOCAL@
+AMTAR = @AMTAR@
+AM_DEFAULT_VERBOSITY = @AM_DEFAULT_VERBOSITY@
+AR = @AR@
+AS = @AS@
+AUTOCONF = @AUTOCONF@
+AUTOHEADER = @AUTOHEADER@
+AUTOMAKE = @AUTOMAKE@
+AWK = @AWK@
+CC = @CC@
+CCDEPMODE = @CCDEPMODE@
+CFLAGS = @CFLAGS@
+CMOCKA_CFLAGS = @CMOCKA_CFLAGS@
+CMOCKA_LIBS = @CMOCKA_LIBS@
+CPP = @CPP@
+CPPFLAGS = @CPPFLAGS@
+CYGPATH_W = @CYGPATH_W@
+DEFS = @DEFS@
+DEPDIR = @DEPDIR@
+DLLTOOL = @DLLTOOL@
+DL_LIBS = @DL_LIBS@
+DSYMUTIL = @DSYMUTIL@
+DUMPBIN = @DUMPBIN@
+ECHO_C = @ECHO_C@
+ECHO_N = @ECHO_N@
+ECHO_T = @ECHO_T@
+EGREP = @EGREP@
+ENABLE_UNITTESTS = @ENABLE_UNITTESTS@
+EXEEXT = @EXEEXT@
+FGREP = @FGREP@
+GIT = @GIT@
+GREP = @GREP@
+IFCONFIG = @IFCONFIG@
+INSTALL = @INSTALL@
+INSTALL_DATA = @INSTALL_DATA@
+INSTALL_PROGRAM = @INSTALL_PROGRAM@
+INSTALL_SCRIPT = @INSTALL_SCRIPT@
+INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@
+IPROUTE = @IPROUTE@
+LD = @LD@
+LDFLAGS = @LDFLAGS@
+LIBOBJS = @LIBOBJS@
+LIBPAM_CFLAGS = @LIBPAM_CFLAGS@
+LIBPAM_LIBS = @LIBPAM_LIBS@
+LIBS = @LIBS@
+LIBTOOL = @LIBTOOL@
+LIPO = @LIPO@
+LN_S = @LN_S@
+LTLIBOBJS = @LTLIBOBJS@
+LT_SYS_LIBRARY_PATH = @LT_SYS_LIBRARY_PATH@
+LZ4_CFLAGS = @LZ4_CFLAGS@
+LZ4_LIBS = @LZ4_LIBS@
+LZO_CFLAGS = @LZO_CFLAGS@
+LZO_LIBS = @LZO_LIBS@
+MAKEINFO = @MAKEINFO@
+MANIFEST_TOOL = @MANIFEST_TOOL@
+MBEDTLS_CFLAGS = @MBEDTLS_CFLAGS@
+MBEDTLS_LIBS = @MBEDTLS_LIBS@
+MKDIR_P = @MKDIR_P@
+NETSTAT = @NETSTAT@
+NM = @NM@
+NMEDIT = @NMEDIT@
+OBJDUMP = @OBJDUMP@
+OBJEXT = @OBJEXT@
+OPENSSL_CFLAGS = @OPENSSL_CFLAGS@
+OPENSSL_LIBS = @OPENSSL_LIBS@
+OPENVPN_VERSION_MAJOR = @OPENVPN_VERSION_MAJOR@
+OPENVPN_VERSION_MINOR = @OPENVPN_VERSION_MINOR@
+OPENVPN_VERSION_PATCH = @OPENVPN_VERSION_PATCH@
+OPTIONAL_CRYPTO_CFLAGS = @OPTIONAL_CRYPTO_CFLAGS@
+OPTIONAL_CRYPTO_LIBS = @OPTIONAL_CRYPTO_LIBS@
+OPTIONAL_DL_LIBS = @OPTIONAL_DL_LIBS@
+OPTIONAL_INOTIFY_CFLAGS = @OPTIONAL_INOTIFY_CFLAGS@
+OPTIONAL_INOTIFY_LIBS = @OPTIONAL_INOTIFY_LIBS@
+OPTIONAL_LZ4_CFLAGS = @OPTIONAL_LZ4_CFLAGS@
+OPTIONAL_LZ4_LIBS = @OPTIONAL_LZ4_LIBS@
+OPTIONAL_LZO_CFLAGS = @OPTIONAL_LZO_CFLAGS@
+OPTIONAL_LZO_LIBS = @OPTIONAL_LZO_LIBS@
+OPTIONAL_PKCS11_HELPER_CFLAGS = @OPTIONAL_PKCS11_HELPER_CFLAGS@
+OPTIONAL_PKCS11_HELPER_LIBS = @OPTIONAL_PKCS11_HELPER_LIBS@
+OPTIONAL_SELINUX_LIBS = @OPTIONAL_SELINUX_LIBS@
+OPTIONAL_SYSTEMD_LIBS = @OPTIONAL_SYSTEMD_LIBS@
+OTOOL = @OTOOL@
+OTOOL64 = @OTOOL64@
+P11KIT_CFLAGS = @P11KIT_CFLAGS@
+P11KIT_LIBS = @P11KIT_LIBS@
+PACKAGE = @PACKAGE@
+PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@
+PACKAGE_NAME = @PACKAGE_NAME@
+PACKAGE_STRING = @PACKAGE_STRING@
+PACKAGE_TARNAME = @PACKAGE_TARNAME@
+PACKAGE_URL = @PACKAGE_URL@
+PACKAGE_VERSION = @PACKAGE_VERSION@
+PATH_SEPARATOR = @PATH_SEPARATOR@
+PKCS11_HELPER_CFLAGS = @PKCS11_HELPER_CFLAGS@
+PKCS11_HELPER_LIBS = @PKCS11_HELPER_LIBS@
+PKG_CONFIG = @PKG_CONFIG@
+PKG_CONFIG_LIBDIR = @PKG_CONFIG_LIBDIR@
+PKG_CONFIG_PATH = @PKG_CONFIG_PATH@
+PLUGINDIR = @PLUGINDIR@
+PLUGIN_AUTH_PAM_CFLAGS = @PLUGIN_AUTH_PAM_CFLAGS@
+PLUGIN_AUTH_PAM_LIBS = @PLUGIN_AUTH_PAM_LIBS@
+RANLIB = @RANLIB@
+RC = @RC@
+ROUTE = @ROUTE@
+RST2HTML = @RST2HTML@
+RST2MAN = @RST2MAN@
+SED = @SED@
+SELINUX_LIBS = @SELINUX_LIBS@
+SET_MAKE = @SET_MAKE@
+SHELL = @SHELL@
+SOCKETS_LIBS = @SOCKETS_LIBS@
+STRIP = @STRIP@
+SYSTEMD_ASK_PASSWORD = @SYSTEMD_ASK_PASSWORD@
+SYSTEMD_UNIT_DIR = @SYSTEMD_UNIT_DIR@
+TAP_CFLAGS = @TAP_CFLAGS@
+TAP_WIN_COMPONENT_ID = @TAP_WIN_COMPONENT_ID@
+TAP_WIN_MIN_MAJOR = @TAP_WIN_MIN_MAJOR@
+TAP_WIN_MIN_MINOR = @TAP_WIN_MIN_MINOR@
+TEST_CFLAGS = @TEST_CFLAGS@
+TEST_LDFLAGS = @TEST_LDFLAGS@
+TMPFILES_DIR = @TMPFILES_DIR@
+VERSION = @VERSION@
+abs_builddir = @abs_builddir@
+abs_srcdir = @abs_srcdir@
+abs_top_builddir = @abs_top_builddir@
+abs_top_srcdir = @abs_top_srcdir@
+ac_ct_AR = @ac_ct_AR@
+ac_ct_CC = @ac_ct_CC@
+ac_ct_DUMPBIN = @ac_ct_DUMPBIN@
+am__include = @am__include@
+am__leading_dot = @am__leading_dot@
+am__quote = @am__quote@
+am__tar = @am__tar@
+am__untar = @am__untar@
+bindir = @bindir@
+build = @build@
+build_alias = @build_alias@
+build_cpu = @build_cpu@
+build_os = @build_os@
+build_vendor = @build_vendor@
+builddir = @builddir@
+datadir = @datadir@
+datarootdir = @datarootdir@
+docdir = @docdir@
+dvidir = @dvidir@
+exec_prefix = @exec_prefix@
+host = @host@
+host_alias = @host_alias@
+host_cpu = @host_cpu@
+host_os = @host_os@
+host_vendor = @host_vendor@
+htmldir = @htmldir@
+includedir = @includedir@
+infodir = @infodir@
+install_sh = @install_sh@
+libdir = @libdir@
+libexecdir = @libexecdir@
+libsystemd_CFLAGS = @libsystemd_CFLAGS@
+libsystemd_LIBS = @libsystemd_LIBS@
+localedir = @localedir@
+localstatedir = @localstatedir@
+mandir = @mandir@
+mkdir_p = @mkdir_p@
+oldincludedir = @oldincludedir@
+pdfdir = @pdfdir@
+plugindir = @plugindir@
+prefix = @prefix@
+program_transform_name = @program_transform_name@
+psdir = @psdir@
+sampledir = @sampledir@
+sbindir = @sbindir@
+sharedstatedir = @sharedstatedir@
+srcdir = @srcdir@
+sysconfdir = @sysconfdir@
+systemdunitdir = @systemdunitdir@
+target_alias = @target_alias@
+tmpfilesdir = @tmpfilesdir@
+top_build_prefix = @top_build_prefix@
+top_builddir = @top_builddir@
+top_srcdir = @top_srcdir@
+MAINTAINERCLEANFILES = \
+ $(srcdir)/Makefile.in
+
+SUBDIRS = doxygen
+dist_doc_DATA = \
+ management-notes.txt
+
+dist_noinst_DATA = README.plugins interactive-service-notes.rst \
+ openvpn.8.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 \
+ man-sections/generic-options.rst man-sections/inline-files.rst \
+ man-sections/link-options.rst man-sections/log-options.rst \
+ man-sections/management-options.rst \
+ man-sections/network-config.rst \
+ man-sections/pkcs11-options.rst \
+ man-sections/plugin-options.rst \
+ man-sections/protocol-options.rst \
+ man-sections/proxy-options.rst man-sections/renegotiation.rst \
+ man-sections/signals.rst man-sections/script-options.rst \
+ man-sections/server-options.rst man-sections/tls-options.rst \
+ man-sections/unsupported-options.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
+
+@HAVE_PYDOCUTILS_TRUE@@WIN32_FALSE@dist_man_MANS = openvpn.8
+all: all-recursive
+
+.SUFFIXES:
+$(srcdir)/Makefile.in: $(srcdir)/Makefile.am $(am__configure_deps)
+ @for dep in $?; do \
+ case '$(am__configure_deps)' in \
+ *$$dep*) \
+ ( cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh ) \
+ && { if test -f $@; then exit 0; else break; fi; }; \
+ exit 1;; \
+ esac; \
+ done; \
+ echo ' cd $(top_srcdir) && $(AUTOMAKE) --foreign doc/Makefile'; \
+ $(am__cd) $(top_srcdir) && \
+ $(AUTOMAKE) --foreign doc/Makefile
+Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status
+ @case '$?' in \
+ *config.status*) \
+ cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh;; \
+ *) \
+ echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__maybe_remake_depfiles)'; \
+ cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__maybe_remake_depfiles);; \
+ esac;
+
+$(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES)
+ cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
+
+$(top_srcdir)/configure: $(am__configure_deps)
+ cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
+$(ACLOCAL_M4): $(am__aclocal_m4_deps)
+ cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
+$(am__aclocal_m4_deps):
+
+mostlyclean-libtool:
+ -rm -f *.lo
+
+clean-libtool:
+ -rm -rf .libs _libs
+install-man8: $(dist_man_MANS)
+ @$(NORMAL_INSTALL)
+ @list1=''; \
+ list2='$(dist_man_MANS)'; \
+ test -n "$(man8dir)" \
+ && test -n "`echo $$list1$$list2`" \
+ || exit 0; \
+ echo " $(MKDIR_P) '$(DESTDIR)$(man8dir)'"; \
+ $(MKDIR_P) "$(DESTDIR)$(man8dir)" || 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 '/\.8[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,^[^8][0-9a-z]*$$,8,;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)$(man8dir)/$$inst'"; \
+ $(INSTALL_DATA) "$$file" "$(DESTDIR)$(man8dir)/$$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)$(man8dir)'"; \
+ $(INSTALL_DATA) $$files "$(DESTDIR)$(man8dir)" || exit $$?; }; \
+ done; }
+
+uninstall-man8:
+ @$(NORMAL_UNINSTALL)
+ @list=''; test -n "$(man8dir)" || 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 '/\.8[a-z]*$$/p'; \
+ } | sed -e 's,.*/,,;h;s,.*\.,,;s,^[^8][0-9a-z]*$$,8,;x' \
+ -e 's,\.[0-9a-z]*$$,,;$(transform);G;s,\n,.,'`; \
+ dir='$(DESTDIR)$(man8dir)'; $(am__uninstall_files_from_dir)
+install-dist_docDATA: $(dist_doc_DATA)
+ @$(NORMAL_INSTALL)
+ @list='$(dist_doc_DATA)'; test -n "$(docdir)" || list=; \
+ if test -n "$$list"; then \
+ echo " $(MKDIR_P) '$(DESTDIR)$(docdir)'"; \
+ $(MKDIR_P) "$(DESTDIR)$(docdir)" || exit 1; \
+ fi; \
+ for p in $$list; do \
+ if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \
+ echo "$$d$$p"; \
+ done | $(am__base_list) | \
+ while read files; do \
+ echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(docdir)'"; \
+ $(INSTALL_DATA) $$files "$(DESTDIR)$(docdir)" || exit $$?; \
+ done
+
+uninstall-dist_docDATA:
+ @$(NORMAL_UNINSTALL)
+ @list='$(dist_doc_DATA)'; test -n "$(docdir)" || list=; \
+ files=`for p in $$list; do echo $$p; done | sed -e 's|^.*/||'`; \
+ dir='$(DESTDIR)$(docdir)'; $(am__uninstall_files_from_dir)
+install-dist_htmlDATA: $(dist_html_DATA)
+ @$(NORMAL_INSTALL)
+ @list='$(dist_html_DATA)'; test -n "$(htmldir)" || list=; \
+ if test -n "$$list"; then \
+ echo " $(MKDIR_P) '$(DESTDIR)$(htmldir)'"; \
+ $(MKDIR_P) "$(DESTDIR)$(htmldir)" || exit 1; \
+ fi; \
+ for p in $$list; do \
+ if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \
+ echo "$$d$$p"; \
+ done | $(am__base_list) | \
+ while read files; do \
+ echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(htmldir)'"; \
+ $(INSTALL_DATA) $$files "$(DESTDIR)$(htmldir)" || exit $$?; \
+ done
+
+uninstall-dist_htmlDATA:
+ @$(NORMAL_UNINSTALL)
+ @list='$(dist_html_DATA)'; test -n "$(htmldir)" || list=; \
+ files=`for p in $$list; do echo $$p; done | sed -e 's|^.*/||'`; \
+ dir='$(DESTDIR)$(htmldir)'; $(am__uninstall_files_from_dir)
+
+# This directory's subdirectories are mostly independent; you can cd
+# into them and run 'make' without going through this Makefile.
+# To change the values of 'make' variables: instead of editing Makefiles,
+# (1) if the variable is set in 'config.status', edit 'config.status'
+# (which will cause the Makefiles to be regenerated when you run 'make');
+# (2) otherwise, pass the desired values on the 'make' command line.
+$(am__recursive_targets):
+ @fail=; \
+ if $(am__make_keepgoing); then \
+ failcom='fail=yes'; \
+ else \
+ failcom='exit 1'; \
+ fi; \
+ dot_seen=no; \
+ target=`echo $@ | sed s/-recursive//`; \
+ case "$@" in \
+ distclean-* | maintainer-clean-*) list='$(DIST_SUBDIRS)' ;; \
+ *) list='$(SUBDIRS)' ;; \
+ esac; \
+ for subdir in $$list; do \
+ echo "Making $$target in $$subdir"; \
+ if test "$$subdir" = "."; then \
+ dot_seen=yes; \
+ local_target="$$target-am"; \
+ else \
+ local_target="$$target"; \
+ fi; \
+ ($(am__cd) $$subdir && $(MAKE) $(AM_MAKEFLAGS) $$local_target) \
+ || eval $$failcom; \
+ done; \
+ if test "$$dot_seen" = "no"; then \
+ $(MAKE) $(AM_MAKEFLAGS) "$$target-am" || exit 1; \
+ fi; test -z "$$fail"
+
+ID: $(am__tagged_files)
+ $(am__define_uniq_tagged_files); mkid -fID $$unique
+tags: tags-recursive
+TAGS: tags
+
+tags-am: $(TAGS_DEPENDENCIES) $(am__tagged_files)
+ set x; \
+ here=`pwd`; \
+ if ($(ETAGS) --etags-include --version) >/dev/null 2>&1; then \
+ include_option=--etags-include; \
+ empty_fix=.; \
+ else \
+ include_option=--include; \
+ empty_fix=; \
+ fi; \
+ list='$(SUBDIRS)'; for subdir in $$list; do \
+ if test "$$subdir" = .; then :; else \
+ test ! -f $$subdir/TAGS || \
+ set "$$@" "$$include_option=$$here/$$subdir/TAGS"; \
+ fi; \
+ done; \
+ $(am__define_uniq_tagged_files); \
+ shift; \
+ if test -z "$(ETAGS_ARGS)$$*$$unique"; then :; else \
+ test -n "$$unique" || unique=$$empty_fix; \
+ if test $$# -gt 0; then \
+ $(ETAGS) $(ETAGSFLAGS) $(AM_ETAGSFLAGS) $(ETAGS_ARGS) \
+ "$$@" $$unique; \
+ else \
+ $(ETAGS) $(ETAGSFLAGS) $(AM_ETAGSFLAGS) $(ETAGS_ARGS) \
+ $$unique; \
+ fi; \
+ fi
+ctags: ctags-recursive
+
+CTAGS: ctags
+ctags-am: $(TAGS_DEPENDENCIES) $(am__tagged_files)
+ $(am__define_uniq_tagged_files); \
+ test -z "$(CTAGS_ARGS)$$unique" \
+ || $(CTAGS) $(CTAGSFLAGS) $(AM_CTAGSFLAGS) $(CTAGS_ARGS) \
+ $$unique
+
+GTAGS:
+ here=`$(am__cd) $(top_builddir) && pwd` \
+ && $(am__cd) $(top_srcdir) \
+ && gtags -i $(GTAGS_ARGS) "$$here"
+cscopelist: cscopelist-recursive
+
+cscopelist-am: $(am__tagged_files)
+ list='$(am__tagged_files)'; \
+ case "$(srcdir)" in \
+ [\\/]* | ?:[\\/]*) sdir="$(srcdir)" ;; \
+ *) sdir=$(subdir)/$(srcdir) ;; \
+ esac; \
+ for i in $$list; do \
+ if test -f "$$i"; then \
+ echo "$(subdir)/$$i"; \
+ else \
+ echo "$$sdir/$$i"; \
+ fi; \
+ done >> $(top_builddir)/cscope.files
+
+distclean-tags:
+ -rm -f TAGS ID GTAGS GRTAGS GSYMS GPATH tags
+
+distdir: $(BUILT_SOURCES)
+ $(MAKE) $(AM_MAKEFLAGS) distdir-am
+
+distdir-am: $(DISTFILES)
+ @srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \
+ topsrcdirstrip=`echo "$(top_srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \
+ list='$(DISTFILES)'; \
+ dist_files=`for file in $$list; do echo $$file; done | \
+ sed -e "s|^$$srcdirstrip/||;t" \
+ -e "s|^$$topsrcdirstrip/|$(top_builddir)/|;t"`; \
+ case $$dist_files in \
+ */*) $(MKDIR_P) `echo "$$dist_files" | \
+ sed '/\//!d;s|^|$(distdir)/|;s,/[^/]*$$,,' | \
+ sort -u` ;; \
+ esac; \
+ for file in $$dist_files; do \
+ if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \
+ if test -d $$d/$$file; then \
+ dir=`echo "/$$file" | sed -e 's,/[^/]*$$,,'`; \
+ if test -d "$(distdir)/$$file"; then \
+ find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \
+ fi; \
+ if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \
+ cp -fpR $(srcdir)/$$file "$(distdir)$$dir" || exit 1; \
+ find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \
+ fi; \
+ cp -fpR $$d/$$file "$(distdir)$$dir" || exit 1; \
+ else \
+ test -f "$(distdir)/$$file" \
+ || cp -p $$d/$$file "$(distdir)/$$file" \
+ || exit 1; \
+ fi; \
+ done
+ @list='$(DIST_SUBDIRS)'; for subdir in $$list; do \
+ if test "$$subdir" = .; then :; else \
+ $(am__make_dryrun) \
+ || test -d "$(distdir)/$$subdir" \
+ || $(MKDIR_P) "$(distdir)/$$subdir" \
+ || exit 1; \
+ dir1=$$subdir; dir2="$(distdir)/$$subdir"; \
+ $(am__relativize); \
+ new_distdir=$$reldir; \
+ dir1=$$subdir; dir2="$(top_distdir)"; \
+ $(am__relativize); \
+ new_top_distdir=$$reldir; \
+ echo " (cd $$subdir && $(MAKE) $(AM_MAKEFLAGS) top_distdir="$$new_top_distdir" distdir="$$new_distdir" \\"; \
+ echo " am__remove_distdir=: am__skip_length_check=: am__skip_mode_fix=: distdir)"; \
+ ($(am__cd) $$subdir && \
+ $(MAKE) $(AM_MAKEFLAGS) \
+ top_distdir="$$new_top_distdir" \
+ distdir="$$new_distdir" \
+ am__remove_distdir=: \
+ am__skip_length_check=: \
+ am__skip_mode_fix=: \
+ distdir) \
+ || exit 1; \
+ fi; \
+ done
+ $(MAKE) $(AM_MAKEFLAGS) \
+ top_distdir="$(top_distdir)" distdir="$(distdir)" \
+ dist-hook
+check-am: all-am
+check: check-recursive
+all-am: Makefile $(MANS) $(DATA)
+installdirs: installdirs-recursive
+installdirs-am:
+ for dir in "$(DESTDIR)$(man8dir)" "$(DESTDIR)$(docdir)" "$(DESTDIR)$(htmldir)"; do \
+ test -z "$$dir" || $(MKDIR_P) "$$dir"; \
+ done
+install: install-recursive
+install-exec: install-exec-recursive
+install-data: install-data-recursive
+uninstall: uninstall-recursive
+
+install-am: all-am
+ @$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am
+
+installcheck: installcheck-recursive
+install-strip:
+ if test -z '$(STRIP)'; then \
+ $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \
+ install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \
+ install; \
+ else \
+ $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \
+ install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \
+ "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'" install; \
+ fi
+mostlyclean-generic:
+
+clean-generic:
+ -test -z "$(CLEANFILES)" || rm -f $(CLEANFILES)
+
+distclean-generic:
+ -test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES)
+ -test . = "$(srcdir)" || test -z "$(CONFIG_CLEAN_VPATH_FILES)" || rm -f $(CONFIG_CLEAN_VPATH_FILES)
+
+maintainer-clean-generic:
+ @echo "This command is intended for maintainers to use"
+ @echo "it deletes files that may require special tools to rebuild."
+ -test -z "$(MAINTAINERCLEANFILES)" || rm -f $(MAINTAINERCLEANFILES)
+clean: clean-recursive
+
+clean-am: clean-generic clean-libtool mostlyclean-am
+
+distclean: distclean-recursive
+ -rm -f Makefile
+distclean-am: clean-am distclean-generic distclean-tags
+
+dvi: dvi-recursive
+
+dvi-am:
+
+html: html-recursive
+
+html-am:
+
+info: info-recursive
+
+info-am:
+
+install-data-am: install-dist_docDATA install-dist_htmlDATA \
+ install-man
+
+install-dvi: install-dvi-recursive
+
+install-dvi-am:
+
+install-exec-am:
+
+install-html: install-html-recursive
+
+install-html-am:
+
+install-info: install-info-recursive
+
+install-info-am:
+
+install-man: install-man8
+
+install-pdf: install-pdf-recursive
+
+install-pdf-am:
+
+install-ps: install-ps-recursive
+
+install-ps-am:
+
+installcheck-am:
+
+maintainer-clean: maintainer-clean-recursive
+ -rm -f Makefile
+maintainer-clean-am: distclean-am maintainer-clean-generic
+
+mostlyclean: mostlyclean-recursive
+
+mostlyclean-am: mostlyclean-generic mostlyclean-libtool
+
+pdf: pdf-recursive
+
+pdf-am:
+
+ps: ps-recursive
+
+ps-am:
+
+uninstall-am: uninstall-dist_docDATA uninstall-dist_htmlDATA \
+ uninstall-man
+
+uninstall-man: uninstall-man8
+
+.MAKE: $(am__recursive_targets) install-am install-strip
+
+.PHONY: $(am__recursive_targets) CTAGS GTAGS TAGS all all-am check \
+ check-am clean clean-generic clean-libtool cscopelist-am ctags \
+ ctags-am dist-hook distclean distclean-generic \
+ distclean-libtool distclean-tags distdir dvi dvi-am html \
+ html-am info info-am install install-am install-data \
+ 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
+
+.PRECIOUS: Makefile
+
+
+openvpn.8 :
+@HAVE_PYDOCUTILS_TRUE@ $(RST2MAN) $(srcdir)/$@.rst > $@
+@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"
+
+dist-hook : openvpn.8 openvpn.8.html
+
+# 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.
+.NOEXPORT:
diff --git a/doc/README.man b/doc/README.man
deleted file mode 100644
index 29654c1..0000000
--- a/doc/README.man
+++ /dev/null
@@ -1,22 +0,0 @@
-
-man page documentation
-======================
-
-The man page content maintained in the openvpn.8.rst file and proper man and
-the html version of the man page are generated using python-docutils. Both
-the man page and html file are generated during 'make dist' or 'make distcheck'
-and should be distributed inside the tarball by default.
-
-Users compiling OpenVPN from the tarball should not need to regenerate the
-man/html files unless the source file needs to be modified.
-
-Further information:
-
-* Python docutils project:
- https://docutils.sourceforge.io/
-
-* Quickstart on .rst
- https://docutils.sourceforge.io/docs/user/rst/quickstart.html
-
-* reStructuredText Markup Specifictaion (.rst)
- https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html
diff --git a/doc/android.txt b/doc/android.txt
deleted file mode 100644
index e287be0..0000000
--- a/doc/android.txt
+++ /dev/null
@@ -1,101 +0,0 @@
-This file documents the support in OpenVPN for Android 4.0 and up.
-
-This support is primarily used in the "OpenVPN for Android" app
-(https://github.com/schwabe/ics-openvpn). For building see the developer
-README: https://github.com/schwabe/ics-openvpn/blob/master/doc/README.txt
-
-Android provides the VPNService API
-(http://developer.android.com/reference/android/net/VpnService.html)
-which allows establishing VPN connections without rooting the device.
-
-Since all the interfaces are are Android specific the calls to this
-interface are made from the UI instead of OpenVPN directly. The API
-needs the following parameters:
-
-- IP and netmask of tun interface
-- Networks that should be routed to the tun interface
-- DNS Servers and DNS Domain
-- MTU
-
-All IPs/Routes are in CIDR style. Non CIDR routes are not supported.
-Notable is the lack of support for setting routes to other interfaces
-usually used to avoid the server connection going over the tun
-interface. The Android VPNService API has the concept of protecting
-a socket from being routed over a interface. Calling protect (fd)
-will internally bind the socket to the interface used for the
-external connection (usually WiFi or mobile data).
-
-To use OpenVPN with the VPNService API OpenVPN must be build with
-the TARGET_ANDROID compile option. Also the UI must use a UNIX
-domain socket to connect to OpenVPN. When compiled as TARGET_ANDROID
-OpenVPN will use management callbacks instead of executing traditional
-ifconfig/route commands use the need-ok callback mechanism which
-will ask
-
-> NEED-OK command
-
-where command can be:
-
-IFCONFIG6 IPv6/netmask
-IFCONFIG local remoteOrNetmask MTU topology
-
-To tell the UI which IPs addresses OpenVPN expects on the interface.
-Topology is one of "net30","p2p","subnet" or "undef".
-
-ROUTE6 network/netmask
-ROUTE network netmask
-
-To tell the UI which routes should be set on the tun interface.
-
-DNSSERVER IP server address
-DNS6SERVER IPv6 server address
-DNSDOMAIN searchdomain
-
-To set the DNS server and search domain.
-
-The GUI will then respond with a "needok 'command' ok' or "needok
-'command' cancel', e.g. "needok 'IFCONFIG' ok".
-
-PERSIST_TUN_ACTION
-
-In Android 4.4-4.4.2 a bug exists that does not allow to open a new tun fd
-while a tun fd is still open. When OpenVPN wants to open an fd it will do
-this query. The UI should compare the last configuration of
-the tun device with the current tun configuration and reply with either (or
-always respond with OPEN_AFTER_BEFORE/OPEN_BEFORE_CLOSE)
-
-- NOACTION: Keep using the old fd
-- OPEN_AFTER_CLOSE: First close the old fd and then open a new to workaround the bug
-- OPEN_BEFORE_CLOSE: the normal behaviour when the VPN configuration changed
-
-For example the UI could respond with
-needok 'PERSIST_TUN_ACTION' OPEN_AFTER_CLOSE
-
-To protect a socket the OpenVPN will send a PROTECTFD to the UI.
-When sending the PROTECTFD command command to the UI it will send
-the fd of the socket as ancillary message over the UNIX socket.
-The UI will then call protect(fd) on the received socket protecting
-it from being routed over the VPN.
-
-When opening a tun device the OpenVPN process will first send all
-route, ifconfig and DNS related configuration to the UI and after
-that calls the OPENTUN command to receive a tun fd with the requested
-configuration. The UI will than use the collected information to
-call the VPNService's establish() method to receive a fd which in
-turn is send to the OpenVPN process as ancillary message to the
-"needok 'OPENTUN' ok' response.
-
-The OpenVPN for Android UI extensively uses other features that
-are not specific to Android but are rarely used on other platform.
-For example using SIGUSR1 and management-hold to restart, pause,
-continue the VPN on network changes or the external key management
---management-external-key option and inline files.
-
-To better support handover between networks, a the management command
-
-network-change [samenetwork]
-
-is used on the Android platform. It tells OpenVPN to do the necessary
-action when the network changes. Currently this is just calling
-the protect callback when using peer-id regardless of the samenetwork.
-Without peer-id OpenVPN will generate USR1 when samenetwork is not set.
diff --git a/doc/doxygen/Makefile.in b/doc/doxygen/Makefile.in
new file mode 100644
index 0000000..b1f3786
--- /dev/null
+++ b/doc/doxygen/Makefile.in
@@ -0,0 +1,532 @@
+# Makefile.in generated by automake 1.16.1 from Makefile.am.
+# @configure_input@
+
+# Copyright (C) 1994-2018 Free Software Foundation, Inc.
+
+# This Makefile.in is free software; the Free Software Foundation
+# gives unlimited permission to copy and/or distribute it,
+# with or without modifications, as long as this notice is preserved.
+
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY, to the extent permitted by law; without
+# even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+# PARTICULAR PURPOSE.
+
+@SET_MAKE@
+
+#
+# OpenVPN -- An application to securely tunnel IP networks
+# over a single UDP port, with support for SSL/TLS-based
+# session authentication and key exchange,
+# packet encryption, packet authentication, and
+# packet compression.
+#
+# Copyright (C) 2017-2018 Fox-IT B.V. <openvpn@fox-it.com>
+#
+VPATH = @srcdir@
+am__is_gnu_make = { \
+ if test -z '$(MAKELEVEL)'; then \
+ false; \
+ elif test -n '$(MAKE_HOST)'; then \
+ true; \
+ elif test -n '$(MAKE_VERSION)' && test -n '$(CURDIR)'; then \
+ true; \
+ else \
+ false; \
+ fi; \
+}
+am__make_running_with_option = \
+ case $${target_option-} in \
+ ?) ;; \
+ *) echo "am__make_running_with_option: internal error: invalid" \
+ "target option '$${target_option-}' specified" >&2; \
+ exit 1;; \
+ esac; \
+ has_opt=no; \
+ sane_makeflags=$$MAKEFLAGS; \
+ if $(am__is_gnu_make); then \
+ sane_makeflags=$$MFLAGS; \
+ else \
+ case $$MAKEFLAGS in \
+ *\\[\ \ ]*) \
+ bs=\\; \
+ sane_makeflags=`printf '%s\n' "$$MAKEFLAGS" \
+ | sed "s/$$bs$$bs[$$bs $$bs ]*//g"`;; \
+ esac; \
+ fi; \
+ skip_next=no; \
+ strip_trailopt () \
+ { \
+ flg=`printf '%s\n' "$$flg" | sed "s/$$1.*$$//"`; \
+ }; \
+ for flg in $$sane_makeflags; do \
+ test $$skip_next = yes && { skip_next=no; continue; }; \
+ case $$flg in \
+ *=*|--*) continue;; \
+ -*I) strip_trailopt 'I'; skip_next=yes;; \
+ -*I?*) strip_trailopt 'I';; \
+ -*O) strip_trailopt 'O'; skip_next=yes;; \
+ -*O?*) strip_trailopt 'O';; \
+ -*l) strip_trailopt 'l'; skip_next=yes;; \
+ -*l?*) strip_trailopt 'l';; \
+ -[dEDm]) skip_next=yes;; \
+ -[JT]) skip_next=yes;; \
+ esac; \
+ case $$flg in \
+ *$$target_option*) has_opt=yes; break;; \
+ esac; \
+ done; \
+ test $$has_opt = yes
+am__make_dryrun = (target_option=n; $(am__make_running_with_option))
+am__make_keepgoing = (target_option=k; $(am__make_running_with_option))
+pkgdatadir = $(datadir)/@PACKAGE@
+pkgincludedir = $(includedir)/@PACKAGE@
+pkglibdir = $(libdir)/@PACKAGE@
+pkglibexecdir = $(libexecdir)/@PACKAGE@
+am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd
+install_sh_DATA = $(install_sh) -c -m 644
+install_sh_PROGRAM = $(install_sh) -c
+install_sh_SCRIPT = $(install_sh) -c
+INSTALL_HEADER = $(INSTALL_DATA)
+transform = $(program_transform_name)
+NORMAL_INSTALL = :
+PRE_INSTALL = :
+POST_INSTALL = :
+NORMAL_UNINSTALL = :
+PRE_UNINSTALL = :
+POST_UNINSTALL = :
+build_triplet = @build@
+host_triplet = @host@
+subdir = doc/doxygen
+ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
+am__aclocal_m4_deps = $(top_srcdir)/m4/ax_emptyarray.m4 \
+ $(top_srcdir)/m4/ax_socklen_t.m4 \
+ $(top_srcdir)/m4/ax_varargs.m4 $(top_srcdir)/m4/libtool.m4 \
+ $(top_srcdir)/m4/ltoptions.m4 $(top_srcdir)/m4/ltsugar.m4 \
+ $(top_srcdir)/m4/ltversion.m4 $(top_srcdir)/m4/lt~obsolete.m4 \
+ $(top_srcdir)/m4/pkg.m4 $(top_srcdir)/version.m4 \
+ $(top_srcdir)/compat.m4 $(top_srcdir)/configure.ac
+am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \
+ $(ACLOCAL_M4)
+DIST_COMMON = $(srcdir)/Makefile.am $(am__DIST_COMMON)
+mkinstalldirs = $(install_sh) -d
+CONFIG_HEADER = $(top_builddir)/config.h \
+ $(top_builddir)/include/openvpn-plugin.h
+CONFIG_CLEAN_FILES = openvpn.doxyfile
+CONFIG_CLEAN_VPATH_FILES =
+AM_V_P = $(am__v_P_@AM_V@)
+am__v_P_ = $(am__v_P_@AM_DEFAULT_V@)
+am__v_P_0 = false
+am__v_P_1 = :
+AM_V_GEN = $(am__v_GEN_@AM_V@)
+am__v_GEN_ = $(am__v_GEN_@AM_DEFAULT_V@)
+am__v_GEN_0 = @echo " GEN " $@;
+am__v_GEN_1 =
+AM_V_at = $(am__v_at_@AM_V@)
+am__v_at_ = $(am__v_at_@AM_DEFAULT_V@)
+am__v_at_0 = @
+am__v_at_1 =
+SOURCES =
+DIST_SOURCES =
+am__can_run_installinfo = \
+ case $$AM_UPDATE_INFO_DIR in \
+ n|no|NO) false;; \
+ *) (install-info --version) >/dev/null 2>&1;; \
+ esac
+am__tagged_files = $(HEADERS) $(SOURCES) $(TAGS_FILES) $(LISP)
+am__DIST_COMMON = $(srcdir)/Makefile.in $(srcdir)/openvpn.doxyfile.in
+DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST)
+ACLOCAL = @ACLOCAL@
+AMTAR = @AMTAR@
+AM_DEFAULT_VERBOSITY = @AM_DEFAULT_VERBOSITY@
+AR = @AR@
+AS = @AS@
+AUTOCONF = @AUTOCONF@
+AUTOHEADER = @AUTOHEADER@
+AUTOMAKE = @AUTOMAKE@
+AWK = @AWK@
+CC = @CC@
+CCDEPMODE = @CCDEPMODE@
+CFLAGS = @CFLAGS@
+CMOCKA_CFLAGS = @CMOCKA_CFLAGS@
+CMOCKA_LIBS = @CMOCKA_LIBS@
+CPP = @CPP@
+CPPFLAGS = @CPPFLAGS@
+CYGPATH_W = @CYGPATH_W@
+DEFS = @DEFS@
+DEPDIR = @DEPDIR@
+DLLTOOL = @DLLTOOL@
+DL_LIBS = @DL_LIBS@
+DSYMUTIL = @DSYMUTIL@
+DUMPBIN = @DUMPBIN@
+ECHO_C = @ECHO_C@
+ECHO_N = @ECHO_N@
+ECHO_T = @ECHO_T@
+EGREP = @EGREP@
+ENABLE_UNITTESTS = @ENABLE_UNITTESTS@
+EXEEXT = @EXEEXT@
+FGREP = @FGREP@
+GIT = @GIT@
+GREP = @GREP@
+IFCONFIG = @IFCONFIG@
+INSTALL = @INSTALL@
+INSTALL_DATA = @INSTALL_DATA@
+INSTALL_PROGRAM = @INSTALL_PROGRAM@
+INSTALL_SCRIPT = @INSTALL_SCRIPT@
+INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@
+IPROUTE = @IPROUTE@
+LD = @LD@
+LDFLAGS = @LDFLAGS@
+LIBOBJS = @LIBOBJS@
+LIBPAM_CFLAGS = @LIBPAM_CFLAGS@
+LIBPAM_LIBS = @LIBPAM_LIBS@
+LIBS = @LIBS@
+LIBTOOL = @LIBTOOL@
+LIPO = @LIPO@
+LN_S = @LN_S@
+LTLIBOBJS = @LTLIBOBJS@
+LT_SYS_LIBRARY_PATH = @LT_SYS_LIBRARY_PATH@
+LZ4_CFLAGS = @LZ4_CFLAGS@
+LZ4_LIBS = @LZ4_LIBS@
+LZO_CFLAGS = @LZO_CFLAGS@
+LZO_LIBS = @LZO_LIBS@
+MAKEINFO = @MAKEINFO@
+MANIFEST_TOOL = @MANIFEST_TOOL@
+MBEDTLS_CFLAGS = @MBEDTLS_CFLAGS@
+MBEDTLS_LIBS = @MBEDTLS_LIBS@
+MKDIR_P = @MKDIR_P@
+NETSTAT = @NETSTAT@
+NM = @NM@
+NMEDIT = @NMEDIT@
+OBJDUMP = @OBJDUMP@
+OBJEXT = @OBJEXT@
+OPENSSL_CFLAGS = @OPENSSL_CFLAGS@
+OPENSSL_LIBS = @OPENSSL_LIBS@
+OPENVPN_VERSION_MAJOR = @OPENVPN_VERSION_MAJOR@
+OPENVPN_VERSION_MINOR = @OPENVPN_VERSION_MINOR@
+OPENVPN_VERSION_PATCH = @OPENVPN_VERSION_PATCH@
+OPTIONAL_CRYPTO_CFLAGS = @OPTIONAL_CRYPTO_CFLAGS@
+OPTIONAL_CRYPTO_LIBS = @OPTIONAL_CRYPTO_LIBS@
+OPTIONAL_DL_LIBS = @OPTIONAL_DL_LIBS@
+OPTIONAL_INOTIFY_CFLAGS = @OPTIONAL_INOTIFY_CFLAGS@
+OPTIONAL_INOTIFY_LIBS = @OPTIONAL_INOTIFY_LIBS@
+OPTIONAL_LZ4_CFLAGS = @OPTIONAL_LZ4_CFLAGS@
+OPTIONAL_LZ4_LIBS = @OPTIONAL_LZ4_LIBS@
+OPTIONAL_LZO_CFLAGS = @OPTIONAL_LZO_CFLAGS@
+OPTIONAL_LZO_LIBS = @OPTIONAL_LZO_LIBS@
+OPTIONAL_PKCS11_HELPER_CFLAGS = @OPTIONAL_PKCS11_HELPER_CFLAGS@
+OPTIONAL_PKCS11_HELPER_LIBS = @OPTIONAL_PKCS11_HELPER_LIBS@
+OPTIONAL_SELINUX_LIBS = @OPTIONAL_SELINUX_LIBS@
+OPTIONAL_SYSTEMD_LIBS = @OPTIONAL_SYSTEMD_LIBS@
+OTOOL = @OTOOL@
+OTOOL64 = @OTOOL64@
+P11KIT_CFLAGS = @P11KIT_CFLAGS@
+P11KIT_LIBS = @P11KIT_LIBS@
+PACKAGE = @PACKAGE@
+PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@
+PACKAGE_NAME = @PACKAGE_NAME@
+PACKAGE_STRING = @PACKAGE_STRING@
+PACKAGE_TARNAME = @PACKAGE_TARNAME@
+PACKAGE_URL = @PACKAGE_URL@
+PACKAGE_VERSION = @PACKAGE_VERSION@
+PATH_SEPARATOR = @PATH_SEPARATOR@
+PKCS11_HELPER_CFLAGS = @PKCS11_HELPER_CFLAGS@
+PKCS11_HELPER_LIBS = @PKCS11_HELPER_LIBS@
+PKG_CONFIG = @PKG_CONFIG@
+PKG_CONFIG_LIBDIR = @PKG_CONFIG_LIBDIR@
+PKG_CONFIG_PATH = @PKG_CONFIG_PATH@
+PLUGINDIR = @PLUGINDIR@
+PLUGIN_AUTH_PAM_CFLAGS = @PLUGIN_AUTH_PAM_CFLAGS@
+PLUGIN_AUTH_PAM_LIBS = @PLUGIN_AUTH_PAM_LIBS@
+RANLIB = @RANLIB@
+RC = @RC@
+ROUTE = @ROUTE@
+RST2HTML = @RST2HTML@
+RST2MAN = @RST2MAN@
+SED = @SED@
+SELINUX_LIBS = @SELINUX_LIBS@
+SET_MAKE = @SET_MAKE@
+SHELL = @SHELL@
+SOCKETS_LIBS = @SOCKETS_LIBS@
+STRIP = @STRIP@
+SYSTEMD_ASK_PASSWORD = @SYSTEMD_ASK_PASSWORD@
+SYSTEMD_UNIT_DIR = @SYSTEMD_UNIT_DIR@
+TAP_CFLAGS = @TAP_CFLAGS@
+TAP_WIN_COMPONENT_ID = @TAP_WIN_COMPONENT_ID@
+TAP_WIN_MIN_MAJOR = @TAP_WIN_MIN_MAJOR@
+TAP_WIN_MIN_MINOR = @TAP_WIN_MIN_MINOR@
+TEST_CFLAGS = @TEST_CFLAGS@
+TEST_LDFLAGS = @TEST_LDFLAGS@
+TMPFILES_DIR = @TMPFILES_DIR@
+VERSION = @VERSION@
+abs_builddir = @abs_builddir@
+abs_srcdir = @abs_srcdir@
+abs_top_builddir = @abs_top_builddir@
+abs_top_srcdir = @abs_top_srcdir@
+ac_ct_AR = @ac_ct_AR@
+ac_ct_CC = @ac_ct_CC@
+ac_ct_DUMPBIN = @ac_ct_DUMPBIN@
+am__include = @am__include@
+am__leading_dot = @am__leading_dot@
+am__quote = @am__quote@
+am__tar = @am__tar@
+am__untar = @am__untar@
+bindir = @bindir@
+build = @build@
+build_alias = @build_alias@
+build_cpu = @build_cpu@
+build_os = @build_os@
+build_vendor = @build_vendor@
+builddir = @builddir@
+datadir = @datadir@
+datarootdir = @datarootdir@
+docdir = @docdir@
+dvidir = @dvidir@
+exec_prefix = @exec_prefix@
+host = @host@
+host_alias = @host_alias@
+host_cpu = @host_cpu@
+host_os = @host_os@
+host_vendor = @host_vendor@
+htmldir = @htmldir@
+includedir = @includedir@
+infodir = @infodir@
+install_sh = @install_sh@
+libdir = @libdir@
+libexecdir = @libexecdir@
+libsystemd_CFLAGS = @libsystemd_CFLAGS@
+libsystemd_LIBS = @libsystemd_LIBS@
+localedir = @localedir@
+localstatedir = @localstatedir@
+mandir = @mandir@
+mkdir_p = @mkdir_p@
+oldincludedir = @oldincludedir@
+pdfdir = @pdfdir@
+plugindir = @plugindir@
+prefix = @prefix@
+program_transform_name = @program_transform_name@
+psdir = @psdir@
+sampledir = @sampledir@
+sbindir = @sbindir@
+sharedstatedir = @sharedstatedir@
+srcdir = @srcdir@
+sysconfdir = @sysconfdir@
+systemdunitdir = @systemdunitdir@
+target_alias = @target_alias@
+tmpfilesdir = @tmpfilesdir@
+top_build_prefix = @top_build_prefix@
+top_builddir = @top_builddir@
+top_srcdir = @top_srcdir@
+MAINTAINERCLEANFILES = \
+ $(srcdir)/Makefile.in
+
+DISTCLEANFILES = openvpn.doxyfile
+all: all-am
+
+.SUFFIXES:
+$(srcdir)/Makefile.in: $(srcdir)/Makefile.am $(am__configure_deps)
+ @for dep in $?; do \
+ case '$(am__configure_deps)' in \
+ *$$dep*) \
+ ( cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh ) \
+ && { if test -f $@; then exit 0; else break; fi; }; \
+ exit 1;; \
+ esac; \
+ done; \
+ echo ' cd $(top_srcdir) && $(AUTOMAKE) --foreign doc/doxygen/Makefile'; \
+ $(am__cd) $(top_srcdir) && \
+ $(AUTOMAKE) --foreign doc/doxygen/Makefile
+Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status
+ @case '$?' in \
+ *config.status*) \
+ cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh;; \
+ *) \
+ echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__maybe_remake_depfiles)'; \
+ cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__maybe_remake_depfiles);; \
+ esac;
+
+$(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES)
+ cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
+
+$(top_srcdir)/configure: $(am__configure_deps)
+ cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
+$(ACLOCAL_M4): $(am__aclocal_m4_deps)
+ cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
+$(am__aclocal_m4_deps):
+openvpn.doxyfile: $(top_builddir)/config.status $(srcdir)/openvpn.doxyfile.in
+ cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@
+
+mostlyclean-libtool:
+ -rm -f *.lo
+
+clean-libtool:
+ -rm -rf .libs _libs
+tags TAGS:
+
+ctags CTAGS:
+
+cscope cscopelist:
+
+
+distdir: $(BUILT_SOURCES)
+ $(MAKE) $(AM_MAKEFLAGS) distdir-am
+
+distdir-am: $(DISTFILES)
+ @srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \
+ topsrcdirstrip=`echo "$(top_srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \
+ list='$(DISTFILES)'; \
+ dist_files=`for file in $$list; do echo $$file; done | \
+ sed -e "s|^$$srcdirstrip/||;t" \
+ -e "s|^$$topsrcdirstrip/|$(top_builddir)/|;t"`; \
+ case $$dist_files in \
+ */*) $(MKDIR_P) `echo "$$dist_files" | \
+ sed '/\//!d;s|^|$(distdir)/|;s,/[^/]*$$,,' | \
+ sort -u` ;; \
+ esac; \
+ for file in $$dist_files; do \
+ if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \
+ if test -d $$d/$$file; then \
+ dir=`echo "/$$file" | sed -e 's,/[^/]*$$,,'`; \
+ if test -d "$(distdir)/$$file"; then \
+ find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \
+ fi; \
+ if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \
+ cp -fpR $(srcdir)/$$file "$(distdir)$$dir" || exit 1; \
+ find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \
+ fi; \
+ cp -fpR $$d/$$file "$(distdir)$$dir" || exit 1; \
+ else \
+ test -f "$(distdir)/$$file" \
+ || cp -p $$d/$$file "$(distdir)/$$file" \
+ || exit 1; \
+ fi; \
+ done
+check-am: all-am
+check: check-am
+all-am: Makefile
+installdirs:
+install: install-am
+install-exec: install-exec-am
+install-data: install-data-am
+uninstall: uninstall-am
+
+install-am: all-am
+ @$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am
+
+installcheck: installcheck-am
+install-strip:
+ if test -z '$(STRIP)'; then \
+ $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \
+ install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \
+ install; \
+ else \
+ $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \
+ install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \
+ "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'" install; \
+ fi
+mostlyclean-generic:
+
+clean-generic:
+
+distclean-generic:
+ -test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES)
+ -test . = "$(srcdir)" || test -z "$(CONFIG_CLEAN_VPATH_FILES)" || rm -f $(CONFIG_CLEAN_VPATH_FILES)
+ -test -z "$(DISTCLEANFILES)" || rm -f $(DISTCLEANFILES)
+
+maintainer-clean-generic:
+ @echo "This command is intended for maintainers to use"
+ @echo "it deletes files that may require special tools to rebuild."
+ -test -z "$(MAINTAINERCLEANFILES)" || rm -f $(MAINTAINERCLEANFILES)
+clean: clean-am
+
+clean-am: clean-generic clean-libtool clean-local mostlyclean-am
+
+distclean: distclean-am
+ -rm -f Makefile
+distclean-am: clean-am distclean-generic
+
+dvi: dvi-am
+
+dvi-am:
+
+html: html-am
+
+html-am:
+
+info: info-am
+
+info-am:
+
+install-data-am:
+
+install-dvi: install-dvi-am
+
+install-dvi-am:
+
+install-exec-am:
+
+install-html: install-html-am
+
+install-html-am:
+
+install-info: install-info-am
+
+install-info-am:
+
+install-man:
+
+install-pdf: install-pdf-am
+
+install-pdf-am:
+
+install-ps: install-ps-am
+
+install-ps-am:
+
+installcheck-am:
+
+maintainer-clean: maintainer-clean-am
+ -rm -f Makefile
+maintainer-clean-am: distclean-am maintainer-clean-generic
+
+mostlyclean: mostlyclean-am
+
+mostlyclean-am: mostlyclean-generic mostlyclean-libtool
+
+pdf: pdf-am
+
+pdf-am:
+
+ps: ps-am
+
+ps-am:
+
+uninstall-am:
+
+.MAKE: install-am install-strip
+
+.PHONY: all all-am check check-am clean clean-generic clean-libtool \
+ clean-local cscopelist-am ctags-am distclean distclean-generic \
+ distclean-libtool distdir dvi dvi-am html html-am info info-am \
+ install install-am install-data install-data-am install-dvi \
+ install-dvi-am install-exec install-exec-am install-html \
+ install-html-am install-info install-info-am install-man \
+ install-pdf install-pdf-am install-ps install-ps-am \
+ install-strip installcheck installcheck-am installdirs \
+ maintainer-clean maintainer-clean-generic mostlyclean \
+ mostlyclean-generic mostlyclean-libtool pdf pdf-am ps ps-am \
+ tags-am uninstall uninstall-am
+
+.PRECIOUS: Makefile
+
+
+.PHONY: doxygen
+doxygen: openvpn.doxyfile
+ doxygen openvpn.doxyfile
+
+clean-local:
+ -rm -rf html latex
+
+# 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.
+.NOEXPORT:
diff --git a/doc/doxygen/doc_compression.h b/doc/doxygen/doc_compression.h
deleted file mode 100644
index 3176bad..0000000
--- a/doc/doxygen/doc_compression.h
+++ /dev/null
@@ -1,91 +0,0 @@
-/*
- * OpenVPN -- An application to securely tunnel IP networks
- * over a single TCP/UDP port, with support for SSL/TLS-based
- * session authentication and key exchange,
- * packet encryption, packet authentication, and
- * packet compression.
- *
- * Copyright (C) 2010-2018 Fox Crypto B.V. <openvpn@fox-it.com>
- *
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License version 2
- * as published by the Free Software Foundation.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License along
- * with this program; if not, write to the Free Software Foundation, Inc.,
- * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
- */
-
-/**
- * @file Data Channel Compression module documentation file.
- */
-
-/**
- * @defgroup compression Data Channel Compression module
- *
- * This module offers compression of data channel packets.
- *
- * @par State structures
- * The Data Channel Compression module stores its internal state in a \c
- * lzo_compress_workspace structure. This state includes flags which
- * control the module's behavior and preallocated working memory. One
- * such structure is present for each VPN tunnel, and is stored in the \c
- * context.c2.lzo_compwork of the \c context associated with that VPN
- * tunnel.
- *
- * @par Initialization and cleanup
- * Every time a new \c lzo_compress_workspace is needed, it must be
- * initialized using the \c lzo_compress_init() function. Similarly,
- * every time a \c lzo_compress_workspace is no longer needed, it must be
- * cleaned up using the \c lzo_compress_uninit() function. These
- * functions take care of the allocation and freeing of internal working
- * memory, but not of the \c lzo_compress_workspace structures themselves.
- *
- * @par
- * Because of the one-to-one relationship between \c
- * lzo_compress_workspace structures and VPN tunnels, the above-mentioned
- * initialization and cleanup functions are called directly from the \c
- * init_instance() and \c close_instance() functions, which control the
- * initialization and cleanup of VPN tunnel instances and their associated
- * \c context structures.
- *
- * @par Packet processing functions
- * This module receives data channel packets from the \link data_control
- * Data Channel Control module\endlink and processes them according to the
- * settings of the packet's VPN tunnel. The \link data_control Data
- * Channel Control module\endlink uses the following interface functions:
- * - For packets which will be sent to a remote OpenVPN peer: \c
- * lzo_compress()
- * - For packets which have been received from a remote OpenVPN peer: \c
- * lzo_decompress()
- *
- * @par Settings that control this module's activity
- * Whether or not the Data Channel Compression module is active depends on
- * the compile-time \c ENABLE_LZO preprocessor macro and the runtime flags
- * stored in \c lzo_compress_workspace.flags of the associated VPN tunnel.
- * The latter are initialized from \c options.lzo, which gets its value
- * from the process's configuration sources, such as its configuration
- * file or command line %options.
- *
- * @par Adaptive compression
- * The compression module supports adaptive compression. If this feature
- * is enabled, the compression routines monitor their own performance and
- * turn compression on or off depending on whether it is leading to
- * significantly reduced payload size.
- *
- * @par Compression algorithms
- * This module uses the Lempel-Ziv-Oberhumer (LZO) compression algorithms.
- * These offer lossless compression and are designed for high-performance
- * decompression. This module uses the external \c lzo library's
- * implementation of the algorithms.
- *
- * @par
- * For more information on the LZO library, see:\n
- * http://www.oberhumer.com/opensource/lzo/
- */
diff --git a/doc/doxygen/doc_control_processor.h b/doc/doxygen/doc_control_processor.h
deleted file mode 100644
index 1bbf2d2..0000000
--- a/doc/doxygen/doc_control_processor.h
+++ /dev/null
@@ -1,184 +0,0 @@
-/*
- * OpenVPN -- An application to securely tunnel IP networks
- * over a single TCP/UDP port, with support for SSL/TLS-based
- * session authentication and key exchange,
- * packet encryption, packet authentication, and
- * packet compression.
- *
- * Copyright (C) 2010-2018 Fox Crypto B.V. <openvpn@fox-it.com>
- *
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License version 2
- * as published by the Free Software Foundation.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License along
- * with this program; if not, write to the Free Software Foundation, Inc.,
- * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
- */
-
-/**
- * @file
- * Control Channel Processor module documentation file.
- */
-
-/**
- * @defgroup control_processor Control Channel Processor module
- *
- * This module controls the setup and maintenance of VPN tunnels and the
- * associated security parameters.
- *
- * @par This module's role
- * The Control Channel Processor module lies at the core of OpenVPN's
- * activities. It handles the setup of new VPN tunnels, the negotiation
- * of data channel security parameters, the managing of active VPN
- * tunnels, and finally the cleanup of expired VPN tunnels.
- *
- * @par State structures
- * A large amount of VPN tunnel state information must be stored within an
- * OpenVPN process. A wide variety of container structures are used by
- * this module for that purpose. Several of these structures are listed
- * below, and the function of the first three VPN tunnel state containers
- * is described in more detail later.
- * - VPN tunnel state containers:
- * - \c tls_multi, security parameter state for a single VPN tunnel.
- * Contains three instances of the \c tls_session structure.
- * - \c tls_session, security parameter state of a single session
- * within a VPN tunnel. Contains two instances of the \c key_state
- * structure.
- * - \c key_state, security parameter state of one TLS and data
- * channel %key set.
- * - Data channel security parameter containers:
- * - \c key_ctx_bi, container for two sets of OpenSSL cipher and/or
- * HMAC context (both directions). Contains two instances of the \c
- * key_ctx structure.
- * - \c key_ctx, container for one set of OpenSSL cipher and/or HMAC
- * context (one directions.
- * - Key material containers:
- * - \c key2, container for two sets of cipher and/or HMAC %key
- * material (both directions). Contains two instances of the \c key
- * structure.
- * - \c key, container for one set of cipher and/or HMAC %key material
- * (one direction).
- * - \c key_direction_state, ordering of %key material within the \c
- * key2.key array.
- * - Key method 2 random material containers:
- * - \c key_source2, container for both halves of random material used
- * for %key method 2. Contains two instances of the \c key_source
- * structure.
- * - \c key_source, container for one half of random material used for
- * %key method 2.
- *
- * @par The life of a \c tls_multi object
- * A \c tls_multi structure contains all the security parameter state
- * information related to the control and data channels of one VPN tunnel.
- * Its life cycle can be summarized as follows:
- * -# Initialization: \c tls_multi_init() and \c
- * tls_multi_init_finalize(), which are called (indirectly) from \c
- * init_instance() when initializing a new \c context structure.
- * - Initializes a \c tls_multi structure.
- * - Allocates the three \c tls_session objects contained by the \c
- * tls_multi structure, and initializes as appropriate.
- * -# Management: \c tls_multi_process() and \c tls_pre_decrypt()
- * - If a new session is initiated by the remote peer, then \c
- * tls_pre_decrypt() starts the new session negotiation in the
- * un-trusted \c tls_session.
- * - If the, as yet, un-trusted \c tls_session authenticates
- * successfully, then \c tls_multi_process() moves it so as to be
- * the active \c tls_session.
- * - If an error occurs during processing of a \c key_state object,
- * then \c tls_multi_process() cleans up and initializes the
- * associated \c tls_session object. If the error occurred in the
- * active \c key_state of the active \c tls_session and the
- * lame-duck \c key_state of that \c tls_session has not yet
- * expired, it is preserved as fallback.
- * -# Cleanup: \c tls_multi_free(), which is called (indirectly) from \c
- * close_instance() when cleaning up a \c context structure.
- * - Cleans up a \c tls_multi structure.
- * - Cleans up the three \c tls_session objects contained by the \c
- * tls_multi structure.
- *
- * @par The life of a \c tls_session object
- * A \c tls_session structure contains the state information related to an
- * active and a lame-duck \c key_state. Its life cycle can be summarized
- * as follows:
- * -# Initialization: \c tls_session_init()
- * - Initializes a \c tls_session structure.
- * - Initializes the primary \c key_state by calling \c
- * key_state_init().
- * -# Renegotiation: \c key_state_soft_reset()
- * - Cleans up the old lame-duck \c key_state by calling \c
- * key_state_free().
- * - Moves the old primary \c key_state to be the new lame-duck \c
- * key_state.
- * - Initializes a new primary \c key_state by calling \c
- * key_state_init().
- * -# Cleanup: \c tls_session_free()
- * - Cleans up a \c tls_session structure.
- * - Cleans up all \c key_state objects associated with the session by
- * calling \c key_state_free() for each.
- *
- * @par The life of a \c key_state object
- * A \c key_state structure represents one control and data channel %key
- * set. It contains an OpenSSL TLS object that encapsulates the control
- * channel, and the data channel security parameters needed by the \link
- * data_crypto Data Channel Crypto module\endlink to perform cryptographic
- * operations on data channel packets. Its life cycle can be summarized
- * as follows:
- * -# Initialization: \c key_state_init()
- * - Initializes a \c key_state structure.
- * - Creates a new OpenSSL TLS object to encapsulate this new control
- * channel session.
- * - Sets \c key_state.state to \c S_INITIAL.
- * - Allocates several internal buffers.
- * - Initializes new reliability layer structures for this key set.
- * -# Negotiation: \c tls_process()
- * - The OpenSSL TLS object negotiates a TLS session between itself
- * and the remote peer's TLS object.
- * - Key material is generated and exchanged through the TLS session
- * between OpenVPN peers.
- * - Both peers initialize their data channel cipher and HMAC key
- * contexts.
- * - On successful negotiation, the \c key_state.state will progress
- * from \c S_INITIAL to \c S_ACTIVE and \c S_NORMAL.
- * -# Active tunneling: \link data_crypto Data Channel Crypto
- * module\endlink
- * - Data channel packet to be sent to a remote OpenVPN peer:
- * - \c tls_pre_encrypt() loads the security parameters from the \c
- * key_state into a \c crypto_options structure.
- * - \c openvpn_encrypt() uses the \c crypto_options to an encrypt
- * and HMAC sign the data channel packet.
- * - Data channel packet received from a remote OpenVPN peer:
- * - \c tls_pre_decrypt() loads the security parameters from the \c
- * key_state into a \c crypto_options structure.
- * - \c openvpn_encrypt() uses the \c crypto_options to
- * authenticate and decrypt the data channel packet.
- * -# Cleanup: \c key_state_free()
- * - Cleans up a \c key_state structure together with its OpenSSL TLS
- * object, key material, internal buffers, and reliability layer
- * structures.
- *
- * @par Control functions
- * The following two functions drive the Control Channel Processor's
- * activities.
- * - \c tls_multi_process(), iterates through the \c tls_session objects
- * within a given \c tls_multi of a VPN tunnel, and calls \c
- * tls_process() for each \c tls_session which is being set up, is
- * already active, or is busy expiring.
- * - \c tls_process(), performs the Control Channel Processor module's
- * core handling of received control channel messages, and generates
- * appropriate messages to be sent.
- *
- * @par Functions which control data channel key generation
- * - Key method 1 key exchange functions were removed from OpenVPN 2.5
- * - Key method 2 key exchange functions:
- * - \c key_method_2_write(), generates and processes key material to
- * be sent to the remote OpenVPN peer.
- * - \c key_method_2_read(), processes key material received from the
- * remote OpenVPN peer.
- */
diff --git a/doc/doxygen/doc_control_tls.h b/doc/doxygen/doc_control_tls.h
deleted file mode 100644
index 5cb7c53..0000000
--- a/doc/doxygen/doc_control_tls.h
+++ /dev/null
@@ -1,104 +0,0 @@
-/*
- * OpenVPN -- An application to securely tunnel IP networks
- * over a single TCP/UDP port, with support for SSL/TLS-based
- * session authentication and key exchange,
- * packet encryption, packet authentication, and
- * packet compression.
- *
- * Copyright (C) 2010-2018 Fox Crypto B.V. <openvpn@fox-it.com>
- *
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License version 2
- * as published by the Free Software Foundation.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License along
- * with this program; if not, write to the Free Software Foundation, Inc.,
- * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
- */
-
-/**
- * @file
- * Control Channel TLS module documentation file.
- */
-
-/**
- * @defgroup control_tls Control Channel TLS module
- *
- * This module provides secure encapsulation of control channel messages
- * exchanged between OpenVPN peers.
- *
- * The Control Channel TLS module uses the Transport Layer Security (TLS)
- * protocol to provide an encrypted communication channel between the
- * local OpenVPN process and a remote peer. This protocol simultaneously
- * offers certificate-based authentication of the communicating parties.
- *
- * @par This module's roles
- * The Control Channel TLS module is essential for the security of any
- * OpenVPN-based system. On the one hand, it performs the security
- * operations necessary to protect control channel messages exchanged
- * between OpenVPN peers. On the other hand, before the control and data
- * channels are even setup, it controls the exchange of certificates and
- * verification of the remote's identity during negotiation of VPN
- * tunnels.
- *
- * @par
- * The former role is described below. The latter is described in the
- * documentation for the \c verify_callback() function.
- *
- * @par
- * In other words, this module takes care of the confidentiality and
- * integrity of data channel communications, and the authentication of
- * both the communicating parties and the control channel messages
- * exchanged.
- *
- * @par Initialization and cleanup
- * Because of the one-to-one relationship between control channel TLS
- * state and \c key_state structures, the initialization and cleanup of an
- * instance of the Control Channel TLS module's state happens within the
- * \c key_state_init() and \c key_state_free() functions. In other words,
- * each \c key_state object contains exactly one OpenSSL SSL-BIO object,
- * which is initialized and cleaned up together with the rest of the \c
- * key_state object.
- *
- * @par Packet processing functions
- * This object behaves somewhat like a black box with a ciphertext and a
- * plaintext I/O port. Its interaction with OpenVPN's control channel
- * during operation takes place within the \c tls_process() function of
- * the \link control_processor Control Channel Processor\endlink. The
- * following functions are available for processing packets:
- * - If ciphertext received from the remote peer is available in the \link
- * reliable Reliability Layer\endlink:
- * - Insert it into the ciphertext-side of the SSL-BIO.
- * - Use function: \c key_state_write_ciphertext()
- * - If ciphertext can be extracted from the ciphertext-side of the
- * SSL-BIO:
- * - Pass it to the \link reliable Reliability Layer\endlink for sending
- * to the remote peer.
- * - Use function: \c key_state_read_ciphertext()
- * - If plaintext can be extracted from the plaintext-side of the SSL-BIO:
- * - Pass it on to the \link control_processor Control Channel
- * Processor\endlink for local processing.
- * - Use function: \c key_state_read_plaintext()
- * - If plaintext from the \link control_processor Control Channel
- * Processor\endlink is available to be sent to the remote peer:
- * - Insert it into the plaintext-side of the SSL-BIO.
- * - Use function: \c key_state_write_plaintext() or \c
- * key_state_write_plaintext_const()
- *
- * @par Transport Layer Security protocol implementation
- * This module uses the OpenSSL library's implementation of the TLS
- * protocol in the form of an OpenSSL SSL-BIO object.
- *
- * @par
- * For more information on the OpenSSL library's BIO objects, please see:
- * - OpenSSL's generic BIO objects:
- * http://www.openssl.org/docs/crypto/bio.html
- * - OpenSSL's SSL-BIO object:
- * http://www.openssl.org/docs/crypto/BIO_f_ssl.html
- */
diff --git a/doc/doxygen/doc_data_control.h b/doc/doxygen/doc_data_control.h
deleted file mode 100644
index ad2a308..0000000
--- a/doc/doxygen/doc_data_control.h
+++ /dev/null
@@ -1,102 +0,0 @@
-/*
- * OpenVPN -- An application to securely tunnel IP networks
- * over a single TCP/UDP port, with support for SSL/TLS-based
- * session authentication and key exchange,
- * packet encryption, packet authentication, and
- * packet compression.
- *
- * Copyright (C) 2010-2018 Fox Crypto B.V. <openvpn@fox-it.com>
- *
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License version 2
- * as published by the Free Software Foundation.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License along
- * with this program; if not, write to the Free Software Foundation, Inc.,
- * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
- */
-
-/**
- * @file
- * Data Channel Control module documentation file.
- */
-
-/**
- * @defgroup data_control Data Channel Control module
- *
- * This module controls the processing of packets as they pass through the
- * data channel.
- *
- * The Data Channel Control module controls the processing of packets as
- * they pass through the data channel. The processing includes packet
- * compression, fragmentation, and the performing of security operations
- * on the packets. This module does not do the processing itself, but
- * passes the packet to other data channel modules to perform the
- * appropriate actions.
- *
- * Packets can travel in two directions through the data channel. They
- * can be going to a remote destination which is reachable through a VPN
- * tunnel, in which case this module prepares them to be sent out through
- * a VPN tunnel. On the other hand, they can have been received through a
- * VPN tunnel from a remote OpenVPN peer, in which case this module
- * retrieves the packet in its original form as it was before entering the
- * VPN tunnel on the remote OpenVPN peer. How this module processes
- * packets traveling in the two directions is discussed in more detail
- * below.
- *
- * @par Packets to be sent to a remote OpenVPN peer
- * This module's main function for processing packets traveling in this
- * direction is \c encrypt_sign(), which performs the following processing
- * steps:
- * - Call the \link compression Data Channel Compression module\endlink to
- * perform packet compression if necessary.
- * - Call the \link fragmentation Data Channel Fragmentation
- * module\endlink to perform packet fragmentation if necessary.
- * - Call the \link data_crypto Data Channel Crypto module\endlink to
- * perform the required security operations.
- *
- * @par
- * See the \c encrypt_sign() documentation for details of these
- * interactions.
- *
- * @par
- * After the above processing is complete, the packet is ready to be sent
- * to a remote OpenVPN peer as a VPN tunnel packet. The actual sending of
- * the packet is handled by the \link external_multiplexer External
- * Multiplexer\endlink.
- *
- * @par Packets received from a remote OpenVPN peer
- * The function that controls how packets traveling in this direction are
- * processed is \c process_incoming_link(). That function, however, also
- * performs some of the tasks required for the \link external_multiplexer
- * External Multiplexer\endlink and is therefore listed as part of that
- * module, instead of here.
- *
- * @par
- * After the \c process_incoming_link() function has determined that a
- * received packet is a data channel packet, it performs the following
- * processing steps:
- * - Call the \link data_crypto Data Channel Crypto module\endlink to
- * perform the required security operations.
- * - Call the \link fragmentation Data Channel Fragmentation
- * module\endlink to perform packet reassembly if necessary.
- * - Call the \link compression Data Channel Compression module\endlink to
- * perform packet decompression if necessary.
- *
- * @par
- * See the \c process_incoming_link() documentation for details of these
- * interactions.
- *
- * @par
- * After the above processing is complete, the packet is in its original
- * form again as it was received by the remote OpenVPN peer. It can now
- * be routed further to its final destination. If that destination is a
- * locally reachable host, then the \link internal_multiplexer Internal
- * Multiplexer\endlink will send it there.
- */
diff --git a/doc/doxygen/doc_data_crypto.h b/doc/doxygen/doc_data_crypto.h
deleted file mode 100644
index 3828089..0000000
--- a/doc/doxygen/doc_data_crypto.h
+++ /dev/null
@@ -1,70 +0,0 @@
-/*
- * OpenVPN -- An application to securely tunnel IP networks
- * over a single TCP/UDP port, with support for SSL/TLS-based
- * session authentication and key exchange,
- * packet encryption, packet authentication, and
- * packet compression.
- *
- * Copyright (C) 2010-2018 Fox Crypto B.V. <openvpn@fox-it.com>
- *
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License version 2
- * as published by the Free Software Foundation.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License along
- * with this program; if not, write to the Free Software Foundation, Inc.,
- * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
- */
-
-/**
- * @file
- * Data Channel Crypto module documentation file.
- */
-
-/**
- * @addtogroup data_crypto Data Channel Crypto module
- *
- * The Data Channel Crypto Module performs cryptographic operations on
- * data channel packets.
- *
- * @par Security parameters
- * This module is merely the user of a VPN tunnel's security parameters.
- * It does not perform the negotiation and setup of the security
- * parameters, nor the %key generation involved. These actions are done
- * by the \link control_processor Control Channel Processor\endlink. This
- * module receives the appropriate security parameters from that module in
- * the form of a \c crypto_options structure when they are necessary for
- * processing a packet.
- *
- * @par Packet processing functions
- * This module receives data channel packets from the \link data_control
- * Data Channel Control module\endlink and processes them according to the
- * security parameters of the packet's VPN tunnel. The \link data_control
- * Data Channel Control module\endlink uses the following interface
- * functions:
- * - For packets which will be sent to a remote OpenVPN peer:
- * - \c tls_pre_encrypt()
- * - \c openvpn_encrypt()
- * - \c tls_post_encrypt()
- * - For packets which have been received from a remote OpenVPN peer:
- * - \c tls_pre_decrypt() (documented as part of the \link
- * external_multiplexer External Multiplexer\endlink)
- * - \c openvpn_decrypt()
- *
- * @par Settings that control this module's activity
- * How the data channel processes packets received from the \link data_control
- * Data Channel Control module\endlink at runtime depends on the associated
- * \c crypto_options structure. To perform cryptographic operations, the
- * \c crypto_options.key_ctx_bi must contain the correct cipher and HMAC
- * security parameters for the direction the packet is traveling in.
- *
- * @par Crypto algorithms
- * This module uses the crypto algorithm implementations of the external
- * crypto library (currently either OpenSSL (default), or mbed TLS).
- */
diff --git a/doc/doxygen/doc_eventloop.h b/doc/doxygen/doc_eventloop.h
deleted file mode 100644
index 8bd2635..0000000
--- a/doc/doxygen/doc_eventloop.h
+++ /dev/null
@@ -1,66 +0,0 @@
-/*
- * OpenVPN -- An application to securely tunnel IP networks
- * over a single TCP/UDP port, with support for SSL/TLS-based
- * session authentication and key exchange,
- * packet encryption, packet authentication, and
- * packet compression.
- *
- * Copyright (C) 2010-2018 Fox Crypto B.V. <openvpn@fox-it.com>
- *
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License version 2
- * as published by the Free Software Foundation.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License along
- * with this program; if not, write to the Free Software Foundation, Inc.,
- * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
- */
-
-/**
- * @file
- * Main Event Loop module documentation file.
- */
-
-/**
- * @defgroup eventloop Main Event Loop module
- *
- * This main event loop module drives the packet processing of OpenVPN.
- *
- * OpenVPN is an event driven system. Its activities are driven by a main
- * event loop, which repeatedly waits for one of several predefined events
- * to occur, and then calls the appropriate module to handle the event.
- * The major types of network events that OpenVPN processes are:
- * - A packet can be read from the external network interface.
- * - The main event loop activates the \link external_multiplexer
- * External Multiplexer\endlink to read and process the packet.
- * - A packet can be read from the virtual tun/tap network interface.
- * - The main event loop activates the \link internal_multiplexer
- * Internal Multiplexer\endlink to read and process the packet.
- * - If a packet is ready to be sent out as a VPN tunnel packet: the
- * external network interface can be written to.
- * - The main event loop activates the \link external_multiplexer
- * External Multiplexer\endlink to send the packet.
- * - If a packet is ready to be sent to a locally reachable destination:
- * the virtual tun/tap network interface can be written to.
- * - The main event loop activates the \link internal_multiplexer
- * Internal Multiplexer\endlink to send the packet.
- *
- * Beside these external events, OpenVPN also processes other types of
- * internal events. These include scheduled events, such as resending of
- * non-acknowledged control channel messages.
- *
- * @par Main event loop implementations
- *
- * Depending on the mode in which OpenVPN is running, a different main
- * event loop function is called to drive the event processing. The
- * following implementations are available:
- * - Client mode using UDP or TCP: \c tunnel_point_to_point()
- * - Server mode using UDP: \c tunnel_server_udp_single_threaded()
- * - Server mode using TCP: \c tunnel_server_tcp()
- */
diff --git a/doc/doxygen/doc_external_multiplexer.h b/doc/doxygen/doc_external_multiplexer.h
deleted file mode 100644
index 692c15c..0000000
--- a/doc/doxygen/doc_external_multiplexer.h
+++ /dev/null
@@ -1,45 +0,0 @@
-/*
- * OpenVPN -- An application to securely tunnel IP networks
- * over a single TCP/UDP port, with support for SSL/TLS-based
- * session authentication and key exchange,
- * packet encryption, packet authentication, and
- * packet compression.
- *
- * Copyright (C) 2010-2018 Fox Crypto B.V. <openvpn@fox-it.com>
- *
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License version 2
- * as published by the Free Software Foundation.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License along
- * with this program; if not, write to the Free Software Foundation, Inc.,
- * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
- */
-
-/**
- * @file
- * External Multiplexer module documentation file.
- */
-
-/**
- * @addtogroup external_multiplexer External Multiplexer module
- *
- * The External Multiplexer is the link between the external network
- * interface and the other OpenVPN modules. It reads packets from the
- * external network interface, determines which remote OpenVPN peer and
- * VPN tunnel they are associated with, and whether they are data channel
- * or control channel packets. It then passes the packets on to the
- * appropriate processing module.
- *
- * This module also handles packets traveling in the reverse direction,
- * which have been generated by the local control channel or which have
- * already been processed by the \link data_control Data Channel Control
- * module\endlink and are destined for a remote host reachable through a
- * VPN tunnel.
- */
diff --git a/doc/doxygen/doc_fragmentation.h b/doc/doxygen/doc_fragmentation.h
deleted file mode 100644
index 90e8d9e..0000000
--- a/doc/doxygen/doc_fragmentation.h
+++ /dev/null
@@ -1,95 +0,0 @@
-/*
- * OpenVPN -- An application to securely tunnel IP networks
- * over a single TCP/UDP port, with support for SSL/TLS-based
- * session authentication and key exchange,
- * packet encryption, packet authentication, and
- * packet compression.
- *
- * Copyright (C) 2010-2018 Fox Crypto B.V. <openvpn@fox-it.com>
- *
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License version 2
- * as published by the Free Software Foundation.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License along
- * with this program; if not, write to the Free Software Foundation, Inc.,
- * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
- */
-
-/**
- * @file
- * Data Channel Fragmentation module documentation file.
- */
-
-/**
- * @defgroup fragmentation Data Channel Fragmentation module
- *
- * The Data Channel Fragmentation module offers fragmentation of data
- * channel packets.
- *
- * @par State structures
- * The Data Channel Fragmentation module stores its internal state in a \c
- * fragment_master structure. One such structure is present for each VPN
- * tunnel, and is stored in \c context.c2.fragment of the \c context
- * associated with that VPN tunnel.
- *
- * @par
- * The \c fragment_master structure contains one \c fragment_list
- * structure \c fragment_master.incoming. This is a list of \c fragment
- * structures, each of which can store the parts of one fragmented packet
- * while it is being reassembled. The \c fragment_master structure also
- * contains one \c buffer called \c fragment_master.outgoing, in which a
- * data channel large packet to be sent to a remote OpenVPN peer can be
- * broken up into parts to be sent one by one.
- *
- * @par Initialization and cleanup
- * Every time a new \c fragment_master is needed, it must be allocated and
- * initialized by the \c fragment_init() function. Similarly, every time
- * a \c fragment_master is no longer needed, it must be cleaned up using
- * the \c fragment_free() function. These functions take care of the
- * allocation and freeing of the \c fragment_master structure itself and
- * all internal memory required for the use of that structure. Note that
- * this behavior is different from that displayed by the \link compression
- * Data Channel Compression module\endlink.
- *
- * @par
- * Because of the one-to-one relationship between \c fragment_master
- * structures and VPN tunnels, the above-mentioned initialization and
- * cleanup functions are called directly from the \c init_instance() and
- * \c close_instance() functions, which control the initialization and
- * cleanup of VPN tunnel instances and their associated \c context
- * structures.
- *
- * @par Packet processing functions
- * This module receives data channel packets from the \link data_control
- * Data Channel Control module\endlink and processes them according to the
- * settings of the packet's VPN tunnel. The \link data_control Data
- * Channel Control module\endlink uses the following interface functions:
- * - For packets which will be sent to a remote OpenVPN peer: \c
- * fragment_outgoing() \n This function inspects data channel packets as
- * they are being made ready to be sent as VPN tunnel packets to a
- * remote OpenVPN peer. If a packet's size is larger than its
- * destination VPN tunnel's maximum transmission unit (MTU), then this
- * module breaks that packet up into smaller parts, each of which is
- * smaller than or equal to the VPN tunnel's MTU. See \c
- * fragment_outgoing() for details.
- * - For packets which have been received from a remote OpenVPN peer: \c
- * fragment_incoming() \n This function inspects data channel packets
- * that have been received from a remote OpenVPN peer through a VPN
- * tunnel. It reads the fragmentation header of the packet, and
- * depending on its value performs the appropriate action. See \c
- * fragment_incoming() for details.
- *
- * @par Settings that control this module's activity
- * Whether the Data Channel Fragmentation module is active or not depends
- * on the compile-time \c ENABLE_FRAGMENT preprocessor macro and the
- * runtime flag \c options.fragment, which gets its value from the
- * process's configuration sources, such as the configuration file and
- * commandline %options.
- */
diff --git a/doc/doxygen/doc_internal_multiplexer.h b/doc/doxygen/doc_internal_multiplexer.h
deleted file mode 100644
index c68a09c..0000000
--- a/doc/doxygen/doc_internal_multiplexer.h
+++ /dev/null
@@ -1,43 +0,0 @@
-/*
- * OpenVPN -- An application to securely tunnel IP networks
- * over a single TCP/UDP port, with support for SSL/TLS-based
- * session authentication and key exchange,
- * packet encryption, packet authentication, and
- * packet compression.
- *
- * Copyright (C) 2010-2018 Fox Crypto B.V. <openvpn@fox-it.com>
- *
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License version 2
- * as published by the Free Software Foundation.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License along
- * with this program; if not, write to the Free Software Foundation, Inc.,
- * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
- */
-
-/**
- * @file
- * Internal Multiplexer module documentation file.
- */
-
-/**
- * @addtogroup internal_multiplexer Internal Multiplexer module
- *
- * The Internal Multiplexer is the link between the virtual tun/tap
- * network interface and the \link data_control Data Channel Control
- * module\endlink. It reads packets from the virtual network interface,
- * determines for which remote OpenVPN peer they are destined, and then
- * passes the packets on to the Data Channel Control module together with
- * information about their destination VPN tunnel instance.
- *
- * This module also handles packets traveling in the reverse direction,
- * which have already been processed by the Data Channel Control module
- * and are destined for a locally reachable host.
- */
diff --git a/doc/doxygen/doc_key_generation.h b/doc/doxygen/doc_key_generation.h
deleted file mode 100644
index 4bb9c70..0000000
--- a/doc/doxygen/doc_key_generation.h
+++ /dev/null
@@ -1,148 +0,0 @@
-/*
- * OpenVPN -- An application to securely tunnel IP networks
- * over a single TCP/UDP port, with support for SSL/TLS-based
- * session authentication and key exchange,
- * packet encryption, packet authentication, and
- * packet compression.
- *
- * Copyright (C) 2010-2018 Fox Crypto B.V. <openvpn@fox-it.com>
- *
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License version 2
- * as published by the Free Software Foundation.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License along
- * with this program; if not, write to the Free Software Foundation, Inc.,
- * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
- */
-
-/**
- * @file
- * Key generation documentation file.
- */
-
-/**
- * @page key_generation Data channel %key generation
- *
- * This section describes how OpenVPN peers generate and exchange %key
- * material necessary for the security operations performed on data
- * channel packets.
- *
- * The %key generation and exchange process between OpenVPN client and
- * server occurs every time data channel security parameters are
- * negotiated, for example during the initial setup of a VPN tunnel or
- * when the active security parameters expire. In source code terms, this
- * is when a new key_state structure is initialized.
- *
- * @section key_generation_method Key methods
- *
- * OpenVPN supports two different ways of generating and exchanging %key
- * material between client and server. These are known as %key method 1
- * and %key method 2. %Key method 2 is the recommended method. Both are
- * explained below.
- *
- * @subsection key_generation_method_1 Key method 1
- *
- * -# Each host generates its own random material.
- * -# Each host uses its locally generated random material as %key data
- * for encrypting and signing packets sent to the remote peer.
- * -# Each host then sends its random material to the remote peer, so that
- * the remote peer can use that %key data for authenticating and
- * decrypting received packets.
- *
- * @subsection key_generation_method_2 Key method 2
- *
- * -# The client generates random material in the following amounts:
- * - Pre-master secret: 48 bytes
- * - Client's PRF seed for master secret: 32 bytes
- * - Client's PRF seed for %key expansion: 32 bytes
- * -# The client sends its share of random material to the server.
- * -# The server generates random material in the following amounts:
- * - Server's PRF seed for master secret: 32 bytes
- * - Server's PRF seed for %key expansion: 32 bytes
- * -# The server computes the %key expansion using its own and the
- * client's random material.
- * -# The server sends its share of random material to the client.
- * -# The client computes the %key expansion using its own and the
- * server's random material.
- *
- * %Key method 2 %key expansion is performed by the \c
- * generate_key_expansion() function. Please refer to its source code for
- * details of the %key expansion process.
- *
- * @subsection key_generation_random Source of random material
- *
- * OpenVPN uses the either the OpenSSL library or the mbed TLS library as its
- * source of random material.
- *
- * In OpenSSL, the \c RAND_bytes() function is called
- * to supply cryptographically strong pseudo-random data. The following links
- * contain more information on this subject:
- * - For OpenSSL's \c RAND_bytes() function:
- * http://www.openssl.org/docs/crypto/RAND_bytes.html
- * - For OpenSSL's pseudo-random number generating system:
- * http://www.openssl.org/docs/crypto/rand.html
- * - For OpenSSL's support for external crypto modules:
- * http://www.openssl.org/docs/crypto/engine.html
- *
- * In mbed TLS, the Havege random number generator is used. For details, see
- * the mbed TLS documentation.
- *
- * @section key_generation_exchange Key exchange:
- *
- * The %key exchange process is initiated by the OpenVPN process running
- * in client mode. After the initial three-way handshake has successfully
- * completed, the client sends its share of random material to the server,
- * after which the server responds with its part. This process is
- * depicted below:
- *
-@verbatim
- Client Client Server Server
- State Action Action State
----------- -------------------- -------------------- ----------
-
- ... waiting until three-way handshake complete ...
-S_START S_START
- key_method_?_write()
- send to server --> --> --> --> receive from client
-S_SENT_KEY key_method_?_read()
- S_GOT_KEY
- key_method_?_write()
- receive from server <-- <-- <-- <-- send to client
- key_method_?_read() S_SENT_KEY
-S_GOT_KEY
- ... waiting until control channel fully synchronized ...
-S_ACTIVE S_ACTIVE
-@endverbatim
- *
- * For more information about the client and server state values, see the
- * \link control_processor Control Channel Processor module\endlink.
- *
- * Depending on which %key method is used, the \c ? in the function names
- * of the diagram above is a \c 1 or a \c 2. For example, if %key method
- * 2 is used, that %key exchange would be started by the client calling \c
- * key_method_2_write(). These functions are called from the \link
- * control_processor Control Channel Processor module's\endlink \c
- * tls_process() function and control the %key generation and exchange
- * process as follows:
- * - %Key method 1 has been removed in OpenVPN 2.5
- * - %Key method 2:
- * - \c key_method_2_write(): generate random material locally, and if
- * in server mode generate %key expansion.
- * - \c key_method_2_read(): read random material received from remote
- * peer, and if in client mode generate %key expansion.
- *
- * @subsection key_generation_encapsulation Transmission of key material
- *
- * The OpenVPN client and server communicate with each other through their
- * control channel. This means that all of the data transmitted over the
- * network, such as random material for %key generation, is encapsulated
- * in a TLS layer. For more details, see the \link control_tls Control
- * Channel TLS module\endlink documentation.
- */
diff --git a/doc/doxygen/doc_mainpage.h b/doc/doxygen/doc_mainpage.h
deleted file mode 100644
index 6016d07..0000000
--- a/doc/doxygen/doc_mainpage.h
+++ /dev/null
@@ -1,161 +0,0 @@
-/*
- * OpenVPN -- An application to securely tunnel IP networks
- * over a single TCP/UDP port, with support for SSL/TLS-based
- * session authentication and key exchange,
- * packet encryption, packet authentication, and
- * packet compression.
- *
- * Copyright (C) 2010-2018 Fox Crypto B.V. <openvpn@fox-it.com>
- *
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License version 2
- * as published by the Free Software Foundation.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License along
- * with this program; if not, write to the Free Software Foundation, Inc.,
- * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
- */
-
-/**
- * @file
- * Main page documentation file.
- */
-
-/**
- * @mainpage OpenVPN source code documentation
- *
- * This documentation describes the internal structure of OpenVPN. It was
- * automatically generated from specially formatted comment blocks in
- * OpenVPN's source code using Doxygen. (See
- * http://www.stack.nl/~dimitri/doxygen/ for more information on Doxygen)
- *
- * The \ref mainpage_modules "Modules section" below gives an introduction
- * into the high-level module concepts used throughout this documentation.
- * The \ref mainpage_relatedpages "Related Pages section" below describes
- * various special subjects related to OpenVPN's implementation which are
- * discussed in the related pages section.
- *
- * @section mainpage_modules Modules
- *
- * For the purpose of describing the internal structure of OpenVPN, this
- * documentation and the underlying source code has been broken up into a
- * number of conceptually well-defined parts, known as modules. Each
- * module plays a specific role within the OpenVPN process, and in most
- * cases each module has a clear interfacing strategy for interacting with
- * other modules.
- *
- * The following modules have been defined:
- * - Driver module:
- * - The \link eventloop Main Event Loop\endlink: this module drives the
- * event handling of OpenVPN. It implements various types of
- * select-loop which wait until an event happens, and then delegate
- * the handling of that event to the appropriate module.
- * - Network interface modules:
- * - The \link external_multiplexer External Multiplexer\endlink: this
- * module sends and receives packets to and from remote OpenVPN peers
- * over the external network interface. It also takes care of
- * demultiplexing received packets to their appropriate VPN tunnel and
- * splitting control channel and data channel packets.
- * - The \link internal_multiplexer Internal Multiplexer\endlink: this
- * module sends and receives packets to and from locally reachable
- * posts over the virtual tun/tap network interface. It also takes
- * care of determining through which VPN tunnel a received packet must
- * be sent to reach its destination.
- * - Control channel modules:
- * - The \link reliable Reliability Layer\endlink: this module offers a
- * %reliable and sequential transport layer for control channel
- * messages.
- * - The \link control_tls Control Channel TLS module\endlink: this
- * module offers a secure encapsulation of control channel messages
- * using the TLS protocol.
- * - The \link control_processor Control Channel Processor\endlink: his
- * module manages the setup, maintenance, and shut down of VPN
- * tunnels.
- * - Data channel modules:
- * - The \link data_control Data Channel Control module\endlink: this
- * module controls the processing of data channel packets and,
- * depending on the settings of the packet's VPN tunnel, passes the
- * packet to the three modules below for handling.
- * - The \link data_crypto Data Channel Crypto module\endlink: this
- * module performs security operations on data channel packets.
- * - The \link fragmentation Data Channel Fragmentation module\endlink:
- * this module offers fragmentation of data channel packets larger
- * than the VPN tunnel's MTU.
- * - The \link compression Data Channel Compression module\endlink: this
- * module offers compression of data channel packets.
- *
- * @subsection mainpage_modules_example Example event: receiving a packet
- *
- * OpenVPN handles many types of events during operation. These include
- * external events, such as network traffic being received, and internal
- * events, such as a %key session timing out causing renegotiation. An
- * example event, receiving a packet over the network, is described here
- * together with which modules play what roles:
- * -# The \link eventloop Main Event Loop\endlink detects that a packet
- * can be read from the external or the virtual tun/tap network
- * interface.
- * -# The \link eventloop Main Event Loop\endlink calls the \link
- * external_multiplexer External Multiplexer\endlink or \link
- * internal_multiplexer Internal Multiplexer\endlink to read and
- * process the packet.
- * -# The multiplexer module determines the type of packet and its
- * destination, and passes the packet on to the appropriate handling
- * module:
- * - A control channel packet received by the \link
- * external_multiplexer External Multiplexer\endlink is passed on
- * through the \link reliable Reliability Layer\endlink and the \link
- * control_tls Control Channel TLS module\endlink to the \link
- * control_processor Control Channel Processor\endlink.
- * - A data channel packet received by either multiplexer module is
- * passed on to the \link data_control Data Channel Control
- * module\endlink.
- * -# The packet is processed by the appropriate control channel or data
- * channel modules.
- * -# If, after processing the packet, a resulting packet is generated
- * that needs to be sent to a local or remote destination, it is given
- * to the \link external_multiplexer External Multiplexer\endlink or
- * \link internal_multiplexer Internal Multiplexer\endlink for sending.
- * -# If a packet is waiting to be sent by either multiplexer module and
- * the \link eventloop Main Event Loop\endlink detects that data can be
- * written to the associated network interface, it calls the
- * multiplexer module to send the packet.
- *
- * @section mainpage_relatedpages Related pages
- *
- * This documentation includes a number of descriptions of various aspects
- * of OpenVPN and its implementation. These are not directly related to
- * one module, function, or data structure, and are therefore listed
- * separately under "Related Pages".
- *
- * @subsection mainpage_relatedpages_key_generation Data channel key generation
- *
- * The @ref key_generation "Data channel key generation" related page
- * describes how, during VPN tunnel setup and renegotiation, OpenVPN peers
- * generate and exchange the %key material required for the symmetric
- * encryption/decryption and HMAC signing/verifying security operations
- * performed on data channel packets.
- *
- * @subsection mainpage_relatedpages_tunnel_state VPN tunnel state
- *
- * The @ref tunnel_state "Structure of VPN tunnel state storage" related
- * page describes how an OpenVPN process manages the state information
- * associated with its active VPN tunnels.
- *
- * @subsection mainpage_relatedpages_network_protocol Network protocol
- *
- * The @ref network_protocol "Network protocol" related page describes the
- * format and content of VPN tunnel packets exchanged between OpenVPN
- * peers.
- *
- * @subsection mainpage_relatedpages_memory_management Memory management
- *
- * The @ref memory_management "Memory management strategies" related page
- * gives a brief introduction into OpenVPN's memory %buffer library and
- * garbage collection facilities.
- */
diff --git a/doc/doxygen/doc_memory_management.h b/doc/doxygen/doc_memory_management.h
deleted file mode 100644
index 1f16328..0000000
--- a/doc/doxygen/doc_memory_management.h
+++ /dev/null
@@ -1,98 +0,0 @@
-/*
- * OpenVPN -- An application to securely tunnel IP networks
- * over a single TCP/UDP port, with support for SSL/TLS-based
- * session authentication and key exchange,
- * packet encryption, packet authentication, and
- * packet compression.
- *
- * Copyright (C) 2010-2018 Fox Crypto B.V. <openvpn@fox-it.com>
- *
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License version 2
- * as published by the Free Software Foundation.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License along
- * with this program; if not, write to the Free Software Foundation, Inc.,
- * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
- */
-
-/**
- * @file
- * Memory management strategies documentation file.
- */
-
-/**
- * @page memory_management OpenVPN's memory management strategies
- *
- * This section describes several implementation details relating to
- * OpenVPN's memory management strategies.
- *
- * During operation, the OpenVPN process performs all kinds of operations
- * on blocks of data. Receiving packets, encrypting content, prepending
- * headers, etc. To make the programmer's job easier and to decrease the
- * likelihood of memory-related bugs, OpenVPN uses its own memory %buffer
- * library and garbage collection facilities. These are described in
- * brief here.
- *
- * @section memory_management_buffer The buffer structure
- *
- * The \c buffer structure is a wrapper around a block of dynamically
- * allocated memory which keeps track of the block's capacity \c
- * buffer.capacity and location in memory \c buffer.data. This structure
- * supports efficient prepending and appending within the allocated memory
- * through the use of offset \c buffer.offset and length \c buffer.len
- * fields. See the \c buffer documentation for more details on the
- * structure itself.
- *
- * OpenVPN's %buffer library, implemented in the \c buffer.h and \c
- * buffer.c files, contains many utility functions for working with \c
- * buffer structures. These functions facilitate common operations, such
- * as allocating, freeing, reading and writing to \c buffer structures,
- * and even offer several more advanced operations, such as string
- * matching and creating sub-buffers.
- *
- * Not only do these utility functions make working with \c buffer
- * structures easy, they also perform extensive error checking. Each
- * function, where necessary, checks whether enough space is available
- * before performing its actions. This minimizes the chance of bugs
- * leading to %buffer overflows and other vulnerabilities.
- *
- * @section memory_management_frame The frame structure
- *
- * The \c frame structure keeps track of the maximum allowed packet
- * geometries of a network connection.
- *
- * It is used, for example, to determine the size of \c buffer structures
- * in which to store data channel packets. This is done by having each
- * data channel processing module register the maximum amount of extra
- * space it will need for header prepending and content expansion in the
- * \c frame structure. Once these parameters are known, \c buffer
- * structures can be allocated, based on the \c frame parameters, so that
- * they are large enough to allow efficient prepending of headers and
- * processing of content.
- *
- * @section memory_management_garbage Garbage collection
- *
- * OpenVPN has many sizable functions which perform various actions
- * depending on their %context. This makes it difficult to know in advance
- * exactly how much memory must be allocated. The garbage collection
- * facilities are used to keep track of dynamic allocations, thereby
- * allowing easy collective freeing of the allocated memory.
- *
- * The garbage collection system is implemented by the \c gc_arena and \c
- * gc_entry structures. The arena represents a garbage collecting unit,
- * and contains a linked list of entries. Each entry represents one block
- * of dynamically allocated memory.
- *
- * The garbage collection system also contains various utility functions
- * for working with the garbage collection structures. These include
- * functions for initializing new arenas, allocating memory of a given
- * size and registering the allocation in an arena, and freeing all the
- * allocated memory associated with an arena.
- */
diff --git a/doc/doxygen/doc_protocol_overview.h b/doc/doxygen/doc_protocol_overview.h
deleted file mode 100644
index 0821222..0000000
--- a/doc/doxygen/doc_protocol_overview.h
+++ /dev/null
@@ -1,195 +0,0 @@
-/*
- * OpenVPN -- An application to securely tunnel IP networks
- * over a single TCP/UDP port, with support for SSL/TLS-based
- * session authentication and key exchange,
- * packet encryption, packet authentication, and
- * packet compression.
- *
- * Copyright (C) 2010-2018 Fox Crypto B.V. <openvpn@fox-it.com>
- *
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License version 2
- * as published by the Free Software Foundation.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License along
- * with this program; if not, write to the Free Software Foundation, Inc.,
- * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
- */
-
-/**
- * @file Network protocol overview documentation file.
- */
-
-/**
- * @page network_protocol OpenVPN's network protocol
- *
- * Description of packet structure in OpenVPN's network protocol.
- *
- * This document describes the structure of packets exchanged between
- * OpenVPN peers. It is based on the protocol description in the \c ssl.h
- * file.
- *
- * @section network_protocol_external Outer structure of packets exchanged between OpenVPN peers
- *
- * VPN tunnel packets are transported between OpenVPN peers using the UDP
- * or TCP protocols. Their structure is described below.
- *
- * @subsection network_protocol_external_structure External packet structure
- *
- * - packet length (16 bits, unsigned) [TCP-mode only]: always sent as
- * plain text. Since TCP is a stream protocol, this packet length
- * defines the packetization of the stream.
- * - packet opcode and key_id (8 bits) [TLS-mode only]:
- * - package message type (high 5 bits)
- * - key_id (low 3 bits): the key_id refers to an already negotiated
- * TLS session. OpenVPN seamlessly renegotiates the TLS session by
- * using a new key_id for the new session. Overlap (controlled by
- * user definable parameters) between old and new TLS sessions is
- * allowed, providing a seamless transition during tunnel operation.
- * - payload (n bytes)
- *
- * @subsection network_protocol_external_types Message types
- *
- * The type of a VPN tunnel packet is indicated by its opcode. The
- * following describes the various opcodes available.
- *
- * - Control channel messages:
- * - \ref P_CONTROL_HARD_RESET_CLIENT_V1 -- %Key method 1, initial %key
- * from client, forget previous state.
- * - \ref P_CONTROL_HARD_RESET_SERVER_V1 -- %Key method 1, initial %key
- * from server, forget previous state.
- * - \ref P_CONTROL_HARD_RESET_CLIENT_V2 -- %Key method 2, initial %key
- * from client, forget previous state.
- * - \ref P_CONTROL_HARD_RESET_SERVER_V2 -- %Key method 2, initial %key
- * from server, forget previous state.
- * - \ref P_CONTROL_SOFT_RESET_V1 -- New %key, with a graceful
- * transition from old to new %key in the sense that a transition
- * window exists where both the old or new key_id can be used.
- * - \ref P_CONTROL_V1 -- Control channel packet (usually TLS
- * ciphertext).
- * - \ref P_ACK_V1 -- Acknowledgement for control channel packets
- * received.
- * - Data channel messages:
- * - \ref P_DATA_V1 -- Data channel packet containing data channel
- * ciphertext.
- * - \ref P_DATA_V2 -- Data channel packet containing peer-id and data
- * channel ciphertext.
- *
- * @subsection network_protocol_external_key_id Session IDs and Key IDs
- *
- * OpenVPN uses two different forms of packet identifiers:
- * - The first form is 64 bits and is used for all control channel
- * messages. This form is referred to as a \c session_id.
- * - Data channel messages on the other hand use a shortened form of 3
- * bits for efficiency reasons since the vast majority of OpenVPN
- * packets in an active tunnel will be data channel messages. This
- * form is referred to as a \c key_id.
- *
- * The control and data channels use independent packet-id sequences,
- * because the data channel is an unreliable channel while the control
- * channel is a %reliable channel. Each use their own independent HMAC
- * keys.
- *
- * @subsection network_protocol_external_reliable Control channel reliability layer
- *
- * Control channel messages (\c P_CONTROL_* and \c P_ACK_* message types)
- * are TLS ciphertext packets which have been encapsulated inside of a
- * reliability layer. The reliability layer is implemented as a
- * straightforward acknowledge and retransmit model.
- *
- * Acknowledgments of received messages can be encoded in either the
- * dedicated \c P_ACK_* record or they can be prepended to a \c
- * P_CONTROL_* message.
- *
- * See the \link reliable Reliability Layer\endlink module for a detailed
- * description.
- *
- * @section network_protocol_control Structure of control channel messages
- *
- * @subsection network_protocol_control_ciphertext Structure of ciphertext control channel messages
- *
- * Control channel packets in ciphertext form consist of the following
- * parts:
- *
- * - local \c session_id (random 64 bit value to identify TLS session).
- * - HMAC signature of entire encapsulation header for HMAC firewall
- * [only if \c --tls-auth is specified] (usually 16 or 20 bytes).
- * - packet-id for replay protection (4 or 8 bytes, includes sequence
- * number and optional \c time_t timestamp).
- * - acknowledgment packet-id array length (1 byte).
- * - acknowledgment packet-id array (if length > 0).
- * - acknowledgment remote session-id (if length > 0).
- * - packet-id of this message (4 bytes).
- * - TLS payload ciphertext (n bytes) (only for \c P_CONTROL_V1).
- *
- * Note that when \c --tls-auth is used, all message types are protected
- * with an HMAC signature, even the initial packets of the TLS handshake.
- * This makes it easy for OpenVPN to throw away bogus packets quickly,
- * without wasting resources on attempting a TLS handshake which will
- * ultimately fail.
- *
- * @subsection network_protocol_control_key_methods Control channel key methods
- *
- * Once the TLS session has been initialized and authenticated, the TLS
- * channel is used to exchange random %key material for bidirectional
- * cipher and HMAC keys which will be used to secure data channel packets.
- * OpenVPN currently implements two %key methods. %Key method 1 directly
- * derives keys using random bits obtained from the \c rand_bytes() function.
- * %Key method 2 mixes random %key material from both sides of the connection
- * using the TLS PRF mixing function. %Key method 2 is the preferred method and
- * is the default for OpenVPN 2.0+.
- *
- * The @ref key_generation "Data channel key generation" related page
- * describes the %key methods in more detail.
- *
- * @subsection network_protocol_control_plaintext Structure of plaintext control channel messages
- *
- * - %Key method 1 (support removed in OpenVPN 2.5):
- * - Cipher %key length in bytes (1 byte).
- * - Cipher %key (n bytes).
- * - HMAC %key length in bytes (1 byte).
- * - HMAC %key (n bytes).
- * - %Options string (n bytes, null terminated, client/server %options
- * string should match).
- * - %Key method 2:
- * - Literal 0 (4 bytes).
- * - %Key method (1 byte).
- * - \c key_source structure (\c key_source.pre_master only defined
- * for client -> server).
- * - %Options string length, including null (2 bytes).
- * - %Options string (n bytes, null terminated, client/server %options
- * string must match).
- * - [The username/password data below is optional, record can end at
- * this point.]
- * - Username string length, including null (2 bytes).
- * - Username string (n bytes, null terminated).
- * - Password string length, including null (2 bytes).
- * - Password string (n bytes, null terminated).
- *
- * @section network_protocol_data Structure of data channel messages
- *
- * The P_DATA_* payload represents encapsulated tunnel packets which tend to be
- * either IP packets or Ethernet frames. This is essentially the "payload" of
- * the VPN. Data channel packets consist of a data channel header, and a
- * payload. There are two possible formats:
- *
- * @par P_DATA_V1
- * P_DATA_V1 packets have a 1-byte header, carrying the \ref P_DATA_V1 \c opcode
- * and \c key_id, followed by the payload:\n
- * <tt> [ 5-bit opcode | 3-bit key_id ] [ payload ] </tt>
- *
- * @par P_DATA_V2
- * P_DATA_V2 packets have the same 1-byte opcode/key_id, but carrying the \ref
- * P_DATA_V2 opcode, followed by a 3-byte peer-id, which uniquely identifies
- * the peer:\n
- * <tt> [ 5-bit opcode | 3-bit key_id ] [ 24-bit peer-id ] [ payload ] </tt>
- *
- * See @ref data_crypto for details on the data channel payload format.
- *
- */
diff --git a/doc/doxygen/doc_reliable.h b/doc/doxygen/doc_reliable.h
deleted file mode 100644
index 70556d7..0000000
--- a/doc/doxygen/doc_reliable.h
+++ /dev/null
@@ -1,48 +0,0 @@
-/*
- * OpenVPN -- An application to securely tunnel IP networks
- * over a single TCP/UDP port, with support for SSL/TLS-based
- * session authentication and key exchange,
- * packet encryption, packet authentication, and
- * packet compression.
- *
- * Copyright (C) 2010-2018 Fox Crypto B.V. <openvpn@fox-it.com>
- *
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License version 2
- * as published by the Free Software Foundation.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License along
- * with this program; if not, write to the Free Software Foundation, Inc.,
- * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
- */
-
-/**
- * @file
- * Reliability Layer module documentation file.
- */
-
-/**
- * @defgroup reliable Reliability Layer module
- *
- * The Reliability Layer is part of OpenVPN's control channel. It
- * provides a reliable and sequential transport mechanism for control
- * channel messages between OpenVPN peers. This module forms the
- * interface between the \link external_multiplexer External
- * Multiplexer\endlink and the \link control_tls Control Channel TLS
- * module\endlink.
- *
- * @par UDP or TCP as VPN tunnel transport
- *
- * This is especially important when OpenVPN is configured to communicate
- * over UDP, because UDP does not offer a reliable and sequential
- * transport. OpenVPN endpoints can also communicate over TCP which does
- * provide a reliable and sequential transport. In both cases, using UDP
- * or TCP as an external transport, the internal Reliability Layer is
- * active.
- */
diff --git a/doc/doxygen/doc_tunnel_state.h b/doc/doxygen/doc_tunnel_state.h
deleted file mode 100644
index 46e750f..0000000
--- a/doc/doxygen/doc_tunnel_state.h
+++ /dev/null
@@ -1,154 +0,0 @@
-/*
- * OpenVPN -- An application to securely tunnel IP networks
- * over a single TCP/UDP port, with support for SSL/TLS-based
- * session authentication and key exchange,
- * packet encryption, packet authentication, and
- * packet compression.
- *
- * Copyright (C) 2010-2018 Fox Crypto B.V. <openvpn@fox-it.com>
- *
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License version 2
- * as published by the Free Software Foundation.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License along
- * with this program; if not, write to the Free Software Foundation, Inc.,
- * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
- */
-
-/**
- * @file
- * VPN tunnel state documentation file.
- */
-
-/**
- * @page tunnel_state Structure of the VPN tunnel state storage
- *
- * This section describes how OpenVPN stores its VPN tunnel state during
- * operation.
- *
- * OpenVPN uses several data structures as storage containers for state
- * information of active VPN tunnels. These are described in this
- * section, together with a little bit of history to help understand the
- * origin of the current architecture.
- *
- * Whether an OpenVPN process is running in client-mode or server-mode
- * determines whether it can support only one or multiple simultaneously
- * active VPN tunnels. This consequently also determines how the
- * associated state information is wrapped up internally. This section
- * gives an overview of the differences.
- *
- * @section tunnel_state_history Historic developments
- *
- * In the old v1.x series, an OpenVPN process managed only one single VPN
- * tunnel. This allowed the VPN tunnel state to be stored together with
- * process-global information in one single \c context structure.
- *
- * This changed, however, in the v2.x series, as new OpenVPN versions
- * running in server-mode can support multiple simultaneously active VPN
- * tunnels. This necessitated a redesign of the VPN tunnel state
- * container structures, and modification of the \link
- * external_multiplexer External Multiplexer\endlink and \link
- * internal_multiplexer Internal Multiplexer\endlink systems. The
- * majority of these changes are only relevant for OpenVPN processes
- * running in server-mode, and the client-mode structure has remained very
- * similar to the v1.x single-tunnel form.
- *
- * @section tunnel_state_client Client-mode state
- *
- * An OpenVPN process running in client-mode can manage at most one single
- * VPN tunnel at any one time. The state information for a client's VPN
- * tunnel is stored in a \c context structure.
- *
- * The \c context structure is created in the \c main() function. That is
- * also where process-wide initialization takes place, such as parsing
- * command line %options and reading configuration files. The \c context
- * is then passed to \c tunnel_point_to_point() which drives OpenVPN's
- * main event processing loop. These functions are both part of the \link
- * eventloop Main Event Loop\endlink module.
- *
- * @subsection tunnel_state_client_init Initialization and cleanup
- *
- * Because there is only one \c context structure present, it can be
- * initialized and cleaned up from the client's main event processing
- * function. Before the \c tunnel_point_to_point() function enters its
- * event loop, it calls \c init_instance_handle_signals() which calls \c
- * init_instance() to initialize the single \c context structure. After
- * the event loop stops, it calls \c close_instance() to clean up the \c
- * context.
- *
- * @subsection tunnel_state_client_event Event processing
- *
- * When the main event processing loop activates the external or internal
- * multiplexer to handle a network event, it is not necessary to determine
- * which VPN tunnel the event is associated with, because there is only
- * one VPN tunnel active.
- *
- * @section tunnel_state_server Server-mode state
- *
- * An OpenVPN process running in server-mode can manage multiple
- * simultaneously active VPN tunnels. For every VPN tunnel active, in
- * other words for every OpenVPN client which is connected to a server,
- * the OpenVPN server has one \c context structure in which it stores that
- * particular VPN tunnel's state information.
- *
- * @subsection tunnel_state_server_multi Multi_context and multi_instance structures
- *
- * To support multiple \c context structures, each is wrapped in a \c
- * multi_instance structure, and all the \c multi_instance structures are
- * registered in one single \c multi_context structure. The \link
- * external_multiplexer External Multiplexer\endlink and \link
- * internal_multiplexer Internal Multiplexer\endlink then use the \c
- * multi_context to retrieve the correct \c multi_instance and \c context
- * associated with a given network address.
- *
- * @subsection tunnel_state_server_init Startup and initialization
- *
- * An OpenVPN process running in server-mode starts in the same \c main()
- * function as it would in client-mode. The same process-wide
- * initialization is performed, and the resulting state and configuration
- * is stored in a \c context structure. The server-mode and client-mode
- * processes diverge when the \c main() function calls one of \c
- * tunnel_point_to_point() or \c tunnel_server().
- *
- * In server-mode, \c main() calls the \c tunnel_server() function, which
- * transfers control to \c tunnel_server_udp_single_threaded() or \c
- * tunnel_server_tcp() depending on the external transport protocol.
- *
- * These functions receive the \c context created in \c main(). This
- * object has a special status in server-mode, as it does not represent an
- * active VPN tunnel, but does contain process-wide configuration
- * parameters. In the source code, it is often stored in "top" variables.
- * To distinguish this object from other instances of the same type, its
- * \c context.mode value is set to \c CM_TOP. Other \c context objects,
- * which do represent active VPN tunnels, have a \c context.mode set to \c
- * CM_CHILD_UDP or \c CM_CHILD_TCP, depending on the external transport
- * protocol.
- *
- * Both \c tunnel_server_udp_single_threaded() and \c tunnel_server_tcp()
- * perform similar initialization. In either case, a \c multi_context
- * structure is created, and it is initialized according to the
- * configuration stored in the top \c context by the \c multi_init() and
- * \c multi_top_init() functions.
- *
- * @subsection tunnel_state_server_tunnels Creating and destroying VPN tunnels
- *
- * When an OpenVPN client makes a new connection to a server, the server
- * creates a new \c context and \c multi_instance. The latter is
- * registered in the \c multi_context, which makes it possible for the
- * external and internal multiplexers to retrieve the correct \c
- * multi_instance and \c context when a network event occurs.
- *
- * @subsection tunnel_state_server_cleanup Final cleanup
- *
- * After the main event loop exits, both \c
- * tunnel_server_udp_single_threaded() and \c tunnel_server_tcp() perform
- * similar cleanup. They call \c multi_uninit() followed by \c
- * multi_top_free() to clean up the \c multi_context structure.
- */
diff --git a/doc/keying-material-exporter.txt b/doc/keying-material-exporter.txt
deleted file mode 100644
index 4c1addc..0000000
--- a/doc/keying-material-exporter.txt
+++ /dev/null
@@ -1,137 +0,0 @@
-OpenVPN Daniel Kubec <niel@rtfm.cz>
-RFC-5705 February 2015
-
-
- Added support for TLS Keying Material Exporters
-
-Keying Material Exporter [RFC-5705] allow additional keying material to be
-derived from existing TLS channel. This exported keying material can then be
-used for a variety of purposes. TLS allows client and server to establish
-keying material for use in the upper layers between the TLS end-points and
-channel bindings is straightforward and well-defined mechanism how to
-authenticate other layers.
-
-
-OpenVPN Configuration
-
---keying-material-exporter label len
-
-Export Keying Material [RFC-5705] of len bytes (min. 16 bytes) using label in
-environment (exported_keying_material) for use by plugins in
-OPENVPN_PLUGIN_TLS_FINAL callback.
-
-Note that exporter labels have the potential to collide with existing PRF
-labels. In order to prevent this, labels MUST begin with "EXPORTER".
-(This option requires OpenSSL 1.0.1 or newer.)
-
-
-Use Cases:
-
-Secure bindings of AAA information to application layer
-
- OpenVPN Client <------> OpenVPN Server
- [KeyAgreement] [KeyAgreement]
-
- [TLSExportedKeyingMaterial] [TLSExportedKeyingMaterial]
- [AAASessionKey] [AAASessionKey]
- Client <------> Server
- [Authenticated layer on top of (D)TLS]
-
-
-TLS side channel authentication and straightforward bindings of AAA information
-to application layer using well-defined mechanism.
-
- OpenVPN Client <------> OpenVPN Server
- [KeyAgreement] [KeyAgreement]
-
- [TLSExportedKeyingMaterial] [TLSExportedKeyingMaterial]
- [DerivedAAABindingKey] [DerivedAAABindingKey]
- [AuthenticateBindingKeys]
- Client -------> Server
- [Confidential channel]
-
-
-TLS Message flow for a full handshake
-
- ClientHello -------->
- ServerHello
- Certificate*
- ServerKeyExchange*
- CertificateRequest*
- <-------- ServerHelloDone
- Certificate*
- ClientKeyExchange
- CertificateVerify*
- [ChangeCipherSpec]
- Finished -------->
- [ChangeCipherSpec]
- <-------- Finished
-
- GenerateTLSBindingKey GenerateTLSBindingKey
-
- Application Data <-------> Application Data
-
-
-Terminology
-
- AAA Authentication, Authorization, and Accounting:
- functions that are generally required to control
- access to a service and support auditing.
-
- Secure channel a packet, datagram, octet stream connection, or
- sequence of connections between two end-points that
- affords cryptographic integrity and confidentiality
- to data exchanged over it.
-
- Channel binding the process of establishing that no man-in-the-middle
- exists between two end-points that have been
- authenticated using secure channel.
-
- TLS Binding Key Exported Keying Material [RFC5705]
-
- If no context is provided, it then computes:
- PRF(SecurityParameters.master_secret, label,
- SecurityParameters.client_random +
- SecurityParameters.server_random
- )[length]
-
- If context is provided, it computes:
- PRF(SecurityParameters.master_secret, label,
- SecurityParameters.client_random +
- SecurityParameters.server_random +
- context_value_length + context_value
- )[length]
-
- AAA Binding Key TLS side channel authentication based on secure
- channel bindings requires one more key derivation.
-
- SHA1(TLSExportedKeyingMaterial + ServerPublicKey)
-
-Reference
-
- [OPENAAA] "TLS side channel authentication and straightforward
- bindings of AAA information to application
- layer using well-defined mechanism."
- Daniel Kubec <niel@rtfm.cz> March 2013
- https://github.com/n13l/openaaa
-
- [RFC5705] "Keying Material Exporters for TLS"
- E. Rescorla, RFC 5705 March 2010
- http://tools.ietf.org/html/rfc5705
-
- [RFC5929] "Channel Bindings for TLS"
- J. Altman, N. Williams, L. Zhu, RFC 5929, July 2010
- http://tools.ietf.org/html/rfc5929
-
- [RFC4680] "TLS Handshake Message for Supplemental Data"
- S. Santesson, RFC 4680, September 2006
- http://tools.ietf.org/html/rfc4680
-
- [RFC5878] "TLS Authorization Extension"
- M. Brown, R. Housley, RFC 5878, May 2010
- http://tools.ietf.org/html/rfc5878
-
- [RFC5746] "TLS Renegotiation Indication Extension"
- E. Rescorla, M. Raym, S. Dispensa, N. Oskov
- RFC 5746, February 2010
- http://tools.ietf.org/html/rfc5746
diff --git a/doc/man-sections/cipher-negotiation.rst b/doc/man-sections/cipher-negotiation.rst
deleted file mode 100644
index f143305..0000000
--- a/doc/man-sections/cipher-negotiation.rst
+++ /dev/null
@@ -1,96 +0,0 @@
-Data channel cipher negotiation
-===============================
-
-OpenVPN 2.4 and higher have the capability to negotiate the data cipher that
-is used to encrypt data packets. This section describes the mechanism in more detail and the
-different backwards compatibility mechanism with older server and clients.
-
-OpenVPN 2.5 and higher behaviour
---------------------------------
-When both client and server are at least running OpenVPN 2.5, that the order of
-the ciphers of the server's ``--data-ciphers`` is used to pick the the data cipher.
-That means that the first cipher in that list that is also in the client's
-``--data-ciphers`` list is chosen. If no common cipher is found the client is rejected
-with a AUTH_FAILED message (as seen in client log):
-
- AUTH: Received control message: AUTH_FAILED,Data channel cipher negotiation failed (no shared cipher)
-
-OpenVPN 2.5 will only allow the ciphers specified in ``--data-ciphers``. To ensure
-backwards compatibility also if a cipher is specified using the ``--cipher`` option
-it is automatically added to this list. If both options are unset the default is
-:code:`AES-256-GCM:AES-128-GCM`.
-
-OpenVPN 2.4 clients
--------------------
-The negotiation support in OpenVPN 2.4 was the first iteration of the implementation
-and still had some quirks. Its main goal was "upgrade to AES-256-GCM when possible".
-An OpenVPN 2.4 client that is built against a crypto library that supports AES in GCM
-mode and does not have ``--ncp-disable`` will always announce support for
-`AES-256-GCM` and `AES-128-GCM` to a server by sending :code:`IV_NCP=2`.
-
-This only causes a problem if ``--ncp-ciphers`` option has been changed from the
-default of :code:`AES-256-GCM:AES-128-GCM` to a value that does not include
-these two ciphers. When a OpenVPN servers try to use `AES-256-GCM` or
-`AES-128-GCM` the connection will then fail. It is therefore recommended to
-always have the `AES-256-GCM` and `AES-128-GCM` ciphers to the ``--ncp-ciphers``
-options to avoid this behaviour.
-
-OpenVPN 3 clients
------------------
-Clients based on the OpenVPN 3.x library (https://github.com/openvpn/openvpn3/)
-do not have a configurable ``--ncp-ciphers`` or ``--data-cipher`` option. Instead
-these clients will announce support for all their supported AEAD ciphers
-(`AES-256-GCM`, `AES-128-GCM` and in newer versions also `Chacha20-Poly1305`).
-
-To support OpenVPN 3.x based clients at least one of these ciphers needs to be
-included in the server's ``--data-ciphers`` option.
-
-
-OpenVPN 2.3 and older clients (and clients with ``--ncp-disable``)
-------------------------------------------------------------------
-When a client without cipher negotiation support connects to a server the
-cipher specified with the ``--cipher`` option in the client configuration
-must be included in the ``--data-ciphers`` option of the server to allow
-the client to connect. Otherwise the client will be sent the ``AUTH_FAILED``
-message that indicates no shared cipher.
-
-If the client is 2.3 or older and has been configured with the
-``--enable-small`` :code:`./configure` argument, using
-``data-ciphers-fallback cipher`` in the server config file with the explicit
-cipher used by the client is necessary.
-
-OpenVPN 2.4 server
-------------------
-When a client indicates support for `AES-128-GCM` and `AES-256-GCM`
-(with ``IV_NCP=2``) an OpenVPN 2.4 server will send the first
-cipher of the ``--ncp-ciphers`` to the OpenVPN client regardless of what
-the cipher is. To emulate the behaviour of an OpenVPN 2.4 client as close
-as possible and have compatibility to a setup that depends on this quirk,
-adding `AES-128-GCM` and `AES-256-GCM` to the client's ``--data-ciphers``
-option is required. OpenVPN 2.5+ will only announce the ``IV_NCP=2`` flag if
-those ciphers are present.
-
-OpenVPN 2.3 and older servers (and servers with ``--ncp-disable``)
-------------------------------------------------------------------
-The cipher used by the server must be included in ``--data-ciphers`` to
-allow the client connecting to a server without cipher negotiation
-support.
-(For compatibility OpenVPN 2.5 will also accept the cipher set with
-``--cipher``)
-
-If the server is 2.3 or older and has been configured with the
-``--enable-small`` :code:`./configure` argument, adding
-``data-ciphers-fallback cipher`` to the client config with the explicit
-cipher used by the server is necessary.
-
-Blowfish in CBC mode (BF-CBC) deprecation
-------------------------------------------
-The ``--cipher`` option defaulted to ``BF-CBC`` in OpenVPN 2.4 and older
-version. The default was never changed to ensure backwards compatibility.
-In OpenVPN 2.5 this behaviour has now been changed so that if the ``--cipher``
-is not explicitly set it does not allow the weak ``BF-CBC`` cipher any more
-and needs to explicitly added as ``--cipher BFC-CBC`` or added to
-``-data-ciphers``.
-
-We strongly recommend to switching away from BF-CBC to a
-more secure cipher as soon as possible instead.
diff --git a/doc/man-sections/vpn-network-options.rst b/doc/man-sections/vpn-network-options.rst
index 7100c1a..825dd1c 100644
--- a/doc/man-sections/vpn-network-options.rst
+++ b/doc/man-sections/vpn-network-options.rst
@@ -93,12 +93,18 @@ routing.
or :code:`tap`.
--dhcp-option args
- Set additional network settings via DHCP. On Windows, this is parsed by
- the ``tap-windows6`` or ``wintun`` driver. On other platforms these
- options can be picked up by an ``--up`` script or plug-in if it has been
- pushed by the OpenVPN server. The option will then be saved in the
- client's environment before the ``--up`` script is called, under the name
- :code:`foreign_option_{n}`.
+ Set additional network parameters on supported platforms. May be specified
+ on the client or pushed from the server. On Windows these options are
+ handled by the ``tap-windows6`` driver by default or directly by OpenVPN
+ if dhcp is disabled or the ``wintun`` driver is in use. The
+ ``OpenVPN for Android`` client also handles them internally.
+
+ On all other platforms these options are only saved in the client's
+ environment under the name :code:`foreign_options_{n}` before the
+ ``--up`` script is called. A plugin or an ``--up`` script must be used to
+ pick up and interpret these as required. Many Linux distributions include
+ such scripts and some third-party user interfaces such as tunnelblick also
+ come with scripts that process these options.
Valid syntax:
::
@@ -108,6 +114,11 @@ routing.
:code:`DOMAIN` ``name``
Set Connection-specific DNS Suffix to :code:`name`.
+ :code:`DOMAIN-SEARCH` ``name``
+ Add :code:`name` to the domain search list.
+ Repeat this option to add more entries. Up to
+ 10 domains are supported.
+
:code:`DNS` ``address``
Set primary domain name server IPv4 or IPv6 address.
Repeat this option to set secondary DNS server addresses.
diff --git a/doc/openvpn.8 b/doc/openvpn.8
new file mode 100644
index 0000000..b914f32
--- /dev/null
+++ b/doc/openvpn.8
@@ -0,0 +1,6954 @@
+.\" Man page generated from reStructuredText.
+.
+.TH OPENVPN 8 "" "" "System Manager's Manual"
+.SH NAME
+openvpn \- 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 SYNOPSIS
+.nf
+\fBopenvpn\fP [ options ... ]
+\fBopenvpn\fP \fB\-\-help\fP
+.fi
+.sp
+.SH INTRODUCTION
+.sp
+OpenVPN is an open source VPN daemon by James Yonan. Because OpenVPN
+tries to be a universal VPN tool offering a great deal of flexibility,
+there are a lot of options on this manual page. If you\(aqre new to
+OpenVPN, you might want to skip ahead to the examples section where you
+will see how to construct simple VPNs on the command line without even
+needing a configuration file.
+.sp
+Also note that there\(aqs more documentation and examples on the OpenVPN
+web site: \fI\%https://openvpn.net/\fP
+.sp
+And if you would like to see a shorter version of this manual, see the
+openvpn usage message which can be obtained by running \fBopenvpn\fP
+without any parameters.
+.SH DESCRIPTION
+.sp
+OpenVPN is a robust and highly flexible VPN daemon. OpenVPN supports
+SSL/TLS security, ethernet bridging, TCP or UDP tunnel transport through
+proxies or NAT, support for dynamic IP addresses and DHCP, scalability
+to hundreds or thousands of users, and portability to most major OS
+platforms.
+.sp
+OpenVPN is tightly bound to the OpenSSL library, and derives much of its
+crypto capabilities from it.
+.sp
+OpenVPN supports conventional encryption using a pre\-shared secret key
+\fB(Static Key mode)\fP or public key security \fB(SSL/TLS mode)\fP using
+client & server certificates. OpenVPN also supports non\-encrypted
+TCP/UDP tunnels.
+.sp
+OpenVPN is designed to work with the \fBTUN/TAP\fP virtual networking
+interface that exists on most platforms.
+.sp
+Overall, OpenVPN aims to offer many of the key features of IPSec but
+with a relatively lightweight footprint.
+.SH OPTIONS
+.sp
+OpenVPN allows any option to be placed either on the command line or in
+a configuration file. Though all command line options are preceded by a
+double\-leading\-dash ("\-\-"), this prefix can be removed when an option is
+placed in a configuration file.
+.SS Generic Options
+.sp
+This section covers generic options which are accessible regardless of
+which mode OpenVPN is configured as.
+.INDENT 0.0
+.TP
+.B \-\-help
+Show options.
+.TP
+.B \-\-auth\-nocache
+Don\(aqt cache \fB\-\-askpass\fP or \fB\-\-auth\-user\-pass\fP username/passwords in
+virtual memory.
+.sp
+If specified, this directive will cause OpenVPN to immediately forget
+username/password inputs after they are used. As a result, when OpenVPN
+needs a username/password, it will prompt for input from stdin, which
+may be multiple times during the duration of an OpenVPN session.
+.sp
+When using \fB\-\-auth\-nocache\fP in combination with a user/password file
+and \fB\-\-chroot\fP or \fB\-\-daemon\fP, make sure to use an absolute path.
+.sp
+This directive does not affect the \fB\-\-http\-proxy\fP username/password.
+It is always cached.
+.TP
+.BI \-\-cd \ dir
+Change directory to \fBdir\fP prior to reading any files such as
+configuration files, key files, scripts, etc. \fBdir\fP should be an
+absolute path, with a leading "/", and without any references to the
+current directory such as \fB\&.\fP or \fB\&..\fP\&.
+.sp
+This option is useful when you are running OpenVPN in \fB\-\-daemon\fP mode,
+and you want to consolidate all of your OpenVPN control files in one
+location.
+.TP
+.BI \-\-chroot \ dir
+Chroot to \fBdir\fP after initialization. \fB\-\-chroot\fP essentially
+redefines \fBdir\fP as being the top level directory tree (/). OpenVPN
+will therefore be unable to access any files outside this tree. This can
+be desirable from a security standpoint.
+.sp
+Since the chroot operation is delayed until after initialization, most
+OpenVPN options that reference files will operate in a pre\-chroot
+context.
+.sp
+In many cases, the \fBdir\fP parameter can point to an empty directory,
+however complications can result when scripts or restarts are executed
+after the chroot operation.
+.sp
+Note: The SSL library will probably need /dev/urandom to be available
+inside the chroot directory \fBdir\fP\&. This is because SSL libraries
+occasionally need to collect fresh random. Newer linux kernels and some
+BSDs implement a getrandom() or getentropy() syscall that removes the
+need for /dev/urandom to be available.
+.TP
+.BI \-\-config \ file
+Load additional config options from \fBfile\fP where each line corresponds
+to one command line option, but with the leading \(aq\-\-\(aq removed.
+.sp
+If \fB\-\-config file\fP is the only option to the openvpn command, the
+\fB\-\-config\fP can be removed, and the command can be given as \fBopenvpn
+file\fP
+.sp
+Note that configuration files can be nested to a reasonable depth.
+.sp
+Double quotation or single quotation characters ("", \(aq\(aq) can be used to
+enclose single parameters containing whitespace, and "#" or ";"
+characters in the first column can be used to denote comments.
+.sp
+Note that OpenVPN 2.0 and higher performs backslash\-based shell escaping
+for characters not in single quotations, so the following mappings
+should be observed:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+\e\e Maps to a single backslash character (\e).
+\e" Pass a literal doublequote character ("), don\(aqt
+ interpret it as enclosing a parameter.
+\e[SPACE] Pass a literal space or tab character, don\(aqt
+ interpret it as a parameter delimiter.
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+For example on Windows, use double backslashes to represent pathnames:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+secret "c:\e\eOpenVPN\e\esecret.key"
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+For examples of configuration files, see
+\fI\%https://openvpn.net/community\-resources/how\-to/\fP
+.sp
+Here is an example configuration file:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+#
+# Sample OpenVPN configuration file for
+# using a pre\-shared static key.
+#
+# \(aq#\(aq or \(aq;\(aq may be used to delimit comments.
+
+# Use a dynamic tun device.
+dev tun
+
+# Our remote peer
+remote mypeer.mydomain
+
+# 10.1.0.1 is our local VPN endpoint
+# 10.1.0.2 is our remote VPN endpoint
+ifconfig 10.1.0.1 10.1.0.2
+
+# Our pre\-shared static key
+secret static.key
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.TP
+.BI \-\-daemon \ progname
+Become a daemon after all initialization functions are completed. This
+option will cause all message and error output to be sent to the syslog
+file (such as \fB/var/log/messages\fP), except for the output of
+scripts and ifconfig commands, which will go to \fB/dev/null\fP unless
+otherwise redirected. The syslog redirection occurs immediately at the
+point that \fB\-\-daemon\fP is parsed on the command line even though the
+daemonization point occurs later. If one of the \fB\-\-log\fP options is
+present, it will supersede syslog redirection.
+.sp
+The optional \fBprogname\fP parameter will cause OpenVPN to report its
+program name to the system logger as \fBprogname\fP\&. This can be useful in
+linking OpenVPN messages in the syslog file with specific tunnels. When
+unspecified, \fBprogname\fP defaults to "openvpn".
+.sp
+When OpenVPN is run with the \fB\-\-daemon\fP option, it will try to delay
+daemonization until the majority of initialization functions which are
+capable of generating fatal errors are complete. This means that
+initialization scripts can test the return status of the openvpn command
+for a fairly reliable indication of whether the command has correctly
+initialized and entered the packet forwarding event loop.
+.sp
+In OpenVPN, the vast majority of errors which occur after initialization
+are non\-fatal.
+.sp
+Note: as soon as OpenVPN has daemonized, it can not ask for usernames,
+passwords, or key pass phrases anymore. This has certain consequences,
+namely that using a password\-protected private key will fail unless the
+\fB\-\-askpass\fP option is used to tell OpenVPN to ask for the pass phrase
+(this requirement is new in v2.3.7, and is a consequence of calling
+daemon() before initializing the crypto layer).
+.sp
+Further, using \fB\-\-daemon\fP together with \fB\-\-auth\-user\-pass\fP (entered
+on console) and \fB\-\-auth\-nocache\fP will fail as soon as key
+renegotiation (and reauthentication) occurs.
+.TP
+.B \-\-disable\-occ
+Don\(aqt output a warning message if option inconsistencies are detected
+between peers. An example of an option inconsistency would be where one
+peer uses \fB\-\-dev tun\fP while the other peer uses \fB\-\-dev tap\fP\&.
+.sp
+Use of this option is discouraged, but is provided as a temporary fix in
+situations where a recent version of OpenVPN must connect to an old
+version.
+.TP
+.BI \-\-engine \ engine\-name
+Enable OpenSSL hardware\-based crypto engine functionality.
+.sp
+If \fBengine\-name\fP is specified, use a specific crypto engine. Use the
+\fB\-\-show\-engines\fP standalone option to list the crypto engines which
+are supported by OpenSSL.
+.TP
+.B \-\-fast\-io
+(Experimental) Optimize TUN/TAP/UDP I/O writes by avoiding a call to
+poll/epoll/select prior to the write operation. The purpose of such a
+call would normally be to block until the device or socket is ready to
+accept the write. Such blocking is unnecessary on some platforms which
+don\(aqt support write blocking on UDP sockets or TUN/TAP devices. In such
+cases, one can optimize the event loop by avoiding the poll/epoll/select
+call, improving CPU efficiency by 5% to 10%.
+.sp
+This option can only be used on non\-Windows systems, when \fB\-\-proto
+udp\fP is specified, and when \fB\-\-shaper\fP is NOT specified.
+.TP
+.BI \-\-group \ group
+Similar to the \fB\-\-user\fP option, this option changes the group ID of
+the OpenVPN process to \fBgroup\fP after initialization.
+.TP
+.BI \-\-ignore\-unknown\-option \ args
+Valid syntax:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+ignore\-unknown\-options opt1 opt2 opt3 ... optN
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+When one of options \fBopt1 ... optN\fP is encountered in the configuration
+file the configuration file parsing does not fail if this OpenVPN version
+does not support the option. Multiple \fB\-\-ignore\-unknown\-option\fP options
+can be given to support a larger number of options to ignore.
+.sp
+This option should be used with caution, as there are good security
+reasons for having OpenVPN fail if it detects problems in a config file.
+Having said that, there are valid reasons for wanting new software
+features to gracefully degrade when encountered by older software
+versions.
+.sp
+\fB\-\-ignore\-unknown\-option\fP is available since OpenVPN 2.3.3.
+.TP
+.BI \-\-iproute \ cmd
+Set alternate command to execute instead of default \fBiproute2\fP command.
+May be used in order to execute OpenVPN in unprivileged environment.
+.TP
+.BI \-\-keying\-material\-exporter \ args
+Save Exported Keying Material [RFC5705] of len bytes (must be between 16
+and 4095 bytes) using \fBlabel\fP in environment
+(\fBexported_keying_material\fP) for use by plugins in
+\fBOPENVPN_PLUGIN_TLS_FINAL\fP callback.
+.sp
+Valid syntax:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+keying\-material\-exporter label len
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Note that exporter \fBlabels\fP have the potential to collide with existing
+PRF labels. In order to prevent this, labels \fIMUST\fP begin with
+\fBEXPORTER\fP\&.
+.TP
+.B \-\-mlock
+Disable paging by calling the POSIX mlockall function. Requires that
+OpenVPN be initially run as root (though OpenVPN can subsequently
+downgrade its UID using the \fB\-\-user\fP option).
+.sp
+Using this option ensures that key material and tunnel data are never
+written to disk due to virtual memory paging operations which occur
+under most modern operating systems. It ensures that even if an attacker
+was able to crack the box running OpenVPN, he would not be able to scan
+the system swap file to recover previously used ephemeral keys, which
+are used for a period of time governed by the \fB\-\-reneg\fP options (see
+below), then are discarded.
+.sp
+The downside of using \fB\-\-mlock\fP is that it will reduce the amount of
+physical memory available to other applications.
+.TP
+.BI \-\-nice \ n
+Change process priority after initialization (\fBn\fP greater than 0 is
+lower priority, \fBn\fP less than zero is higher priority).
+.TP
+.B \-\-persist\-key
+Don\(aqt re\-read key files across \fBSIGUSR1\fP or \fB\-\-ping\-restart\fP\&.
+.sp
+This option can be combined with \fB\-\-user nobody\fP to allow restarts
+triggered by the \fBSIGUSR1\fP signal. Normally if you drop root
+privileges in OpenVPN, the daemon cannot be restarted since it will now
+be unable to re\-read protected key files.
+.sp
+This option solves the problem by persisting keys across \fBSIGUSR1\fP
+resets, so they don\(aqt need to be re\-read.
+.TP
+.BI \-\-remap\-usr1 \ signal
+Control whether internally or externally generated \fBSIGUSR1\fP signals
+are remapped to \fBSIGHUP\fP (restart without persisting state) or
+SIGTERM (exit).
+.sp
+\fBsignal\fP can be set to \fBSIGHUP\fP or \fBSIGTERM\fP\&. By default,
+no remapping occurs.
+.TP
+.BI \-\-script\-security \ level
+This directive offers policy\-level control over OpenVPN\(aqs usage of
+external programs and scripts. Lower \fBlevel\fP values are more
+restrictive, higher values are more permissive. Settings for \fBlevel\fP:
+.INDENT 7.0
+.TP
+.B \fB0\fP
+Strictly no calling of external programs.
+.TP
+.B \fB1\fP
+(Default) Only call built\-in executables such as ifconfig,
+ip, route, or netsh.
+.TP
+.B \fB2\fP
+Allow calling of built\-in executables and user\-defined
+scripts.
+.TP
+.B \fB3\fP
+Allow passwords to be passed to scripts via environmental
+variables (potentially unsafe).
+.UNINDENT
+.sp
+OpenVPN releases before v2.3 also supported a \fBmethod\fP flag which
+indicated how OpenVPN should call external commands and scripts. This
+could be either \fBexecve\fP or \fBsystem\fP\&. As of OpenVPN 2.3, this
+flag is no longer accepted. In most *nix environments the execve()
+approach has been used without any issues.
+.sp
+Some directives such as \fB\-\-up\fP allow options to be passed to the
+external script. In these cases make sure the script name does not
+contain any spaces or the configuration parser will choke because it
+can\(aqt determine where the script name ends and script options start.
+.sp
+To run scripts in Windows in earlier OpenVPN versions you needed to
+either add a full path to the script interpreter which can parse the
+script or use the \fBsystem\fP flag to run these scripts. As of OpenVPN
+2.3 it is now a strict requirement to have full path to the script
+interpreter when running non\-executables files. This is not needed for
+executable files, such as .exe, .com, .bat or .cmd files. For example,
+if you have a Visual Basic script, you must use this syntax now:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+\-\-up \(aqC:\e\eWindows\e\eSystem32\e\ewscript.exe C:\e\eProgram\e Files\e\eOpenVPN\e\econfig\e\emy\-up\-script.vbs\(aq
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Please note the single quote marks and the escaping of the backslashes
+(\e) and the space character.
+.sp
+The reason the support for the \fBsystem\fP flag was removed is due to
+the security implications with shell expansions when executing scripts
+via the \fBsystem()\fP call.
+.TP
+.BI \-\-setcon \ context
+Apply SELinux \fBcontext\fP after initialization. This essentially
+provides the ability to restrict OpenVPN\(aqs rights to only network I/O
+operations, thanks to SELinux. This goes further than \fB\-\-user\fP and
+\fB\-\-chroot\fP in that those two, while being great security features,
+unfortunately do not protect against privilege escalation by
+exploitation of a vulnerable system call. You can of course combine all
+three, but please note that since setcon requires access to /proc you
+will have to provide it inside the chroot directory (e.g. with mount
+\-\-bind).
+.sp
+Since the setcon operation is delayed until after initialization,
+OpenVPN can be restricted to just network\-related system calls, whereas
+by applying the context before startup (such as the OpenVPN one provided
+in the SELinux Reference Policies) you will have to allow many things
+required only during initialization.
+.sp
+Like with chroot, complications can result when scripts or restarts are
+executed after the setcon operation, which is why you should really
+consider using the \fB\-\-persist\-key\fP and \fB\-\-persist\-tun\fP options.
+.TP
+.BI \-\-status \ args
+Write operational status to \fBfile\fP every \fBn\fP seconds.
+.sp
+Valid syntaxes:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+status file
+status file n
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Status can also be written to the syslog by sending a \fBSIGUSR2\fP
+signal.
+.sp
+With multi\-client capability enabled on a server, the status file
+includes a list of clients and a routing table. The output format can be
+controlled by the \fB\-\-status\-version\fP option in that case.
+.sp
+For clients or instances running in point\-to\-point mode, it will contain
+the traffic statistics.
+.TP
+.BI \-\-status\-version \ n
+Set the status file format version number to \fBn\fP\&.
+.sp
+This only affects the status file on servers with multi\-client
+capability enabled. Valid status version values:
+.INDENT 7.0
+.TP
+.B \fB1\fP
+Traditional format (default). The client list contains the
+following fields comma\-separated: Common Name, Real Address, Bytes
+Received, Bytes Sent, Connected Since.
+.TP
+.B \fB2\fP
+A more reliable format for external processing. Compared to
+version \fB1\fP, the client list contains some additional fields:
+Virtual Address, Virtual IPv6 Address, Username, Client ID, Peer ID,
+Data Channel Cipher. Future versions may extend the number of fields.
+.TP
+.B \fB3\fP
+Identical to \fB2\fP, but fields are tab\-separated.
+.UNINDENT
+.TP
+.B \-\-test\-crypto
+Do a self\-test of OpenVPN\(aqs crypto options by encrypting and decrypting
+test packets using the data channel encryption options specified above.
+This option does not require a peer to function, and therefore can be
+specified without \fB\-\-dev\fP or \fB\-\-remote\fP\&.
+.sp
+The typical usage of \fB\-\-test\-crypto\fP would be something like this:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+openvpn \-\-test\-crypto \-\-secret key
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+or
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+openvpn \-\-test\-crypto \-\-secret key \-\-verb 9
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+This option is very useful to test OpenVPN after it has been ported to a
+new platform, or to isolate problems in the compiler, OpenSSL crypto
+library, or OpenVPN\(aqs crypto code. Since it is a self\-test mode,
+problems with encryption and authentication can be debugged
+independently of network and tunnel issues.
+.TP
+.BI \-\-tmp\-dir \ dir
+Specify a directory \fBdir\fP for temporary files. This directory will be
+used by openvpn processes and script to communicate temporary data with
+openvpn main process. Note that the directory must be writable by the
+OpenVPN process after it has dropped it\(aqs root privileges.
+.sp
+This directory will be used by in the following cases:
+.INDENT 7.0
+.IP \(bu 2
+\fB\-\-client\-connect\fP scripts and \fBOPENVPN_PLUGIN_CLIENT_CONNECT\fP
+plug\-in hook to dynamically generate client\-specific configuration
+\fBclient_connect_config_file\fP and return success/failure via
+\fBclient_connect_deferred_file\fP when using deferred client connect
+method
+.IP \(bu 2
+\fBOPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY\fP plug\-in hooks returns
+success/failure via \fBauth_control_file\fP when using deferred auth
+method
+.IP \(bu 2
+\fBOPENVPN_PLUGIN_ENABLE_PF\fP plugin hook to pass filtering rules
+via \fBpf_file\fP
+.UNINDENT
+.TP
+.B \-\-use\-prediction\-resistance
+Enable prediction resistance on mbed TLS\(aqs RNG.
+.sp
+Enabling prediction resistance causes the RNG to reseed in each call for
+random. Reseeding this often can quickly deplete the kernel entropy
+pool.
+.sp
+If you need this option, please consider running a daemon that adds
+entropy to the kernel pool.
+.TP
+.BI \-\-user \ user
+Change the user ID of the OpenVPN process to \fBuser\fP after
+initialization, dropping privileges in the process. This option is
+useful to protect the system in the event that some hostile party was
+able to gain control of an OpenVPN session. Though OpenVPN\(aqs security
+features make this unlikely, it is provided as a second line of defense.
+.sp
+By setting \fBuser\fP to \fBnobody\fP or somebody similarly unprivileged,
+the hostile party would be limited in what damage they could cause. Of
+course once you take away privileges, you cannot return them to an
+OpenVPN session. This means, for example, that if you want to reset an
+OpenVPN daemon with a \fBSIGUSR1\fP signal (for example in response to
+a DHCP reset), you should make use of one or more of the \fB\-\-persist\fP
+options to ensure that OpenVPN doesn\(aqt need to execute any privileged
+operations in order to restart (such as re\-reading key files or running
+\fBifconfig\fP on the TUN device).
+.TP
+.BI \-\-writepid \ file
+Write OpenVPN\(aqs main process ID to \fBfile\fP\&.
+.UNINDENT
+.SS Log options
+.INDENT 0.0
+.TP
+.BI \-\-echo \ parms
+Echo \fBparms\fP to log output.
+.sp
+Designed to be used to send messages to a controlling application which
+is receiving the OpenVPN log output.
+.TP
+.B \-\-errors\-to\-stderr
+Output errors to stderr instead of stdout unless log output is
+redirected by one of the \fB\-\-log\fP options.
+.TP
+.BI \-\-log \ file
+Output logging messages to \fBfile\fP, including output to stdout/stderr
+which is generated by called scripts. If \fBfile\fP already exists it will
+be truncated. This option takes effect immediately when it is parsed in
+the command line and will supersede syslog output if \fB\-\-daemon\fP or
+\fB\-\-inetd\fP is also specified. This option is persistent over the entire
+course of an OpenVPN instantiation and will not be reset by
+\fBSIGHUP\fP, \fBSIGUSR1\fP, or \fB\-\-ping\-restart\fP\&.
+.sp
+Note that on Windows, when OpenVPN is started as a service, logging
+occurs by default without the need to specify this option.
+.TP
+.BI \-\-log\-append \ file
+Append logging messages to \fBfile\fP\&. If \fBfile\fP does not exist, it will
+be created. This option behaves exactly like \fB\-\-log\fP except that it
+appends to rather than truncating the log file.
+.TP
+.B \-\-machine\-readable\-output
+Always write timestamps and message flags to log messages, even when
+they otherwise would not be prefixed. In particular, this applies to log
+messages sent to stdout.
+.TP
+.BI \-\-mute \ n
+Log at most \fBn\fP consecutive messages in the same category. This is
+useful to limit repetitive logging of similar message types.
+.TP
+.B \-\-mute\-replay\-warnings
+Silence the output of replay warnings, which are a common false alarm on
+WiFi networks. This option preserves the security of the replay
+protection code without the verbosity associated with warnings about
+duplicate packets.
+.TP
+.B \-\-suppress\-timestamps
+Avoid writing timestamps to log messages, even when they otherwise would
+be prepended. In particular, this applies to log messages sent to
+stdout.
+.TP
+.BI \-\-syslog \ progname
+Direct log output to system logger, but do not become a daemon. See
+\fB\-\-daemon\fP directive above for description of \fBprogname\fP parameter.
+.TP
+.BI \-\-verb \ n
+Set output verbosity to \fBn\fP (default \fB1\fP). Each level shows all
+info from the previous levels. Level \fB3\fP is recommended if you want
+a good summary of what\(aqs happening without being swamped by output.
+.INDENT 7.0
+.TP
+.B \fB0\fP
+No output except fatal errors.
+.TP
+.B \fB1\fP to \fB4\fP
+Normal usage range.
+.TP
+.B \fB5\fP
+Outputs \fBR\fP and \fBW\fP characters to the console for
+each packet read and write, uppercase is used for TCP/UDP
+packets and lowercase is used for TUN/TAP packets.
+.TP
+.B \fB6\fP to \fB11\fP
+Debug info range (see \fBerrlevel.h\fP in the source code for
+additional information on debug levels).
+.UNINDENT
+.UNINDENT
+.SS Protocol options
+.sp
+Options in this section affect features available in the OpenVPN wire
+protocol. Many of these options also define the encryption options
+of the data channel in the OpenVPN wire protocol. These options must be
+configured in a compatible way between both the local and remote side.
+.INDENT 0.0
+.TP
+.BI \-\-allow\-compression \ mode
+As described in the \fB\-\-compress\fP option, compression is a potentially
+dangerous option. This option allows controlling the behaviour of
+OpenVPN when compression is used and allowed.
+.sp
+Valid syntaxes:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+allow\-compression
+allow\-compression mode
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The \fBmode\fP argument can be one of the following values:
+.INDENT 7.0
+.TP
+.B \fBasym\fP (default)
+OpenVPN will only \fIdecompress downlink packets\fP but \fInot compress
+uplink packets\fP\&. This also allows migrating to disable compression
+when changing both server and client configurations to remove
+compression at the same time is not a feasible option.
+.TP
+.B \fBno\fP
+OpenVPN will refuse any non\-stub compression.
+.TP
+.B \fByes\fP
+OpenVPN will send and receive compressed packets.
+.UNINDENT
+.TP
+.BI \-\-auth \ alg
+Authenticate data channel packets and (if enabled) \fBtls\-auth\fP control
+channel packets with HMAC using message digest algorithm \fBalg\fP\&. (The
+default is \fBSHA1\fP ). HMAC is a commonly used message authentication
+algorithm (MAC) that uses a data string, a secure hash algorithm and a
+key to produce a digital signature.
+.sp
+The OpenVPN data channel protocol uses encrypt\-then\-mac (i.e. first
+encrypt a packet then HMAC the resulting ciphertext), which prevents
+padding oracle attacks.
+.sp
+If an AEAD cipher mode (e.g. GCM) is chosen then the specified \fB\-\-auth\fP
+algorithm is ignored for the data channel and the authentication method
+of the AEAD cipher is used instead. Note that \fBalg\fP still specifies
+the digest used for \fBtls\-auth\fP\&.
+.sp
+In static\-key encryption mode, the HMAC key is included in the key file
+generated by \fB\-\-genkey\fP\&. In TLS mode, the HMAC key is dynamically
+generated and shared between peers via the TLS control channel. If
+OpenVPN receives a packet with a bad HMAC it will drop the packet. HMAC
+usually adds 16 or 20 bytes per packet. Set \fBalg=none\fP to disable
+authentication.
+.sp
+For more information on HMAC see
+\fI\%http://www.cs.ucsd.edu/users/mihir/papers/hmac.html\fP
+.TP
+.BI \-\-cipher \ alg
+This option is deprecated for server\-client mode. \fB\-\-data\-ciphers\fP
+or possibly \fI\-\-data\-ciphers\-fallback\(ga\fP should be used instead.
+.sp
+Encrypt data channel packets with cipher algorithm \fBalg\fP\&.
+.sp
+The default is \fBBF\-CBC\fP, an abbreviation for Blowfish in Cipher
+Block Chaining mode. When cipher negotiation (NCP) is allowed,
+OpenVPN 2.4 and newer on both client and server side will automatically
+upgrade to \fBAES\-256\-GCM\fP\&. See \fB\-\-data\-ciphers\fP and
+\fB\-\-ncp\-disable\fP for more details on NCP.
+.sp
+Using \fBBF\-CBC\fP is no longer recommended, because of its 64\-bit
+block size. This small block size allows attacks based on collisions, as
+demonstrated by SWEET32. See
+\fI\%https://community.openvpn.net/openvpn/wiki/SWEET32\fP
+for details. Due to this, support for \fBBF\-CBC\fP, \fBDES\fP,
+\fBCAST5\fP, \fBIDEA\fP and \fBRC2\fP ciphers will be removed in
+OpenVPN 2.6.
+.sp
+To see other ciphers that are available with OpenVPN, use the
+\fB\-\-show\-ciphers\fP option.
+.sp
+Set \fBalg\fP to \fBnone\fP to disable encryption.
+.TP
+.BI \-\-compress \ algorithm
+\fBDEPRECATED\fP Enable a compression algorithm. Compression is generally
+not recommended. VPN tunnels which use compression are susceptible to
+the VORALCE attack vector.
+.sp
+The \fBalgorithm\fP parameter may be \fBlzo\fP, \fBlz4\fP,
+\fBlz4\-v2\fP, \fBstub\fP, \fBstub\-v2\fP or empty.
+LZO and LZ4 are different compression algorithms, with LZ4 generally
+offering the best performance with least CPU usage.
+.sp
+The \fBlz4\-v2\fP and \fBstub\-v2\fP variants implement a better
+framing that does not add overhead when packets cannot be compressed. All
+other variants always add one extra framing byte compared to no
+compression framing.
+.sp
+If the \fBalgorithm\fP parameter is \fBstub\fP, \fBstub\-v2\fP or empty,
+compression will be turned off, but the packet framing for compression
+will still be enabled, allowing a different setting to be pushed later.
+Additionally, \fBstub\fP and \fBstub\-v2\fP wil disable announcing
+\fBlzo\fP and \fBlz4\fP compression support via \fIIV_\fP variables to the
+server.
+.sp
+Note: the \fBstub\fP (or empty) option is NOT compatible with the older
+option \fB\-\-comp\-lzo no\fP\&.
+.sp
+\fB*Security Considerations*\fP
+.sp
+Compression and encryption is a tricky combination. If an attacker knows
+or is able to control (parts of) the plain\-text of packets that contain
+secrets, the attacker might be able to extract the secret if compression
+is enabled. See e.g. the \fICRIME\fP and \fIBREACH\fP attacks on TLS and
+\fIVORACLE\fP on VPNs which also leverage to break encryption. If you are not
+entirely sure that the above does not apply to your traffic, you are
+advised to \fInot\fP enable compression.
+.TP
+.BI \-\-comp\-lzo \ mode
+\fBDEPRECATED\fP Enable LZO compression algorithm. Compression is
+generally not recommended. VPN tunnels which uses compression are
+suspectible to the VORALCE attack vector.
+.sp
+Use LZO compression \-\- may add up to 1 byte per packet for incompressible
+data. \fBmode\fP may be \fByes\fP, \fBno\fP, or \fBadaptive\fP
+(default).
+.sp
+In a server mode setup, it is possible to selectively turn compression
+on or off for individual clients.
+.sp
+First, make sure the client\-side config file enables selective
+compression by having at least one \fB\-\-comp\-lzo\fP directive, such as
+\fB\-\-comp\-lzo no\fP\&. This will turn off compression by default, but allow
+a future directive push from the server to dynamically change the
+\fBon\fP/\fBoff\fP/\fBadaptive\fP setting.
+.sp
+Next in a \fB\-\-client\-config\-dir\fP file, specify the compression setting
+for the client, for example:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+comp\-lzo yes
+push "comp\-lzo yes"
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The first line sets the \fBcomp\-lzo\fP setting for the server side of the
+link, the second sets the client side.
+.TP
+.B \-\-comp\-noadapt
+\fBDEPRECATED\fP When used in conjunction with \fB\-\-comp\-lzo\fP, this option
+will disable OpenVPN\(aqs adaptive compression algorithm. Normally, adaptive
+compression is enabled with \fB\-\-comp\-lzo\fP\&.
+.sp
+Adaptive compression tries to optimize the case where you have
+compression enabled, but you are sending predominantly incompressible
+(or pre\-compressed) packets over the tunnel, such as an FTP or rsync
+transfer of a large, compressed file. With adaptive compression, OpenVPN
+will periodically sample the compression process to measure its
+efficiency. If the data being sent over the tunnel is already
+compressed, the compression efficiency will be very low, triggering
+openvpn to disable compression for a period of time until the next
+re\-sample test.
+.TP
+.B \-\-key\-direction
+Alternative way of specifying the optional direction parameter for the
+\fB\-\-tls\-auth\fP and \fB\-\-secret\fP options. Useful when using inline files
+(See section on inline files).
+.TP
+.BI \-\-keysize \ n
+\fBDEPRECATED\fP This option will be removed in OpenVPN 2.6.
+.sp
+Size of cipher key in bits (optional). If unspecified, defaults to
+cipher\-specific default. The \fB\-\-show\-ciphers\fP option (see below) shows
+all available OpenSSL ciphers, their default key sizes, and whether the
+key size can be changed. Use care in changing a cipher\(aqs default key
+size. Many ciphers have not been extensively cryptanalyzed with
+non\-standard key lengths, and a larger key may offer no real guarantee
+of greater security, or may even reduce security.
+.TP
+.BI \-\-data\-ciphers \ cipher\-list
+Restrict the allowed ciphers to be negotiated to the ciphers in
+\fBcipher\-list\fP\&. \fBcipher\-list\fP is a colon\-separated list of ciphers,
+and defaults to \fBAES\-256\-GCM:AES\-128\-GCM\fP\&.
+.sp
+For servers, the first cipher from \fBcipher\-list\fP that is also
+supported by the client will be pushed to clients that support cipher
+negotiation.
+.sp
+Cipher negotiation is enabled in client\-server mode only. I.e. if
+\fB\-\-mode\fP is set to \(aqserver\(aq (server\-side, implied by setting
+\fB\-\-server\fP ), or if \fB\-\-pull\fP is specified (client\-side, implied by
+setting \-\-client).
+.sp
+If no common cipher is found during cipher negotiation, the connection
+is terminated. To support old clients/old servers that do not provide any
+cipher negotiation support see \fB\-\-data\-ciphers\-fallback\fP\&.
+.sp
+Additionally, to allow for more smooth transition, if NCP is enabled,
+OpenVPN will inherit the cipher of the peer if that cipher is different
+from the local \fB\-\-cipher\fP setting, but the peer cipher is one of the
+ciphers specified in \fB\-\-data\-ciphers\fP\&. E.g. a non\-NCP client (<=v2.3,
+or with \-\-ncp\-disabled set) connecting to a NCP server (v2.4+) with
+\fB\-\-cipher BF\-CBC\fP and \fB\-\-data\-ciphers AES\-256\-GCM:AES\-256\-CBC\fP set can
+either specify \fB\-\-cipher BF\-CBC\fP or \fB\-\-cipher AES\-256\-CBC\fP and both
+will work.
+.sp
+Note for using NCP with an OpenVPN 2.4 peer: This list must include the
+\fBAES\-256\-GCM\fP and \fBAES\-128\-GCM\fP ciphers.
+.sp
+This list is restricted to be 127 chars long after conversion to OpenVPN
+ciphers.
+.sp
+This option was called \fB\-\-ncp\-ciphers\fP in OpenVPN 2.4 but has been renamed
+to \fB\-\-data\-ciphers\fP in OpenVPN 2.5 to more accurately reflect its meaning.
+.TP
+.BI \-\-data\-ciphers\-fallback \ alg
+Configure a cipher that is used to fall back to if we could not determine
+which cipher the peer is willing to use.
+.sp
+This option should only be needed to
+connect to peers that are running OpenVPN 2.3 and older version, and
+have been configured with \fI\-\-enable\-small\fP
+(typically used on routers or other embedded devices).
+.TP
+.B \-\-ncp\-disable
+\fBDEPRECATED\fP Disable "Negotiable Crypto Parameters". This completely
+disables cipher negotiation.
+.TP
+.BI \-\-secret \ args
+Enable Static Key encryption mode (non\-TLS). Use pre\-shared secret
+\fBfile\fP which was generated with \fB\-\-genkey\fP\&.
+.sp
+Valid syntaxes:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+secret file
+secret file direction
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The optional \fBdirection\fP parameter enables the use of 4 distinct keys
+(HMAC\-send, cipher\-encrypt, HMAC\-receive, cipher\-decrypt), so that each
+data flow direction has a different set of HMAC and cipher keys. This
+has a number of desirable security properties including eliminating
+certain kinds of DoS and message replay attacks.
+.sp
+When the \fBdirection\fP parameter is omitted, 2 keys are used
+bidirectionally, one for HMAC and the other for encryption/decryption.
+.sp
+The \fBdirection\fP parameter should always be complementary on either
+side of the connection, i.e. one side should use \fB0\fP and the other
+should use \fB1\fP, or both sides should omit it altogether.
+.sp
+The \fBdirection\fP parameter requires that \fBfile\fP contains a 2048 bit
+key. While pre\-1.5 versions of OpenVPN generate 1024 bit key files, any
+version of OpenVPN which supports the \fBdirection\fP parameter, will also
+support 2048 bit key file generation using the \fB\-\-genkey\fP option.
+.sp
+Static key encryption mode has certain advantages, the primary being
+ease of configuration.
+.sp
+There are no certificates or certificate authorities or complicated
+negotiation handshakes and protocols. The only requirement is that you
+have a pre\-existing secure channel with your peer (such as \fBssh\fP) to
+initially copy the key. This requirement, along with the fact that your
+key never changes unless you manually generate a new one, makes it
+somewhat less secure than TLS mode (see below). If an attacker manages
+to steal your key, everything that was ever encrypted with it is
+compromised. Contrast that to the perfect forward secrecy features of
+TLS mode (using Diffie Hellman key exchange), where even if an attacker
+was able to steal your private key, he would gain no information to help
+him decrypt past sessions.
+.sp
+Another advantageous aspect of Static Key encryption mode is that it is
+a handshake\-free protocol without any distinguishing signature or
+feature (such as a header or protocol handshake sequence) that would
+mark the ciphertext packets as being generated by OpenVPN. Anyone
+eavesdropping on the wire would see nothing but random\-looking data.
+.TP
+.BI \-\-tran\-window \ n
+Transition window \-\- our old key can live this many seconds after a new
+a key renegotiation begins (default \fB3600\fP seconds). This feature
+allows for a graceful transition from old to new key, and removes the key
+renegotiation sequence from the critical path of tunnel data forwarding.
+.UNINDENT
+.SS Client Options
+.sp
+The client options are used when connecting to an OpenVPN server configured
+to use \fB\-\-server\fP, \fB\-\-server\-bridge\fP, or \fB\-\-mode server\fP in its
+configuration.
+.INDENT 0.0
+.TP
+.B \-\-allow\-pull\-fqdn
+Allow client to pull DNS names from server (rather than being limited to
+IP address) for \fB\-\-ifconfig\fP, \fB\-\-route\fP, and \fB\-\-route\-gateway\fP\&.
+.TP
+.B \-\-allow\-recursive\-routing
+When this option is set, OpenVPN will not drop incoming tun packets with
+same destination as host.
+.TP
+.BI \-\-auth\-token \ token
+This is not an option to be used directly in any configuration files,
+but rather push this option from a \fB\-\-client\-connect\fP script or a
+\fB\-\-plugin\fP which hooks into the \fBOPENVPN_PLUGIN_CLIENT_CONNECT\fP
+or \fBOPENVPN_PLUGIN_CLIENT_CONNECT_V2\fP calls. This option provides a
+possibility to replace the clients password with an authentication token
+during the lifetime of the OpenVPN client.
+.sp
+Whenever the connection is renegotiated and the
+\fB\-\-auth\-user\-pass\-verify\fP script or \fB\-\-plugin\fP making use of the
+\fBOPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY\fP hook is triggered, it will
+pass over this token as the password instead of the password the user
+provided. The authentication token can only be reset by a full reconnect
+where the server can push new options to the client. The password the
+user entered is never preserved once an authentication token has been
+set. If the OpenVPN server side rejects the authentication token then
+the client will receive an \fBAUTH_FAILED\fP and disconnect.
+.sp
+The purpose of this is to enable two factor authentication methods, such
+as HOTP or TOTP, to be used without needing to retrieve a new OTP code
+each time the connection is renegotiated. Another use case is to cache
+authentication data on the client without needing to have the users
+password cached in memory during the life time of the session.
+.sp
+To make use of this feature, the \fB\-\-client\-connect\fP script or
+\fB\-\-plugin\fP needs to put
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+push "auth\-token UNIQUE_TOKEN_VALUE"
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+into the file/buffer for dynamic configuration data. This will then make
+the OpenVPN server to push this value to the client, which replaces the
+local password with the \fBUNIQUE_TOKEN_VALUE\fP\&.
+.sp
+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
+.B \-\-auth\-user\-pass
+Authenticate with server using username/password.
+.sp
+Valid syntaxes:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+auth\-user\-pass
+auth\-user\-pass up
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+If \fBup\fP is present, it must be a file containing username/password on 2
+lines. If the password line is missing, OpenVPN will prompt for one.
+.sp
+If \fBup\fP is omitted, username/password will be prompted from the
+console.
+.sp
+The server configuration must specify an \fB\-\-auth\-user\-pass\-verify\fP
+script to verify the username/password provided by the client.
+.TP
+.BI \-\-auth\-retry \ type
+Controls how OpenVPN responds to username/password verification errors
+such as the client\-side response to an \fBAUTH_FAILED\fP message from
+the server or verification failure of the private key password.
+.sp
+Normally used to prevent auth errors from being fatal on the client
+side, and to permit username/password requeries in case of error.
+.sp
+An \fBAUTH_FAILED\fP message is generated by the server if the client
+fails \fB\-\-auth\-user\-pass\fP authentication, or if the server\-side
+\fB\-\-client\-connect\fP script returns an error status when the client
+tries to connect.
+.sp
+\fBtype\fP can be one of:
+.INDENT 7.0
+.TP
+.B \fBnone\fP
+Client will exit with a fatal error (this is the default).
+.TP
+.B \fBnointeract\fP
+Client will retry the connection without requerying
+for an \fB\-\-auth\-user\-pass\fP username/password. Use this option for
+unattended clients.
+.TP
+.B \fBinteract\fP
+Client will requery for an \fB\-\-auth\-user\-pass\fP
+username/password and/or private key password before attempting a
+reconnection.
+.UNINDENT
+.sp
+Note that while this option cannot be pushed, it can be controlled from
+the management interface.
+.TP
+.B \-\-client
+A helper directive designed to simplify the configuration of OpenVPN\(aqs
+client mode. This directive is equivalent to:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+pull
+tls\-client
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.TP
+.BI \-\-client\-nat \ args
+This pushable client option sets up a stateless one\-to\-one NAT rule on
+packet addresses (not ports), and is useful in cases where routes or
+ifconfig settings pushed to the client would create an IP numbering
+conflict.
+.sp
+Examples:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+client\-nat snat 192.168.0.0/255.255.0.0
+client\-nat dnat 10.64.0.0/255.255.0.0
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+\fBnetwork/netmask\fP (for example \fB192.168.0.0/255.255.0.0\fP) defines
+the local view of a resource from the client perspective, while
+\fBalias/netmask\fP (for example \fB10.64.0.0/255.255.0.0\fP) defines the
+remote view from the server perspective.
+.sp
+Use \fBsnat\fP (source NAT) for resources owned by the client and
+\fBdnat\fP (destination NAT) for remote resources.
+.sp
+Set \fB\-\-verb 6\fP for debugging info showing the transformation of
+src/dest addresses in packets.
+.TP
+.BI \-\-connect\-retry \ n
+Wait \fBn\fP seconds between connection attempts (default \fB5\fP).
+Repeated reconnection attempts are slowed down after 5 retries per
+remote by doubling the wait time after each unsuccessful attempt. An
+optional argument \fBmax\fP specifies the maximum value of wait time in
+seconds at which it gets capped (default \fB300\fP).
+.TP
+.BI \-\-connect\-retry\-max \ n
+\fBn\fP specifies the number of times each \fB\-\-remote\fP or
+\fB<connection>\fP entry is tried. Specifying \fBn\fP as \fB1\fP would try
+each entry exactly once. A successful connection resets the counter.
+(default \fIunlimited\fP).
+.TP
+.BI \-\-connect\-timeout \ n
+See \fB\-\-server\-poll\-timeout\fP\&.
+.TP
+.BI \-\-explicit\-exit\-notify \ n
+In UDP client mode or point\-to\-point mode, send server/peer an exit
+notification if tunnel is restarted or OpenVPN process is exited. In
+client mode, on exit/restart, this option will tell the server to
+immediately close its client instance object rather than waiting for a
+timeout.
+.sp
+The \fBn\fP parameter (default \fB1\fP if not present) controls the
+maximum number of attempts that the client will try to resend the exit
+notification message.
+.sp
+In UDP server mode, send \fBRESTART\fP control channel command to
+connected clients. The \fBn\fP parameter (default \fB1\fP if not present)
+controls client behavior. With \fBn\fP = \fB1\fP client will attempt to
+reconnect to the same server, with \fBn\fP = \fB2\fP client will advance
+to the next server.
+.sp
+OpenVPN will not send any exit notifications unless this option is
+enabled.
+.TP
+.BI \-\-inactive \ args
+Causes OpenVPN to exit after \fBn\fP seconds of inactivity on the TUN/TAP
+device. The time length of inactivity is measured since the last
+incoming or outgoing tunnel packet. The default value is 0 seconds,
+which disables this feature.
+.sp
+Valid syntaxes:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+inactive n
+inactive n bytes
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+If the optional \fBbytes\fP parameter is included, exit if less than
+\fBbytes\fP of combined in/out traffic are produced on the tun/tap device
+in \fBn\fP seconds.
+.sp
+In any case, OpenVPN\(aqs internal ping packets (which are just keepalives)
+and TLS control packets are not considered "activity", nor are they
+counted as traffic, as they are used internally by OpenVPN and are not
+an indication of actual user activity.
+.TP
+.BI \-\-proto\-force \ p
+When iterating through connection profiles, only consider profiles using
+protocol \fBp\fP (\fBtcp\fP | \fBudp\fP).
+.TP
+.B \-\-pull
+This option must be used on a client which is connecting to a
+multi\-client server. It indicates to OpenVPN that it should accept
+options pushed by the server, provided they are part of the legal set of
+pushable options (note that the \fB\-\-pull\fP option is implied by
+\fB\-\-client\fP ).
+.sp
+In particular, \fB\-\-pull\fP allows the server to push routes to the
+client, so you should not use \fB\-\-pull\fP or \fB\-\-client\fP in situations
+where you don\(aqt trust the server to have control over the client\(aqs
+routing table.
+.TP
+.BI \-\-pull\-filter \ args
+Filter options on the client pushed by the server to the client.
+.sp
+Valid syntaxes:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+pull\-filter accept text
+pull\-filter ignore text
+pull\-filter reject text
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Filter options received from the server if the option starts with
+\fBtext\fP\&. The action flag \fBaccept\fP allows the option,
+\fBignore\fP removes it and \fBreject\fP flags an error and triggers
+a \fBSIGUSR1\fP restart. The filters may be specified multiple times,
+and each filter is applied in the order it is specified. The filtering of
+each option stops as soon as a match is found. Unmatched options are accepted
+by default.
+.sp
+Prefix comparison is used to match \fBtext\fP against the received option so
+that
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+pull\-filter ignore "route"
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+would remove all pushed options starting with \fBroute\fP which would
+include, for example, \fBroute\-gateway\fP\&. Enclose \fItext\fP in quotes to
+embed spaces.
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+pull\-filter accept "route 192.168.1."
+pull\-filter ignore "route "
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+would remove all routes that do not start with \fB192.168.1\fP\&.
+.sp
+\fINote\fP that \fBreject\fP may result in a repeated cycle of failure and
+reconnect, unless multiple remotes are specified and connection to the
+next remote succeeds. To silently ignore an option pushed by the server,
+use \fBignore\fP\&.
+.TP
+.BI \-\-remote \ args
+Remote host name or IP address. It supports two additional optional
+arguments: \fBport\fP and \fBproto\fP\&. On the client, multiple \fB\-\-remote\fP
+options may be specified for redundancy, each referring to a different
+OpenVPN server. Specifying multiple \fB\-\-remote\fP options for this
+purpose is a special case of the more general connection\-profile
+feature. See the \fB<connection>\fP documentation below.
+.sp
+The OpenVPN client will try to connect to a server at \fBhost:port\fP in
+the order specified by the list of \fB\-\-remote\fP options.
+.sp
+Examples:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+remote server.example.net
+remote server.example.net 1194
+remote server.example.net tcp
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+\fBproto\fP indicates the protocol to use when connecting with the remote,
+and may be \fBtcp\fP or \fBudp\fP\&.
+.sp
+For forcing IPv4 or IPv6 connection suffix tcp or udp with 4/6 like
+udp4/udp6/tcp4/tcp6.
+.sp
+The client will move on to the next host in the list, in the event of
+connection failure. Note that at any given time, the OpenVPN client will
+at most be connected to one server.
+.sp
+Note that since UDP is connectionless, connection failure is defined by
+the \fB\-\-ping\fP and \fB\-\-ping\-restart\fP options.
+.sp
+Note the following corner case: If you use multiple \fB\-\-remote\fP
+options, AND you are dropping root privileges on the client with
+\fB\-\-user\fP and/or \fB\-\-group\fP AND the client is running a non\-Windows
+OS, if the client needs to switch to a different server, and that server
+pushes back different TUN/TAP or route settings, the client may lack the
+necessary privileges to close and reopen the TUN/TAP interface. This
+could cause the client to exit with a fatal error.
+.sp
+If \fB\-\-remote\fP is unspecified, OpenVPN will listen for packets from any
+IP address, but will not act on those packets unless they pass all
+authentication tests. This requirement for authentication is binding on
+all potential peers, even those from known and supposedly trusted IP
+addresses (it is very easy to forge a source IP address on a UDP
+packet).
+.sp
+When used in TCP mode, \fB\-\-remote\fP will act as a filter, rejecting
+connections from any host which does not match \fBhost\fP\&.
+.sp
+If \fBhost\fP is a DNS name which resolves to multiple IP addresses,
+OpenVPN will try them in the order that the system getaddrinfo()
+presents them, so priorization and DNS randomization is done by the
+system library. Unless an IP version is forced by the protocol
+specification (4/6 suffix), OpenVPN will try both IPv4 and IPv6
+addresses, in the order getaddrinfo() returns them.
+.TP
+.B \-\-remote\-random
+When multiple \fB\-\-remote\fP address/ports are specified, or if connection
+profiles are being used, initially randomize the order of the list as a
+kind of basic load\-balancing measure.
+.TP
+.B \-\-remote\-random\-hostname
+Prepend a random string (6 bytes, 12 hex characters) to hostname to
+prevent DNS caching. For example, "foo.bar.gov" would be modified to
+"<random\-chars>.foo.bar.gov".
+.TP
+.BI \-\-resolv\-retry \ n
+If hostname resolve fails for \fB\-\-remote\fP, retry resolve for \fBn\fP
+seconds before failing.
+.sp
+Set \fBn\fP to "infinite" to retry indefinitely.
+.sp
+By default, \fB\-\-resolv\-retry infinite\fP is enabled. You can disable by
+setting n=0.
+.TP
+.B \-\-single\-session
+After initially connecting to a remote peer, disallow any new
+connections. Using this option means that a remote peer cannot connect,
+disconnect, and then reconnect.
+.sp
+If the daemon is reset by a signal or \fB\-\-ping\-restart\fP, it will allow
+one new connection.
+.sp
+\fB\-\-single\-session\fP can be used with \fB\-\-ping\-exit\fP or \fB\-\-inactive\fP
+to create a single dynamic session that will exit when finished.
+.TP
+.BI \-\-server\-poll\-timeout \ n
+When connecting to a remote server do not wait for more than \fBn\fP
+seconds for a response before trying the next server. The default value
+is 120s. This timeout includes proxy and TCP connect timeouts.
+.TP
+.BI \-\-static\-challenge \ args
+Enable static challenge/response protocol
+.sp
+Valid syntax:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+static\-challenge text echo
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The \fBtext\fP challenge text is presented to the user which describes what
+information is requested. The \fBecho\fP flag indicates if the user\(aqs
+input should be echoed on the screen. Valid \fBecho\fP values are
+\fB0\fP or \fB1\fP\&.
+.sp
+See management\-notes.txt in the OpenVPN distribution for a description of
+the OpenVPN challenge/response protocol.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-show\-proxy\-settings
+Show sensed HTTP or SOCKS proxy settings. Currently, only Windows
+clients support this option.
+.TP
+.BI \-\-http\-proxy \ args
+Connect to remote host through an HTTP proxy. This requires at least an
+address \fBserver\fP and \fBport\fP argument. If HTTP Proxy\-Authenticate
+is required, a file name to an \fBauthfile\fP file containing a username
+and password on 2 lines can be given, or \fBstdin\fP to prompt from
+console. Its content can also be specified in the config file with the
+\fB\-\-http\-proxy\-user\-pass\fP option. (See section on inline files)
+.sp
+The last optional argument is an \fBauth\-method\fP which should be one
+of \fBnone\fP, \fBbasic\fP, or \fBntlm\fP\&.
+.sp
+HTTP Digest authentication is supported as well, but only via the
+\fBauto\fP or \fBauto\-nct\fP flags (below). This must replace
+the \fBauthfile\fP argument.
+.sp
+The \fBauto\fP flag causes OpenVPN to automatically determine the
+\fBauth\-method\fP and query stdin or the management interface for
+username/password credentials, if required. This flag exists on OpenVPN
+2.1 or higher.
+.sp
+The \fBauto\-nct\fP flag (no clear\-text auth) instructs OpenVPN to
+automatically determine the authentication method, but to reject weak
+authentication protocols such as HTTP Basic Authentication.
+.sp
+Examples:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+http\-proxy proxy.example.net 3128
+http\-proxy proxy.example.net 3128 authfile.txt
+http\-proxy proxy.example.net 3128 stdin
+http\-proxy proxy.example.net 3128 auto basic
+http\-proxy proxy.example.net 3128 auto\-nct ntlm
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.TP
+.BI \-\-http\-proxy\-option \ args
+Set extended HTTP proxy options. Requires an option \fBtype\fP as argument
+and an optional \fBparameter\fP to the type. Repeat to set multiple
+options.
+.INDENT 7.0
+.TP
+.B \fBVERSION\fP \fBversion\fP
+Set HTTP version number to \fBversion\fP (default \fB1.0\fP).
+.TP
+.B \fBAGENT\fP \fBuser\-agent\fP
+Set HTTP "User\-Agent" string to \fBuser\-agent\fP\&.
+.TP
+.B \fBCUSTOM\-HEADER\fP \fBname\fP \fBcontent\fP
+Adds the custom Header with \fBname\fP as name and \fBcontent\fP as
+the content of the custom HTTP header.
+.UNINDENT
+.sp
+Examples:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+http\-proxy\-option VERSION 1.1
+http\-proxy\-option AGENT OpenVPN/2.4
+http\-proxy\-option X\-Proxy\-Flag some\-flags
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.TP
+.BI \-\-socks\-proxy \ args
+Connect to remote host through a Socks5 proxy. A required \fBserver\fP
+argument is needed. Optionally a \fBport\fP (default \fB1080\fP) and
+\fBauthfile\fP can be given. The \fBauthfile\fP is a file containing a
+username and password on 2 lines, or \fBstdin\fP can be used to
+prompt from console.
+.UNINDENT
+.SS Server Options
+.sp
+Starting with OpenVPN 2.0, a multi\-client TCP/UDP server mode is
+supported, and can be enabled with the \fB\-\-mode server\fP option. In
+server mode, OpenVPN will listen on a single port for incoming client
+connections. All client connections will be routed through a single tun
+or tap interface. This mode is designed for scalability and should be
+able to support hundreds or even thousands of clients on sufficiently
+fast hardware. SSL/TLS authentication must be used in this mode.
+.INDENT 0.0
+.TP
+.BI \-\-auth\-gen\-token \ args
+Returns an authentication token to successfully authenticated clients.
+.sp
+Valid syntax:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+auth\-gen\-token [lifetime] [external\-auth]
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+After successful user/password authentication, the OpenVPN server will
+with this option generate a temporary authentication token and push that
+to the client. On the following renegotiations, the OpenVPN client will pass
+this token instead of the users password. On the server side the server
+will do the token authentication internally and it will NOT do any
+additional authentications against configured external user/password
+authentication mechanisms.
+.sp
+The tokens implemented by this mechanism include an initial timestamp and
+a renew timestamp and are secured by HMAC.
+.sp
+The \fBlifetime\fP argument defines how long the generated token is valid.
+The lifetime is defined in seconds. If lifetime is not set or it is set
+to \fB0\fP, the token will never expire.
+.sp
+The token will expire either after the configured \fBlifetime\fP of the
+token is reached or after not being renewed for more than 2 *
+\fBreneg\-sec\fP seconds. Clients will be sent renewed tokens on every TLS
+renogiation to keep the client\(aqs token updated. This is done to
+invalidate a token if a client is disconnected for a sufficently long
+time, while at the same time permitting much longer token lifetimes for
+active clients.
+.sp
+This feature is useful for environments which are configured to use One
+Time Passwords (OTP) as part of the user/password authentications and
+that authentication mechanism does not implement any auth\-token support.
+.sp
+When the \fBexternal\-auth\fP keyword is present the normal
+authentication method will always be called even if auth\-token succeeds.
+Normally other authentications method are skipped if auth\-token
+verification suceeds or fails.
+.sp
+This option postpones this decision to the external authentication
+methods and checks the validity of the account and do other checks.
+.sp
+In this mode the environment will have a \fBsession_id\fP variable that
+holds the session id from auth\-gen\-token. Also an environment variable
+\fBsession_state\fP is present. This variable indicates whether the
+auth\-token has succeeded or not. It can have the following values:
+.INDENT 7.0
+.TP
+.B \fBInitial\fP
+No token from client.
+.TP
+.B \fBAuthenticated\fP
+Token is valid and not expired.
+.TP
+.B \fBExpired\fP
+Token is valid but has expired.
+.TP
+.B \fBInvalid\fP
+Token is invalid (failed HMAC or wrong length)
+.TP
+.B \fBAuthenticatedEmptyUser\fP / \fBExpiredEmptyUser\fP
+The token is not valid with the username sent from the client but
+would be valid (or expired) if we assume an empty username was
+used instead. These two cases are a workaround for behaviour in
+OpenVPN 3. If this workaround is not needed these two cases should
+be handled in the same way as \fBInvalid\fP\&.
+.UNINDENT
+.sp
+\fBWarning:\fP Use this feature only if you want your authentication
+method called on every verification. Since the external authentication
+is called it needs to also indicate a success or failure of the
+authentication. It is strongly recommended to return an authentication
+failure in the case of the Invalid/Expired auth\-token with the
+external\-auth option unless the client could authenticate in another
+acceptable way (e.g. client certificate), otherwise returning success
+will lead to authentication bypass (as does returning success on a wrong
+password from a script).
+.TP
+.BI \-\-auth\-gen\-token\-secret \ file
+Specifies a file that holds a secret for the HMAC used in
+\fB\-\-auth\-gen\-token\fP If \fBfile\fP is not present OpenVPN will generate a
+random secret on startup. This file should be used if auth\-token should
+validate after restarting a server or if client should be able to roam
+between multiple OpenVPN servers with their auth\-token.
+.TP
+.B \-\-auth\-user\-pass\-optional
+Allow connections by clients that do not specify a username/password.
+Normally, when \fB\-\-auth\-user\-pass\-verify\fP or
+\fB\-\-management\-client\-auth\fP are specified (or an authentication plugin
+module), the OpenVPN server daemon will require connecting clients to
+specify a username and password. This option makes the submission of a
+username/password by clients optional, passing the responsibility to the
+user\-defined authentication module/script to accept or deny the client
+based on other factors (such as the setting of X509 certificate fields).
+When this option is used, and a connecting client does not submit a
+username/password, the user\-defined authentication module/script will
+see the username and password as being set to empty strings (""). The
+authentication module/script MUST have logic to detect this condition
+and respond accordingly.
+.TP
+.B \-\-ccd\-exclusive
+Require, as a condition of authentication, that a connecting client has
+a \fB\-\-client\-config\-dir\fP file.
+.TP
+.BI \-\-client\-config\-dir \ dir
+Specify a directory \fBdir\fP for custom client config files. After a
+connecting client has been authenticated, OpenVPN will look in this
+directory for a file having the same name as the client\(aqs X509 common
+name. If a matching file exists, it will be opened and parsed for
+client\-specific configuration options. If no matching file is found,
+OpenVPN will instead try to open and parse a default file called
+"DEFAULT", which may be provided but is not required. Note that the
+configuration files must be readable by the OpenVPN process after it has
+dropped it\(aqs root privileges.
+.sp
+This file can specify a fixed IP address for a given client using
+\fB\-\-ifconfig\-push\fP, as well as fixed subnets owned by the client using
+\fB\-\-iroute\fP\&.
+.sp
+One of the useful properties of this option is that it allows client
+configuration files to be conveniently created, edited, or removed while
+the server is live, without needing to restart the server.
+.sp
+The following options are legal in a client\-specific context: \fB\-\-push\fP,
+\fB\-\-push\-reset\fP, \fB\-\-push\-remove\fP, \fB\-\-iroute\fP, \fB\-\-ifconfig\-push\fP,
+\fB\-\-vlan\-pvid\fP and \fB\-\-config\fP\&.
+.TP
+.B \-\-client\-to\-client
+Because the OpenVPN server mode handles multiple clients through a
+single tun or tap interface, it is effectively a router. The
+\fB\-\-client\-to\-client\fP flag tells OpenVPN to internally route
+client\-to\-client traffic rather than pushing all client\-originating
+traffic to the TUN/TAP interface.
+.sp
+When this option is used, each client will "see" the other clients which
+are currently connected. Otherwise, each client will only see the
+server. Don\(aqt use this option if you want to firewall tunnel traffic
+using custom, per\-client rules.
+.TP
+.B \-\-disable
+Disable a particular client (based on the common name) from connecting.
+Don\(aqt use this option to disable a client due to key or password
+compromise. Use a CRL (certificate revocation list) instead (see the
+\fB\-\-crl\-verify\fP option).
+.sp
+This option must be associated with a specific client instance, which
+means that it must be specified either in a client instance config file
+using \fB\-\-client\-config\-dir\fP or dynamically generated using a
+\fB\-\-client\-connect\fP script.
+.TP
+.BI \-\-connect\-freq \ args
+Allow a maximum of \fBn\fP new connections per \fBsec\fP seconds from
+clients.
+.sp
+Valid syntax:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+connect\-freq n sec
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+This is designed to contain DoS attacks which flood the server
+with connection requests using certificates which will ultimately fail
+to authenticate.
+.sp
+This is an imperfect solution however, because in a real DoS scenario,
+legitimate connections might also be refused.
+.sp
+For the best protection against DoS attacks in server mode, use
+\fB\-\-proto udp\fP and either \fB\-\-tls\-auth\fP or \fB\-\-tls\-crypt\fP\&.
+.TP
+.B \-\-duplicate\-cn
+Allow multiple clients with the same common name to concurrently
+connect. In the absence of this option, OpenVPN will disconnect a client
+instance upon connection of a new client having the same common name.
+.TP
+.BI \-\-ifconfig\-pool \ args
+Set aside a pool of subnets to be dynamically allocated to connecting
+clients, similar to a DHCP server.
+.sp
+Valid syntax:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+ifconfig\-pool start\-IP end\-IP [netmask]
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+For tun\-style tunnels, each client
+will be given a /30 subnet (for interoperability with Windows clients).
+For tap\-style tunnels, individual addresses will be allocated, and the
+optional \fBnetmask\fP parameter will also be pushed to clients.
+.TP
+.BI \-\-ifconfig\-ipv6\-pool \ args
+Specify an IPv6 address pool for dynamic assignment to clients.
+.sp
+Valid args:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+ifconfig\-ipv6\-pool ipv6addr/bits
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The pool starts at \fBipv6addr\fP and matches the offset determined from
+the start of the IPv4 pool.
+.TP
+.BI \-\-ifconfig\-pool\-persist \ args
+Persist/unpersist ifconfig\-pool data to \fBfile\fP, at \fBseconds\fP
+intervals (default \fB600\fP), as well as on program startup and shutdown.
+.sp
+Valid syntax:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+ifconfig\-pool\-persist file [seconds]
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The goal of this option is to provide a long\-term association between
+clients (denoted by their common name) and the virtual IP address
+assigned to them from the ifconfig\-pool. Maintaining a long\-term
+association is good for clients because it allows them to effectively
+use the \fB\-\-persist\-tun\fP option.
+.sp
+\fBfile\fP is a comma\-delimited ASCII file, formatted as
+\fB<Common\-Name>,<IP\-address>\fP\&.
+.sp
+If \fBseconds\fP = \fB0\fP, \fBfile\fP will be treated as read\-only. This
+is useful if you would like to treat \fBfile\fP as a configuration file.
+.sp
+Note that the entries in this file are treated by OpenVPN as
+\fIsuggestions\fP only, based on past associations between a common name and
+IP address. They do not guarantee that the given common name will always
+receive the given IP address. If you want guaranteed assignment, use
+\fB\-\-ifconfig\-push\fP
+.TP
+.BI \-\-ifconfig\-push \ args
+Push virtual IP endpoints for client tunnel, overriding the
+\fB\-\-ifconfig\-pool\fP dynamic allocation.
+.sp
+Valid syntax:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+ifconfig\-push local remote\-netmask [alias]
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The parameters \fBlocal\fP and \fBremote\-netmask\fP are set according to the
+\fB\-\-ifconfig\fP directive which you want to execute on the client machine
+to configure the remote end of the tunnel. Note that the parameters
+\fBlocal\fP and \fBremote\-netmask\fP are from the perspective of the client,
+not the server. They may be DNS names rather than IP addresses, in which
+case they will be resolved on the server at the time of client
+connection.
+.sp
+The optional \fBalias\fP parameter may be used in cases where NAT causes
+the client view of its local endpoint to differ from the server view. In
+this case \fBlocal/remote\-netmask\fP will refer to the server view while
+\fBalias/remote\-netmask\fP will refer to the client view.
+.sp
+This option must be associated with a specific client instance, which
+means that it must be specified either in a client instance config file
+using \fB\-\-client\-config\-dir\fP or dynamically generated using a
+\fB\-\-client\-connect\fP script.
+.sp
+Remember also to include a \fB\-\-route\fP directive in the main OpenVPN
+config file which encloses \fBlocal\fP, so that the kernel will know to
+route it to the server\(aqs TUN/TAP interface.
+.sp
+OpenVPN\(aqs internal client IP address selection algorithm works as
+follows:
+.INDENT 7.0
+.IP 1. 3
+Use \fB\-\-client\-connect script\fP generated file for static IP
+(first choice).
+.IP 2. 3
+Use \fB\-\-client\-config\-dir\fP file for static IP (next choice).
+.IP 3. 3
+Use \fB\-\-ifconfig\-pool\fP allocation for dynamic IP (last
+choice).
+.UNINDENT
+.TP
+.BI \-\-ifconfig\-ipv6\-push \ args
+for \fB\-\-client\-config\-dir\fP per\-client static IPv6 interface
+configuration, see \fB\-\-client\-config\-dir\fP and \fB\-\-ifconfig\-push\fP for
+more details.
+.sp
+Valid syntax:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+ifconfig\-ipv6\-push ipv6addr/bits ipv6remote
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.TP
+.BI \-\-inetd \ args
+Valid syntaxes:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+inetd
+inetd wait
+inetd nowait
+inetd wait progname
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Use this option when OpenVPN is being run from the inetd or \fBxinetd\fP(8)
+server.
+.sp
+The \fBwait\fP and \fBnowait\fP option must match what is specified
+in the inetd/xinetd config file. The \fBnowait\fP mode can only be used
+with \fB\-\-proto tcp\-server\fP The default is \fBwait\fP\&. The
+\fBnowait\fP mode can be used to instantiate the OpenVPN daemon as a
+classic TCP server, where client connection requests are serviced on a
+single port number. For additional information on this kind of
+configuration, see the OpenVPN FAQ:
+\fI\%https://community.openvpn.net/openvpn/wiki/325\-openvpn\-as\-a\-\-forking\-tcp\-server\-which\-can\-service\-multiple\-clients\-over\-a\-single\-tcp\-port\fP
+.sp
+This option precludes the use of \fB\-\-daemon\fP, \fB\-\-local\fP or
+\fB\-\-remote\fP\&. Note that this option causes message and error output to
+be handled in the same way as the \fB\-\-daemon\fP option. The optional
+\fBprogname\fP parameter is also handled exactly as in \fB\-\-daemon\fP\&.
+.sp
+Also note that in \fBwait\fP mode, each OpenVPN tunnel requires a separate
+TCP/UDP port and a separate inetd or xinetd entry. See the OpenVPN 1.x
+HOWTO for an example on using OpenVPN with xinetd:
+\fI\%https://openvpn.net/community\-resources/1xhowto/\fP
+.TP
+.B \-\-multihome
+Configure a multi\-homed UDP server. This option needs to be used when a
+server has more than one IP address (e.g. multiple interfaces, or
+secondary IP addresses), and is not using \fB\-\-local\fP to force binding
+to one specific address only. This option will add some extra lookups to
+the packet path to ensure that the UDP reply packets are always sent
+from the address that the client is talking to. This is not supported on
+all platforms, and it adds more processing, so it\(aqs not enabled by
+default.
+.INDENT 7.0
+.TP
+.B \fINotes:\fP
+.INDENT 7.0
+.IP \(bu 2
+This option is only relevant for UDP servers.
+.IP \(bu 2
+If you do an IPv6+IPv4 dual\-stack bind on a Linux machine with
+multiple IPv4 address, connections to IPv4 addresses will not
+work right on kernels before 3.15, due to missing kernel
+support for the IPv4\-mapped case (some distributions have
+ported this to earlier kernel versions, though).
+.UNINDENT
+.UNINDENT
+.TP
+.BI \-\-iroute \ args
+Generate an internal route to a specific client. The \fBnetmask\fP
+parameter, if omitted, defaults to \fB255.255.255.255\fP\&.
+.sp
+Valid syntax:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+iroute network [netmask]
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+This directive can be used to route a fixed subnet from the server to a
+particular client, regardless of where the client is connecting from.
+Remember that you must also add the route to the system routing table as
+well (such as by using the \fB\-\-route\fP directive). The reason why two
+routes are needed is that the \fB\-\-route\fP directive routes the packet
+from the kernel to OpenVPN. Once in OpenVPN, the \fB\-\-iroute\fP directive
+routes to the specific client.
+.sp
+This option must be specified either in a client instance config file
+using \fB\-\-client\-config\-dir\fP or dynamically generated using a
+\fB\-\-client\-connect\fP script.
+.sp
+The \fB\-\-iroute\fP directive also has an important interaction with
+\fB\-\-push "route ..."\fP\&. \fB\-\-iroute\fP essentially defines a subnet which
+is owned by a particular client (we will call this client \fIA\fP). If you
+would like other clients to be able to reach \fIA\fP\(aqs subnet, you can use
+\fB\-\-push "route ..."\fP together with \fB\-\-client\-to\-client\fP to effect
+this. In order for all clients to see \fIA\fP\(aqs subnet, OpenVPN must push
+this route to all clients EXCEPT for \fIA\fP, since the subnet is already
+owned by \fIA\fP\&. OpenVPN accomplishes this by not not pushing a route to
+a client if it matches one of the client\(aqs iroutes.
+.TP
+.BI \-\-iroute\-ipv6 \ args
+for \fB\-\-client\-config\-dir\fP per\-client static IPv6 route configuration,
+see \fB\-\-iroute\fP for more details how to setup and use this, and how
+\fB\-\-iroute\fP and \fB\-\-route\fP interact.
+.sp
+Valid syntax:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+iroute\-ipv6 ipv6addr/bits
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.TP
+.BI \-\-max\-clients \ n
+Limit server to a maximum of \fBn\fP concurrent clients.
+.TP
+.BI \-\-max\-routes\-per\-client \ n
+Allow a maximum of \fBn\fP internal routes per client (default
+\fB256\fP). This is designed to help contain DoS attacks where an
+authenticated client floods the server with packets appearing to come
+from many unique MAC addresses, forcing the server to deplete virtual
+memory as its internal routing table expands. This directive can be used
+in a \fB\-\-client\-config\-dir\fP file or auto\-generated by a
+\fB\-\-client\-connect\fP script to override the global value for a particular
+client.
+.sp
+Note that this directive affects OpenVPN\(aqs internal routing table, not
+the kernel routing table.
+.TP
+.B \-\-opt\-verify
+Clients that connect with options that are incompatible with those of the
+server will be disconnected.
+.sp
+Options that will be compared for compatibility include \fBdev\-type\fP,
+\fBlink\-mtu\fP, \fBtun\-mtu\fP, \fBproto\fP, \fBifconfig\fP,
+\fBcomp\-lzo\fP, \fBfragment\fP, \fBkeydir\fP, \fBcipher\fP,
+\fBauth\fP, \fBkeysize\fP, \fBsecret\fP, \fBno\-replay\fP,
+\fBtls\-auth\fP, \fBkey\-method\fP, \fBtls\-server\fP
+and \fBtls\-client\fP\&.
+.sp
+This option requires that \fB\-\-disable\-occ\fP NOT be used.
+.TP
+.BI \-\-port\-share \ args
+Share OpenVPN TCP with another service
+.sp
+Valid syntax:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+port\-share host port [dir]
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+When run in TCP server mode, share the OpenVPN port with another
+application, such as an HTTPS server. If OpenVPN senses a connection to
+its port which is using a non\-OpenVPN protocol, it will proxy the
+connection to the server at \fBhost\fP:\fBport\fP\&. Currently only designed to
+work with HTTP/HTTPS, though it would be theoretically possible to
+extend to other protocols such as ssh.
+.sp
+\fBdir\fP specifies an optional directory where a temporary file with name
+N containing content C will be dynamically generated for each proxy
+connection, where N is the source IP:port of the client connection and C
+is the source IP:port of the connection to the proxy receiver. This
+directory can be used as a dictionary by the proxy receiver to determine
+the origin of the connection. Each generated file will be automatically
+deleted when the proxied connection is torn down.
+.sp
+Not implemented on Windows.
+.TP
+.BI \-\-push \ option
+Push a config file option back to the client for remote execution. Note
+that \fBoption\fP must be enclosed in double quotes (\fB""\fP). The
+client must specify \fB\-\-pull\fP in its config file. The set of options
+which can be pushed is limited by both feasibility and security. Some
+options such as those which would execute scripts are banned, since they
+would effectively allow a compromised server to execute arbitrary code
+on the client. Other options such as TLS or MTU parameters cannot be
+pushed because the client needs to know them before the connection to the
+server can be initiated.
+.sp
+This is a partial list of options which can currently be pushed:
+\fB\-\-route\fP, \fB\-\-route\-gateway\fP, \fB\-\-route\-delay\fP,
+\fB\-\-redirect\-gateway\fP, \fB\-\-ip\-win32\fP, \fB\-\-dhcp\-option\fP,
+\fB\-\-inactive\fP, \fB\-\-ping\fP, \fB\-\-ping\-exit\fP, \fB\-\-ping\-restart\fP,
+\fB\-\-setenv\fP, \fB\-\-auth\-token\fP, \fB\-\-persist\-key\fP, \fB\-\-persist\-tun\fP,
+\fB\-\-echo\fP, \fB\-\-comp\-lzo\fP, \fB\-\-socket\-flags\fP, \fB\-\-sndbuf\fP,
+\fB\-\-rcvbuf\fP
+.TP
+.B \-\-push\-peer\-info
+Push additional information about the client to server. The following
+data is always pushed to the server:
+.INDENT 7.0
+.TP
+.B \fBIV_VER=<version>\fP
+The client OpenVPN version
+.TP
+.B \fBIV_PLAT=[linux|solaris|openbsd|mac|netbsd|freebsd|win]\fP
+The client OS platform
+.TP
+.B \fBIV_LZO_STUB=1\fP
+If client was built with LZO stub capability
+.TP
+.B \fBIV_LZ4=1\fP
+If the client supports LZ4 compressions.
+.TP
+.B \fBIV_PROTO\fP
+Details about protocol extensions that the peer supports. The
+variable is a bitfield and the bits are defined as follows
+(starting a bit 0 for the first (unused) bit:
+.INDENT 7.0
+.IP \(bu 2
+bit 1: The peer supports peer\-id floating mechanism
+.IP \(bu 2
+bit 2: The client expects a push\-reply and the server may
+send this reply without waiting for a push\-request first.
+.UNINDENT
+.TP
+.B \fBIV_NCP=2\fP
+Negotiable ciphers, client supports \fB\-\-cipher\fP pushed by
+the server, a value of 2 or greater indicates client supports
+\fIAES\-GCM\-128\fP and \fIAES\-GCM\-256\fP\&.
+.TP
+.B \fBIV_CIPHERS=<ncp\-ciphers>\fP
+The client announces the list of supported ciphers configured with the
+\fB\-\-data\-ciphers\fP option to the server.
+.TP
+.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.
+.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
+.TP
+.B \fBIV_SSL=<version string>\fP
+The ssl version used by the client, e.g.
+\fBOpenSSL 1.0.2f 28 Jan 2016\fP\&.
+.TP
+.B \fBIV_PLAT_VER=x.y\fP
+The version of the operating system, e.g. 6.1 for Windows 7.
+.TP
+.B \fBUV_<name>=<value>\fP
+Client environment variables whose names start with
+\fBUV_\fP
+.UNINDENT
+.TP
+.BI \-\-push\-remove \ opt
+Selectively remove all \fB\-\-push\fP options matching "opt" from the option
+list for a client. \fBopt\fP is matched as a substring against the whole
+option string to\-be\-pushed to the client, so \fB\-\-push\-remove route\fP
+would remove all \fB\-\-push route ...\fP and \fB\-\-push route\-ipv6 ...\fP
+statements, while \fB\-\-push\-remove "route\-ipv6 2001:"\fP would only remove
+IPv6 routes for \fB2001:...\fP networks.
+.sp
+\fB\-\-push\-remove\fP can only be used in a client\-specific context, like in
+a \fB\-\-client\-config\-dir\fP file, or \fB\-\-client\-connect\fP script or plugin
+\-\- similar to \fB\-\-push\-reset\fP, just more selective.
+.sp
+\fINOTE\fP: to \fIchange\fP an option, \fB\-\-push\-remove\fP can be used to first
+remove the old value, and then add a new \fB\-\-push\fP option with the new
+value.
+.sp
+\fINOTE 2\fP: due to implementation details, \(aqifconfig\(aq and \(aqifconfig\-ipv6\(aq
+can only be removed with an exact match on the option (
+\fBpush\-remove ifconfig\fP), no substring matching and no matching on
+the IPv4/IPv6 address argument is possible.
+.TP
+.B \-\-push\-reset
+Don\(aqt inherit the global push list for a specific client instance.
+Specify this option in a client\-specific context such as with a
+\fB\-\-client\-config\-dir\fP configuration file. This option will ignore
+\fB\-\-push\fP options at the global config file level.
+.TP
+.BI \-\-server \ args
+A helper directive designed to simplify the configuration of OpenVPN\(aqs
+server mode. This directive will set up an OpenVPN server which will
+allocate addresses to clients out of the given network/netmask. The
+server itself will take the \fB\&.1\fP address of the given network for
+use as the server\-side endpoint of the local TUN/TAP interface. If the
+optional \fBnopool\fP flag is given, no dynamic IP address pool will
+prepared for VPN clients.
+.sp
+Valid syntax:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+server network netmask [nopool]
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+For example, \fB\-\-server 10.8.0.0 255.255.255.0\fP expands as follows:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+mode server
+tls\-server
+push "topology [topology]"
+
+if dev tun AND (topology == net30 OR topology == p2p):
+ ifconfig 10.8.0.1 10.8.0.2
+ if !nopool:
+ ifconfig\-pool 10.8.0.4 10.8.0.251
+ route 10.8.0.0 255.255.255.0
+ if client\-to\-client:
+ push "route 10.8.0.0 255.255.255.0"
+ else if topology == net30:
+ push "route 10.8.0.1"
+
+if dev tap OR (dev tun AND topology == subnet):
+ ifconfig 10.8.0.1 255.255.255.0
+ if !nopool:
+ ifconfig\-pool 10.8.0.2 10.8.0.253 255.255.255.0
+ push "route\-gateway 10.8.0.1"
+ if route\-gateway unset:
+ route\-gateway 10.8.0.2
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Don\(aqt use \fB\-\-server\fP if you are ethernet bridging. Use
+\fB\-\-server\-bridge\fP instead.
+.TP
+.BI \-\-server\-bridge \ args
+A helper directive similar to \fB\-\-server\fP which is designed to simplify
+the configuration of OpenVPN\(aqs server mode in ethernet bridging
+configurations.
+.sp
+Valid syntaxes:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+server\-bridge gateway netmask pool\-start\-IP pool\-end\-IP
+server\-bridge [nogw]
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+If \fB\-\-server\-bridge\fP is used without any parameters, it will enable a
+DHCP\-proxy mode, where connecting OpenVPN clients will receive an IP
+address for their TAP adapter from the DHCP server running on the
+OpenVPN server\-side LAN. Note that only clients that support the binding
+of a DHCP client with the TAP adapter (such as Windows) can support this
+mode. The optional \fBnogw\fP flag (advanced) indicates that gateway
+information should not be pushed to the client.
+.sp
+To configure ethernet bridging, you must first use your OS\(aqs bridging
+capability to bridge the TAP interface with the ethernet NIC interface.
+For example, on Linux this is done with the \fBbrctl\fP tool, and with
+Windows XP it is done in the Network Connections Panel by selecting the
+ethernet and TAP adapters and right\-clicking on "Bridge Connections".
+.sp
+Next you you must manually set the IP/netmask on the bridge interface.
+The \fBgateway\fP and \fBnetmask\fP parameters to \fB\-\-server\-bridge\fP can be
+set to either the IP/netmask of the bridge interface, or the IP/netmask
+of the default gateway/router on the bridged subnet.
+.sp
+Finally, set aside a IP range in the bridged subnet, denoted by
+\fBpool\-start\-IP\fP and \fBpool\-end\-IP\fP, for OpenVPN to allocate to
+connecting clients.
+.sp
+For example, \fBserver\-bridge 10.8.0.4 255.255.255.0 10.8.0.128
+10.8.0.254\fP expands as follows:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+mode server
+tls\-server
+
+ifconfig\-pool 10.8.0.128 10.8.0.254 255.255.255.0
+push "route\-gateway 10.8.0.4"
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+In another example, \fB\-\-server\-bridge\fP (without parameters) expands as
+follows:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+mode server
+tls\-server
+
+push "route\-gateway dhcp"
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Or \fB\-\-server\-bridge nogw\fP expands as follows:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+mode server
+tls\-server
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.TP
+.BI \-\-stale\-routes\-check \ args
+Remove routes which haven\(aqt had activity for \fBn\fP seconds (i.e. the ageing
+time). This check is run every \fBt\fP seconds (i.e. check interval).
+.sp
+Valid syntax:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+stale\-routes\-check n [t]
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+If \fBt\fP is not present it defaults to \fBn\fP\&.
+.sp
+This option helps to keep the dynamic routing table small. See also
+\fB\-\-max\-routes\-per\-client\fP
+.TP
+.B \-\-username\-as\-common\-name
+For \fB\-\-auth\-user\-pass\-verify\fP authentication, use the authenticated
+username as the common name, rather than the common name from the client
+cert.
+.TP
+.BI \-\-verify\-client\-cert \ mode
+Specify whether the client is required to supply a valid certificate.
+.sp
+Possible \fBmode\fP options are:
+.INDENT 7.0
+.TP
+.B \fBnone\fP
+A client certificate is not required. the client needs to
+authenticate using username/password only. Be aware that using this
+directive is less secure than requiring certificates from all
+clients.
+.sp
+If you use this directive, the entire responsibility of authentication
+will rest on your \fB\-\-auth\-user\-pass\-verify\fP script, so keep in mind
+that bugs in your script could potentially compromise the security of
+your VPN.
+.sp
+\fB\-\-verify\-client\-cert none\fP is functionally equivalent to
+\fB\-\-client\-cert\-not\-required\fP\&.
+.TP
+.B \fBoptional\fP
+A client may present a certificate but it is not required to do so.
+When using this directive, you should also use a
+\fB\-\-auth\-user\-pass\-verify\fP script to ensure that clients are
+authenticated using a certificate, a username and password, or
+possibly even both.
+.sp
+Again, the entire responsibility of authentication will rest on your
+\fB\-\-auth\-user\-pass\-verify\fP script, so keep in mind that bugs in your
+script could potentially compromise the security of your VPN.
+.TP
+.B \fBrequire\fP
+This is the default option. A client is required to present a
+certificate, otherwise VPN access is refused.
+.UNINDENT
+.sp
+If you don\(aqt use this directive (or use \fB\-\-verify\-client\-cert require\fP)
+but you also specify an \fB\-\-auth\-user\-pass\-verify\fP script, then OpenVPN
+will perform double authentication. The client certificate verification
+AND the \fB\-\-auth\-user\-pass\-verify\fP script will need to succeed in order
+for a client to be authenticated and accepted onto the VPN.
+.TP
+.B \-\-vlan\-tagging
+Server\-only option. Turns the OpenVPN server instance into a switch that
+understands VLAN\-tagging, based on IEEE 802.1Q.
+.sp
+The server TAP device and each of the connecting clients is seen as a
+port of the switch. All client ports are in untagged mode and the server
+TAP device is VLAN\-tagged, untagged or accepts both, depending on the
+\fB\-\-vlan\-accept\fP setting.
+.sp
+Ethernet frames with a prepended 802.1Q tag are called "tagged". If the
+VLAN Identifier (VID) field in such a tag is non\-zero, the frame is
+called "VLAN\-tagged". If the VID is zero, but the Priority Control Point
+(PCP) field is non\-zero, the frame is called "prio\-tagged". If there is
+no 802.1Q tag, the frame is "untagged".
+.sp
+Using the \fB\-\-vlan\-pvid v\fP option once per client (see
+\-\-client\-config\-dir), each port can be associated with a certain VID.
+Packets can only be forwarded between ports having the same VID.
+Therefore, clients with differing VIDs are completely separated from
+one\-another, even if \fB\-\-client\-to\-client\fP is activated.
+.sp
+The packet filtering takes place in the OpenVPN server. Clients should
+not have any VLAN tagging configuration applied.
+.sp
+The \fB\-\-vlan\-tagging\fP option is off by default. While turned off,
+OpenVPN accepts any Ethernet frame and does not perform any special
+processing for VLAN\-tagged packets.
+.sp
+This option can only be activated in \fB\-\-dev tap mode\fP\&.
+.TP
+.BI \-\-vlan\-accept \ args
+Configure the VLAN tagging policy for the server TAP device.
+.sp
+Valid syntax:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+vlan\-accept all|tagged|untagged
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The following modes are available:
+.INDENT 7.0
+.TP
+.B \fBtagged\fP
+Admit only VLAN\-tagged frames. Only VLAN\-tagged packets are accepted,
+while untagged or priority\-tagged packets are dropped when entering
+the server TAP device.
+.TP
+.B \fBuntagged\fP
+Admit only untagged and prio\-tagged frames. VLAN\-tagged packets are
+not accepted, while untagged or priority\-tagged packets entering the
+server TAP device are tagged with the value configured for the global
+\fB\-\-vlan\-pvid\fP setting.
+.TP
+.B \fBall\fP (default)
+Admit all frames. All packets are admitted and then treated like
+untagged or tagged mode respectively.
+.TP
+.B \fINote\fP:
+Some vendors refer to switch ports running in \fBtagged\fP mode
+as "trunk ports" and switch ports running in \fBuntagged\fP mode
+as "access ports".
+.UNINDENT
+.sp
+Packets forwarded from clients to the server are VLAN\-tagged with the
+originating client\(aqs PVID, unless the VID matches the global
+\fB\-\-vlan\-pvid\fP, in which case the tag is removed.
+.sp
+If no \fIPVID\fP is configured for a given client (see \-\-vlan\-pvid) packets
+are tagged with 1 by default.
+.TP
+.BI \-\-vlan\-pvid \ v
+Specifies which VLAN identifier a "port" is associated with. Only valid
+when \fB\-\-vlan\-tagging\fP is speficied.
+.sp
+In the client context, the setting specifies which VLAN ID a client is
+associated with. In the global context, the VLAN ID of the server TAP
+device is set. The latter only makes sense for \fB\-\-vlan\-accept
+untagged\fP and \fB\-\-vlan\-accept all\fP modes.
+.sp
+Valid values for \fBv\fP go from \fB1\fP through to \fB4094\fP\&. The
+global value defaults to \fB1\fP\&. If no \fB\-\-vlan\-pvid\fP is specified in
+the client context, the global value is inherited.
+.sp
+In some switch implementations, the \fIPVID\fP is also referred to as "Native
+VLAN".
+.UNINDENT
+.SH ENCRYPTION OPTIONS
+.SS SSL Library information
+.INDENT 0.0
+.TP
+.B \-\-show\-ciphers
+(Standalone) Show all cipher algorithms to use with the \fB\-\-cipher\fP
+option.
+.TP
+.B \-\-show\-digests
+(Standalone) Show all message digest algorithms to use with the
+\fB\-\-auth\fP option.
+.TP
+.B \-\-show\-tls
+(Standalone) Show all TLS ciphers supported by the crypto library.
+OpenVPN uses TLS to secure the control channel, over which the keys that
+are used to protect the actual VPN traffic are exchanged. The TLS
+ciphers will be sorted from highest preference (most secure) to lowest.
+.sp
+Be aware that whether a cipher suite in this list can actually work
+depends on the specific setup of both peers (e.g. both peers must
+support the cipher, and an ECDSA cipher suite will not work if you are
+using an RSA certificate, etc.).
+.TP
+.B \-\-show\-engines
+(Standalone) Show currently available hardware\-based crypto acceleration
+engines supported by the OpenSSL library.
+.TP
+.B \-\-show\-groups
+(Standalone) Show all available elliptic curves/groups to use with the
+\fB\-\-ecdh\-curve\fP and \fBtls\-groups\fP options.
+.UNINDENT
+.SS Generating key material
+.INDENT 0.0
+.TP
+.BI \-\-genkey \ args
+(Standalone) Generate a key to be used of the type keytype. if keyfile
+is left out or empty the key will be output on stdout. See the following
+sections for the different keytypes.
+.sp
+Valid syntax:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+\-\-genkey keytype keyfile
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Valid keytype arguments are:
+.sp
+\fBsecret\fP Standard OpenVPN shared secret keys
+.sp
+\fBtls\-crypt\fP Alias for \fBsecret\fP
+.sp
+\fBtls\-auth\fP Alias for \fBsecret\fP
+.sp
+\fBauth\-token\fP Key used for \fB\-\-auth\-gen\-token\-key\fP
+.sp
+\fBtls\-crypt\-v2\-server\fP TLS Crypt v2 server key
+.sp
+\fBtls\-crypt\-v2\-client\fP TLS Crypt v2 client key
+.sp
+Examples:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ openvpn \-\-genkey secret shared.key
+$ openvpn \-\-genkey tls\-crypt shared.key
+$ openvpn \-\-genkey tls\-auth shared.key
+$ openvpn \-\-genkey tls\-crypt\-v2\-server v2crypt\-server.key
+$ openvpn \-\-tls\-crypt\-v2 v2crypt\-server.key \-\-genkey tls\-crypt\-v2\-client v2crypt\-client\-1.key
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.INDENT 7.0
+.IP \(bu 2
+Generating \fIShared Secret Keys\fP
+Generate a shared secret, for use with the \fB\-\-secret\fP, \fB\-\-tls\-auth\fP
+or \fB\-\-tls\-crypt\fP options.
+.sp
+Syntax:
+.INDENT 2.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ openvpn \-\-genkey secret|tls\-crypt|tls\-auth keyfile
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The key is saved in \fBkeyfile\fP\&. All three variants (\fB\-\-secret\fP,
+\fBtls\-crypt\fP and \fBtls\-auth\fP) generate the same type of key. The
+aliases are added for convenience.
+.sp
+If using this for \fB\-\-secret\fP, this file must be shared with the peer
+over a pre\-existing secure channel such as \fBscp\fP(1).
+.IP \(bu 2
+Generating \fITLS Crypt v2 Server key\fP
+Generate a \fB\-\-tls\-crypt\-v2\fP key to be used by an OpenVPN server.
+The key is stored in \fBkeyfile\fP\&.
+.sp
+Syntax:
+.INDENT 2.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+\-\-genkey tls\-crypt\-v2\-server keyfile
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.IP \(bu 2
+Generating \fITLS Crypt v2 Client key\fP
+Generate a \-\-tls\-crypt\-v2 key to be used by OpenVPN clients. The
+key is stored in \fBkeyfile\fP\&.
+.sp
+Syntax
+.INDENT 2.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+\-\-genkey tls\-crypt\-v2\-client keyfile [metadata]
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+If supplied, include the supplied \fBmetadata\fP in the wrapped client
+key. This metadata must be supplied in base64\-encoded form. The
+metadata must be at most 735 bytes long (980 bytes in base64).
+.sp
+If no metadata is supplied, OpenVPN will use a 64\-bit unix timestamp
+representing the current time in UTC, encoded in network order, as
+metadata for the generated key.
+.sp
+A tls\-crypt\-v2 client key is wrapped using a server key. To generate a
+client key, the user must therefore supply the server key using the
+\fB\-\-tls\-crypt\-v2\fP option.
+.sp
+Servers can use \fB\-\-tls\-crypt\-v2\-verify\fP to specify a metadata
+verification command.
+.IP \(bu 2
+Generate \fIAuthentication Token key\fP
+Generate a new secret that can be used with \fB\-\-auth\-gen\-token\-secret\fP
+.sp
+Syntax:
+.INDENT 2.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+\-\-genkey auth\-token [keyfile]
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.INDENT 2.0
+.TP
+.B \fINote:\fP
+This file should be kept secret to the server as anyone that has
+access to this file will be able to generate auth tokens that the
+OpenVPN server will accept as valid.
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.SS Data Channel Renegotiation
+.sp
+When running OpenVPN in client/server mode, the data channel will use a
+separate ephemeral encryption key which is rotated at regular intervals.
+.INDENT 0.0
+.TP
+.BI \-\-reneg\-bytes \ n
+Renegotiate data channel key after \fBn\fP bytes sent or received
+(disabled by default with an exception, see below). OpenVPN allows the
+lifetime of a key to be expressed as a number of bytes
+encrypted/decrypted, a number of packets, or a number of seconds. A key
+renegotiation will be forced if any of these three criteria are met by
+either peer.
+.sp
+If using ciphers with cipher block sizes less than 128\-bits,
+\fB\-\-reneg\-bytes\fP is set to 64MB by default, unless it is explicitly
+disabled by setting the value to \fB0\fP, but this is
+\fBHIGHLY DISCOURAGED\fP as this is designed to add some protection against
+the SWEET32 attack vector. For more information see the \fB\-\-cipher\fP
+option.
+.TP
+.BI \-\-reneg\-pkts \ n
+Renegotiate data channel key after \fBn\fP packets sent and received
+(disabled by default).
+.TP
+.BI \-\-reneg\-sec \ args
+Renegotiate data channel key after at most \fBmax\fP seconds
+(default \fB3600\fP) and at least \fBmin\fP seconds (default is 90% of
+\fBmax\fP for servers, and equal to \fBmax\fP for clients).
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+reneg\-sec max [min]
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The effective \fB\-\-reneg\-sec\fP value used is per session
+pseudo\-uniform\-randomized between \fBmin\fP and \fBmax\fP\&.
+.sp
+With the default value of \fB3600\fP this results in an effective per
+session value in the range of \fB3240\fP\&..:code:\fI3600\fP seconds for
+servers, or just 3600 for clients.
+.sp
+When using dual\-factor authentication, note that this default value may
+cause the end user to be challenged to reauthorize once per hour.
+.sp
+Also, keep in mind that this option can be used on both the client and
+server, and whichever uses the lower value will be the one to trigger
+the renegotiation. A common mistake is to set \fB\-\-reneg\-sec\fP to a
+higher value on either the client or server, while the other side of the
+connection is still using the default value of \fB3600\fP seconds,
+meaning that the renegotiation will still occur once per \fB3600\fP
+seconds. The solution is to increase \-\-reneg\-sec on both the client and
+server, or set it to \fB0\fP on one side of the connection (to
+disable), and to your chosen value on the other side.
+.UNINDENT
+.SS TLS Mode Options
+.sp
+TLS mode is the most powerful crypto mode of OpenVPN in both security
+and flexibility. TLS mode works by establishing control and data
+channels which are multiplexed over a single TCP/UDP port. OpenVPN
+initiates a TLS session over the control channel and uses it to exchange
+cipher and HMAC keys to protect the data channel. TLS mode uses a robust
+reliability layer over the UDP connection for all control channel
+communication, while the data channel, over which encrypted tunnel data
+passes, is forwarded without any mediation. The result is the best of
+both worlds: a fast data channel that forwards over UDP with only the
+overhead of encrypt, decrypt, and HMAC functions, and a control channel
+that provides all of the security features of TLS, including
+certificate\-based authentication and Diffie Hellman forward secrecy.
+.sp
+To use TLS mode, each peer that runs OpenVPN should have its own local
+certificate/key pair (\fB\-\-cert\fP and \fB\-\-key\fP), signed by the root
+certificate which is specified in \fB\-\-ca\fP\&.
+.sp
+When two OpenVPN peers connect, each presents its local certificate to
+the other. Each peer will then check that its partner peer presented a
+certificate which was signed by the master root certificate as specified
+in \fB\-\-ca\fP\&.
+.sp
+If that check on both peers succeeds, then the TLS negotiation will
+succeed, both OpenVPN peers will exchange temporary session keys, and
+the tunnel will begin passing data.
+.sp
+The OpenVPN project provides a set of scripts for managing RSA
+certificates and keys: \fI\%https://github.com/OpenVPN/easy\-rsa\fP
+.INDENT 0.0
+.TP
+.BI \-\-askpass \ file
+Get certificate password from console or \fBfile\fP before we daemonize.
+.sp
+Valid syntaxes:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+askpass
+askpass file
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+For the extremely security conscious, it is possible to protect your
+private key with a password. Of course this means that every time the
+OpenVPN daemon is started you must be there to type the password. The
+\fB\-\-askpass\fP option allows you to start OpenVPN from the command line.
+It will query you for a password before it daemonizes. To protect a
+private key with a password you should omit the \fB\-nodes\fP option when
+you use the \fBopenssl\fP command line tool to manage certificates and
+private keys.
+.sp
+If \fBfile\fP is specified, read the password from the first line of
+\fBfile\fP\&. Keep in mind that storing your password in a file to a certain
+extent invalidates the extra security provided by using an encrypted
+key.
+.TP
+.BI \-\-ca \ file
+Certificate authority (CA) file in .pem format, also referred to as the
+\fIroot\fP certificate. This file can have multiple certificates in .pem
+format, concatenated together. You can construct your own certificate
+authority certificate and private key by using a command such as:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+openssl req \-nodes \-new \-x509 \-keyout ca.key \-out ca.crt
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Then edit your openssl.cnf file and edit the \fBcertificate\fP variable to
+point to your new root certificate \fBca.crt\fP\&.
+.sp
+For testing purposes only, the OpenVPN distribution includes a sample CA
+certificate (ca.crt). Of course you should never use the test
+certificates and test keys distributed with OpenVPN in a production
+environment, since by virtue of the fact that they are distributed with
+OpenVPN, they are totally insecure.
+.TP
+.BI \-\-capath \ dir
+Directory containing trusted certificates (CAs and CRLs). Not available
+with mbed TLS.
+.sp
+CAs in the capath directory are expected to be named <hash>.<n>. CRLs
+are expected to be named <hash>.r<n>. See the \fB\-CApath\fP option of
+\fBopenssl verify\fP, and the \fB\-hash\fP option of \fBopenssl x509\fP,
+\fBopenssl crl\fP and \fBX509_LOOKUP_hash_dir()\fP(3)
+for more information.
+.sp
+Similar to the \fB\-\-crl\-verify\fP option, CRLs are not mandatory \-
+OpenVPN will log the usual warning in the logs if the relevant CRL is
+missing, but the connection will be allowed.
+.TP
+.BI \-\-cert \ file
+Local peer\(aqs signed certificate in .pem format \-\- must be signed by a
+certificate authority whose certificate is in \fB\-\-ca file\fP\&. Each peer
+in an OpenVPN link running in TLS mode should have its own certificate
+and private key file. In addition, each certificate should have been
+signed by the key of a certificate authority whose public key resides in
+the \fB\-\-ca\fP certificate authority file. You can easily make your own
+certificate authority (see above) or pay money to use a commercial
+service such as thawte.com (in which case you will be helping to finance
+the world\(aqs second space tourist :). To generate a certificate, you can
+use a command such as:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+openssl req \-nodes \-new \-keyout mycert.key \-out mycert.csr
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+If your certificate authority private key lives on another machine, copy
+the certificate signing request (mycert.csr) to this other machine (this
+can be done over an insecure channel such as email). Now sign the
+certificate with a command such as:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+openssl ca \-out mycert.crt \-in mycert.csr
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Now copy the certificate (mycert.crt) back to the peer which initially
+generated the .csr file (this can be over a public medium). Note that
+the \fBopenssl ca\fP command reads the location of the certificate
+authority key from its configuration file such as
+\fB/usr/share/ssl/openssl.cnf\fP \-\- note also that for certificate
+authority functions, you must set up the files \fBindex.txt\fP (may be
+empty) and \fBserial\fP (initialize to \fB01\fP).
+.TP
+.BI \-\-crl\-verify \ args
+Check peer certificate against a Certificate Revocation List.
+.sp
+Valid syntax:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+crl\-verify file/directory flag
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Examples:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+crl\-verify crl\-file.pem
+crl\-verify /etc/openvpn/crls dir
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+A CRL (certificate revocation list) is used when a particular key is
+compromised but when the overall PKI is still intact.
+.sp
+Suppose you had a PKI consisting of a CA, root certificate, and a number
+of client certificates. Suppose a laptop computer containing a client
+key and certificate was stolen. By adding the stolen certificate to the
+CRL file, you could reject any connection which attempts to use it,
+while preserving the overall integrity of the PKI.
+.sp
+The only time when it would be necessary to rebuild the entire PKI from
+scratch would be if the root certificate key itself was compromised.
+.sp
+The option is not mandatory \- if the relevant CRL is missing, OpenVPN
+will log a warning in the logs \- e.g.
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+VERIFY WARNING: depth=0, unable to get certificate CRL
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+but the connection will be allowed. If the optional \fBdir\fP flag
+is specified, enable a different mode where the \fBcrl\-verify\fP is
+pointed at a directory containing files named as revoked serial numbers
+(the files may be empty, the contents are never read). If a client
+requests a connection, where the client certificate serial number
+(decimal string) is the name of a file present in the directory, it will
+be rejected.
+.INDENT 7.0
+.TP
+.B \fINote:\fP
+As the crl file (or directory) is read every time a peer
+connects, if you are dropping root privileges with
+\fB\-\-user\fP, make sure that this user has sufficient
+privileges to read the file.
+.UNINDENT
+.TP
+.BI \-\-dh \ file
+File containing Diffie Hellman parameters in .pem format (required for
+\fB\-\-tls\-server\fP only).
+.sp
+Set \fBfile\fP to \fBnone\fP to disable Diffie Hellman key exchange (and
+use ECDH only). Note that this requires peers to be using an SSL library
+that supports ECDH TLS cipher suites (e.g. OpenSSL 1.0.1+, or
+mbed TLS 2.0+).
+.sp
+Use \fBopenssl dhparam \-out dh2048.pem 2048\fP to generate 2048\-bit DH
+parameters. Diffie Hellman parameters may be considered public.
+.TP
+.BI \-\-ecdh\-curve \ name
+Specify the curve to use for elliptic curve Diffie Hellman. Available
+curves can be listed with \fB\-\-show\-curves\fP\&. The specified curve will
+only be used for ECDH TLS\-ciphers.
+.sp
+This option is not supported in mbed TLS builds of OpenVPN.
+.TP
+.BI \-\-extra\-certs \ file
+Specify a \fBfile\fP containing one or more PEM certs (concatenated
+together) that complete the local certificate chain.
+.sp
+This option is useful for "split" CAs, where the CA for server certs is
+different than the CA for client certs. Putting certs in this file
+allows them to be used to complete the local certificate chain without
+trusting them to verify the peer\-submitted certificate, as would be the
+case if the certs were placed in the \fBca\fP file.
+.TP
+.BI \-\-hand\-window \ n
+Handshake Window \-\- the TLS\-based key exchange must finalize within
+\fBn\fP seconds of handshake initiation by any peer (default \fB60\fP
+seconds). If the handshake fails we will attempt to reset our connection
+with our peer and try again. Even in the event of handshake failure we
+will still use our expiring key for up to \fB\-\-tran\-window\fP seconds to
+maintain continuity of transmission of tunnel data.
+.TP
+.BI \-\-key \ file
+Local peer\(aqs private key in .pem format. Use the private key which was
+generated when you built your peer\(aqs certificate (see \fB\-\-cert file\fP
+above).
+.TP
+.BI \-\-pkcs12 \ file
+Specify a PKCS #12 file containing local private key, local certificate,
+and root CA certificate. This option can be used instead of \fB\-\-ca\fP,
+\fB\-\-cert\fP, and \fB\-\-key\fP\&. Not available with mbed TLS.
+.TP
+.BI \-\-remote\-cert\-eku \ oid
+Require that peer certificate was signed with an explicit \fIextended key
+usage\fP\&.
+.sp
+This is a useful security option for clients, to ensure that the host
+they connect to is a designated server.
+.sp
+The extended key usage should be encoded in \fIoid notation\fP, or \fIOpenSSL
+symbolic representation\fP\&.
+.TP
+.BI \-\-remote\-cert\-ku \ key\-usage
+Require that peer certificate was signed with an explicit
+\fBkey\-usage\fP\&.
+.sp
+If present in the certificate, the \fBkeyUsage\fP value is validated by
+the TLS library during the TLS handshake. Specifying this option without
+arguments requires this extension to be present (so the TLS library will
+verify it).
+.sp
+If \fBkey\-usage\fP is a list of usage bits, the \fBkeyUsage\fP field
+must have \fIat least\fP the same bits set as the bits in \fIone of\fP the values
+supplied in the \fBkey\-usage\fP list.
+.sp
+The \fBkey\-usage\fP values in the list must be encoded in hex, e.g.
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+remote\-cert\-ku a0
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.TP
+.BI \-\-remote\-cert\-tls \ type
+Require that peer certificate was signed with an explicit \fIkey usage\fP
+and \fIextended key usage\fP based on RFC3280 TLS rules.
+.sp
+Valid syntaxes:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+remote\-cert\-tls server
+remote\-cert\-tls client
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+This is a useful security option for clients, to ensure that the host
+they connect to is a designated server. Or the other way around; for a
+server to verify that only hosts with a client certificate can connect.
+.sp
+The \fB\-\-remote\-cert\-tls client\fP option is equivalent to
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+remote\-cert\-ku
+remote\-cert\-eku "TLS Web Client Authentication"
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The \fB\-\-remote\-cert\-tls server\fP option is equivalent to
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+remote\-cert\-ku
+remote\-cert\-eku "TLS Web Server Authentication"
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+This is an important security precaution to protect against a
+man\-in\-the\-middle attack where an authorized client attempts to connect
+to another client by impersonating the server. The attack is easily
+prevented by having clients verify the server certificate using any one
+of \fB\-\-remote\-cert\-tls\fP, \fB\-\-verify\-x509\-name\fP, or \fB\-\-tls\-verify\fP\&.
+.TP
+.BI \-\-tls\-auth \ args
+Add an additional layer of HMAC authentication on top of the TLS control
+channel to mitigate DoS attacks and attacks on the TLS stack.
+.sp
+Valid syntaxes:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+tls\-auth file
+tls\-auth file 0
+tls\-auth file 1
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+In a nutshell, \fB\-\-tls\-auth\fP enables a kind of "HMAC firewall" on
+OpenVPN\(aqs TCP/UDP port, where TLS control channel packets bearing an
+incorrect HMAC signature can be dropped immediately without response.
+.sp
+\fBfile\fP (required) is a file in OpenVPN static key format which can be
+generated by \fB\-\-genkey\fP\&.
+.sp
+Older versions (up to OpenVPN 2.3) supported a freeform passphrase file.
+This is no longer supported in newer versions (v2.4+).
+.sp
+See the \fB\-\-secret\fP option for more information on the optional
+\fBdirection\fP parameter.
+.sp
+\fB\-\-tls\-auth\fP is recommended when you are running OpenVPN in a mode
+where it is listening for packets from any IP address, such as when
+\fB\-\-remote\fP is not specified, or \fB\-\-remote\fP is specified with
+\fB\-\-float\fP\&.
+.sp
+The rationale for this feature is as follows. TLS requires a
+multi\-packet exchange before it is able to authenticate a peer. During
+this time before authentication, OpenVPN is allocating resources (memory
+and CPU) to this potential peer. The potential peer is also exposing
+many parts of OpenVPN and the OpenSSL library to the packets it is
+sending. Most successful network attacks today seek to either exploit
+bugs in programs (such as buffer overflow attacks) or force a program to
+consume so many resources that it becomes unusable. Of course the first
+line of defense is always to produce clean, well\-audited code. OpenVPN
+has been written with buffer overflow attack prevention as a top
+priority. But as history has shown, many of the most widely used network
+applications have, from time to time, fallen to buffer overflow attacks.
+.sp
+So as a second line of defense, OpenVPN offers this special layer of
+authentication on top of the TLS control channel so that every packet on
+the control channel is authenticated by an HMAC signature and a unique
+ID for replay protection. This signature will also help protect against
+DoS (Denial of Service) attacks. An important rule of thumb in reducing
+vulnerability to DoS attacks is to minimize the amount of resources a
+potential, but as yet unauthenticated, client is able to consume.
+.sp
+\fB\-\-tls\-auth\fP does this by signing every TLS control channel packet
+with an HMAC signature, including packets which are sent before the TLS
+level has had a chance to authenticate the peer. The result is that
+packets without the correct signature can be dropped immediately upon
+reception, before they have a chance to consume additional system
+resources such as by initiating a TLS handshake. \fB\-\-tls\-auth\fP can be
+strengthened by adding the \fB\-\-replay\-persist\fP option which will keep
+OpenVPN\(aqs replay protection state in a file so that it is not lost
+across restarts.
+.sp
+It should be emphasized that this feature is optional and that the key
+file used with \fB\-\-tls\-auth\fP gives a peer nothing more than the power
+to initiate a TLS handshake. It is not used to encrypt or authenticate
+any tunnel data.
+.sp
+Use \fB\-\-tls\-crypt\fP instead if you want to use the key file to not only
+authenticate, but also encrypt the TLS control channel.
+.TP
+.BI \-\-tls\-groups \ list
+A list of allowable groups/curves in order of preference.
+.sp
+Set the allowed elliptic curves/groups for the TLS session.
+These groups are allowed to be used in signatures and key exchange.
+.sp
+mbedTLS currently allows all known curves per default.
+.sp
+OpenSSL 1.1+ restricts the list per default to
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+"X25519:secp256r1:X448:secp521r1:secp384r1".
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+If you use certificates that use non\-standard curves, you
+might need to add them here. If you do not force the ecdh curve
+by using \fB\-\-ecdh\-curve\fP, the groups for ecdh will also be picked
+from this list.
+.sp
+OpenVPN maps the curve name \fIsecp256r1\fP to \fIprime256v1\fP to allow
+specifying the same tls\-groups option for mbedTLS and OpenSSL.
+.sp
+Warning: this option not only affects elliptic curve certificates
+but also the key exchange in TLS 1.3 and using this option improperly
+will disable TLS 1.3.
+.TP
+.BI \-\-tls\-cert\-profile \ profile
+Set the allowed cryptographic algorithms for certificates according to
+\fBprofile\fP\&.
+.sp
+The following profiles are supported:
+.INDENT 7.0
+.TP
+.B \fBlegacy\fP (default)
+SHA1 and newer, RSA 2048\-bit+, any elliptic curve.
+.TP
+.B \fBpreferred\fP
+SHA2 and newer, RSA 2048\-bit+, any elliptic curve.
+.TP
+.B \fBsuiteb\fP
+SHA256/SHA384, ECDSA with P\-256 or P\-384.
+.UNINDENT
+.sp
+This option is only fully supported for mbed TLS builds. OpenSSL builds
+use the following approximation:
+.INDENT 7.0
+.TP
+.B \fBlegacy\fP (default)
+sets "security level 1"
+.TP
+.B \fBpreferred\fP
+sets "security level 2"
+.TP
+.B \fBsuiteb\fP
+sets "security level 3" and \fB\-\-tls\-cipher "SUITEB128"\fP\&.
+.UNINDENT
+.sp
+OpenVPN will migrate to \(aqpreferred\(aq as default in the future. Please
+ensure that your keys already comply.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \fIWARNING:\fP \fB\-\-tls\-ciphers\fP, \fB\-\-tls\-ciphersuites\fP and \fBtls\-groups\fP
+These options are expert features, which \- if used correctly \- can
+improve the security of your VPN connection. But it is also easy to
+unwittingly use them to carefully align a gun with your foot, or just
+break your connection. Use with care!
+.UNINDENT
+.INDENT 0.0
+.TP
+.BI \-\-tls\-cipher \ l
+A list \fBl\fP of allowable TLS ciphers delimited by a colon ("\fB:\fP").
+.sp
+These setting can be used to ensure that certain cipher suites are used
+(or not used) for the TLS connection. OpenVPN uses TLS to secure the
+control channel, over which the keys that are used to protect the actual
+VPN traffic are exchanged.
+.sp
+The supplied list of ciphers is (after potential OpenSSL/IANA name
+translation) simply supplied to the crypto library. Please see the
+OpenSSL and/or mbed TLS documentation for details on the cipher list
+interpretation.
+.sp
+For OpenSSL, the \fB\-\-tls\-cipher\fP is used for TLS 1.2 and below.
+.sp
+Use \fB\-\-show\-tls\fP to see a list of TLS ciphers supported by your crypto
+library.
+.sp
+The default for \fB\-\-tls\-cipher\fP is to use mbed TLS\(aqs default cipher list
+when using mbed TLS or
+\fBDEFAULT:!EXP:!LOW:!MEDIUM:!kDH:!kECDH:!DSS:!PSK:!SRP:!kRSA\fP when
+using OpenSSL.
+.sp
+The default for \fI\-\-tls\-ciphersuites\fP is to use the crypto library\(aqs
+default.
+.TP
+.BI \-\-tls\-ciphersuites \ l
+Same as \fB\-\-tls\-cipher\fP but for TLS 1.3 and up. mbed TLS has no
+TLS 1.3 support yet and only the \fB\-\-tls\-cipher\fP setting is used.
+.TP
+.B \-\-tls\-client
+Enable TLS and assume client role during TLS handshake.
+.TP
+.BI \-\-tls\-crypt \ keyfile
+Encrypt and authenticate all control channel packets with the key from
+\fBkeyfile\fP\&. (See \fB\-\-tls\-auth\fP for more background.)
+.sp
+Encrypting (and authenticating) control channel packets:
+.INDENT 7.0
+.IP \(bu 2
+provides more privacy by hiding the certificate used for the TLS
+connection,
+.IP \(bu 2
+makes it harder to identify OpenVPN traffic as such,
+.IP \(bu 2
+provides "poor\-man\(aqs" post\-quantum security, against attackers who will
+never know the pre\-shared key (i.e. no forward secrecy).
+.UNINDENT
+.sp
+In contrast to \fB\-\-tls\-auth\fP, \fB\-\-tls\-crypt\fP does \fInot\fP require the
+user to set \fB\-\-key\-direction\fP\&.
+.sp
+\fBSecurity Considerations\fP
+.sp
+All peers use the same \fB\-\-tls\-crypt\fP pre\-shared group key to
+authenticate and encrypt control channel messages. To ensure that IV
+collisions remain unlikely, this key should not be used to encrypt more
+than 2^48 client\-to\-server or 2^48 server\-to\-client control channel
+messages. A typical initial negotiation is about 10 packets in each
+direction. Assuming both initial negotiation and renegotiations are at
+most 2^16 (65536) packets (to be conservative), and (re)negotiations
+happen each minute for each user (24/7), this limits the tls\-crypt key
+lifetime to 8171 years divided by the number of users. So a setup with
+1000 users should rotate the key at least once each eight years. (And a
+setup with 8000 users each year.)
+.sp
+If IV collisions were to occur, this could result in the security of
+\fB\-\-tls\-crypt\fP degrading to the same security as using \fB\-\-tls\-auth\fP\&.
+That is, the control channel still benefits from the extra protection
+against active man\-in\-the\-middle\-attacks and DoS attacks, but may no
+longer offer extra privacy and post\-quantum security on top of what TLS
+itself offers.
+.sp
+For large setups or setups where clients are not trusted, consider using
+\fB\-\-tls\-crypt\-v2\fP instead. That uses per\-client unique keys, and
+thereby improves the bounds to \(aqrotate a client key at least once per
+8000 years\(aq.
+.TP
+.BI \-\-tls\-crypt\-v2 \ keyfile
+Use client\-specific tls\-crypt keys.
+.sp
+For clients, \fBkeyfile\fP is a client\-specific tls\-crypt key. Such a key
+can be generated using the \fB\-\-genkey tls\-crypt\-v2\-client\fP option.
+.sp
+For servers, \fBkeyfile\fP is used to unwrap client\-specific keys supplied
+by the client during connection setup. This key must be the same as the
+key used to generate the client\-specific key (see \fB\-\-genkey
+tls\-crypt\-v2\-client\fP).
+.sp
+On servers, this option can be used together with the \fB\-\-tls\-auth\fP or
+\fB\-\-tls\-crypt\fP option. In that case, the server will detect whether the
+client is using client\-specific keys, and automatically select the right
+mode.
+.TP
+.BI \-\-tls\-crypt\-v2\-verify \ cmd
+Run command \fBcmd\fP to verify the metadata of the client\-specific
+tls\-crypt\-v2 key of a connecting client. This allows server
+administrators to reject client connections, before exposing the TLS
+stack (including the notoriously dangerous X.509 and ASN.1 stacks) to
+the connecting client.
+.sp
+OpenVPN supplies the following environment variables to the command:
+.INDENT 7.0
+.IP \(bu 2
+\fBscript_type\fP is set to \fBtls\-crypt\-v2\-verify\fP
+.IP \(bu 2
+\fBmetadata_type\fP is set to \fB0\fP if the metadata was user
+supplied, or \fB1\fP if it\(aqs a 64\-bit unix timestamp representing
+the key creation time.
+.IP \(bu 2
+\fBmetadata_file\fP contains the filename of a temporary file that
+contains the client metadata.
+.UNINDENT
+.sp
+The command can reject the connection by exiting with a non\-zero exit
+code.
+.TP
+.B \-\-tls\-exit
+Exit on TLS negotiation failure.
+.TP
+.BI \-\-tls\-export\-cert \ directory
+Store the certificates the clients use upon connection to this
+directory. This will be done before \fB\-\-tls\-verify\fP is called. The
+certificates will use a temporary name and will be deleted when the
+tls\-verify script returns. The file name used for the certificate is
+available via the \fBpeer_cert\fP environment variable.
+.TP
+.B \-\-tls\-server
+Enable TLS and assume server role during TLS handshake. Note that
+OpenVPN is designed as a peer\-to\-peer application. The designation of
+client or server is only for the purpose of negotiating the TLS control
+channel.
+.TP
+.BI \-\-tls\-timeout \ n
+Packet retransmit timeout on TLS control channel if no acknowledgment
+from remote within \fBn\fP seconds (default \fB2\fP). When OpenVPN sends
+a control packet to its peer, it will expect to receive an
+acknowledgement within \fBn\fP seconds or it will retransmit the packet,
+subject to a TCP\-like exponential backoff algorithm. This parameter only
+applies to control channel packets. Data channel packets (which carry
+encrypted tunnel data) are never acknowledged, sequenced, or
+retransmitted by OpenVPN because the higher level network protocols
+running on top of the tunnel such as TCP expect this role to be left to
+them.
+.TP
+.BI \-\-tls\-version\-min \ args
+Sets the minimum TLS version we will accept from the peer (default is
+"1.0").
+.sp
+Valid syntax:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+tls\-version\-min version [\(aqor\-highest\(aq]
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Examples for version include \fB1.0\fP, \fB1.1\fP, or \fB1.2\fP\&. If
+\fBor\-highest\fP is specified and version is not recognized, we will
+only accept the highest TLS version supported by the local SSL
+implementation.
+.TP
+.BI \-\-tls\-version\-max \ version
+Set the maximum TLS version we will use (default is the highest version
+supported). Examples for version include \fB1.0\fP, \fB1.1\fP, or
+\fB1.2\fP\&.
+.TP
+.BI \-\-verify\-hash \ args
+Specify SHA1 or SHA256 fingerprint for level\-1 cert.
+.sp
+Valid syntax:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+verify\-hash hash [algo]
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The level\-1 cert is the CA (or intermediate cert) that signs the leaf
+certificate, and is one removed from the leaf certificate in the
+direction of the root. When accepting a connection from a peer, the
+level\-1 cert fingerprint must match \fBhash\fP or certificate verification
+will fail. Hash is specified as XX:XX:... For example:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+AD:B0:95:D8:09:C8:36:45:12:A9:89:C8:90:09:CB:13:72:A6:AD:16
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The \fBalgo\fP flag can be either \fBSHA1\fP or \fBSHA256\fP\&. If not
+provided, it defaults to \fBSHA1\fP\&.
+.TP
+.BI \-\-verify\-x509\-name \ args
+Accept connections only if a host\(aqs X.509 name is equal to \fBname.\fP The
+remote host must also pass all other tests of verification.
+.sp
+Valid syntax:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+verify\-x509 name type
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Which X.509 name is compared to \fBname\fP depends on the setting of type.
+\fBtype\fP can be \fBsubject\fP to match the complete subject DN
+(default), \fBname\fP to match a subject RDN or \fBname\-prefix\fP to
+match a subject RDN prefix. Which RDN is verified as name depends on the
+\fB\-\-x509\-username\-field\fP option. But it defaults to the common name
+(CN), e.g. a certificate with a subject DN
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+C=KG, ST=NA, L=Bishkek, CN=Server\-1
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+would be matched by:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+verify\-x509\-name \(aqC=KG, ST=NA, L=Bishkek, CN=Server\-1\(aq
+verify\-x509\-name Server\-1 name
+verify\-x509\-name Server\- name\-prefix
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The last example is useful if you want a client to only accept
+connections to \fBServer\-1\fP, \fBServer\-2\fP, etc.
+.sp
+\fB\-\-verify\-x509\-name\fP is a useful replacement for the \fB\-\-tls\-verify\fP
+option to verify the remote host, because \fB\-\-verify\-x509\-name\fP works
+in a \fB\-\-chroot\fP environment without any dependencies.
+.sp
+Using a name prefix is a useful alternative to managing a CRL
+(Certificate Revocation List) on the client, since it allows the client
+to refuse all certificates except for those associated with designated
+servers.
+.INDENT 7.0
+.TP
+.B \fINOTE:\fP
+Test against a name prefix only when you are using OpenVPN
+with a custom CA certificate that is under your control. Never use
+this option with type \fBname\-prefix\fP when your client
+certificates are signed by a third party, such as a commercial
+web CA.
+.UNINDENT
+.TP
+.BI \-\-x509\-track \ attribute
+Save peer X509 \fBattribute\fP value in environment for use by plugins and
+management interface. Prepend a \fB+\fP to \fBattribute\fP to save values
+from full cert chain. Values will be encoded as
+\fBX509_<depth>_<attribute>=<value>\fP\&. Multiple \fB\-\-x509\-track\fP
+options can be defined to track multiple attributes.
+.TP
+.BI \-\-x509\-username\-field \ args
+Field in the X.509 certificate subject to be used as the username
+(default \fBCN\fP).
+.sp
+Valid syntax:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+x509\-username\-field [ext:]fieldname
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Typically, this option is specified with \fBfieldname\fP as
+either of the following:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+x509\-username\-field emailAddress
+x509\-username\-field ext:subjectAltName
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The first example uses the value of the \fBemailAddress\fP attribute
+in the certificate\(aqs Subject field as the username. The second example
+uses the \fBext:\fP prefix to signify that the X.509 extension
+\fBfieldname\fP \fBsubjectAltName\fP be searched for an rfc822Name
+(email) field to be used as the username. In cases where there are
+multiple email addresses in \fBext:fieldname\fP, the last occurrence
+is chosen.
+.sp
+When this option is used, the \fB\-\-verify\-x509\-name\fP option will match
+against the chosen \fBfieldname\fP instead of the Common Name.
+.sp
+Only the \fBsubjectAltName\fP and \fBissuerAltName\fP X.509
+extensions are supported.
+.sp
+\fBPlease note:\fP This option has a feature which will convert an
+all\-lowercase \fBfieldname\fP to uppercase characters, e.g.,
+\fBou\fP \-> \fBOU\fP\&. A mixed\-case \fBfieldname\fP or one having the
+\fBext:\fP prefix will be left as\-is. This automatic upcasing feature is
+deprecated and will be removed in a future release.
+.UNINDENT
+.SS PKCS#11 / SmartCard options
+.INDENT 0.0
+.TP
+.BI \-\-pkcs11\-cert\-private \ args
+Set if access to certificate object should be performed after login.
+Every provider has its own setting.
+.sp
+Valid syntaxes:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+pkcs11\-cert\-private 0
+pkcs11\-cert\-private 1
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.TP
+.BI \-\-pkcs11\-id \ name
+Specify the serialized certificate id to be used. The id can be gotten
+by the standalone \fB\-\-show\-pkcs11\-ids\fP option.
+.TP
+.B \-\-pkcs11\-id\-management
+Acquire PKCS#11 id from management interface. In this case a
+\fBNEED\-STR \(aqpkcs11\-id\-request\(aq\fP real\-time message will be triggered,
+application may use pkcs11\-id\-count command to retrieve available number of
+certificates, and pkcs11\-id\-get command to retrieve certificate id and
+certificate body.
+.TP
+.BI \-\-pkcs11\-pin\-cache \ seconds
+Specify how many seconds the PIN can be cached, the default is until the
+token is removed.
+.TP
+.BI \-\-pkcs11\-private\-mode \ mode
+Specify which method to use in order to perform private key operations.
+A different mode can be specified for each provider. Mode is encoded as
+hex number, and can be a mask one of the following:
+.sp
+\fB0\fP (default) Try to determine automatically.
+.sp
+\fB1\fP Use sign.
+.sp
+\fB2\fP Use sign recover.
+.sp
+\fB4\fP Use decrypt.
+.sp
+\fB8\fP Use unwrap.
+.TP
+.BI \-\-pkcs11\-protected\-authentication \ args
+Use PKCS#11 protected authentication path, useful for biometric and
+external keypad devices. Every provider has its own setting.
+.sp
+Valid syntaxes:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+pkcs11\-protected\-authentication 0
+pkcs11\-protected\-authentication 1
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.TP
+.BI \-\-pkcs11\-providers \ provider
+Specify an RSA Security Inc. PKCS #11 Cryptographic Token Interface
+(Cryptoki) providers to load. This option can be used instead of
+\fB\-\-cert\fP, \fB\-\-key\fP and \fB\-\-pkcs12\fP\&.
+.sp
+If p11\-kit is present on the system, its \fBp11\-kit\-proxy.so\fP module
+will be loaded by default if either the \fB\-\-pkcs11\-id\fP or
+\fB\-\-pkcs11\-id\-management\fP options are specified without
+\fB\-\-pkcs11\-provider\fP being given.
+.TP
+.BI \-\-show\-pkcs11\-ids \ args
+(Standalone) Show PKCS#11 token object list.
+.sp
+Valid syntax:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+show\-pkcs11 [provider] [cert_private]
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Specify \fBcert_private\fP as \fB1\fP if certificates are stored as
+private objects.
+.sp
+If \fIp11\-kit\fP is present on the system, the \fBprovider\fP argument is
+optional; if omitted the default \fBp11\-kit\-proxy.so\fP module will be
+queried.
+.sp
+\fB\-\-verb\fP option can be used BEFORE this option to produce debugging
+information.
+.UNINDENT
+.SH DATA CHANNEL CIPHER NEGOTIATION
+.sp
+OpenVPN 2.4 and higher have the capability to negotiate the data cipher that
+is used to encrypt data packets. This section describes the mechanism in more detail and the
+different backwards compatibility mechanism with older server and clients.
+.SS OpenVPN 2.5 and higher behaviour
+.sp
+When both client and server are at least running OpenVPN 2.5, that the order of
+the ciphers of the server\(aqs \fB\-\-data\-ciphers\fP is used to pick the the data cipher.
+That means that the first cipher in that list that is also in the client\(aqs
+\fB\-\-data\-ciphers\fP list is chosen. If no common cipher is found the client is rejected
+with a AUTH_FAILED message (as seen in client log):
+.INDENT 0.0
+.INDENT 3.5
+AUTH: Received control message: AUTH_FAILED,Data channel cipher negotiation failed (no shared cipher)
+.UNINDENT
+.UNINDENT
+.sp
+OpenVPN 2.5 will only allow the ciphers specified in \fB\-\-data\-ciphers\fP\&. To ensure
+backwards compatibility also if a cipher is specified using the \fB\-\-cipher\fP option
+it is automatically added to this list. If both options are unset the default is
+\fBAES\-256\-GCM:AES\-128\-GCM\fP\&.
+.SS OpenVPN 2.4 clients
+.sp
+The negotiation support in OpenVPN 2.4 was the first iteration of the implementation
+and still had some quirks. Its main goal was "upgrade to AES\-256\-GCM when possible".
+An OpenVPN 2.4 client that is built against a crypto library that supports AES in GCM
+mode and does not have \fB\-\-ncp\-disable\fP will always announce support for
+\fIAES\-256\-GCM\fP and \fIAES\-128\-GCM\fP to a server by sending \fBIV_NCP=2\fP\&.
+.sp
+This only causes a problem if \fB\-\-ncp\-ciphers\fP option has been changed from the
+default of \fBAES\-256\-GCM:AES\-128\-GCM\fP to a value that does not include
+these two ciphers. When a OpenVPN servers try to use \fIAES\-256\-GCM\fP or
+\fIAES\-128\-GCM\fP the connection will then fail. It is therefore recommended to
+always have the \fIAES\-256\-GCM\fP and \fIAES\-128\-GCM\fP ciphers to the \fB\-\-ncp\-ciphers\fP
+options to avoid this behaviour.
+.SS OpenVPN 3 clients
+.sp
+Clients based on the OpenVPN 3.x library (\fI\%https://github.com/openvpn/openvpn3/\fP)
+do not have a configurable \fB\-\-ncp\-ciphers\fP or \fB\-\-data\-ciphers\fP option. Instead
+these clients will announce support for all their supported AEAD ciphers
+(\fIAES\-256\-GCM\fP, \fIAES\-128\-GCM\fP and in newer versions also \fIChacha20\-Poly1305\fP).
+.sp
+To support OpenVPN 3.x based clients at least one of these ciphers needs to be
+included in the server\(aqs \fB\-\-data\-ciphers\fP option.
+.SS OpenVPN 2.3 and older clients (and clients with \fB\-\-ncp\-disable\fP)
+.sp
+When a client without cipher negotiation support connects to a server the
+cipher specified with the \fB\-\-cipher\fP option in the client configuration
+must be included in the \fB\-\-data\-ciphers\fP option of the server to allow
+the client to connect. Otherwise the client will be sent the \fBAUTH_FAILED\fP
+message that indicates no shared cipher.
+.sp
+If the client is 2.3 or older and has been configured with the
+\fB\-\-enable\-small\fP \fB\&./configure\fP argument, using
+\fBdata\-ciphers\-fallback cipher\fP in the server config file with the explicit
+cipher used by the client is necessary.
+.SS OpenVPN 2.4 server
+.sp
+When a client indicates support for \fIAES\-128\-GCM\fP and \fIAES\-256\-GCM\fP
+(with \fBIV_NCP=2\fP) an OpenVPN 2.4 server will send the first
+cipher of the \fB\-\-ncp\-ciphers\fP to the OpenVPN client regardless of what
+the cipher is. To emulate the behaviour of an OpenVPN 2.4 client as close
+as possible and have compatibility to a setup that depends on this quirk,
+adding \fIAES\-128\-GCM\fP and \fIAES\-256\-GCM\fP to the client\(aqs \fB\-\-data\-ciphers\fP
+option is required. OpenVPN 2.5+ will only announce the \fBIV_NCP=2\fP flag if
+those ciphers are present.
+.SS OpenVPN 2.3 and older servers (and servers with \fB\-\-ncp\-disable\fP)
+.sp
+The cipher used by the server must be included in \fB\-\-data\-ciphers\fP to
+allow the client connecting to a server without cipher negotiation
+support.
+(For compatibility OpenVPN 2.5 will also accept the cipher set with
+\fB\-\-cipher\fP)
+.sp
+If the server is 2.3 or older and has been configured with the
+\fB\-\-enable\-small\fP \fB\&./configure\fP argument, adding
+\fBdata\-ciphers\-fallback cipher\fP to the client config with the explicit
+cipher used by the server is necessary.
+.SS Blowfish in CBC mode (BF\-CBC) deprecation
+.sp
+The \fB\-\-cipher\fP option defaulted to \fBBF\-CBC\fP in OpenVPN 2.4 and older
+version. The default was never changed to ensure backwards compatibility.
+In OpenVPN 2.5 this behaviour has now been changed so that if the \fB\-\-cipher\fP
+is not explicitly set it does not allow the weak \fBBF\-CBC\fP cipher any more
+and needs to explicitly added as \fB\-\-cipher BFC\-CBC\fP or added to
+\fB\-\-data\-ciphers\fP\&.
+.sp
+We strongly recommend to switching away from BF\-CBC to a
+more secure cipher as soon as possible instead.
+.SH NETWORK CONFIGURATION
+.sp
+OpenVPN consists of two sides of network configuration. One side is the
+\fIlink\fP between the local and remote side, the other side is the \fIvirtual
+network adapter\fP (tun/tap device).
+.SS Link Options
+.sp
+This link options section covers options related to the connection between
+the local and the remote host.
+.INDENT 0.0
+.TP
+.BI \-\-bind \ keywords
+Bind to local address and port. This is the default unless any of
+\fB\-\-proto tcp\-client\fP , \fB\-\-http\-proxy\fP or \fB\-\-socks\-proxy\fP are used.
+.sp
+If the optional \fBipv6only\fP keyword is present OpenVPN will bind only
+to IPv6 (as opposed to IPv6 and IPv4) when a IPv6 socket is opened.
+.TP
+.B \-\-float
+Allow remote peer to change its IP address and/or port number, such as
+due to DHCP (this is the default if \fB\-\-remote\fP is not used).
+\fB\-\-float\fP when specified with \fB\-\-remote\fP allows an OpenVPN session
+to initially connect to a peer at a known address, however if packets
+arrive from a new address and pass all authentication tests, the new
+address will take control of the session. This is useful when you are
+connecting to a peer which holds a dynamic address such as a dial\-in
+user or DHCP client.
+.sp
+Essentially, \fB\-\-float\fP tells OpenVPN to accept authenticated packets
+from any address, not only the address which was specified in the
+\fB\-\-remote\fP option.
+.TP
+.BI \-\-fragment \ max
+Enable internal datagram fragmentation so that no UDP datagrams are sent
+which are larger than \fBmax\fP bytes.
+.sp
+The \fBmax\fP parameter is interpreted in the same way as the
+\fB\-\-link\-mtu\fP parameter, i.e. the UDP packet size after encapsulation
+overhead has been added in, but not including the UDP header itself.
+.sp
+The \fB\-\-fragment\fP option only makes sense when you are using the UDP
+protocol (\fB\-\-proto udp\fP).
+.sp
+\fB\-\-fragment\fP adds 4 bytes of overhead per datagram.
+.sp
+See the \fB\-\-mssfix\fP option below for an important related option to
+\fB\-\-fragment\fP\&.
+.sp
+It should also be noted that this option is not meant to replace UDP
+fragmentation at the IP stack level. It is only meant as a last resort
+when path MTU discovery is broken. Using this option is less efficient
+than fixing path MTU discovery for your IP link and using native IP
+fragmentation instead.
+.sp
+Having said that, there are circumstances where using OpenVPN\(aqs internal
+fragmentation capability may be your only option, such as tunneling a
+UDP multicast stream which requires fragmentation.
+.TP
+.BI \-\-keepalive \ args
+A helper directive designed to simplify the expression of \fB\-\-ping\fP and
+\fB\-\-ping\-restart\fP\&.
+.sp
+Valid syntax:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+keepalive interval timeout
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+This option can be used on both client and server side, but it is enough
+to add this on the server side as it will push appropriate \fB\-\-ping\fP
+and \fB\-\-ping\-restart\fP options to the client. If used on both server and
+client, the values pushed from server will override the client local
+values.
+.sp
+The \fBtimeout\fP argument will be twice as long on the server side. This
+ensures that a timeout is detected on client side before the server side
+drops the connection.
+.sp
+For example, \fB\-\-keepalive 10 60\fP expands as follows:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+if mode server:
+ ping 10 # Argument: interval
+ ping\-restart 120 # Argument: timeout*2
+ push "ping 10" # Argument: interval
+ push "ping\-restart 60" # Argument: timeout
+else
+ ping 10 # Argument: interval
+ ping\-restart 60 # Argument: timeout
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.TP
+.BI \-\-link\-mtu \ n
+Sets an upper bound on the size of UDP packets which are sent between
+OpenVPN peers. \fIIt\(aqs best not to set this parameter unless you know what
+you\(aqre doing.\fP
+.TP
+.BI \-\-local \ host
+Local host name or IP address for bind. If specified, OpenVPN will bind
+to this address only. If unspecified, OpenVPN will bind to all
+interfaces.
+.TP
+.BI \-\-lport \ port
+Set local TCP/UDP port number or name. Cannot be used together with
+\fB\-\-nobind\fP option.
+.TP
+.BI \-\-mark \ value
+Mark encrypted packets being sent with value. The mark value can be
+matched in policy routing and packetfilter rules. This option is only
+supported in Linux and does nothing on other operating systems.
+.TP
+.BI \-\-mode \ m
+Set OpenVPN major mode. By default, OpenVPN runs in point\-to\-point mode
+(\fBp2p\fP). OpenVPN 2.0 introduces a new mode (\fBserver\fP) which
+implements a multi\-client server capability.
+.TP
+.BI \-\-mssfix \ max
+Announce to TCP sessions running over the tunnel that they should limit
+their send packet sizes such that after OpenVPN has encapsulated them,
+the resulting UDP packet size that OpenVPN sends to its peer will not
+exceed \fBmax\fP bytes. The default value is \fB1450\fP\&.
+.sp
+The \fBmax\fP parameter is interpreted in the same way as the
+\fB\-\-link\-mtu\fP parameter, i.e. the UDP packet size after encapsulation
+overhead has been added in, but not including the UDP header itself.
+Resulting packet would be at most 28 bytes larger for IPv4 and 48 bytes
+for IPv6 (20/40 bytes for IP header and 8 bytes for UDP header). Default
+value of 1450 allows IPv4 packets to be transmitted over a link with MTU
+1473 or higher without IP level fragmentation.
+.sp
+The \fB\-\-mssfix\fP option only makes sense when you are using the UDP
+protocol for OpenVPN peer\-to\-peer communication, i.e. \fB\-\-proto udp\fP\&.
+.sp
+\fB\-\-mssfix\fP and \fB\-\-fragment\fP can be ideally used together, where
+\fB\-\-mssfix\fP will try to keep TCP from needing packet fragmentation in
+the first place, and if big packets come through anyhow (from protocols
+other than TCP), \fB\-\-fragment\fP will internally fragment them.
+.sp
+Both \fB\-\-fragment\fP and \fB\-\-mssfix\fP are designed to work around cases
+where Path MTU discovery is broken on the network path between OpenVPN
+peers.
+.sp
+The usual symptom of such a breakdown is an OpenVPN connection which
+successfully starts, but then stalls during active usage.
+.sp
+If \fB\-\-fragment\fP and \fB\-\-mssfix\fP are used together, \fB\-\-mssfix\fP will
+take its default \fBmax\fP parameter from the \fB\-\-fragment max\fP option.
+.sp
+Therefore, one could lower the maximum UDP packet size to 1300 (a good
+first try for solving MTU\-related connection problems) with the
+following options:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+\-\-tun\-mtu 1500 \-\-fragment 1300 \-\-mssfix
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.TP
+.BI \-\-mtu\-disc \ type
+Should we do Path MTU discovery on TCP/UDP channel? Only supported on
+OSes such as Linux that supports the necessary system call to set.
+.sp
+Valid types:
+.sp
+\fBno\fP Never send DF (Don\(aqt Fragment) frames
+.sp
+\fBmaybe\fP Use per\-route hints
+.sp
+\fByes\fP Always DF (Don\(aqt Fragment)
+.TP
+.B \-\-mtu\-test
+To empirically measure MTU on connection startup, add the \fB\-\-mtu\-test\fP
+option to your configuration. OpenVPN will send ping packets of various
+sizes to the remote peer and measure the largest packets which were
+successfully received. The \fB\-\-mtu\-test\fP process normally takes about 3
+minutes to complete.
+.TP
+.B \-\-nobind
+Do not bind to local address and port. The IP stack will allocate a
+dynamic port for returning packets. Since the value of the dynamic port
+could not be known in advance by a peer, this option is only suitable
+for peers which will be initiating connections by using the \-\-remote
+option.
+.TP
+.B \-\-passtos
+Set the TOS field of the tunnel packet to what the payload\(aqs TOS is.
+.TP
+.BI \-\-ping \ n
+Ping remote over the TCP/UDP control channel if no packets have been
+sent for at least \fBn\fP seconds (specify \fB\-\-ping\fP on both peers to
+cause ping packets to be sent in both directions since OpenVPN ping
+packets are not echoed like IP ping packets). When used in one of
+OpenVPN\(aqs secure modes (where \fB\-\-secret\fP, \fB\-\-tls\-server\fP or
+\fB\-\-tls\-client\fP is specified), the ping packet will be
+cryptographically secure.
+.sp
+This option has two intended uses:
+.INDENT 7.0
+.IP 1. 3
+Compatibility with stateful firewalls. The periodic ping will ensure
+that a stateful firewall rule which allows OpenVPN UDP packets to
+pass will not time out.
+.IP 2. 3
+To provide a basis for the remote to test the existence of its peer
+using the \fB\-\-ping\-exit\fP option.
+.UNINDENT
+.TP
+.BI \-\-ping\-exit \ n
+Causes OpenVPN to exit after \fBn\fP seconds pass without reception of a
+ping or other packet from remote. This option can be combined with
+\fB\-\-inactive\fP, \fB\-\-ping\fP and \fB\-\-ping\-exit\fP to create a two\-tiered
+inactivity disconnect.
+.sp
+For example,
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+openvpn [options...] \-\-inactive 3600 \-\-ping 10 \-\-ping\-exit 60
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+when used on both peers will cause OpenVPN to exit within 60 seconds if
+its peer disconnects, but will exit after one hour if no actual tunnel
+data is exchanged.
+.TP
+.BI \-\-ping\-restart \ n
+Similar to \fB\-\-ping\-exit\fP, but trigger a \fBSIGUSR1\fP restart after
+\fBn\fP seconds pass without reception of a ping or other packet from
+remote.
+.sp
+This option is useful in cases where the remote peer has a dynamic IP
+address and a low\-TTL DNS name is used to track the IP address using a
+service such as \fI\%http://dyndns.org/\fP + a dynamic DNS client such as
+\fBddclient\fP\&.
+.sp
+If the peer cannot be reached, a restart will be triggered, causing the
+hostname used with \fB\-\-remote\fP to be re\-resolved (if \fB\-\-resolv\-retry\fP
+is also specified).
+.sp
+In server mode, \fB\-\-ping\-restart\fP, \fB\-\-inactive\fP or any other type of
+internally generated signal will always be applied to individual client
+instance objects, never to whole server itself. Note also in server mode
+that any internally generated signal which would normally cause a
+restart, will cause the deletion of the client instance object instead.
+.sp
+In client mode, the \fB\-\-ping\-restart\fP parameter is set to 120 seconds
+by default. This default will hold until the client pulls a replacement
+value from the server, based on the \fB\-\-keepalive\fP setting in the
+server configuration. To disable the 120 second default, set
+\fB\-\-ping\-restart 0\fP on the client.
+.sp
+See the signals section below for more information on \fBSIGUSR1\fP\&.
+.sp
+Note that the behavior of \fBSIGUSR1\fP can be modified by the
+\fB\-\-persist\-tun\fP, \fB\-\-persist\-key\fP, \fB\-\-persist\-local\-ip\fP and
+\fB\-\-persist\-remote\-ip\fP options.
+.sp
+Also note that \fB\-\-ping\-exit\fP and \fB\-\-ping\-restart\fP are mutually
+exclusive and cannot be used together.
+.TP
+.B \-\-ping\-timer\-rem
+Run the \fB\-\-ping\-exit\fP / \fB\-\-ping\-restart\fP timer only if we have a
+remote address. Use this option if you are starting the daemon in listen
+mode (i.e. without an explicit \fB\-\-remote\fP peer), and you don\(aqt want to
+start clocking timeouts until a remote peer connects.
+.TP
+.BI \-\-proto \ p
+Use protocol \fBp\fP for communicating with remote host. \fBp\fP can be
+\fBudp\fP, \fBtcp\-client\fP, or \fBtcp\-server\fP\&.
+.sp
+The default protocol is \fBudp\fP when \fB\-\-proto\fP is not specified.
+.sp
+For UDP operation, \fB\-\-proto udp\fP should be specified on both peers.
+.sp
+For TCP operation, one peer must use \fB\-\-proto tcp\-server\fP and the
+other must use \fB\-\-proto tcp\-client\fP\&. A peer started with
+\fBtcp\-server\fP will wait indefinitely for an incoming connection. A peer
+started with \fBtcp\-client\fP will attempt to connect, and if that fails,
+will sleep for 5 seconds (adjustable via the \fB\-\-connect\-retry\fP option)
+and try again infinite or up to N retries (adjustable via the
+\fB\-\-connect\-retry\-max\fP option). Both TCP client and server will
+simulate a SIGUSR1 restart signal if either side resets the connection.
+.sp
+OpenVPN is designed to operate optimally over UDP, but TCP capability is
+provided for situations where UDP cannot be used. In comparison with
+UDP, TCP will usually be somewhat less efficient and less robust when
+used over unreliable or congested networks.
+.sp
+This article outlines some of problems with tunneling IP over TCP:
+\fI\%http://sites.inka.de/sites/bigred/devel/tcp\-tcp.html\fP
+.sp
+There are certain cases, however, where using TCP may be advantageous
+from a security and robustness perspective, such as tunneling non\-IP or
+application\-level UDP protocols, or tunneling protocols which don\(aqt
+possess a built\-in reliability layer.
+.TP
+.BI \-\-port \ port
+TCP/UDP port number or port name for both local and remote (sets both
+\fB\-\-lport\fP and \fB\-\-rport\fP options to given port). The current default
+of 1194 represents the official IANA port number assignment for OpenVPN
+and has been used since version 2.0\-beta17. Previous versions used port
+5000 as the default.
+.TP
+.BI \-\-rport \ port
+Set TCP/UDP port number or name used by the \fB\-\-remote\fP option. The
+port can also be set directly using the \fB\-\-remote\fP option.
+.TP
+.BI \-\-replay\-window \ args
+Modify the replay protection sliding\-window size and time window.
+.sp
+Valid syntax:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+replay\-window n [t]
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Use a replay protection sliding\-window of size \fBn\fP and a time window
+of \fBt\fP seconds.
+.sp
+By default \fBn\fP is 64 (the IPSec default) and \fBt\fP is 15 seconds.
+.sp
+This option is only relevant in UDP mode, i.e. when either \fB\-\-proto
+udp\fP is specified, or no \fB\-\-proto\fP option is specified.
+.sp
+When OpenVPN tunnels IP packets over UDP, there is the possibility that
+packets might be dropped or delivered out of order. Because OpenVPN,
+like IPSec, is emulating the physical network layer, it will accept an
+out\-of\-order packet sequence, and will deliver such packets in the same
+order they were received to the TCP/IP protocol stack, provided they
+satisfy several constraints.
+.INDENT 7.0
+.IP a. 3
+The packet cannot be a replay (unless \fB\-\-no\-replay\fP is
+specified, which disables replay protection altogether).
+.IP b. 3
+If a packet arrives out of order, it will only be accepted if
+the difference between its sequence number and the highest sequence
+number received so far is less than \fBn\fP\&.
+.IP c. 3
+If a packet arrives out of order, it will only be accepted if it
+arrives no later than \fBt\fP seconds after any packet containing a higher
+sequence number.
+.UNINDENT
+.sp
+If you are using a network link with a large pipeline (meaning that the
+product of bandwidth and latency is high), you may want to use a larger
+value for \fBn\fP\&. Satellite links in particular often require this.
+.sp
+If you run OpenVPN at \fB\-\-verb 4\fP, you will see the message
+"Replay\-window backtrack occurred [x]" every time the maximum sequence
+number backtrack seen thus far increases. This can be used to calibrate
+\fBn\fP\&.
+.sp
+There is some controversy on the appropriate method of handling packet
+reordering at the security layer.
+.sp
+Namely, to what extent should the security layer protect the
+encapsulated protocol from attacks which masquerade as the kinds of
+normal packet loss and reordering that occur over IP networks?
+.sp
+The IPSec and OpenVPN approach is to allow packet reordering within a
+certain fixed sequence number window.
+.sp
+OpenVPN adds to the IPSec model by limiting the window size in time as
+well as sequence space.
+.sp
+OpenVPN also adds TCP transport as an option (not offered by IPSec) in
+which case OpenVPN can adopt a very strict attitude towards message
+deletion and reordering: Don\(aqt allow it. Since TCP guarantees
+reliability, any packet loss or reordering event can be assumed to be an
+attack.
+.sp
+In this sense, it could be argued that TCP tunnel transport is preferred
+when tunneling non\-IP or UDP application protocols which might be
+vulnerable to a message deletion or reordering attack which falls within
+the normal operational parameters of IP networks.
+.sp
+So I would make the statement that one should never tunnel a non\-IP
+protocol or UDP application protocol over UDP, if the protocol might be
+vulnerable to a message deletion or reordering attack that falls within
+the normal operating parameters of what is to be expected from the
+physical IP layer. The problem is easily fixed by simply using TCP as
+the VPN transport layer.
+.TP
+.BI \-\-replay\-persist \ file
+Persist replay\-protection state across sessions using \fBfile\fP to save
+and reload the state.
+.sp
+This option will strengthen protection against replay attacks,
+especially when you are using OpenVPN in a dynamic context (such as with
+\fB\-\-inetd\fP) when OpenVPN sessions are frequently started and stopped.
+.sp
+This option will keep a disk copy of the current replay protection state
+(i.e. the most recent packet timestamp and sequence number received from
+the remote peer), so that if an OpenVPN session is stopped and
+restarted, it will reject any replays of packets which were already
+received by the prior session.
+.sp
+This option only makes sense when replay protection is enabled (the
+default) and you are using either \fB\-\-secret\fP (shared\-secret key mode)
+or TLS mode with \fB\-\-tls\-auth\fP\&.
+.TP
+.BI \-\-socket\-flags \ flags
+Apply the given flags to the OpenVPN transport socket. Currently, only
+\fBTCP_NODELAY\fP is supported.
+.sp
+The \fBTCP_NODELAY\fP socket flag is useful in TCP mode, and causes the
+kernel to send tunnel packets immediately over the TCP connection without
+trying to group several smaller packets into a larger packet. This can
+result in a considerably improvement in latency.
+.sp
+This option is pushable from server to client, and should be used on
+both client and server for maximum effect.
+.TP
+.B \-\-tcp\-nodelay
+This macro sets the \fBTCP_NODELAY\fP socket flag on the server as well
+as pushes it to connecting clients. The \fBTCP_NODELAY\fP flag disables
+the Nagle algorithm on TCP sockets causing packets to be transmitted
+immediately with low latency, rather than waiting a short period of time
+in order to aggregate several packets into a larger containing packet.
+In VPN applications over TCP, \fBTCP_NODELAY\fP is generally a good
+latency optimization.
+.sp
+The macro expands as follows:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+if mode server:
+ socket\-flags TCP_NODELAY
+ push "socket\-flags TCP_NODELAY"
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.SS Virtual Network Adapter (VPN interface)
+.sp
+Options in this section relates to configuration of the virtual tun/tap
+network interface, including setting the VPN IP address and network
+routing.
+.INDENT 0.0
+.TP
+.BI \-\-bind\-dev \ device
+(Linux only) Set \fBdevice\fP to bind the server socket to a
+\fI\%Virtual Routing and Forwarding\fP device
+.TP
+.B \-\-block\-ipv6
+On the client, instead of sending IPv6 packets over the VPN tunnel, all
+IPv6 packets are answered with an ICMPv6 no route host message. On the
+server, all IPv6 packets from clients are answered with an ICMPv6 no
+route to host message. This options is intended for cases when IPv6
+should be blocked and other options are not available. \fB\-\-block\-ipv6\fP
+will use the remote IPv6 as source address of the ICMPv6 packets if set,
+otherwise will use \fBfe80::7\fP as source address.
+.sp
+For this option to make sense you actually have to route traffic to the
+tun interface. The following example config block would send all IPv6
+traffic to OpenVPN and answer all requests with no route to host,
+effectively blocking IPv6.
+.INDENT 7.0
+.TP
+.B \fBClient config\fP
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+\-\-ifconfig\-ipv6 fd15:53b6:dead::2/64 fd15:53b6:dead::1
+\-\-redirect\-gateway ipv6
+\-\-block\-ipv6
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.TP
+.B \fBServer config\fP
+Push a "valid" ipv6 config to the client and block on the server
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+\-\-push "ifconfig\-ipv6 fd15:53b6:dead::2/64 fd15:53b6:dead::1"
+\-\-push "redirect\-gateway ipv6"
+\-\-block\-ipv6
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.TP
+.BI \-\-dev \ device
+TUN/TAP virtual network device which can be \fBtunX\fP, \fBtapX\fP,
+\fBnull\fP or an arbitrary name string (\fBX\fP can be omitted for
+a dynamic device.)
+.sp
+See examples section below for an example on setting up a TUN device.
+.sp
+You must use either tun devices on both ends of the connection or tap
+devices on both ends. You cannot mix them, as they represent different
+underlying network layers:
+.INDENT 7.0
+.TP
+.B \fBtun\fP
+devices encapsulate IPv4 or IPv6 (OSI Layer 3)
+.TP
+.B \fBtap\fP
+devices encapsulate Ethernet 802.3 (OSI Layer 2).
+.UNINDENT
+.sp
+Valid syntaxes:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+dev tun2
+dev tap4
+dev ovpn
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+When the device name starts with \fBtun\fP or \fBtap\fP, the device
+type is extracted automatically. Otherwise the \fB\-\-dev\-type\fP option
+needs to be added as well.
+.TP
+.BI \-\-dev\-node \ node
+Explicitly set the device node rather than using \fB/dev/net/tun\fP,
+\fB/dev/tun\fP, \fB/dev/tap\fP, etc. If OpenVPN cannot figure out
+whether \fBnode\fP is a TUN or TAP device based on the name, you should
+also specify \fB\-\-dev\-type tun\fP or \fB\-\-dev\-type tap\fP\&.
+.sp
+Under Mac OS X this option can be used to specify the default tun
+implementation. Using \fB\-\-dev\-node utun\fP forces usage of the native
+Darwin tun kernel support. Use \fB\-\-dev\-node utunN\fP to select a specific
+utun instance. To force using the \fBtun.kext\fP (\fB/dev/tunX\fP)
+use \fB\-\-dev\-node tun\fP\&. When not specifying a \fB\-\-dev\-node\fP option
+openvpn will first try to open utun, and fall back to tun.kext.
+.sp
+On Windows systems, select the TAP\-Win32 adapter which is named \fBnode\fP
+in the Network Connections Control Panel or the raw GUID of the adapter
+enclosed by braces. The \fB\-\-show\-adapters\fP option under Windows can
+also be used to enumerate all available TAP\-Win32 adapters and will show
+both the network connections control panel name and the GUID for each
+TAP\-Win32 adapter.
+.TP
+.BI \-\-dev\-type \ device\-type
+Which device type are we using? \fBdevice\-type\fP should be \fBtun\fP
+(OSI Layer 3) or \fBtap\fP (OSI Layer 2). Use this option only if
+the TUN/TAP device used with \fB\-\-dev\fP does not begin with \fBtun\fP
+or \fBtap\fP\&.
+.TP
+.BI \-\-dhcp\-option \ args
+Set additional network parameters on supported platforms. May be specified
+on the client or pushed from the server. On Windows these options are
+handled by the \fBtap\-windows6\fP driver by default or directly by OpenVPN
+if dhcp is disabled or the \fBwintun\fP driver is in use. The
+\fBOpenVPN for Android\fP client also handles them internally.
+.sp
+On all other platforms these options are only saved in the client\(aqs
+environment under the name \fBforeign_options_{n}\fP before the
+\fB\-\-up\fP script is called. A plugin or an \fB\-\-up\fP script must be used to
+pick up and interpret these as required. Many Linux distributions include
+such scripts and some third\-party user interfaces such as tunnelblick also
+come with scripts that process these options.
+.sp
+Valid syntax:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+dhcp\-options type [parm]
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.INDENT 7.0
+.TP
+.B \fBDOMAIN\fP \fBname\fP
+Set Connection\-specific DNS Suffix to \fBname\fP\&.
+.TP
+.B \fBDOMAIN\-SEARCH\fP \fBname\fP
+Add \fBname\fP to the domain search list.
+Repeat this option to add more entries. Up to
+10 domains are supported.
+.TP
+.B \fBDNS\fP \fBaddress\fP
+Set primary domain name server IPv4 or IPv6 address.
+Repeat this option to set secondary DNS server addresses.
+.sp
+Note: DNS IPv6 servers are currently set using netsh (the existing
+DHCP code can only do IPv4 DHCP, and that protocol only permits
+IPv4 addresses anywhere). The option will be put into the
+environment, so an \fB\-\-up\fP script could act upon it if needed.
+.TP
+.B \fBWINS\fP \fBaddress\fP
+Set primary WINS server address (NetBIOS over TCP/IP Name Server).
+Repeat this option to set secondary WINS server addresses.
+.TP
+.B \fBNBDD\fP \fBaddress\fP
+Set primary NBDD server address (NetBIOS over TCP/IP Datagram
+Distribution Server). Repeat this option to set secondary NBDD
+server addresses.
+.TP
+.B \fBNTP\fP \fBaddress\fP
+Set primary NTP server address (Network Time Protocol).
+Repeat this option to set secondary NTP server addresses.
+.TP
+.B \fBNBT\fP \fBtype\fP
+Set NetBIOS over TCP/IP Node type. Possible options:
+.INDENT 7.0
+.TP
+.B \fB1\fP
+b\-node (broadcasts)
+.TP
+.B \fB2\fP
+p\-node (point\-to\-point name queries to a WINS server)
+.TP
+.B \fB4\fP
+m\-node (broadcast then query name server)
+.TP
+.B \fB8\fP
+h\-node (query name server, then broadcast).
+.UNINDENT
+.TP
+.B \fBNBS\fP \fBscope\-id\fP
+Set NetBIOS over TCP/IP Scope. A NetBIOS Scope ID provides an
+extended naming service for the NetBIOS over TCP/IP (Known as NBT)
+module. The primary purpose of a NetBIOS scope ID is to isolate
+NetBIOS traffic on a single network to only those nodes with the
+same NetBIOS scope ID. The NetBIOS scope ID is a character string
+that is appended to the NetBIOS name. The NetBIOS scope ID on two
+hosts must match, or the two hosts will not be able to communicate.
+The NetBIOS Scope ID also allows computers to use the same computer
+name, as they have different scope IDs. The Scope ID becomes a part
+of the NetBIOS name, making the name unique. (This description of
+NetBIOS scopes courtesy of \fI\%NeonSurge@abyss.com\fP)
+.TP
+.B \fBDISABLE\-NBT\fP
+Disable Netbios\-over\-TCP/IP.
+.UNINDENT
+.TP
+.BI \-\-ifconfig \ args
+Set TUN/TAP adapter parameters. It requires the \fIIP address\fP of the local
+VPN endpoint. For TUN devices in point\-to\-point mode, the next argument
+must be the VPN IP address of the remote VPN endpoint. For TAP devices,
+or TUN devices used with \fB\-\-topology subnet\fP, the second argument
+is the subnet mask of the virtual network segment which is being created
+or connected to.
+.sp
+For TUN devices, which facilitate virtual point\-to\-point IP connections
+(when used in \fB\-\-topology net30\fP or \fBp2p\fP mode), the proper usage of
+\fB\-\-ifconfig\fP is to use two private IP addresses which are not a member
+of any existing subnet which is in use. The IP addresses may be
+consecutive and should have their order reversed on the remote peer.
+After the VPN is established, by pinging \fBrn\fP, you will be pinging
+across the VPN.
+.sp
+For TAP devices, which provide the ability to create virtual ethernet
+segments, or TUN devices in \fB\-\-topology subnet\fP mode (which create
+virtual "multipoint networks"), \fB\-\-ifconfig\fP is used to set an IP
+address and subnet mask just as a physical ethernet adapter would be
+similarly configured. If you are attempting to connect to a remote
+ethernet bridge, the IP address and subnet should be set to values which
+would be valid on the the bridged ethernet segment (note also that DHCP
+can be used for the same purpose).
+.sp
+This option, while primarily a proxy for the \fBifconfig\fP(8) command,
+is designed to simplify TUN/TAP tunnel configuration by providing a
+standard interface to the different ifconfig implementations on
+different platforms.
+.sp
+\fB\-\-ifconfig\fP parameters which are IP addresses can also be specified
+as a DNS or /etc/hosts file resolvable name.
+.sp
+For TAP devices, \fB\-\-ifconfig\fP should not be used if the TAP interface
+will be getting an IP address lease from a DHCP server.
+.sp
+Examples:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+# tun device in net30/p2p mode
+ifconfig 10.8.0.2 10.8.0.1
+
+# tun/tap device in subnet mode
+ifconfig 10.8.0.2 255.255.255.0
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.TP
+.BI \-\-ifconfig\-ipv6 \ args
+Configure an IPv6 address on the \fItun\fP device.
+.sp
+Valid syntax:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+ifconfig\-ipv6 ipv6addr/bits [ipv6remote]
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The \fBipv6addr/bits\fP argument is the IPv6 address to use. The
+second parameter is used as route target for \fB\-\-route\-ipv6\fP if no
+gateway is specified.
+.sp
+The \fB\-\-topology\fP option has no influence with \fB\-\-ifconfig\-ipv6\fP
+.TP
+.B \-\-ifconfig\-noexec
+Don\(aqt actually execute ifconfig/netsh commands, instead pass
+\fB\-\-ifconfig\fP parameters to scripts using environmental variables.
+.TP
+.B \-\-ifconfig\-nowarn
+Don\(aqt output an options consistency check warning if the \fB\-\-ifconfig\fP
+option on this side of the connection doesn\(aqt match the remote side.
+This is useful when you want to retain the overall benefits of the
+options consistency check (also see \fB\-\-disable\-occ\fP option) while only
+disabling the ifconfig component of the check.
+.sp
+For example, if you have a configuration where the local host uses
+\fB\-\-ifconfig\fP but the remote host does not, use \fB\-\-ifconfig\-nowarn\fP
+on the local host.
+.sp
+This option will also silence warnings about potential address conflicts
+which occasionally annoy more experienced users by triggering "false
+positive" warnings.
+.TP
+.BI \-\-lladdr \ address
+Specify the link layer address, more commonly known as the MAC address.
+Only applied to TAP devices.
+.TP
+.B \-\-persist\-tun
+Don\(aqt close and reopen TUN/TAP device or run up/down scripts across
+\fBSIGUSR1\fP or \fB\-\-ping\-restart\fP restarts.
+.sp
+\fBSIGUSR1\fP is a restart signal similar to \fBSIGHUP\fP, but which
+offers finer\-grained control over reset options.
+.TP
+.BI \-\-redirect\-gateway \ flags
+Automatically execute routing commands to cause all outgoing IP traffic
+to be redirected over the VPN. This is a client\-side option.
+.sp
+This option performs three steps:
+.INDENT 7.0
+.IP 1. 3
+Create a static route for the \fB\-\-remote\fP address which
+forwards to the pre\-existing default gateway. This is done so that
+\fB(3)\fP will not create a routing loop.
+.IP 2. 3
+Delete the default gateway route.
+.IP 3. 3
+Set the new default gateway to be the VPN endpoint address
+(derived either from \fB\-\-route\-gateway\fP or the second parameter to
+\fB\-\-ifconfig\fP when \fB\-\-dev tun\fP is specified).
+.UNINDENT
+.sp
+When the tunnel is torn down, all of the above steps are reversed so
+that the original default route is restored.
+.sp
+Option flags:
+.INDENT 7.0
+.TP
+.B \fBlocal\fP
+Add the \fBlocal\fP flag if both OpenVPN peers are directly
+connected via a common subnet, such as with wireless. The
+\fBlocal\fP flag will cause step \fB(1)\fP above to be omitted.
+.TP
+.B \fBautolocal\fP
+Try to automatically determine whether to enable \fBlocal\fP
+flag above.
+.TP
+.B \fBdef1\fP
+Use this flag to override the default gateway by using
+\fB0.0.0.0/1\fP and \fB128.0.0.0/1\fP rather than
+\fB0.0.0.0/0\fP\&. This has the benefit of overriding but not
+wiping out the original default gateway.
+.TP
+.B \fBbypass\-dhcp\fP
+Add a direct route to the DHCP server (if it is non\-local) which
+bypasses the tunnel (Available on Windows clients, may not be
+available on non\-Windows clients).
+.TP
+.B \fBbypass\-dns\fP
+Add a direct route to the DNS server(s) (if they are non\-local)
+which bypasses the tunnel (Available on Windows clients, may
+not be available on non\-Windows clients).
+.TP
+.B \fBblock\-local\fP
+Block access to local LAN when the tunnel is active, except for
+the LAN gateway itself. This is accomplished by routing the local
+LAN (except for the LAN gateway address) into the tunnel.
+.TP
+.B \fBipv6\fP
+Redirect IPv6 routing into the tunnel. This works similar to
+the \fBdef1\fP flag, that is, more specific IPv6 routes are added
+(\fB2000::/4\fP, \fB3000::/4\fP), covering the whole IPv6
+unicast space.
+.TP
+.B \fB!ipv4\fP
+Do not redirect IPv4 traffic \- typically used in the flag pair
+\fBipv6 !ipv4\fP to redirect IPv6\-only.
+.UNINDENT
+.TP
+.BI \-\-redirect\-private \ flags
+Like \fB\-\-redirect\-gateway\fP, but omit actually changing the default gateway.
+Useful when pushing private subnets.
+.TP
+.BI \-\-route \ args
+Add route to routing table after connection is established. Multiple
+routes can be specified. Routes will be automatically torn down in
+reverse order prior to TUN/TAP device close.
+.sp
+Valid syntaxes:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+route network/IP
+route network/IP netmask
+route network/IP netmask gateway
+route network/IP netmask gateway metric
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+This option is intended as a convenience proxy for the \fBroute\fP(8)
+shell command, while at the same time providing portable semantics
+across OpenVPN\(aqs platform space.
+.INDENT 7.0
+.TP
+.B \fBnetmask\fP
+defaults to \fB255.255.255.255\fP when not given
+.TP
+.B \fBgateway\fP
+default taken from \fB\-\-route\-gateway\fP or the second
+parameter to \fB\-\-ifconfig\fP when \fB\-\-dev tun\fP is specified.
+.TP
+.B \fBmetric\fP
+default taken from \fB\-\-route\-metric\fP if set, otherwise \fB0\fP\&.
+.UNINDENT
+.sp
+The default can be specified by leaving an option blank or setting it to
+\fBdefault\fP\&.
+.sp
+The \fBnetwork\fP and \fBgateway\fP parameters can also be specified as a
+DNS or \fB/etc/hosts\fP file resolvable name, or as one of three special
+keywords:
+.INDENT 7.0
+.TP
+.B \fBvpn_gateway\fP
+The remote VPN endpoint address (derived either from
+\fB\-\-route\-gateway\fP or the second parameter to \fB\-\-ifconfig\fP
+when \fB\-\-dev tun\fP is specified).
+.TP
+.B \fBnet_gateway\fP
+The pre\-existing IP default gateway, read from the
+routing table (not supported on all OSes).
+.TP
+.B \fBremote_host\fP
+The \fB\-\-remote\fP address if OpenVPN is being run in
+client mode, and is undefined in server mode.
+.UNINDENT
+.TP
+.BI \-\-route\-delay \ args
+Valid syntaxes:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+route\-delay
+route\-delay n
+route\-delay n m
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Delay \fBn\fP seconds (default \fB0\fP) after connection establishment,
+before adding routes. If \fBn\fP is \fB0\fP, routes will be added
+immediately upon connection establishment. If \fB\-\-route\-delay\fP is
+omitted, routes will be added immediately after TUN/TAP device open and
+\fB\-\-up\fP script execution, before any \fB\-\-user\fP or \fB\-\-group\fP privilege
+downgrade (or \fB\-\-chroot\fP execution.)
+.sp
+This option is designed to be useful in scenarios where DHCP is used to
+set tap adapter addresses. The delay will give the DHCP handshake time
+to complete before routes are added.
+.sp
+On Windows, \fB\-\-route\-delay\fP tries to be more intelligent by waiting
+\fBw\fP seconds (default \fB30\fP by default) for the TAP\-Win32 adapter
+to come up before adding routes.
+.TP
+.BI \-\-route\-ipv6 \ args
+Setup IPv6 routing in the system to send the specified IPv6 network into
+OpenVPN\(aqs \fItun\fP\&.
+.sp
+Valid syntax:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+route\-ipv6 ipv6addr/bits [gateway] [metric]
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The gateway parameter is only used for IPv6 routes across \fItap\fP devices,
+and if missing, the \fBipv6remote\fP field from \fB\-\-ifconfig\-ipv6\fP or
+\fB\-\-route\-ipv6\-gateway\fP is used.
+.TP
+.BI \-\-route\-gateway \ arg
+Specify a default \fIgateway\fP for use with \fB\-\-route\fP\&.
+.sp
+If \fBdhcp\fP is specified as the parameter, the gateway address will
+be extracted from a DHCP negotiation with the OpenVPN server\-side LAN.
+.sp
+Valid syntaxes:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+route\-gateway gateway
+route\-gateway dhcp
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.TP
+.BI \-\-route\-ipv6\-gateway \ gw
+Specify a default gateway \fBgw\fP for use with \fB\-\-route\-ipv6\fP\&.
+.TP
+.BI \-\-route\-metric \ m
+Specify a default metric \fBm\fP for use with \fB\-\-route\fP\&.
+.TP
+.B \-\-route\-noexec
+Don\(aqt add or remove routes automatically. Instead pass routes to
+\fB\-\-route\-up\fP script using environmental variables.
+.TP
+.B \-\-route\-nopull
+When used with \fB\-\-client\fP or \fB\-\-pull\fP, accept options pushed by
+server EXCEPT for routes, block\-outside\-dns and dhcp options like DNS
+servers.
+.sp
+When used on the client, this option effectively bars the server from
+adding routes to the client\(aqs routing table, however note that this
+option still allows the server to set the TCP/IP properties of the
+client\(aqs TUN/TAP interface.
+.TP
+.BI \-\-topology \ mode
+Configure virtual addressing topology when running in \fB\-\-dev tun\fP
+mode. This directive has no meaning in \fB\-\-dev tap\fP mode, which always
+uses a \fBsubnet\fP topology.
+.sp
+If you set this directive on the server, the \fB\-\-server\fP and
+\fB\-\-server\-bridge\fP directives will automatically push your chosen
+topology setting to clients as well. This directive can also be manually
+pushed to clients. Like the \fB\-\-dev\fP directive, this directive must
+always be compatible between client and server.
+.sp
+\fBmode\fP can be one of:
+.INDENT 7.0
+.TP
+.B \fBnet30\fP
+Use a point\-to\-point topology, by allocating one /30 subnet
+per client. This is designed to allow point\-to\-point semantics when some
+or all of the connecting clients might be Windows systems. This is the
+default on OpenVPN 2.0.
+.TP
+.B \fBp2p\fP
+Use a point\-to\-point topology where the remote endpoint of
+the client\(aqs tun interface always points to the local endpoint of the
+server\(aqs tun interface. This mode allocates a single IP address per
+connecting client. Only use when none of the connecting clients are
+Windows systems.
+.TP
+.B \fBsubnet\fP
+Use a subnet rather than a point\-to\-point topology by
+configuring the tun interface with a local IP address and subnet mask,
+similar to the topology used in \fB\-\-dev tap\fP and ethernet bridging
+mode. This mode allocates a single IP address per connecting client and
+works on Windows as well. Only available when server and clients are
+OpenVPN 2.1 or higher, or OpenVPN 2.0.x which has been manually patched
+with the \fB\-\-topology\fP directive code. When used on Windows, requires
+version 8.2 or higher of the TAP\-Win32 driver. When used on *nix,
+requires that the tun driver supports an \fBifconfig\fP(8) command which
+sets a subnet instead of a remote endpoint IP address.
+.UNINDENT
+.sp
+\fINote:\fP Using \fB\-\-topology subnet\fP changes the interpretation of the
+arguments of \fB\-\-ifconfig\fP to mean "address netmask", no longer "local
+remote".
+.TP
+.BI \-\-tun\-mtu \ n
+Take the TUN device MTU to be \fBn\fP and derive the link MTU from it
+(default \fB1500\fP). In most cases, you will probably want to leave
+this parameter set to its default value.
+.sp
+The MTU (Maximum Transmission Units) is the maximum datagram size in
+bytes that can be sent unfragmented over a particular network path.
+OpenVPN requires that packets on the control and data channels be sent
+unfragmented.
+.sp
+MTU problems often manifest themselves as connections which hang during
+periods of active usage.
+.sp
+It\(aqs best to use the \fB\-\-fragment\fP and/or \fB\-\-mssfix\fP options to deal
+with MTU sizing issues.
+.TP
+.BI \-\-tun\-mtu\-extra \ n
+Assume that the TUN/TAP device might return as many as \fBn\fP bytes more
+than the \fB\-\-tun\-mtu\fP size on read. This parameter defaults to 0, which
+is sufficient for most TUN devices. TAP devices may introduce additional
+overhead in excess of the MTU size, and a setting of 32 is the default
+when TAP devices are used. This parameter only controls internal OpenVPN
+buffer sizing, so there is no transmission overhead associated with
+using a larger value.
+.UNINDENT
+.SS TUN/TAP standalone operations
+.sp
+These two standalone operations will require \fB\-\-dev\fP and optionally
+\fB\-\-user\fP and/or \fB\-\-group\fP\&.
+.INDENT 0.0
+.TP
+.B \-\-mktun
+(Standalone) Create a persistent tunnel on platforms which support them
+such as Linux. Normally TUN/TAP tunnels exist only for the period of
+time that an application has them open. This option takes advantage of
+the TUN/TAP driver\(aqs ability to build persistent tunnels that live
+through multiple instantiations of OpenVPN and die only when they are
+deleted or the machine is rebooted.
+.sp
+One of the advantages of persistent tunnels is that they eliminate the
+need for separate \fB\-\-up\fP and \fB\-\-down\fP scripts to run the appropriate
+\fBifconfig\fP(8) and \fBroute\fP(8) commands. These commands can be
+placed in the the same shell script which starts or terminates an
+OpenVPN session.
+.sp
+Another advantage is that open connections through the TUN/TAP\-based
+tunnel will not be reset if the OpenVPN peer restarts. This can be
+useful to provide uninterrupted connectivity through the tunnel in the
+event of a DHCP reset of the peer\(aqs public IP address (see the
+\fB\-\-ipchange\fP option above).
+.sp
+One disadvantage of persistent tunnels is that it is harder to
+automatically configure their MTU value (see \fB\-\-link\-mtu\fP and
+\fB\-\-tun\-mtu\fP above).
+.sp
+On some platforms such as Windows, TAP\-Win32 tunnels are persistent by
+default.
+.TP
+.B \-\-rmtun
+(Standalone) Remove a persistent tunnel.
+.UNINDENT
+.SS Virtual Routing and Forwarding
+.sp
+Options in this section relates to configuration of virtual routing and
+forwarding in combination with the underlying operating system.
+.sp
+As of today this is only supported on Linux, a kernel >= 4.9 is
+recommended.
+.sp
+This could come in handy when for example the external network should be
+only used as a means to connect to some VPN endpoints and all regular
+traffic should only be routed through any tunnel(s). This could be
+achieved by setting up a VRF and configuring the interface connected to
+the external network to be part of the VRF. The examples below will cover
+this setup.
+.sp
+Another option would be to put the tun/tap interface into a VRF. This could
+be done by an up\-script which uses the \fBip link set\fP command shown
+below.
+.SS VRF setup with iproute2
+.sp
+Create VRF \fBvrf_external\fP and map it to routing table \fB1023\fP
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+ip link add vrf_external type vrf table 1023
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Move \fBeth0\fP into \fBvrf_external\fP
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+ip link set master vrf_external dev eth0
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Any prefixes configured on \fBeth0\fP will be moved from the :code\(gamain\(ga
+routing table into routing table \fI1023\fP
+.SS VRF setup with ifupdown
+.sp
+For Debian based Distributions \fBifupdown2\fP provides an almost drop\-in
+replacement for \fBifupdown\fP including VRFs and other features.
+A configuration for an interface \fBeth0\fP being part of VRF
+code:\fIvrf_external\fP could look like this:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+auto eth0
+iface eth0
+ address 192.0.2.42/24
+ address 2001:db8:08:15::42/64
+ gateway 192.0.2.1
+ gateway 2001:db8:08:15::1
+ vrf vrf_external
+
+auto vrf_external
+iface vrf_external
+ vrf\-table 1023
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS OpenVPN configuration
+.sp
+The OpenVPN configuration needs to contain this line:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+bind\-dev vrf_external
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Further reading
+.sp
+Wikipedia has nice page one VRFs: \fI\%https://en.wikipedia.org/wiki/Virtual_routing_and_forwarding\fP
+.sp
+This talk from the Network Track of FrOSCon 2018 provides an overview about
+advanced layer 2 and layer 3 features of Linux
+.INDENT 0.0
+.INDENT 3.5
+.INDENT 0.0
+.IP \(bu 2
+Slides: \fI\%https://www.slideshare.net/BarbarossaTM/l2l3\-fr\-fortgeschrittene\-helle\-und\-dunkle\-magie\-im\-linuxnetzwerkstack\fP
+.IP \(bu 2
+Video (german): \fI\%https://media.ccc.de/v/froscon2018\-2247\-l2_l3_fur_fortgeschrittene_\-_helle_und_dunkle_magie_im_linux\-netzwerkstack\fP
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.SH SCRIPTING INTEGRATION
+.sp
+OpenVPN can execute external scripts in various phases of the lifetime of
+the OpenVPN process.
+.SS Script Order of Execution
+.INDENT 0.0
+.IP 1. 4
+\fB\-\-up\fP
+.sp
+Executed after TCP/UDP socket bind and TUN/TAP open.
+.IP 2. 4
+\fB\-\-tls\-verify\fP
+.sp
+Executed when we have a still untrusted remote peer.
+.IP 3. 4
+\fB\-\-ipchange\fP
+.sp
+Executed after connection authentication, or remote IP address change.
+.IP 4. 4
+\fB\-\-client\-connect\fP
+.sp
+Executed in \fB\-\-mode server\fP mode immediately after client
+authentication.
+.IP 5. 4
+\fB\-\-route\-up\fP
+.sp
+Executed after connection authentication, either immediately after, or
+some number of seconds after as defined by the \fB\-\-route\-delay\fP option.
+.IP 6. 4
+\fB\-\-route\-pre\-down\fP
+.sp
+Executed right before the routes are removed.
+.IP 7. 4
+\fB\-\-client\-disconnect\fP
+.sp
+Executed in \fB\-\-mode server\fP mode on client instance shutdown.
+.IP 8. 4
+\fB\-\-down\fP
+.sp
+Executed after TCP/UDP and TUN/TAP close.
+.IP 9. 4
+\fB\-\-learn\-address\fP
+.sp
+Executed in \fB\-\-mode server\fP mode whenever an IPv4 address/route or MAC
+address is added to OpenVPN\(aqs internal routing table.
+.IP 10. 4
+\fB\-\-auth\-user\-pass\-verify\fP
+.sp
+Executed in \fB\-\-mode server\fP mode on new client connections, when the
+client is still untrusted.
+.UNINDENT
+.SS SCRIPT HOOKS
+.INDENT 0.0
+.TP
+.BI \-\-auth\-user\-pass\-verify \ args
+Require the client to provide a username/password (possibly in addition
+to a client certificate) for authentication.
+.sp
+Valid syntax:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+auth\-user\-pass\-verify cmd method
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+OpenVPN will run command \fBcmd\fP to validate the username/password
+provided by the client.
+.sp
+\fBcmd\fP consists of a path to a script (or executable program), optionally
+followed by arguments. The path and arguments may be single\- or
+double\-quoted and/or escaped using a backslash, and should be separated
+by one or more spaces.
+.sp
+If \fBmethod\fP is set to \fBvia\-env\fP, OpenVPN will call \fBscript\fP
+with the environmental variables \fBusername\fP and \fBpassword\fP
+set to the username/password strings provided by the client. \fIBeware\fP
+that this method is insecure on some platforms which make the environment
+of a process publicly visible to other unprivileged processes.
+.sp
+If \fBmethod\fP is set to \fBvia\-file\fP, OpenVPN will write the username
+and password to the first two lines of a temporary file. The filename
+will be passed as an argument to \fBscript\fP, and the file will be
+automatically deleted by OpenVPN after the script returns. The location
+of the temporary file is controlled by the \fB\-\-tmp\-dir\fP option, and
+will default to the current directory if unspecified. For security,
+consider setting \fB\-\-tmp\-dir\fP to a volatile storage medium such as
+\fB/dev/shm\fP (if available) to prevent the username/password file
+from touching the hard drive.
+.sp
+The script should examine the username and password, returning a success
+exit code (\fB0\fP) if the client\(aqs authentication request is to be
+accepted, or a failure code (\fB1\fP) to reject the client.
+.sp
+This directive is designed to enable a plugin\-style interface for
+extending OpenVPN\(aqs authentication capabilities.
+.sp
+To protect against a client passing a maliciously formed username or
+password string, the username string must consist only of these
+characters: alphanumeric, underbar (\(aq\fB_\fP\(aq), dash (\(aq\fB\-\fP\(aq),
+dot (\(aq\fB\&.\fP\(aq), or at (\(aq\fB@\fP\(aq). The password string can consist
+of any printable characters except for CR or LF. Any illegal characters
+in either the username or password string will be converted to
+underbar (\(aq\fB_\fP\(aq).
+.sp
+Care must be taken by any user\-defined scripts to avoid creating a
+security vulnerability in the way that these strings are handled. Never
+use these strings in such a way that they might be escaped or evaluated
+by a shell interpreter.
+.sp
+For a sample script that performs PAM authentication, see
+\fBsample\-scripts/auth\-pam.pl\fP in the OpenVPN source distribution.
+.TP
+.BI \-\-client\-connect \ cmd
+Run command \fBcmd\fP on client connection.
+.sp
+\fBcmd\fP consists of a path to a script (or executable program), optionally
+followed by arguments. The path and arguments may be single\- or
+double\-quoted and/or escaped using a backslash, and should be separated
+by one or more spaces.
+.sp
+The command is passed the common name and IP address of the
+just\-authenticated client as environmental variables (see environmental
+variable section below). The command is also passed the pathname of a
+freshly created temporary file as the last argument (after any arguments
+specified in \fBcmd\fP ), to be used by the command to pass dynamically
+generated config file directives back to OpenVPN.
+.sp
+If the script wants to generate a dynamic config file to be applied on
+the server when the client connects, it should write it to the file
+named by the last argument.
+.sp
+See the \fB\-\-client\-config\-dir\fP option below for options which can be
+legally used in a dynamically generated config file.
+.sp
+Note that the return value of \fBscript\fP is significant. If \fBscript\fP
+returns a non\-zero error status, it will cause the client to be
+disconnected.
+.sp
+If a \fB\-\-client\-connect\fP wants to defer the generating of the
+configuration then the script needs to use the
+\fBclient_connect_deferred_file\fP and
+\fBclient_connect_config_file\fP environment variables, and write
+status accordingly into these files. See the \fI\%Environmental Variables\fP
+section for more details.
+.TP
+.BI \-\-client\-disconnect \ cmd
+Like \fB\-\-client\-connect\fP but called on client instance shutdown. Will
+not be called unless the \fB\-\-client\-connect\fP script and plugins (if
+defined) were previously called on this instance with successful (0)
+status returns.
+.sp
+The exception to this rule is if the \fB\-\-client\-disconnect\fP command or
+plugins are cascaded, and at least one client\-connect function
+succeeded, then ALL of the client\-disconnect functions for scripts and
+plugins will be called on client instance object deletion, even in cases
+where some of the related client\-connect functions returned an error
+status.
+.sp
+The \fB\-\-client\-disconnect\fP command is passed the same pathname as the
+corresponding \fB\-\-client\-connect\fP command as its last argument (after
+any arguments specified in \fBcmd\fP).
+.TP
+.BI \-\-down \ cmd
+Run command \fBcmd\fP after TUN/TAP device close (post \fB\-\-user\fP UID
+change and/or \fB\-\-chroot\fP ). \fBcmd\fP consists of a path to script (or
+executable program), optionally followed by arguments. The path and
+arguments may be single\- or double\-quoted and/or escaped using a
+backslash, and should be separated by one or more spaces.
+.sp
+Called with the same parameters and environmental variables as the
+\fB\-\-up\fP option above.
+.sp
+Note that if you reduce privileges by using \fB\-\-user\fP and/or
+\fB\-\-group\fP, your \fB\-\-down\fP script will also run at reduced privilege.
+.TP
+.B \-\-down\-pre
+Call \fB\-\-down\fP cmd/script before, rather than after, TUN/TAP close.
+.TP
+.BI \-\-ipchange \ cmd
+Run command \fBcmd\fP when our remote ip\-address is initially
+authenticated or changes.
+.sp
+\fBcmd\fP consists of a path to a script (or executable program), optionally
+followed by arguments. The path and arguments may be single\- or
+double\-quoted and/or escaped using a backslash, and should be separated
+by one or more spaces.
+.sp
+When \fBcmd\fP is executed two arguments are appended after any arguments
+specified in \fBcmd\fP , as follows:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+cmd ip address port number
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Don\(aqt use \fB\-\-ipchange\fP in \fB\-\-mode server\fP mode. Use a
+\fB\-\-client\-connect\fP script instead.
+.sp
+See the \fI\%Environmental Variables\fP section below for additional
+parameters passed as environmental variables.
+.sp
+If you are running in a dynamic IP address environment where the IP
+addresses of either peer could change without notice, you can use this
+script, for example, to edit the \fB/etc/hosts\fP file with the current
+address of the peer. The script will be run every time the remote peer
+changes its IP address.
+.sp
+Similarly if \fIour\fP IP address changes due to DHCP, we should configure
+our IP address change script (see man page for \fBdhcpcd\fP(8)) to
+deliver a \fBSIGHUP\fP or \fBSIGUSR1\fP signal to OpenVPN. OpenVPN will
+then re\-establish a connection with its most recently authenticated
+peer on its new IP address.
+.TP
+.BI \-\-learn\-address \ cmd
+Run command \fBcmd\fP to validate client virtual addresses or routes.
+.sp
+\fBcmd\fP consists of a path to a script (or executable program), optionally
+followed by arguments. The path and arguments may be single\- or
+double\-quoted and/or escaped using a backslash, and should be separated
+by one or more spaces.
+.sp
+Three arguments will be appended to any arguments in \fBcmd\fP as follows:
+.INDENT 7.0
+.TP
+.B \fB$1\fP \- [operation]
+\fB"add"\fP, \fB"update"\fP, or \fB"delete"\fP based on whether
+or not the address is being added to, modified, or deleted from
+OpenVPN\(aqs internal routing table.
+.TP
+.B \fB$2\fP \- [address]
+The address being learned or unlearned. This can be an IPv4 address
+such as \fB"198.162.10.14"\fP, an IPv4 subnet such as
+\fB"198.162.10.0/24"\fP, or an ethernet MAC address (when
+\fB\-\-dev tap\fP is being used) such as \fB"00:FF:01:02:03:04"\fP\&.
+.TP
+.B \fB$3\fP \- [common name]
+The common name on the certificate associated with the client linked
+to this address. Only present for \fB"add"\fP or \fB"update"\fP
+operations, not \fB"delete"\fP\&.
+.UNINDENT
+.sp
+On \fB"add"\fP or \fB"update"\fP methods, if the script returns
+a failure code (non\-zero), OpenVPN will reject the address and will not
+modify its internal routing table.
+.sp
+Normally, the \fBcmd\fP script will use the information provided above to
+set appropriate firewall entries on the VPN TUN/TAP interface. Since
+OpenVPN provides the association between virtual IP or MAC address and
+the client\(aqs authenticated common name, it allows a user\-defined script
+to configure firewall access policies with regard to the client\(aqs
+high\-level common name, rather than the low level client virtual
+addresses.
+.TP
+.BI \-\-route\-up \ cmd
+Run command \fBcmd\fP after routes are added, subject to \fB\-\-route\-delay\fP\&.
+.sp
+\fBcmd\fP consists of a path to a script (or executable program), optionally
+followed by arguments. The path and arguments may be single\- or
+double\-quoted and/or escaped using a backslash, and should be separated
+by one or more spaces.
+.sp
+See the \fI\%Environmental Variables\fP section below for additional
+parameters passed as environmental variables.
+.TP
+.BI \-\-route\-pre\-down \ cmd
+Run command \fBcmd\fP before routes are removed upon disconnection.
+.sp
+\fBcmd\fP consists of a path to a script (or executable program), optionally
+followed by arguments. The path and arguments may be single\- or
+double\-quoted and/or escaped using a backslash, and should be separated
+by one or more spaces.
+.sp
+See the \fI\%Environmental Variables\fP section below for additional
+parameters passed as environmental variables.
+.TP
+.BI \-\-setenv \ args
+Set a custom environmental variable \fBname=value\fP to pass to script.
+.sp
+Valid syntaxes:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+setenv name value
+setenv FORWARD_COMPATIBLE 1
+setenv opt config_option
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+By setting \fBFORWARD_COMPATIBLE\fP to \fB1\fP, the config file
+syntax checking is relaxed so that unknown directives will trigger a
+warning but not a fatal error, on the assumption that a given unknown
+directive might be valid in future OpenVPN versions.
+.sp
+This option should be used with caution, as there are good security
+reasons for having OpenVPN fail if it detects problems in a config file.
+Having said that, there are valid reasons for wanting new software
+features to gracefully degrade when encountered by older software
+versions.
+.sp
+It is also possible to tag a single directive so as not to trigger a
+fatal error if the directive isn\(aqt recognized. To do this, prepend the
+following before the directive: \fBsetenv opt\fP
+.sp
+Versions prior to OpenVPN 2.3.3 will always ignore options set with the
+\fBsetenv opt\fP directive.
+.sp
+See also \fB\-\-ignore\-unknown\-option\fP
+.TP
+.BI \-\-setenv\-safe \ args
+Set a custom environmental variable \fBOPENVPN_name\fP to \fBvalue\fP
+to pass to scripts.
+.sp
+Valid syntaxes:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+setenv\-safe name value
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+This directive is designed to be pushed by the server to clients, and
+the prepending of \fBOPENVPN_\fP to the environmental variable is a
+safety precaution to prevent a \fBLD_PRELOAD\fP style attack from a
+malicious or compromised server.
+.TP
+.BI \-\-tls\-verify \ cmd
+Run command \fBcmd\fP to verify the X509 name of a pending TLS connection
+that has otherwise passed all other tests of certification (except for
+revocation via \fB\-\-crl\-verify\fP directive; the revocation test occurs
+after the \fB\-\-tls\-verify\fP test).
+.sp
+\fBcmd\fP should return \fB0\fP to allow the TLS handshake to proceed,
+or \fB1\fP to fail.
+.sp
+\fBcmd\fP consists of a path to a script (or executable program), optionally
+followed by arguments. The path and arguments may be single\- or
+double\-quoted and/or escaped using a backslash, and should be separated
+by one or more spaces.
+.sp
+When \fBcmd\fP is executed two arguments are appended after any arguments
+specified in \fBcmd\fP, as follows:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+cmd certificate_depth subject
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+These arguments are, respectively, the current certificate depth and the
+X509 subject distinguished name (dn) of the peer.
+.sp
+This feature is useful if the peer you want to trust has a certificate
+which was signed by a certificate authority who also signed many other
+certificates, where you don\(aqt necessarily want to trust all of them, but
+rather be selective about which peer certificate you will accept. This
+feature allows you to write a script which will test the X509 name on a
+certificate and decide whether or not it should be accepted. For a
+simple perl script which will test the common name field on the
+certificate, see the file \fBverify\-cn\fP in the OpenVPN distribution.
+.sp
+See the \fI\%Environmental Variables\fP section below for additional
+parameters passed as environmental variables.
+.TP
+.BI \-\-up \ cmd
+Run command \fBcmd\fP after successful TUN/TAP device open (pre \fB\-\-user\fP
+UID change).
+.sp
+\fBcmd\fP consists of a path to a script (or executable program), optionally
+followed by arguments. The path and arguments may be single\- or
+double\-quoted and/or escaped using a backslash, and should be separated
+by one or more spaces.
+.sp
+The up command is useful for specifying route commands which route IP
+traffic destined for private subnets which exist at the other end of the
+VPN connection into the tunnel.
+.sp
+For \fB\-\-dev tun\fP execute as:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+cmd tun_dev tun_mtu link_mtu ifconfig_local_ip ifconfig_remote_ip [init | restart]
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+For \fB\-\-dev tap\fP execute as:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+cmd tap_dev tap_mtu link_mtu ifconfig_local_ip ifconfig_netmask [init | restart]
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+See the \fI\%Environmental Variables\fP section below for additional
+parameters passed as environmental variables.
+.sp
+Note that if \fBcmd\fP includes arguments, all OpenVPN\-generated arguments
+will be appended to them to build an argument list with which the
+executable will be called.
+.sp
+Typically, \fBcmd\fP will run a script to add routes to the tunnel.
+.sp
+Normally the up script is called after the TUN/TAP device is opened. In
+this context, the last command line parameter passed to the script will
+be \fIinit.\fP If the \fB\-\-up\-restart\fP option is also used, the up script
+will be called for restarts as well. A restart is considered to be a
+partial reinitialization of OpenVPN where the TUN/TAP instance is
+preserved (the \fB\-\-persist\-tun\fP option will enable such preservation).
+A restart can be generated by a SIGUSR1 signal, a \fB\-\-ping\-restart\fP
+timeout, or a connection reset when the TCP protocol is enabled with the
+\fB\-\-proto\fP option. If a restart occurs, and \fB\-\-up\-restart\fP has been
+specified, the up script will be called with \fIrestart\fP as the last
+parameter.
+.INDENT 7.0
+.TP
+.B \fINOTE:\fP
+On restart, OpenVPN will not pass the full set of environment
+variables to the script. Namely, everything related to routing and
+gateways will not be passed, as nothing needs to be done anyway \- all
+the routing setup is already in place. Additionally, the up\-restart
+script will run with the downgraded UID/GID settings (if configured).
+.UNINDENT
+.sp
+The following standalone example shows how the \fB\-\-up\fP script can be
+called in both an initialization and restart context. (\fINOTE:\fP for
+security reasons, don\(aqt run the following example unless UDP port 9999
+is blocked by your firewall. Also, the example will run indefinitely, so
+you should abort with control\-c).
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+openvpn \-\-dev tun \-\-port 9999 \-\-verb 4 \-\-ping\-restart 10 \e
+ \-\-up \(aqecho up\(aq \-\-down \(aqecho down\(aq \-\-persist\-tun \e
+ \-\-up\-restart
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Note that OpenVPN also provides the \fB\-\-ifconfig\fP option to
+automatically ifconfig the TUN device, eliminating the need to define an
+\fB\-\-up\fP script, unless you also want to configure routes in the
+\fB\-\-up\fP script.
+.sp
+If \fB\-\-ifconfig\fP is also specified, OpenVPN will pass the ifconfig
+local and remote endpoints on the command line to the \fB\-\-up\fP script so
+that they can be used to configure routes such as:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+route add \-net 10.0.0.0 netmask 255.255.255.0 gw $5
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.TP
+.B \-\-up\-delay
+Delay TUN/TAP open and possible \fB\-\-up\fP script execution until after
+TCP/UDP connection establishment with peer.
+.sp
+In \fB\-\-proto udp\fP mode, this option normally requires the use of
+\fB\-\-ping\fP to allow connection initiation to be sensed in the absence of
+tunnel data, since UDP is a "connectionless" protocol.
+.sp
+On Windows, this option will delay the TAP\-Win32 media state
+transitioning to "connected" until connection establishment, i.e. the
+receipt of the first authenticated packet from the peer.
+.TP
+.B \-\-up\-restart
+Enable the \fB\-\-up\fP and \fB\-\-down\fP scripts to be called for restarts as
+well as initial program start. This option is described more fully above
+in the \fB\-\-up\fP option documentation.
+.UNINDENT
+.SS String Types and Remapping
+.sp
+In certain cases, OpenVPN will perform remapping of characters in
+strings. Essentially, any characters outside the set of permitted
+characters for each string type will be converted to underbar (\(aq_\(aq).
+.INDENT 0.0
+.TP
+.B \fIQ: Why is string remapping necessary?\fP
+It\(aqs an important security feature to prevent the malicious
+coding of strings from untrusted sources to be passed as parameters to
+scripts, saved in the environment, used as a common name, translated to
+a filename, etc.
+.TP
+.B \fIQ: Can string remapping be disabled?\fP
+Yes, by using the \fB\-\-no\-name\-remapping\fP option, however this
+should be considered an advanced option.
+.UNINDENT
+.sp
+Here is a brief rundown of OpenVPN\(aqs current string types and the
+permitted character class for each string:
+.INDENT 0.0
+.TP
+.B \fIX509 Names\fP
+Alphanumeric, underbar (\(aq_\(aq), dash (\(aq\-\(aq), dot (\(aq.\(aq), at
+(\(aq@\(aq), colon (\(aq:\(aq), slash (\(aq/\(aq), and equal (\(aq=\(aq). Alphanumeric is
+defined as a character which will cause the C library isalnum() function
+to return true.
+.TP
+.B \fICommon Names\fP
+Alphanumeric, underbar (\(aq_\(aq), dash (\(aq\-\(aq), dot (\(aq.\(aq), and at (\(aq@\(aq).
+.TP
+.B \fI\-\-auth\-user\-pass username\fP
+Same as Common Name, with one exception:
+starting with OpenVPN 2.0.1, the username is passed to the
+\fBOPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY\fP plugin in its raw form,
+without string remapping.
+.TP
+.B \fI\-\-auth\-user\-pass password\fP
+Any "printable" character except CR or LF. Printable is defined to be
+a character which will cause the C library isprint() function to
+return true.
+.TP
+.B \fI\-\-client\-config\-dir filename as derived from common name or\(gausername\fP
+Alphanumeric, underbar (\(aq_\(aq), dash (\(aq\-\(aq), and dot (\(aq.\(aq) except for "."
+or ".." as standalone strings. As of v2.0.1\-rc6, the at (\(aq@\(aq) character
+has been added as well for compatibility with the common name character
+class.
+.TP
+.B \fIEnvironmental variable names\fP
+Alphanumeric or underbar (\(aq_\(aq).
+.TP
+.B \fIEnvironmental variable values\fP
+Any printable character.
+.UNINDENT
+.sp
+For all cases, characters in a string which are not members of the legal
+character class for that string type will be remapped to underbar
+(\(aq_\(aq).
+.SS Environmental Variables
+.sp
+Once set, a variable is persisted indefinitely until it is reset by a
+new value or a restart,
+.sp
+As of OpenVPN 2.0\-beta12, in server mode, environmental variables set by
+OpenVPN are scoped according to the client objects they are associated
+with, so there should not be any issues with scripts having access to
+stale, previously set variables which refer to different client
+instances.
+.INDENT 0.0
+.TP
+.B \fBbytes_received\fP
+Total number of bytes received from client during VPN session. Set prior
+to execution of the \fB\-\-client\-disconnect\fP script.
+.TP
+.B \fBbytes_sent\fP
+Total number of bytes sent to client during VPN session. Set prior to
+execution of the \fB\-\-client\-disconnect\fP script.
+.TP
+.B \fBclient_connect_config_file\fP
+The path to the configuration file that should be written to by the
+\fB\-\-client\-connect\fP script (optional, if per\-session configuration
+is desired). This is the same file name as passed via command line
+argument on the call to the \fB\-\-client\-connect\fP script.
+.TP
+.B \fBclient_connect_deferred_file\fP
+This file can be optionally written to in order to to communicate a
+status code of the \fB\-\-client\-connect\fP script or plgin. Only the
+first character in the file is relevant. It must be either \fB1\fP
+to indicate normal script execution, \fB0\fP indicates an error (in
+the same way that a non zero exit status does) or \fB2\fP to indicate
+that the script deferred returning the config file.
+.sp
+For deferred (background) handling, the script or plugin MUST write
+\fB2\fP to the file to indicate the deferral and then return with
+exit code \fB0\fP to signal \fBdeferred handler started OK\fP\&.
+.sp
+A background process or similar must then take care of writing the
+configuration to the file indicated by the
+\fBclient_connect_config_file\fP environment variable and when
+finished, write the a \fB1\fP to this file (or \fB0\fP in case of
+an error).
+.sp
+The absence of any character in the file when the script finishes
+executing is interpreted the same as \fB1\fP\&. This allows scripts
+that are not written to support the defer mechanism to be used
+unmodified.
+.TP
+.B \fBcommon_name\fP
+The X509 common name of an authenticated client. Set prior to execution
+of \fB\-\-client\-connect\fP, \fB\-\-client\-disconnect\fP and
+\fB\-\-auth\-user\-pass\-verify\fP scripts.
+.TP
+.B \fBconfig\fP
+Name of first \fB\-\-config\fP file. Set on program initiation and reset on
+SIGHUP.
+.TP
+.B \fBdaemon\fP
+Set to "1" if the \fB\-\-daemon\fP directive is specified, or "0" otherwise.
+Set on program initiation and reset on SIGHUP.
+.TP
+.B \fBdaemon_log_redirect\fP
+Set to "1" if the \fB\-\-log\fP or \fB\-\-log\-append\fP directives are
+specified, or "0" otherwise. Set on program initiation and reset on
+SIGHUP.
+.TP
+.B \fBdev\fP
+The actual name of the TUN/TAP device, including a unit number if it
+exists. Set prior to \fB\-\-up\fP or \fB\-\-down\fP script execution.
+.TP
+.B \fBdev_idx\fP
+On Windows, the device index of the TUN/TAP adapter (to be used in
+netsh.exe calls which sometimes just do not work right with interface
+names). Set prior to \fB\-\-up\fP or \fB\-\-down\fP script execution.
+.TP
+.B \fBforeign_option_{n}\fP
+An option pushed via \fB\-\-push\fP to a client which does not natively
+support it, such as \fB\-\-dhcp\-option\fP on a non\-Windows system, will be
+recorded to this environmental variable sequence prior to \fB\-\-up\fP
+script execution.
+.TP
+.B \fBifconfig_broadcast\fP
+The broadcast address for the virtual ethernet segment which is derived
+from the \fB\-\-ifconfig\fP option when \fB\-\-dev tap\fP is used. Set prior to
+OpenVPN calling the \fBifconfig\fP or \fBnetsh\fP (windows version
+of ifconfig) commands which normally occurs prior to \fB\-\-up\fP script
+execution.
+.TP
+.B \fBifconfig_ipv6_local\fP
+The local VPN endpoint IPv6 address specified in the
+\fB\-\-ifconfig\-ipv6\fP option (first parameter). Set prior to OpenVPN
+calling the \fBifconfig\fP or code:\fInetsh\fP (windows version of
+ifconfig) commands which normally occurs prior to \fB\-\-up\fP script
+execution.
+.TP
+.B \fBifconfig_ipv6_netbits\fP
+The prefix length of the IPv6 network on the VPN interface. Derived
+from the /nnn parameter of the IPv6 address in the \fB\-\-ifconfig\-ipv6\fP
+option (first parameter). Set prior to OpenVPN calling the
+\fBifconfig\fP or \fBnetsh\fP (windows version of ifconfig)
+commands which normally occurs prior to \fB\-\-up\fP script execution.
+.TP
+.B \fBifconfig_ipv6_remote\fP
+The remote VPN endpoint IPv6 address specified in the
+\fB\-\-ifconfig\-ipv6\fP option (second parameter). Set prior to OpenVPN
+calling the \fBifconfig\fP or \fBnetsh\fP (windows version of
+ifconfig) commands which normally occurs prior to \fB\-\-up\fP script
+execution.
+.TP
+.B \fBifconfig_local\fP
+The local VPN endpoint IP address specified in the \fB\-\-ifconfig\fP
+option (first parameter). Set prior to OpenVPN calling the
+\fBifconfig\fP or \fBnetsh\fP (windows version of ifconfig)
+commands which normally occurs prior to \fB\-\-up\fP script execution.
+.TP
+.B \fBifconfig_remote\fP
+The remote VPN endpoint IP address specified in the \fB\-\-ifconfig\fP
+option (second parameter) when \fB\-\-dev tun\fP is used. Set prior to
+OpenVPN calling the \fBifconfig\fP or \fBnetsh\fP (windows version
+of ifconfig) commands which normally occurs prior to \fB\-\-up\fP script
+execution.
+.TP
+.B \fBifconfig_netmask\fP
+The subnet mask of the virtual ethernet segment that is specified as
+the second parameter to \fB\-\-ifconfig\fP when \fB\-\-dev tap\fP is being
+used. Set prior to OpenVPN calling the \fBifconfig\fP or
+\fBnetsh\fP (windows version of ifconfig) commands which normally
+occurs prior to \fB\-\-up\fP script execution.
+.TP
+.B \fBifconfig_pool_local_ip\fP
+The local virtual IP address for the TUN/TAP tunnel taken from an
+\fB\-\-ifconfig\-push\fP directive if specified, or otherwise from the
+ifconfig pool (controlled by the \fB\-\-ifconfig\-pool\fP config file
+directive). Only set for \fB\-\-dev tun\fP tunnels. This option is set on
+the server prior to execution of the \fB\-\-client\-connect\fP and
+\fB\-\-client\-disconnect\fP scripts.
+.TP
+.B \fBifconfig_pool_netmask\fP
+The virtual IP netmask for the TUN/TAP tunnel taken from an
+\fB\-\-ifconfig\-push\fP directive if specified, or otherwise from the
+ifconfig pool (controlled by the \fB\-\-ifconfig\-pool\fP config file
+directive). Only set for \fB\-\-dev tap\fP tunnels. This option is set on
+the server prior to execution of the \fB\-\-client\-connect\fP and
+\fB\-\-client\-disconnect\fP scripts.
+.TP
+.B \fBifconfig_pool_remote_ip\fP
+The remote virtual IP address for the TUN/TAP tunnel taken from an
+\fB\-\-ifconfig\-push\fP directive if specified, or otherwise from the
+ifconfig pool (controlled by the \fB\-\-ifconfig\-pool\fP config file
+directive). This option is set on the server prior to execution of the
+\fB\-\-client\-connect\fP and \fB\-\-client\-disconnect\fP scripts.
+.TP
+.B \fBlink_mtu\fP
+The maximum packet size (not including the IP header) of tunnel data in
+UDP tunnel transport mode. Set prior to \fB\-\-up\fP or \fB\-\-down\fP script
+execution.
+.TP
+.B \fBlocal\fP
+The \fB\-\-local\fP parameter. Set on program initiation and reset on
+SIGHUP.
+.TP
+.B \fBlocal_port\fP
+The local port number or name, specified by \fB\-\-port\fP or \fB\-\-lport\fP\&.
+Set on program initiation and reset on SIGHUP.
+.TP
+.B \fBpassword\fP
+The password provided by a connecting client. Set prior to
+\fB\-\-auth\-user\-pass\-verify\fP script execution only when the \fBvia\-env\fP
+modifier is specified, and deleted from the environment after the script
+returns.
+.TP
+.B \fBproto\fP
+The \fB\-\-proto\fP parameter. Set on program initiation and reset on
+SIGHUP.
+.TP
+.B \fBremote_{n}\fP
+The \fB\-\-remote\fP parameter. Set on program initiation and reset on
+SIGHUP.
+.TP
+.B \fBremote_port_{n}\fP
+The remote port number, specified by \fB\-\-port\fP or \fB\-\-rport\fP\&. Set on
+program initiation and reset on SIGHUP.
+.TP
+.B \fBroute_net_gateway\fP
+The pre\-existing default IP gateway in the system routing table. Set
+prior to \fB\-\-up\fP script execution.
+.TP
+.B \fBroute_vpn_gateway\fP
+The default gateway used by \fB\-\-route\fP options, as specified in either
+the \fB\-\-route\-gateway\fP option or the second parameter to
+\fB\-\-ifconfig\fP when \fB\-\-dev tun\fP is specified. Set prior to \fB\-\-up\fP
+script execution.
+.TP
+.B \fBroute_{parm}_{n}\fP
+A set of variables which define each route to be added, and are set
+prior to \fB\-\-up\fP script execution.
+.sp
+\fBparm\fP will be one of \fBnetwork\fP, \fBnetmask"\fP,
+\fBgateway\fP, or \fBmetric\fP\&.
+.sp
+\fBn\fP is the OpenVPN route number, starting from 1.
+.sp
+If the network or gateway are resolvable DNS names, their IP address
+translations will be recorded rather than their names as denoted on the
+command line or configuration file.
+.TP
+.B \fBroute_ipv6_{parm}_{n}\fP
+A set of variables which define each IPv6 route to be added, and are
+set prior to \fB\-\-up\fP script execution.
+.sp
+\fBparm\fP will be one of \fBnetwork\fP or \fBgateway\fP
+(\fBnetmask\fP is contained as \fB/nnn\fP in the
+\fBroute_ipv6_network_{n}\fP, unlike IPv4 where it is passed in a
+separate environment variable).
+.sp
+\fBn\fP is the OpenVPN route number, starting from 1.
+.sp
+If the network or gateway are resolvable DNS names, their IP address
+translations will be recorded rather than their names as denoted on the
+command line or configuration file.
+.TP
+.B \fBpeer_cert\fP
+Temporary file name containing the client certificate upon connection.
+Useful in conjunction with \fB\-\-tls\-verify\fP\&.
+.TP
+.B \fBscript_context\fP
+Set to "init" or "restart" prior to up/down script execution. For more
+information, see documentation for \fB\-\-up\fP\&.
+.TP
+.B \fBscript_type\fP
+Prior to execution of any script, this variable is set to the type of
+script being run. It can be one of the following: \fBup\fP,
+\fBdown\fP, \fBipchange\fP, \fBroute\-up\fP, \fBtls\-verify\fP,
+\fBauth\-user\-pass\-verify\fP, \fBclient\-connect\fP,
+\fBclient\-disconnect\fP or \fBlearn\-address\fP\&. Set prior to
+execution of any script.
+.TP
+.B \fBsignal\fP
+The reason for exit or restart. Can be one of \fBsigusr1\fP,
+\fBsighup\fP, \fBsigterm\fP, \fBsigint\fP, \fBinactive\fP
+(controlled by \fB\-\-inactive\fP option), \fBping\-exit\fP (controlled
+by \fB\-\-ping\-exit\fP option), \fBping\-restart\fP (controlled by
+\fB\-\-ping\-restart\fP option), \fBconnection\-reset\fP (triggered on TCP
+connection reset), \fBerror\fP or \fBunknown\fP (unknown signal).
+This variable is set just prior to down script execution.
+.TP
+.B \fBtime_ascii\fP
+Client connection timestamp, formatted as a human\-readable time string.
+Set prior to execution of the \fB\-\-client\-connect\fP script.
+.TP
+.B \fBtime_duration\fP
+The duration (in seconds) of the client session which is now
+disconnecting. Set prior to execution of the \fB\-\-client\-disconnect\fP
+script.
+.TP
+.B \fBtime_unix\fP
+Client connection timestamp, formatted as a unix integer date/time
+value. Set prior to execution of the \fB\-\-client\-connect\fP script.
+.TP
+.B \fBtls_digest_{n}\fP / \fBtls_digest_sha256_{n}\fP
+Contains the certificate SHA1 / SHA256 fingerprint, where \fBn\fP is the
+verification level. Only set for TLS connections. Set prior to execution
+of \fB\-\-tls\-verify\fP script.
+.TP
+.B \fBtls_id_{n}\fP
+A series of certificate fields from the remote peer, where \fBn\fP is the
+verification level. Only set for TLS connections. Set prior to execution
+of \fB\-\-tls\-verify\fP script.
+.TP
+.B \fBtls_serial_{n}\fP
+The serial number of the certificate from the remote peer, where \fBn\fP
+is the verification level. Only set for TLS connections. Set prior to
+execution of \fB\-\-tls\-verify\fP script. This is in the form of a decimal
+string like "933971680", which is suitable for doing serial\-based OCSP
+queries (with OpenSSL, do not prepend "0x" to the string) If something
+goes wrong while reading the value from the certificate it will be an
+empty string, so your code should check that. See the
+\fBcontrib/OCSP_check/OCSP_check.sh\fP script for an example.
+.TP
+.B \fBtls_serial_hex_{n}\fP
+Like \fBtls_serial_{n}\fP, but in hex form (e.g.
+\fB12:34:56:78:9A\fP).
+.TP
+.B \fBtun_mtu\fP
+The MTU of the TUN/TAP device. Set prior to \fB\-\-up\fP or \fB\-\-down\fP
+script execution.
+.TP
+.B \fBtrusted_ip\fP / \fBtrusted_ip6\fP)
+Actual IP address of connecting client or peer which has been
+authenticated. Set prior to execution of \fB\-\-ipchange\fP,
+\fB\-\-client\-connect\fP and \fB\-\-client\-disconnect\fP scripts. If using ipv6
+endpoints (udp6, tcp6), \fBtrusted_ip6\fP will be set instead.
+.TP
+.B \fBtrusted_port\fP
+Actual port number of connecting client or peer which has been
+authenticated. Set prior to execution of \fB\-\-ipchange\fP,
+\fB\-\-client\-connect\fP and \fB\-\-client\-disconnect\fP scripts.
+.TP
+.B \fBuntrusted_ip\fP / \fBuntrusted_ip6\fP
+Actual IP address of connecting client or peer which has not been
+authenticated yet. Sometimes used to \fInmap\fP the connecting host in a
+\fB\-\-tls\-verify\fP script to ensure it is firewalled properly. Set prior
+to execution of \fB\-\-tls\-verify\fP and \fB\-\-auth\-user\-pass\-verify\fP
+scripts. If using ipv6 endpoints (udp6, tcp6), \fBuntrusted_ip6\fP
+will be set instead.
+.TP
+.B \fBuntrusted_port\fP
+Actual port number of connecting client or peer which has not been
+authenticated yet. Set prior to execution of \fB\-\-tls\-verify\fP and
+\fB\-\-auth\-user\-pass\-verify\fP scripts.
+.TP
+.B \fBusername\fP
+The username provided by a connecting client. Set prior to
+\fB\-\-auth\-user\-pass\-verify\fP script execution only when the
+\fBvia\-env\fP modifier is specified.
+.TP
+.B \fBX509_{n}_{subject_field}\fP
+An X509 subject field from the remote peer certificate, where \fBn\fP is
+the verification level. Only set for TLS connections. Set prior to
+execution of \fB\-\-tls\-verify\fP script. This variable is similar to
+\fBtls_id_{n}\fP except the component X509 subject fields are broken
+out, and no string remapping occurs on these field values (except for
+remapping of control characters to "\fB_\fP"). For example, the
+following variables would be set on the OpenVPN server using the sample
+client certificate in sample\-keys (client.crt). Note that the
+verification level is 0 for the client certificate and 1 for the CA
+certificate.
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+X509_0_emailAddress=me@myhost.mydomain
+X509_0_CN=Test\-Client
+X509_0_O=OpenVPN\-TEST
+X509_0_ST=NA
+X509_0_C=KG
+X509_1_emailAddress=me@myhost.mydomain
+X509_1_O=OpenVPN\-TEST
+X509_1_L=BISHKEK
+X509_1_ST=NA
+X509_1_C=KG
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.SS Management Interface Options
+.sp
+OpenVPN provides a feature rich socket based management interface for both
+server and client mode operations.
+.INDENT 0.0
+.TP
+.BI \-\-management \ args
+Enable a management server on a \fBsocket\-name\fP Unix socket on those
+platforms supporting it, or on a designated TCP port.
+.sp
+Valid syntaxes:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+management socket\-name unix #
+management socket\-name unix pw\-file # (recommended)
+management IP port # (INSECURE)
+management IP port pw\-file #
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+\fBpw\-file\fP, if specified, is a password file where the password must
+be on first line. Instead of a filename it can use the keyword stdin
+which will prompt the user for a password to use when OpenVPN is
+starting.
+.sp
+For unix sockets, the default behaviour is to create a unix domain
+socket that may be connected to by any process. Use the
+\fB\-\-management\-client\-user\fP and \fB\-\-management\-client\-group\fP
+directives to restrict access.
+.sp
+The management interface provides a special mode where the TCP
+management link can operate over the tunnel itself. To enable this mode,
+set IP to \fBtunnel\fP\&. Tunnel mode will cause the management interface to
+listen for a TCP connection on the local VPN address of the TUN/TAP
+interface.
+.sp
+\fB*BEWARE*\fP of enabling the management interface over TCP. In these cases
+you should \fIALWAYS\fP make use of \fBpw\-file\fP to password protect the
+management interface. Any user who can connect to this TCP \fBIP:port\fP
+will be able to manage and control (and interfere with) the OpenVPN
+process. It is also strongly recommended to set IP to 127.0.0.1
+(localhost) to restrict accessibility of the management server to local
+clients.
+.sp
+While the management port is designed for programmatic control of
+OpenVPN by other applications, it is possible to telnet to the port,
+using a telnet client in "raw" mode. Once connected, type \fBhelp\fP
+for a list of commands.
+.sp
+For detailed documentation on the management interface, see the
+\fImanagement\-notes.txt\fP file in the management folder of the OpenVPN
+source distribution.
+.TP
+.B \-\-management\-client
+Management interface will connect as a TCP/unix domain client to
+\fBIP:port\fP specified by \fB\-\-management\fP rather than listen as a TCP
+server or on a unix domain socket.
+.sp
+If the client connection fails to connect or is disconnected, a SIGTERM
+signal will be generated causing OpenVPN to quit.
+.TP
+.B \-\-management\-client\-auth
+Gives management interface client the responsibility to authenticate
+clients after their client certificate has been verified. See
+\fBmanagement\-notes.txt\fP in OpenVPN distribution for detailed notes.
+.TP
+.BI \-\-management\-client\-group \ g
+When the management interface is listening on a unix domain socket, only
+allow connections from group \fBg\fP\&.
+.TP
+.B \-\-management\-client\-pf
+Management interface clients must specify a packet filter file for each
+connecting client. See \fBmanagement\-notes.txt\fP in OpenVPN
+distribution for detailed notes.
+.TP
+.BI \-\-management\-client\-user \ u
+When the management interface is listening on a unix domain socket, only
+allow connections from user \fBu\fP\&.
+.TP
+.BI \-\-management\-external\-cert \ certificate\-hint
+Allows usage for external certificate instead of \fB\-\-cert\fP option
+(client\-only). \fBcertificate\-hint\fP is an arbitrary string which is
+passed to a management interface client as an argument of
+\fINEED\-CERTIFICATE\fP notification. Requires \fB\-\-management\-external\-key\fP\&.
+.TP
+.BI \-\-management\-external\-key \ args
+Allows usage for external private key file instead of \fB\-\-key\fP option
+(client\-only).
+.sp
+Valid syntaxes:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+management\-external\-key
+management\-external\-key nopadding
+management\-external\-key pkcs1
+management\-external\-key nopadding pkcs1
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The optional parameters \fBnopadding\fP and \fBpkcs1\fP signal
+support for different padding algorithms. See
+\fBdoc/mangement\-notes.txt\fP for a complete description of this
+feature.
+.TP
+.B \-\-management\-forget\-disconnect
+Make OpenVPN forget passwords when management session disconnects.
+.sp
+This directive does not affect the \fB\-\-http\-proxy\fP username/password.
+It is always cached.
+.TP
+.B \-\-management\-hold
+Start OpenVPN in a hibernating state, until a client of the management
+interface explicitly starts it with the \fBhold release\fP command.
+.TP
+.BI \-\-management\-log\-cache \ n
+Cache the most recent \fBn\fP lines of log file history for usage by the
+management channel.
+.TP
+.B \-\-management\-query\-passwords
+Query management channel for private key password and
+\fB\-\-auth\-user\-pass\fP username/password. Only query the management
+channel for inputs which ordinarily would have been queried from the
+console.
+.TP
+.B \-\-management\-query\-proxy
+Query management channel for proxy server information for a specific
+\fB\-\-remote\fP (client\-only).
+.TP
+.B \-\-management\-query\-remote
+Allow management interface to override \fB\-\-remote\fP directives
+(client\-only).
+.TP
+.B \-\-management\-signal
+Send SIGUSR1 signal to OpenVPN if management session disconnects. This
+is useful when you wish to disconnect an OpenVPN session on user logoff.
+For \fB\-\-management\-client\fP this option is not needed since a disconnect
+will always generate a \fBSIGTERM\fP\&.
+.TP
+.B \-\-management\-up\-down
+Report tunnel up/down events to management interface.
+.UNINDENT
+.SS Plug\-in Interface Options
+.sp
+OpenVPN can be extended by loading external plug\-in modules at runtime. These
+plug\-ins must be prebuilt and adhere to the OpenVPN Plug\-In API.
+.INDENT 0.0
+.TP
+.BI \-\-plugin \ args
+Loads an OpenVPN plug\-in module.
+.sp
+Valid syntax:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+plugin module\-name
+plugin module\-name "arguments"
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The \fBmodule\-name\fP needs to be the first
+argument, indicating the plug\-in to load. The second argument is an
+optional init string which will be passed directly to the plug\-in.
+If the init consists of multiple arguments it must be enclosed in
+double\-quotes ("). Multiple plugin modules may be loaded into one
+OpenVPN process.
+.sp
+The \fBmodule\-name\fP argument can be just a filename or a filename
+with a relative or absolute path. The format of the filename and path
+defines if the plug\-in will be loaded from a default plug\-in directory
+or outside this directory.
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+\-\-plugin path Effective directory used
+===================== =============================
+ myplug.so DEFAULT_DIR/myplug.so
+ subdir/myplug.so DEFAULT_DIR/subdir/myplug.so
+ ./subdir/myplug.so CWD/subdir/myplug.so
+ /usr/lib/my/plug.so /usr/lib/my/plug.so
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+\fBDEFAULT_DIR\fP is replaced by the default plug\-in directory, which is
+configured at the build time of OpenVPN. \fBCWD\fP is the current directory
+where OpenVPN was started or the directory OpenVPN have switched into
+via the \fB\-\-cd\fP option before the \fB\-\-plugin\fP option.
+.sp
+For more information and examples on how to build OpenVPN plug\-in
+modules, see the README file in the \fBplugin\fP folder of the OpenVPN
+source distribution.
+.sp
+If you are using an RPM install of OpenVPN, see
+\fB/usr/share/openvpn/plugin\fP\&. The documentation is in \fBdoc\fP and
+the actual plugin modules are in \fBlib\fP\&.
+.sp
+Multiple plugin modules can be cascaded, and modules can be used in
+tandem with scripts. The modules will be called by OpenVPN in the order
+that they are declared in the config file. If both a plugin and script
+are configured for the same callback, the script will be called last. If
+the return code of the module/script controls an authentication function
+(such as tls\-verify, auth\-user\-pass\-verify, or client\-connect), then
+every module and script must return success (\fB0\fP) in order for the
+connection to be authenticated.
+.UNINDENT
+.SS Windows\-Specific Options
+.INDENT 0.0
+.TP
+.BI \-\-allow\-nonadmin \ TAP\-adapter
+(Standalone) Set \fBTAP\-adapter\fP to allow access from non\-administrative
+accounts. If \fBTAP\-adapter\fP is omitted, all TAP adapters on the system
+will be configured to allow non\-admin access. The non\-admin access
+setting will only persist for the length of time that the TAP\-Win32
+device object and driver remain loaded, and will need to be re\-enabled
+after a reboot, or if the driver is unloaded and reloaded. This
+directive can only be used by an administrator.
+.TP
+.B \-\-block\-outside\-dns
+Block DNS servers on other network adapters to prevent DNS leaks. This
+option prevents any application from accessing TCP or UDP port 53 except
+one inside the tunnel. It uses Windows Filtering Platform (WFP) and
+works on Windows Vista or later.
+.sp
+This option is considered unknown on non\-Windows platforms and
+unsupported on Windows XP, resulting in fatal error. You may want to use
+\fB\-\-setenv opt\fP or \fB\-\-ignore\-unknown\-option\fP (not suitable for
+Windows XP) to ignore said error. Note that pushing unknown options from
+server does not trigger fatal errors.
+.TP
+.BI \-\-cryptoapicert \ select\-string
+\fI(Windows/OpenSSL Only)\fP Load the certificate and private key from the
+Windows Certificate System Store.
+.sp
+Use this option instead of \fB\-\-cert\fP and \fB\-\-key\fP\&.
+.sp
+This makes it possible to use any smart card, supported by Windows, but
+also any kind of certificate, residing in the Cert Store, where you have
+access to the private key. This option has been tested with a couple of
+different smart cards (GemSAFE, Cryptoflex, and Swedish Post Office eID)
+on the client side, and also an imported PKCS12 software certificate on
+the server side.
+.sp
+To select a certificate, based on a substring search in the
+certificate\(aqs subject:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+cryptoapicert "SUBJ:Peter Runestig"
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+To select a certificate, based on certificate\(aqs thumbprint:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+cryptoapicert "THUMB:f6 49 24 41 01 b4 ..."
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The thumbprint hex string can easily be copy\-and\-pasted from the Windows
+Certificate Store GUI.
+.TP
+.B \-\-dhcp\-release
+Ask Windows to release the TAP adapter lease on shutdown. This option
+has no effect now, as it is enabled by default starting with
+OpenVPN 2.4.1.
+.TP
+.B \-\-dhcp\-renew
+Ask Windows to renew the TAP adapter lease on startup. This option is
+normally unnecessary, as Windows automatically triggers a DHCP
+renegotiation on the TAP adapter when it comes up, however if you set
+the TAP\-Win32 adapter Media Status property to "Always Connected", you
+may need this flag.
+.TP
+.BI \-\-ip\-win32 \ method
+When using \fB\-\-ifconfig\fP on Windows, set the TAP\-Win32 adapter IP
+address and netmask using \fBmethod\fP\&. Don\(aqt use this option unless you
+are also using \fB\-\-ifconfig\fP\&.
+.INDENT 7.0
+.TP
+.B \fBmanual\fP
+Don\(aqt set the IP address or netmask automatically. Instead
+output a message to the console telling the user to configure the
+adapter manually and indicating the IP/netmask which OpenVPN
+expects the adapter to be set to.
+.TP
+.B \fBdynamic [offset] [lease\-time]\fP
+Automatically set the IP address and netmask by replying to DHCP
+query messages generated by the kernel. This mode is probably the
+"cleanest" solution for setting the TCP/IP properties since it
+uses the well\-known DHCP protocol. There are, however, two
+prerequisites for using this mode:
+.INDENT 7.0
+.IP 1. 3
+The TCP/IP properties for the TAP\-Win32 adapter must be set
+to "Obtain an IP address automatically", and
+.IP 2. 3
+OpenVPN needs to claim an IP address in the subnet for use
+as the virtual DHCP server address.
+.UNINDENT
+.sp
+By default in \fB\-\-dev tap\fP mode, OpenVPN will take the normally
+unused first address in the subnet. For example, if your subnet is
+\fB192.168.4.0 netmask 255.255.255.0\fP, then OpenVPN will take
+the IP address \fB192.168.4.0\fP to use as the virtual DHCP
+server address. In \fB\-\-dev tun\fP mode, OpenVPN will cause the DHCP
+server to masquerade as if it were coming from the remote endpoint.
+.sp
+The optional offset parameter is an integer which is > \fB\-256\fP
+and < \fB256\fP and which defaults to \-1. If offset is positive,
+the DHCP server will masquerade as the IP address at network
+address + offset. If offset is negative, the DHCP server will
+masquerade as the IP address at broadcast address + offset.
+.sp
+The Windows \fBipconfig /all\fP command can be used to show what
+Windows thinks the DHCP server address is. OpenVPN will "claim"
+this address, so make sure to use a free address. Having said that,
+different OpenVPN instantiations, including different ends of
+the same connection, can share the same virtual DHCP server
+address.
+.sp
+The \fBlease\-time\fP parameter controls the lease time of the DHCP
+assignment given to the TAP\-Win32 adapter, and is denoted in
+seconds. Normally a very long lease time is preferred because it
+prevents routes involving the TAP\-Win32 adapter from being lost
+when the system goes to sleep. The default lease time is one year.
+.TP
+.B \fBnetsh\fP
+Automatically set the IP address and netmask using the Windows
+command\-line "netsh" command. This method appears to work correctly
+on Windows XP but not Windows 2000.
+.TP
+.B \fBipapi\fP
+Automatically set the IP address and netmask using the Windows IP
+Helper API. This approach does not have ideal semantics, though
+testing has indicated that it works okay in practice. If you use
+this option, it is best to leave the TCP/IP properties for the
+TAP\-Win32 adapter in their default state, i.e. "Obtain an IP
+address automatically."
+.TP
+.B \fBadaptive\fP (Default)
+Try \fBdynamic\fP method initially and fail over to \fBnetsh\fP
+if the DHCP negotiation with the TAP\-Win32 adapter does not succeed
+in 20 seconds. Such failures have been known to occur when certain
+third\-party firewall packages installed on the client machine block
+the DHCP negotiation used by the TAP\-Win32 adapter. Note that if
+the \fBnetsh\fP failover occurs, the TAP\-Win32 adapter TCP/IP
+properties will be reset from DHCP to static, and this will cause
+future OpenVPN startups using the \fBadaptive\fP mode to use
+\fBnetsh\fP immediately, rather than trying \fBdynamic\fP first.
+.sp
+To "unstick" the \fBadaptive\fP mode from using \fBnetsh\fP,
+run OpenVPN at least once using the \fBdynamic\fP mode to restore
+the TAP\-Win32 adapter TCP/IP properties to a DHCP configuration.
+.UNINDENT
+.TP
+.B \-\-pause\-exit
+Put up a "press any key to continue" message on the console prior to
+OpenVPN program exit. This option is automatically used by the Windows
+explorer when OpenVPN is run on a configuration file using the
+right\-click explorer menu.
+.TP
+.B \-\-register\-dns
+Run \fBipconfig /flushdns\fP and \fBipconfig /registerdns\fP on
+connection initiation. This is known to kick Windows into recognizing
+pushed DNS servers.
+.TP
+.BI \-\-route\-method \ m
+Which method \fBm\fP to use for adding routes on Windows?
+.INDENT 7.0
+.TP
+.B \fBadaptive\fP (default)
+Try IP helper API first. If that fails, fall back to the route.exe
+shell command.
+.TP
+.B \fBipapi\fP
+Use IP helper API.
+.TP
+.B \fBexe\fP
+Call the route.exe shell command.
+.UNINDENT
+.TP
+.BI \-\-service \ args
+Should be used when OpenVPN is being automatically executed by another
+program in such a context that no interaction with the user via display
+or keyboard is possible.
+.sp
+Valid syntax:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+service exit\-event [0|1]
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+In general, end\-users should never need to explicitly use this option,
+as it is automatically added by the OpenVPN service wrapper when a given
+OpenVPN configuration is being run as a service.
+.sp
+\fBexit\-event\fP is the name of a Windows global event object, and OpenVPN
+will continuously monitor the state of this event object and exit when
+it becomes signaled.
+.sp
+The second parameter indicates the initial state of \fBexit\-event\fP and
+normally defaults to 0.
+.sp
+Multiple OpenVPN processes can be simultaneously executed with the same
+\fBexit\-event\fP parameter. In any case, the controlling process can
+signal \fBexit\-event\fP, causing all such OpenVPN processes to exit.
+.sp
+When executing an OpenVPN process using the \fB\-\-service\fP directive,
+OpenVPN will probably not have a console window to output status/error
+messages, therefore it is useful to use \fB\-\-log\fP or \fB\-\-log\-append\fP to
+write these messages to a file.
+.TP
+.B \-\-show\-adapters
+(Standalone) Show available TAP\-Win32 adapters which can be selected
+using the \fB\-\-dev\-node\fP option. On non\-Windows systems, the
+\fBifconfig\fP(8) command provides similar functionality.
+.TP
+.B \-\-show\-net
+(Standalone) Show OpenVPN\(aqs view of the system routing table and network
+adapter list.
+.TP
+.B \-\-show\-net\-up
+Output OpenVPN\(aqs view of the system routing table and network adapter
+list to the syslog or log file after the TUN/TAP adapter has been
+brought up and any routes have been added.
+.TP
+.B \-\-show\-valid\-subnets
+(Standalone) Show valid subnets for \fB\-\-dev tun\fP emulation. Since the
+TAP\-Win32 driver exports an ethernet interface to Windows, and since TUN
+devices are point\-to\-point in nature, it is necessary for the TAP\-Win32
+driver to impose certain constraints on TUN endpoint address selection.
+.sp
+Namely, the point\-to\-point endpoints used in TUN device emulation must
+be the middle two addresses of a /30 subnet (netmask 255.255.255.252).
+.TP
+.BI \-\-tap\-sleep \ n
+Cause OpenVPN to sleep for \fBn\fP seconds immediately after the TAP\-Win32
+adapter state is set to "connected".
+.sp
+This option is intended to be used to troubleshoot problems with the
+\fB\-\-ifconfig\fP and \fB\-\-ip\-win32\fP options, and is used to give the
+TAP\-Win32 adapter time to come up before Windows IP Helper API
+operations are applied to it.
+.TP
+.BI \-\-win\-sys \ path
+Set the Windows system directory pathname to use when looking for system
+executables such as \fBroute.exe\fP and \fBnetsh.exe\fP\&. By default, if this
+directive is not specified, OpenVPN will use the SystemRoot environment
+variable.
+.sp
+This option has changed behaviour since OpenVPN 2.3. Earlier you had to
+define \fB\-\-win\-sys env\fP to use the SystemRoot environment variable,
+otherwise it defaulted to \fBC:\e\eWINDOWS\fP\&. It is not needed to use
+the \fBenv\fP keyword any more, and it will just be ignored. A warning is
+logged when this is found in the configuration file.
+.TP
+.BI \-\-windows\-driver \ drv
+Specifies which tun driver to use. Values are \fBtap\-windows6\fP
+(default) and \fBwintun\fP\&. This is a Windows\-only option.
+\fBwintun\fP" requires \fB\-\-dev tun\fP and the OpenVPN process to run
+elevated, or be invoked using the Interactive Service.
+.UNINDENT
+.SS Standalone Debug Options
+.INDENT 0.0
+.TP
+.BI \-\-show\-gateway \ args
+(Standalone) Show current IPv4 and IPv6 default gateway and interface
+towards the gateway (if the protocol in question is enabled).
+.sp
+Valid syntax:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+\-\-show\-gateway
+\-\-show\-gateway IPv6\-target
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+If an IPv6 target address is passed as argument, the IPv6 route for this
+host is reported.
+.UNINDENT
+.SS Advanced Expert Options
+.sp
+These are options only required when special tweaking is needed, often
+used when debugging or testing out special usage scenarios.
+.INDENT 0.0
+.TP
+.BI \-\-hash\-size \ args
+Set the size of the real address hash table to \fBr\fP and the virtual
+address table to \fBv\fP\&.
+.sp
+Valid syntax:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+hash\-size r v
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+By default, both tables are sized at 256 buckets.
+.TP
+.BI \-\-bcast\-buffers \ n
+Allocate \fBn\fP buffers for broadcast datagrams (default \fB256\fP).
+.TP
+.B \-\-persist\-local\-ip
+Preserve initially resolved local IP address and port number across
+\fBSIGUSR1\fP or \fB\-\-ping\-restart\fP restarts.
+.TP
+.B \-\-persist\-remote\-ip
+Preserve most recently authenticated remote IP address and port number
+across \fBSIGUSR1\fP or \fB\-\-ping\-restart\fP restarts.
+.TP
+.BI \-\-prng \ args
+\fI(Advanced)\fP Change the PRNG (Pseudo\-random number generator) parameters
+.sp
+Valid syntaxes:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+prng alg
+prng alg nsl
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Changes the PRNG to use digest algorithm \fBalg\fP (default \fBsha1\fP),
+and set \fBnsl\fP (default \fB16\fP) to the size in bytes of the nonce
+secret length (between 16 and 64).
+.sp
+Set \fBalg\fP to \fBnone\fP to disable the PRNG and use the OpenSSL
+RAND_bytes function instead for all of OpenVPN\(aqs pseudo\-random number
+needs.
+.TP
+.BI \-\-rcvbuf \ size
+Set the TCP/UDP socket receive buffer size. Defaults to operating system
+default.
+.TP
+.BI \-\-shaper \ n
+Limit bandwidth of outgoing tunnel data to \fBn\fP bytes per second on the
+TCP/UDP port. Note that this will only work if mode is set to
+\fBp2p\fP\&. If you want to limit the bandwidth in both directions, use
+this option on both peers.
+.sp
+OpenVPN uses the following algorithm to implement traffic shaping: Given
+a shaper rate of \fBn\fP bytes per second, after a datagram write of \fBb\fP
+bytes is queued on the TCP/UDP port, wait a minimum of \fB(b / n)\fP
+seconds before queuing the next write.
+.sp
+It should be noted that OpenVPN supports multiple tunnels between the
+same two peers, allowing you to construct full\-speed and reduced
+bandwidth tunnels at the same time, routing low\-priority data such as
+off\-site backups over the reduced bandwidth tunnel, and other data over
+the full\-speed tunnel.
+.sp
+Also note that for low bandwidth tunnels (under 1000 bytes per second),
+you should probably use lower MTU values as well (see above), otherwise
+the packet latency will grow so large as to trigger timeouts in the TLS
+layer and TCP connections running over the tunnel.
+.sp
+OpenVPN allows \fBn\fP to be between 100 bytes/sec and 100 Mbytes/sec.
+.TP
+.BI \-\-sndbuf \ size
+Set the TCP/UDP socket send buffer size. Defaults to operating system
+default.
+.TP
+.BI \-\-tcp\-queue\-limit \ n
+Maximum number of output packets queued before TCP (default \fB64\fP).
+.sp
+When OpenVPN is tunneling data from a TUN/TAP device to a remote client
+over a TCP connection, it is possible that the TUN/TAP device might
+produce data at a faster rate than the TCP connection can support. When
+the number of output packets queued before sending to the TCP socket
+reaches this limit for a given client connection, OpenVPN will start to
+drop outgoing packets directed at this client.
+.TP
+.BI \-\-txqueuelen \ n
+\fI(Linux only)\fP Set the TX queue length on the TUN/TAP interface.
+Currently defaults to operating system default.
+.UNINDENT
+.SH UNSUPPORTED OPTIONS
+.sp
+Options listed in this section have been removed from OpenVPN and are no
+longer supported
+.INDENT 0.0
+.TP
+.B \-\-client\-cert\-not\-required
+Removed in OpenVPN 2.5. This should be replaxed with
+\fB\-\-verify\-client\-cert none\fP\&.
+.TP
+.B \-\-ifconfig\-pool\-linear
+Removed in OpenVPN 2.5. This should be replaced with \fB\-\-topology p2p\fP\&.
+.TP
+.B \-\-key\-method
+Removed in OpenVPN 2.5. This option should not be used, as using the old
+\fBkey\-method\fP weakens the VPN tunnel security. The old \fBkey\-method\fP
+was also only needed when the remote side was older than OpenVPN 2.0.
+.TP
+.B \-\-no\-iv
+Removed in OpenVPN 2.5. This option should not be used as it weakens the
+VPN tunnel security. This has been a NOOP option since OpenVPN 2.4.
+.TP
+.B \-\-no\-replay
+Removed in OpenVPN 2.5. This option should not be used as it weakens the
+VPN tunnel security.
+.TP
+.B \-\-ns\-cert\-type
+Removed in OpenVPN 2.5. The \fBnsCertType\fP field is no longer supported
+in recent SSL/TLS libraries. If your certificates does not include \fIkey
+usage\fP and \fIextended key usage\fP fields, they must be upgraded and the
+\fB\-\-remote\-cert\-tls\fP option should be used instead.
+.UNINDENT
+.SH CONNECTION PROFILES
+.sp
+Client configuration files may contain multiple remote servers which
+it will attempt to connect against. But there are some configuration
+options which are related to specific \fB\-\-remote\fP options. For these
+use cases, connection profiles are the solution.
+.sp
+By enacpulating the \fB\-\-remote\fP option and related options within
+\fB<connection>\fP and \fB</connection>\fP, these options are handled as a
+group.
+.sp
+An OpenVPN client will try each connection profile sequentially until it
+achieves a successful connection.
+.sp
+\fB\-\-remote\-random\fP can be used to initially "scramble" the connection
+list.
+.sp
+Here is an example of connection profile usage:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+client
+dev tun
+
+<connection>
+remote 198.19.34.56 1194 udp
+</connection>
+
+<connection>
+remote 198.19.34.56 443 tcp
+</connection>
+
+<connection>
+remote 198.19.34.56 443 tcp
+http\-proxy 192.168.0.8 8080
+</connection>
+
+<connection>
+remote 198.19.36.99 443 tcp
+http\-proxy 192.168.0.8 8080
+</connection>
+
+persist\-key
+persist\-tun
+pkcs12 client.p12
+remote\-cert\-tls server
+verb 3
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+First we try to connect to a server at 198.19.34.56:1194 using UDP. If
+that fails, we then try to connect to 198.19.34.56:443 using TCP. If
+that also fails, then try connecting through an HTTP proxy at
+192.168.0.8:8080 to 198.19.34.56:443 using TCP. Finally, try to connect
+through the same proxy to a server at 198.19.36.99:443 using TCP.
+.sp
+The following OpenVPN options may be used inside of a \fB<connection>\fP
+block:
+.sp
+\fBbind\fP, \fBconnect\-retry\fP, \fBconnect\-retry\-max\fP, \fBconnect\-timeout\fP,
+\fBexplicit\-exit\-notify\fP, \fBfloat\fP, \fBfragment\fP, \fBhttp\-proxy\fP,
+\fBhttp\-proxy\-option\fP, \fBkey\-direction\fP, \fBlink\-mtu\fP, \fBlocal\fP,
+\fBlport\fP, \fBmssfix\fP, \fBmtu\-disc\fP, \fBnobind\fP, \fBport\fP, \fBproto\fP,
+\fBremote\fP, \fBrport\fP, \fBsocks\-proxy\fP, \fBtls\-auth\fP, \fBtls\-crypt\fP,
+\fBtun\-mtu and\fP, \fBtun\-mtu\-extra\fP\&.
+.sp
+A defaulting mechanism exists for specifying options to apply to all
+\fB<connection>\fP profiles. If any of the above options (with the
+exception of \fBremote\fP ) appear outside of a \fB<connection>\fP block,
+but in a configuration file which has one or more \fB<connection>\fP
+blocks, the option setting will be used as a default for
+\fB<connection>\fP blocks which follow it in the configuration file.
+.sp
+For example, suppose the \fBnobind\fP option were placed in the sample
+configuration file above, near the top of the file, before the first
+\fB<connection>\fP block. The effect would be as if \fBnobind\fP were
+declared in all \fB<connection>\fP blocks below it.
+.SH INLINE FILE SUPPORT
+.sp
+OpenVPN allows including files in the main configuration for the \fB\-\-ca\fP,
+\fB\-\-cert\fP, \fB\-\-dh\fP, \fB\-\-extra\-certs\fP, \fB\-\-key\fP, \fB\-\-pkcs12\fP,
+\fB\-\-secret\fP, \fB\-\-crl\-verify\fP, \fB\-\-http\-proxy\-user\-pass\fP, \fB\-\-tls\-auth\fP,
+\fB\-\-auth\-gen\-token\-secret\fP, \fB\-\-tls\-crypt\fP and \fB\-\-tls\-crypt\-v2\fP
+options.
+.sp
+Each inline file started by the line \fB<option>\fP and ended by the line
+\fB</option>\fP
+.sp
+Here is an example of an inline file usage
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+<cert>
+\-\-\-\-\-BEGIN CERTIFICATE\-\-\-\-\-
+[...]
+\-\-\-\-\-END CERTIFICATE\-\-\-\-\-
+</cert>
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+When using the inline file feature with \fB\-\-pkcs12\fP the inline file has
+to be base64 encoded. Encoding of a .p12 file into base64 can be done
+for example with OpenSSL by running \fBopenssl base64 \-in input.p12\fP
+.SH SIGNALS
+.INDENT 0.0
+.TP
+.B \fBSIGHUP\fP
+Cause OpenVPN to close all TUN/TAP and network connections, restart,
+re\-read the configuration file (if any), and reopen TUN/TAP and network
+connections.
+.TP
+.B \fBSIGUSR1\fP
+Like \fBSIGHUP\(ga\fP, except don\(aqt re\-read configuration file, and
+possibly don\(aqt close and reopen TUN/TAP device, re\-read key files,
+preserve local IP address/port, or preserve most recently authenticated
+remote IP address/port based on \fB\-\-persist\-tun\fP, \fB\-\-persist\-key\fP,
+\fB\-\-persist\-local\-ip\fP and \fB\-\-persist\-remote\-ip\fP options respectively
+(see above).
+.sp
+This signal may also be internally generated by a timeout condition,
+governed by the \fB\-\-ping\-restart\fP option.
+.sp
+This signal, when combined with \fB\-\-persist\-remote\-ip\fP, may be sent
+when the underlying parameters of the host\(aqs network interface change
+such as when the host is a DHCP client and is assigned a new IP address.
+See \fB\-\-ipchange\fP for more information.
+.TP
+.B \fBSIGUSR2\fP
+Causes OpenVPN to display its current statistics (to the syslog file if
+\fB\-\-daemon\fP is used, or stdout otherwise).
+.TP
+.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
+.SH HOWTO
+.sp
+For a more comprehensive guide to setting up OpenVPN in a production
+setting, see the OpenVPN HOWTO at
+\fI\%https://openvpn.net/community\-resources/how\-to/\fP
+.SH PROTOCOL
+.sp
+For a description of OpenVPN\(aqs underlying protocol, see
+\fI\%https://openvpn.net/community\-resources/openvpn\-protocol/\fP
+.SH WEB
+.sp
+OpenVPN\(aqs web site is at \fI\%https://openvpn.net/\fP
+.sp
+Go here to download the latest version of OpenVPN, subscribe to the
+mailing lists, read the mailing list archives, or browse the SVN
+repository.
+.SH BUGS
+.sp
+Report all bugs to the OpenVPN team \fI\%info@openvpn.net\fP
+.SH SEE ALSO
+.sp
+\fBdhcpcd\fP(8),
+\fBifconfig\fP(8),
+\fBopenssl\fP(1),
+\fBroute\fP(8),
+\fBscp\fP(1)
+\fBssh\fP(1)
+.SH NOTES
+.sp
+This product includes software developed by the OpenSSL Project
+(\fI\%https://www.openssl.org/\fP)
+.sp
+For more information on the TLS protocol, see
+\fI\%http://www.ietf.org/rfc/rfc2246.txt\fP
+.sp
+For more information on the LZO real\-time compression library see
+\fI\%https://www.oberhumer.com/opensource/lzo/\fP
+.SH COPYRIGHT
+.sp
+Copyright (C) 2002\-2020 OpenVPN Inc This program is free software; you
+can redistribute it and/or modify it under the terms of the GNU General
+Public License version 2 as published by the Free Software Foundation.
+.SH AUTHORS
+.sp
+James Yonan \fI\%james@openvpn.net\fP
+.\" Generated by docutils manpage writer.
+.
diff --git a/doc/openvpn.8.html b/doc/openvpn.8.html
new file mode 100644
index 0000000..d6b2719
--- /dev/null
+++ b/doc/openvpn.8.html
@@ -0,0 +1,6023 @@
+<?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.14: http://docutils.sourceforge.net/" />
+<title>openvpn</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">
+<h1 class="title">openvpn</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">8</td>
+</tr>
+<tr class="manual-group field"><th class="docinfo-name">Manual group:</th><td class="field-body">System Manager's Manual</td>
+</tr>
+</tbody>
+</table>
+<div class="section" id="synopsis">
+<h1>SYNOPSIS</h1>
+<div class="line-block">
+<div class="line"><tt class="docutils literal">openvpn</tt> [ options ... ]</div>
+<div class="line"><tt class="docutils literal">openvpn</tt> <tt class="docutils literal"><span class="pre">--help</span></tt></div>
+</div>
+</div>
+<div class="section" id="introduction">
+<h1>INTRODUCTION</h1>
+<p>OpenVPN is an open source VPN daemon by James Yonan. Because OpenVPN
+tries to be a universal VPN tool offering a great deal of flexibility,
+there are a lot of options on this manual page. If you're new to
+OpenVPN, you might want to skip ahead to the examples section where you
+will see how to construct simple VPNs on the command line without even
+needing a configuration file.</p>
+<p>Also note that there's more documentation and examples on the OpenVPN
+web site: <a class="reference external" href="https://openvpn.net/">https://openvpn.net/</a></p>
+<p>And if you would like to see a shorter version of this manual, see the
+openvpn usage message which can be obtained by running <strong>openvpn</strong>
+without any parameters.</p>
+</div>
+<div class="section" id="description">
+<h1>DESCRIPTION</h1>
+<p>OpenVPN is a robust and highly flexible VPN daemon. OpenVPN supports
+SSL/TLS security, ethernet bridging, TCP or UDP tunnel transport through
+proxies or NAT, support for dynamic IP addresses and DHCP, scalability
+to hundreds or thousands of users, and portability to most major OS
+platforms.</p>
+<p>OpenVPN is tightly bound to the OpenSSL library, and derives much of its
+crypto capabilities from it.</p>
+<p>OpenVPN supports conventional encryption using a pre-shared secret key
+<strong>(Static Key mode)</strong> or public key security <strong>(SSL/TLS mode)</strong> using
+client &amp; server certificates. OpenVPN also supports non-encrypted
+TCP/UDP tunnels.</p>
+<p>OpenVPN is designed to work with the <strong>TUN/TAP</strong> virtual networking
+interface that exists on most platforms.</p>
+<p>Overall, OpenVPN aims to offer many of the key features of IPSec but
+with a relatively lightweight footprint.</p>
+</div>
+<div class="section" id="options">
+<h1>OPTIONS</h1>
+<p>OpenVPN allows any option to be placed either on the command line or in
+a configuration file. Though all command line options are preceded by a
+double-leading-dash (&quot;--&quot;), this prefix can be removed when an option is
+placed in a configuration file.</p>
+<div class="section" id="generic-options">
+<h2>Generic Options</h2>
+<p>This section covers generic options which are accessible regardless of
+which mode OpenVPN is configured as.</p>
+<table class="docutils option-list" frame="void" rules="none">
+<col class="option" />
+<col class="description" />
+<tbody valign="top">
+<tr><td class="option-group">
+<kbd><span class="option">--help</span></kbd></td>
+<td>Show options.</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--auth-nocache</span></kbd></td>
+<td><p class="first">Don't cache <tt class="docutils literal"><span class="pre">--askpass</span></tt> or <tt class="docutils literal"><span class="pre">--auth-user-pass</span></tt> username/passwords in
+virtual memory.</p>
+<p>If specified, this directive will cause OpenVPN to immediately forget
+username/password inputs after they are used. As a result, when OpenVPN
+needs a username/password, it will prompt for input from stdin, which
+may be multiple times during the duration of an OpenVPN session.</p>
+<p>When using <tt class="docutils literal"><span class="pre">--auth-nocache</span></tt> in combination with a user/password file
+and <tt class="docutils literal"><span class="pre">--chroot</span></tt> or <tt class="docutils literal"><span class="pre">--daemon</span></tt>, make sure to use an absolute path.</p>
+<p class="last">This directive does not affect the <tt class="docutils literal"><span class="pre">--http-proxy</span></tt> username/password.
+It is always cached.</p>
+</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--cd <var>dir</var></span></kbd></td>
+<td><p class="first">Change directory to <tt class="docutils literal">dir</tt> prior to reading any files such as
+configuration files, key files, scripts, etc. <tt class="docutils literal">dir</tt> should be an
+absolute path, with a leading &quot;/&quot;, and without any references to the
+current directory such as <code>.</code> or <code>..</code>.</p>
+<p class="last">This option is useful when you are running OpenVPN in <tt class="docutils literal"><span class="pre">--daemon</span></tt> mode,
+and you want to consolidate all of your OpenVPN control files in one
+location.</p>
+</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--chroot <var>dir</var></span></kbd></td>
+<td><p class="first">Chroot to <tt class="docutils literal">dir</tt> after initialization. <tt class="docutils literal"><span class="pre">--chroot</span></tt> essentially
+redefines <tt class="docutils literal">dir</tt> as being the top level directory tree (/). OpenVPN
+will therefore be unable to access any files outside this tree. This can
+be desirable from a security standpoint.</p>
+<p>Since the chroot operation is delayed until after initialization, most
+OpenVPN options that reference files will operate in a pre-chroot
+context.</p>
+<p>In many cases, the <tt class="docutils literal">dir</tt> parameter can point to an empty directory,
+however complications can result when scripts or restarts are executed
+after the chroot operation.</p>
+<p class="last">Note: The SSL library will probably need /dev/urandom to be available
+inside the chroot directory <tt class="docutils literal">dir</tt>. This is because SSL libraries
+occasionally need to collect fresh random. Newer linux kernels and some
+BSDs implement a getrandom() or getentropy() syscall that removes the
+need for /dev/urandom to be available.</p>
+</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--config <var>file</var></span></kbd></td>
+<td><p class="first">Load additional config options from <tt class="docutils literal">file</tt> where each line corresponds
+to one command line option, but with the leading '--' removed.</p>
+<p>If <tt class="docutils literal"><span class="pre">--config</span> file</tt> is the only option to the openvpn command, the
+<tt class="docutils literal"><span class="pre">--config</span></tt> can be removed, and the command can be given as <tt class="docutils literal">openvpn
+file</tt></p>
+<p>Note that configuration files can be nested to a reasonable depth.</p>
+<p>Double quotation or single quotation characters (&quot;&quot;, '') can be used to
+enclose single parameters containing whitespace, and &quot;#&quot; or &quot;;&quot;
+characters in the first column can be used to denote comments.</p>
+<p>Note that OpenVPN 2.0 and higher performs backslash-based shell escaping
+for characters not in single quotations, so the following mappings
+should be observed:</p>
+<pre class="literal-block">
+\\ Maps to a single backslash character (\).
+\&quot; Pass a literal doublequote character (&quot;), don't
+ interpret it as enclosing a parameter.
+\[SPACE] Pass a literal space or tab character, don't
+ interpret it as a parameter delimiter.
+</pre>
+<p>For example on Windows, use double backslashes to represent pathnames:</p>
+<pre class="literal-block">
+secret &quot;c:\\OpenVPN\\secret.key&quot;
+</pre>
+<p>For examples of configuration files, see
+<a class="reference external" href="https://openvpn.net/community-resources/how-to/">https://openvpn.net/community-resources/how-to/</a></p>
+<p>Here is an example configuration file:</p>
+<pre class="last literal-block">
+#
+# Sample OpenVPN configuration file for
+# using a pre-shared static key.
+#
+# '#' or ';' may be used to delimit comments.
+
+# Use a dynamic tun device.
+dev tun
+
+# Our remote peer
+remote mypeer.mydomain
+
+# 10.1.0.1 is our local VPN endpoint
+# 10.1.0.2 is our remote VPN endpoint
+ifconfig 10.1.0.1 10.1.0.2
+
+# Our pre-shared static key
+secret static.key
+</pre>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--daemon <var>progname</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Become a daemon after all initialization functions are completed. This
+option will cause all message and error output to be sent to the syslog
+file (such as <code>/var/log/messages</code>), except for the output of
+scripts and ifconfig commands, which will go to <code>/dev/null</code> unless
+otherwise redirected. The syslog redirection occurs immediately at the
+point that <tt class="docutils literal"><span class="pre">--daemon</span></tt> is parsed on the command line even though the
+daemonization point occurs later. If one of the <tt class="docutils literal"><span class="pre">--log</span></tt> options is
+present, it will supersede syslog redirection.</p>
+<p>The optional <tt class="docutils literal">progname</tt> parameter will cause OpenVPN to report its
+program name to the system logger as <tt class="docutils literal">progname</tt>. This can be useful in
+linking OpenVPN messages in the syslog file with specific tunnels. When
+unspecified, <tt class="docutils literal">progname</tt> defaults to &quot;openvpn&quot;.</p>
+<p>When OpenVPN is run with the <tt class="docutils literal"><span class="pre">--daemon</span></tt> option, it will try to delay
+daemonization until the majority of initialization functions which are
+capable of generating fatal errors are complete. This means that
+initialization scripts can test the return status of the openvpn command
+for a fairly reliable indication of whether the command has correctly
+initialized and entered the packet forwarding event loop.</p>
+<p>In OpenVPN, the vast majority of errors which occur after initialization
+are non-fatal.</p>
+<p>Note: as soon as OpenVPN has daemonized, it can not ask for usernames,
+passwords, or key pass phrases anymore. This has certain consequences,
+namely that using a password-protected private key will fail unless the
+<tt class="docutils literal"><span class="pre">--askpass</span></tt> option is used to tell OpenVPN to ask for the pass phrase
+(this requirement is new in v2.3.7, and is a consequence of calling
+daemon() before initializing the crypto layer).</p>
+<p class="last">Further, using <tt class="docutils literal"><span class="pre">--daemon</span></tt> together with <tt class="docutils literal"><span class="pre">--auth-user-pass</span></tt> (entered
+on console) and <tt class="docutils literal"><span class="pre">--auth-nocache</span></tt> will fail as soon as key
+renegotiation (and reauthentication) occurs.</p>
+</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--disable-occ</span></kbd></td>
+<td><p class="first">Don't output a warning message if option inconsistencies are detected
+between peers. An example of an option inconsistency would be where one
+peer uses <tt class="docutils literal"><span class="pre">--dev</span> tun</tt> while the other peer uses <tt class="docutils literal"><span class="pre">--dev</span> tap</tt>.</p>
+<p class="last">Use of this option is discouraged, but is provided as a temporary fix in
+situations where a recent version of OpenVPN must connect to an old
+version.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--engine <var>engine-name</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Enable OpenSSL hardware-based crypto engine functionality.</p>
+<p class="last">If <tt class="docutils literal"><span class="pre">engine-name</span></tt> is specified, use a specific crypto engine. Use the
+<tt class="docutils literal"><span class="pre">--show-engines</span></tt> standalone option to list the crypto engines which
+are supported by OpenSSL.</p>
+</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--fast-io</span></kbd></td>
+<td><p class="first">(Experimental) Optimize TUN/TAP/UDP I/O writes by avoiding a call to
+poll/epoll/select prior to the write operation. The purpose of such a
+call would normally be to block until the device or socket is ready to
+accept the write. Such blocking is unnecessary on some platforms which
+don't support write blocking on UDP sockets or TUN/TAP devices. In such
+cases, one can optimize the event loop by avoiding the poll/epoll/select
+call, improving CPU efficiency by 5% to 10%.</p>
+<p class="last">This option can only be used on non-Windows systems, when <tt class="docutils literal"><span class="pre">--proto</span>
+udp</tt> is specified, and when <tt class="docutils literal"><span class="pre">--shaper</span></tt> is NOT specified.</p>
+</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--group <var>group</var></span></kbd></td>
+<td>Similar to the <tt class="docutils literal"><span class="pre">--user</span></tt> option, this option changes the group ID of
+the OpenVPN process to <tt class="docutils literal">group</tt> after initialization.</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--ignore-unknown-option <var>args</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Valid syntax:</p>
+<pre class="literal-block">
+ignore-unknown-options opt1 opt2 opt3 ... optN
+</pre>
+<p>When one of options <tt class="docutils literal">opt1 ... optN</tt> is encountered in the configuration
+file the configuration file parsing does not fail if this OpenVPN version
+does not support the option. Multiple <tt class="docutils literal"><span class="pre">--ignore-unknown-option</span></tt> options
+can be given to support a larger number of options to ignore.</p>
+<p>This option should be used with caution, as there are good security
+reasons for having OpenVPN fail if it detects problems in a config file.
+Having said that, there are valid reasons for wanting new software
+features to gracefully degrade when encountered by older software
+versions.</p>
+<p class="last"><tt class="docutils literal"><span class="pre">--ignore-unknown-option</span></tt> is available since OpenVPN 2.3.3.</p>
+</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--iproute <var>cmd</var></span></kbd></td>
+<td>Set alternate command to execute instead of default <tt class="docutils literal">iproute2</tt> command.
+May be used in order to execute OpenVPN in unprivileged environment.</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--keying-material-exporter <var>args</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Save Exported Keying Material [RFC5705] of len bytes (must be between 16
+and 4095 bytes) using <tt class="docutils literal">label</tt> in environment
+(<code>exported_keying_material</code>) for use by plugins in
+<code>OPENVPN_PLUGIN_TLS_FINAL</code> callback.</p>
+<p>Valid syntax:</p>
+<pre class="literal-block">
+keying-material-exporter label len
+</pre>
+<p class="last">Note that exporter <tt class="docutils literal">labels</tt> have the potential to collide with existing
+PRF labels. In order to prevent this, labels <em>MUST</em> begin with
+<code>EXPORTER</code>.</p>
+</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--mlock</span></kbd></td>
+<td><p class="first">Disable paging by calling the POSIX mlockall function. Requires that
+OpenVPN be initially run as root (though OpenVPN can subsequently
+downgrade its UID using the <tt class="docutils literal"><span class="pre">--user</span></tt> option).</p>
+<p>Using this option ensures that key material and tunnel data are never
+written to disk due to virtual memory paging operations which occur
+under most modern operating systems. It ensures that even if an attacker
+was able to crack the box running OpenVPN, he would not be able to scan
+the system swap file to recover previously used ephemeral keys, which
+are used for a period of time governed by the <tt class="docutils literal"><span class="pre">--reneg</span></tt> options (see
+below), then are discarded.</p>
+<p class="last">The downside of using <tt class="docutils literal"><span class="pre">--mlock</span></tt> is that it will reduce the amount of
+physical memory available to other applications.</p>
+</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--nice <var>n</var></span></kbd></td>
+<td>Change process priority after initialization (<tt class="docutils literal">n</tt> greater than 0 is
+lower priority, <tt class="docutils literal">n</tt> less than zero is higher priority).</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--persist-key</span></kbd></td>
+<td><p class="first">Don't re-read key files across <code>SIGUSR1</code> or <tt class="docutils literal"><span class="pre">--ping-restart</span></tt>.</p>
+<p>This option can be combined with <tt class="docutils literal"><span class="pre">--user</span> nobody</tt> to allow restarts
+triggered by the <code>SIGUSR1</code> signal. Normally if you drop root
+privileges in OpenVPN, the daemon cannot be restarted since it will now
+be unable to re-read protected key files.</p>
+<p class="last">This option solves the problem by persisting keys across <code>SIGUSR1</code>
+resets, so they don't need to be re-read.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--remap-usr1 <var>signal</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Control whether internally or externally generated <code>SIGUSR1</code> signals
+are remapped to <code>SIGHUP</code> (restart without persisting state) or
+SIGTERM (exit).</p>
+<p class="last"><tt class="docutils literal">signal</tt> can be set to <code>SIGHUP</code> or <code>SIGTERM</code>. By default,
+no remapping occurs.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--script-security <var>level</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">This directive offers policy-level control over OpenVPN's usage of
+external programs and scripts. Lower <tt class="docutils literal">level</tt> values are more
+restrictive, higher values are more permissive. Settings for <tt class="docutils literal">level</tt>:</p>
+<dl class="docutils">
+<dt><code>0</code></dt>
+<dd>Strictly no calling of external programs.</dd>
+<dt><code>1</code></dt>
+<dd>(Default) Only call built-in executables such as ifconfig,
+ip, route, or netsh.</dd>
+<dt><code>2</code></dt>
+<dd>Allow calling of built-in executables and user-defined
+scripts.</dd>
+<dt><code>3</code></dt>
+<dd>Allow passwords to be passed to scripts via environmental
+variables (potentially unsafe).</dd>
+</dl>
+<p>OpenVPN releases before v2.3 also supported a <tt class="docutils literal">method</tt> flag which
+indicated how OpenVPN should call external commands and scripts. This
+could be either <code>execve</code> or <code>system</code>. As of OpenVPN 2.3, this
+flag is no longer accepted. In most *nix environments the execve()
+approach has been used without any issues.</p>
+<p>Some directives such as <tt class="docutils literal"><span class="pre">--up</span></tt> allow options to be passed to the
+external script. In these cases make sure the script name does not
+contain any spaces or the configuration parser will choke because it
+can't determine where the script name ends and script options start.</p>
+<p>To run scripts in Windows in earlier OpenVPN versions you needed to
+either add a full path to the script interpreter which can parse the
+script or use the <tt class="docutils literal">system</tt> flag to run these scripts. As of OpenVPN
+2.3 it is now a strict requirement to have full path to the script
+interpreter when running non-executables files. This is not needed for
+executable files, such as .exe, .com, .bat or .cmd files. For example,
+if you have a Visual Basic script, you must use this syntax now:</p>
+<pre class="literal-block">
+--up 'C:\\Windows\\System32\\wscript.exe C:\\Program\ Files\\OpenVPN\\config\\my-up-script.vbs'
+</pre>
+<p>Please note the single quote marks and the escaping of the backslashes
+(\) and the space character.</p>
+<p class="last">The reason the support for the <code>system</code> flag was removed is due to
+the security implications with shell expansions when executing scripts
+via the <code>system()</code> call.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--setcon <var>context</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Apply SELinux <tt class="docutils literal">context</tt> after initialization. This essentially
+provides the ability to restrict OpenVPN's rights to only network I/O
+operations, thanks to SELinux. This goes further than <tt class="docutils literal"><span class="pre">--user</span></tt> and
+<tt class="docutils literal"><span class="pre">--chroot</span></tt> in that those two, while being great security features,
+unfortunately do not protect against privilege escalation by
+exploitation of a vulnerable system call. You can of course combine all
+three, but please note that since setcon requires access to /proc you
+will have to provide it inside the chroot directory (e.g. with mount
+--bind).</p>
+<p>Since the setcon operation is delayed until after initialization,
+OpenVPN can be restricted to just network-related system calls, whereas
+by applying the context before startup (such as the OpenVPN one provided
+in the SELinux Reference Policies) you will have to allow many things
+required only during initialization.</p>
+<p class="last">Like with chroot, complications can result when scripts or restarts are
+executed after the setcon operation, which is why you should really
+consider using the <tt class="docutils literal"><span class="pre">--persist-key</span></tt> and <tt class="docutils literal"><span class="pre">--persist-tun</span></tt> options.</p>
+</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--status <var>args</var></span></kbd></td>
+<td><p class="first">Write operational status to <tt class="docutils literal">file</tt> every <tt class="docutils literal">n</tt> seconds.</p>
+<p>Valid syntaxes:</p>
+<pre class="literal-block">
+status file
+status file n
+</pre>
+<p>Status can also be written to the syslog by sending a <code>SIGUSR2</code>
+signal.</p>
+<p>With multi-client capability enabled on a server, the status file
+includes a list of clients and a routing table. The output format can be
+controlled by the <tt class="docutils literal"><span class="pre">--status-version</span></tt> option in that case.</p>
+<p class="last">For clients or instances running in point-to-point mode, it will contain
+the traffic statistics.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--status-version <var>n</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Set the status file format version number to <tt class="docutils literal">n</tt>.</p>
+<p>This only affects the status file on servers with multi-client
+capability enabled. Valid status version values:</p>
+<dl class="last docutils">
+<dt><code>1</code></dt>
+<dd>Traditional format (default). The client list contains the
+following fields comma-separated: Common Name, Real Address, Bytes
+Received, Bytes Sent, Connected Since.</dd>
+<dt><code>2</code></dt>
+<dd>A more reliable format for external processing. Compared to
+version <code>1</code>, the client list contains some additional fields:
+Virtual Address, Virtual IPv6 Address, Username, Client ID, Peer ID,
+Data Channel Cipher. Future versions may extend the number of fields.</dd>
+<dt><code>3</code></dt>
+<dd>Identical to <code>2</code>, but fields are tab-separated.</dd>
+</dl>
+</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--test-crypto</span></kbd></td>
+<td><p class="first">Do a self-test of OpenVPN's crypto options by encrypting and decrypting
+test packets using the data channel encryption options specified above.
+This option does not require a peer to function, and therefore can be
+specified without <tt class="docutils literal"><span class="pre">--dev</span></tt> or <tt class="docutils literal"><span class="pre">--remote</span></tt>.</p>
+<p>The typical usage of <tt class="docutils literal"><span class="pre">--test-crypto</span></tt> would be something like this:</p>
+<pre class="literal-block">
+openvpn --test-crypto --secret key
+</pre>
+<p>or</p>
+<pre class="literal-block">
+openvpn --test-crypto --secret key --verb 9
+</pre>
+<p class="last">This option is very useful to test OpenVPN after it has been ported to a
+new platform, or to isolate problems in the compiler, OpenSSL crypto
+library, or OpenVPN's crypto code. Since it is a self-test mode,
+problems with encryption and authentication can be debugged
+independently of network and tunnel issues.</p>
+</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--tmp-dir <var>dir</var></span></kbd></td>
+<td><p class="first">Specify a directory <tt class="docutils literal">dir</tt> for temporary files. This directory will be
+used by openvpn processes and script to communicate temporary data with
+openvpn main process. Note that the directory must be writable by the
+OpenVPN process after it has dropped it's root privileges.</p>
+<p>This directory will be used by in the following cases:</p>
+<ul class="last simple">
+<li><tt class="docutils literal"><span class="pre">--client-connect</span></tt> scripts and <code>OPENVPN_PLUGIN_CLIENT_CONNECT</code>
+plug-in hook to dynamically generate client-specific configuration
+<code>client_connect_config_file</code> and return success/failure via
+<code>client_connect_deferred_file</code> when using deferred client connect
+method</li>
+<li><code>OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY</code> plug-in hooks returns
+success/failure via <code>auth_control_file</code> when using deferred auth
+method</li>
+<li><code>OPENVPN_PLUGIN_ENABLE_PF</code> plugin hook to pass filtering rules
+via <tt class="docutils literal">pf_file</tt></li>
+</ul>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--use-prediction-resistance</span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Enable prediction resistance on mbed TLS's RNG.</p>
+<p>Enabling prediction resistance causes the RNG to reseed in each call for
+random. Reseeding this often can quickly deplete the kernel entropy
+pool.</p>
+<p class="last">If you need this option, please consider running a daemon that adds
+entropy to the kernel pool.</p>
+</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--user <var>user</var></span></kbd></td>
+<td><p class="first">Change the user ID of the OpenVPN process to <tt class="docutils literal">user</tt> after
+initialization, dropping privileges in the process. This option is
+useful to protect the system in the event that some hostile party was
+able to gain control of an OpenVPN session. Though OpenVPN's security
+features make this unlikely, it is provided as a second line of defense.</p>
+<p class="last">By setting <tt class="docutils literal">user</tt> to <code>nobody</code> or somebody similarly unprivileged,
+the hostile party would be limited in what damage they could cause. Of
+course once you take away privileges, you cannot return them to an
+OpenVPN session. This means, for example, that if you want to reset an
+OpenVPN daemon with a <code>SIGUSR1</code> signal (for example in response to
+a DHCP reset), you should make use of one or more of the <tt class="docutils literal"><span class="pre">--persist</span></tt>
+options to ensure that OpenVPN doesn't need to execute any privileged
+operations in order to restart (such as re-reading key files or running
+<tt class="docutils literal">ifconfig</tt> on the TUN device).</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--writepid <var>file</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td>Write OpenVPN's main process ID to <tt class="docutils literal">file</tt>.</td></tr>
+</tbody>
+</table>
+</div>
+<div class="section" id="log-options">
+<h2>Log options</h2>
+<table class="docutils option-list" frame="void" rules="none">
+<col class="option" />
+<col class="description" />
+<tbody valign="top">
+<tr><td class="option-group">
+<kbd><span class="option">--echo <var>parms</var></span></kbd></td>
+<td><p class="first">Echo <tt class="docutils literal">parms</tt> to log output.</p>
+<p class="last">Designed to be used to send messages to a controlling application which
+is receiving the OpenVPN log output.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--errors-to-stderr</span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td>Output errors to stderr instead of stdout unless log output is
+redirected by one of the <tt class="docutils literal"><span class="pre">--log</span></tt> options.</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--log <var>file</var></span></kbd></td>
+<td><p class="first">Output logging messages to <tt class="docutils literal">file</tt>, including output to stdout/stderr
+which is generated by called scripts. If <tt class="docutils literal">file</tt> already exists it will
+be truncated. This option takes effect immediately when it is parsed in
+the command line and will supersede syslog output if <tt class="docutils literal"><span class="pre">--daemon</span></tt> or
+<tt class="docutils literal"><span class="pre">--inetd</span></tt> is also specified. This option is persistent over the entire
+course of an OpenVPN instantiation and will not be reset by
+<code>SIGHUP</code>, <code>SIGUSR1</code>, or <tt class="docutils literal"><span class="pre">--ping-restart</span></tt>.</p>
+<p class="last">Note that on Windows, when OpenVPN is started as a service, logging
+occurs by default without the need to specify this option.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--log-append <var>file</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td>Append logging messages to <tt class="docutils literal">file</tt>. If <tt class="docutils literal">file</tt> does not exist, it will
+be created. This option behaves exactly like <tt class="docutils literal"><span class="pre">--log</span></tt> except that it
+appends to rather than truncating the log file.</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--machine-readable-output</span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td>Always write timestamps and message flags to log messages, even when
+they otherwise would not be prefixed. In particular, this applies to log
+messages sent to stdout.</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--mute <var>n</var></span></kbd></td>
+<td>Log at most <tt class="docutils literal">n</tt> consecutive messages in the same category. This is
+useful to limit repetitive logging of similar message types.</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--mute-replay-warnings</span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td>Silence the output of replay warnings, which are a common false alarm on
+WiFi networks. This option preserves the security of the replay
+protection code without the verbosity associated with warnings about
+duplicate packets.</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--suppress-timestamps</span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td>Avoid writing timestamps to log messages, even when they otherwise would
+be prepended. In particular, this applies to log messages sent to
+stdout.</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--syslog <var>progname</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td>Direct log output to system logger, but do not become a daemon. See
+<tt class="docutils literal"><span class="pre">--daemon</span></tt> directive above for description of <tt class="docutils literal">progname</tt> parameter.</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--verb <var>n</var></span></kbd></td>
+<td><p class="first">Set output verbosity to <tt class="docutils literal">n</tt> (default <code>1</code>). Each level shows all
+info from the previous levels. Level <code>3</code> is recommended if you want
+a good summary of what's happening without being swamped by output.</p>
+<dl class="last docutils">
+<dt><code>0</code></dt>
+<dd>No output except fatal errors.</dd>
+<dt><code>1</code> to <code>4</code></dt>
+<dd>Normal usage range.</dd>
+<dt><code>5</code></dt>
+<dd>Outputs <code>R</code> and <code>W</code> characters to the console for
+each packet read and write, uppercase is used for TCP/UDP
+packets and lowercase is used for TUN/TAP packets.</dd>
+<dt><code>6</code> to <code>11</code></dt>
+<dd>Debug info range (see <code>errlevel.h</code> in the source code for
+additional information on debug levels).</dd>
+</dl>
+</td></tr>
+</tbody>
+</table>
+</div>
+<div class="section" id="protocol-options">
+<h2>Protocol options</h2>
+<p>Options in this section affect features available in the OpenVPN wire
+protocol. Many of these options also define the encryption options
+of the data channel in the OpenVPN wire protocol. These options must be
+configured in a compatible way between both the local and remote side.</p>
+<table class="docutils option-list" frame="void" rules="none">
+<col class="option" />
+<col class="description" />
+<tbody valign="top">
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--allow-compression <var>mode</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">As described in the <tt class="docutils literal"><span class="pre">--compress</span></tt> option, compression is a potentially
+dangerous option. This option allows controlling the behaviour of
+OpenVPN when compression is used and allowed.</p>
+<p>Valid syntaxes:</p>
+<pre class="literal-block">
+allow-compression
+allow-compression mode
+</pre>
+<p>The <tt class="docutils literal">mode</tt> argument can be one of the following values:</p>
+<dl class="last docutils">
+<dt><code>asym</code> (default)</dt>
+<dd>OpenVPN will only <em>decompress downlink packets</em> but <em>not compress
+uplink packets</em>. This also allows migrating to disable compression
+when changing both server and client configurations to remove
+compression at the same time is not a feasible option.</dd>
+<dt><code>no</code></dt>
+<dd>OpenVPN will refuse any non-stub compression.</dd>
+<dt><code>yes</code></dt>
+<dd>OpenVPN will send and receive compressed packets.</dd>
+</dl>
+</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--auth <var>alg</var></span></kbd></td>
+<td><p class="first">Authenticate data channel packets and (if enabled) <tt class="docutils literal"><span class="pre">tls-auth</span></tt> control
+channel packets with HMAC using message digest algorithm <tt class="docutils literal">alg</tt>. (The
+default is <tt class="docutils literal">SHA1</tt> ). HMAC is a commonly used message authentication
+algorithm (MAC) that uses a data string, a secure hash algorithm and a
+key to produce a digital signature.</p>
+<p>The OpenVPN data channel protocol uses encrypt-then-mac (i.e. first
+encrypt a packet then HMAC the resulting ciphertext), which prevents
+padding oracle attacks.</p>
+<p>If an AEAD cipher mode (e.g. GCM) is chosen then the specified <tt class="docutils literal"><span class="pre">--auth</span></tt>
+algorithm is ignored for the data channel and the authentication method
+of the AEAD cipher is used instead. Note that <tt class="docutils literal">alg</tt> still specifies
+the digest used for <tt class="docutils literal"><span class="pre">tls-auth</span></tt>.</p>
+<p>In static-key encryption mode, the HMAC key is included in the key file
+generated by <tt class="docutils literal"><span class="pre">--genkey</span></tt>. In TLS mode, the HMAC key is dynamically
+generated and shared between peers via the TLS control channel. If
+OpenVPN receives a packet with a bad HMAC it will drop the packet. HMAC
+usually adds 16 or 20 bytes per packet. Set <tt class="docutils literal">alg=none</tt> to disable
+authentication.</p>
+<p class="last">For more information on HMAC see
+<a class="reference external" href="http://www.cs.ucsd.edu/users/mihir/papers/hmac.html">http://www.cs.ucsd.edu/users/mihir/papers/hmac.html</a></p>
+</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--cipher <var>alg</var></span></kbd></td>
+<td><p class="first">This option is deprecated for server-client mode. <tt class="docutils literal"><span class="pre">--data-ciphers</span></tt>
+or possibly <cite>--data-ciphers-fallback`</cite> should be used instead.</p>
+<p>Encrypt data channel packets with cipher algorithm <tt class="docutils literal">alg</tt>.</p>
+<p>The default is <code>BF-CBC</code>, an abbreviation for Blowfish in Cipher
+Block Chaining mode. When cipher negotiation (NCP) is allowed,
+OpenVPN 2.4 and newer on both client and server side will automatically
+upgrade to <code>AES-256-GCM</code>. See <tt class="docutils literal"><span class="pre">--data-ciphers</span></tt> and
+<tt class="docutils literal"><span class="pre">--ncp-disable</span></tt> for more details on NCP.</p>
+<p>Using <code>BF-CBC</code> is no longer recommended, because of its 64-bit
+block size. This small block size allows attacks based on collisions, as
+demonstrated by SWEET32. See
+<a class="reference external" href="https://community.openvpn.net/openvpn/wiki/SWEET32">https://community.openvpn.net/openvpn/wiki/SWEET32</a>
+for details. Due to this, support for <code>BF-CBC</code>, <code>DES</code>,
+<code>CAST5</code>, <code>IDEA</code> and <code>RC2</code> ciphers will be removed in
+OpenVPN 2.6.</p>
+<p>To see other ciphers that are available with OpenVPN, use the
+<tt class="docutils literal"><span class="pre">--show-ciphers</span></tt> option.</p>
+<p class="last">Set <tt class="docutils literal">alg</tt> to <code>none</code> to disable encryption.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--compress <var>algorithm</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first"><strong>DEPRECATED</strong> Enable a compression algorithm. Compression is generally
+not recommended. VPN tunnels which use compression are susceptible to
+the VORALCE attack vector.</p>
+<p>The <tt class="docutils literal">algorithm</tt> parameter may be <code>lzo</code>, <code>lz4</code>,
+<code>lz4-v2</code>, <code>stub</code>, <code>stub-v2</code> or empty.
+LZO and LZ4 are different compression algorithms, with LZ4 generally
+offering the best performance with least CPU usage.</p>
+<p>The <code>lz4-v2</code> and <code>stub-v2</code> variants implement a better
+framing that does not add overhead when packets cannot be compressed. All
+other variants always add one extra framing byte compared to no
+compression framing.</p>
+<p>If the <tt class="docutils literal">algorithm</tt> parameter is <code>stub</code>, <code>stub-v2</code> or empty,
+compression will be turned off, but the packet framing for compression
+will still be enabled, allowing a different setting to be pushed later.
+Additionally, <code>stub</code> and <code>stub-v2</code> wil disable announcing
+<tt class="docutils literal">lzo</tt> and <tt class="docutils literal">lz4</tt> compression support via <em>IV_</em> variables to the
+server.</p>
+<p>Note: the <code>stub</code> (or empty) option is NOT compatible with the older
+option <tt class="docutils literal"><span class="pre">--comp-lzo</span> no</tt>.</p>
+<p><strong>*Security Considerations*</strong></p>
+<p class="last">Compression and encryption is a tricky combination. If an attacker knows
+or is able to control (parts of) the plain-text of packets that contain
+secrets, the attacker might be able to extract the secret if compression
+is enabled. See e.g. the <em>CRIME</em> and <em>BREACH</em> attacks on TLS and
+<em>VORACLE</em> on VPNs which also leverage to break encryption. If you are not
+entirely sure that the above does not apply to your traffic, you are
+advised to <em>not</em> enable compression.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--comp-lzo <var>mode</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first"><strong>DEPRECATED</strong> Enable LZO compression algorithm. Compression is
+generally not recommended. VPN tunnels which uses compression are
+suspectible to the VORALCE attack vector.</p>
+<p>Use LZO compression -- may add up to 1 byte per packet for incompressible
+data. <tt class="docutils literal">mode</tt> may be <code>yes</code>, <code>no</code>, or <code>adaptive</code>
+(default).</p>
+<p>In a server mode setup, it is possible to selectively turn compression
+on or off for individual clients.</p>
+<p>First, make sure the client-side config file enables selective
+compression by having at least one <tt class="docutils literal"><span class="pre">--comp-lzo</span></tt> directive, such as
+<tt class="docutils literal"><span class="pre">--comp-lzo</span> no</tt>. This will turn off compression by default, but allow
+a future directive push from the server to dynamically change the
+<code>on</code>/<code>off</code>/<code>adaptive</code> setting.</p>
+<p>Next in a <tt class="docutils literal"><span class="pre">--client-config-dir</span></tt> file, specify the compression setting
+for the client, for example:</p>
+<pre class="literal-block">
+comp-lzo yes
+push &quot;comp-lzo yes&quot;
+</pre>
+<p class="last">The first line sets the <tt class="docutils literal"><span class="pre">comp-lzo</span></tt> setting for the server side of the
+link, the second sets the client side.</p>
+</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--comp-noadapt</span></kbd></td>
+<td><p class="first"><strong>DEPRECATED</strong> When used in conjunction with <tt class="docutils literal"><span class="pre">--comp-lzo</span></tt>, this option
+will disable OpenVPN's adaptive compression algorithm. Normally, adaptive
+compression is enabled with <tt class="docutils literal"><span class="pre">--comp-lzo</span></tt>.</p>
+<p class="last">Adaptive compression tries to optimize the case where you have
+compression enabled, but you are sending predominantly incompressible
+(or pre-compressed) packets over the tunnel, such as an FTP or rsync
+transfer of a large, compressed file. With adaptive compression, OpenVPN
+will periodically sample the compression process to measure its
+efficiency. If the data being sent over the tunnel is already
+compressed, the compression efficiency will be very low, triggering
+openvpn to disable compression for a period of time until the next
+re-sample test.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--key-direction</span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td>Alternative way of specifying the optional direction parameter for the
+<tt class="docutils literal"><span class="pre">--tls-auth</span></tt> and <tt class="docutils literal"><span class="pre">--secret</span></tt> options. Useful when using inline files
+(See section on inline files).</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--keysize <var>n</var></span></kbd></td>
+<td><p class="first"><strong>DEPRECATED</strong> This option will be removed in OpenVPN 2.6.</p>
+<p class="last">Size of cipher key in bits (optional). If unspecified, defaults to
+cipher-specific default. The <tt class="docutils literal"><span class="pre">--show-ciphers</span></tt> option (see below) shows
+all available OpenSSL ciphers, their default key sizes, and whether the
+key size can be changed. Use care in changing a cipher's default key
+size. Many ciphers have not been extensively cryptanalyzed with
+non-standard key lengths, and a larger key may offer no real guarantee
+of greater security, or may even reduce security.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--data-ciphers <var>cipher-list</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Restrict the allowed ciphers to be negotiated to the ciphers in
+<tt class="docutils literal"><span class="pre">cipher-list</span></tt>. <tt class="docutils literal"><span class="pre">cipher-list</span></tt> is a colon-separated list of ciphers,
+and defaults to <code>AES-256-GCM:AES-128-GCM</code>.</p>
+<p>For servers, the first cipher from <tt class="docutils literal"><span class="pre">cipher-list</span></tt> that is also
+supported by the client will be pushed to clients that support cipher
+negotiation.</p>
+<p>Cipher negotiation is enabled in client-server mode only. I.e. if
+<tt class="docutils literal"><span class="pre">--mode</span></tt> is set to 'server' (server-side, implied by setting
+<tt class="docutils literal"><span class="pre">--server</span></tt> ), or if <tt class="docutils literal"><span class="pre">--pull</span></tt> is specified (client-side, implied by
+setting --client).</p>
+<p>If no common cipher is found during cipher negotiation, the connection
+is terminated. To support old clients/old servers that do not provide any
+cipher negotiation support see <tt class="docutils literal"><span class="pre">--data-ciphers-fallback</span></tt>.</p>
+<p>Additionally, to allow for more smooth transition, if NCP is enabled,
+OpenVPN will inherit the cipher of the peer if that cipher is different
+from the local <tt class="docutils literal"><span class="pre">--cipher</span></tt> setting, but the peer cipher is one of the
+ciphers specified in <tt class="docutils literal"><span class="pre">--data-ciphers</span></tt>. E.g. a non-NCP client (&lt;=v2.3,
+or with --ncp-disabled set) connecting to a NCP server (v2.4+) with
+<tt class="docutils literal"><span class="pre">--cipher</span> <span class="pre">BF-CBC</span></tt> and <tt class="docutils literal"><span class="pre">--data-ciphers</span> <span class="pre">AES-256-GCM:AES-256-CBC</span></tt> set can
+either specify <tt class="docutils literal"><span class="pre">--cipher</span> <span class="pre">BF-CBC</span></tt> or <tt class="docutils literal"><span class="pre">--cipher</span> <span class="pre">AES-256-CBC</span></tt> and both
+will work.</p>
+<p>Note for using NCP with an OpenVPN 2.4 peer: This list must include the
+<code>AES-256-GCM</code> and <code>AES-128-GCM</code> ciphers.</p>
+<p>This list is restricted to be 127 chars long after conversion to OpenVPN
+ciphers.</p>
+<p class="last">This option was called <tt class="docutils literal"><span class="pre">--ncp-ciphers</span></tt> in OpenVPN 2.4 but has been renamed
+to <tt class="docutils literal"><span class="pre">--data-ciphers</span></tt> in OpenVPN 2.5 to more accurately reflect its meaning.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--data-ciphers-fallback <var>alg</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Configure a cipher that is used to fall back to if we could not determine
+which cipher the peer is willing to use.</p>
+<p class="last">This option should only be needed to
+connect to peers that are running OpenVPN 2.3 and older version, and
+have been configured with <cite>--enable-small</cite>
+(typically used on routers or other embedded devices).</p>
+</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--ncp-disable</span></kbd></td>
+<td><strong>DEPRECATED</strong> Disable &quot;Negotiable Crypto Parameters&quot;. This completely
+disables cipher negotiation.</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--secret <var>args</var></span></kbd></td>
+<td><p class="first">Enable Static Key encryption mode (non-TLS). Use pre-shared secret
+<tt class="docutils literal">file</tt> which was generated with <tt class="docutils literal"><span class="pre">--genkey</span></tt>.</p>
+<p>Valid syntaxes:</p>
+<pre class="literal-block">
+secret file
+secret file direction
+</pre>
+<p>The optional <tt class="docutils literal">direction</tt> parameter enables the use of 4 distinct keys
+(HMAC-send, cipher-encrypt, HMAC-receive, cipher-decrypt), so that each
+data flow direction has a different set of HMAC and cipher keys. This
+has a number of desirable security properties including eliminating
+certain kinds of DoS and message replay attacks.</p>
+<p>When the <tt class="docutils literal">direction</tt> parameter is omitted, 2 keys are used
+bidirectionally, one for HMAC and the other for encryption/decryption.</p>
+<p>The <tt class="docutils literal">direction</tt> parameter should always be complementary on either
+side of the connection, i.e. one side should use <code>0</code> and the other
+should use <code>1</code>, or both sides should omit it altogether.</p>
+<p>The <tt class="docutils literal">direction</tt> parameter requires that <tt class="docutils literal">file</tt> contains a 2048 bit
+key. While pre-1.5 versions of OpenVPN generate 1024 bit key files, any
+version of OpenVPN which supports the <tt class="docutils literal">direction</tt> parameter, will also
+support 2048 bit key file generation using the <tt class="docutils literal"><span class="pre">--genkey</span></tt> option.</p>
+<p>Static key encryption mode has certain advantages, the primary being
+ease of configuration.</p>
+<p>There are no certificates or certificate authorities or complicated
+negotiation handshakes and protocols. The only requirement is that you
+have a pre-existing secure channel with your peer (such as <tt class="docutils literal">ssh</tt>) to
+initially copy the key. This requirement, along with the fact that your
+key never changes unless you manually generate a new one, makes it
+somewhat less secure than TLS mode (see below). If an attacker manages
+to steal your key, everything that was ever encrypted with it is
+compromised. Contrast that to the perfect forward secrecy features of
+TLS mode (using Diffie Hellman key exchange), where even if an attacker
+was able to steal your private key, he would gain no information to help
+him decrypt past sessions.</p>
+<p class="last">Another advantageous aspect of Static Key encryption mode is that it is
+a handshake-free protocol without any distinguishing signature or
+feature (such as a header or protocol handshake sequence) that would
+mark the ciphertext packets as being generated by OpenVPN. Anyone
+eavesdropping on the wire would see nothing but random-looking data.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--tran-window <var>n</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td>Transition window -- our old key can live this many seconds after a new
+a key renegotiation begins (default <code>3600</code> seconds). This feature
+allows for a graceful transition from old to new key, and removes the key
+renegotiation sequence from the critical path of tunnel data forwarding.</td></tr>
+</tbody>
+</table>
+</div>
+<div class="section" id="client-options">
+<h2>Client Options</h2>
+<p>The client options are used when connecting to an OpenVPN server configured
+to use <tt class="docutils literal"><span class="pre">--server</span></tt>, <tt class="docutils literal"><span class="pre">--server-bridge</span></tt>, or <tt class="docutils literal"><span class="pre">--mode</span> server</tt> in its
+configuration.</p>
+<table class="docutils option-list" frame="void" rules="none">
+<col class="option" />
+<col class="description" />
+<tbody valign="top">
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--allow-pull-fqdn</span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td>Allow client to pull DNS names from server (rather than being limited to
+IP address) for <tt class="docutils literal"><span class="pre">--ifconfig</span></tt>, <tt class="docutils literal"><span class="pre">--route</span></tt>, and <tt class="docutils literal"><span class="pre">--route-gateway</span></tt>.</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--allow-recursive-routing</span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td>When this option is set, OpenVPN will not drop incoming tun packets with
+same destination as host.</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--auth-token <var>token</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">This is not an option to be used directly in any configuration files,
+but rather push this option from a <tt class="docutils literal"><span class="pre">--client-connect</span></tt> script or a
+<tt class="docutils literal"><span class="pre">--plugin</span></tt> which hooks into the <code>OPENVPN_PLUGIN_CLIENT_CONNECT</code>
+or <code>OPENVPN_PLUGIN_CLIENT_CONNECT_V2</code> calls. This option provides a
+possibility to replace the clients password with an authentication token
+during the lifetime of the OpenVPN client.</p>
+<p>Whenever the connection is renegotiated and the
+<tt class="docutils literal"><span class="pre">--auth-user-pass-verify</span></tt> script or <tt class="docutils literal"><span class="pre">--plugin</span></tt> making use of the
+<code>OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY</code> hook is triggered, it will
+pass over this token as the password instead of the password the user
+provided. The authentication token can only be reset by a full reconnect
+where the server can push new options to the client. The password the
+user entered is never preserved once an authentication token has been
+set. If the OpenVPN server side rejects the authentication token then
+the client will receive an <code>AUTH_FAILED</code> and disconnect.</p>
+<p>The purpose of this is to enable two factor authentication methods, such
+as HOTP or TOTP, to be used without needing to retrieve a new OTP code
+each time the connection is renegotiated. Another use case is to cache
+authentication data on the client without needing to have the users
+password cached in memory during the life time of the session.</p>
+<p>To make use of this feature, the <tt class="docutils literal"><span class="pre">--client-connect</span></tt> script or
+<tt class="docutils literal"><span class="pre">--plugin</span></tt> needs to put</p>
+<pre class="literal-block">
+push &quot;auth-token UNIQUE_TOKEN_VALUE&quot;
+</pre>
+<p>into the file/buffer for dynamic configuration data. This will then make
+the OpenVPN server to push this value to the client, which replaces the
+local password with the <tt class="docutils literal">UNIQUE_TOKEN_VALUE</tt>.</p>
+<p class="last">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 <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-user-pass</span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Authenticate with server using username/password.</p>
+<p>Valid syntaxes:</p>
+<pre class="literal-block">
+auth-user-pass
+auth-user-pass up
+</pre>
+<p>If <tt class="docutils literal">up</tt> is present, it must be a file containing username/password on 2
+lines. If the password line is missing, OpenVPN will prompt for one.</p>
+<p>If <tt class="docutils literal">up</tt> is omitted, username/password will be prompted from the
+console.</p>
+<p class="last">The server configuration must specify an <tt class="docutils literal"><span class="pre">--auth-user-pass-verify</span></tt>
+script to verify the username/password provided by the client.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--auth-retry <var>type</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Controls how OpenVPN responds to username/password verification errors
+such as the client-side response to an <code>AUTH_FAILED</code> message from
+the server or verification failure of the private key password.</p>
+<p>Normally used to prevent auth errors from being fatal on the client
+side, and to permit username/password requeries in case of error.</p>
+<p>An <code>AUTH_FAILED</code> message is generated by the server if the client
+fails <tt class="docutils literal"><span class="pre">--auth-user-pass</span></tt> authentication, or if the server-side
+<tt class="docutils literal"><span class="pre">--client-connect</span></tt> script returns an error status when the client
+tries to connect.</p>
+<p><tt class="docutils literal">type</tt> can be one of:</p>
+<dl class="docutils">
+<dt><code>none</code></dt>
+<dd>Client will exit with a fatal error (this is the default).</dd>
+<dt><code>nointeract</code></dt>
+<dd>Client will retry the connection without requerying
+for an <tt class="docutils literal"><span class="pre">--auth-user-pass</span></tt> username/password. Use this option for
+unattended clients.</dd>
+<dt><code>interact</code></dt>
+<dd>Client will requery for an <tt class="docutils literal"><span class="pre">--auth-user-pass</span></tt>
+username/password and/or private key password before attempting a
+reconnection.</dd>
+</dl>
+<p class="last">Note that while this option cannot be pushed, it can be controlled from
+the management interface.</p>
+</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--client</span></kbd></td>
+<td><p class="first">A helper directive designed to simplify the configuration of OpenVPN's
+client mode. This directive is equivalent to:</p>
+<pre class="last literal-block">
+pull
+tls-client
+</pre>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--client-nat <var>args</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">This pushable client option sets up a stateless one-to-one NAT rule on
+packet addresses (not ports), and is useful in cases where routes or
+ifconfig settings pushed to the client would create an IP numbering
+conflict.</p>
+<p>Examples:</p>
+<pre class="literal-block">
+client-nat snat 192.168.0.0/255.255.0.0
+client-nat dnat 10.64.0.0/255.255.0.0
+</pre>
+<p><tt class="docutils literal">network/netmask</tt> (for example <code>192.168.0.0/255.255.0.0</code>) defines
+the local view of a resource from the client perspective, while
+<tt class="docutils literal">alias/netmask</tt> (for example <code>10.64.0.0/255.255.0.0</code>) defines the
+remote view from the server perspective.</p>
+<p>Use <code>snat</code> (source NAT) for resources owned by the client and
+<code>dnat</code> (destination NAT) for remote resources.</p>
+<p class="last">Set <tt class="docutils literal"><span class="pre">--verb</span> 6</tt> for debugging info showing the transformation of
+src/dest addresses in packets.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--connect-retry <var>n</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td>Wait <tt class="docutils literal">n</tt> seconds between connection attempts (default <code>5</code>).
+Repeated reconnection attempts are slowed down after 5 retries per
+remote by doubling the wait time after each unsuccessful attempt. An
+optional argument <tt class="docutils literal">max</tt> specifies the maximum value of wait time in
+seconds at which it gets capped (default <code>300</code>).</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--connect-retry-max <var>n</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><tt class="docutils literal">n</tt> specifies the number of times each <tt class="docutils literal"><span class="pre">--remote</span></tt> or
+<tt class="docutils literal">&lt;connection&gt;</tt> entry is tried. Specifying <tt class="docutils literal">n</tt> as <code>1</code> would try
+each entry exactly once. A successful connection resets the counter.
+(default <em>unlimited</em>).</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--connect-timeout <var>n</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td>See <tt class="docutils literal"><span class="pre">--server-poll-timeout</span></tt>.</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--explicit-exit-notify <var>n</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">In UDP client mode or point-to-point mode, send server/peer an exit
+notification if tunnel is restarted or OpenVPN process is exited. In
+client mode, on exit/restart, this option will tell the server to
+immediately close its client instance object rather than waiting for a
+timeout.</p>
+<p>The <strong>n</strong> parameter (default <code>1</code> if not present) controls the
+maximum number of attempts that the client will try to resend the exit
+notification message.</p>
+<p>In UDP server mode, send <code>RESTART</code> control channel command to
+connected clients. The <tt class="docutils literal">n</tt> parameter (default <code>1</code> if not present)
+controls client behavior. With <tt class="docutils literal">n</tt> = <code>1</code> client will attempt to
+reconnect to the same server, with <tt class="docutils literal">n</tt> = <code>2</code> client will advance
+to the next server.</p>
+<p class="last">OpenVPN will not send any exit notifications unless this option is
+enabled.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--inactive <var>args</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Causes OpenVPN to exit after <tt class="docutils literal">n</tt> seconds of inactivity on the TUN/TAP
+device. The time length of inactivity is measured since the last
+incoming or outgoing tunnel packet. The default value is 0 seconds,
+which disables this feature.</p>
+<p>Valid syntaxes:</p>
+<pre class="literal-block">
+inactive n
+inactive n bytes
+</pre>
+<p>If the optional <tt class="docutils literal">bytes</tt> parameter is included, exit if less than
+<tt class="docutils literal">bytes</tt> of combined in/out traffic are produced on the tun/tap device
+in <tt class="docutils literal">n</tt> seconds.</p>
+<p class="last">In any case, OpenVPN's internal ping packets (which are just keepalives)
+and TLS control packets are not considered &quot;activity&quot;, nor are they
+counted as traffic, as they are used internally by OpenVPN and are not
+an indication of actual user activity.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--proto-force <var>p</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td>When iterating through connection profiles, only consider profiles using
+protocol <tt class="docutils literal">p</tt> (<code>tcp</code> | <code>udp</code>).</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--pull</span></kbd></td>
+<td><p class="first">This option must be used on a client which is connecting to a
+multi-client server. It indicates to OpenVPN that it should accept
+options pushed by the server, provided they are part of the legal set of
+pushable options (note that the <tt class="docutils literal"><span class="pre">--pull</span></tt> option is implied by
+<tt class="docutils literal"><span class="pre">--client</span></tt> ).</p>
+<p class="last">In particular, <tt class="docutils literal"><span class="pre">--pull</span></tt> allows the server to push routes to the
+client, so you should not use <tt class="docutils literal"><span class="pre">--pull</span></tt> or <tt class="docutils literal"><span class="pre">--client</span></tt> in situations
+where you don't trust the server to have control over the client's
+routing table.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--pull-filter <var>args</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Filter options on the client pushed by the server to the client.</p>
+<p>Valid syntaxes:</p>
+<pre class="literal-block">
+pull-filter accept text
+pull-filter ignore text
+pull-filter reject text
+</pre>
+<p>Filter options received from the server if the option starts with
+<code>text</code>. The action flag <code>accept</code> allows the option,
+<code>ignore</code> removes it and <code>reject</code> flags an error and triggers
+a <code>SIGUSR1</code> restart. The filters may be specified multiple times,
+and each filter is applied in the order it is specified. The filtering of
+each option stops as soon as a match is found. Unmatched options are accepted
+by default.</p>
+<p>Prefix comparison is used to match <code>text</code> against the received option so
+that</p>
+<pre class="literal-block">
+pull-filter ignore &quot;route&quot;
+</pre>
+<p>would remove all pushed options starting with <tt class="docutils literal">route</tt> which would
+include, for example, <tt class="docutils literal"><span class="pre">route-gateway</span></tt>. Enclose <em>text</em> in quotes to
+embed spaces.</p>
+<pre class="literal-block">
+pull-filter accept &quot;route 192.168.1.&quot;
+pull-filter ignore &quot;route &quot;
+</pre>
+<p>would remove all routes that do not start with <tt class="docutils literal">192.168.1</tt>.</p>
+<p class="last"><em>Note</em> that <code>reject</code> may result in a repeated cycle of failure and
+reconnect, unless multiple remotes are specified and connection to the
+next remote succeeds. To silently ignore an option pushed by the server,
+use <code>ignore</code>.</p>
+</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--remote <var>args</var></span></kbd></td>
+<td><p class="first">Remote host name or IP address. It supports two additional optional
+arguments: <tt class="docutils literal">port</tt> and <tt class="docutils literal">proto</tt>. On the client, multiple <tt class="docutils literal"><span class="pre">--remote</span></tt>
+options may be specified for redundancy, each referring to a different
+OpenVPN server. Specifying multiple <tt class="docutils literal"><span class="pre">--remote</span></tt> options for this
+purpose is a special case of the more general connection-profile
+feature. See the <tt class="docutils literal">&lt;connection&gt;</tt> documentation below.</p>
+<p>The OpenVPN client will try to connect to a server at <tt class="docutils literal">host:port</tt> in
+the order specified by the list of <tt class="docutils literal"><span class="pre">--remote</span></tt> options.</p>
+<p>Examples:</p>
+<pre class="literal-block">
+remote server.example.net
+remote server.example.net 1194
+remote server.example.net tcp
+</pre>
+<p><tt class="docutils literal">proto</tt> indicates the protocol to use when connecting with the remote,
+and may be <code>tcp</code> or <code>udp</code>.</p>
+<p>For forcing IPv4 or IPv6 connection suffix tcp or udp with 4/6 like
+udp4/udp6/tcp4/tcp6.</p>
+<p>The client will move on to the next host in the list, in the event of
+connection failure. Note that at any given time, the OpenVPN client will
+at most be connected to one server.</p>
+<p>Note that since UDP is connectionless, connection failure is defined by
+the <tt class="docutils literal"><span class="pre">--ping</span></tt> and <tt class="docutils literal"><span class="pre">--ping-restart</span></tt> options.</p>
+<p>Note the following corner case: If you use multiple <tt class="docutils literal"><span class="pre">--remote</span></tt>
+options, AND you are dropping root privileges on the client with
+<tt class="docutils literal"><span class="pre">--user</span></tt> and/or <tt class="docutils literal"><span class="pre">--group</span></tt> AND the client is running a non-Windows
+OS, if the client needs to switch to a different server, and that server
+pushes back different TUN/TAP or route settings, the client may lack the
+necessary privileges to close and reopen the TUN/TAP interface. This
+could cause the client to exit with a fatal error.</p>
+<p>If <tt class="docutils literal"><span class="pre">--remote</span></tt> is unspecified, OpenVPN will listen for packets from any
+IP address, but will not act on those packets unless they pass all
+authentication tests. This requirement for authentication is binding on
+all potential peers, even those from known and supposedly trusted IP
+addresses (it is very easy to forge a source IP address on a UDP
+packet).</p>
+<p>When used in TCP mode, <tt class="docutils literal"><span class="pre">--remote</span></tt> will act as a filter, rejecting
+connections from any host which does not match <tt class="docutils literal">host</tt>.</p>
+<p class="last">If <tt class="docutils literal">host</tt> is a DNS name which resolves to multiple IP addresses,
+OpenVPN will try them in the order that the system getaddrinfo()
+presents them, so priorization and DNS randomization is done by the
+system library. Unless an IP version is forced by the protocol
+specification (4/6 suffix), OpenVPN will try both IPv4 and IPv6
+addresses, in the order getaddrinfo() returns them.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--remote-random</span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td>When multiple <tt class="docutils literal"><span class="pre">--remote</span></tt> address/ports are specified, or if connection
+profiles are being used, initially randomize the order of the list as a
+kind of basic load-balancing measure.</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--remote-random-hostname</span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td>Prepend a random string (6 bytes, 12 hex characters) to hostname to
+prevent DNS caching. For example, &quot;foo.bar.gov&quot; would be modified to
+&quot;&lt;random-chars&gt;.foo.bar.gov&quot;.</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--resolv-retry <var>n</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">If hostname resolve fails for <tt class="docutils literal"><span class="pre">--remote</span></tt>, retry resolve for <tt class="docutils literal">n</tt>
+seconds before failing.</p>
+<p>Set <tt class="docutils literal">n</tt> to &quot;infinite&quot; to retry indefinitely.</p>
+<p class="last">By default, <tt class="docutils literal"><span class="pre">--resolv-retry</span> infinite</tt> is enabled. You can disable by
+setting n=0.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--single-session</span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">After initially connecting to a remote peer, disallow any new
+connections. Using this option means that a remote peer cannot connect,
+disconnect, and then reconnect.</p>
+<p>If the daemon is reset by a signal or <tt class="docutils literal"><span class="pre">--ping-restart</span></tt>, it will allow
+one new connection.</p>
+<p class="last"><tt class="docutils literal"><span class="pre">--single-session</span></tt> can be used with <tt class="docutils literal"><span class="pre">--ping-exit</span></tt> or <tt class="docutils literal"><span class="pre">--inactive</span></tt>
+to create a single dynamic session that will exit when finished.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--server-poll-timeout <var>n</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td>When connecting to a remote server do not wait for more than <tt class="docutils literal">n</tt>
+seconds for a response before trying the next server. The default value
+is 120s. This timeout includes proxy and TCP connect timeouts.</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--static-challenge <var>args</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Enable static challenge/response protocol</p>
+<p>Valid syntax:</p>
+<pre class="literal-block">
+static-challenge text echo
+</pre>
+<p>The <tt class="docutils literal">text</tt> challenge text is presented to the user which describes what
+information is requested. The <tt class="docutils literal">echo</tt> flag indicates if the user's
+input should be echoed on the screen. Valid <tt class="docutils literal">echo</tt> values are
+<code>0</code> or <code>1</code>.</p>
+<p class="last">See management-notes.txt in the OpenVPN distribution for a description of
+the OpenVPN challenge/response protocol.</p>
+</td></tr>
+</tbody>
+</table>
+<table class="docutils option-list" frame="void" rules="none">
+<col class="option" />
+<col class="description" />
+<tbody valign="top">
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--show-proxy-settings</span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td>Show sensed HTTP or SOCKS proxy settings. Currently, only Windows
+clients support this option.</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--http-proxy <var>args</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Connect to remote host through an HTTP proxy. This requires at least an
+address <tt class="docutils literal">server</tt> and <tt class="docutils literal">port</tt> argument. If HTTP Proxy-Authenticate
+is required, a file name to an <tt class="docutils literal">authfile</tt> file containing a username
+and password on 2 lines can be given, or <code>stdin</code> to prompt from
+console. Its content can also be specified in the config file with the
+<tt class="docutils literal"><span class="pre">--http-proxy-user-pass</span></tt> option. (See section on inline files)</p>
+<p>The last optional argument is an <tt class="docutils literal"><span class="pre">auth-method</span></tt> which should be one
+of <code>none</code>, <code>basic</code>, or <code>ntlm</code>.</p>
+<p>HTTP Digest authentication is supported as well, but only via the
+<code>auto</code> or <code>auto-nct</code> flags (below). This must replace
+the <tt class="docutils literal">authfile</tt> argument.</p>
+<p>The <code>auto</code> flag causes OpenVPN to automatically determine the
+<tt class="docutils literal"><span class="pre">auth-method</span></tt> and query stdin or the management interface for
+username/password credentials, if required. This flag exists on OpenVPN
+2.1 or higher.</p>
+<p>The <tt class="docutils literal"><span class="pre">auto-nct</span></tt> flag (no clear-text auth) instructs OpenVPN to
+automatically determine the authentication method, but to reject weak
+authentication protocols such as HTTP Basic Authentication.</p>
+<p>Examples:</p>
+<pre class="last literal-block">
+http-proxy proxy.example.net 3128
+http-proxy proxy.example.net 3128 authfile.txt
+http-proxy proxy.example.net 3128 stdin
+http-proxy proxy.example.net 3128 auto basic
+http-proxy proxy.example.net 3128 auto-nct ntlm
+</pre>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--http-proxy-option <var>args</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Set extended HTTP proxy options. Requires an option <tt class="docutils literal">type</tt> as argument
+and an optional <tt class="docutils literal">parameter</tt> to the type. Repeat to set multiple
+options.</p>
+<dl class="docutils">
+<dt><code>VERSION</code> <tt class="docutils literal">version</tt></dt>
+<dd>Set HTTP version number to <tt class="docutils literal">version</tt> (default <code>1.0</code>).</dd>
+<dt><code>AGENT</code> <tt class="docutils literal"><span class="pre">user-agent</span></tt></dt>
+<dd>Set HTTP &quot;User-Agent&quot; string to <tt class="docutils literal"><span class="pre">user-agent</span></tt>.</dd>
+<dt><code>CUSTOM-HEADER</code> <tt class="docutils literal">name</tt> <tt class="docutils literal">content</tt></dt>
+<dd>Adds the custom Header with <tt class="docutils literal">name</tt> as name and <tt class="docutils literal">content</tt> as
+the content of the custom HTTP header.</dd>
+</dl>
+<p>Examples:</p>
+<pre class="last literal-block">
+http-proxy-option VERSION 1.1
+http-proxy-option AGENT OpenVPN/2.4
+http-proxy-option X-Proxy-Flag some-flags
+</pre>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--socks-proxy <var>args</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td>Connect to remote host through a Socks5 proxy. A required <tt class="docutils literal">server</tt>
+argument is needed. Optionally a <tt class="docutils literal">port</tt> (default <code>1080</code>) and
+<tt class="docutils literal">authfile</tt> can be given. The <tt class="docutils literal">authfile</tt> is a file containing a
+username and password on 2 lines, or <code>stdin</code> can be used to
+prompt from console.</td></tr>
+</tbody>
+</table>
+</div>
+<div class="section" id="server-options">
+<h2>Server Options</h2>
+<p>Starting with OpenVPN 2.0, a multi-client TCP/UDP server mode is
+supported, and can be enabled with the <tt class="docutils literal"><span class="pre">--mode</span> server</tt> option. In
+server mode, OpenVPN will listen on a single port for incoming client
+connections. All client connections will be routed through a single tun
+or tap interface. This mode is designed for scalability and should be
+able to support hundreds or even thousands of clients on sufficiently
+fast hardware. SSL/TLS authentication must be used in this mode.</p>
+<table class="docutils option-list" frame="void" rules="none">
+<col class="option" />
+<col class="description" />
+<tbody valign="top">
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--auth-gen-token <var>args</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Returns an authentication token to successfully authenticated clients.</p>
+<p>Valid syntax:</p>
+<pre class="literal-block">
+auth-gen-token [lifetime] [external-auth]
+</pre>
+<p>After successful user/password authentication, the OpenVPN server will
+with this option generate a temporary authentication token and push that
+to the client. On the following renegotiations, the OpenVPN client will pass
+this token instead of the users password. On the server side the server
+will do the token authentication internally and it will NOT do any
+additional authentications against configured external user/password
+authentication mechanisms.</p>
+<p>The tokens implemented by this mechanism include an initial timestamp and
+a renew timestamp and are secured by HMAC.</p>
+<p>The <tt class="docutils literal">lifetime</tt> argument defines how long the generated token is valid.
+The lifetime is defined in seconds. If lifetime is not set or it is set
+to <code>0</code>, the token will never expire.</p>
+<p>The token will expire either after the configured <tt class="docutils literal">lifetime</tt> of the
+token is reached or after not being renewed for more than 2 *
+<tt class="docutils literal"><span class="pre">reneg-sec</span></tt> seconds. Clients will be sent renewed tokens on every TLS
+renogiation to keep the client's token updated. This is done to
+invalidate a token if a client is disconnected for a sufficently long
+time, while at the same time permitting much longer token lifetimes for
+active clients.</p>
+<p>This feature is useful for environments which are configured to use One
+Time Passwords (OTP) as part of the user/password authentications and
+that authentication mechanism does not implement any auth-token support.</p>
+<p>When the <code>external-auth</code> keyword is present the normal
+authentication method will always be called even if auth-token succeeds.
+Normally other authentications method are skipped if auth-token
+verification suceeds or fails.</p>
+<p>This option postpones this decision to the external authentication
+methods and checks the validity of the account and do other checks.</p>
+<p>In this mode the environment will have a <tt class="docutils literal">session_id</tt> variable that
+holds the session id from auth-gen-token. Also an environment variable
+<tt class="docutils literal">session_state</tt> is present. This variable indicates whether the
+auth-token has succeeded or not. It can have the following values:</p>
+<dl class="docutils">
+<dt><code>Initial</code></dt>
+<dd>No token from client.</dd>
+<dt><code>Authenticated</code></dt>
+<dd>Token is valid and not expired.</dd>
+<dt><code>Expired</code></dt>
+<dd>Token is valid but has expired.</dd>
+<dt><code>Invalid</code></dt>
+<dd>Token is invalid (failed HMAC or wrong length)</dd>
+<dt><code>AuthenticatedEmptyUser</code> / <code>ExpiredEmptyUser</code></dt>
+<dd>The token is not valid with the username sent from the client but
+would be valid (or expired) if we assume an empty username was
+used instead. These two cases are a workaround for behaviour in
+OpenVPN 3. If this workaround is not needed these two cases should
+be handled in the same way as <code>Invalid</code>.</dd>
+</dl>
+<p class="last"><strong>Warning:</strong> Use this feature only if you want your authentication
+method called on every verification. Since the external authentication
+is called it needs to also indicate a success or failure of the
+authentication. It is strongly recommended to return an authentication
+failure in the case of the Invalid/Expired auth-token with the
+external-auth option unless the client could authenticate in another
+acceptable way (e.g. client certificate), otherwise returning success
+will lead to authentication bypass (as does returning success on a wrong
+password from a script).</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--auth-gen-token-secret <var>file</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td>Specifies a file that holds a secret for the HMAC used in
+<tt class="docutils literal"><span class="pre">--auth-gen-token</span></tt> If <tt class="docutils literal">file</tt> is not present OpenVPN will generate a
+random secret on startup. This file should be used if auth-token should
+validate after restarting a server or if client should be able to roam
+between multiple OpenVPN servers with their auth-token.</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--auth-user-pass-optional</span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td>Allow connections by clients that do not specify a username/password.
+Normally, when <tt class="docutils literal"><span class="pre">--auth-user-pass-verify</span></tt> or
+<tt class="docutils literal"><span class="pre">--management-client-auth</span></tt> are specified (or an authentication plugin
+module), the OpenVPN server daemon will require connecting clients to
+specify a username and password. This option makes the submission of a
+username/password by clients optional, passing the responsibility to the
+user-defined authentication module/script to accept or deny the client
+based on other factors (such as the setting of X509 certificate fields).
+When this option is used, and a connecting client does not submit a
+username/password, the user-defined authentication module/script will
+see the username and password as being set to empty strings (&quot;&quot;). The
+authentication module/script MUST have logic to detect this condition
+and respond accordingly.</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--ccd-exclusive</span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td>Require, as a condition of authentication, that a connecting client has
+a <tt class="docutils literal"><span class="pre">--client-config-dir</span></tt> file.</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--client-config-dir <var>dir</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Specify a directory <tt class="docutils literal">dir</tt> for custom client config files. After a
+connecting client has been authenticated, OpenVPN will look in this
+directory for a file having the same name as the client's X509 common
+name. If a matching file exists, it will be opened and parsed for
+client-specific configuration options. If no matching file is found,
+OpenVPN will instead try to open and parse a default file called
+&quot;DEFAULT&quot;, which may be provided but is not required. Note that the
+configuration files must be readable by the OpenVPN process after it has
+dropped it's root privileges.</p>
+<p>This file can specify a fixed IP address for a given client using
+<tt class="docutils literal"><span class="pre">--ifconfig-push</span></tt>, as well as fixed subnets owned by the client using
+<tt class="docutils literal"><span class="pre">--iroute</span></tt>.</p>
+<p>One of the useful properties of this option is that it allows client
+configuration files to be conveniently created, edited, or removed while
+the server is live, without needing to restart the server.</p>
+<p class="last">The following options are legal in a client-specific context: <tt class="docutils literal"><span class="pre">--push</span></tt>,
+<tt class="docutils literal"><span class="pre">--push-reset</span></tt>, <tt class="docutils literal"><span class="pre">--push-remove</span></tt>, <tt class="docutils literal"><span class="pre">--iroute</span></tt>, <tt class="docutils literal"><span class="pre">--ifconfig-push</span></tt>,
+<tt class="docutils literal"><span class="pre">--vlan-pvid</span></tt> and <tt class="docutils literal"><span class="pre">--config</span></tt>.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--client-to-client</span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Because the OpenVPN server mode handles multiple clients through a
+single tun or tap interface, it is effectively a router. The
+<tt class="docutils literal"><span class="pre">--client-to-client</span></tt> flag tells OpenVPN to internally route
+client-to-client traffic rather than pushing all client-originating
+traffic to the TUN/TAP interface.</p>
+<p class="last">When this option is used, each client will &quot;see&quot; the other clients which
+are currently connected. Otherwise, each client will only see the
+server. Don't use this option if you want to firewall tunnel traffic
+using custom, per-client rules.</p>
+</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--disable</span></kbd></td>
+<td><p class="first">Disable a particular client (based on the common name) from connecting.
+Don't use this option to disable a client due to key or password
+compromise. Use a CRL (certificate revocation list) instead (see the
+<tt class="docutils literal"><span class="pre">--crl-verify</span></tt> option).</p>
+<p class="last">This option must be associated with a specific client instance, which
+means that it must be specified either in a client instance config file
+using <tt class="docutils literal"><span class="pre">--client-config-dir</span></tt> or dynamically generated using a
+<tt class="docutils literal"><span class="pre">--client-connect</span></tt> script.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--connect-freq <var>args</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Allow a maximum of <tt class="docutils literal">n</tt> new connections per <tt class="docutils literal">sec</tt> seconds from
+clients.</p>
+<p>Valid syntax:</p>
+<pre class="literal-block">
+connect-freq n sec
+</pre>
+<p>This is designed to contain DoS attacks which flood the server
+with connection requests using certificates which will ultimately fail
+to authenticate.</p>
+<p>This is an imperfect solution however, because in a real DoS scenario,
+legitimate connections might also be refused.</p>
+<p class="last">For the best protection against DoS attacks in server mode, use
+<tt class="docutils literal"><span class="pre">--proto</span> udp</tt> and either <tt class="docutils literal"><span class="pre">--tls-auth</span></tt> or <tt class="docutils literal"><span class="pre">--tls-crypt</span></tt>.</p>
+</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--duplicate-cn</span></kbd></td>
+<td>Allow multiple clients with the same common name to concurrently
+connect. In the absence of this option, OpenVPN will disconnect a client
+instance upon connection of a new client having the same common name.</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--ifconfig-pool <var>args</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Set aside a pool of subnets to be dynamically allocated to connecting
+clients, similar to a DHCP server.</p>
+<p>Valid syntax:</p>
+<pre class="literal-block">
+ifconfig-pool start-IP end-IP [netmask]
+</pre>
+<p class="last">For tun-style tunnels, each client
+will be given a /30 subnet (for interoperability with Windows clients).
+For tap-style tunnels, individual addresses will be allocated, and the
+optional <tt class="docutils literal">netmask</tt> parameter will also be pushed to clients.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--ifconfig-ipv6-pool <var>args</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Specify an IPv6 address pool for dynamic assignment to clients.</p>
+<p>Valid args:</p>
+<pre class="literal-block">
+ifconfig-ipv6-pool ipv6addr/bits
+</pre>
+<p class="last">The pool starts at <tt class="docutils literal">ipv6addr</tt> and matches the offset determined from
+the start of the IPv4 pool.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--ifconfig-pool-persist <var>args</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Persist/unpersist ifconfig-pool data to <tt class="docutils literal">file</tt>, at <tt class="docutils literal">seconds</tt>
+intervals (default <code>600</code>), as well as on program startup and shutdown.</p>
+<p>Valid syntax:</p>
+<pre class="literal-block">
+ifconfig-pool-persist file [seconds]
+</pre>
+<p>The goal of this option is to provide a long-term association between
+clients (denoted by their common name) and the virtual IP address
+assigned to them from the ifconfig-pool. Maintaining a long-term
+association is good for clients because it allows them to effectively
+use the <tt class="docutils literal"><span class="pre">--persist-tun</span></tt> option.</p>
+<p><tt class="docutils literal">file</tt> is a comma-delimited ASCII file, formatted as
+<code>&lt;Common-Name&gt;,&lt;IP-address&gt;</code>.</p>
+<p>If <tt class="docutils literal">seconds</tt> = <code>0</code>, <tt class="docutils literal">file</tt> will be treated as read-only. This
+is useful if you would like to treat <tt class="docutils literal">file</tt> as a configuration file.</p>
+<p class="last">Note that the entries in this file are treated by OpenVPN as
+<em>suggestions</em> only, based on past associations between a common name and
+IP address. They do not guarantee that the given common name will always
+receive the given IP address. If you want guaranteed assignment, use
+<tt class="docutils literal"><span class="pre">--ifconfig-push</span></tt></p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--ifconfig-push <var>args</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Push virtual IP endpoints for client tunnel, overriding the
+<tt class="docutils literal"><span class="pre">--ifconfig-pool</span></tt> dynamic allocation.</p>
+<p>Valid syntax:</p>
+<pre class="literal-block">
+ifconfig-push local remote-netmask [alias]
+</pre>
+<p>The parameters <tt class="docutils literal">local</tt> and <tt class="docutils literal"><span class="pre">remote-netmask</span></tt> are set according to the
+<tt class="docutils literal"><span class="pre">--ifconfig</span></tt> directive which you want to execute on the client machine
+to configure the remote end of the tunnel. Note that the parameters
+<tt class="docutils literal">local</tt> and <tt class="docutils literal"><span class="pre">remote-netmask</span></tt> are from the perspective of the client,
+not the server. They may be DNS names rather than IP addresses, in which
+case they will be resolved on the server at the time of client
+connection.</p>
+<p>The optional <tt class="docutils literal">alias</tt> parameter may be used in cases where NAT causes
+the client view of its local endpoint to differ from the server view. In
+this case <tt class="docutils literal"><span class="pre">local/remote-netmask</span></tt> will refer to the server view while
+<tt class="docutils literal"><span class="pre">alias/remote-netmask</span></tt> will refer to the client view.</p>
+<p>This option must be associated with a specific client instance, which
+means that it must be specified either in a client instance config file
+using <tt class="docutils literal"><span class="pre">--client-config-dir</span></tt> or dynamically generated using a
+<tt class="docutils literal"><span class="pre">--client-connect</span></tt> script.</p>
+<p>Remember also to include a <tt class="docutils literal"><span class="pre">--route</span></tt> directive in the main OpenVPN
+config file which encloses <tt class="docutils literal">local</tt>, so that the kernel will know to
+route it to the server's TUN/TAP interface.</p>
+<p>OpenVPN's internal client IP address selection algorithm works as
+follows:</p>
+<ol class="last arabic simple">
+<li>Use <tt class="docutils literal"><span class="pre">--client-connect</span> script</tt> generated file for static IP
+(first choice).</li>
+<li>Use <tt class="docutils literal"><span class="pre">--client-config-dir</span></tt> file for static IP (next choice).</li>
+<li>Use <tt class="docutils literal"><span class="pre">--ifconfig-pool</span></tt> allocation for dynamic IP (last
+choice).</li>
+</ol>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--ifconfig-ipv6-push <var>args</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">for <tt class="docutils literal"><span class="pre">--client-config-dir</span></tt> per-client static IPv6 interface
+configuration, see <tt class="docutils literal"><span class="pre">--client-config-dir</span></tt> and <tt class="docutils literal"><span class="pre">--ifconfig-push</span></tt> for
+more details.</p>
+<p>Valid syntax:</p>
+<pre class="last literal-block">
+ifconfig-ipv6-push ipv6addr/bits ipv6remote
+</pre>
+</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--inetd <var>args</var></span></kbd></td>
+<td><p class="first">Valid syntaxes:</p>
+<pre class="literal-block">
+inetd
+inetd wait
+inetd nowait
+inetd wait progname
+</pre>
+<p>Use this option when OpenVPN is being run from the inetd or <tt class="docutils literal">xinetd</tt>(8)
+server.</p>
+<p>The <code>wait</code> and <code>nowait</code> option must match what is specified
+in the inetd/xinetd config file. The <code>nowait</code> mode can only be used
+with <tt class="docutils literal"><span class="pre">--proto</span> <span class="pre">tcp-server</span></tt> The default is <code>wait</code>. The
+<code>nowait</code> mode can be used to instantiate the OpenVPN daemon as a
+classic TCP server, where client connection requests are serviced on a
+single port number. For additional information on this kind of
+configuration, see the OpenVPN FAQ:
+<a class="reference external" href="https://community.openvpn.net/openvpn/wiki/325-openvpn-as-a--forking-tcp-server-which-can-service-multiple-clients-over-a-single-tcp-port">https://community.openvpn.net/openvpn/wiki/325-openvpn-as-a--forking-tcp-server-which-can-service-multiple-clients-over-a-single-tcp-port</a></p>
+<p>This option precludes the use of <tt class="docutils literal"><span class="pre">--daemon</span></tt>, <tt class="docutils literal"><span class="pre">--local</span></tt> or
+<tt class="docutils literal"><span class="pre">--remote</span></tt>. Note that this option causes message and error output to
+be handled in the same way as the <tt class="docutils literal"><span class="pre">--daemon</span></tt> option. The optional
+<tt class="docutils literal">progname</tt> parameter is also handled exactly as in <tt class="docutils literal"><span class="pre">--daemon</span></tt>.</p>
+<p class="last">Also note that in <tt class="docutils literal">wait</tt> mode, each OpenVPN tunnel requires a separate
+TCP/UDP port and a separate inetd or xinetd entry. See the OpenVPN 1.x
+HOWTO for an example on using OpenVPN with xinetd:
+<a class="reference external" href="https://openvpn.net/community-resources/1xhowto/">https://openvpn.net/community-resources/1xhowto/</a></p>
+</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--multihome</span></kbd></td>
+<td><p class="first">Configure a multi-homed UDP server. This option needs to be used when a
+server has more than one IP address (e.g. multiple interfaces, or
+secondary IP addresses), and is not using <tt class="docutils literal"><span class="pre">--local</span></tt> to force binding
+to one specific address only. This option will add some extra lookups to
+the packet path to ensure that the UDP reply packets are always sent
+from the address that the client is talking to. This is not supported on
+all platforms, and it adds more processing, so it's not enabled by
+default.</p>
+<dl class="last docutils">
+<dt><em>Notes:</em></dt>
+<dd><ul class="first last simple">
+<li>This option is only relevant for UDP servers.</li>
+<li>If you do an IPv6+IPv4 dual-stack bind on a Linux machine with
+multiple IPv4 address, connections to IPv4 addresses will not
+work right on kernels before 3.15, due to missing kernel
+support for the IPv4-mapped case (some distributions have
+ported this to earlier kernel versions, though).</li>
+</ul>
+</dd>
+</dl>
+</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--iroute <var>args</var></span></kbd></td>
+<td><p class="first">Generate an internal route to a specific client. The <tt class="docutils literal">netmask</tt>
+parameter, if omitted, defaults to <code>255.255.255.255</code>.</p>
+<p>Valid syntax:</p>
+<pre class="literal-block">
+iroute network [netmask]
+</pre>
+<p>This directive can be used to route a fixed subnet from the server to a
+particular client, regardless of where the client is connecting from.
+Remember that you must also add the route to the system routing table as
+well (such as by using the <tt class="docutils literal"><span class="pre">--route</span></tt> directive). The reason why two
+routes are needed is that the <tt class="docutils literal"><span class="pre">--route</span></tt> directive routes the packet
+from the kernel to OpenVPN. Once in OpenVPN, the <tt class="docutils literal"><span class="pre">--iroute</span></tt> directive
+routes to the specific client.</p>
+<p>This option must be specified either in a client instance config file
+using <tt class="docutils literal"><span class="pre">--client-config-dir</span></tt> or dynamically generated using a
+<tt class="docutils literal"><span class="pre">--client-connect</span></tt> script.</p>
+<p class="last">The <tt class="docutils literal"><span class="pre">--iroute</span></tt> directive also has an important interaction with
+<tt class="docutils literal"><span class="pre">--push</span> &quot;route <span class="pre">...&quot;</span></tt>. <tt class="docutils literal"><span class="pre">--iroute</span></tt> essentially defines a subnet which
+is owned by a particular client (we will call this client <em>A</em>). If you
+would like other clients to be able to reach <em>A</em>'s subnet, you can use
+<tt class="docutils literal"><span class="pre">--push</span> &quot;route <span class="pre">...&quot;</span></tt> together with <tt class="docutils literal"><span class="pre">--client-to-client</span></tt> to effect
+this. In order for all clients to see <em>A</em>'s subnet, OpenVPN must push
+this route to all clients EXCEPT for <em>A</em>, since the subnet is already
+owned by <em>A</em>. OpenVPN accomplishes this by not not pushing a route to
+a client if it matches one of the client's iroutes.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--iroute-ipv6 <var>args</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">for <tt class="docutils literal"><span class="pre">--client-config-dir</span></tt> per-client static IPv6 route configuration,
+see <tt class="docutils literal"><span class="pre">--iroute</span></tt> for more details how to setup and use this, and how
+<tt class="docutils literal"><span class="pre">--iroute</span></tt> and <tt class="docutils literal"><span class="pre">--route</span></tt> interact.</p>
+<p>Valid syntax:</p>
+<pre class="last literal-block">
+iroute-ipv6 ipv6addr/bits
+</pre>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--max-clients <var>n</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td>Limit server to a maximum of <tt class="docutils literal">n</tt> concurrent clients.</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--max-routes-per-client <var>n</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Allow a maximum of <tt class="docutils literal">n</tt> internal routes per client (default
+<code>256</code>). This is designed to help contain DoS attacks where an
+authenticated client floods the server with packets appearing to come
+from many unique MAC addresses, forcing the server to deplete virtual
+memory as its internal routing table expands. This directive can be used
+in a <tt class="docutils literal"><span class="pre">--client-config-dir</span></tt> file or auto-generated by a
+<tt class="docutils literal"><span class="pre">--client-connect</span></tt> script to override the global value for a particular
+client.</p>
+<p class="last">Note that this directive affects OpenVPN's internal routing table, not
+the kernel routing table.</p>
+</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--opt-verify</span></kbd></td>
+<td><p class="first">Clients that connect with options that are incompatible with those of the
+server will be disconnected.</p>
+<p>Options that will be compared for compatibility include <tt class="docutils literal"><span class="pre">dev-type</span></tt>,
+<tt class="docutils literal"><span class="pre">link-mtu</span></tt>, <tt class="docutils literal"><span class="pre">tun-mtu</span></tt>, <tt class="docutils literal">proto</tt>, <tt class="docutils literal">ifconfig</tt>,
+<tt class="docutils literal"><span class="pre">comp-lzo</span></tt>, <tt class="docutils literal">fragment</tt>, <tt class="docutils literal">keydir</tt>, <tt class="docutils literal">cipher</tt>,
+<tt class="docutils literal">auth</tt>, <tt class="docutils literal">keysize</tt>, <tt class="docutils literal">secret</tt>, <tt class="docutils literal"><span class="pre">no-replay</span></tt>,
+<tt class="docutils literal"><span class="pre">tls-auth</span></tt>, <tt class="docutils literal"><span class="pre">key-method</span></tt>, <tt class="docutils literal"><span class="pre">tls-server</span></tt>
+and <tt class="docutils literal"><span class="pre">tls-client</span></tt>.</p>
+<p class="last">This option requires that <tt class="docutils literal"><span class="pre">--disable-occ</span></tt> NOT be used.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--port-share <var>args</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Share OpenVPN TCP with another service</p>
+<p>Valid syntax:</p>
+<pre class="literal-block">
+port-share host port [dir]
+</pre>
+<p>When run in TCP server mode, share the OpenVPN port with another
+application, such as an HTTPS server. If OpenVPN senses a connection to
+its port which is using a non-OpenVPN protocol, it will proxy the
+connection to the server at <tt class="docutils literal">host</tt>:<tt class="docutils literal">port</tt>. Currently only designed to
+work with HTTP/HTTPS, though it would be theoretically possible to
+extend to other protocols such as ssh.</p>
+<p><tt class="docutils literal">dir</tt> specifies an optional directory where a temporary file with name
+N containing content C will be dynamically generated for each proxy
+connection, where N is the source IP:port of the client connection and C
+is the source IP:port of the connection to the proxy receiver. This
+directory can be used as a dictionary by the proxy receiver to determine
+the origin of the connection. Each generated file will be automatically
+deleted when the proxied connection is torn down.</p>
+<p class="last">Not implemented on Windows.</p>
+</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--push <var>option</var></span></kbd></td>
+<td><p class="first">Push a config file option back to the client for remote execution. Note
+that <tt class="docutils literal">option</tt> must be enclosed in double quotes (<code>&quot;&quot;</code>). The
+client must specify <tt class="docutils literal"><span class="pre">--pull</span></tt> in its config file. The set of options
+which can be pushed is limited by both feasibility and security. Some
+options such as those which would execute scripts are banned, since they
+would effectively allow a compromised server to execute arbitrary code
+on the client. Other options such as TLS or MTU parameters cannot be
+pushed because the client needs to know them before the connection to the
+server can be initiated.</p>
+<p class="last">This is a partial list of options which can currently be pushed:
+<tt class="docutils literal"><span class="pre">--route</span></tt>, <tt class="docutils literal"><span class="pre">--route-gateway</span></tt>, <tt class="docutils literal"><span class="pre">--route-delay</span></tt>,
+<tt class="docutils literal"><span class="pre">--redirect-gateway</span></tt>, <tt class="docutils literal"><span class="pre">--ip-win32</span></tt>, <tt class="docutils literal"><span class="pre">--dhcp-option</span></tt>,
+<tt class="docutils literal"><span class="pre">--inactive</span></tt>, <tt class="docutils literal"><span class="pre">--ping</span></tt>, <tt class="docutils literal"><span class="pre">--ping-exit</span></tt>, <tt class="docutils literal"><span class="pre">--ping-restart</span></tt>,
+<tt class="docutils literal"><span class="pre">--setenv</span></tt>, <tt class="docutils literal"><span class="pre">--auth-token</span></tt>, <tt class="docutils literal"><span class="pre">--persist-key</span></tt>, <tt class="docutils literal"><span class="pre">--persist-tun</span></tt>,
+<tt class="docutils literal"><span class="pre">--echo</span></tt>, <tt class="docutils literal"><span class="pre">--comp-lzo</span></tt>, <tt class="docutils literal"><span class="pre">--socket-flags</span></tt>, <tt class="docutils literal"><span class="pre">--sndbuf</span></tt>,
+<tt class="docutils literal"><span class="pre">--rcvbuf</span></tt></p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--push-peer-info</span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Push additional information about the client to server. The following
+data is always pushed to the server:</p>
+<dl class="docutils">
+<dt><code>IV_VER=&lt;version&gt;</code></dt>
+<dd>The client OpenVPN version</dd>
+<dt><code>IV_PLAT=[linux|solaris|openbsd|mac|netbsd|freebsd|win]</code></dt>
+<dd>The client OS platform</dd>
+<dt><code>IV_LZO_STUB=1</code></dt>
+<dd>If client was built with LZO stub capability</dd>
+<dt><code>IV_LZ4=1</code></dt>
+<dd>If the client supports LZ4 compressions.</dd>
+<dt><code>IV_PROTO</code></dt>
+<dd><p class="first">Details about protocol extensions that the peer supports. The
+variable is a bitfield and the bits are defined as follows
+(starting a bit 0 for the first (unused) bit:</p>
+<ul class="last simple">
+<li>bit 1: The peer supports peer-id floating mechanism</li>
+<li>bit 2: The client expects a push-reply and the server may
+send this reply without waiting for a push-request first.</li>
+</ul>
+</dd>
+<dt><code>IV_NCP=2</code></dt>
+<dd>Negotiable ciphers, client supports <tt class="docutils literal"><span class="pre">--cipher</span></tt> pushed by
+the server, a value of 2 or greater indicates client supports
+<em>AES-GCM-128</em> and <em>AES-GCM-256</em>.</dd>
+<dt><code>IV_CIPHERS=&lt;ncp-ciphers&gt;</code></dt>
+<dd>The client announces the list of supported ciphers configured with the
+<tt class="docutils literal"><span class="pre">--data-ciphers</span></tt> option to the server.</dd>
+<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>
+</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_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>
+<dt><code>IV_PLAT_VER=x.y</code></dt>
+<dd>The version of the operating system, e.g. 6.1 for Windows 7.</dd>
+<dt><code>UV_&lt;name&gt;=&lt;value&gt;</code></dt>
+<dd>Client environment variables whose names start with
+<code>UV_</code></dd>
+</dl>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--push-remove <var>opt</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Selectively remove all <tt class="docutils literal"><span class="pre">--push</span></tt> options matching &quot;opt&quot; from the option
+list for a client. <tt class="docutils literal">opt</tt> is matched as a substring against the whole
+option string to-be-pushed to the client, so <tt class="docutils literal"><span class="pre">--push-remove</span> route</tt>
+would remove all <tt class="docutils literal"><span class="pre">--push</span> route ...</tt> and <tt class="docutils literal"><span class="pre">--push</span> <span class="pre">route-ipv6</span> ...</tt>
+statements, while <tt class="docutils literal"><span class="pre">--push-remove</span> <span class="pre">&quot;route-ipv6</span> 2001:&quot;</tt> would only remove
+IPv6 routes for <code>2001:...</code> networks.</p>
+<p><tt class="docutils literal"><span class="pre">--push-remove</span></tt> can only be used in a client-specific context, like in
+a <tt class="docutils literal"><span class="pre">--client-config-dir</span></tt> file, or <tt class="docutils literal"><span class="pre">--client-connect</span></tt> script or plugin
+-- similar to <tt class="docutils literal"><span class="pre">--push-reset</span></tt>, just more selective.</p>
+<p><em>NOTE</em>: to <em>change</em> an option, <tt class="docutils literal"><span class="pre">--push-remove</span></tt> can be used to first
+remove the old value, and then add a new <tt class="docutils literal"><span class="pre">--push</span></tt> option with the new
+value.</p>
+<p class="last"><em>NOTE 2</em>: due to implementation details, 'ifconfig' and 'ifconfig-ipv6'
+can only be removed with an exact match on the option (
+<code>push-remove ifconfig</code>), no substring matching and no matching on
+the IPv4/IPv6 address argument is possible.</p>
+</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--push-reset</span></kbd></td>
+<td>Don't inherit the global push list for a specific client instance.
+Specify this option in a client-specific context such as with a
+<tt class="docutils literal"><span class="pre">--client-config-dir</span></tt> configuration file. This option will ignore
+<tt class="docutils literal"><span class="pre">--push</span></tt> options at the global config file level.</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--server <var>args</var></span></kbd></td>
+<td><p class="first">A helper directive designed to simplify the configuration of OpenVPN's
+server mode. This directive will set up an OpenVPN server which will
+allocate addresses to clients out of the given network/netmask. The
+server itself will take the <code>.1</code> address of the given network for
+use as the server-side endpoint of the local TUN/TAP interface. If the
+optional <code>nopool</code> flag is given, no dynamic IP address pool will
+prepared for VPN clients.</p>
+<p>Valid syntax:</p>
+<pre class="literal-block">
+server network netmask [nopool]
+</pre>
+<p>For example, <tt class="docutils literal"><span class="pre">--server</span> 10.8.0.0 255.255.255.0</tt> expands as follows:</p>
+<pre class="literal-block">
+mode server
+tls-server
+push &quot;topology [topology]&quot;
+
+if dev tun AND (topology == net30 OR topology == p2p):
+ ifconfig 10.8.0.1 10.8.0.2
+ if !nopool:
+ ifconfig-pool 10.8.0.4 10.8.0.251
+ route 10.8.0.0 255.255.255.0
+ if client-to-client:
+ push &quot;route 10.8.0.0 255.255.255.0&quot;
+ else if topology == net30:
+ push &quot;route 10.8.0.1&quot;
+
+if dev tap OR (dev tun AND topology == subnet):
+ ifconfig 10.8.0.1 255.255.255.0
+ if !nopool:
+ ifconfig-pool 10.8.0.2 10.8.0.253 255.255.255.0
+ push &quot;route-gateway 10.8.0.1&quot;
+ if route-gateway unset:
+ route-gateway 10.8.0.2
+</pre>
+<p class="last">Don't use <tt class="docutils literal"><span class="pre">--server</span></tt> if you are ethernet bridging. Use
+<tt class="docutils literal"><span class="pre">--server-bridge</span></tt> instead.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--server-bridge <var>args</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">A helper directive similar to <tt class="docutils literal"><span class="pre">--server</span></tt> which is designed to simplify
+the configuration of OpenVPN's server mode in ethernet bridging
+configurations.</p>
+<p>Valid syntaxes:</p>
+<pre class="literal-block">
+server-bridge gateway netmask pool-start-IP pool-end-IP
+server-bridge [nogw]
+</pre>
+<p>If <tt class="docutils literal"><span class="pre">--server-bridge</span></tt> is used without any parameters, it will enable a
+DHCP-proxy mode, where connecting OpenVPN clients will receive an IP
+address for their TAP adapter from the DHCP server running on the
+OpenVPN server-side LAN. Note that only clients that support the binding
+of a DHCP client with the TAP adapter (such as Windows) can support this
+mode. The optional <code>nogw</code> flag (advanced) indicates that gateway
+information should not be pushed to the client.</p>
+<p>To configure ethernet bridging, you must first use your OS's bridging
+capability to bridge the TAP interface with the ethernet NIC interface.
+For example, on Linux this is done with the <code>brctl</code> tool, and with
+Windows XP it is done in the Network Connections Panel by selecting the
+ethernet and TAP adapters and right-clicking on &quot;Bridge Connections&quot;.</p>
+<p>Next you you must manually set the IP/netmask on the bridge interface.
+The <tt class="docutils literal">gateway</tt> and <tt class="docutils literal">netmask</tt> parameters to <tt class="docutils literal"><span class="pre">--server-bridge</span></tt> can be
+set to either the IP/netmask of the bridge interface, or the IP/netmask
+of the default gateway/router on the bridged subnet.</p>
+<p>Finally, set aside a IP range in the bridged subnet, denoted by
+<tt class="docutils literal"><span class="pre">pool-start-IP</span></tt> and <tt class="docutils literal"><span class="pre">pool-end-IP</span></tt>, for OpenVPN to allocate to
+connecting clients.</p>
+<p>For example, <tt class="docutils literal"><span class="pre">server-bridge</span> 10.8.0.4 255.255.255.0 10.8.0.128
+10.8.0.254</tt> expands as follows:</p>
+<pre class="literal-block">
+mode server
+tls-server
+
+ifconfig-pool 10.8.0.128 10.8.0.254 255.255.255.0
+push &quot;route-gateway 10.8.0.4&quot;
+</pre>
+<p>In another example, <tt class="docutils literal"><span class="pre">--server-bridge</span></tt> (without parameters) expands as
+follows:</p>
+<pre class="literal-block">
+mode server
+tls-server
+
+push &quot;route-gateway dhcp&quot;
+</pre>
+<p>Or <tt class="docutils literal"><span class="pre">--server-bridge</span> nogw</tt> expands as follows:</p>
+<pre class="last literal-block">
+mode server
+tls-server
+</pre>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--stale-routes-check <var>args</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Remove routes which haven't had activity for <tt class="docutils literal">n</tt> seconds (i.e. the ageing
+time). This check is run every <tt class="docutils literal">t</tt> seconds (i.e. check interval).</p>
+<p>Valid syntax:</p>
+<pre class="literal-block">
+stale-routes-check n [t]
+</pre>
+<p>If <tt class="docutils literal">t</tt> is not present it defaults to <tt class="docutils literal">n</tt>.</p>
+<p class="last">This option helps to keep the dynamic routing table small. See also
+<tt class="docutils literal"><span class="pre">--max-routes-per-client</span></tt></p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--username-as-common-name</span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td>For <tt class="docutils literal"><span class="pre">--auth-user-pass-verify</span></tt> authentication, use the authenticated
+username as the common name, rather than the common name from the client
+cert.</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--verify-client-cert <var>mode</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Specify whether the client is required to supply a valid certificate.</p>
+<p>Possible <tt class="docutils literal">mode</tt> options are:</p>
+<dl class="docutils">
+<dt><code>none</code></dt>
+<dd><p class="first">A client certificate is not required. the client needs to
+authenticate using username/password only. Be aware that using this
+directive is less secure than requiring certificates from all
+clients.</p>
+<p>If you use this directive, the entire responsibility of authentication
+will rest on your <tt class="docutils literal"><span class="pre">--auth-user-pass-verify</span></tt> script, so keep in mind
+that bugs in your script could potentially compromise the security of
+your VPN.</p>
+<p class="last"><tt class="docutils literal"><span class="pre">--verify-client-cert</span> none</tt> is functionally equivalent to
+<tt class="docutils literal"><span class="pre">--client-cert-not-required</span></tt>.</p>
+</dd>
+<dt><code>optional</code></dt>
+<dd><p class="first">A client may present a certificate but it is not required to do so.
+When using this directive, you should also use a
+<tt class="docutils literal"><span class="pre">--auth-user-pass-verify</span></tt> script to ensure that clients are
+authenticated using a certificate, a username and password, or
+possibly even both.</p>
+<p class="last">Again, the entire responsibility of authentication will rest on your
+<tt class="docutils literal"><span class="pre">--auth-user-pass-verify</span></tt> script, so keep in mind that bugs in your
+script could potentially compromise the security of your VPN.</p>
+</dd>
+<dt><code>require</code></dt>
+<dd>This is the default option. A client is required to present a
+certificate, otherwise VPN access is refused.</dd>
+</dl>
+<p class="last">If you don't use this directive (or use <tt class="docutils literal"><span class="pre">--verify-client-cert</span> require</tt>)
+but you also specify an <tt class="docutils literal"><span class="pre">--auth-user-pass-verify</span></tt> script, then OpenVPN
+will perform double authentication. The client certificate verification
+AND the <tt class="docutils literal"><span class="pre">--auth-user-pass-verify</span></tt> script will need to succeed in order
+for a client to be authenticated and accepted onto the VPN.</p>
+</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--vlan-tagging</span></kbd></td>
+<td><p class="first">Server-only option. Turns the OpenVPN server instance into a switch that
+understands VLAN-tagging, based on IEEE 802.1Q.</p>
+<p>The server TAP device and each of the connecting clients is seen as a
+port of the switch. All client ports are in untagged mode and the server
+TAP device is VLAN-tagged, untagged or accepts both, depending on the
+<tt class="docutils literal"><span class="pre">--vlan-accept</span></tt> setting.</p>
+<p>Ethernet frames with a prepended 802.1Q tag are called &quot;tagged&quot;. If the
+VLAN Identifier (VID) field in such a tag is non-zero, the frame is
+called &quot;VLAN-tagged&quot;. If the VID is zero, but the Priority Control Point
+(PCP) field is non-zero, the frame is called &quot;prio-tagged&quot;. If there is
+no 802.1Q tag, the frame is &quot;untagged&quot;.</p>
+<p>Using the <tt class="docutils literal"><span class="pre">--vlan-pvid</span> v</tt> option once per client (see
+--client-config-dir), each port can be associated with a certain VID.
+Packets can only be forwarded between ports having the same VID.
+Therefore, clients with differing VIDs are completely separated from
+one-another, even if <tt class="docutils literal"><span class="pre">--client-to-client</span></tt> is activated.</p>
+<p>The packet filtering takes place in the OpenVPN server. Clients should
+not have any VLAN tagging configuration applied.</p>
+<p>The <tt class="docutils literal"><span class="pre">--vlan-tagging</span></tt> option is off by default. While turned off,
+OpenVPN accepts any Ethernet frame and does not perform any special
+processing for VLAN-tagged packets.</p>
+<p class="last">This option can only be activated in <tt class="docutils literal"><span class="pre">--dev</span> tap mode</tt>.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--vlan-accept <var>args</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Configure the VLAN tagging policy for the server TAP device.</p>
+<p>Valid syntax:</p>
+<pre class="literal-block">
+vlan-accept all|tagged|untagged
+</pre>
+<p>The following modes are available:</p>
+<dl class="docutils">
+<dt><code>tagged</code></dt>
+<dd>Admit only VLAN-tagged frames. Only VLAN-tagged packets are accepted,
+while untagged or priority-tagged packets are dropped when entering
+the server TAP device.</dd>
+<dt><code>untagged</code></dt>
+<dd>Admit only untagged and prio-tagged frames. VLAN-tagged packets are
+not accepted, while untagged or priority-tagged packets entering the
+server TAP device are tagged with the value configured for the global
+<tt class="docutils literal"><span class="pre">--vlan-pvid</span></tt> setting.</dd>
+<dt><code>all</code> (default)</dt>
+<dd>Admit all frames. All packets are admitted and then treated like
+untagged or tagged mode respectively.</dd>
+<dt><em>Note</em>:</dt>
+<dd>Some vendors refer to switch ports running in <code>tagged</code> mode
+as &quot;trunk ports&quot; and switch ports running in <code>untagged</code> mode
+as &quot;access ports&quot;.</dd>
+</dl>
+<p>Packets forwarded from clients to the server are VLAN-tagged with the
+originating client's PVID, unless the VID matches the global
+<tt class="docutils literal"><span class="pre">--vlan-pvid</span></tt>, in which case the tag is removed.</p>
+<p class="last">If no <em>PVID</em> is configured for a given client (see --vlan-pvid) packets
+are tagged with 1 by default.</p>
+</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--vlan-pvid <var>v</var></span></kbd></td>
+<td><p class="first">Specifies which VLAN identifier a &quot;port&quot; is associated with. Only valid
+when <tt class="docutils literal"><span class="pre">--vlan-tagging</span></tt> is speficied.</p>
+<p>In the client context, the setting specifies which VLAN ID a client is
+associated with. In the global context, the VLAN ID of the server TAP
+device is set. The latter only makes sense for <tt class="docutils literal"><span class="pre">--vlan-accept</span>
+untagged</tt> and <tt class="docutils literal"><span class="pre">--vlan-accept</span> all</tt> modes.</p>
+<p>Valid values for <tt class="docutils literal">v</tt> go from <code>1</code> through to <code>4094</code>. The
+global value defaults to <code>1</code>. If no <tt class="docutils literal"><span class="pre">--vlan-pvid</span></tt> is specified in
+the client context, the global value is inherited.</p>
+<p class="last">In some switch implementations, the <em>PVID</em> is also referred to as &quot;Native
+VLAN&quot;.</p>
+</td></tr>
+</tbody>
+</table>
+</div>
+</div>
+<div class="section" id="encryption-options">
+<h1>Encryption Options</h1>
+<div class="section" id="ssl-library-information">
+<h2>SSL Library information</h2>
+<table class="docutils option-list" frame="void" rules="none">
+<col class="option" />
+<col class="description" />
+<tbody valign="top">
+<tr><td class="option-group">
+<kbd><span class="option">--show-ciphers</span></kbd></td>
+<td>(Standalone) Show all cipher algorithms to use with the <tt class="docutils literal"><span class="pre">--cipher</span></tt>
+option.</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--show-digests</span></kbd></td>
+<td>(Standalone) Show all message digest algorithms to use with the
+<tt class="docutils literal"><span class="pre">--auth</span></tt> option.</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--show-tls</span></kbd></td>
+<td><p class="first">(Standalone) Show all TLS ciphers supported by the crypto library.
+OpenVPN uses TLS to secure the control channel, over which the keys that
+are used to protect the actual VPN traffic are exchanged. The TLS
+ciphers will be sorted from highest preference (most secure) to lowest.</p>
+<p class="last">Be aware that whether a cipher suite in this list can actually work
+depends on the specific setup of both peers (e.g. both peers must
+support the cipher, and an ECDSA cipher suite will not work if you are
+using an RSA certificate, etc.).</p>
+</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--show-engines</span></kbd></td>
+<td>(Standalone) Show currently available hardware-based crypto acceleration
+engines supported by the OpenSSL library.</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--show-groups</span></kbd></td>
+<td>(Standalone) Show all available elliptic curves/groups to use with the
+<tt class="docutils literal"><span class="pre">--ecdh-curve</span></tt> and <tt class="docutils literal"><span class="pre">tls-groups</span></tt> options.</td></tr>
+</tbody>
+</table>
+</div>
+<div class="section" id="generating-key-material">
+<h2>Generating key material</h2>
+<table class="docutils option-list" frame="void" rules="none">
+<col class="option" />
+<col class="description" />
+<tbody valign="top">
+<tr><td class="option-group">
+<kbd><span class="option">--genkey <var>args</var></span></kbd></td>
+<td><p class="first">(Standalone) Generate a key to be used of the type keytype. if keyfile
+is left out or empty the key will be output on stdout. See the following
+sections for the different keytypes.</p>
+<p>Valid syntax:</p>
+<pre class="literal-block">
+--genkey keytype keyfile
+</pre>
+<p>Valid keytype arguments are:</p>
+<p><code>secret</code> Standard OpenVPN shared secret keys</p>
+<p><code>tls-crypt</code> Alias for <code>secret</code></p>
+<p><code>tls-auth</code> Alias for <code>secret</code></p>
+<p><code>auth-token</code> Key used for <tt class="docutils literal"><span class="pre">--auth-gen-token-key</span></tt></p>
+<p><code>tls-crypt-v2-server</code> TLS Crypt v2 server key</p>
+<p><code>tls-crypt-v2-client</code> TLS Crypt v2 client key</p>
+<p>Examples:</p>
+<pre class="literal-block">
+$ openvpn --genkey secret shared.key
+$ openvpn --genkey tls-crypt shared.key
+$ openvpn --genkey tls-auth shared.key
+$ openvpn --genkey tls-crypt-v2-server v2crypt-server.key
+$ openvpn --tls-crypt-v2 v2crypt-server.key --genkey tls-crypt-v2-client v2crypt-client-1.key
+</pre>
+<ul class="last">
+<li><p class="first">Generating <em>Shared Secret Keys</em>
+Generate a shared secret, for use with the <tt class="docutils literal"><span class="pre">--secret</span></tt>, <tt class="docutils literal"><span class="pre">--tls-auth</span></tt>
+or <tt class="docutils literal"><span class="pre">--tls-crypt</span></tt> options.</p>
+<p>Syntax:</p>
+<pre class="literal-block">
+$ openvpn --genkey secret|tls-crypt|tls-auth keyfile
+</pre>
+<p>The key is saved in <tt class="docutils literal">keyfile</tt>. All three variants (<tt class="docutils literal"><span class="pre">--secret</span></tt>,
+<tt class="docutils literal"><span class="pre">tls-crypt</span></tt> and <tt class="docutils literal"><span class="pre">tls-auth</span></tt>) generate the same type of key. The
+aliases are added for convenience.</p>
+<p>If using this for <tt class="docutils literal"><span class="pre">--secret</span></tt>, this file must be shared with the peer
+over a pre-existing secure channel such as <tt class="docutils literal">scp</tt>(1).</p>
+</li>
+<li><p class="first">Generating <em>TLS Crypt v2 Server key</em>
+Generate a <tt class="docutils literal"><span class="pre">--tls-crypt-v2</span></tt> key to be used by an OpenVPN server.
+The key is stored in <tt class="docutils literal">keyfile</tt>.</p>
+<p>Syntax:</p>
+<pre class="literal-block">
+--genkey tls-crypt-v2-server keyfile
+</pre>
+</li>
+<li><p class="first">Generating <em>TLS Crypt v2 Client key</em>
+Generate a --tls-crypt-v2 key to be used by OpenVPN clients. The
+key is stored in <tt class="docutils literal">keyfile</tt>.</p>
+<p>Syntax</p>
+<pre class="literal-block">
+--genkey tls-crypt-v2-client keyfile [metadata]
+</pre>
+<p>If supplied, include the supplied <tt class="docutils literal">metadata</tt> in the wrapped client
+key. This metadata must be supplied in base64-encoded form. The
+metadata must be at most 735 bytes long (980 bytes in base64).</p>
+<p>If no metadata is supplied, OpenVPN will use a 64-bit unix timestamp
+representing the current time in UTC, encoded in network order, as
+metadata for the generated key.</p>
+<p>A tls-crypt-v2 client key is wrapped using a server key. To generate a
+client key, the user must therefore supply the server key using the
+<tt class="docutils literal"><span class="pre">--tls-crypt-v2</span></tt> option.</p>
+<p>Servers can use <tt class="docutils literal"><span class="pre">--tls-crypt-v2-verify</span></tt> to specify a metadata
+verification command.</p>
+</li>
+<li><p class="first">Generate <em>Authentication Token key</em>
+Generate a new secret that can be used with <strong>--auth-gen-token-secret</strong></p>
+<p>Syntax:</p>
+<pre class="literal-block">
+--genkey auth-token [keyfile]
+</pre>
+<dl class="docutils">
+<dt><em>Note:</em></dt>
+<dd><p class="first last">This file should be kept secret to the server as anyone that has
+access to this file will be able to generate auth tokens that the
+OpenVPN server will accept as valid.</p>
+</dd>
+</dl>
+</li>
+</ul>
+</td></tr>
+</tbody>
+</table>
+</div>
+<div class="section" id="data-channel-renegotiation">
+<h2>Data Channel Renegotiation</h2>
+<p>When running OpenVPN in client/server mode, the data channel will use a
+separate ephemeral encryption key which is rotated at regular intervals.</p>
+<table class="docutils option-list" frame="void" rules="none">
+<col class="option" />
+<col class="description" />
+<tbody valign="top">
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--reneg-bytes <var>n</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Renegotiate data channel key after <tt class="docutils literal">n</tt> bytes sent or received
+(disabled by default with an exception, see below). OpenVPN allows the
+lifetime of a key to be expressed as a number of bytes
+encrypted/decrypted, a number of packets, or a number of seconds. A key
+renegotiation will be forced if any of these three criteria are met by
+either peer.</p>
+<p class="last">If using ciphers with cipher block sizes less than 128-bits,
+<tt class="docutils literal"><span class="pre">--reneg-bytes</span></tt> is set to 64MB by default, unless it is explicitly
+disabled by setting the value to <code>0</code>, but this is
+<strong>HIGHLY DISCOURAGED</strong> as this is designed to add some protection against
+the SWEET32 attack vector. For more information see the <tt class="docutils literal"><span class="pre">--cipher</span></tt>
+option.</p>
+</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--reneg-pkts <var>n</var></span></kbd></td>
+<td>Renegotiate data channel key after <strong>n</strong> packets sent and received
+(disabled by default).</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--reneg-sec <var>args</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Renegotiate data channel key after at most <tt class="docutils literal">max</tt> seconds
+(default <code>3600</code>) and at least <tt class="docutils literal">min</tt> seconds (default is 90% of
+<tt class="docutils literal">max</tt> for servers, and equal to <tt class="docutils literal">max</tt> for clients).</p>
+<pre class="literal-block">
+reneg-sec max [min]
+</pre>
+<p>The effective <tt class="docutils literal"><span class="pre">--reneg-sec</span></tt> value used is per session
+pseudo-uniform-randomized between <tt class="docutils literal">min</tt> and <tt class="docutils literal">max</tt>.</p>
+<p>With the default value of <code>3600</code> this results in an effective per
+session value in the range of <code>3240</code>..:code:<cite>3600</cite> seconds for
+servers, or just 3600 for clients.</p>
+<p>When using dual-factor authentication, note that this default value may
+cause the end user to be challenged to reauthorize once per hour.</p>
+<p class="last">Also, keep in mind that this option can be used on both the client and
+server, and whichever uses the lower value will be the one to trigger
+the renegotiation. A common mistake is to set <tt class="docutils literal"><span class="pre">--reneg-sec</span></tt> to a
+higher value on either the client or server, while the other side of the
+connection is still using the default value of <code>3600</code> seconds,
+meaning that the renegotiation will still occur once per <code>3600</code>
+seconds. The solution is to increase --reneg-sec on both the client and
+server, or set it to <code>0</code> on one side of the connection (to
+disable), and to your chosen value on the other side.</p>
+</td></tr>
+</tbody>
+</table>
+</div>
+<div class="section" id="tls-mode-options">
+<h2>TLS Mode Options</h2>
+<p>TLS mode is the most powerful crypto mode of OpenVPN in both security
+and flexibility. TLS mode works by establishing control and data
+channels which are multiplexed over a single TCP/UDP port. OpenVPN
+initiates a TLS session over the control channel and uses it to exchange
+cipher and HMAC keys to protect the data channel. TLS mode uses a robust
+reliability layer over the UDP connection for all control channel
+communication, while the data channel, over which encrypted tunnel data
+passes, is forwarded without any mediation. The result is the best of
+both worlds: a fast data channel that forwards over UDP with only the
+overhead of encrypt, decrypt, and HMAC functions, and a control channel
+that provides all of the security features of TLS, including
+certificate-based authentication and Diffie Hellman forward secrecy.</p>
+<p>To use TLS mode, each peer that runs OpenVPN should have its own local
+certificate/key pair (<tt class="docutils literal"><span class="pre">--cert</span></tt> and <tt class="docutils literal"><span class="pre">--key</span></tt>), signed by the root
+certificate which is specified in <tt class="docutils literal"><span class="pre">--ca</span></tt>.</p>
+<p>When two OpenVPN peers connect, each presents its local certificate to
+the other. Each peer will then check that its partner peer presented a
+certificate which was signed by the master root certificate as specified
+in <tt class="docutils literal"><span class="pre">--ca</span></tt>.</p>
+<p>If that check on both peers succeeds, then the TLS negotiation will
+succeed, both OpenVPN peers will exchange temporary session keys, and
+the tunnel will begin passing data.</p>
+<p>The OpenVPN project provides a set of scripts for managing RSA
+certificates and keys: <a class="reference external" href="https://github.com/OpenVPN/easy-rsa">https://github.com/OpenVPN/easy-rsa</a></p>
+<table class="docutils option-list" frame="void" rules="none">
+<col class="option" />
+<col class="description" />
+<tbody valign="top">
+<tr><td class="option-group">
+<kbd><span class="option">--askpass <var>file</var></span></kbd></td>
+<td><p class="first">Get certificate password from console or <tt class="docutils literal">file</tt> before we daemonize.</p>
+<p>Valid syntaxes:</p>
+<pre class="literal-block">
+askpass
+askpass file
+</pre>
+<p>For the extremely security conscious, it is possible to protect your
+private key with a password. Of course this means that every time the
+OpenVPN daemon is started you must be there to type the password. The
+<tt class="docutils literal"><span class="pre">--askpass</span></tt> option allows you to start OpenVPN from the command line.
+It will query you for a password before it daemonizes. To protect a
+private key with a password you should omit the <tt class="docutils literal"><span class="pre">-nodes</span></tt> option when
+you use the <tt class="docutils literal">openssl</tt> command line tool to manage certificates and
+private keys.</p>
+<p class="last">If <tt class="docutils literal">file</tt> is specified, read the password from the first line of
+<tt class="docutils literal">file</tt>. Keep in mind that storing your password in a file to a certain
+extent invalidates the extra security provided by using an encrypted
+key.</p>
+</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--ca <var>file</var></span></kbd></td>
+<td><p class="first">Certificate authority (CA) file in .pem format, also referred to as the
+<em>root</em> certificate. This file can have multiple certificates in .pem
+format, concatenated together. You can construct your own certificate
+authority certificate and private key by using a command such as:</p>
+<pre class="literal-block">
+openssl req -nodes -new -x509 -keyout ca.key -out ca.crt
+</pre>
+<p>Then edit your openssl.cnf file and edit the <tt class="docutils literal">certificate</tt> variable to
+point to your new root certificate <tt class="docutils literal">ca.crt</tt>.</p>
+<p class="last">For testing purposes only, the OpenVPN distribution includes a sample CA
+certificate (ca.crt). Of course you should never use the test
+certificates and test keys distributed with OpenVPN in a production
+environment, since by virtue of the fact that they are distributed with
+OpenVPN, they are totally insecure.</p>
+</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--capath <var>dir</var></span></kbd></td>
+<td><p class="first">Directory containing trusted certificates (CAs and CRLs). Not available
+with mbed TLS.</p>
+<p>CAs in the capath directory are expected to be named &lt;hash&gt;.&lt;n&gt;. CRLs
+are expected to be named &lt;hash&gt;.r&lt;n&gt;. See the <tt class="docutils literal"><span class="pre">-CApath</span></tt> option of
+<tt class="docutils literal">openssl verify</tt>, and the <tt class="docutils literal"><span class="pre">-hash</span></tt> option of <tt class="docutils literal">openssl x509</tt>,
+<tt class="docutils literal">openssl crl</tt> and <tt class="docutils literal">X509_LOOKUP_hash_dir()</tt>(3)
+for more information.</p>
+<p class="last">Similar to the <tt class="docutils literal"><span class="pre">--crl-verify</span></tt> option, CRLs are not mandatory -
+OpenVPN will log the usual warning in the logs if the relevant CRL is
+missing, but the connection will be allowed.</p>
+</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--cert <var>file</var></span></kbd></td>
+<td><p class="first">Local peer's signed certificate in .pem format -- must be signed by a
+certificate authority whose certificate is in <tt class="docutils literal"><span class="pre">--ca</span> file</tt>. Each peer
+in an OpenVPN link running in TLS mode should have its own certificate
+and private key file. In addition, each certificate should have been
+signed by the key of a certificate authority whose public key resides in
+the <tt class="docutils literal"><span class="pre">--ca</span></tt> certificate authority file. You can easily make your own
+certificate authority (see above) or pay money to use a commercial
+service such as thawte.com (in which case you will be helping to finance
+the world's second space tourist :). To generate a certificate, you can
+use a command such as:</p>
+<pre class="literal-block">
+openssl req -nodes -new -keyout mycert.key -out mycert.csr
+</pre>
+<p>If your certificate authority private key lives on another machine, copy
+the certificate signing request (mycert.csr) to this other machine (this
+can be done over an insecure channel such as email). Now sign the
+certificate with a command such as:</p>
+<pre class="literal-block">
+openssl ca -out mycert.crt -in mycert.csr
+</pre>
+<p class="last">Now copy the certificate (mycert.crt) back to the peer which initially
+generated the .csr file (this can be over a public medium). Note that
+the <tt class="docutils literal">openssl ca</tt> command reads the location of the certificate
+authority key from its configuration file such as
+<code>/usr/share/ssl/openssl.cnf</code> -- note also that for certificate
+authority functions, you must set up the files <code>index.txt</code> (may be
+empty) and <code>serial</code> (initialize to <code>01</code>).</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--crl-verify <var>args</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Check peer certificate against a Certificate Revocation List.</p>
+<p>Valid syntax:</p>
+<pre class="literal-block">
+crl-verify file/directory flag
+</pre>
+<p>Examples:</p>
+<pre class="literal-block">
+crl-verify crl-file.pem
+crl-verify /etc/openvpn/crls dir
+</pre>
+<p>A CRL (certificate revocation list) is used when a particular key is
+compromised but when the overall PKI is still intact.</p>
+<p>Suppose you had a PKI consisting of a CA, root certificate, and a number
+of client certificates. Suppose a laptop computer containing a client
+key and certificate was stolen. By adding the stolen certificate to the
+CRL file, you could reject any connection which attempts to use it,
+while preserving the overall integrity of the PKI.</p>
+<p>The only time when it would be necessary to rebuild the entire PKI from
+scratch would be if the root certificate key itself was compromised.</p>
+<p>The option is not mandatory - if the relevant CRL is missing, OpenVPN
+will log a warning in the logs - e.g.</p>
+<pre class="literal-block">
+VERIFY WARNING: depth=0, unable to get certificate CRL
+</pre>
+<p>but the connection will be allowed. If the optional <code>dir</code> flag
+is specified, enable a different mode where the <tt class="docutils literal"><span class="pre">crl-verify</span></tt> is
+pointed at a directory containing files named as revoked serial numbers
+(the files may be empty, the contents are never read). If a client
+requests a connection, where the client certificate serial number
+(decimal string) is the name of a file present in the directory, it will
+be rejected.</p>
+<dl class="last docutils">
+<dt><em>Note:</em></dt>
+<dd>As the crl file (or directory) is read every time a peer
+connects, if you are dropping root privileges with
+<tt class="docutils literal"><span class="pre">--user</span></tt>, make sure that this user has sufficient
+privileges to read the file.</dd>
+</dl>
+</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--dh <var>file</var></span></kbd></td>
+<td><p class="first">File containing Diffie Hellman parameters in .pem format (required for
+<tt class="docutils literal"><span class="pre">--tls-server</span></tt> only).</p>
+<p>Set <tt class="docutils literal">file</tt> to <code>none</code> to disable Diffie Hellman key exchange (and
+use ECDH only). Note that this requires peers to be using an SSL library
+that supports ECDH TLS cipher suites (e.g. OpenSSL 1.0.1+, or
+mbed TLS 2.0+).</p>
+<p class="last">Use <tt class="docutils literal">openssl dhparam <span class="pre">-out</span> dh2048.pem 2048</tt> to generate 2048-bit DH
+parameters. Diffie Hellman parameters may be considered public.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--ecdh-curve <var>name</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Specify the curve to use for elliptic curve Diffie Hellman. Available
+curves can be listed with <tt class="docutils literal"><span class="pre">--show-curves</span></tt>. The specified curve will
+only be used for ECDH TLS-ciphers.</p>
+<p class="last">This option is not supported in mbed TLS builds of OpenVPN.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--extra-certs <var>file</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Specify a <tt class="docutils literal">file</tt> containing one or more PEM certs (concatenated
+together) that complete the local certificate chain.</p>
+<p class="last">This option is useful for &quot;split&quot; CAs, where the CA for server certs is
+different than the CA for client certs. Putting certs in this file
+allows them to be used to complete the local certificate chain without
+trusting them to verify the peer-submitted certificate, as would be the
+case if the certs were placed in the <tt class="docutils literal">ca</tt> file.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--hand-window <var>n</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td>Handshake Window -- the TLS-based key exchange must finalize within
+<tt class="docutils literal">n</tt> seconds of handshake initiation by any peer (default <code>60</code>
+seconds). If the handshake fails we will attempt to reset our connection
+with our peer and try again. Even in the event of handshake failure we
+will still use our expiring key for up to <tt class="docutils literal"><span class="pre">--tran-window</span></tt> seconds to
+maintain continuity of transmission of tunnel data.</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--key <var>file</var></span></kbd></td>
+<td>Local peer's private key in .pem format. Use the private key which was
+generated when you built your peer's certificate (see <tt class="docutils literal"><span class="pre">--cert</span> file</tt>
+above).</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--pkcs12 <var>file</var></span></kbd></td>
+<td>Specify a PKCS #12 file containing local private key, local certificate,
+and root CA certificate. This option can be used instead of <tt class="docutils literal"><span class="pre">--ca</span></tt>,
+<tt class="docutils literal"><span class="pre">--cert</span></tt>, and <tt class="docutils literal"><span class="pre">--key</span></tt>. Not available with mbed TLS.</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--remote-cert-eku <var>oid</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Require that peer certificate was signed with an explicit <em>extended key
+usage</em>.</p>
+<p>This is a useful security option for clients, to ensure that the host
+they connect to is a designated server.</p>
+<p class="last">The extended key usage should be encoded in <em>oid notation</em>, or <em>OpenSSL
+symbolic representation</em>.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--remote-cert-ku <var>key-usage</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Require that peer certificate was signed with an explicit
+<tt class="docutils literal"><span class="pre">key-usage</span></tt>.</p>
+<p>If present in the certificate, the <code>keyUsage</code> value is validated by
+the TLS library during the TLS handshake. Specifying this option without
+arguments requires this extension to be present (so the TLS library will
+verify it).</p>
+<p>If <tt class="docutils literal"><span class="pre">key-usage</span></tt> is a list of usage bits, the <code>keyUsage</code> field
+must have <em>at least</em> the same bits set as the bits in <em>one of</em> the values
+supplied in the <tt class="docutils literal"><span class="pre">key-usage</span></tt> list.</p>
+<p>The <tt class="docutils literal"><span class="pre">key-usage</span></tt> values in the list must be encoded in hex, e.g.</p>
+<pre class="last literal-block">
+remote-cert-ku a0
+</pre>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--remote-cert-tls <var>type</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Require that peer certificate was signed with an explicit <em>key usage</em>
+and <em>extended key usage</em> based on RFC3280 TLS rules.</p>
+<p>Valid syntaxes:</p>
+<pre class="literal-block">
+remote-cert-tls server
+remote-cert-tls client
+</pre>
+<p>This is a useful security option for clients, to ensure that the host
+they connect to is a designated server. Or the other way around; for a
+server to verify that only hosts with a client certificate can connect.</p>
+<p>The <tt class="docutils literal"><span class="pre">--remote-cert-tls</span> client</tt> option is equivalent to</p>
+<pre class="literal-block">
+remote-cert-ku
+remote-cert-eku &quot;TLS Web Client Authentication&quot;
+</pre>
+<p>The <tt class="docutils literal"><span class="pre">--remote-cert-tls</span> server</tt> option is equivalent to</p>
+<pre class="literal-block">
+remote-cert-ku
+remote-cert-eku &quot;TLS Web Server Authentication&quot;
+</pre>
+<p class="last">This is an important security precaution to protect against a
+man-in-the-middle attack where an authorized client attempts to connect
+to another client by impersonating the server. The attack is easily
+prevented by having clients verify the server certificate using any one
+of <tt class="docutils literal"><span class="pre">--remote-cert-tls</span></tt>, <tt class="docutils literal"><span class="pre">--verify-x509-name</span></tt>, or <tt class="docutils literal"><span class="pre">--tls-verify</span></tt>.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--tls-auth <var>args</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Add an additional layer of HMAC authentication on top of the TLS control
+channel to mitigate DoS attacks and attacks on the TLS stack.</p>
+<p>Valid syntaxes:</p>
+<pre class="literal-block">
+tls-auth file
+tls-auth file 0
+tls-auth file 1
+</pre>
+<p>In a nutshell, <tt class="docutils literal"><span class="pre">--tls-auth</span></tt> enables a kind of &quot;HMAC firewall&quot; on
+OpenVPN's TCP/UDP port, where TLS control channel packets bearing an
+incorrect HMAC signature can be dropped immediately without response.</p>
+<p><tt class="docutils literal">file</tt> (required) is a file in OpenVPN static key format which can be
+generated by <tt class="docutils literal"><span class="pre">--genkey</span></tt>.</p>
+<p>Older versions (up to OpenVPN 2.3) supported a freeform passphrase file.
+This is no longer supported in newer versions (v2.4+).</p>
+<p>See the <tt class="docutils literal"><span class="pre">--secret</span></tt> option for more information on the optional
+<tt class="docutils literal">direction</tt> parameter.</p>
+<p><tt class="docutils literal"><span class="pre">--tls-auth</span></tt> is recommended when you are running OpenVPN in a mode
+where it is listening for packets from any IP address, such as when
+<tt class="docutils literal"><span class="pre">--remote</span></tt> is not specified, or <tt class="docutils literal"><span class="pre">--remote</span></tt> is specified with
+<tt class="docutils literal"><span class="pre">--float</span></tt>.</p>
+<p>The rationale for this feature is as follows. TLS requires a
+multi-packet exchange before it is able to authenticate a peer. During
+this time before authentication, OpenVPN is allocating resources (memory
+and CPU) to this potential peer. The potential peer is also exposing
+many parts of OpenVPN and the OpenSSL library to the packets it is
+sending. Most successful network attacks today seek to either exploit
+bugs in programs (such as buffer overflow attacks) or force a program to
+consume so many resources that it becomes unusable. Of course the first
+line of defense is always to produce clean, well-audited code. OpenVPN
+has been written with buffer overflow attack prevention as a top
+priority. But as history has shown, many of the most widely used network
+applications have, from time to time, fallen to buffer overflow attacks.</p>
+<p>So as a second line of defense, OpenVPN offers this special layer of
+authentication on top of the TLS control channel so that every packet on
+the control channel is authenticated by an HMAC signature and a unique
+ID for replay protection. This signature will also help protect against
+DoS (Denial of Service) attacks. An important rule of thumb in reducing
+vulnerability to DoS attacks is to minimize the amount of resources a
+potential, but as yet unauthenticated, client is able to consume.</p>
+<p><tt class="docutils literal"><span class="pre">--tls-auth</span></tt> does this by signing every TLS control channel packet
+with an HMAC signature, including packets which are sent before the TLS
+level has had a chance to authenticate the peer. The result is that
+packets without the correct signature can be dropped immediately upon
+reception, before they have a chance to consume additional system
+resources such as by initiating a TLS handshake. <tt class="docutils literal"><span class="pre">--tls-auth</span></tt> can be
+strengthened by adding the <tt class="docutils literal"><span class="pre">--replay-persist</span></tt> option which will keep
+OpenVPN's replay protection state in a file so that it is not lost
+across restarts.</p>
+<p>It should be emphasized that this feature is optional and that the key
+file used with <tt class="docutils literal"><span class="pre">--tls-auth</span></tt> gives a peer nothing more than the power
+to initiate a TLS handshake. It is not used to encrypt or authenticate
+any tunnel data.</p>
+<p class="last">Use <tt class="docutils literal"><span class="pre">--tls-crypt</span></tt> instead if you want to use the key file to not only
+authenticate, but also encrypt the TLS control channel.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--tls-groups <var>list</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">A list of allowable groups/curves in order of preference.</p>
+<p>Set the allowed elliptic curves/groups for the TLS session.
+These groups are allowed to be used in signatures and key exchange.</p>
+<p>mbedTLS currently allows all known curves per default.</p>
+<p>OpenSSL 1.1+ restricts the list per default to</p>
+<pre class="literal-block">
+&quot;X25519:secp256r1:X448:secp521r1:secp384r1&quot;.
+</pre>
+<p>If you use certificates that use non-standard curves, you
+might need to add them here. If you do not force the ecdh curve
+by using <tt class="docutils literal"><span class="pre">--ecdh-curve</span></tt>, the groups for ecdh will also be picked
+from this list.</p>
+<p>OpenVPN maps the curve name <cite>secp256r1</cite> to <cite>prime256v1</cite> to allow
+specifying the same tls-groups option for mbedTLS and OpenSSL.</p>
+<p class="last">Warning: this option not only affects elliptic curve certificates
+but also the key exchange in TLS 1.3 and using this option improperly
+will disable TLS 1.3.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--tls-cert-profile <var>profile</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Set the allowed cryptographic algorithms for certificates according to
+<tt class="docutils literal">profile</tt>.</p>
+<p>The following profiles are supported:</p>
+<dl class="docutils">
+<dt><code>legacy</code> (default)</dt>
+<dd>SHA1 and newer, RSA 2048-bit+, any elliptic curve.</dd>
+<dt><code>preferred</code></dt>
+<dd>SHA2 and newer, RSA 2048-bit+, any elliptic curve.</dd>
+<dt><code>suiteb</code></dt>
+<dd>SHA256/SHA384, ECDSA with P-256 or P-384.</dd>
+</dl>
+<p>This option is only fully supported for mbed TLS builds. OpenSSL builds
+use the following approximation:</p>
+<dl class="docutils">
+<dt><code>legacy</code> (default)</dt>
+<dd>sets &quot;security level 1&quot;</dd>
+<dt><code>preferred</code></dt>
+<dd>sets &quot;security level 2&quot;</dd>
+<dt><code>suiteb</code></dt>
+<dd>sets &quot;security level 3&quot; and <tt class="docutils literal"><span class="pre">--tls-cipher</span> &quot;SUITEB128&quot;</tt>.</dd>
+</dl>
+<p class="last">OpenVPN will migrate to 'preferred' as default in the future. Please
+ensure that your keys already comply.</p>
+</td></tr>
+</tbody>
+</table>
+<dl class="docutils">
+<dt><em>WARNING:</em> <tt class="docutils literal"><span class="pre">--tls-ciphers</span></tt>, <tt class="docutils literal"><span class="pre">--tls-ciphersuites</span></tt> and <tt class="docutils literal"><span class="pre">tls-groups</span></tt></dt>
+<dd>These options are expert features, which - if used correctly - can
+improve the security of your VPN connection. But it is also easy to
+unwittingly use them to carefully align a gun with your foot, or just
+break your connection. Use with care!</dd>
+</dl>
+<table class="docutils option-list" frame="void" rules="none">
+<col class="option" />
+<col class="description" />
+<tbody valign="top">
+<tr><td class="option-group">
+<kbd><span class="option">--tls-cipher <var>l</var></span></kbd></td>
+<td><p class="first">A list <tt class="docutils literal">l</tt> of allowable TLS ciphers delimited by a colon (&quot;<code>:</code>&quot;).</p>
+<p>These setting can be used to ensure that certain cipher suites are used
+(or not used) for the TLS connection. OpenVPN uses TLS to secure the
+control channel, over which the keys that are used to protect the actual
+VPN traffic are exchanged.</p>
+<p>The supplied list of ciphers is (after potential OpenSSL/IANA name
+translation) simply supplied to the crypto library. Please see the
+OpenSSL and/or mbed TLS documentation for details on the cipher list
+interpretation.</p>
+<p>For OpenSSL, the <tt class="docutils literal"><span class="pre">--tls-cipher</span></tt> is used for TLS 1.2 and below.</p>
+<p>Use <tt class="docutils literal"><span class="pre">--show-tls</span></tt> to see a list of TLS ciphers supported by your crypto
+library.</p>
+<p>The default for <tt class="docutils literal"><span class="pre">--tls-cipher</span></tt> is to use mbed TLS's default cipher list
+when using mbed TLS or
+<code>DEFAULT:!EXP:!LOW:!MEDIUM:!kDH:!kECDH:!DSS:!PSK:!SRP:!kRSA</code> when
+using OpenSSL.</p>
+<p class="last">The default for <cite>--tls-ciphersuites</cite> is to use the crypto library's
+default.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--tls-ciphersuites <var>l</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td>Same as <tt class="docutils literal"><span class="pre">--tls-cipher</span></tt> but for TLS 1.3 and up. mbed TLS has no
+TLS 1.3 support yet and only the <tt class="docutils literal"><span class="pre">--tls-cipher</span></tt> setting is used.</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--tls-client</span></kbd></td>
+<td>Enable TLS and assume client role during TLS handshake.</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--tls-crypt <var>keyfile</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Encrypt and authenticate all control channel packets with the key from
+<tt class="docutils literal">keyfile</tt>. (See <tt class="docutils literal"><span class="pre">--tls-auth</span></tt> for more background.)</p>
+<p>Encrypting (and authenticating) control channel packets:</p>
+<ul class="simple">
+<li>provides more privacy by hiding the certificate used for the TLS
+connection,</li>
+<li>makes it harder to identify OpenVPN traffic as such,</li>
+<li>provides &quot;poor-man's&quot; post-quantum security, against attackers who will
+never know the pre-shared key (i.e. no forward secrecy).</li>
+</ul>
+<p>In contrast to <tt class="docutils literal"><span class="pre">--tls-auth</span></tt>, <tt class="docutils literal"><span class="pre">--tls-crypt</span></tt> does <em>not</em> require the
+user to set <tt class="docutils literal"><span class="pre">--key-direction</span></tt>.</p>
+<p><strong>Security Considerations</strong></p>
+<p>All peers use the same <tt class="docutils literal"><span class="pre">--tls-crypt</span></tt> pre-shared group key to
+authenticate and encrypt control channel messages. To ensure that IV
+collisions remain unlikely, this key should not be used to encrypt more
+than 2^48 client-to-server or 2^48 server-to-client control channel
+messages. A typical initial negotiation is about 10 packets in each
+direction. Assuming both initial negotiation and renegotiations are at
+most 2^16 (65536) packets (to be conservative), and (re)negotiations
+happen each minute for each user (24/7), this limits the tls-crypt key
+lifetime to 8171 years divided by the number of users. So a setup with
+1000 users should rotate the key at least once each eight years. (And a
+setup with 8000 users each year.)</p>
+<p>If IV collisions were to occur, this could result in the security of
+<tt class="docutils literal"><span class="pre">--tls-crypt</span></tt> degrading to the same security as using <tt class="docutils literal"><span class="pre">--tls-auth</span></tt>.
+That is, the control channel still benefits from the extra protection
+against active man-in-the-middle-attacks and DoS attacks, but may no
+longer offer extra privacy and post-quantum security on top of what TLS
+itself offers.</p>
+<p class="last">For large setups or setups where clients are not trusted, consider using
+<tt class="docutils literal"><span class="pre">--tls-crypt-v2</span></tt> instead. That uses per-client unique keys, and
+thereby improves the bounds to 'rotate a client key at least once per
+8000 years'.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--tls-crypt-v2 <var>keyfile</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Use client-specific tls-crypt keys.</p>
+<p>For clients, <tt class="docutils literal">keyfile</tt> is a client-specific tls-crypt key. Such a key
+can be generated using the <code>--genkey tls-crypt-v2-client</code> option.</p>
+<p>For servers, <tt class="docutils literal">keyfile</tt> is used to unwrap client-specific keys supplied
+by the client during connection setup. This key must be the same as the
+key used to generate the client-specific key (see <code>--genkey
+tls-crypt-v2-client</code>).</p>
+<p class="last">On servers, this option can be used together with the <tt class="docutils literal"><span class="pre">--tls-auth</span></tt> or
+<tt class="docutils literal"><span class="pre">--tls-crypt</span></tt> option. In that case, the server will detect whether the
+client is using client-specific keys, and automatically select the right
+mode.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--tls-crypt-v2-verify <var>cmd</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Run command <tt class="docutils literal">cmd</tt> to verify the metadata of the client-specific
+tls-crypt-v2 key of a connecting client. This allows server
+administrators to reject client connections, before exposing the TLS
+stack (including the notoriously dangerous X.509 and ASN.1 stacks) to
+the connecting client.</p>
+<p>OpenVPN supplies the following environment variables to the command:</p>
+<ul class="simple">
+<li><code>script_type</code> is set to <code>tls-crypt-v2-verify</code></li>
+<li><code>metadata_type</code> is set to <code>0</code> if the metadata was user
+supplied, or <code>1</code> if it's a 64-bit unix timestamp representing
+the key creation time.</li>
+<li><code>metadata_file</code> contains the filename of a temporary file that
+contains the client metadata.</li>
+</ul>
+<p class="last">The command can reject the connection by exiting with a non-zero exit
+code.</p>
+</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--tls-exit</span></kbd></td>
+<td>Exit on TLS negotiation failure.</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--tls-export-cert <var>directory</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td>Store the certificates the clients use upon connection to this
+directory. This will be done before <tt class="docutils literal"><span class="pre">--tls-verify</span></tt> is called. The
+certificates will use a temporary name and will be deleted when the
+tls-verify script returns. The file name used for the certificate is
+available via the <tt class="docutils literal">peer_cert</tt> environment variable.</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--tls-server</span></kbd></td>
+<td>Enable TLS and assume server role during TLS handshake. Note that
+OpenVPN is designed as a peer-to-peer application. The designation of
+client or server is only for the purpose of negotiating the TLS control
+channel.</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--tls-timeout <var>n</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td>Packet retransmit timeout on TLS control channel if no acknowledgment
+from remote within <tt class="docutils literal">n</tt> seconds (default <code>2</code>). When OpenVPN sends
+a control packet to its peer, it will expect to receive an
+acknowledgement within <tt class="docutils literal">n</tt> seconds or it will retransmit the packet,
+subject to a TCP-like exponential backoff algorithm. This parameter only
+applies to control channel packets. Data channel packets (which carry
+encrypted tunnel data) are never acknowledged, sequenced, or
+retransmitted by OpenVPN because the higher level network protocols
+running on top of the tunnel such as TCP expect this role to be left to
+them.</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--tls-version-min <var>args</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Sets the minimum TLS version we will accept from the peer (default is
+&quot;1.0&quot;).</p>
+<p>Valid syntax:</p>
+<pre class="literal-block">
+tls-version-min version ['or-highest']
+</pre>
+<p class="last">Examples for version include <code>1.0</code>, <code>1.1</code>, or <code>1.2</code>. If
+<code>or-highest</code> is specified and version is not recognized, we will
+only accept the highest TLS version supported by the local SSL
+implementation.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--tls-version-max <var>version</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td>Set the maximum TLS version we will use (default is the highest version
+supported). Examples for version include <code>1.0</code>, <code>1.1</code>, or
+<code>1.2</code>.</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--verify-hash <var>args</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Specify SHA1 or SHA256 fingerprint for level-1 cert.</p>
+<p>Valid syntax:</p>
+<pre class="literal-block">
+verify-hash hash [algo]
+</pre>
+<p>The level-1 cert is the CA (or intermediate cert) that signs the leaf
+certificate, and is one removed from the leaf certificate in the
+direction of the root. When accepting a connection from a peer, the
+level-1 cert fingerprint must match <tt class="docutils literal">hash</tt> or certificate verification
+will fail. Hash is specified as XX:XX:... For example:</p>
+<pre class="literal-block">
+AD:B0:95:D8:09:C8:36:45:12:A9:89:C8:90:09:CB:13:72:A6:AD:16
+</pre>
+<p class="last">The <tt class="docutils literal">algo</tt> flag can be either <code>SHA1</code> or <code>SHA256</code>. If not
+provided, it defaults to <code>SHA1</code>.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--verify-x509-name <var>args</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Accept connections only if a host's X.509 name is equal to <strong>name.</strong> The
+remote host must also pass all other tests of verification.</p>
+<p>Valid syntax:</p>
+<pre class="literal-block">
+verify-x509 name type
+</pre>
+<p>Which X.509 name is compared to <tt class="docutils literal">name</tt> depends on the setting of type.
+<tt class="docutils literal">type</tt> can be <code>subject</code> to match the complete subject DN
+(default), <code>name</code> to match a subject RDN or <code>name-prefix</code> to
+match a subject RDN prefix. Which RDN is verified as name depends on the
+<tt class="docutils literal"><span class="pre">--x509-username-field</span></tt> option. But it defaults to the common name
+(CN), e.g. a certificate with a subject DN</p>
+<pre class="literal-block">
+C=KG, ST=NA, L=Bishkek, CN=Server-1
+</pre>
+<p>would be matched by:</p>
+<pre class="literal-block">
+verify-x509-name 'C=KG, ST=NA, L=Bishkek, CN=Server-1'
+verify-x509-name Server-1 name
+verify-x509-name Server- name-prefix
+</pre>
+<p>The last example is useful if you want a client to only accept
+connections to <code>Server-1</code>, <code>Server-2</code>, etc.</p>
+<p><tt class="docutils literal"><span class="pre">--verify-x509-name</span></tt> is a useful replacement for the <tt class="docutils literal"><span class="pre">--tls-verify</span></tt>
+option to verify the remote host, because <tt class="docutils literal"><span class="pre">--verify-x509-name</span></tt> works
+in a <tt class="docutils literal"><span class="pre">--chroot</span></tt> environment without any dependencies.</p>
+<p>Using a name prefix is a useful alternative to managing a CRL
+(Certificate Revocation List) on the client, since it allows the client
+to refuse all certificates except for those associated with designated
+servers.</p>
+<dl class="last docutils">
+<dt><em>NOTE:</em></dt>
+<dd>Test against a name prefix only when you are using OpenVPN
+with a custom CA certificate that is under your control. Never use
+this option with type <code>name-prefix</code> when your client
+certificates are signed by a third party, such as a commercial
+web CA.</dd>
+</dl>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--x509-track <var>attribute</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td>Save peer X509 <strong>attribute</strong> value in environment for use by plugins and
+management interface. Prepend a <code>+</code> to <tt class="docutils literal">attribute</tt> to save values
+from full cert chain. Values will be encoded as
+<code>X509_&lt;depth&gt;_&lt;attribute&gt;=&lt;value&gt;</code>. Multiple <tt class="docutils literal"><span class="pre">--x509-track</span></tt>
+options can be defined to track multiple attributes.</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--x509-username-field <var>args</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Field in the X.509 certificate subject to be used as the username
+(default <code>CN</code>).</p>
+<p>Valid syntax:</p>
+<pre class="literal-block">
+x509-username-field [ext:]fieldname
+</pre>
+<p>Typically, this option is specified with <strong>fieldname</strong> as
+either of the following:</p>
+<pre class="literal-block">
+x509-username-field emailAddress
+x509-username-field ext:subjectAltName
+</pre>
+<p>The first example uses the value of the <code>emailAddress</code> attribute
+in the certificate's Subject field as the username. The second example
+uses the <code>ext:</code> prefix to signify that the X.509 extension
+<tt class="docutils literal">fieldname</tt> <code>subjectAltName</code> be searched for an rfc822Name
+(email) field to be used as the username. In cases where there are
+multiple email addresses in <code>ext:fieldname</code>, the last occurrence
+is chosen.</p>
+<p>When this option is used, the <tt class="docutils literal"><span class="pre">--verify-x509-name</span></tt> option will match
+against the chosen <tt class="docutils literal">fieldname</tt> instead of the Common Name.</p>
+<p>Only the <code>subjectAltName</code> and <code>issuerAltName</code> X.509
+extensions are supported.</p>
+<p class="last"><strong>Please note:</strong> This option has a feature which will convert an
+all-lowercase <tt class="docutils literal">fieldname</tt> to uppercase characters, e.g.,
+<code>ou</code> -&gt; <code>OU</code>. A mixed-case <tt class="docutils literal">fieldname</tt> or one having the
+<code>ext:</code> prefix will be left as-is. This automatic upcasing feature is
+deprecated and will be removed in a future release.</p>
+</td></tr>
+</tbody>
+</table>
+</div>
+<div class="section" id="pkcs-11-smartcard-options">
+<h2>PKCS#11 / SmartCard options</h2>
+<table class="docutils option-list" frame="void" rules="none">
+<col class="option" />
+<col class="description" />
+<tbody valign="top">
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--pkcs11-cert-private <var>args</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Set if access to certificate object should be performed after login.
+Every provider has its own setting.</p>
+<p>Valid syntaxes:</p>
+<pre class="last literal-block">
+pkcs11-cert-private 0
+pkcs11-cert-private 1
+</pre>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--pkcs11-id <var>name</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td>Specify the serialized certificate id to be used. The id can be gotten
+by the standalone <tt class="docutils literal"><span class="pre">--show-pkcs11-ids</span></tt> option.</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--pkcs11-id-management</span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td>Acquire PKCS#11 id from management interface. In this case a
+<code>NEED-STR 'pkcs11-id-request'</code> real-time message will be triggered,
+application may use pkcs11-id-count command to retrieve available number of
+certificates, and pkcs11-id-get command to retrieve certificate id and
+certificate body.</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--pkcs11-pin-cache <var>seconds</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td>Specify how many seconds the PIN can be cached, the default is until the
+token is removed.</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--pkcs11-private-mode <var>mode</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Specify which method to use in order to perform private key operations.
+A different mode can be specified for each provider. Mode is encoded as
+hex number, and can be a mask one of the following:</p>
+<p><code>0</code> (default) Try to determine automatically.</p>
+<p><code>1</code> Use sign.</p>
+<p><code>2</code> Use sign recover.</p>
+<p><code>4</code> Use decrypt.</p>
+<p class="last"><code>8</code> Use unwrap.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--pkcs11-protected-authentication <var>args</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Use PKCS#11 protected authentication path, useful for biometric and
+external keypad devices. Every provider has its own setting.</p>
+<p>Valid syntaxes:</p>
+<pre class="last literal-block">
+pkcs11-protected-authentication 0
+pkcs11-protected-authentication 1
+</pre>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--pkcs11-providers <var>provider</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Specify an RSA Security Inc. PKCS #11 Cryptographic Token Interface
+(Cryptoki) providers to load. This option can be used instead of
+<tt class="docutils literal"><span class="pre">--cert</span></tt>, <tt class="docutils literal"><span class="pre">--key</span></tt> and <tt class="docutils literal"><span class="pre">--pkcs12</span></tt>.</p>
+<p class="last">If p11-kit is present on the system, its <code>p11-kit-proxy.so</code> module
+will be loaded by default if either the <tt class="docutils literal"><span class="pre">--pkcs11-id</span></tt> or
+<tt class="docutils literal"><span class="pre">--pkcs11-id-management</span></tt> options are specified without
+<tt class="docutils literal"><span class="pre">--pkcs11-provider</span></tt> being given.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--show-pkcs11-ids <var>args</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">(Standalone) Show PKCS#11 token object list.</p>
+<p>Valid syntax:</p>
+<pre class="literal-block">
+show-pkcs11 [provider] [cert_private]
+</pre>
+<p>Specify <tt class="docutils literal">cert_private</tt> as <code>1</code> if certificates are stored as
+private objects.</p>
+<p>If <em>p11-kit</em> is present on the system, the <tt class="docutils literal">provider</tt> argument is
+optional; if omitted the default <code>p11-kit-proxy.so</code> module will be
+queried.</p>
+<p class="last"><tt class="docutils literal"><span class="pre">--verb</span></tt> option can be used BEFORE this option to produce debugging
+information.</p>
+</td></tr>
+</tbody>
+</table>
+</div>
+</div>
+<div class="section" id="data-channel-cipher-negotiation">
+<h1>Data channel cipher negotiation</h1>
+<p>OpenVPN 2.4 and higher have the capability to negotiate the data cipher that
+is used to encrypt data packets. This section describes the mechanism in more detail and the
+different backwards compatibility mechanism with older server and clients.</p>
+<div class="section" id="openvpn-2-5-and-higher-behaviour">
+<h2>OpenVPN 2.5 and higher behaviour</h2>
+<p>When both client and server are at least running OpenVPN 2.5, that the order of
+the ciphers of the server's <tt class="docutils literal"><span class="pre">--data-ciphers</span></tt> is used to pick the the data cipher.
+That means that the first cipher in that list that is also in the client's
+<tt class="docutils literal"><span class="pre">--data-ciphers</span></tt> list is chosen. If no common cipher is found the client is rejected
+with a AUTH_FAILED message (as seen in client log):</p>
+<blockquote>
+AUTH: Received control message: AUTH_FAILED,Data channel cipher negotiation failed (no shared cipher)</blockquote>
+<p>OpenVPN 2.5 will only allow the ciphers specified in <tt class="docutils literal"><span class="pre">--data-ciphers</span></tt>. To ensure
+backwards compatibility also if a cipher is specified using the <tt class="docutils literal"><span class="pre">--cipher</span></tt> option
+it is automatically added to this list. If both options are unset the default is
+<code>AES-256-GCM:AES-128-GCM</code>.</p>
+</div>
+<div class="section" id="openvpn-2-4-clients">
+<h2>OpenVPN 2.4 clients</h2>
+<p>The negotiation support in OpenVPN 2.4 was the first iteration of the implementation
+and still had some quirks. Its main goal was &quot;upgrade to AES-256-GCM when possible&quot;.
+An OpenVPN 2.4 client that is built against a crypto library that supports AES in GCM
+mode and does not have <tt class="docutils literal"><span class="pre">--ncp-disable</span></tt> will always announce support for
+<cite>AES-256-GCM</cite> and <cite>AES-128-GCM</cite> to a server by sending <code>IV_NCP=2</code>.</p>
+<p>This only causes a problem if <tt class="docutils literal"><span class="pre">--ncp-ciphers</span></tt> option has been changed from the
+default of <code>AES-256-GCM:AES-128-GCM</code> to a value that does not include
+these two ciphers. When a OpenVPN servers try to use <cite>AES-256-GCM</cite> or
+<cite>AES-128-GCM</cite> the connection will then fail. It is therefore recommended to
+always have the <cite>AES-256-GCM</cite> and <cite>AES-128-GCM</cite> ciphers to the <tt class="docutils literal"><span class="pre">--ncp-ciphers</span></tt>
+options to avoid this behaviour.</p>
+</div>
+<div class="section" id="openvpn-3-clients">
+<h2>OpenVPN 3 clients</h2>
+<p>Clients based on the OpenVPN 3.x library (<a class="reference external" href="https://github.com/openvpn/openvpn3/">https://github.com/openvpn/openvpn3/</a>)
+do not have a configurable <tt class="docutils literal"><span class="pre">--ncp-ciphers</span></tt> or <tt class="docutils literal"><span class="pre">--data-ciphers</span></tt> option. Instead
+these clients will announce support for all their supported AEAD ciphers
+(<cite>AES-256-GCM</cite>, <cite>AES-128-GCM</cite> and in newer versions also <cite>Chacha20-Poly1305</cite>).</p>
+<p>To support OpenVPN 3.x based clients at least one of these ciphers needs to be
+included in the server's <tt class="docutils literal"><span class="pre">--data-ciphers</span></tt> option.</p>
+</div>
+<div class="section" id="openvpn-2-3-and-older-clients-and-clients-with-ncp-disable">
+<h2>OpenVPN 2.3 and older clients (and clients with <tt class="docutils literal"><span class="pre">--ncp-disable</span></tt>)</h2>
+<p>When a client without cipher negotiation support connects to a server the
+cipher specified with the <tt class="docutils literal"><span class="pre">--cipher</span></tt> option in the client configuration
+must be included in the <tt class="docutils literal"><span class="pre">--data-ciphers</span></tt> option of the server to allow
+the client to connect. Otherwise the client will be sent the <tt class="docutils literal">AUTH_FAILED</tt>
+message that indicates no shared cipher.</p>
+<p>If the client is 2.3 or older and has been configured with the
+<tt class="docutils literal"><span class="pre">--enable-small</span></tt> <code>./configure</code> argument, using
+<tt class="docutils literal"><span class="pre">data-ciphers-fallback</span> cipher</tt> in the server config file with the explicit
+cipher used by the client is necessary.</p>
+</div>
+<div class="section" id="openvpn-2-4-server">
+<h2>OpenVPN 2.4 server</h2>
+<p>When a client indicates support for <cite>AES-128-GCM</cite> and <cite>AES-256-GCM</cite>
+(with <tt class="docutils literal">IV_NCP=2</tt>) an OpenVPN 2.4 server will send the first
+cipher of the <tt class="docutils literal"><span class="pre">--ncp-ciphers</span></tt> to the OpenVPN client regardless of what
+the cipher is. To emulate the behaviour of an OpenVPN 2.4 client as close
+as possible and have compatibility to a setup that depends on this quirk,
+adding <cite>AES-128-GCM</cite> and <cite>AES-256-GCM</cite> to the client's <tt class="docutils literal"><span class="pre">--data-ciphers</span></tt>
+option is required. OpenVPN 2.5+ will only announce the <tt class="docutils literal">IV_NCP=2</tt> flag if
+those ciphers are present.</p>
+</div>
+<div class="section" id="openvpn-2-3-and-older-servers-and-servers-with-ncp-disable">
+<h2>OpenVPN 2.3 and older servers (and servers with <tt class="docutils literal"><span class="pre">--ncp-disable</span></tt>)</h2>
+<p>The cipher used by the server must be included in <tt class="docutils literal"><span class="pre">--data-ciphers</span></tt> to
+allow the client connecting to a server without cipher negotiation
+support.
+(For compatibility OpenVPN 2.5 will also accept the cipher set with
+<tt class="docutils literal"><span class="pre">--cipher</span></tt>)</p>
+<p>If the server is 2.3 or older and has been configured with the
+<tt class="docutils literal"><span class="pre">--enable-small</span></tt> <code>./configure</code> argument, adding
+<tt class="docutils literal"><span class="pre">data-ciphers-fallback</span> cipher</tt> to the client config with the explicit
+cipher used by the server is necessary.</p>
+</div>
+<div class="section" id="blowfish-in-cbc-mode-bf-cbc-deprecation">
+<h2>Blowfish in CBC mode (BF-CBC) deprecation</h2>
+<p>The <tt class="docutils literal"><span class="pre">--cipher</span></tt> option defaulted to <tt class="docutils literal"><span class="pre">BF-CBC</span></tt> in OpenVPN 2.4 and older
+version. The default was never changed to ensure backwards compatibility.
+In OpenVPN 2.5 this behaviour has now been changed so that if the <tt class="docutils literal"><span class="pre">--cipher</span></tt>
+is not explicitly set it does not allow the weak <tt class="docutils literal"><span class="pre">BF-CBC</span></tt> cipher any more
+and needs to explicitly added as <tt class="docutils literal"><span class="pre">--cipher</span> <span class="pre">BFC-CBC</span></tt> or added to
+<tt class="docutils literal"><span class="pre">--data-ciphers</span></tt>.</p>
+<p>We strongly recommend to switching away from BF-CBC to a
+more secure cipher as soon as possible instead.</p>
+</div>
+</div>
+<div class="section" id="network-configuration">
+<h1>NETWORK CONFIGURATION</h1>
+<p>OpenVPN consists of two sides of network configuration. One side is the
+<em>link</em> between the local and remote side, the other side is the <em>virtual
+network adapter</em> (tun/tap device).</p>
+<div class="section" id="link-options">
+<h2>Link Options</h2>
+<p>This link options section covers options related to the connection between
+the local and the remote host.</p>
+<table class="docutils option-list" frame="void" rules="none">
+<col class="option" />
+<col class="description" />
+<tbody valign="top">
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--bind <var>keywords</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Bind to local address and port. This is the default unless any of
+<tt class="docutils literal"><span class="pre">--proto</span> <span class="pre">tcp-client</span></tt> , <tt class="docutils literal"><span class="pre">--http-proxy</span></tt> or <tt class="docutils literal"><span class="pre">--socks-proxy</span></tt> are used.</p>
+<p class="last">If the optional <code>ipv6only</code> keyword is present OpenVPN will bind only
+to IPv6 (as opposed to IPv6 and IPv4) when a IPv6 socket is opened.</p>
+</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--float</span></kbd></td>
+<td><p class="first">Allow remote peer to change its IP address and/or port number, such as
+due to DHCP (this is the default if <tt class="docutils literal"><span class="pre">--remote</span></tt> is not used).
+<tt class="docutils literal"><span class="pre">--float</span></tt> when specified with <tt class="docutils literal"><span class="pre">--remote</span></tt> allows an OpenVPN session
+to initially connect to a peer at a known address, however if packets
+arrive from a new address and pass all authentication tests, the new
+address will take control of the session. This is useful when you are
+connecting to a peer which holds a dynamic address such as a dial-in
+user or DHCP client.</p>
+<p class="last">Essentially, <tt class="docutils literal"><span class="pre">--float</span></tt> tells OpenVPN to accept authenticated packets
+from any address, not only the address which was specified in the
+<tt class="docutils literal"><span class="pre">--remote</span></tt> option.</p>
+</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--fragment <var>max</var></span></kbd></td>
+<td><p class="first">Enable internal datagram fragmentation so that no UDP datagrams are sent
+which are larger than <tt class="docutils literal">max</tt> bytes.</p>
+<p>The <tt class="docutils literal">max</tt> parameter is interpreted in the same way as the
+<tt class="docutils literal"><span class="pre">--link-mtu</span></tt> parameter, i.e. the UDP packet size after encapsulation
+overhead has been added in, but not including the UDP header itself.</p>
+<p>The <tt class="docutils literal"><span class="pre">--fragment</span></tt> option only makes sense when you are using the UDP
+protocol (<tt class="docutils literal"><span class="pre">--proto</span> udp</tt>).</p>
+<p><tt class="docutils literal"><span class="pre">--fragment</span></tt> adds 4 bytes of overhead per datagram.</p>
+<p>See the <tt class="docutils literal"><span class="pre">--mssfix</span></tt> option below for an important related option to
+<tt class="docutils literal"><span class="pre">--fragment</span></tt>.</p>
+<p>It should also be noted that this option is not meant to replace UDP
+fragmentation at the IP stack level. It is only meant as a last resort
+when path MTU discovery is broken. Using this option is less efficient
+than fixing path MTU discovery for your IP link and using native IP
+fragmentation instead.</p>
+<p class="last">Having said that, there are circumstances where using OpenVPN's internal
+fragmentation capability may be your only option, such as tunneling a
+UDP multicast stream which requires fragmentation.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--keepalive <var>args</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">A helper directive designed to simplify the expression of <tt class="docutils literal"><span class="pre">--ping</span></tt> and
+<tt class="docutils literal"><span class="pre">--ping-restart</span></tt>.</p>
+<p>Valid syntax:</p>
+<pre class="literal-block">
+keepalive interval timeout
+</pre>
+<p>This option can be used on both client and server side, but it is enough
+to add this on the server side as it will push appropriate <tt class="docutils literal"><span class="pre">--ping</span></tt>
+and <tt class="docutils literal"><span class="pre">--ping-restart</span></tt> options to the client. If used on both server and
+client, the values pushed from server will override the client local
+values.</p>
+<p>The <tt class="docutils literal">timeout</tt> argument will be twice as long on the server side. This
+ensures that a timeout is detected on client side before the server side
+drops the connection.</p>
+<p>For example, <tt class="docutils literal"><span class="pre">--keepalive</span> 10 60</tt> expands as follows:</p>
+<pre class="last literal-block">
+if mode server:
+ ping 10 # Argument: interval
+ ping-restart 120 # Argument: timeout*2
+ push &quot;ping 10&quot; # Argument: interval
+ push &quot;ping-restart 60&quot; # Argument: timeout
+else
+ ping 10 # Argument: interval
+ ping-restart 60 # Argument: timeout
+</pre>
+</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--link-mtu <var>n</var></span></kbd></td>
+<td>Sets an upper bound on the size of UDP packets which are sent between
+OpenVPN peers. <em>It's best not to set this parameter unless you know what
+you're doing.</em></td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--local <var>host</var></span></kbd></td>
+<td>Local host name or IP address for bind. If specified, OpenVPN will bind
+to this address only. If unspecified, OpenVPN will bind to all
+interfaces.</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--lport <var>port</var></span></kbd></td>
+<td>Set local TCP/UDP port number or name. Cannot be used together with
+<tt class="docutils literal"><span class="pre">--nobind</span></tt> option.</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--mark <var>value</var></span></kbd></td>
+<td>Mark encrypted packets being sent with value. The mark value can be
+matched in policy routing and packetfilter rules. This option is only
+supported in Linux and does nothing on other operating systems.</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--mode <var>m</var></span></kbd></td>
+<td>Set OpenVPN major mode. By default, OpenVPN runs in point-to-point mode
+(<code>p2p</code>). OpenVPN 2.0 introduces a new mode (<code>server</code>) which
+implements a multi-client server capability.</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--mssfix <var>max</var></span></kbd></td>
+<td><p class="first">Announce to TCP sessions running over the tunnel that they should limit
+their send packet sizes such that after OpenVPN has encapsulated them,
+the resulting UDP packet size that OpenVPN sends to its peer will not
+exceed <tt class="docutils literal">max</tt> bytes. The default value is <code>1450</code>.</p>
+<p>The <tt class="docutils literal">max</tt> parameter is interpreted in the same way as the
+<tt class="docutils literal"><span class="pre">--link-mtu</span></tt> parameter, i.e. the UDP packet size after encapsulation
+overhead has been added in, but not including the UDP header itself.
+Resulting packet would be at most 28 bytes larger for IPv4 and 48 bytes
+for IPv6 (20/40 bytes for IP header and 8 bytes for UDP header). Default
+value of 1450 allows IPv4 packets to be transmitted over a link with MTU
+1473 or higher without IP level fragmentation.</p>
+<p>The <tt class="docutils literal"><span class="pre">--mssfix</span></tt> option only makes sense when you are using the UDP
+protocol for OpenVPN peer-to-peer communication, i.e. <tt class="docutils literal"><span class="pre">--proto</span> udp</tt>.</p>
+<p><tt class="docutils literal"><span class="pre">--mssfix</span></tt> and <tt class="docutils literal"><span class="pre">--fragment</span></tt> can be ideally used together, where
+<tt class="docutils literal"><span class="pre">--mssfix</span></tt> will try to keep TCP from needing packet fragmentation in
+the first place, and if big packets come through anyhow (from protocols
+other than TCP), <tt class="docutils literal"><span class="pre">--fragment</span></tt> will internally fragment them.</p>
+<p>Both <tt class="docutils literal"><span class="pre">--fragment</span></tt> and <tt class="docutils literal"><span class="pre">--mssfix</span></tt> are designed to work around cases
+where Path MTU discovery is broken on the network path between OpenVPN
+peers.</p>
+<p>The usual symptom of such a breakdown is an OpenVPN connection which
+successfully starts, but then stalls during active usage.</p>
+<p>If <tt class="docutils literal"><span class="pre">--fragment</span></tt> and <tt class="docutils literal"><span class="pre">--mssfix</span></tt> are used together, <tt class="docutils literal"><span class="pre">--mssfix</span></tt> will
+take its default <tt class="docutils literal">max</tt> parameter from the <tt class="docutils literal"><span class="pre">--fragment</span> max</tt> option.</p>
+<p>Therefore, one could lower the maximum UDP packet size to 1300 (a good
+first try for solving MTU-related connection problems) with the
+following options:</p>
+<pre class="last literal-block">
+--tun-mtu 1500 --fragment 1300 --mssfix
+</pre>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--mtu-disc <var>type</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Should we do Path MTU discovery on TCP/UDP channel? Only supported on
+OSes such as Linux that supports the necessary system call to set.</p>
+<p>Valid types:</p>
+<p><code>no</code> Never send DF (Don't Fragment) frames</p>
+<p><code>maybe</code> Use per-route hints</p>
+<p class="last"><code>yes</code> Always DF (Don't Fragment)</p>
+</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--mtu-test</span></kbd></td>
+<td>To empirically measure MTU on connection startup, add the <tt class="docutils literal"><span class="pre">--mtu-test</span></tt>
+option to your configuration. OpenVPN will send ping packets of various
+sizes to the remote peer and measure the largest packets which were
+successfully received. The <tt class="docutils literal"><span class="pre">--mtu-test</span></tt> process normally takes about 3
+minutes to complete.</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--nobind</span></kbd></td>
+<td>Do not bind to local address and port. The IP stack will allocate a
+dynamic port for returning packets. Since the value of the dynamic port
+could not be known in advance by a peer, this option is only suitable
+for peers which will be initiating connections by using the --remote
+option.</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--passtos</span></kbd></td>
+<td>Set the TOS field of the tunnel packet to what the payload's TOS is.</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--ping <var>n</var></span></kbd></td>
+<td><p class="first">Ping remote over the TCP/UDP control channel if no packets have been
+sent for at least <tt class="docutils literal">n</tt> seconds (specify <tt class="docutils literal"><span class="pre">--ping</span></tt> on both peers to
+cause ping packets to be sent in both directions since OpenVPN ping
+packets are not echoed like IP ping packets). When used in one of
+OpenVPN's secure modes (where <tt class="docutils literal"><span class="pre">--secret</span></tt>, <tt class="docutils literal"><span class="pre">--tls-server</span></tt> or
+<tt class="docutils literal"><span class="pre">--tls-client</span></tt> is specified), the ping packet will be
+cryptographically secure.</p>
+<p>This option has two intended uses:</p>
+<ol class="last arabic simple">
+<li>Compatibility with stateful firewalls. The periodic ping will ensure
+that a stateful firewall rule which allows OpenVPN UDP packets to
+pass will not time out.</li>
+<li>To provide a basis for the remote to test the existence of its peer
+using the <tt class="docutils literal"><span class="pre">--ping-exit</span></tt> option.</li>
+</ol>
+</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--ping-exit <var>n</var></span></kbd></td>
+<td><p class="first">Causes OpenVPN to exit after <tt class="docutils literal">n</tt> seconds pass without reception of a
+ping or other packet from remote. This option can be combined with
+<tt class="docutils literal"><span class="pre">--inactive</span></tt>, <tt class="docutils literal"><span class="pre">--ping</span></tt> and <tt class="docutils literal"><span class="pre">--ping-exit</span></tt> to create a two-tiered
+inactivity disconnect.</p>
+<p>For example,</p>
+<pre class="literal-block">
+openvpn [options...] --inactive 3600 --ping 10 --ping-exit 60
+</pre>
+<p class="last">when used on both peers will cause OpenVPN to exit within 60 seconds if
+its peer disconnects, but will exit after one hour if no actual tunnel
+data is exchanged.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--ping-restart <var>n</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Similar to <tt class="docutils literal"><span class="pre">--ping-exit</span></tt>, but trigger a <code>SIGUSR1</code> restart after
+<tt class="docutils literal">n</tt> seconds pass without reception of a ping or other packet from
+remote.</p>
+<p>This option is useful in cases where the remote peer has a dynamic IP
+address and a low-TTL DNS name is used to track the IP address using a
+service such as <a class="reference external" href="http://dyndns.org/">http://dyndns.org/</a> + a dynamic DNS client such as
+<tt class="docutils literal">ddclient</tt>.</p>
+<p>If the peer cannot be reached, a restart will be triggered, causing the
+hostname used with <tt class="docutils literal"><span class="pre">--remote</span></tt> to be re-resolved (if <tt class="docutils literal"><span class="pre">--resolv-retry</span></tt>
+is also specified).</p>
+<p>In server mode, <tt class="docutils literal"><span class="pre">--ping-restart</span></tt>, <tt class="docutils literal"><span class="pre">--inactive</span></tt> or any other type of
+internally generated signal will always be applied to individual client
+instance objects, never to whole server itself. Note also in server mode
+that any internally generated signal which would normally cause a
+restart, will cause the deletion of the client instance object instead.</p>
+<p>In client mode, the <tt class="docutils literal"><span class="pre">--ping-restart</span></tt> parameter is set to 120 seconds
+by default. This default will hold until the client pulls a replacement
+value from the server, based on the <tt class="docutils literal"><span class="pre">--keepalive</span></tt> setting in the
+server configuration. To disable the 120 second default, set
+<tt class="docutils literal"><span class="pre">--ping-restart</span> 0</tt> on the client.</p>
+<p>See the signals section below for more information on <code>SIGUSR1</code>.</p>
+<p>Note that the behavior of <tt class="docutils literal">SIGUSR1</tt> can be modified by the
+<tt class="docutils literal"><span class="pre">--persist-tun</span></tt>, <tt class="docutils literal"><span class="pre">--persist-key</span></tt>, <tt class="docutils literal"><span class="pre">--persist-local-ip</span></tt> and
+<tt class="docutils literal"><span class="pre">--persist-remote-ip</span></tt> options.</p>
+<p class="last">Also note that <tt class="docutils literal"><span class="pre">--ping-exit</span></tt> and <tt class="docutils literal"><span class="pre">--ping-restart</span></tt> are mutually
+exclusive and cannot be used together.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--ping-timer-rem</span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td>Run the <tt class="docutils literal"><span class="pre">--ping-exit</span></tt> / <tt class="docutils literal"><span class="pre">--ping-restart</span></tt> timer only if we have a
+remote address. Use this option if you are starting the daemon in listen
+mode (i.e. without an explicit <tt class="docutils literal"><span class="pre">--remote</span></tt> peer), and you don't want to
+start clocking timeouts until a remote peer connects.</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--proto <var>p</var></span></kbd></td>
+<td><p class="first">Use protocol <tt class="docutils literal">p</tt> for communicating with remote host. <tt class="docutils literal">p</tt> can be
+<code>udp</code>, <code>tcp-client</code>, or <code>tcp-server</code>.</p>
+<p>The default protocol is <code>udp</code> when <tt class="docutils literal"><span class="pre">--proto</span></tt> is not specified.</p>
+<p>For UDP operation, <tt class="docutils literal"><span class="pre">--proto</span> udp</tt> should be specified on both peers.</p>
+<p>For TCP operation, one peer must use <tt class="docutils literal"><span class="pre">--proto</span> <span class="pre">tcp-server</span></tt> and the
+other must use <tt class="docutils literal"><span class="pre">--proto</span> <span class="pre">tcp-client</span></tt>. A peer started with
+<code>tcp-server</code> will wait indefinitely for an incoming connection. A peer
+started with <code>tcp-client</code> will attempt to connect, and if that fails,
+will sleep for 5 seconds (adjustable via the <tt class="docutils literal"><span class="pre">--connect-retry</span></tt> option)
+and try again infinite or up to N retries (adjustable via the
+<tt class="docutils literal"><span class="pre">--connect-retry-max</span></tt> option). Both TCP client and server will
+simulate a SIGUSR1 restart signal if either side resets the connection.</p>
+<p>OpenVPN is designed to operate optimally over UDP, but TCP capability is
+provided for situations where UDP cannot be used. In comparison with
+UDP, TCP will usually be somewhat less efficient and less robust when
+used over unreliable or congested networks.</p>
+<p>This article outlines some of problems with tunneling IP over TCP:
+<a class="reference external" href="http://sites.inka.de/sites/bigred/devel/tcp-tcp.html">http://sites.inka.de/sites/bigred/devel/tcp-tcp.html</a></p>
+<p class="last">There are certain cases, however, where using TCP may be advantageous
+from a security and robustness perspective, such as tunneling non-IP or
+application-level UDP protocols, or tunneling protocols which don't
+possess a built-in reliability layer.</p>
+</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--port <var>port</var></span></kbd></td>
+<td>TCP/UDP port number or port name for both local and remote (sets both
+<tt class="docutils literal"><span class="pre">--lport</span></tt> and <tt class="docutils literal"><span class="pre">--rport</span></tt> options to given port). The current default
+of 1194 represents the official IANA port number assignment for OpenVPN
+and has been used since version 2.0-beta17. Previous versions used port
+5000 as the default.</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--rport <var>port</var></span></kbd></td>
+<td>Set TCP/UDP port number or name used by the <tt class="docutils literal"><span class="pre">--remote</span></tt> option. The
+port can also be set directly using the <tt class="docutils literal"><span class="pre">--remote</span></tt> option.</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--replay-window <var>args</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Modify the replay protection sliding-window size and time window.</p>
+<p>Valid syntax:</p>
+<pre class="literal-block">
+replay-window n [t]
+</pre>
+<p>Use a replay protection sliding-window of size <strong>n</strong> and a time window
+of <strong>t</strong> seconds.</p>
+<p>By default <strong>n</strong> is 64 (the IPSec default) and <strong>t</strong> is 15 seconds.</p>
+<p>This option is only relevant in UDP mode, i.e. when either <strong>--proto
+udp</strong> is specified, or no <strong>--proto</strong> option is specified.</p>
+<p>When OpenVPN tunnels IP packets over UDP, there is the possibility that
+packets might be dropped or delivered out of order. Because OpenVPN,
+like IPSec, is emulating the physical network layer, it will accept an
+out-of-order packet sequence, and will deliver such packets in the same
+order they were received to the TCP/IP protocol stack, provided they
+satisfy several constraints.</p>
+<ol class="loweralpha simple">
+<li>The packet cannot be a replay (unless <tt class="docutils literal"><span class="pre">--no-replay</span></tt> is
+specified, which disables replay protection altogether).</li>
+<li>If a packet arrives out of order, it will only be accepted if
+the difference between its sequence number and the highest sequence
+number received so far is less than <tt class="docutils literal">n</tt>.</li>
+<li>If a packet arrives out of order, it will only be accepted if it
+arrives no later than <tt class="docutils literal">t</tt> seconds after any packet containing a higher
+sequence number.</li>
+</ol>
+<p>If you are using a network link with a large pipeline (meaning that the
+product of bandwidth and latency is high), you may want to use a larger
+value for <tt class="docutils literal">n</tt>. Satellite links in particular often require this.</p>
+<p>If you run OpenVPN at <tt class="docutils literal"><span class="pre">--verb</span> 4</tt>, you will see the message
+&quot;Replay-window backtrack occurred [x]&quot; every time the maximum sequence
+number backtrack seen thus far increases. This can be used to calibrate
+<tt class="docutils literal">n</tt>.</p>
+<p>There is some controversy on the appropriate method of handling packet
+reordering at the security layer.</p>
+<p>Namely, to what extent should the security layer protect the
+encapsulated protocol from attacks which masquerade as the kinds of
+normal packet loss and reordering that occur over IP networks?</p>
+<p>The IPSec and OpenVPN approach is to allow packet reordering within a
+certain fixed sequence number window.</p>
+<p>OpenVPN adds to the IPSec model by limiting the window size in time as
+well as sequence space.</p>
+<p>OpenVPN also adds TCP transport as an option (not offered by IPSec) in
+which case OpenVPN can adopt a very strict attitude towards message
+deletion and reordering: Don't allow it. Since TCP guarantees
+reliability, any packet loss or reordering event can be assumed to be an
+attack.</p>
+<p>In this sense, it could be argued that TCP tunnel transport is preferred
+when tunneling non-IP or UDP application protocols which might be
+vulnerable to a message deletion or reordering attack which falls within
+the normal operational parameters of IP networks.</p>
+<p class="last">So I would make the statement that one should never tunnel a non-IP
+protocol or UDP application protocol over UDP, if the protocol might be
+vulnerable to a message deletion or reordering attack that falls within
+the normal operating parameters of what is to be expected from the
+physical IP layer. The problem is easily fixed by simply using TCP as
+the VPN transport layer.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--replay-persist <var>file</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Persist replay-protection state across sessions using <tt class="docutils literal">file</tt> to save
+and reload the state.</p>
+<p>This option will strengthen protection against replay attacks,
+especially when you are using OpenVPN in a dynamic context (such as with
+<tt class="docutils literal"><span class="pre">--inetd</span></tt>) when OpenVPN sessions are frequently started and stopped.</p>
+<p>This option will keep a disk copy of the current replay protection state
+(i.e. the most recent packet timestamp and sequence number received from
+the remote peer), so that if an OpenVPN session is stopped and
+restarted, it will reject any replays of packets which were already
+received by the prior session.</p>
+<p class="last">This option only makes sense when replay protection is enabled (the
+default) and you are using either <tt class="docutils literal"><span class="pre">--secret</span></tt> (shared-secret key mode)
+or TLS mode with <tt class="docutils literal"><span class="pre">--tls-auth</span></tt>.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--socket-flags <var>flags</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Apply the given flags to the OpenVPN transport socket. Currently, only
+<code>TCP_NODELAY</code> is supported.</p>
+<p>The <code>TCP_NODELAY</code> socket flag is useful in TCP mode, and causes the
+kernel to send tunnel packets immediately over the TCP connection without
+trying to group several smaller packets into a larger packet. This can
+result in a considerably improvement in latency.</p>
+<p class="last">This option is pushable from server to client, and should be used on
+both client and server for maximum effect.</p>
+</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--tcp-nodelay</span></kbd></td>
+<td><p class="first">This macro sets the <code>TCP_NODELAY</code> socket flag on the server as well
+as pushes it to connecting clients. The <code>TCP_NODELAY</code> flag disables
+the Nagle algorithm on TCP sockets causing packets to be transmitted
+immediately with low latency, rather than waiting a short period of time
+in order to aggregate several packets into a larger containing packet.
+In VPN applications over TCP, <code>TCP_NODELAY</code> is generally a good
+latency optimization.</p>
+<p>The macro expands as follows:</p>
+<pre class="last literal-block">
+if mode server:
+ socket-flags TCP_NODELAY
+ push &quot;socket-flags TCP_NODELAY&quot;
+</pre>
+</td></tr>
+</tbody>
+</table>
+</div>
+<div class="section" id="virtual-network-adapter-vpn-interface">
+<h2>Virtual Network Adapter (VPN interface)</h2>
+<p>Options in this section relates to configuration of the virtual tun/tap
+network interface, including setting the VPN IP address and network
+routing.</p>
+<table class="docutils option-list" frame="void" rules="none">
+<col class="option" />
+<col class="description" />
+<tbody valign="top">
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--bind-dev <var>device</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td>(Linux only) Set <tt class="docutils literal">device</tt> to bind the server socket to a
+<a class="reference internal" href="#virtual-routing-and-forwarding">Virtual Routing and Forwarding</a> device</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--block-ipv6</span></kbd></td>
+<td><p class="first">On the client, instead of sending IPv6 packets over the VPN tunnel, all
+IPv6 packets are answered with an ICMPv6 no route host message. On the
+server, all IPv6 packets from clients are answered with an ICMPv6 no
+route to host message. This options is intended for cases when IPv6
+should be blocked and other options are not available. <tt class="docutils literal"><span class="pre">--block-ipv6</span></tt>
+will use the remote IPv6 as source address of the ICMPv6 packets if set,
+otherwise will use <code>fe80::7</code> as source address.</p>
+<p>For this option to make sense you actually have to route traffic to the
+tun interface. The following example config block would send all IPv6
+traffic to OpenVPN and answer all requests with no route to host,
+effectively blocking IPv6.</p>
+<dl class="last docutils">
+<dt><strong>Client config</strong></dt>
+<dd><pre class="first last literal-block">
+--ifconfig-ipv6 fd15:53b6:dead::2/64 fd15:53b6:dead::1
+--redirect-gateway ipv6
+--block-ipv6
+</pre>
+</dd>
+<dt><strong>Server config</strong></dt>
+<dd><p class="first">Push a &quot;valid&quot; ipv6 config to the client and block on the server</p>
+<pre class="last literal-block">
+--push &quot;ifconfig-ipv6 fd15:53b6:dead::2/64 fd15:53b6:dead::1&quot;
+--push &quot;redirect-gateway ipv6&quot;
+--block-ipv6
+</pre>
+</dd>
+</dl>
+</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--dev <var>device</var></span></kbd></td>
+<td><p class="first">TUN/TAP virtual network device which can be <code>tunX</code>, <code>tapX</code>,
+<code>null</code> or an arbitrary name string (<code>X</code> can be omitted for
+a dynamic device.)</p>
+<p>See examples section below for an example on setting up a TUN device.</p>
+<p>You must use either tun devices on both ends of the connection or tap
+devices on both ends. You cannot mix them, as they represent different
+underlying network layers:</p>
+<dl class="docutils">
+<dt><code>tun</code></dt>
+<dd>devices encapsulate IPv4 or IPv6 (OSI Layer 3)</dd>
+<dt><code>tap</code></dt>
+<dd>devices encapsulate Ethernet 802.3 (OSI Layer 2).</dd>
+</dl>
+<p>Valid syntaxes:</p>
+<pre class="literal-block">
+dev tun2
+dev tap4
+dev ovpn
+</pre>
+<p class="last">When the device name starts with <code>tun</code> or <code>tap</code>, the device
+type is extracted automatically. Otherwise the <tt class="docutils literal"><span class="pre">--dev-type</span></tt> option
+needs to be added as well.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--dev-node <var>node</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Explicitly set the device node rather than using <code>/dev/net/tun</code>,
+<code>/dev/tun</code>, <code>/dev/tap</code>, etc. If OpenVPN cannot figure out
+whether <tt class="docutils literal">node</tt> is a TUN or TAP device based on the name, you should
+also specify <tt class="docutils literal"><span class="pre">--dev-type</span> tun</tt> or <tt class="docutils literal"><span class="pre">--dev-type</span> tap</tt>.</p>
+<p>Under Mac OS X this option can be used to specify the default tun
+implementation. Using <tt class="docutils literal"><span class="pre">--dev-node</span> utun</tt> forces usage of the native
+Darwin tun kernel support. Use <tt class="docutils literal"><span class="pre">--dev-node</span> utunN</tt> to select a specific
+utun instance. To force using the <code>tun.kext</code> (<code>/dev/tunX</code>)
+use <tt class="docutils literal"><span class="pre">--dev-node</span> tun</tt>. When not specifying a <tt class="docutils literal"><span class="pre">--dev-node</span></tt> option
+openvpn will first try to open utun, and fall back to tun.kext.</p>
+<p class="last">On Windows systems, select the TAP-Win32 adapter which is named <tt class="docutils literal">node</tt>
+in the Network Connections Control Panel or the raw GUID of the adapter
+enclosed by braces. The <tt class="docutils literal"><span class="pre">--show-adapters</span></tt> option under Windows can
+also be used to enumerate all available TAP-Win32 adapters and will show
+both the network connections control panel name and the GUID for each
+TAP-Win32 adapter.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--dev-type <var>device-type</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td>Which device type are we using? <tt class="docutils literal"><span class="pre">device-type</span></tt> should be <code>tun</code>
+(OSI Layer 3) or <code>tap</code> (OSI Layer 2). Use this option only if
+the TUN/TAP device used with <tt class="docutils literal"><span class="pre">--dev</span></tt> does not begin with <code>tun</code>
+or <code>tap</code>.</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--dhcp-option <var>args</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Set additional network parameters on supported platforms. May be specified
+on the client or pushed from the server. On Windows these options are
+handled by the <tt class="docutils literal"><span class="pre">tap-windows6</span></tt> driver by default or directly by OpenVPN
+if dhcp is disabled or the <tt class="docutils literal">wintun</tt> driver is in use. The
+<tt class="docutils literal">OpenVPN for Android</tt> client also handles them internally.</p>
+<p>On all other platforms these options are only saved in the client's
+environment under the name <code>foreign_options_{n}</code> before the
+<tt class="docutils literal"><span class="pre">--up</span></tt> script is called. A plugin or an <tt class="docutils literal"><span class="pre">--up</span></tt> script must be used to
+pick up and interpret these as required. Many Linux distributions include
+such scripts and some third-party user interfaces such as tunnelblick also
+come with scripts that process these options.</p>
+<p>Valid syntax:</p>
+<pre class="literal-block">
+dhcp-options type [parm]
+</pre>
+<dl class="last docutils">
+<dt><code>DOMAIN</code> <tt class="docutils literal">name</tt></dt>
+<dd>Set Connection-specific DNS Suffix to <code>name</code>.</dd>
+<dt><code>DOMAIN-SEARCH</code> <tt class="docutils literal">name</tt></dt>
+<dd>Add <code>name</code> to the domain search list.
+Repeat this option to add more entries. Up to
+10 domains are supported.</dd>
+<dt><code>DNS</code> <tt class="docutils literal">address</tt></dt>
+<dd><p class="first">Set primary domain name server IPv4 or IPv6 address.
+Repeat this option to set secondary DNS server addresses.</p>
+<p class="last">Note: DNS IPv6 servers are currently set using netsh (the existing
+DHCP code can only do IPv4 DHCP, and that protocol only permits
+IPv4 addresses anywhere). The option will be put into the
+environment, so an <tt class="docutils literal"><span class="pre">--up</span></tt> script could act upon it if needed.</p>
+</dd>
+<dt><code>WINS</code> <tt class="docutils literal">address</tt></dt>
+<dd>Set primary WINS server address (NetBIOS over TCP/IP Name Server).
+Repeat this option to set secondary WINS server addresses.</dd>
+<dt><code>NBDD</code> <tt class="docutils literal">address</tt></dt>
+<dd>Set primary NBDD server address (NetBIOS over TCP/IP Datagram
+Distribution Server). Repeat this option to set secondary NBDD
+server addresses.</dd>
+<dt><code>NTP</code> <tt class="docutils literal">address</tt></dt>
+<dd>Set primary NTP server address (Network Time Protocol).
+Repeat this option to set secondary NTP server addresses.</dd>
+<dt><code>NBT</code> <tt class="docutils literal">type</tt></dt>
+<dd><p class="first">Set NetBIOS over TCP/IP Node type. Possible options:</p>
+<dl class="last docutils">
+<dt><code>1</code></dt>
+<dd>b-node (broadcasts)</dd>
+<dt><code>2</code></dt>
+<dd>p-node (point-to-point name queries to a WINS server)</dd>
+<dt><code>4</code></dt>
+<dd>m-node (broadcast then query name server)</dd>
+<dt><code>8</code></dt>
+<dd>h-node (query name server, then broadcast).</dd>
+</dl>
+</dd>
+<dt><code>NBS</code> <tt class="docutils literal"><span class="pre">scope-id</span></tt></dt>
+<dd>Set NetBIOS over TCP/IP Scope. A NetBIOS Scope ID provides an
+extended naming service for the NetBIOS over TCP/IP (Known as NBT)
+module. The primary purpose of a NetBIOS scope ID is to isolate
+NetBIOS traffic on a single network to only those nodes with the
+same NetBIOS scope ID. The NetBIOS scope ID is a character string
+that is appended to the NetBIOS name. The NetBIOS scope ID on two
+hosts must match, or the two hosts will not be able to communicate.
+The NetBIOS Scope ID also allows computers to use the same computer
+name, as they have different scope IDs. The Scope ID becomes a part
+of the NetBIOS name, making the name unique. (This description of
+NetBIOS scopes courtesy of <a class="reference external" href="mailto:NeonSurge&#64;abyss.com">NeonSurge&#64;abyss.com</a>)</dd>
+<dt><code>DISABLE-NBT</code></dt>
+<dd>Disable Netbios-over-TCP/IP.</dd>
+</dl>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--ifconfig <var>args</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Set TUN/TAP adapter parameters. It requires the <em>IP address</em> of the local
+VPN endpoint. For TUN devices in point-to-point mode, the next argument
+must be the VPN IP address of the remote VPN endpoint. For TAP devices,
+or TUN devices used with <tt class="docutils literal"><span class="pre">--topology</span> subnet</tt>, the second argument
+is the subnet mask of the virtual network segment which is being created
+or connected to.</p>
+<p>For TUN devices, which facilitate virtual point-to-point IP connections
+(when used in <tt class="docutils literal"><span class="pre">--topology</span> net30</tt> or <tt class="docutils literal">p2p</tt> mode), the proper usage of
+<tt class="docutils literal"><span class="pre">--ifconfig</span></tt> is to use two private IP addresses which are not a member
+of any existing subnet which is in use. The IP addresses may be
+consecutive and should have their order reversed on the remote peer.
+After the VPN is established, by pinging <tt class="docutils literal">rn</tt>, you will be pinging
+across the VPN.</p>
+<p>For TAP devices, which provide the ability to create virtual ethernet
+segments, or TUN devices in <tt class="docutils literal"><span class="pre">--topology</span> subnet</tt> mode (which create
+virtual &quot;multipoint networks&quot;), <tt class="docutils literal"><span class="pre">--ifconfig</span></tt> is used to set an IP
+address and subnet mask just as a physical ethernet adapter would be
+similarly configured. If you are attempting to connect to a remote
+ethernet bridge, the IP address and subnet should be set to values which
+would be valid on the the bridged ethernet segment (note also that DHCP
+can be used for the same purpose).</p>
+<p>This option, while primarily a proxy for the <tt class="docutils literal">ifconfig</tt>(8) command,
+is designed to simplify TUN/TAP tunnel configuration by providing a
+standard interface to the different ifconfig implementations on
+different platforms.</p>
+<p><tt class="docutils literal"><span class="pre">--ifconfig</span></tt> parameters which are IP addresses can also be specified
+as a DNS or /etc/hosts file resolvable name.</p>
+<p>For TAP devices, <tt class="docutils literal"><span class="pre">--ifconfig</span></tt> should not be used if the TAP interface
+will be getting an IP address lease from a DHCP server.</p>
+<p>Examples:</p>
+<pre class="last literal-block">
+# tun device in net30/p2p mode
+ifconfig 10.8.0.2 10.8.0.1
+
+# tun/tap device in subnet mode
+ifconfig 10.8.0.2 255.255.255.0
+</pre>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--ifconfig-ipv6 <var>args</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Configure an IPv6 address on the <em>tun</em> device.</p>
+<p>Valid syntax:</p>
+<pre class="literal-block">
+ifconfig-ipv6 ipv6addr/bits [ipv6remote]
+</pre>
+<p>The <tt class="docutils literal">ipv6addr/bits</tt> argument is the IPv6 address to use. The
+second parameter is used as route target for <tt class="docutils literal"><span class="pre">--route-ipv6</span></tt> if no
+gateway is specified.</p>
+<p class="last">The <tt class="docutils literal"><span class="pre">--topology</span></tt> option has no influence with <tt class="docutils literal"><span class="pre">--ifconfig-ipv6</span></tt></p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--ifconfig-noexec</span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td>Don't actually execute ifconfig/netsh commands, instead pass
+<tt class="docutils literal"><span class="pre">--ifconfig</span></tt> parameters to scripts using environmental variables.</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--ifconfig-nowarn</span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Don't output an options consistency check warning if the <tt class="docutils literal"><span class="pre">--ifconfig</span></tt>
+option on this side of the connection doesn't match the remote side.
+This is useful when you want to retain the overall benefits of the
+options consistency check (also see <tt class="docutils literal"><span class="pre">--disable-occ</span></tt> option) while only
+disabling the ifconfig component of the check.</p>
+<p>For example, if you have a configuration where the local host uses
+<tt class="docutils literal"><span class="pre">--ifconfig</span></tt> but the remote host does not, use <tt class="docutils literal"><span class="pre">--ifconfig-nowarn</span></tt>
+on the local host.</p>
+<p class="last">This option will also silence warnings about potential address conflicts
+which occasionally annoy more experienced users by triggering &quot;false
+positive&quot; warnings.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--lladdr <var>address</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td>Specify the link layer address, more commonly known as the MAC address.
+Only applied to TAP devices.</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--persist-tun</span></kbd></td>
+<td><p class="first">Don't close and reopen TUN/TAP device or run up/down scripts across
+<code>SIGUSR1</code> or <tt class="docutils literal"><span class="pre">--ping-restart</span></tt> restarts.</p>
+<p class="last"><code>SIGUSR1</code> is a restart signal similar to <code>SIGHUP</code>, but which
+offers finer-grained control over reset options.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--redirect-gateway <var>flags</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Automatically execute routing commands to cause all outgoing IP traffic
+to be redirected over the VPN. This is a client-side option.</p>
+<p>This option performs three steps:</p>
+<ol class="arabic simple">
+<li>Create a static route for the <tt class="docutils literal"><span class="pre">--remote</span></tt> address which
+forwards to the pre-existing default gateway. This is done so that
+<tt class="docutils literal">(3)</tt> will not create a routing loop.</li>
+<li>Delete the default gateway route.</li>
+<li>Set the new default gateway to be the VPN endpoint address
+(derived either from <tt class="docutils literal"><span class="pre">--route-gateway</span></tt> or the second parameter to
+<tt class="docutils literal"><span class="pre">--ifconfig</span></tt> when <tt class="docutils literal"><span class="pre">--dev</span> tun</tt> is specified).</li>
+</ol>
+<p>When the tunnel is torn down, all of the above steps are reversed so
+that the original default route is restored.</p>
+<p>Option flags:</p>
+<dl class="last docutils">
+<dt><code>local</code></dt>
+<dd>Add the <code>local</code> flag if both OpenVPN peers are directly
+connected via a common subnet, such as with wireless. The
+<code>local</code> flag will cause step <tt class="docutils literal">(1)</tt> above to be omitted.</dd>
+<dt><code>autolocal</code></dt>
+<dd>Try to automatically determine whether to enable <code>local</code>
+flag above.</dd>
+<dt><code>def1</code></dt>
+<dd>Use this flag to override the default gateway by using
+<code>0.0.0.0/1</code> and <code>128.0.0.0/1</code> rather than
+<code>0.0.0.0/0</code>. This has the benefit of overriding but not
+wiping out the original default gateway.</dd>
+<dt><code>bypass-dhcp</code></dt>
+<dd>Add a direct route to the DHCP server (if it is non-local) which
+bypasses the tunnel (Available on Windows clients, may not be
+available on non-Windows clients).</dd>
+<dt><code>bypass-dns</code></dt>
+<dd>Add a direct route to the DNS server(s) (if they are non-local)
+which bypasses the tunnel (Available on Windows clients, may
+not be available on non-Windows clients).</dd>
+<dt><code>block-local</code></dt>
+<dd>Block access to local LAN when the tunnel is active, except for
+the LAN gateway itself. This is accomplished by routing the local
+LAN (except for the LAN gateway address) into the tunnel.</dd>
+<dt><code>ipv6</code></dt>
+<dd>Redirect IPv6 routing into the tunnel. This works similar to
+the <code>def1</code> flag, that is, more specific IPv6 routes are added
+(<code>2000::/4</code>, <code>3000::/4</code>), covering the whole IPv6
+unicast space.</dd>
+<dt><code>!ipv4</code></dt>
+<dd>Do not redirect IPv4 traffic - typically used in the flag pair
+<code>ipv6 !ipv4</code> to redirect IPv6-only.</dd>
+</dl>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--redirect-private <var>flags</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td>Like <tt class="docutils literal"><span class="pre">--redirect-gateway</span></tt>, but omit actually changing the default gateway.
+Useful when pushing private subnets.</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--route <var>args</var></span></kbd></td>
+<td><p class="first">Add route to routing table after connection is established. Multiple
+routes can be specified. Routes will be automatically torn down in
+reverse order prior to TUN/TAP device close.</p>
+<p>Valid syntaxes:</p>
+<pre class="literal-block">
+route network/IP
+route network/IP netmask
+route network/IP netmask gateway
+route network/IP netmask gateway metric
+</pre>
+<p>This option is intended as a convenience proxy for the <tt class="docutils literal">route</tt>(8)
+shell command, while at the same time providing portable semantics
+across OpenVPN's platform space.</p>
+<dl class="docutils">
+<dt><tt class="docutils literal">netmask</tt></dt>
+<dd>defaults to <code>255.255.255.255</code> when not given</dd>
+<dt><tt class="docutils literal">gateway</tt></dt>
+<dd>default taken from <tt class="docutils literal"><span class="pre">--route-gateway</span></tt> or the second
+parameter to <tt class="docutils literal"><span class="pre">--ifconfig</span></tt> when <tt class="docutils literal"><span class="pre">--dev</span> tun</tt> is specified.</dd>
+<dt><tt class="docutils literal">metric</tt></dt>
+<dd>default taken from <tt class="docutils literal"><span class="pre">--route-metric</span></tt> if set, otherwise <code>0</code>.</dd>
+</dl>
+<p>The default can be specified by leaving an option blank or setting it to
+<code>default</code>.</p>
+<p>The <tt class="docutils literal">network</tt> and <tt class="docutils literal">gateway</tt> parameters can also be specified as a
+DNS or <code>/etc/hosts</code> file resolvable name, or as one of three special
+keywords:</p>
+<dl class="last docutils">
+<dt><code>vpn_gateway</code></dt>
+<dd>The remote VPN endpoint address (derived either from
+<tt class="docutils literal"><span class="pre">--route-gateway</span></tt> or the second parameter to <tt class="docutils literal"><span class="pre">--ifconfig</span></tt>
+when <tt class="docutils literal"><span class="pre">--dev</span> tun</tt> is specified).</dd>
+<dt><code>net_gateway</code></dt>
+<dd>The pre-existing IP default gateway, read from the
+routing table (not supported on all OSes).</dd>
+<dt><code>remote_host</code></dt>
+<dd>The <tt class="docutils literal"><span class="pre">--remote</span></tt> address if OpenVPN is being run in
+client mode, and is undefined in server mode.</dd>
+</dl>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--route-delay <var>args</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Valid syntaxes:</p>
+<pre class="literal-block">
+route-delay
+route-delay n
+route-delay n m
+</pre>
+<p>Delay <tt class="docutils literal">n</tt> seconds (default <code>0</code>) after connection establishment,
+before adding routes. If <tt class="docutils literal">n</tt> is <code>0</code>, routes will be added
+immediately upon connection establishment. If <tt class="docutils literal"><span class="pre">--route-delay</span></tt> is
+omitted, routes will be added immediately after TUN/TAP device open and
+<tt class="docutils literal"><span class="pre">--up</span></tt> script execution, before any <tt class="docutils literal"><span class="pre">--user</span></tt> or <tt class="docutils literal"><span class="pre">--group</span></tt> privilege
+downgrade (or <tt class="docutils literal"><span class="pre">--chroot</span></tt> execution.)</p>
+<p>This option is designed to be useful in scenarios where DHCP is used to
+set tap adapter addresses. The delay will give the DHCP handshake time
+to complete before routes are added.</p>
+<p class="last">On Windows, <tt class="docutils literal"><span class="pre">--route-delay</span></tt> tries to be more intelligent by waiting
+<tt class="docutils literal">w</tt> seconds (default <code>30</code> by default) for the TAP-Win32 adapter
+to come up before adding routes.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--route-ipv6 <var>args</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Setup IPv6 routing in the system to send the specified IPv6 network into
+OpenVPN's <em>tun</em>.</p>
+<p>Valid syntax:</p>
+<pre class="literal-block">
+route-ipv6 ipv6addr/bits [gateway] [metric]
+</pre>
+<p class="last">The gateway parameter is only used for IPv6 routes across <em>tap</em> devices,
+and if missing, the <tt class="docutils literal">ipv6remote</tt> field from <tt class="docutils literal"><span class="pre">--ifconfig-ipv6</span></tt> or
+<tt class="docutils literal"><span class="pre">--route-ipv6-gateway</span></tt> is used.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--route-gateway <var>arg</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Specify a default <em>gateway</em> for use with <tt class="docutils literal"><span class="pre">--route</span></tt>.</p>
+<p>If <code>dhcp</code> is specified as the parameter, the gateway address will
+be extracted from a DHCP negotiation with the OpenVPN server-side LAN.</p>
+<p>Valid syntaxes:</p>
+<pre class="last literal-block">
+route-gateway gateway
+route-gateway dhcp
+</pre>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--route-ipv6-gateway <var>gw</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td>Specify a default gateway <tt class="docutils literal">gw</tt> for use with <tt class="docutils literal"><span class="pre">--route-ipv6</span></tt>.</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--route-metric <var>m</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td>Specify a default metric <tt class="docutils literal">m</tt> for use with <tt class="docutils literal"><span class="pre">--route</span></tt>.</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--route-noexec</span></kbd></td>
+<td>Don't add or remove routes automatically. Instead pass routes to
+<tt class="docutils literal"><span class="pre">--route-up</span></tt> script using environmental variables.</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--route-nopull</span></kbd></td>
+<td><p class="first">When used with <tt class="docutils literal"><span class="pre">--client</span></tt> or <tt class="docutils literal"><span class="pre">--pull</span></tt>, accept options pushed by
+server EXCEPT for routes, block-outside-dns and dhcp options like DNS
+servers.</p>
+<p class="last">When used on the client, this option effectively bars the server from
+adding routes to the client's routing table, however note that this
+option still allows the server to set the TCP/IP properties of the
+client's TUN/TAP interface.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--topology <var>mode</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Configure virtual addressing topology when running in <tt class="docutils literal"><span class="pre">--dev</span> tun</tt>
+mode. This directive has no meaning in <tt class="docutils literal"><span class="pre">--dev</span> tap</tt> mode, which always
+uses a <code>subnet</code> topology.</p>
+<p>If you set this directive on the server, the <tt class="docutils literal"><span class="pre">--server</span></tt> and
+<tt class="docutils literal"><span class="pre">--server-bridge</span></tt> directives will automatically push your chosen
+topology setting to clients as well. This directive can also be manually
+pushed to clients. Like the <tt class="docutils literal"><span class="pre">--dev</span></tt> directive, this directive must
+always be compatible between client and server.</p>
+<p><tt class="docutils literal">mode</tt> can be one of:</p>
+<dl class="docutils">
+<dt><code>net30</code></dt>
+<dd>Use a point-to-point topology, by allocating one /30 subnet
+per client. This is designed to allow point-to-point semantics when some
+or all of the connecting clients might be Windows systems. This is the
+default on OpenVPN 2.0.</dd>
+<dt><code>p2p</code></dt>
+<dd>Use a point-to-point topology where the remote endpoint of
+the client's tun interface always points to the local endpoint of the
+server's tun interface. This mode allocates a single IP address per
+connecting client. Only use when none of the connecting clients are
+Windows systems.</dd>
+<dt><code>subnet</code></dt>
+<dd>Use a subnet rather than a point-to-point topology by
+configuring the tun interface with a local IP address and subnet mask,
+similar to the topology used in <tt class="docutils literal"><span class="pre">--dev</span> tap</tt> and ethernet bridging
+mode. This mode allocates a single IP address per connecting client and
+works on Windows as well. Only available when server and clients are
+OpenVPN 2.1 or higher, or OpenVPN 2.0.x which has been manually patched
+with the <tt class="docutils literal"><span class="pre">--topology</span></tt> directive code. When used on Windows, requires
+version 8.2 or higher of the TAP-Win32 driver. When used on *nix,
+requires that the tun driver supports an <tt class="docutils literal">ifconfig</tt>(8) command which
+sets a subnet instead of a remote endpoint IP address.</dd>
+</dl>
+<p class="last"><em>Note:</em> Using <tt class="docutils literal"><span class="pre">--topology</span> subnet</tt> changes the interpretation of the
+arguments of <tt class="docutils literal"><span class="pre">--ifconfig</span></tt> to mean &quot;address netmask&quot;, no longer &quot;local
+remote&quot;.</p>
+</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--tun-mtu <var>n</var></span></kbd></td>
+<td><p class="first">Take the TUN device MTU to be <strong>n</strong> and derive the link MTU from it
+(default <code>1500</code>). In most cases, you will probably want to leave
+this parameter set to its default value.</p>
+<p>The MTU (Maximum Transmission Units) is the maximum datagram size in
+bytes that can be sent unfragmented over a particular network path.
+OpenVPN requires that packets on the control and data channels be sent
+unfragmented.</p>
+<p>MTU problems often manifest themselves as connections which hang during
+periods of active usage.</p>
+<p class="last">It's best to use the <tt class="docutils literal"><span class="pre">--fragment</span></tt> and/or <tt class="docutils literal"><span class="pre">--mssfix</span></tt> options to deal
+with MTU sizing issues.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--tun-mtu-extra <var>n</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td>Assume that the TUN/TAP device might return as many as <tt class="docutils literal">n</tt> bytes more
+than the <tt class="docutils literal"><span class="pre">--tun-mtu</span></tt> size on read. This parameter defaults to 0, which
+is sufficient for most TUN devices. TAP devices may introduce additional
+overhead in excess of the MTU size, and a setting of 32 is the default
+when TAP devices are used. This parameter only controls internal OpenVPN
+buffer sizing, so there is no transmission overhead associated with
+using a larger value.</td></tr>
+</tbody>
+</table>
+</div>
+<div class="section" id="tun-tap-standalone-operations">
+<h2>TUN/TAP standalone operations</h2>
+<p>These two standalone operations will require <tt class="docutils literal"><span class="pre">--dev</span></tt> and optionally
+<tt class="docutils literal"><span class="pre">--user</span></tt> and/or <tt class="docutils literal"><span class="pre">--group</span></tt>.</p>
+<table class="docutils option-list" frame="void" rules="none">
+<col class="option" />
+<col class="description" />
+<tbody valign="top">
+<tr><td class="option-group">
+<kbd><span class="option">--mktun</span></kbd></td>
+<td><p class="first">(Standalone) Create a persistent tunnel on platforms which support them
+such as Linux. Normally TUN/TAP tunnels exist only for the period of
+time that an application has them open. This option takes advantage of
+the TUN/TAP driver's ability to build persistent tunnels that live
+through multiple instantiations of OpenVPN and die only when they are
+deleted or the machine is rebooted.</p>
+<p>One of the advantages of persistent tunnels is that they eliminate the
+need for separate <tt class="docutils literal"><span class="pre">--up</span></tt> and <tt class="docutils literal"><span class="pre">--down</span></tt> scripts to run the appropriate
+<tt class="docutils literal">ifconfig</tt>(8) and <tt class="docutils literal">route</tt>(8) commands. These commands can be
+placed in the the same shell script which starts or terminates an
+OpenVPN session.</p>
+<p>Another advantage is that open connections through the TUN/TAP-based
+tunnel will not be reset if the OpenVPN peer restarts. This can be
+useful to provide uninterrupted connectivity through the tunnel in the
+event of a DHCP reset of the peer's public IP address (see the
+<tt class="docutils literal"><span class="pre">--ipchange</span></tt> option above).</p>
+<p>One disadvantage of persistent tunnels is that it is harder to
+automatically configure their MTU value (see <tt class="docutils literal"><span class="pre">--link-mtu</span></tt> and
+<tt class="docutils literal"><span class="pre">--tun-mtu</span></tt> above).</p>
+<p class="last">On some platforms such as Windows, TAP-Win32 tunnels are persistent by
+default.</p>
+</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--rmtun</span></kbd></td>
+<td>(Standalone) Remove a persistent tunnel.</td></tr>
+</tbody>
+</table>
+</div>
+<div class="section" id="virtual-routing-and-forwarding">
+<h2>Virtual Routing and Forwarding</h2>
+<p>Options in this section relates to configuration of virtual routing and
+forwarding in combination with the underlying operating system.</p>
+<p>As of today this is only supported on Linux, a kernel &gt;= 4.9 is
+recommended.</p>
+<p>This could come in handy when for example the external network should be
+only used as a means to connect to some VPN endpoints and all regular
+traffic should only be routed through any tunnel(s). This could be
+achieved by setting up a VRF and configuring the interface connected to
+the external network to be part of the VRF. The examples below will cover
+this setup.</p>
+<p>Another option would be to put the tun/tap interface into a VRF. This could
+be done by an up-script which uses the <code>ip link set</code> command shown
+below.</p>
+<div class="section" id="vrf-setup-with-iproute2">
+<h3>VRF setup with iproute2</h3>
+<p>Create VRF <code>vrf_external</code> and map it to routing table <code>1023</code></p>
+<pre class="literal-block">
+ip link add vrf_external type vrf table 1023
+</pre>
+<p>Move <code>eth0</code> into <code>vrf_external</code></p>
+<pre class="literal-block">
+ip link set master vrf_external dev eth0
+</pre>
+<p>Any prefixes configured on <code>eth0</code> will be moved from the :code`main`
+routing table into routing table <cite>1023</cite></p>
+</div>
+<div class="section" id="vrf-setup-with-ifupdown">
+<h3>VRF setup with ifupdown</h3>
+<p>For Debian based Distributions <code>ifupdown2</code> provides an almost drop-in
+replacement for <code>ifupdown</code> including VRFs and other features.
+A configuration for an interface <code>eth0</code> being part of VRF
+code:<cite>vrf_external</cite> could look like this:</p>
+<pre class="literal-block">
+auto eth0
+iface eth0
+ address 192.0.2.42/24
+ address 2001:db8:08:15::42/64
+ gateway 192.0.2.1
+ gateway 2001:db8:08:15::1
+ vrf vrf_external
+
+auto vrf_external
+iface vrf_external
+ vrf-table 1023
+</pre>
+</div>
+<div class="section" id="openvpn-configuration">
+<h3>OpenVPN configuration</h3>
+<p>The OpenVPN configuration needs to contain this line:</p>
+<pre class="literal-block">
+bind-dev vrf_external
+</pre>
+</div>
+<div class="section" id="further-reading">
+<h3>Further reading</h3>
+<p>Wikipedia has nice page one VRFs: <a class="reference external" href="https://en.wikipedia.org/wiki/Virtual_routing_and_forwarding">https://en.wikipedia.org/wiki/Virtual_routing_and_forwarding</a></p>
+<p>This talk from the Network Track of FrOSCon 2018 provides an overview about
+advanced layer 2 and layer 3 features of Linux</p>
+<blockquote>
+<ul class="simple">
+<li>Slides: <a class="reference external" href="https://www.slideshare.net/BarbarossaTM/l2l3-fr-fortgeschrittene-helle-und-dunkle-magie-im-linuxnetzwerkstack">https://www.slideshare.net/BarbarossaTM/l2l3-fr-fortgeschrittene-helle-und-dunkle-magie-im-linuxnetzwerkstack</a></li>
+<li>Video (german): <a class="reference external" href="https://media.ccc.de/v/froscon2018-2247-l2_l3_fur_fortgeschrittene_-_helle_und_dunkle_magie_im_linux-netzwerkstack">https://media.ccc.de/v/froscon2018-2247-l2_l3_fur_fortgeschrittene_-_helle_und_dunkle_magie_im_linux-netzwerkstack</a></li>
+</ul>
+</blockquote>
+</div>
+</div>
+</div>
+<div class="section" id="scripting-integration">
+<h1>SCRIPTING INTEGRATION</h1>
+<p>OpenVPN can execute external scripts in various phases of the lifetime of
+the OpenVPN process.</p>
+<div class="section" id="script-order-of-execution">
+<h2>Script Order of Execution</h2>
+<ol class="arabic">
+<li><p class="first"><tt class="docutils literal"><span class="pre">--up</span></tt></p>
+<p>Executed after TCP/UDP socket bind and TUN/TAP open.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">--tls-verify</span></tt></p>
+<p>Executed when we have a still untrusted remote peer.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">--ipchange</span></tt></p>
+<p>Executed after connection authentication, or remote IP address change.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">--client-connect</span></tt></p>
+<p>Executed in <strong>--mode server</strong> mode immediately after client
+authentication.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">--route-up</span></tt></p>
+<p>Executed after connection authentication, either immediately after, or
+some number of seconds after as defined by the <strong>--route-delay</strong> option.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">--route-pre-down</span></tt></p>
+<p>Executed right before the routes are removed.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">--client-disconnect</span></tt></p>
+<p>Executed in <tt class="docutils literal"><span class="pre">--mode</span> server</tt> mode on client instance shutdown.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">--down</span></tt></p>
+<p>Executed after TCP/UDP and TUN/TAP close.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">--learn-address</span></tt></p>
+<p>Executed in <tt class="docutils literal"><span class="pre">--mode</span> server</tt> mode whenever an IPv4 address/route or MAC
+address is added to OpenVPN's internal routing table.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">--auth-user-pass-verify</span></tt></p>
+<p>Executed in <tt class="docutils literal"><span class="pre">--mode</span> server</tt> mode on new client connections, when the
+client is still untrusted.</p>
+</li>
+</ol>
+</div>
+<div class="section" id="script-hooks">
+<h2>SCRIPT HOOKS</h2>
+<table class="docutils option-list" frame="void" rules="none">
+<col class="option" />
+<col class="description" />
+<tbody valign="top">
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--auth-user-pass-verify <var>args</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Require the client to provide a username/password (possibly in addition
+to a client certificate) for authentication.</p>
+<p>Valid syntax:</p>
+<pre class="literal-block">
+auth-user-pass-verify cmd method
+</pre>
+<p>OpenVPN will run command <tt class="docutils literal">cmd</tt> to validate the username/password
+provided by the client.</p>
+<p><tt class="docutils literal">cmd</tt> consists of a path to a script (or executable program), optionally
+followed by arguments. The path and arguments may be single- or
+double-quoted and/or escaped using a backslash, and should be separated
+by one or more spaces.</p>
+<p>If <tt class="docutils literal">method</tt> is set to <code>via-env</code>, OpenVPN will call <tt class="docutils literal">script</tt>
+with the environmental variables <code>username</code> and <code>password</code>
+set to the username/password strings provided by the client. <em>Beware</em>
+that this method is insecure on some platforms which make the environment
+of a process publicly visible to other unprivileged processes.</p>
+<p>If <tt class="docutils literal">method</tt> is set to <code>via-file</code>, OpenVPN will write the username
+and password to the first two lines of a temporary file. The filename
+will be passed as an argument to <tt class="docutils literal">script</tt>, and the file will be
+automatically deleted by OpenVPN after the script returns. The location
+of the temporary file is controlled by the <tt class="docutils literal"><span class="pre">--tmp-dir</span></tt> option, and
+will default to the current directory if unspecified. For security,
+consider setting <tt class="docutils literal"><span class="pre">--tmp-dir</span></tt> to a volatile storage medium such as
+<code>/dev/shm</code> (if available) to prevent the username/password file
+from touching the hard drive.</p>
+<p>The script should examine the username and password, returning a success
+exit code (<code>0</code>) if the client's authentication request is to be
+accepted, or a failure code (<code>1</code>) to reject the client.</p>
+<p>This directive is designed to enable a plugin-style interface for
+extending OpenVPN's authentication capabilities.</p>
+<p>To protect against a client passing a maliciously formed username or
+password string, the username string must consist only of these
+characters: alphanumeric, underbar ('<code>_</code>'), dash ('<code>-</code>'),
+dot ('<code>.</code>'), or at ('<code>&#64;</code>'). The password string can consist
+of any printable characters except for CR or LF. Any illegal characters
+in either the username or password string will be converted to
+underbar ('<code>_</code>').</p>
+<p>Care must be taken by any user-defined scripts to avoid creating a
+security vulnerability in the way that these strings are handled. Never
+use these strings in such a way that they might be escaped or evaluated
+by a shell interpreter.</p>
+<p class="last">For a sample script that performs PAM authentication, see
+<code>sample-scripts/auth-pam.pl</code> in the OpenVPN source distribution.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--client-connect <var>cmd</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Run command <tt class="docutils literal">cmd</tt> on client connection.</p>
+<p><tt class="docutils literal">cmd</tt> consists of a path to a script (or executable program), optionally
+followed by arguments. The path and arguments may be single- or
+double-quoted and/or escaped using a backslash, and should be separated
+by one or more spaces.</p>
+<p>The command is passed the common name and IP address of the
+just-authenticated client as environmental variables (see environmental
+variable section below). The command is also passed the pathname of a
+freshly created temporary file as the last argument (after any arguments
+specified in <tt class="docutils literal">cmd</tt> ), to be used by the command to pass dynamically
+generated config file directives back to OpenVPN.</p>
+<p>If the script wants to generate a dynamic config file to be applied on
+the server when the client connects, it should write it to the file
+named by the last argument.</p>
+<p>See the <tt class="docutils literal"><span class="pre">--client-config-dir</span></tt> option below for options which can be
+legally used in a dynamically generated config file.</p>
+<p>Note that the return value of <tt class="docutils literal">script</tt> is significant. If <tt class="docutils literal">script</tt>
+returns a non-zero error status, it will cause the client to be
+disconnected.</p>
+<p class="last">If a <tt class="docutils literal"><span class="pre">--client-connect</span></tt> wants to defer the generating of the
+configuration then the script needs to use the
+<code>client_connect_deferred_file</code> and
+<code>client_connect_config_file</code> environment variables, and write
+status accordingly into these files. See the <a class="reference internal" href="#environmental-variables">Environmental Variables</a>
+section for more details.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--client-disconnect <var>cmd</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Like <tt class="docutils literal"><span class="pre">--client-connect</span></tt> but called on client instance shutdown. Will
+not be called unless the <tt class="docutils literal"><span class="pre">--client-connect</span></tt> script and plugins (if
+defined) were previously called on this instance with successful (0)
+status returns.</p>
+<p>The exception to this rule is if the <tt class="docutils literal"><span class="pre">--client-disconnect</span></tt> command or
+plugins are cascaded, and at least one client-connect function
+succeeded, then ALL of the client-disconnect functions for scripts and
+plugins will be called on client instance object deletion, even in cases
+where some of the related client-connect functions returned an error
+status.</p>
+<p class="last">The <tt class="docutils literal"><span class="pre">--client-disconnect</span></tt> command is passed the same pathname as the
+corresponding <tt class="docutils literal"><span class="pre">--client-connect</span></tt> command as its last argument (after
+any arguments specified in <tt class="docutils literal">cmd</tt>).</p>
+</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--down <var>cmd</var></span></kbd></td>
+<td><p class="first">Run command <tt class="docutils literal">cmd</tt> after TUN/TAP device close (post <tt class="docutils literal"><span class="pre">--user</span></tt> UID
+change and/or <tt class="docutils literal"><span class="pre">--chroot</span></tt> ). <tt class="docutils literal">cmd</tt> consists of a path to script (or
+executable program), optionally followed by arguments. The path and
+arguments may be single- or double-quoted and/or escaped using a
+backslash, and should be separated by one or more spaces.</p>
+<p>Called with the same parameters and environmental variables as the
+<tt class="docutils literal"><span class="pre">--up</span></tt> option above.</p>
+<p class="last">Note that if you reduce privileges by using <tt class="docutils literal"><span class="pre">--user</span></tt> and/or
+<tt class="docutils literal"><span class="pre">--group</span></tt>, your <tt class="docutils literal"><span class="pre">--down</span></tt> script will also run at reduced privilege.</p>
+</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--down-pre</span></kbd></td>
+<td>Call <tt class="docutils literal"><span class="pre">--down</span></tt> cmd/script before, rather than after, TUN/TAP close.</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--ipchange <var>cmd</var></span></kbd></td>
+<td><p class="first">Run command <tt class="docutils literal">cmd</tt> when our remote ip-address is initially
+authenticated or changes.</p>
+<p><tt class="docutils literal">cmd</tt> consists of a path to a script (or executable program), optionally
+followed by arguments. The path and arguments may be single- or
+double-quoted and/or escaped using a backslash, and should be separated
+by one or more spaces.</p>
+<p>When <tt class="docutils literal">cmd</tt> is executed two arguments are appended after any arguments
+specified in <tt class="docutils literal">cmd</tt> , as follows:</p>
+<pre class="literal-block">
+cmd ip address port number
+</pre>
+<p>Don't use <tt class="docutils literal"><span class="pre">--ipchange</span></tt> in <tt class="docutils literal"><span class="pre">--mode</span> server</tt> mode. Use a
+<tt class="docutils literal"><span class="pre">--client-connect</span></tt> script instead.</p>
+<p>See the <a class="reference internal" href="#environmental-variables">Environmental Variables</a> section below for additional
+parameters passed as environmental variables.</p>
+<p>If you are running in a dynamic IP address environment where the IP
+addresses of either peer could change without notice, you can use this
+script, for example, to edit the <code>/etc/hosts</code> file with the current
+address of the peer. The script will be run every time the remote peer
+changes its IP address.</p>
+<p class="last">Similarly if <em>our</em> IP address changes due to DHCP, we should configure
+our IP address change script (see man page for <tt class="docutils literal">dhcpcd</tt>(8)) to
+deliver a <tt class="docutils literal">SIGHUP</tt> or <tt class="docutils literal">SIGUSR1</tt> signal to OpenVPN. OpenVPN will
+then re-establish a connection with its most recently authenticated
+peer on its new IP address.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--learn-address <var>cmd</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Run command <tt class="docutils literal">cmd</tt> to validate client virtual addresses or routes.</p>
+<p><tt class="docutils literal">cmd</tt> consists of a path to a script (or executable program), optionally
+followed by arguments. The path and arguments may be single- or
+double-quoted and/or escaped using a backslash, and should be separated
+by one or more spaces.</p>
+<p>Three arguments will be appended to any arguments in <tt class="docutils literal">cmd</tt> as follows:</p>
+<dl class="docutils">
+<dt><code>$1</code> - [operation]</dt>
+<dd><code>&quot;add&quot;</code>, <code>&quot;update&quot;</code>, or <code>&quot;delete&quot;</code> based on whether
+or not the address is being added to, modified, or deleted from
+OpenVPN's internal routing table.</dd>
+<dt><code>$2</code> - [address]</dt>
+<dd>The address being learned or unlearned. This can be an IPv4 address
+such as <code>&quot;198.162.10.14&quot;</code>, an IPv4 subnet such as
+<code>&quot;198.162.10.0/24&quot;</code>, or an ethernet MAC address (when
+<tt class="docutils literal"><span class="pre">--dev</span> tap</tt> is being used) such as <code>&quot;00:FF:01:02:03:04&quot;</code>.</dd>
+<dt><code>$3</code> - [common name]</dt>
+<dd>The common name on the certificate associated with the client linked
+to this address. Only present for <code>&quot;add&quot;</code> or <code>&quot;update&quot;</code>
+operations, not <code>&quot;delete&quot;</code>.</dd>
+</dl>
+<p>On <code>&quot;add&quot;</code> or <code>&quot;update&quot;</code> methods, if the script returns
+a failure code (non-zero), OpenVPN will reject the address and will not
+modify its internal routing table.</p>
+<p class="last">Normally, the <tt class="docutils literal">cmd</tt> script will use the information provided above to
+set appropriate firewall entries on the VPN TUN/TAP interface. Since
+OpenVPN provides the association between virtual IP or MAC address and
+the client's authenticated common name, it allows a user-defined script
+to configure firewall access policies with regard to the client's
+high-level common name, rather than the low level client virtual
+addresses.</p>
+</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--route-up <var>cmd</var></span></kbd></td>
+<td><p class="first">Run command <tt class="docutils literal">cmd</tt> after routes are added, subject to <tt class="docutils literal"><span class="pre">--route-delay</span></tt>.</p>
+<p><tt class="docutils literal">cmd</tt> consists of a path to a script (or executable program), optionally
+followed by arguments. The path and arguments may be single- or
+double-quoted and/or escaped using a backslash, and should be separated
+by one or more spaces.</p>
+<p class="last">See the <a class="reference internal" href="#environmental-variables">Environmental Variables</a> section below for additional
+parameters passed as environmental variables.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--route-pre-down <var>cmd</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Run command <tt class="docutils literal">cmd</tt> before routes are removed upon disconnection.</p>
+<p><tt class="docutils literal">cmd</tt> consists of a path to a script (or executable program), optionally
+followed by arguments. The path and arguments may be single- or
+double-quoted and/or escaped using a backslash, and should be separated
+by one or more spaces.</p>
+<p class="last">See the <a class="reference internal" href="#environmental-variables">Environmental Variables</a> section below for additional
+parameters passed as environmental variables.</p>
+</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--setenv <var>args</var></span></kbd></td>
+<td><p class="first">Set a custom environmental variable <code>name=value</code> to pass to script.</p>
+<p>Valid syntaxes:</p>
+<pre class="literal-block">
+setenv name value
+setenv FORWARD_COMPATIBLE 1
+setenv opt config_option
+</pre>
+<p>By setting <code>FORWARD_COMPATIBLE</code> to <code>1</code>, the config file
+syntax checking is relaxed so that unknown directives will trigger a
+warning but not a fatal error, on the assumption that a given unknown
+directive might be valid in future OpenVPN versions.</p>
+<p>This option should be used with caution, as there are good security
+reasons for having OpenVPN fail if it detects problems in a config file.
+Having said that, there are valid reasons for wanting new software
+features to gracefully degrade when encountered by older software
+versions.</p>
+<p>It is also possible to tag a single directive so as not to trigger a
+fatal error if the directive isn't recognized. To do this, prepend the
+following before the directive: <tt class="docutils literal">setenv opt</tt></p>
+<p>Versions prior to OpenVPN 2.3.3 will always ignore options set with the
+<tt class="docutils literal">setenv opt</tt> directive.</p>
+<p class="last">See also <tt class="docutils literal"><span class="pre">--ignore-unknown-option</span></tt></p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--setenv-safe <var>args</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Set a custom environmental variable <code>OPENVPN_name</code> to <code>value</code>
+to pass to scripts.</p>
+<p>Valid syntaxes:</p>
+<pre class="literal-block">
+setenv-safe name value
+</pre>
+<p class="last">This directive is designed to be pushed by the server to clients, and
+the prepending of <code>OPENVPN_</code> to the environmental variable is a
+safety precaution to prevent a <code>LD_PRELOAD</code> style attack from a
+malicious or compromised server.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--tls-verify <var>cmd</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Run command <tt class="docutils literal">cmd</tt> to verify the X509 name of a pending TLS connection
+that has otherwise passed all other tests of certification (except for
+revocation via <tt class="docutils literal"><span class="pre">--crl-verify</span></tt> directive; the revocation test occurs
+after the <tt class="docutils literal"><span class="pre">--tls-verify</span></tt> test).</p>
+<p><tt class="docutils literal">cmd</tt> should return <code>0</code> to allow the TLS handshake to proceed,
+or <code>1</code> to fail.</p>
+<p><tt class="docutils literal">cmd</tt> consists of a path to a script (or executable program), optionally
+followed by arguments. The path and arguments may be single- or
+double-quoted and/or escaped using a backslash, and should be separated
+by one or more spaces.</p>
+<p>When <tt class="docutils literal">cmd</tt> is executed two arguments are appended after any arguments
+specified in <tt class="docutils literal">cmd</tt>, as follows:</p>
+<pre class="literal-block">
+cmd certificate_depth subject
+</pre>
+<p>These arguments are, respectively, the current certificate depth and the
+X509 subject distinguished name (dn) of the peer.</p>
+<p>This feature is useful if the peer you want to trust has a certificate
+which was signed by a certificate authority who also signed many other
+certificates, where you don't necessarily want to trust all of them, but
+rather be selective about which peer certificate you will accept. This
+feature allows you to write a script which will test the X509 name on a
+certificate and decide whether or not it should be accepted. For a
+simple perl script which will test the common name field on the
+certificate, see the file <tt class="docutils literal"><span class="pre">verify-cn</span></tt> in the OpenVPN distribution.</p>
+<p class="last">See the <a class="reference internal" href="#environmental-variables">Environmental Variables</a> section below for additional
+parameters passed as environmental variables.</p>
+</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--up <var>cmd</var></span></kbd></td>
+<td><p class="first">Run command <tt class="docutils literal">cmd</tt> after successful TUN/TAP device open (pre <tt class="docutils literal"><span class="pre">--user</span></tt>
+UID change).</p>
+<p><tt class="docutils literal">cmd</tt> consists of a path to a script (or executable program), optionally
+followed by arguments. The path and arguments may be single- or
+double-quoted and/or escaped using a backslash, and should be separated
+by one or more spaces.</p>
+<p>The up command is useful for specifying route commands which route IP
+traffic destined for private subnets which exist at the other end of the
+VPN connection into the tunnel.</p>
+<p>For <tt class="docutils literal"><span class="pre">--dev</span> tun</tt> execute as:</p>
+<pre class="literal-block">
+cmd tun_dev tun_mtu link_mtu ifconfig_local_ip ifconfig_remote_ip [init | restart]
+</pre>
+<p>For <tt class="docutils literal"><span class="pre">--dev</span> tap</tt> execute as:</p>
+<pre class="literal-block">
+cmd tap_dev tap_mtu link_mtu ifconfig_local_ip ifconfig_netmask [init | restart]
+</pre>
+<p>See the <a class="reference internal" href="#environmental-variables">Environmental Variables</a> section below for additional
+parameters passed as environmental variables.</p>
+<p>Note that if <tt class="docutils literal">cmd</tt> includes arguments, all OpenVPN-generated arguments
+will be appended to them to build an argument list with which the
+executable will be called.</p>
+<p>Typically, <tt class="docutils literal">cmd</tt> will run a script to add routes to the tunnel.</p>
+<p>Normally the up script is called after the TUN/TAP device is opened. In
+this context, the last command line parameter passed to the script will
+be <em>init.</em> If the <tt class="docutils literal"><span class="pre">--up-restart</span></tt> option is also used, the up script
+will be called for restarts as well. A restart is considered to be a
+partial reinitialization of OpenVPN where the TUN/TAP instance is
+preserved (the <tt class="docutils literal"><span class="pre">--persist-tun</span></tt> option will enable such preservation).
+A restart can be generated by a SIGUSR1 signal, a <tt class="docutils literal"><span class="pre">--ping-restart</span></tt>
+timeout, or a connection reset when the TCP protocol is enabled with the
+<tt class="docutils literal"><span class="pre">--proto</span></tt> option. If a restart occurs, and <tt class="docutils literal"><span class="pre">--up-restart</span></tt> has been
+specified, the up script will be called with <em>restart</em> as the last
+parameter.</p>
+<dl class="docutils">
+<dt><em>NOTE:</em></dt>
+<dd>On restart, OpenVPN will not pass the full set of environment
+variables to the script. Namely, everything related to routing and
+gateways will not be passed, as nothing needs to be done anyway - all
+the routing setup is already in place. Additionally, the up-restart
+script will run with the downgraded UID/GID settings (if configured).</dd>
+</dl>
+<p>The following standalone example shows how the <tt class="docutils literal"><span class="pre">--up</span></tt> script can be
+called in both an initialization and restart context. (<em>NOTE:</em> for
+security reasons, don't run the following example unless UDP port 9999
+is blocked by your firewall. Also, the example will run indefinitely, so
+you should abort with control-c).</p>
+<pre class="literal-block">
+openvpn --dev tun --port 9999 --verb 4 --ping-restart 10 \
+ --up 'echo up' --down 'echo down' --persist-tun \
+ --up-restart
+</pre>
+<p>Note that OpenVPN also provides the <tt class="docutils literal"><span class="pre">--ifconfig</span></tt> option to
+automatically ifconfig the TUN device, eliminating the need to define an
+<tt class="docutils literal"><span class="pre">--up</span></tt> script, unless you also want to configure routes in the
+<tt class="docutils literal"><span class="pre">--up</span></tt> script.</p>
+<p>If <tt class="docutils literal"><span class="pre">--ifconfig</span></tt> is also specified, OpenVPN will pass the ifconfig
+local and remote endpoints on the command line to the <tt class="docutils literal"><span class="pre">--up</span></tt> script so
+that they can be used to configure routes such as:</p>
+<pre class="last literal-block">
+route add -net 10.0.0.0 netmask 255.255.255.0 gw $5
+</pre>
+</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--up-delay</span></kbd></td>
+<td><p class="first">Delay TUN/TAP open and possible <tt class="docutils literal"><span class="pre">--up</span></tt> script execution until after
+TCP/UDP connection establishment with peer.</p>
+<p>In <tt class="docutils literal"><span class="pre">--proto</span> udp</tt> mode, this option normally requires the use of
+<tt class="docutils literal"><span class="pre">--ping</span></tt> to allow connection initiation to be sensed in the absence of
+tunnel data, since UDP is a &quot;connectionless&quot; protocol.</p>
+<p class="last">On Windows, this option will delay the TAP-Win32 media state
+transitioning to &quot;connected&quot; until connection establishment, i.e. the
+receipt of the first authenticated packet from the peer.</p>
+</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--up-restart</span></kbd></td>
+<td>Enable the <tt class="docutils literal"><span class="pre">--up</span></tt> and <tt class="docutils literal"><span class="pre">--down</span></tt> scripts to be called for restarts as
+well as initial program start. This option is described more fully above
+in the <tt class="docutils literal"><span class="pre">--up</span></tt> option documentation.</td></tr>
+</tbody>
+</table>
+</div>
+<div class="section" id="string-types-and-remapping">
+<h2>String Types and Remapping</h2>
+<p>In certain cases, OpenVPN will perform remapping of characters in
+strings. Essentially, any characters outside the set of permitted
+characters for each string type will be converted to underbar ('_').</p>
+<dl class="docutils">
+<dt><em>Q: Why is string remapping necessary?</em></dt>
+<dd>It's an important security feature to prevent the malicious
+coding of strings from untrusted sources to be passed as parameters to
+scripts, saved in the environment, used as a common name, translated to
+a filename, etc.</dd>
+<dt><em>Q: Can string remapping be disabled?</em></dt>
+<dd>Yes, by using the <tt class="docutils literal"><span class="pre">--no-name-remapping</span></tt> option, however this
+should be considered an advanced option.</dd>
+</dl>
+<p>Here is a brief rundown of OpenVPN's current string types and the
+permitted character class for each string:</p>
+<dl class="docutils">
+<dt><em>X509 Names</em></dt>
+<dd>Alphanumeric, underbar ('_'), dash ('-'), dot ('.'), at
+('&#64;'), colon (':'), slash ('/'), and equal ('='). Alphanumeric is
+defined as a character which will cause the C library isalnum() function
+to return true.</dd>
+<dt><em>Common Names</em></dt>
+<dd>Alphanumeric, underbar ('_'), dash ('-'), dot ('.'), and at ('&#64;').</dd>
+<dt><em>--auth-user-pass username</em></dt>
+<dd>Same as Common Name, with one exception:
+starting with OpenVPN 2.0.1, the username is passed to the
+<code>OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY</code> plugin in its raw form,
+without string remapping.</dd>
+<dt><em>--auth-user-pass password</em></dt>
+<dd>Any &quot;printable&quot; character except CR or LF. Printable is defined to be
+a character which will cause the C library isprint() function to
+return true.</dd>
+<dt><em>--client-config-dir filename as derived from common name or`username</em></dt>
+<dd>Alphanumeric, underbar ('_'), dash ('-'), and dot ('.') except for &quot;.&quot;
+or &quot;..&quot; as standalone strings. As of v2.0.1-rc6, the at ('&#64;') character
+has been added as well for compatibility with the common name character
+class.</dd>
+<dt><em>Environmental variable names</em></dt>
+<dd>Alphanumeric or underbar ('_').</dd>
+<dt><em>Environmental variable values</em></dt>
+<dd>Any printable character.</dd>
+</dl>
+<p>For all cases, characters in a string which are not members of the legal
+character class for that string type will be remapped to underbar
+('_').</p>
+</div>
+<div class="section" id="environmental-variables">
+<h2>Environmental Variables</h2>
+<p>Once set, a variable is persisted indefinitely until it is reset by a
+new value or a restart,</p>
+<p>As of OpenVPN 2.0-beta12, in server mode, environmental variables set by
+OpenVPN are scoped according to the client objects they are associated
+with, so there should not be any issues with scripts having access to
+stale, previously set variables which refer to different client
+instances.</p>
+<dl class="docutils">
+<dt><code>bytes_received</code></dt>
+<dd>Total number of bytes received from client during VPN session. Set prior
+to execution of the <tt class="docutils literal"><span class="pre">--client-disconnect</span></tt> script.</dd>
+<dt><code>bytes_sent</code></dt>
+<dd>Total number of bytes sent to client during VPN session. Set prior to
+execution of the <tt class="docutils literal"><span class="pre">--client-disconnect</span></tt> script.</dd>
+<dt><code>client_connect_config_file</code></dt>
+<dd>The path to the configuration file that should be written to by the
+<tt class="docutils literal"><span class="pre">--client-connect</span></tt> script (optional, if per-session configuration
+is desired). This is the same file name as passed via command line
+argument on the call to the <tt class="docutils literal"><span class="pre">--client-connect</span></tt> script.</dd>
+<dt><code>client_connect_deferred_file</code></dt>
+<dd><p class="first">This file can be optionally written to in order to to communicate a
+status code of the <tt class="docutils literal"><span class="pre">--client-connect</span></tt> script or plgin. Only the
+first character in the file is relevant. It must be either <code>1</code>
+to indicate normal script execution, <code>0</code> indicates an error (in
+the same way that a non zero exit status does) or <code>2</code> to indicate
+that the script deferred returning the config file.</p>
+<p>For deferred (background) handling, the script or plugin MUST write
+<code>2</code> to the file to indicate the deferral and then return with
+exit code <code>0</code> to signal <tt class="docutils literal">deferred handler started OK</tt>.</p>
+<p>A background process or similar must then take care of writing the
+configuration to the file indicated by the
+<code>client_connect_config_file</code> environment variable and when
+finished, write the a <code>1</code> to this file (or <code>0</code> in case of
+an error).</p>
+<p class="last">The absence of any character in the file when the script finishes
+executing is interpreted the same as <code>1</code>. This allows scripts
+that are not written to support the defer mechanism to be used
+unmodified.</p>
+</dd>
+<dt><code>common_name</code></dt>
+<dd>The X509 common name of an authenticated client. Set prior to execution
+of <tt class="docutils literal"><span class="pre">--client-connect</span></tt>, <tt class="docutils literal"><span class="pre">--client-disconnect</span></tt> and
+<tt class="docutils literal"><span class="pre">--auth-user-pass-verify</span></tt> scripts.</dd>
+<dt><code>config</code></dt>
+<dd>Name of first <tt class="docutils literal"><span class="pre">--config</span></tt> file. Set on program initiation and reset on
+SIGHUP.</dd>
+<dt><code>daemon</code></dt>
+<dd>Set to &quot;1&quot; if the <tt class="docutils literal"><span class="pre">--daemon</span></tt> directive is specified, or &quot;0&quot; otherwise.
+Set on program initiation and reset on SIGHUP.</dd>
+<dt><code>daemon_log_redirect</code></dt>
+<dd>Set to &quot;1&quot; if the <tt class="docutils literal"><span class="pre">--log</span></tt> or <tt class="docutils literal"><span class="pre">--log-append</span></tt> directives are
+specified, or &quot;0&quot; otherwise. Set on program initiation and reset on
+SIGHUP.</dd>
+<dt><code>dev</code></dt>
+<dd>The actual name of the TUN/TAP device, including a unit number if it
+exists. Set prior to <tt class="docutils literal"><span class="pre">--up</span></tt> or <tt class="docutils literal"><span class="pre">--down</span></tt> script execution.</dd>
+<dt><code>dev_idx</code></dt>
+<dd>On Windows, the device index of the TUN/TAP adapter (to be used in
+netsh.exe calls which sometimes just do not work right with interface
+names). Set prior to <tt class="docutils literal"><span class="pre">--up</span></tt> or <tt class="docutils literal"><span class="pre">--down</span></tt> script execution.</dd>
+<dt><code>foreign_option_{n}</code></dt>
+<dd>An option pushed via <tt class="docutils literal"><span class="pre">--push</span></tt> to a client which does not natively
+support it, such as <tt class="docutils literal"><span class="pre">--dhcp-option</span></tt> on a non-Windows system, will be
+recorded to this environmental variable sequence prior to <tt class="docutils literal"><span class="pre">--up</span></tt>
+script execution.</dd>
+<dt><code>ifconfig_broadcast</code></dt>
+<dd>The broadcast address for the virtual ethernet segment which is derived
+from the <tt class="docutils literal"><span class="pre">--ifconfig</span></tt> option when <tt class="docutils literal"><span class="pre">--dev</span> tap</tt> is used. Set prior to
+OpenVPN calling the <code>ifconfig</code> or <code>netsh</code> (windows version
+of ifconfig) commands which normally occurs prior to <tt class="docutils literal"><span class="pre">--up</span></tt> script
+execution.</dd>
+<dt><code>ifconfig_ipv6_local</code></dt>
+<dd>The local VPN endpoint IPv6 address specified in the
+<tt class="docutils literal"><span class="pre">--ifconfig-ipv6</span></tt> option (first parameter). Set prior to OpenVPN
+calling the <code>ifconfig</code> or code:<cite>netsh</cite> (windows version of
+ifconfig) commands which normally occurs prior to <tt class="docutils literal"><span class="pre">--up</span></tt> script
+execution.</dd>
+<dt><code>ifconfig_ipv6_netbits</code></dt>
+<dd>The prefix length of the IPv6 network on the VPN interface. Derived
+from the /nnn parameter of the IPv6 address in the <tt class="docutils literal"><span class="pre">--ifconfig-ipv6</span></tt>
+option (first parameter). Set prior to OpenVPN calling the
+<code>ifconfig</code> or <code>netsh</code> (windows version of ifconfig)
+commands which normally occurs prior to <tt class="docutils literal"><span class="pre">--up</span></tt> script execution.</dd>
+<dt><code>ifconfig_ipv6_remote</code></dt>
+<dd>The remote VPN endpoint IPv6 address specified in the
+<tt class="docutils literal"><span class="pre">--ifconfig-ipv6</span></tt> option (second parameter). Set prior to OpenVPN
+calling the <code>ifconfig</code> or <code>netsh</code> (windows version of
+ifconfig) commands which normally occurs prior to <tt class="docutils literal"><span class="pre">--up</span></tt> script
+execution.</dd>
+<dt><code>ifconfig_local</code></dt>
+<dd>The local VPN endpoint IP address specified in the <tt class="docutils literal"><span class="pre">--ifconfig</span></tt>
+option (first parameter). Set prior to OpenVPN calling the
+<code>ifconfig</code> or <code>netsh</code> (windows version of ifconfig)
+commands which normally occurs prior to <tt class="docutils literal"><span class="pre">--up</span></tt> script execution.</dd>
+<dt><code>ifconfig_remote</code></dt>
+<dd>The remote VPN endpoint IP address specified in the <tt class="docutils literal"><span class="pre">--ifconfig</span></tt>
+option (second parameter) when <tt class="docutils literal"><span class="pre">--dev</span> tun</tt> is used. Set prior to
+OpenVPN calling the <code>ifconfig</code> or <code>netsh</code> (windows version
+of ifconfig) commands which normally occurs prior to <tt class="docutils literal"><span class="pre">--up</span></tt> script
+execution.</dd>
+<dt><code>ifconfig_netmask</code></dt>
+<dd>The subnet mask of the virtual ethernet segment that is specified as
+the second parameter to <tt class="docutils literal"><span class="pre">--ifconfig</span></tt> when <tt class="docutils literal"><span class="pre">--dev</span> tap</tt> is being
+used. Set prior to OpenVPN calling the <code>ifconfig</code> or
+<code>netsh</code> (windows version of ifconfig) commands which normally
+occurs prior to <tt class="docutils literal"><span class="pre">--up</span></tt> script execution.</dd>
+<dt><code>ifconfig_pool_local_ip</code></dt>
+<dd>The local virtual IP address for the TUN/TAP tunnel taken from an
+<tt class="docutils literal"><span class="pre">--ifconfig-push</span></tt> directive if specified, or otherwise from the
+ifconfig pool (controlled by the <tt class="docutils literal"><span class="pre">--ifconfig-pool</span></tt> config file
+directive). Only set for <tt class="docutils literal"><span class="pre">--dev</span> tun</tt> tunnels. This option is set on
+the server prior to execution of the <tt class="docutils literal"><span class="pre">--client-connect</span></tt> and
+<tt class="docutils literal"><span class="pre">--client-disconnect</span></tt> scripts.</dd>
+<dt><code>ifconfig_pool_netmask</code></dt>
+<dd>The virtual IP netmask for the TUN/TAP tunnel taken from an
+<tt class="docutils literal"><span class="pre">--ifconfig-push</span></tt> directive if specified, or otherwise from the
+ifconfig pool (controlled by the <tt class="docutils literal"><span class="pre">--ifconfig-pool</span></tt> config file
+directive). Only set for <tt class="docutils literal"><span class="pre">--dev</span> tap</tt> tunnels. This option is set on
+the server prior to execution of the <tt class="docutils literal"><span class="pre">--client-connect</span></tt> and
+<tt class="docutils literal"><span class="pre">--client-disconnect</span></tt> scripts.</dd>
+<dt><code>ifconfig_pool_remote_ip</code></dt>
+<dd>The remote virtual IP address for the TUN/TAP tunnel taken from an
+<tt class="docutils literal"><span class="pre">--ifconfig-push</span></tt> directive if specified, or otherwise from the
+ifconfig pool (controlled by the <tt class="docutils literal"><span class="pre">--ifconfig-pool</span></tt> config file
+directive). This option is set on the server prior to execution of the
+<tt class="docutils literal"><span class="pre">--client-connect</span></tt> and <tt class="docutils literal"><span class="pre">--client-disconnect</span></tt> scripts.</dd>
+<dt><code>link_mtu</code></dt>
+<dd>The maximum packet size (not including the IP header) of tunnel data in
+UDP tunnel transport mode. Set prior to <tt class="docutils literal"><span class="pre">--up</span></tt> or <tt class="docutils literal"><span class="pre">--down</span></tt> script
+execution.</dd>
+<dt><code>local</code></dt>
+<dd>The <tt class="docutils literal"><span class="pre">--local</span></tt> parameter. Set on program initiation and reset on
+SIGHUP.</dd>
+<dt><code>local_port</code></dt>
+<dd>The local port number or name, specified by <tt class="docutils literal"><span class="pre">--port</span></tt> or <tt class="docutils literal"><span class="pre">--lport</span></tt>.
+Set on program initiation and reset on SIGHUP.</dd>
+<dt><code>password</code></dt>
+<dd>The password provided by a connecting client. Set prior to
+<tt class="docutils literal"><span class="pre">--auth-user-pass-verify</span></tt> script execution only when the <tt class="docutils literal"><span class="pre">via-env</span></tt>
+modifier is specified, and deleted from the environment after the script
+returns.</dd>
+<dt><code>proto</code></dt>
+<dd>The <tt class="docutils literal"><span class="pre">--proto</span></tt> parameter. Set on program initiation and reset on
+SIGHUP.</dd>
+<dt><code>remote_{n}</code></dt>
+<dd>The <tt class="docutils literal"><span class="pre">--remote</span></tt> parameter. Set on program initiation and reset on
+SIGHUP.</dd>
+<dt><code>remote_port_{n}</code></dt>
+<dd>The remote port number, specified by <tt class="docutils literal"><span class="pre">--port</span></tt> or <tt class="docutils literal"><span class="pre">--rport</span></tt>. Set on
+program initiation and reset on SIGHUP.</dd>
+<dt><code>route_net_gateway</code></dt>
+<dd>The pre-existing default IP gateway in the system routing table. Set
+prior to <tt class="docutils literal"><span class="pre">--up</span></tt> script execution.</dd>
+<dt><code>route_vpn_gateway</code></dt>
+<dd>The default gateway used by <tt class="docutils literal"><span class="pre">--route</span></tt> options, as specified in either
+the <tt class="docutils literal"><span class="pre">--route-gateway</span></tt> option or the second parameter to
+<tt class="docutils literal"><span class="pre">--ifconfig</span></tt> when <tt class="docutils literal"><span class="pre">--dev</span> tun</tt> is specified. Set prior to <tt class="docutils literal"><span class="pre">--up</span></tt>
+script execution.</dd>
+<dt><code>route_{parm}_{n}</code></dt>
+<dd><p class="first">A set of variables which define each route to be added, and are set
+prior to <tt class="docutils literal"><span class="pre">--up</span></tt> script execution.</p>
+<p><tt class="docutils literal">parm</tt> will be one of <code>network</code>, <code>netmask&quot;</code>,
+<code>gateway</code>, or <code>metric</code>.</p>
+<p><tt class="docutils literal">n</tt> is the OpenVPN route number, starting from 1.</p>
+<p class="last">If the network or gateway are resolvable DNS names, their IP address
+translations will be recorded rather than their names as denoted on the
+command line or configuration file.</p>
+</dd>
+<dt><code>route_ipv6_{parm}_{n}</code></dt>
+<dd><p class="first">A set of variables which define each IPv6 route to be added, and are
+set prior to <strong>--up</strong> script execution.</p>
+<p><tt class="docutils literal">parm</tt> will be one of <code>network</code> or <code>gateway</code>
+(<code>netmask</code> is contained as <code>/nnn</code> in the
+<tt class="docutils literal">route_ipv6_network_{n}</tt>, unlike IPv4 where it is passed in a
+separate environment variable).</p>
+<p><tt class="docutils literal">n</tt> is the OpenVPN route number, starting from 1.</p>
+<p class="last">If the network or gateway are resolvable DNS names, their IP address
+translations will be recorded rather than their names as denoted on the
+command line or configuration file.</p>
+</dd>
+<dt><code>peer_cert</code></dt>
+<dd>Temporary file name containing the client certificate upon connection.
+Useful in conjunction with <tt class="docutils literal"><span class="pre">--tls-verify</span></tt>.</dd>
+<dt><code>script_context</code></dt>
+<dd>Set to &quot;init&quot; or &quot;restart&quot; prior to up/down script execution. For more
+information, see documentation for <tt class="docutils literal"><span class="pre">--up</span></tt>.</dd>
+<dt><code>script_type</code></dt>
+<dd>Prior to execution of any script, this variable is set to the type of
+script being run. It can be one of the following: <code>up</code>,
+<code>down</code>, <code>ipchange</code>, <code>route-up</code>, <code>tls-verify</code>,
+<code>auth-user-pass-verify</code>, <code>client-connect</code>,
+<code>client-disconnect</code> or <code>learn-address</code>. Set prior to
+execution of any script.</dd>
+<dt><code>signal</code></dt>
+<dd>The reason for exit or restart. Can be one of <code>sigusr1</code>,
+<code>sighup</code>, <code>sigterm</code>, <code>sigint</code>, <code>inactive</code>
+(controlled by <tt class="docutils literal"><span class="pre">--inactive</span></tt> option), <code>ping-exit</code> (controlled
+by <tt class="docutils literal"><span class="pre">--ping-exit</span></tt> option), <code>ping-restart</code> (controlled by
+<tt class="docutils literal"><span class="pre">--ping-restart</span></tt> option), <code>connection-reset</code> (triggered on TCP
+connection reset), <code>error</code> or <code>unknown</code> (unknown signal).
+This variable is set just prior to down script execution.</dd>
+<dt><code>time_ascii</code></dt>
+<dd>Client connection timestamp, formatted as a human-readable time string.
+Set prior to execution of the <tt class="docutils literal"><span class="pre">--client-connect</span></tt> script.</dd>
+<dt><code>time_duration</code></dt>
+<dd>The duration (in seconds) of the client session which is now
+disconnecting. Set prior to execution of the <tt class="docutils literal"><span class="pre">--client-disconnect</span></tt>
+script.</dd>
+<dt><code>time_unix</code></dt>
+<dd>Client connection timestamp, formatted as a unix integer date/time
+value. Set prior to execution of the <tt class="docutils literal"><span class="pre">--client-connect</span></tt> script.</dd>
+<dt><code>tls_digest_{n}</code> / <code>tls_digest_sha256_{n}</code></dt>
+<dd>Contains the certificate SHA1 / SHA256 fingerprint, where <tt class="docutils literal">n</tt> is the
+verification level. Only set for TLS connections. Set prior to execution
+of <tt class="docutils literal"><span class="pre">--tls-verify</span></tt> script.</dd>
+<dt><code>tls_id_{n}</code></dt>
+<dd>A series of certificate fields from the remote peer, where <tt class="docutils literal">n</tt> is the
+verification level. Only set for TLS connections. Set prior to execution
+of <tt class="docutils literal"><span class="pre">--tls-verify</span></tt> script.</dd>
+<dt><code>tls_serial_{n}</code></dt>
+<dd>The serial number of the certificate from the remote peer, where <tt class="docutils literal">n</tt>
+is the verification level. Only set for TLS connections. Set prior to
+execution of <tt class="docutils literal"><span class="pre">--tls-verify</span></tt> script. This is in the form of a decimal
+string like &quot;933971680&quot;, which is suitable for doing serial-based OCSP
+queries (with OpenSSL, do not prepend &quot;0x&quot; to the string) If something
+goes wrong while reading the value from the certificate it will be an
+empty string, so your code should check that. See the
+<code>contrib/OCSP_check/OCSP_check.sh</code> script for an example.</dd>
+<dt><code>tls_serial_hex_{n}</code></dt>
+<dd>Like <code>tls_serial_{n}</code>, but in hex form (e.g.
+<code>12:34:56:78:9A</code>).</dd>
+<dt><code>tun_mtu</code></dt>
+<dd>The MTU of the TUN/TAP device. Set prior to <tt class="docutils literal"><span class="pre">--up</span></tt> or <tt class="docutils literal"><span class="pre">--down</span></tt>
+script execution.</dd>
+<dt><code>trusted_ip</code> / <code>trusted_ip6</code>)</dt>
+<dd>Actual IP address of connecting client or peer which has been
+authenticated. Set prior to execution of <tt class="docutils literal"><span class="pre">--ipchange</span></tt>,
+<tt class="docutils literal"><span class="pre">--client-connect</span></tt> and <tt class="docutils literal"><span class="pre">--client-disconnect</span></tt> scripts. If using ipv6
+endpoints (udp6, tcp6), <code>trusted_ip6</code> will be set instead.</dd>
+<dt><code>trusted_port</code></dt>
+<dd>Actual port number of connecting client or peer which has been
+authenticated. Set prior to execution of <tt class="docutils literal"><span class="pre">--ipchange</span></tt>,
+<tt class="docutils literal"><span class="pre">--client-connect</span></tt> and <tt class="docutils literal"><span class="pre">--client-disconnect</span></tt> scripts.</dd>
+<dt><code>untrusted_ip</code> / <code>untrusted_ip6</code></dt>
+<dd>Actual IP address of connecting client or peer which has not been
+authenticated yet. Sometimes used to <em>nmap</em> the connecting host in a
+<tt class="docutils literal"><span class="pre">--tls-verify</span></tt> script to ensure it is firewalled properly. Set prior
+to execution of <tt class="docutils literal"><span class="pre">--tls-verify</span></tt> and <tt class="docutils literal"><span class="pre">--auth-user-pass-verify</span></tt>
+scripts. If using ipv6 endpoints (udp6, tcp6), <code>untrusted_ip6</code>
+will be set instead.</dd>
+<dt><code>untrusted_port</code></dt>
+<dd>Actual port number of connecting client or peer which has not been
+authenticated yet. Set prior to execution of <tt class="docutils literal"><span class="pre">--tls-verify</span></tt> and
+<tt class="docutils literal"><span class="pre">--auth-user-pass-verify</span></tt> scripts.</dd>
+<dt><code>username</code></dt>
+<dd>The username provided by a connecting client. Set prior to
+<tt class="docutils literal"><span class="pre">--auth-user-pass-verify</span></tt> script execution only when the
+<code>via-env</code> modifier is specified.</dd>
+<dt><code>X509_{n}_{subject_field}</code></dt>
+<dd><p class="first">An X509 subject field from the remote peer certificate, where <tt class="docutils literal">n</tt> is
+the verification level. Only set for TLS connections. Set prior to
+execution of <tt class="docutils literal"><span class="pre">--tls-verify</span></tt> script. This variable is similar to
+<code>tls_id_{n}</code> except the component X509 subject fields are broken
+out, and no string remapping occurs on these field values (except for
+remapping of control characters to &quot;<code>_</code>&quot;). For example, the
+following variables would be set on the OpenVPN server using the sample
+client certificate in sample-keys (client.crt). Note that the
+verification level is 0 for the client certificate and 1 for the CA
+certificate.</p>
+<pre class="last literal-block">
+X509_0_emailAddress=me&#64;myhost.mydomain
+X509_0_CN=Test-Client
+X509_0_O=OpenVPN-TEST
+X509_0_ST=NA
+X509_0_C=KG
+X509_1_emailAddress=me&#64;myhost.mydomain
+X509_1_O=OpenVPN-TEST
+X509_1_L=BISHKEK
+X509_1_ST=NA
+X509_1_C=KG
+</pre>
+</dd>
+</dl>
+</div>
+<div class="section" id="management-interface-options">
+<h2>Management Interface Options</h2>
+<p>OpenVPN provides a feature rich socket based management interface for both
+server and client mode operations.</p>
+<table class="docutils option-list" frame="void" rules="none">
+<col class="option" />
+<col class="description" />
+<tbody valign="top">
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--management <var>args</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Enable a management server on a <tt class="docutils literal"><span class="pre">socket-name</span></tt> Unix socket on those
+platforms supporting it, or on a designated TCP port.</p>
+<p>Valid syntaxes:</p>
+<pre class="literal-block">
+management socket-name unix #
+management socket-name unix pw-file # (recommended)
+management IP port # (INSECURE)
+management IP port pw-file #
+</pre>
+<p><tt class="docutils literal"><span class="pre">pw-file</span></tt>, if specified, is a password file where the password must
+be on first line. Instead of a filename it can use the keyword stdin
+which will prompt the user for a password to use when OpenVPN is
+starting.</p>
+<p>For unix sockets, the default behaviour is to create a unix domain
+socket that may be connected to by any process. Use the
+<tt class="docutils literal"><span class="pre">--management-client-user</span></tt> and <tt class="docutils literal"><span class="pre">--management-client-group</span></tt>
+directives to restrict access.</p>
+<p>The management interface provides a special mode where the TCP
+management link can operate over the tunnel itself. To enable this mode,
+set IP to <tt class="docutils literal">tunnel</tt>. Tunnel mode will cause the management interface to
+listen for a TCP connection on the local VPN address of the TUN/TAP
+interface.</p>
+<p><strong>*BEWARE*</strong> of enabling the management interface over TCP. In these cases
+you should <em>ALWAYS</em> make use of <tt class="docutils literal"><span class="pre">pw-file</span></tt> to password protect the
+management interface. Any user who can connect to this TCP <tt class="docutils literal">IP:port</tt>
+will be able to manage and control (and interfere with) the OpenVPN
+process. It is also strongly recommended to set IP to 127.0.0.1
+(localhost) to restrict accessibility of the management server to local
+clients.</p>
+<p>While the management port is designed for programmatic control of
+OpenVPN by other applications, it is possible to telnet to the port,
+using a telnet client in &quot;raw&quot; mode. Once connected, type <code>help</code>
+for a list of commands.</p>
+<p class="last">For detailed documentation on the management interface, see the
+<em>management-notes.txt</em> file in the management folder of the OpenVPN
+source distribution.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--management-client</span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Management interface will connect as a TCP/unix domain client to
+<tt class="docutils literal">IP:port</tt> specified by <tt class="docutils literal"><span class="pre">--management</span></tt> rather than listen as a TCP
+server or on a unix domain socket.</p>
+<p class="last">If the client connection fails to connect or is disconnected, a SIGTERM
+signal will be generated causing OpenVPN to quit.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--management-client-auth</span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td>Gives management interface client the responsibility to authenticate
+clients after their client certificate has been verified. See
+<code>management-notes.txt</code> in OpenVPN distribution for detailed notes.</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--management-client-group <var>g</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td>When the management interface is listening on a unix domain socket, only
+allow connections from group <tt class="docutils literal">g</tt>.</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--management-client-pf</span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td>Management interface clients must specify a packet filter file for each
+connecting client. See <code>management-notes.txt</code> in OpenVPN
+distribution for detailed notes.</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--management-client-user <var>u</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td>When the management interface is listening on a unix domain socket, only
+allow connections from user <tt class="docutils literal">u</tt>.</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--management-external-cert <var>certificate-hint</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td>Allows usage for external certificate instead of <tt class="docutils literal"><span class="pre">--cert</span></tt> option
+(client-only). <tt class="docutils literal"><span class="pre">certificate-hint</span></tt> is an arbitrary string which is
+passed to a management interface client as an argument of
+<em>NEED-CERTIFICATE</em> notification. Requires <tt class="docutils literal"><span class="pre">--management-external-key</span></tt>.</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--management-external-key <var>args</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Allows usage for external private key file instead of <tt class="docutils literal"><span class="pre">--key</span></tt> option
+(client-only).</p>
+<p>Valid syntaxes:</p>
+<pre class="literal-block">
+management-external-key
+management-external-key nopadding
+management-external-key pkcs1
+management-external-key nopadding pkcs1
+</pre>
+<p class="last">The optional parameters <code>nopadding</code> and <code>pkcs1</code> signal
+support for different padding algorithms. See
+<code>doc/mangement-notes.txt</code> for a complete description of this
+feature.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--management-forget-disconnect</span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Make OpenVPN forget passwords when management session disconnects.</p>
+<p class="last">This directive does not affect the <tt class="docutils literal"><span class="pre">--http-proxy</span></tt> username/password.
+It is always cached.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--management-hold</span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td>Start OpenVPN in a hibernating state, until a client of the management
+interface explicitly starts it with the <code>hold release</code> command.</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--management-log-cache <var>n</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td>Cache the most recent <tt class="docutils literal">n</tt> lines of log file history for usage by the
+management channel.</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--management-query-passwords</span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td>Query management channel for private key password and
+<tt class="docutils literal"><span class="pre">--auth-user-pass</span></tt> username/password. Only query the management
+channel for inputs which ordinarily would have been queried from the
+console.</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--management-query-proxy</span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td>Query management channel for proxy server information for a specific
+<tt class="docutils literal"><span class="pre">--remote</span></tt> (client-only).</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--management-query-remote</span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td>Allow management interface to override <tt class="docutils literal"><span class="pre">--remote</span></tt> directives
+(client-only).</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--management-signal</span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td>Send SIGUSR1 signal to OpenVPN if management session disconnects. This
+is useful when you wish to disconnect an OpenVPN session on user logoff.
+For <tt class="docutils literal"><span class="pre">--management-client</span></tt> this option is not needed since a disconnect
+will always generate a <code>SIGTERM</code>.</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--management-up-down</span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td>Report tunnel up/down events to management interface.</td></tr>
+</tbody>
+</table>
+</div>
+<div class="section" id="plug-in-interface-options">
+<h2>Plug-in Interface Options</h2>
+<p>OpenVPN can be extended by loading external plug-in modules at runtime. These
+plug-ins must be prebuilt and adhere to the OpenVPN Plug-In API.</p>
+<table class="docutils option-list" frame="void" rules="none">
+<col class="option" />
+<col class="description" />
+<tbody valign="top">
+<tr><td class="option-group">
+<kbd><span class="option">--plugin <var>args</var></span></kbd></td>
+<td><p class="first">Loads an OpenVPN plug-in module.</p>
+<p>Valid syntax:</p>
+<pre class="literal-block">
+plugin module-name
+plugin module-name &quot;arguments&quot;
+</pre>
+<p>The <tt class="docutils literal"><span class="pre">module-name</span></tt> needs to be the first
+argument, indicating the plug-in to load. The second argument is an
+optional init string which will be passed directly to the plug-in.
+If the init consists of multiple arguments it must be enclosed in
+double-quotes (&quot;). Multiple plugin modules may be loaded into one
+OpenVPN process.</p>
+<p>The <tt class="docutils literal"><span class="pre">module-name</span></tt> argument can be just a filename or a filename
+with a relative or absolute path. The format of the filename and path
+defines if the plug-in will be loaded from a default plug-in directory
+or outside this directory.</p>
+<pre class="literal-block">
+--plugin path Effective directory used
+===================== =============================
+ myplug.so DEFAULT_DIR/myplug.so
+ subdir/myplug.so DEFAULT_DIR/subdir/myplug.so
+ ./subdir/myplug.so CWD/subdir/myplug.so
+ /usr/lib/my/plug.so /usr/lib/my/plug.so
+</pre>
+<p><tt class="docutils literal">DEFAULT_DIR</tt> is replaced by the default plug-in directory, which is
+configured at the build time of OpenVPN. <tt class="docutils literal">CWD</tt> is the current directory
+where OpenVPN was started or the directory OpenVPN have switched into
+via the <tt class="docutils literal"><span class="pre">--cd</span></tt> option before the <tt class="docutils literal"><span class="pre">--plugin</span></tt> option.</p>
+<p>For more information and examples on how to build OpenVPN plug-in
+modules, see the README file in the <tt class="docutils literal">plugin</tt> folder of the OpenVPN
+source distribution.</p>
+<p>If you are using an RPM install of OpenVPN, see
+<code>/usr/share/openvpn/plugin</code>. The documentation is in <tt class="docutils literal">doc</tt> and
+the actual plugin modules are in <tt class="docutils literal">lib</tt>.</p>
+<p class="last">Multiple plugin modules can be cascaded, and modules can be used in
+tandem with scripts. The modules will be called by OpenVPN in the order
+that they are declared in the config file. If both a plugin and script
+are configured for the same callback, the script will be called last. If
+the return code of the module/script controls an authentication function
+(such as tls-verify, auth-user-pass-verify, or client-connect), then
+every module and script must return success (<code>0</code>) in order for the
+connection to be authenticated.</p>
+</td></tr>
+</tbody>
+</table>
+</div>
+<div class="section" id="windows-specific-options">
+<h2>Windows-Specific Options</h2>
+<table class="docutils option-list" frame="void" rules="none">
+<col class="option" />
+<col class="description" />
+<tbody valign="top">
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--allow-nonadmin <var>TAP-adapter</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td>(Standalone) Set <tt class="docutils literal"><span class="pre">TAP-adapter</span></tt> to allow access from non-administrative
+accounts. If <tt class="docutils literal"><span class="pre">TAP-adapter</span></tt> is omitted, all TAP adapters on the system
+will be configured to allow non-admin access. The non-admin access
+setting will only persist for the length of time that the TAP-Win32
+device object and driver remain loaded, and will need to be re-enabled
+after a reboot, or if the driver is unloaded and reloaded. This
+directive can only be used by an administrator.</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--block-outside-dns</span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Block DNS servers on other network adapters to prevent DNS leaks. This
+option prevents any application from accessing TCP or UDP port 53 except
+one inside the tunnel. It uses Windows Filtering Platform (WFP) and
+works on Windows Vista or later.</p>
+<p class="last">This option is considered unknown on non-Windows platforms and
+unsupported on Windows XP, resulting in fatal error. You may want to use
+<tt class="docutils literal"><span class="pre">--setenv</span> opt</tt> or <tt class="docutils literal"><span class="pre">--ignore-unknown-option</span></tt> (not suitable for
+Windows XP) to ignore said error. Note that pushing unknown options from
+server does not trigger fatal errors.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--cryptoapicert <var>select-string</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first"><em>(Windows/OpenSSL Only)</em> Load the certificate and private key from the
+Windows Certificate System Store.</p>
+<p>Use this option instead of <tt class="docutils literal"><span class="pre">--cert</span></tt> and <tt class="docutils literal"><span class="pre">--key</span></tt>.</p>
+<p>This makes it possible to use any smart card, supported by Windows, but
+also any kind of certificate, residing in the Cert Store, where you have
+access to the private key. This option has been tested with a couple of
+different smart cards (GemSAFE, Cryptoflex, and Swedish Post Office eID)
+on the client side, and also an imported PKCS12 software certificate on
+the server side.</p>
+<p>To select a certificate, based on a substring search in the
+certificate's subject:</p>
+<pre class="literal-block">
+cryptoapicert &quot;SUBJ:Peter Runestig&quot;
+</pre>
+<p>To select a certificate, based on certificate's thumbprint:</p>
+<pre class="literal-block">
+cryptoapicert &quot;THUMB:f6 49 24 41 01 b4 ...&quot;
+</pre>
+<p class="last">The thumbprint hex string can easily be copy-and-pasted from the Windows
+Certificate Store GUI.</p>
+</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--dhcp-release</span></kbd></td>
+<td>Ask Windows to release the TAP adapter lease on shutdown. This option
+has no effect now, as it is enabled by default starting with
+OpenVPN 2.4.1.</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--dhcp-renew</span></kbd></td>
+<td>Ask Windows to renew the TAP adapter lease on startup. This option is
+normally unnecessary, as Windows automatically triggers a DHCP
+renegotiation on the TAP adapter when it comes up, however if you set
+the TAP-Win32 adapter Media Status property to &quot;Always Connected&quot;, you
+may need this flag.</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--ip-win32 <var>method</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">When using <tt class="docutils literal"><span class="pre">--ifconfig</span></tt> on Windows, set the TAP-Win32 adapter IP
+address and netmask using <tt class="docutils literal">method</tt>. Don't use this option unless you
+are also using <tt class="docutils literal"><span class="pre">--ifconfig</span></tt>.</p>
+<dl class="last docutils">
+<dt><code>manual</code></dt>
+<dd>Don't set the IP address or netmask automatically. Instead
+output a message to the console telling the user to configure the
+adapter manually and indicating the IP/netmask which OpenVPN
+expects the adapter to be set to.</dd>
+<dt><code>dynamic [offset] [lease-time]</code></dt>
+<dd><p class="first">Automatically set the IP address and netmask by replying to DHCP
+query messages generated by the kernel. This mode is probably the
+&quot;cleanest&quot; solution for setting the TCP/IP properties since it
+uses the well-known DHCP protocol. There are, however, two
+prerequisites for using this mode:</p>
+<ol class="arabic simple">
+<li>The TCP/IP properties for the TAP-Win32 adapter must be set
+to &quot;Obtain an IP address automatically&quot;, and</li>
+<li>OpenVPN needs to claim an IP address in the subnet for use
+as the virtual DHCP server address.</li>
+</ol>
+<p>By default in <tt class="docutils literal"><span class="pre">--dev</span> tap</tt> mode, OpenVPN will take the normally
+unused first address in the subnet. For example, if your subnet is
+<code>192.168.4.0 netmask 255.255.255.0</code>, then OpenVPN will take
+the IP address <code>192.168.4.0</code> to use as the virtual DHCP
+server address. In <tt class="docutils literal"><span class="pre">--dev</span> tun</tt> mode, OpenVPN will cause the DHCP
+server to masquerade as if it were coming from the remote endpoint.</p>
+<p>The optional offset parameter is an integer which is &gt; <code>-256</code>
+and &lt; <code>256</code> and which defaults to -1. If offset is positive,
+the DHCP server will masquerade as the IP address at network
+address + offset. If offset is negative, the DHCP server will
+masquerade as the IP address at broadcast address + offset.</p>
+<p>The Windows <code>ipconfig /all</code> command can be used to show what
+Windows thinks the DHCP server address is. OpenVPN will &quot;claim&quot;
+this address, so make sure to use a free address. Having said that,
+different OpenVPN instantiations, including different ends of
+the same connection, can share the same virtual DHCP server
+address.</p>
+<p class="last">The <tt class="docutils literal"><span class="pre">lease-time</span></tt> parameter controls the lease time of the DHCP
+assignment given to the TAP-Win32 adapter, and is denoted in
+seconds. Normally a very long lease time is preferred because it
+prevents routes involving the TAP-Win32 adapter from being lost
+when the system goes to sleep. The default lease time is one year.</p>
+</dd>
+<dt><code>netsh</code></dt>
+<dd>Automatically set the IP address and netmask using the Windows
+command-line &quot;netsh&quot; command. This method appears to work correctly
+on Windows XP but not Windows 2000.</dd>
+<dt><code>ipapi</code></dt>
+<dd>Automatically set the IP address and netmask using the Windows IP
+Helper API. This approach does not have ideal semantics, though
+testing has indicated that it works okay in practice. If you use
+this option, it is best to leave the TCP/IP properties for the
+TAP-Win32 adapter in their default state, i.e. &quot;Obtain an IP
+address automatically.&quot;</dd>
+<dt><code>adaptive</code> (Default)</dt>
+<dd><p class="first">Try <code>dynamic</code> method initially and fail over to <code>netsh</code>
+if the DHCP negotiation with the TAP-Win32 adapter does not succeed
+in 20 seconds. Such failures have been known to occur when certain
+third-party firewall packages installed on the client machine block
+the DHCP negotiation used by the TAP-Win32 adapter. Note that if
+the <code>netsh</code> failover occurs, the TAP-Win32 adapter TCP/IP
+properties will be reset from DHCP to static, and this will cause
+future OpenVPN startups using the <code>adaptive</code> mode to use
+<code>netsh</code> immediately, rather than trying <code>dynamic</code> first.</p>
+<p class="last">To &quot;unstick&quot; the <code>adaptive</code> mode from using <code>netsh</code>,
+run OpenVPN at least once using the <code>dynamic</code> mode to restore
+the TAP-Win32 adapter TCP/IP properties to a DHCP configuration.</p>
+</dd>
+</dl>
+</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--pause-exit</span></kbd></td>
+<td>Put up a &quot;press any key to continue&quot; message on the console prior to
+OpenVPN program exit. This option is automatically used by the Windows
+explorer when OpenVPN is run on a configuration file using the
+right-click explorer menu.</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--register-dns</span></kbd></td>
+<td>Run <code>ipconfig /flushdns</code> and <code>ipconfig /registerdns</code> on
+connection initiation. This is known to kick Windows into recognizing
+pushed DNS servers.</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--route-method <var>m</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Which method <tt class="docutils literal">m</tt> to use for adding routes on Windows?</p>
+<dl class="last docutils">
+<dt><code>adaptive</code> (default)</dt>
+<dd>Try IP helper API first. If that fails, fall back to the route.exe
+shell command.</dd>
+<dt><code>ipapi</code></dt>
+<dd>Use IP helper API.</dd>
+<dt><code>exe</code></dt>
+<dd>Call the route.exe shell command.</dd>
+</dl>
+</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--service <var>args</var></span></kbd></td>
+<td><p class="first">Should be used when OpenVPN is being automatically executed by another
+program in such a context that no interaction with the user via display
+or keyboard is possible.</p>
+<p>Valid syntax:</p>
+<pre class="literal-block">
+service exit-event [0|1]
+</pre>
+<p>In general, end-users should never need to explicitly use this option,
+as it is automatically added by the OpenVPN service wrapper when a given
+OpenVPN configuration is being run as a service.</p>
+<p><tt class="docutils literal"><span class="pre">exit-event</span></tt> is the name of a Windows global event object, and OpenVPN
+will continuously monitor the state of this event object and exit when
+it becomes signaled.</p>
+<p>The second parameter indicates the initial state of <tt class="docutils literal"><span class="pre">exit-event</span></tt> and
+normally defaults to 0.</p>
+<p>Multiple OpenVPN processes can be simultaneously executed with the same
+<tt class="docutils literal"><span class="pre">exit-event</span></tt> parameter. In any case, the controlling process can
+signal <tt class="docutils literal"><span class="pre">exit-event</span></tt>, causing all such OpenVPN processes to exit.</p>
+<p class="last">When executing an OpenVPN process using the <tt class="docutils literal"><span class="pre">--service</span></tt> directive,
+OpenVPN will probably not have a console window to output status/error
+messages, therefore it is useful to use <tt class="docutils literal"><span class="pre">--log</span></tt> or <tt class="docutils literal"><span class="pre">--log-append</span></tt> to
+write these messages to a file.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--show-adapters</span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td>(Standalone) Show available TAP-Win32 adapters which can be selected
+using the <tt class="docutils literal"><span class="pre">--dev-node</span></tt> option. On non-Windows systems, the
+<tt class="docutils literal">ifconfig</tt>(8) command provides similar functionality.</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--show-net</span></kbd></td>
+<td>(Standalone) Show OpenVPN's view of the system routing table and network
+adapter list.</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--show-net-up</span></kbd></td>
+<td>Output OpenVPN's view of the system routing table and network adapter
+list to the syslog or log file after the TUN/TAP adapter has been
+brought up and any routes have been added.</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--show-valid-subnets</span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">(Standalone) Show valid subnets for <tt class="docutils literal"><span class="pre">--dev</span> tun</tt> emulation. Since the
+TAP-Win32 driver exports an ethernet interface to Windows, and since TUN
+devices are point-to-point in nature, it is necessary for the TAP-Win32
+driver to impose certain constraints on TUN endpoint address selection.</p>
+<p class="last">Namely, the point-to-point endpoints used in TUN device emulation must
+be the middle two addresses of a /30 subnet (netmask 255.255.255.252).</p>
+</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--tap-sleep <var>n</var></span></kbd></td>
+<td><p class="first">Cause OpenVPN to sleep for <tt class="docutils literal">n</tt> seconds immediately after the TAP-Win32
+adapter state is set to &quot;connected&quot;.</p>
+<p class="last">This option is intended to be used to troubleshoot problems with the
+<tt class="docutils literal"><span class="pre">--ifconfig</span></tt> and <tt class="docutils literal"><span class="pre">--ip-win32</span></tt> options, and is used to give the
+TAP-Win32 adapter time to come up before Windows IP Helper API
+operations are applied to it.</p>
+</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--win-sys <var>path</var></span></kbd></td>
+<td><p class="first">Set the Windows system directory pathname to use when looking for system
+executables such as <tt class="docutils literal">route.exe</tt> and <tt class="docutils literal">netsh.exe</tt>. By default, if this
+directive is not specified, OpenVPN will use the SystemRoot environment
+variable.</p>
+<p class="last">This option has changed behaviour since OpenVPN 2.3. Earlier you had to
+define <tt class="docutils literal"><span class="pre">--win-sys</span> env</tt> to use the SystemRoot environment variable,
+otherwise it defaulted to <code>C:\\WINDOWS</code>. It is not needed to use
+the <tt class="docutils literal">env</tt> keyword any more, and it will just be ignored. A warning is
+logged when this is found in the configuration file.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--windows-driver <var>drv</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td>Specifies which tun driver to use. Values are <code>tap-windows6</code>
+(default) and <code>wintun</code>. This is a Windows-only option.
+<code>wintun</code>&quot; requires <tt class="docutils literal"><span class="pre">--dev</span> tun</tt> and the OpenVPN process to run
+elevated, or be invoked using the Interactive Service.</td></tr>
+</tbody>
+</table>
+</div>
+<div class="section" id="standalone-debug-options">
+<h2>Standalone Debug Options</h2>
+<table class="docutils option-list" frame="void" rules="none">
+<col class="option" />
+<col class="description" />
+<tbody valign="top">
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--show-gateway <var>args</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">(Standalone) Show current IPv4 and IPv6 default gateway and interface
+towards the gateway (if the protocol in question is enabled).</p>
+<p>Valid syntax:</p>
+<pre class="literal-block">
+--show-gateway
+--show-gateway IPv6-target
+</pre>
+<p class="last">If an IPv6 target address is passed as argument, the IPv6 route for this
+host is reported.</p>
+</td></tr>
+</tbody>
+</table>
+</div>
+<div class="section" id="advanced-expert-options">
+<h2>Advanced Expert Options</h2>
+<p>These are options only required when special tweaking is needed, often
+used when debugging or testing out special usage scenarios.</p>
+<table class="docutils option-list" frame="void" rules="none">
+<col class="option" />
+<col class="description" />
+<tbody valign="top">
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--hash-size <var>args</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Set the size of the real address hash table to <tt class="docutils literal">r</tt> and the virtual
+address table to <tt class="docutils literal">v</tt>.</p>
+<p>Valid syntax:</p>
+<pre class="literal-block">
+hash-size r v
+</pre>
+<p class="last">By default, both tables are sized at 256 buckets.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--bcast-buffers <var>n</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td>Allocate <tt class="docutils literal">n</tt> buffers for broadcast datagrams (default <code>256</code>).</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--persist-local-ip</span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td>Preserve initially resolved local IP address and port number across
+<tt class="docutils literal">SIGUSR1</tt> or <tt class="docutils literal"><span class="pre">--ping-restart</span></tt> restarts.</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--persist-remote-ip</span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td>Preserve most recently authenticated remote IP address and port number
+across <code>SIGUSR1</code> or <tt class="docutils literal"><span class="pre">--ping-restart</span></tt> restarts.</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--prng <var>args</var></span></kbd></td>
+<td><p class="first"><em>(Advanced)</em> Change the PRNG (Pseudo-random number generator) parameters</p>
+<p>Valid syntaxes:</p>
+<pre class="literal-block">
+prng alg
+prng alg nsl
+</pre>
+<p>Changes the PRNG to use digest algorithm <strong>alg</strong> (default <code>sha1</code>),
+and set <tt class="docutils literal">nsl</tt> (default <code>16</code>) to the size in bytes of the nonce
+secret length (between 16 and 64).</p>
+<p class="last">Set <tt class="docutils literal">alg</tt> to <code>none</code> to disable the PRNG and use the OpenSSL
+RAND_bytes function instead for all of OpenVPN's pseudo-random number
+needs.</p>
+</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--rcvbuf <var>size</var></span></kbd></td>
+<td>Set the TCP/UDP socket receive buffer size. Defaults to operating system
+default.</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--shaper <var>n</var></span></kbd></td>
+<td><p class="first">Limit bandwidth of outgoing tunnel data to <tt class="docutils literal">n</tt> bytes per second on the
+TCP/UDP port. Note that this will only work if mode is set to
+<code>p2p</code>. If you want to limit the bandwidth in both directions, use
+this option on both peers.</p>
+<p>OpenVPN uses the following algorithm to implement traffic shaping: Given
+a shaper rate of <tt class="docutils literal">n</tt> bytes per second, after a datagram write of <tt class="docutils literal">b</tt>
+bytes is queued on the TCP/UDP port, wait a minimum of <tt class="docutils literal">(b / n)</tt>
+seconds before queuing the next write.</p>
+<p>It should be noted that OpenVPN supports multiple tunnels between the
+same two peers, allowing you to construct full-speed and reduced
+bandwidth tunnels at the same time, routing low-priority data such as
+off-site backups over the reduced bandwidth tunnel, and other data over
+the full-speed tunnel.</p>
+<p>Also note that for low bandwidth tunnels (under 1000 bytes per second),
+you should probably use lower MTU values as well (see above), otherwise
+the packet latency will grow so large as to trigger timeouts in the TLS
+layer and TCP connections running over the tunnel.</p>
+<p class="last">OpenVPN allows <tt class="docutils literal">n</tt> to be between 100 bytes/sec and 100 Mbytes/sec.</p>
+</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--sndbuf <var>size</var></span></kbd></td>
+<td>Set the TCP/UDP socket send buffer size. Defaults to operating system
+default.</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--tcp-queue-limit <var>n</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Maximum number of output packets queued before TCP (default <code>64</code>).</p>
+<p class="last">When OpenVPN is tunneling data from a TUN/TAP device to a remote client
+over a TCP connection, it is possible that the TUN/TAP device might
+produce data at a faster rate than the TCP connection can support. When
+the number of output packets queued before sending to the TCP socket
+reaches this limit for a given client connection, OpenVPN will start to
+drop outgoing packets directed at this client.</p>
+</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--txqueuelen <var>n</var></span></kbd></td>
+<td><em>(Linux only)</em> Set the TX queue length on the TUN/TAP interface.
+Currently defaults to operating system default.</td></tr>
+</tbody>
+</table>
+</div>
+</div>
+<div class="section" id="unsupported-options">
+<h1>UNSUPPORTED OPTIONS</h1>
+<p>Options listed in this section have been removed from OpenVPN and are no
+longer supported</p>
+<table class="docutils option-list" frame="void" rules="none">
+<col class="option" />
+<col class="description" />
+<tbody valign="top">
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--client-cert-not-required</span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td>Removed in OpenVPN 2.5. This should be replaxed with
+<tt class="docutils literal"><span class="pre">--verify-client-cert</span> none</tt>.</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--ifconfig-pool-linear</span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td>Removed in OpenVPN 2.5. This should be replaced with <tt class="docutils literal"><span class="pre">--topology</span> p2p</tt>.</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--key-method</span></kbd></td>
+<td>Removed in OpenVPN 2.5. This option should not be used, as using the old
+<tt class="docutils literal"><span class="pre">key-method</span></tt> weakens the VPN tunnel security. The old <tt class="docutils literal"><span class="pre">key-method</span></tt>
+was also only needed when the remote side was older than OpenVPN 2.0.</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--no-iv</span></kbd></td>
+<td>Removed in OpenVPN 2.5. This option should not be used as it weakens the
+VPN tunnel security. This has been a NOOP option since OpenVPN 2.4.</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--no-replay</span></kbd></td>
+<td>Removed in OpenVPN 2.5. This option should not be used as it weakens the
+VPN tunnel security.</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--ns-cert-type</span></kbd></td>
+<td>Removed in OpenVPN 2.5. The <tt class="docutils literal">nsCertType</tt> field is no longer supported
+in recent SSL/TLS libraries. If your certificates does not include <em>key
+usage</em> and <em>extended key usage</em> fields, they must be upgraded and the
+<tt class="docutils literal"><span class="pre">--remote-cert-tls</span></tt> option should be used instead.</td></tr>
+</tbody>
+</table>
+</div>
+<div class="section" id="connection-profiles">
+<h1>CONNECTION PROFILES</h1>
+<p>Client configuration files may contain multiple remote servers which
+it will attempt to connect against. But there are some configuration
+options which are related to specific <tt class="docutils literal"><span class="pre">--remote</span></tt> options. For these
+use cases, connection profiles are the solution.</p>
+<p>By enacpulating the <tt class="docutils literal"><span class="pre">--remote</span></tt> option and related options within
+<tt class="docutils literal">&lt;connection&gt;</tt> and <tt class="docutils literal">&lt;/connection&gt;</tt>, these options are handled as a
+group.</p>
+<p>An OpenVPN client will try each connection profile sequentially until it
+achieves a successful connection.</p>
+<p><tt class="docutils literal"><span class="pre">--remote-random</span></tt> can be used to initially &quot;scramble&quot; the connection
+list.</p>
+<p>Here is an example of connection profile usage:</p>
+<pre class="literal-block">
+client
+dev tun
+
+&lt;connection&gt;
+remote 198.19.34.56 1194 udp
+&lt;/connection&gt;
+
+&lt;connection&gt;
+remote 198.19.34.56 443 tcp
+&lt;/connection&gt;
+
+&lt;connection&gt;
+remote 198.19.34.56 443 tcp
+http-proxy 192.168.0.8 8080
+&lt;/connection&gt;
+
+&lt;connection&gt;
+remote 198.19.36.99 443 tcp
+http-proxy 192.168.0.8 8080
+&lt;/connection&gt;
+
+persist-key
+persist-tun
+pkcs12 client.p12
+remote-cert-tls server
+verb 3
+</pre>
+<p>First we try to connect to a server at 198.19.34.56:1194 using UDP. If
+that fails, we then try to connect to 198.19.34.56:443 using TCP. If
+that also fails, then try connecting through an HTTP proxy at
+192.168.0.8:8080 to 198.19.34.56:443 using TCP. Finally, try to connect
+through the same proxy to a server at 198.19.36.99:443 using TCP.</p>
+<p>The following OpenVPN options may be used inside of a <tt class="docutils literal">&lt;connection&gt;</tt>
+block:</p>
+<p><tt class="docutils literal">bind</tt>, <tt class="docutils literal"><span class="pre">connect-retry</span></tt>, <tt class="docutils literal"><span class="pre">connect-retry-max</span></tt>, <tt class="docutils literal"><span class="pre">connect-timeout</span></tt>,
+<tt class="docutils literal"><span class="pre">explicit-exit-notify</span></tt>, <tt class="docutils literal">float</tt>, <tt class="docutils literal">fragment</tt>, <tt class="docutils literal"><span class="pre">http-proxy</span></tt>,
+<tt class="docutils literal"><span class="pre">http-proxy-option</span></tt>, <tt class="docutils literal"><span class="pre">key-direction</span></tt>, <tt class="docutils literal"><span class="pre">link-mtu</span></tt>, <tt class="docutils literal">local</tt>,
+<tt class="docutils literal">lport</tt>, <tt class="docutils literal">mssfix</tt>, <tt class="docutils literal"><span class="pre">mtu-disc</span></tt>, <tt class="docutils literal">nobind</tt>, <tt class="docutils literal">port</tt>, <tt class="docutils literal">proto</tt>,
+<tt class="docutils literal">remote</tt>, <tt class="docutils literal">rport</tt>, <tt class="docutils literal"><span class="pre">socks-proxy</span></tt>, <tt class="docutils literal"><span class="pre">tls-auth</span></tt>, <tt class="docutils literal"><span class="pre">tls-crypt</span></tt>,
+<tt class="docutils literal"><span class="pre">tun-mtu</span> and</tt>, <tt class="docutils literal"><span class="pre">tun-mtu-extra</span></tt>.</p>
+<p>A defaulting mechanism exists for specifying options to apply to all
+<tt class="docutils literal">&lt;connection&gt;</tt> profiles. If any of the above options (with the
+exception of <tt class="docutils literal">remote</tt> ) appear outside of a <tt class="docutils literal">&lt;connection&gt;</tt> block,
+but in a configuration file which has one or more <tt class="docutils literal">&lt;connection&gt;</tt>
+blocks, the option setting will be used as a default for
+<tt class="docutils literal">&lt;connection&gt;</tt> blocks which follow it in the configuration file.</p>
+<p>For example, suppose the <tt class="docutils literal">nobind</tt> option were placed in the sample
+configuration file above, near the top of the file, before the first
+<tt class="docutils literal">&lt;connection&gt;</tt> block. The effect would be as if <tt class="docutils literal">nobind</tt> were
+declared in all <tt class="docutils literal">&lt;connection&gt;</tt> blocks below it.</p>
+</div>
+<div class="section" id="inline-file-support">
+<h1>INLINE FILE SUPPORT</h1>
+<p>OpenVPN allows including files in the main configuration for the <tt class="docutils literal"><span class="pre">--ca</span></tt>,
+<tt class="docutils literal"><span class="pre">--cert</span></tt>, <tt class="docutils literal"><span class="pre">--dh</span></tt>, <tt class="docutils literal"><span class="pre">--extra-certs</span></tt>, <tt class="docutils literal"><span class="pre">--key</span></tt>, <tt class="docutils literal"><span class="pre">--pkcs12</span></tt>,
+<tt class="docutils literal"><span class="pre">--secret</span></tt>, <tt class="docutils literal"><span class="pre">--crl-verify</span></tt>, <tt class="docutils literal"><span class="pre">--http-proxy-user-pass</span></tt>, <tt class="docutils literal"><span class="pre">--tls-auth</span></tt>,
+<tt class="docutils literal"><span class="pre">--auth-gen-token-secret</span></tt>, <tt class="docutils literal"><span class="pre">--tls-crypt</span></tt> and <tt class="docutils literal"><span class="pre">--tls-crypt-v2</span></tt>
+options.</p>
+<p>Each inline file started by the line <tt class="docutils literal">&lt;option&gt;</tt> and ended by the line
+<tt class="docutils literal">&lt;/option&gt;</tt></p>
+<p>Here is an example of an inline file usage</p>
+<pre class="literal-block">
+&lt;cert&gt;
+-----BEGIN CERTIFICATE-----
+[...]
+-----END CERTIFICATE-----
+&lt;/cert&gt;
+</pre>
+<p>When using the inline file feature with <tt class="docutils literal"><span class="pre">--pkcs12</span></tt> the inline file has
+to be base64 encoded. Encoding of a .p12 file into base64 can be done
+for example with OpenSSL by running <code>openssl base64 -in input.p12</code></p>
+</div>
+<div class="section" id="signals">
+<h1>SIGNALS</h1>
+<dl class="docutils">
+<dt><code>SIGHUP</code></dt>
+<dd>Cause OpenVPN to close all TUN/TAP and network connections, restart,
+re-read the configuration file (if any), and reopen TUN/TAP and network
+connections.</dd>
+<dt><code>SIGUSR1</code></dt>
+<dd><p class="first">Like <code>SIGHUP`</code>, except don't re-read configuration file, and
+possibly don't close and reopen TUN/TAP device, re-read key files,
+preserve local IP address/port, or preserve most recently authenticated
+remote IP address/port based on <tt class="docutils literal"><span class="pre">--persist-tun</span></tt>, <tt class="docutils literal"><span class="pre">--persist-key</span></tt>,
+<tt class="docutils literal"><span class="pre">--persist-local-ip</span></tt> and <tt class="docutils literal"><span class="pre">--persist-remote-ip</span></tt> options respectively
+(see above).</p>
+<p>This signal may also be internally generated by a timeout condition,
+governed by the <tt class="docutils literal"><span class="pre">--ping-restart</span></tt> option.</p>
+<p class="last">This signal, when combined with <tt class="docutils literal"><span class="pre">--persist-remote-ip</span></tt>, may be sent
+when the underlying parameters of the host's network interface change
+such as when the host is a DHCP client and is assigned a new IP address.
+See <tt class="docutils literal"><span class="pre">--ipchange</span></tt> for more information.</p>
+</dd>
+<dt><code>SIGUSR2</code></dt>
+<dd>Causes OpenVPN to display its current statistics (to the syslog file if
+<tt class="docutils literal"><span class="pre">--daemon</span></tt> is used, or stdout otherwise).</dd>
+<dt><code>SIGINT</code>, <code>SIGTERM</code></dt>
+<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>
+</div>
+<div class="section" id="howto">
+<h1>HOWTO</h1>
+<p>For a more comprehensive guide to setting up OpenVPN in a production
+setting, see the OpenVPN HOWTO at
+<a class="reference external" href="https://openvpn.net/community-resources/how-to/">https://openvpn.net/community-resources/how-to/</a></p>
+</div>
+<div class="section" id="protocol">
+<h1>PROTOCOL</h1>
+<p>For a description of OpenVPN's underlying protocol, see
+<a class="reference external" href="https://openvpn.net/community-resources/openvpn-protocol/">https://openvpn.net/community-resources/openvpn-protocol/</a></p>
+</div>
+<div class="section" id="web">
+<h1>WEB</h1>
+<p>OpenVPN's web site is at <a class="reference external" href="https://openvpn.net/">https://openvpn.net/</a></p>
+<p>Go here to download the latest version of OpenVPN, subscribe to the
+mailing lists, read the mailing list archives, or browse the SVN
+repository.</p>
+</div>
+<div class="section" id="bugs">
+<h1>BUGS</h1>
+<p>Report all bugs to the OpenVPN team <a class="reference external" href="mailto:info&#64;openvpn.net">info&#64;openvpn.net</a></p>
+</div>
+<div class="section" id="see-also">
+<h1>SEE ALSO</h1>
+<p><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),
+<tt class="docutils literal">scp</tt>(1)
+<tt class="docutils literal">ssh</tt>(1)</p>
+</div>
+<div class="section" id="notes">
+<h1>NOTES</h1>
+<p>This product includes software developed by the OpenSSL Project
+(<a class="reference external" href="https://www.openssl.org/">https://www.openssl.org/</a>)</p>
+<p>For more information on the TLS protocol, see
+<a class="reference external" href="http://www.ietf.org/rfc/rfc2246.txt">http://www.ietf.org/rfc/rfc2246.txt</a></p>
+<p>For more information on the LZO real-time compression library see
+<a class="reference external" href="https://www.oberhumer.com/opensource/lzo/">https://www.oberhumer.com/opensource/lzo/</a></p>
+</div>
+<div class="section" id="copyright">
+<h1>COPYRIGHT</h1>
+<p>Copyright (C) 2002-2020 OpenVPN Inc This program is free software; you
+can redistribute it and/or modify it under the terms of the GNU General
+Public License version 2 as published by the Free Software Foundation.</p>
+</div>
+<div class="section" id="authors">
+<h1>AUTHORS</h1>
+<p>James Yonan <a class="reference external" href="mailto:james&#64;openvpn.net">james&#64;openvpn.net</a></p>
+</div>
+</div>
+</body>
+</html>
diff --git a/doc/tls-crypt-v2.txt b/doc/tls-crypt-v2.txt
deleted file mode 100644
index 3798791..0000000
--- a/doc/tls-crypt-v2.txt
+++ /dev/null
@@ -1,189 +0,0 @@
-Client-specific tls-crypt keys (--tls-crypt-v2)
-===============================================
-
-This document describes the ``--tls-crypt-v2`` option, which enables OpenVPN
-to use client-specific ``--tls-crypt`` keys.
-
-Rationale
----------
-
-``--tls-auth`` and ``tls-crypt`` use a pre-shared group key, which is shared
-among all clients and servers in an OpenVPN deployment. If any client or
-server is compromised, the attacker will have access to this shared key, and it
-will no longer provide any security. To reduce the risk of losing pre-shared
-keys, ``tls-crypt-v2`` adds the ability to supply each client with a unique
-tls-crypt key. This allows large organisations and VPN providers to profit
-from the same DoS and TLS stack protection that small deployments can already
-achieve using ``tls-auth`` or ``tls-crypt``.
-
-Also, for ``tls-crypt``, even if all these peers succeed in keeping the key
-secret, the key lifetime is limited to roughly 8000 years, divided by the
-number of clients (see the ``--tls-crypt`` section of the man page). Using
-client-specific keys, we lift this lifetime requirement to roughly 8000 years
-for each client key (which "Should Be Enough For Everybody (tm)").
-
-
-Introduction
-------------
-
-``tls-crypt-v2`` uses an encrypted cookie mechanism to introduce
-client-specific tls-crypt keys without introducing a lot of server-side state.
-The client-specific key is encrypted using a server key. The server key is the
-same for all servers in a group. When a client connects, it first sends the
-encrypted key to the server, such that the server can decrypt the key and all
-messages can thereafter be encrypted using the client-specific key.
-
-A wrapped (encrypted and authenticated) client-specific key can also contain
-metadata. The metadata is wrapped together with the key, and can be used to
-allow servers to identify clients and/or key validity. This allows the server
-to abort the connection immediately after receiving the first packet, rather
-than performing an entire TLS handshake. Aborting the connection this early
-greatly improves the DoS resilience and reduces attack surface against
-malicious clients that have the ``tls-crypt`` or ``tls-auth`` key. This is
-particularly relevant for large deployments (think lost key or disgruntled
-employee) and VPN providers (clients are not trusted).
-
-To allow for a smooth transition, ``tls-crypt-v2`` is designed such that a
-server can enable both ``tls-crypt-v2`` and either ``tls-crypt`` or
-``tls-auth``. This is achieved by introducing a P_CONTROL_HARD_RESET_CLIENT_V3
-opcode, that indicates that the client wants to use ``tls-crypt-v2`` for the
-current connection.
-
-For an exact specification and more details, read the Implementation section.
-
-
-Implementation
---------------
-
-When setting up a tls-crypt-v2 group (similar to generating a tls-crypt or
-tls-auth key previously):
-
-1. Generate a tls-crypt-v2 server key using OpenVPN's ``--tls-crypt-v2-genkey server``.
- This key contains 2 512-bit keys, of which we use:
-
- * the first 256 bits of key 1 as AES-256-CTR encryption key ``Ke``
- * the first 256 bits of key 2 as HMAC-SHA-256 authentication key ``Ka``
-
- This format is similar to the format for regular ``tls-crypt``/``tls-auth``
- and data channel keys, which allows us to reuse code.
-
-2. Add the tls-crypt-v2 server key to all server configs
- (``tls-crypt-v2 /path/to/server.key``)
-
-
-When provisioning a client, create a client-specific tls-crypt key:
-
-1. Generate 2048 bits client-specific key ``Kc`` using OpenVPN's ``--tls-crypt-v2-genkey client``
-
-2. Optionally generate metadata
-
- The first byte of the metadata determines the type. The initial
- implementation supports the following types:
-
- 0x00 (USER): User-defined free-form data.
- 0x01 (TIMESTAMP): 64-bit network order unix timestamp of key generation.
-
- The timestamp can be used to reject too-old tls-crypt-v2 client keys.
-
- User metadata could for example contain the users certificate serial, such
- that the incoming connection can be verified against a CRL.
-
- If no metadata is supplied during key generation, openvpn defaults to the
- TIMESTAMP metadata type.
-
-3. Create a wrapped client key ``WKc``, using the same nonce-misuse-resistant
- SIV construction we use for tls-crypt:
-
- ``len = len(WKc)`` (16 bit, network byte order)
-
- ``T = HMAC-SHA256(Ka, len || Kc || metadata)``
-
- ``IV = 128 most significant bits of T``
-
- ``WKc = T || AES-256-CTR(Ke, IV, Kc || metadata) || len``
-
- Note that the length of ``WKc`` can be computed before composing ``WKc``,
- because the length of each component is known (and AES-256-CTR does not add
- any padding).
-
-4. Create a tls-crypt-v2 client key: PEM-encode ``Kc || WKc`` and store in a
- file, using the header ``-----BEGIN OpenVPN tls-crypt-v2 client key-----``
- and the footer ``-----END OpenVPN tls-crypt-v2 client key-----``. (The PEM
- format is simple, and following PEM allows us to use the crypto lib function
- for en/decoding.)
-
-5. Add the tls-crypt-v2 client key to the client config
- (``tls-crypt-v2 /path/to/client-specific.key``)
-
-
-When setting up the openvpn connection:
-
-1. The client reads the tls-crypt-v2 key from its config, and:
-
- 1. loads ``Kc`` as its tls-crypt key,
- 2. stores ``WKc`` in memory for sending to the server.
-
-2. To start the connection, the client creates a P_CONTROL_HARD_RESET_CLIENT_V3
- message, wraps it with tls-crypt using ``Kc`` as the key, and appends
- ``WKc``. (``WKc`` must not be encrypted, to prevent a chicken-and-egg
- problem.)
-
-3. The server receives the P_CONTROL_HARD_RESET_CLIENT_V3 message, and
-
- 1. reads the WKc length field from the end of the message, and extracts WKc
- from the message
- 2. unwraps ``WKc``
- 3. uses unwrapped ``Kc`` to verify the remaining
- P_CONTROL_HARD_RESET_CLIENT_V3 message's (encryption and) authentication.
-
- The message is dropped and no error response is sent when either 3.1, 3.2 or
- 3.3 fails (DoS protection).
-
-4. Server optionally checks metadata using a --tls-crypt-v2-verify script
-
- This allows early abort of connection, *before* we expose any of the
- notoriously dangerous TLS, X.509 and ASN.1 parsers and thereby reduces the
- attack surface of the server.
-
- The metadata is checked *after* the OpenVPN three-way handshake has
- completed, to prevent DoS attacks. (That is, once the client has proved to
- the server that it possesses Kc, by authenticating a packet that contains the
- session ID picked by the server.)
-
- A server should not send back any error messages if metadata verification
- fails, to reduce attack surface and maximize DoS resilience.
-
-6. Client and server use ``Kc`` for (un)wrapping any following control channel
- messages.
-
-
-Considerations
---------------
-
-To allow for a smooth transition, the server implementation allows
-``tls-crypt`` or ``tls-auth`` to be used simultaneously with ``tls-crypt-v2``.
-This specification does not allow simultaneously using ``tls-crypt-v2`` and
-connections without any control channel wrapping, because that would break DoS
-resilience.
-
-WKc includes a length field, so we leave the option for future extension of the
-P_CONTROL_HEAD_RESET_CLIENT_V3 message open. (E.g. add payload to the reset to
-indicate low-level protocol features.)
-
-``tls-crypt-v2`` uses fixed crypto algorithms, because:
-
- * The crypto is used before we can do any negotiation, so the algorithms have
- to be predefined.
- * The crypto primitives are chosen conservatively, making problems with these
- primitives unlikely.
- * Making anything configurable adds complexity, both in implementation and
- usage. We should not add any more complexity than is absolutely necessary.
-
-Potential ``tls-crypt-v2`` risks:
-
- * Slightly more work on first connection (``WKc`` unwrap + hard reset unwrap)
- than with ``tls-crypt`` (hard reset unwrap) or ``tls-auth`` (hard reset auth).
- * Flexible metadata allow mistakes
- (So we should make it easy to do it right. Provide tooling to create client
- keys based on cert serial + CA fingerprint, provide script that uses CRL (if
- available) to drop revoked keys.)