From 57f0b7b331088e489e93ae89ee0aed98381d8806 Mon Sep 17 00:00:00 2001 From: Bernhard Schmidt Date: Tue, 1 Sep 2020 16:53:26 +0200 Subject: New upstream version 2.5~beta3 --- doc/Makefile.in | 899 ++++ doc/README.man | 22 - doc/android.txt | 101 - doc/doxygen/Makefile.in | 532 +++ doc/doxygen/doc_compression.h | 91 - doc/doxygen/doc_control_processor.h | 184 - doc/doxygen/doc_control_tls.h | 104 - doc/doxygen/doc_data_control.h | 102 - doc/doxygen/doc_data_crypto.h | 70 - doc/doxygen/doc_eventloop.h | 66 - doc/doxygen/doc_external_multiplexer.h | 45 - doc/doxygen/doc_fragmentation.h | 95 - doc/doxygen/doc_internal_multiplexer.h | 43 - doc/doxygen/doc_key_generation.h | 148 - doc/doxygen/doc_mainpage.h | 161 - doc/doxygen/doc_memory_management.h | 98 - doc/doxygen/doc_protocol_overview.h | 195 - doc/doxygen/doc_reliable.h | 48 - doc/doxygen/doc_tunnel_state.h | 154 - doc/keying-material-exporter.txt | 137 - doc/man-sections/cipher-negotiation.rst | 96 - doc/man-sections/vpn-network-options.rst | 23 +- doc/openvpn.8 | 6954 ++++++++++++++++++++++++++++++ doc/openvpn.8.html | 6023 ++++++++++++++++++++++++++ doc/tls-crypt-v2.txt | 189 - 25 files changed, 14425 insertions(+), 2155 deletions(-) create mode 100644 doc/Makefile.in delete mode 100644 doc/README.man delete mode 100644 doc/android.txt create mode 100644 doc/doxygen/Makefile.in delete mode 100644 doc/doxygen/doc_compression.h delete mode 100644 doc/doxygen/doc_control_processor.h delete mode 100644 doc/doxygen/doc_control_tls.h delete mode 100644 doc/doxygen/doc_data_control.h delete mode 100644 doc/doxygen/doc_data_crypto.h delete mode 100644 doc/doxygen/doc_eventloop.h delete mode 100644 doc/doxygen/doc_external_multiplexer.h delete mode 100644 doc/doxygen/doc_fragmentation.h delete mode 100644 doc/doxygen/doc_internal_multiplexer.h delete mode 100644 doc/doxygen/doc_key_generation.h delete mode 100644 doc/doxygen/doc_mainpage.h delete mode 100644 doc/doxygen/doc_memory_management.h delete mode 100644 doc/doxygen/doc_protocol_overview.h delete mode 100644 doc/doxygen/doc_reliable.h delete mode 100644 doc/doxygen/doc_tunnel_state.h delete mode 100644 doc/keying-material-exporter.txt delete mode 100644 doc/man-sections/cipher-negotiation.rst create mode 100644 doc/openvpn.8 create mode 100644 doc/openvpn.8.html delete mode 100644 doc/tls-crypt-v2.txt (limited to 'doc') 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 +# Copyright (C) 2006-2012 Alon Bar-Lev +# + +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. +# +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. - * - * - * 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. - * - * - * 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. - * - * - * 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. - * - * - * 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. - * - * - * 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. - * - * - * 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. - * - * - * 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. - * - * - * 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. - * - * - * 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. - * - * - * 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. - * - * - * 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. - * - * - * 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. - * - * - * 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 - * [ 5-bit opcode | 3-bit key_id ] [ payload ] - * - * @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 - * [ 5-bit opcode | 3-bit key_id ] [ 24-bit peer-id ] [ payload ] - * - * 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. - * - * - * 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. - * - * - * 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 -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 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\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\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 +".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,\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=\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=\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= \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=\fP +The MAC address of clients default gateway +.TP +.B \fBIV_SSL=\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_=\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 .. CRLs +are expected to be named .r. 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__=\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\fP and \fB\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 + + +remote 198.19.34.56 1194 udp + + + +remote 198.19.34.56 443 tcp + + + +remote 198.19.34.56 443 tcp +http\-proxy 192.168.0.8 8080 + + + +remote 198.19.36.99 443 tcp +http\-proxy 192.168.0.8 8080 + + +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\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\fP profiles. If any of the above options (with the +exception of \fBremote\fP ) appear outside of a \fB\fP block, +but in a configuration file which has one or more \fB\fP +blocks, the option setting will be used as a default for +\fB\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\fP block. The effect would be as if \fBnobind\fP were +declared in all \fB\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\fP +.sp +Here is an example of an inline file usage +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C + +\-\-\-\-\-BEGIN CERTIFICATE\-\-\-\-\- +[...] +\-\-\-\-\-END CERTIFICATE\-\-\-\-\- + +.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 @@ + + + + + + +openvpn + + + +
+

openvpn

+

Secure IP tunnel daemon

+ +++ + + + + + +
Manual section:8
Manual group:System Manager's Manual
+
+

SYNOPSIS

+
+
openvpn [ options ... ]
+
openvpn --help
+
+
+
+

INTRODUCTION

+

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.

+

Also note that there's more documentation and examples on the OpenVPN +web site: https://openvpn.net/

+

And if you would like to see a shorter version of this manual, see the +openvpn usage message which can be obtained by running openvpn +without any parameters.

+
+
+

DESCRIPTION

+

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.

+

OpenVPN is tightly bound to the OpenSSL library, and derives much of its +crypto capabilities from it.

+

OpenVPN supports conventional encryption using a pre-shared secret key +(Static Key mode) or public key security (SSL/TLS mode) using +client & server certificates. OpenVPN also supports non-encrypted +TCP/UDP tunnels.

+

OpenVPN is designed to work with the TUN/TAP virtual networking +interface that exists on most platforms.

+

Overall, OpenVPN aims to offer many of the key features of IPSec but +with a relatively lightweight footprint.

+
+
+

OPTIONS

+

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.

+
+

Generic Options

+

This section covers generic options which are accessible regardless of +which mode OpenVPN is configured as.

+ +++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+--helpShow options.
+--auth-nocache

Don't cache --askpass or --auth-user-pass username/passwords in +virtual memory.

+

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.

+

When using --auth-nocache in combination with a user/password file +and --chroot or --daemon, make sure to use an absolute path.

+

This directive does not affect the --http-proxy username/password. +It is always cached.

+
+--cd dir

Change directory to dir prior to reading any files such as +configuration files, key files, scripts, etc. dir should be an +absolute path, with a leading "/", and without any references to the +current directory such as . or ...

+

This option is useful when you are running OpenVPN in --daemon mode, +and you want to consolidate all of your OpenVPN control files in one +location.

+
+--chroot dir

Chroot to dir after initialization. --chroot essentially +redefines dir 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.

+

Since the chroot operation is delayed until after initialization, most +OpenVPN options that reference files will operate in a pre-chroot +context.

+

In many cases, the dir parameter can point to an empty directory, +however complications can result when scripts or restarts are executed +after the chroot operation.

+

Note: The SSL library will probably need /dev/urandom to be available +inside the chroot directory dir. 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.

+
+--config file

Load additional config options from file where each line corresponds +to one command line option, but with the leading '--' removed.

+

If --config file is the only option to the openvpn command, the +--config can be removed, and the command can be given as openvpn +file

+

Note that configuration files can be nested to a reasonable depth.

+

Double quotation or single quotation characters ("", '') can be used to +enclose single parameters containing whitespace, and "#" or ";" +characters in the first column can be used to denote comments.

+

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:

+
+\\       Maps to a single backslash character (\).
+\"       Pass a literal doublequote character ("), don't
+         interpret it as enclosing a parameter.
+\[SPACE] Pass a literal space or tab character, don't
+         interpret it as a parameter delimiter.
+
+

For example on Windows, use double backslashes to represent pathnames:

+
+secret "c:\\OpenVPN\\secret.key"
+
+

For examples of configuration files, see +https://openvpn.net/community-resources/how-to/

+

Here is an example configuration file:

+
+#
+# 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
+
+
+--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 /var/log/messages), except for the output of +scripts and ifconfig commands, which will go to /dev/null unless +otherwise redirected. The syslog redirection occurs immediately at the +point that --daemon is parsed on the command line even though the +daemonization point occurs later. If one of the --log options is +present, it will supersede syslog redirection.

+

The optional progname parameter will cause OpenVPN to report its +program name to the system logger as progname. This can be useful in +linking OpenVPN messages in the syslog file with specific tunnels. When +unspecified, progname defaults to "openvpn".

+

When OpenVPN is run with the --daemon 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.

+

In OpenVPN, the vast majority of errors which occur after initialization +are non-fatal.

+

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 +--askpass 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).

+

Further, using --daemon together with --auth-user-pass (entered +on console) and --auth-nocache will fail as soon as key +renegotiation (and reauthentication) occurs.

+
+--disable-occ

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 --dev tun while the other peer uses --dev tap.

+

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.

+
+--engine engine-name
 

Enable OpenSSL hardware-based crypto engine functionality.

+

If engine-name is specified, use a specific crypto engine. Use the +--show-engines standalone option to list the crypto engines which +are supported by OpenSSL.

+
+--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'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%.

+

This option can only be used on non-Windows systems, when --proto +udp is specified, and when --shaper is NOT specified.

+
+--group groupSimilar to the --user option, this option changes the group ID of +the OpenVPN process to group after initialization.
+--ignore-unknown-option args
 

Valid syntax:

+
+ignore-unknown-options opt1 opt2 opt3 ... optN
+
+

When one of options opt1 ... optN is encountered in the configuration +file the configuration file parsing does not fail if this OpenVPN version +does not support the option. Multiple --ignore-unknown-option options +can be given to support a larger number of options to ignore.

+

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.

+

--ignore-unknown-option is available since OpenVPN 2.3.3.

+
+--iproute cmdSet alternate command to execute instead of default iproute2 command. +May be used in order to execute OpenVPN in unprivileged environment.
+--keying-material-exporter args
 

Save Exported Keying Material [RFC5705] of len bytes (must be between 16 +and 4095 bytes) using label in environment +(exported_keying_material) for use by plugins in +OPENVPN_PLUGIN_TLS_FINAL callback.

+

Valid syntax:

+
+keying-material-exporter label len
+
+

Note that exporter labels have the potential to collide with existing +PRF labels. In order to prevent this, labels MUST begin with +EXPORTER.

+
+--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 --user option).

+

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 --reneg options (see +below), then are discarded.

+

The downside of using --mlock is that it will reduce the amount of +physical memory available to other applications.

+
+--nice nChange process priority after initialization (n greater than 0 is +lower priority, n less than zero is higher priority).
+--persist-key

Don't re-read key files across SIGUSR1 or --ping-restart.

+

This option can be combined with --user nobody to allow restarts +triggered by the SIGUSR1 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.

+

This option solves the problem by persisting keys across SIGUSR1 +resets, so they don't need to be re-read.

+
+--remap-usr1 signal
 

Control whether internally or externally generated SIGUSR1 signals +are remapped to SIGHUP (restart without persisting state) or +SIGTERM (exit).

+

signal can be set to SIGHUP or SIGTERM. By default, +no remapping occurs.

+
+--script-security level
 

This directive offers policy-level control over OpenVPN's usage of +external programs and scripts. Lower level values are more +restrictive, higher values are more permissive. Settings for level:

+
+
0
+
Strictly no calling of external programs.
+
1
+
(Default) Only call built-in executables such as ifconfig, +ip, route, or netsh.
+
2
+
Allow calling of built-in executables and user-defined +scripts.
+
3
+
Allow passwords to be passed to scripts via environmental +variables (potentially unsafe).
+
+

OpenVPN releases before v2.3 also supported a method flag which +indicated how OpenVPN should call external commands and scripts. This +could be either execve or system. As of OpenVPN 2.3, this +flag is no longer accepted. In most *nix environments the execve() +approach has been used without any issues.

+

Some directives such as --up 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.

+

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 system 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:

+
+--up 'C:\\Windows\\System32\\wscript.exe C:\\Program\ Files\\OpenVPN\\config\\my-up-script.vbs'
+
+

Please note the single quote marks and the escaping of the backslashes +(\) and the space character.

+

The reason the support for the system flag was removed is due to +the security implications with shell expansions when executing scripts +via the system() call.

+
+--setcon context
 

Apply SELinux context 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 --user and +--chroot 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).

+

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.

+

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 --persist-key and --persist-tun options.

+
+--status args

Write operational status to file every n seconds.

+

Valid syntaxes:

+
+status file
+status file n
+
+

Status can also be written to the syslog by sending a SIGUSR2 +signal.

+

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 --status-version option in that case.

+

For clients or instances running in point-to-point mode, it will contain +the traffic statistics.

+
+--status-version n
 

Set the status file format version number to n.

+

This only affects the status file on servers with multi-client +capability enabled. Valid status version values:

+
+
1
+
Traditional format (default). The client list contains the +following fields comma-separated: Common Name, Real Address, Bytes +Received, Bytes Sent, Connected Since.
+
2
+
A more reliable format for external processing. Compared to +version 1, 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.
+
3
+
Identical to 2, but fields are tab-separated.
+
+
+--test-crypto

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 --dev or --remote.

+

The typical usage of --test-crypto would be something like this:

+
+openvpn --test-crypto --secret key
+
+

or

+
+openvpn --test-crypto --secret key --verb 9
+
+

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.

+
+--tmp-dir dir

Specify a directory dir 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.

+

This directory will be used by in the following cases:

+
    +
  • --client-connect scripts and OPENVPN_PLUGIN_CLIENT_CONNECT +plug-in hook to dynamically generate client-specific configuration +client_connect_config_file and return success/failure via +client_connect_deferred_file when using deferred client connect +method
    • +
  • OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY plug-in hooks returns +success/failure via auth_control_file when using deferred auth +method
    • +
  • OPENVPN_PLUGIN_ENABLE_PF plugin hook to pass filtering rules +via pf_file
    • +
+
+--use-prediction-resistance
 

Enable prediction resistance on mbed TLS's RNG.

+

Enabling prediction resistance causes the RNG to reseed in each call for +random. Reseeding this often can quickly deplete the kernel entropy +pool.

+

If you need this option, please consider running a daemon that adds +entropy to the kernel pool.

+
+--user user

Change the user ID of the OpenVPN process to user 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.

+

By setting user to nobody 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 SIGUSR1 signal (for example in response to +a DHCP reset), you should make use of one or more of the --persist +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 +ifconfig on the TUN device).

+
+--writepid file
 Write OpenVPN's main process ID to file.
+
+
+

Log options

+ +++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+--echo parms

Echo parms to log output.

+

Designed to be used to send messages to a controlling application which +is receiving the OpenVPN log output.

+
+--errors-to-stderr
 Output errors to stderr instead of stdout unless log output is +redirected by one of the --log options.
+--log file

Output logging messages to file, including output to stdout/stderr +which is generated by called scripts. If file 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 --daemon or +--inetd is also specified. This option is persistent over the entire +course of an OpenVPN instantiation and will not be reset by +SIGHUP, SIGUSR1, or --ping-restart.

+

Note that on Windows, when OpenVPN is started as a service, logging +occurs by default without the need to specify this option.

+
+--log-append file
 Append logging messages to file. If file does not exist, it will +be created. This option behaves exactly like --log except that it +appends to rather than truncating the log file.
+--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.
+--mute nLog at most n consecutive messages in the same category. This is +useful to limit repetitive logging of similar message types.
+--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.
+--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.
+--syslog progname
 Direct log output to system logger, but do not become a daemon. See +--daemon directive above for description of progname parameter.
+--verb n

Set output verbosity to n (default 1). Each level shows all +info from the previous levels. Level 3 is recommended if you want +a good summary of what's happening without being swamped by output.

+
+
0
+
No output except fatal errors.
+
1 to 4
+
Normal usage range.
+
5
+
Outputs R and W 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.
+
6 to 11
+
Debug info range (see errlevel.h in the source code for +additional information on debug levels).
+
+
+
+
+

Protocol options

+

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.

+ +++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+--allow-compression mode
 

As described in the --compress option, compression is a potentially +dangerous option. This option allows controlling the behaviour of +OpenVPN when compression is used and allowed.

+

Valid syntaxes:

+
+allow-compression
+allow-compression mode
+
+

The mode argument can be one of the following values:

+
+
asym (default)
+
OpenVPN will only decompress downlink packets but not compress +uplink packets. 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.
+
no
+
OpenVPN will refuse any non-stub compression.
+
yes
+
OpenVPN will send and receive compressed packets.
+
+
+--auth alg

Authenticate data channel packets and (if enabled) tls-auth control +channel packets with HMAC using message digest algorithm alg. (The +default is SHA1 ). 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.

+

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.

+

If an AEAD cipher mode (e.g. GCM) is chosen then the specified --auth +algorithm is ignored for the data channel and the authentication method +of the AEAD cipher is used instead. Note that alg still specifies +the digest used for tls-auth.

+

In static-key encryption mode, the HMAC key is included in the key file +generated by --genkey. 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 alg=none to disable +authentication.

+

For more information on HMAC see +http://www.cs.ucsd.edu/users/mihir/papers/hmac.html

+
+--cipher alg

This option is deprecated for server-client mode. --data-ciphers +or possibly --data-ciphers-fallback` should be used instead.

+

Encrypt data channel packets with cipher algorithm alg.

+

The default is BF-CBC, 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 AES-256-GCM. See --data-ciphers and +--ncp-disable for more details on NCP.

+

Using BF-CBC 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 +https://community.openvpn.net/openvpn/wiki/SWEET32 +for details. Due to this, support for BF-CBC, DES, +CAST5, IDEA and RC2 ciphers will be removed in +OpenVPN 2.6.

+

To see other ciphers that are available with OpenVPN, use the +--show-ciphers option.

+

Set alg to none to disable encryption.

+
+--compress algorithm
 

DEPRECATED Enable a compression algorithm. Compression is generally +not recommended. VPN tunnels which use compression are susceptible to +the VORALCE attack vector.

+

The algorithm parameter may be lzo, lz4, +lz4-v2, stub, stub-v2 or empty. +LZO and LZ4 are different compression algorithms, with LZ4 generally +offering the best performance with least CPU usage.

+

The lz4-v2 and stub-v2 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.

+

If the algorithm parameter is stub, stub-v2 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, stub and stub-v2 wil disable announcing +lzo and lz4 compression support via IV_ variables to the +server.

+

Note: the stub (or empty) option is NOT compatible with the older +option --comp-lzo no.

+

*Security Considerations*

+

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 CRIME and BREACH attacks on TLS and +VORACLE 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 not enable compression.

+
+--comp-lzo mode
 

DEPRECATED Enable LZO compression algorithm. Compression is +generally not recommended. VPN tunnels which uses compression are +suspectible to the VORALCE attack vector.

+

Use LZO compression -- may add up to 1 byte per packet for incompressible +data. mode may be yes, no, or adaptive +(default).

+

In a server mode setup, it is possible to selectively turn compression +on or off for individual clients.

+

First, make sure the client-side config file enables selective +compression by having at least one --comp-lzo directive, such as +--comp-lzo no. This will turn off compression by default, but allow +a future directive push from the server to dynamically change the +on/off/adaptive setting.

+

Next in a --client-config-dir file, specify the compression setting +for the client, for example:

+
+comp-lzo yes
+push "comp-lzo yes"
+
+

The first line sets the comp-lzo setting for the server side of the +link, the second sets the client side.

+
+--comp-noadapt

DEPRECATED When used in conjunction with --comp-lzo, this option +will disable OpenVPN's adaptive compression algorithm. Normally, adaptive +compression is enabled with --comp-lzo.

+

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.

+
+--key-direction
 Alternative way of specifying the optional direction parameter for the +--tls-auth and --secret options. Useful when using inline files +(See section on inline files).
+--keysize n

DEPRECATED This option will be removed in OpenVPN 2.6.

+

Size of cipher key in bits (optional). If unspecified, defaults to +cipher-specific default. The --show-ciphers 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.

+
+--data-ciphers cipher-list
 

Restrict the allowed ciphers to be negotiated to the ciphers in +cipher-list. cipher-list is a colon-separated list of ciphers, +and defaults to AES-256-GCM:AES-128-GCM.

+

For servers, the first cipher from cipher-list that is also +supported by the client will be pushed to clients that support cipher +negotiation.

+

Cipher negotiation is enabled in client-server mode only. I.e. if +--mode is set to 'server' (server-side, implied by setting +--server ), or if --pull is specified (client-side, implied by +setting --client).

+

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 --data-ciphers-fallback.

+

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 --cipher setting, but the peer cipher is one of the +ciphers specified in --data-ciphers. E.g. a non-NCP client (<=v2.3, +or with --ncp-disabled set) connecting to a NCP server (v2.4+) with +--cipher BF-CBC and --data-ciphers AES-256-GCM:AES-256-CBC set can +either specify --cipher BF-CBC or --cipher AES-256-CBC and both +will work.

+

Note for using NCP with an OpenVPN 2.4 peer: This list must include the +AES-256-GCM and AES-128-GCM ciphers.

+

This list is restricted to be 127 chars long after conversion to OpenVPN +ciphers.

+

This option was called --ncp-ciphers in OpenVPN 2.4 but has been renamed +to --data-ciphers in OpenVPN 2.5 to more accurately reflect its meaning.

+
+--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.

+

This option should only be needed to +connect to peers that are running OpenVPN 2.3 and older version, and +have been configured with --enable-small +(typically used on routers or other embedded devices).

+
+--ncp-disableDEPRECATED Disable "Negotiable Crypto Parameters". This completely +disables cipher negotiation.
+--secret args

Enable Static Key encryption mode (non-TLS). Use pre-shared secret +file which was generated with --genkey.

+

Valid syntaxes:

+
+secret file
+secret file direction
+
+

The optional direction 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.

+

When the direction parameter is omitted, 2 keys are used +bidirectionally, one for HMAC and the other for encryption/decryption.

+

The direction parameter should always be complementary on either +side of the connection, i.e. one side should use 0 and the other +should use 1, or both sides should omit it altogether.

+

The direction parameter requires that file contains a 2048 bit +key. While pre-1.5 versions of OpenVPN generate 1024 bit key files, any +version of OpenVPN which supports the direction parameter, will also +support 2048 bit key file generation using the --genkey option.

+

Static key encryption mode has certain advantages, the primary being +ease of configuration.

+

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 ssh) 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.

+

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.

+
+--tran-window n
 Transition window -- our old key can live this many seconds after a new +a key renegotiation begins (default 3600 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.
+
+
+

Client Options

+

The client options are used when connecting to an OpenVPN server configured +to use --server, --server-bridge, or --mode server in its +configuration.

+ +++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+--allow-pull-fqdn
 Allow client to pull DNS names from server (rather than being limited to +IP address) for --ifconfig, --route, and --route-gateway.
+--allow-recursive-routing
 When this option is set, OpenVPN will not drop incoming tun packets with +same destination as host.
+--auth-token token
 

This is not an option to be used directly in any configuration files, +but rather push this option from a --client-connect script or a +--plugin which hooks into the OPENVPN_PLUGIN_CLIENT_CONNECT +or OPENVPN_PLUGIN_CLIENT_CONNECT_V2 calls. This option provides a +possibility to replace the clients password with an authentication token +during the lifetime of the OpenVPN client.

+

Whenever the connection is renegotiated and the +--auth-user-pass-verify script or --plugin making use of the +OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY 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 AUTH_FAILED and disconnect.

+

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.

+

To make use of this feature, the --client-connect script or +--plugin needs to put

+
+push "auth-token UNIQUE_TOKEN_VALUE"
+
+

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 UNIQUE_TOKEN_VALUE.

+

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 --auth-retry

+
+--auth-user-pass
 

Authenticate with server using username/password.

+

Valid syntaxes:

+
+auth-user-pass
+auth-user-pass up
+
+

If up is present, it must be a file containing username/password on 2 +lines. If the password line is missing, OpenVPN will prompt for one.

+

If up is omitted, username/password will be prompted from the +console.

+

The server configuration must specify an --auth-user-pass-verify +script to verify the username/password provided by the client.

+
+--auth-retry type
 

Controls how OpenVPN responds to username/password verification errors +such as the client-side response to an AUTH_FAILED message from +the server or verification failure of the private key password.

+

Normally used to prevent auth errors from being fatal on the client +side, and to permit username/password requeries in case of error.

+

An AUTH_FAILED message is generated by the server if the client +fails --auth-user-pass authentication, or if the server-side +--client-connect script returns an error status when the client +tries to connect.

+

type can be one of:

+
+
none
+
Client will exit with a fatal error (this is the default).
+
nointeract
+
Client will retry the connection without requerying +for an --auth-user-pass username/password. Use this option for +unattended clients.
+
interact
+
Client will requery for an --auth-user-pass +username/password and/or private key password before attempting a +reconnection.
+
+

Note that while this option cannot be pushed, it can be controlled from +the management interface.

+
+--client

A helper directive designed to simplify the configuration of OpenVPN's +client mode. This directive is equivalent to:

+
+pull
+tls-client
+
+
+--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.

+

Examples:

+
+client-nat snat 192.168.0.0/255.255.0.0
+client-nat dnat 10.64.0.0/255.255.0.0
+
+

network/netmask (for example 192.168.0.0/255.255.0.0) defines +the local view of a resource from the client perspective, while +alias/netmask (for example 10.64.0.0/255.255.0.0) defines the +remote view from the server perspective.

+

Use snat (source NAT) for resources owned by the client and +dnat (destination NAT) for remote resources.

+

Set --verb 6 for debugging info showing the transformation of +src/dest addresses in packets.

+
+--connect-retry n
 Wait n seconds between connection attempts (default 5). +Repeated reconnection attempts are slowed down after 5 retries per +remote by doubling the wait time after each unsuccessful attempt. An +optional argument max specifies the maximum value of wait time in +seconds at which it gets capped (default 300).
+--connect-retry-max n
 n specifies the number of times each --remote or +<connection> entry is tried. Specifying n as 1 would try +each entry exactly once. A successful connection resets the counter. +(default unlimited).
+--connect-timeout n
 See --server-poll-timeout.
+--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.

+

The n parameter (default 1 if not present) controls the +maximum number of attempts that the client will try to resend the exit +notification message.

+

In UDP server mode, send RESTART control channel command to +connected clients. The n parameter (default 1 if not present) +controls client behavior. With n = 1 client will attempt to +reconnect to the same server, with n = 2 client will advance +to the next server.

+

OpenVPN will not send any exit notifications unless this option is +enabled.

+
+--inactive args
 

Causes OpenVPN to exit after n 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.

+

Valid syntaxes:

+
+inactive n
+inactive n bytes
+
+

If the optional bytes parameter is included, exit if less than +bytes of combined in/out traffic are produced on the tun/tap device +in n seconds.

+

In any case, OpenVPN's 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.

+
+--proto-force p
 When iterating through connection profiles, only consider profiles using +protocol p (tcp | udp).
+--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 --pull option is implied by +--client ).

+

In particular, --pull allows the server to push routes to the +client, so you should not use --pull or --client in situations +where you don't trust the server to have control over the client's +routing table.

+
+--pull-filter args
 

Filter options on the client pushed by the server to the client.

+

Valid syntaxes:

+
+pull-filter accept text
+pull-filter ignore text
+pull-filter reject text
+
+

Filter options received from the server if the option starts with +text. The action flag accept allows the option, +ignore removes it and reject flags an error and triggers +a SIGUSR1 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.

+

Prefix comparison is used to match text against the received option so +that

+
+pull-filter ignore "route"
+
+

would remove all pushed options starting with route which would +include, for example, route-gateway. Enclose text in quotes to +embed spaces.

+
+pull-filter accept "route 192.168.1."
+pull-filter ignore "route "
+
+

would remove all routes that do not start with 192.168.1.

+

Note that reject 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 ignore.

+
+--remote args

Remote host name or IP address. It supports two additional optional +arguments: port and proto. On the client, multiple --remote +options may be specified for redundancy, each referring to a different +OpenVPN server. Specifying multiple --remote options for this +purpose is a special case of the more general connection-profile +feature. See the <connection> documentation below.

+

The OpenVPN client will try to connect to a server at host:port in +the order specified by the list of --remote options.

+

Examples:

+
+remote server.example.net
+remote server.example.net 1194
+remote server.example.net tcp
+
+

proto indicates the protocol to use when connecting with the remote, +and may be tcp or udp.

+

For forcing IPv4 or IPv6 connection suffix tcp or udp with 4/6 like +udp4/udp6/tcp4/tcp6.

+

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.

+

Note that since UDP is connectionless, connection failure is defined by +the --ping and --ping-restart options.

+

Note the following corner case: If you use multiple --remote +options, AND you are dropping root privileges on the client with +--user and/or --group 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.

+

If --remote 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).

+

When used in TCP mode, --remote will act as a filter, rejecting +connections from any host which does not match host.

+

If host 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.

+
+--remote-random
 When multiple --remote 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.
+--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".
+--resolv-retry n
 

If hostname resolve fails for --remote, retry resolve for n +seconds before failing.

+

Set n to "infinite" to retry indefinitely.

+

By default, --resolv-retry infinite is enabled. You can disable by +setting n=0.

+
+--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.

+

If the daemon is reset by a signal or --ping-restart, it will allow +one new connection.

+

--single-session can be used with --ping-exit or --inactive +to create a single dynamic session that will exit when finished.

+
+--server-poll-timeout n
 When connecting to a remote server do not wait for more than n +seconds for a response before trying the next server. The default value +is 120s. This timeout includes proxy and TCP connect timeouts.
+--static-challenge args
 

Enable static challenge/response protocol

+

Valid syntax:

+
+static-challenge text echo
+
+

The text challenge text is presented to the user which describes what +information is requested. The echo flag indicates if the user's +input should be echoed on the screen. Valid echo values are +0 or 1.

+

See management-notes.txt in the OpenVPN distribution for a description of +the OpenVPN challenge/response protocol.

+
+ +++ + + + + + + + + + + + + + +
+--show-proxy-settings
 Show sensed HTTP or SOCKS proxy settings. Currently, only Windows +clients support this option.
+--http-proxy args
 

Connect to remote host through an HTTP proxy. This requires at least an +address server and port argument. If HTTP Proxy-Authenticate +is required, a file name to an authfile file containing a username +and password on 2 lines can be given, or stdin to prompt from +console. Its content can also be specified in the config file with the +--http-proxy-user-pass option. (See section on inline files)

+

The last optional argument is an auth-method which should be one +of none, basic, or ntlm.

+

HTTP Digest authentication is supported as well, but only via the +auto or auto-nct flags (below). This must replace +the authfile argument.

+

The auto flag causes OpenVPN to automatically determine the +auth-method and query stdin or the management interface for +username/password credentials, if required. This flag exists on OpenVPN +2.1 or higher.

+

The auto-nct flag (no clear-text auth) instructs OpenVPN to +automatically determine the authentication method, but to reject weak +authentication protocols such as HTTP Basic Authentication.

+

Examples:

+
+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
+
+
+--http-proxy-option args
 

Set extended HTTP proxy options. Requires an option type as argument +and an optional parameter to the type. Repeat to set multiple +options.

+
+
VERSION version
+
Set HTTP version number to version (default 1.0).
+
AGENT user-agent
+
Set HTTP "User-Agent" string to user-agent.
+
CUSTOM-HEADER name content
+
Adds the custom Header with name as name and content as +the content of the custom HTTP header.
+
+

Examples:

+
+http-proxy-option VERSION 1.1
+http-proxy-option AGENT OpenVPN/2.4
+http-proxy-option X-Proxy-Flag some-flags
+
+
+--socks-proxy args
 Connect to remote host through a Socks5 proxy. A required server +argument is needed. Optionally a port (default 1080) and +authfile can be given. The authfile is a file containing a +username and password on 2 lines, or stdin can be used to +prompt from console.
+
+
+

Server Options

+

Starting with OpenVPN 2.0, a multi-client TCP/UDP server mode is +supported, and can be enabled with the --mode server 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.

+ +++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+--auth-gen-token args
 

Returns an authentication token to successfully authenticated clients.

+

Valid syntax:

+
+auth-gen-token [lifetime] [external-auth]
+
+

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.

+

The tokens implemented by this mechanism include an initial timestamp and +a renew timestamp and are secured by HMAC.

+

The lifetime 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 0, the token will never expire.

+

The token will expire either after the configured lifetime of the +token is reached or after not being renewed for more than 2 * +reneg-sec 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.

+

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.

+

When the external-auth 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.

+

This option postpones this decision to the external authentication +methods and checks the validity of the account and do other checks.

+

In this mode the environment will have a session_id variable that +holds the session id from auth-gen-token. Also an environment variable +session_state is present. This variable indicates whether the +auth-token has succeeded or not. It can have the following values:

+
+
Initial
+
No token from client.
+
Authenticated
+
Token is valid and not expired.
+
Expired
+
Token is valid but has expired.
+
Invalid
+
Token is invalid (failed HMAC or wrong length)
+
AuthenticatedEmptyUser / ExpiredEmptyUser
+
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 Invalid.
+
+

Warning: 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).

+
+--auth-gen-token-secret file
 Specifies a file that holds a secret for the HMAC used in +--auth-gen-token If file 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.
+--auth-user-pass-optional
 Allow connections by clients that do not specify a username/password. +Normally, when --auth-user-pass-verify or +--management-client-auth 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.
+--ccd-exclusive
 Require, as a condition of authentication, that a connecting client has +a --client-config-dir file.
+--client-config-dir dir
 

Specify a directory dir 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 +"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's root privileges.

+

This file can specify a fixed IP address for a given client using +--ifconfig-push, as well as fixed subnets owned by the client using +--iroute.

+

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.

+

The following options are legal in a client-specific context: --push, +--push-reset, --push-remove, --iroute, --ifconfig-push, +--vlan-pvid and --config.

+
+--client-to-client
 

Because the OpenVPN server mode handles multiple clients through a +single tun or tap interface, it is effectively a router. The +--client-to-client flag tells OpenVPN to internally route +client-to-client traffic rather than pushing all client-originating +traffic to the TUN/TAP interface.

+

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't use this option if you want to firewall tunnel traffic +using custom, per-client rules.

+
+--disable

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 +--crl-verify option).

+

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 --client-config-dir or dynamically generated using a +--client-connect script.

+
+--connect-freq args
 

Allow a maximum of n new connections per sec seconds from +clients.

+

Valid syntax:

+
+connect-freq n sec
+
+

This is designed to contain DoS attacks which flood the server +with connection requests using certificates which will ultimately fail +to authenticate.

+

This is an imperfect solution however, because in a real DoS scenario, +legitimate connections might also be refused.

+

For the best protection against DoS attacks in server mode, use +--proto udp and either --tls-auth or --tls-crypt.

+
+--duplicate-cnAllow 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.
+--ifconfig-pool args
 

Set aside a pool of subnets to be dynamically allocated to connecting +clients, similar to a DHCP server.

+

Valid syntax:

+
+ifconfig-pool start-IP end-IP [netmask]
+
+

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 netmask parameter will also be pushed to clients.

+
+--ifconfig-ipv6-pool args
 

Specify an IPv6 address pool for dynamic assignment to clients.

+

Valid args:

+
+ifconfig-ipv6-pool ipv6addr/bits
+
+

The pool starts at ipv6addr and matches the offset determined from +the start of the IPv4 pool.

+
+--ifconfig-pool-persist args
 

Persist/unpersist ifconfig-pool data to file, at seconds +intervals (default 600), as well as on program startup and shutdown.

+

Valid syntax:

+
+ifconfig-pool-persist file [seconds]
+
+

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 --persist-tun option.

+

file is a comma-delimited ASCII file, formatted as +<Common-Name>,<IP-address>.

+

If seconds = 0, file will be treated as read-only. This +is useful if you would like to treat file as a configuration file.

+

Note that the entries in this file are treated by OpenVPN as +suggestions 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 +--ifconfig-push

+
+--ifconfig-push args
 

Push virtual IP endpoints for client tunnel, overriding the +--ifconfig-pool dynamic allocation.

+

Valid syntax:

+
+ifconfig-push local remote-netmask [alias]
+
+

The parameters local and remote-netmask are set according to the +--ifconfig directive which you want to execute on the client machine +to configure the remote end of the tunnel. Note that the parameters +local and remote-netmask 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.

+

The optional alias 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 local/remote-netmask will refer to the server view while +alias/remote-netmask will refer to the client view.

+

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 --client-config-dir or dynamically generated using a +--client-connect script.

+

Remember also to include a --route directive in the main OpenVPN +config file which encloses local, so that the kernel will know to +route it to the server's TUN/TAP interface.

+

OpenVPN's internal client IP address selection algorithm works as +follows:

+
    +
  1. Use --client-connect script generated file for static IP +(first choice).
    2. +
  2. Use --client-config-dir file for static IP (next choice).
    3. +
  3. Use --ifconfig-pool allocation for dynamic IP (last +choice).
    4. +
+
+--ifconfig-ipv6-push args
 

for --client-config-dir per-client static IPv6 interface +configuration, see --client-config-dir and --ifconfig-push for +more details.

+

Valid syntax:

+
+ifconfig-ipv6-push ipv6addr/bits ipv6remote
+
+
+--inetd args

Valid syntaxes:

+
+inetd
+inetd wait
+inetd nowait
+inetd wait progname
+
+

Use this option when OpenVPN is being run from the inetd or xinetd(8) +server.

+

The wait and nowait option must match what is specified +in the inetd/xinetd config file. The nowait mode can only be used +with --proto tcp-server The default is wait. The +nowait 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: +https://community.openvpn.net/openvpn/wiki/325-openvpn-as-a--forking-tcp-server-which-can-service-multiple-clients-over-a-single-tcp-port

+

This option precludes the use of --daemon, --local or +--remote. Note that this option causes message and error output to +be handled in the same way as the --daemon option. The optional +progname parameter is also handled exactly as in --daemon.

+

Also note that in wait 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: +https://openvpn.net/community-resources/1xhowto/

+
+--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 --local 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.

+
+
Notes:
+
    +
  • This option is only relevant for UDP servers.
    • +
  • 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).
    • +
+
+
+
+--iroute args

Generate an internal route to a specific client. The netmask +parameter, if omitted, defaults to 255.255.255.255.

+

Valid syntax:

+
+iroute network [netmask]
+
+

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 --route directive). The reason why two +routes are needed is that the --route directive routes the packet +from the kernel to OpenVPN. Once in OpenVPN, the --iroute directive +routes to the specific client.

+

This option must be specified either in a client instance config file +using --client-config-dir or dynamically generated using a +--client-connect script.

+

The --iroute directive also has an important interaction with +--push "route ...". --iroute essentially defines a subnet which +is owned by a particular client (we will call this client A). If you +would like other clients to be able to reach A's subnet, you can use +--push "route ..." together with --client-to-client to effect +this. In order for all clients to see A's subnet, OpenVPN must push +this route to all clients EXCEPT for A, since the subnet is already +owned by A. OpenVPN accomplishes this by not not pushing a route to +a client if it matches one of the client's iroutes.

+
+--iroute-ipv6 args
 

for --client-config-dir per-client static IPv6 route configuration, +see --iroute for more details how to setup and use this, and how +--iroute and --route interact.

+

Valid syntax:

+
+iroute-ipv6 ipv6addr/bits
+
+
+--max-clients n
 Limit server to a maximum of n concurrent clients.
+--max-routes-per-client n
 

Allow a maximum of n internal routes per client (default +256). 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 --client-config-dir file or auto-generated by a +--client-connect script to override the global value for a particular +client.

+

Note that this directive affects OpenVPN's internal routing table, not +the kernel routing table.

+
+--opt-verify

Clients that connect with options that are incompatible with those of the +server will be disconnected.

+

Options that will be compared for compatibility include dev-type, +link-mtu, tun-mtu, proto, ifconfig, +comp-lzo, fragment, keydir, cipher, +auth, keysize, secret, no-replay, +tls-auth, key-method, tls-server +and tls-client.

+

This option requires that --disable-occ NOT be used.

+
+--port-share args
 

Share OpenVPN TCP with another service

+

Valid syntax:

+
+port-share host port [dir]
+
+

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 host:port. Currently only designed to +work with HTTP/HTTPS, though it would be theoretically possible to +extend to other protocols such as ssh.

+

dir 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.

+

Not implemented on Windows.

+
+--push option

Push a config file option back to the client for remote execution. Note +that option must be enclosed in double quotes (""). The +client must specify --pull 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.

+

This is a partial list of options which can currently be pushed: +--route, --route-gateway, --route-delay, +--redirect-gateway, --ip-win32, --dhcp-option, +--inactive, --ping, --ping-exit, --ping-restart, +--setenv, --auth-token, --persist-key, --persist-tun, +--echo, --comp-lzo, --socket-flags, --sndbuf, +--rcvbuf

+
+--push-peer-info
 

Push additional information about the client to server. The following +data is always pushed to the server:

+
+
IV_VER=<version>
+
The client OpenVPN version
+
IV_PLAT=[linux|solaris|openbsd|mac|netbsd|freebsd|win]
+
The client OS platform
+
IV_LZO_STUB=1
+
If client was built with LZO stub capability
+
IV_LZ4=1
+
If the client supports LZ4 compressions.
+
IV_PROTO
+

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:

+
    +
  • bit 1: The peer supports peer-id floating mechanism
    • +
  • bit 2: The client expects a push-reply and the server may +send this reply without waiting for a push-request first.
    • +
+
+
IV_NCP=2
+
Negotiable ciphers, client supports --cipher pushed by +the server, a value of 2 or greater indicates client supports +AES-GCM-128 and AES-GCM-256.
+
IV_CIPHERS=<ncp-ciphers>
+
The client announces the list of supported ciphers configured with the +--data-ciphers option to the server.
+
IV_GUI_VER=<gui_id> <version>
+
The UI version of a UI if one is running, for example +de.blinkt.openvpn 0.5.47 for the Android app.
+
+

When --push-peer-info is enabled the additional information consists +of the following data:

+
+
IV_HWADDR=<mac address>
+
The MAC address of clients default gateway
+
IV_SSL=<version string>
+
The ssl version used by the client, e.g. +OpenSSL 1.0.2f 28 Jan 2016.
+
IV_PLAT_VER=x.y
+
The version of the operating system, e.g. 6.1 for Windows 7.
+
UV_<name>=<value>
+
Client environment variables whose names start with +UV_
+
+
+--push-remove opt
 

Selectively remove all --push options matching "opt" from the option +list for a client. opt is matched as a substring against the whole +option string to-be-pushed to the client, so --push-remove route +would remove all --push route ... and --push route-ipv6 ... +statements, while --push-remove "route-ipv6 2001:" would only remove +IPv6 routes for 2001:... networks.

+

--push-remove can only be used in a client-specific context, like in +a --client-config-dir file, or --client-connect script or plugin +-- similar to --push-reset, just more selective.

+

NOTE: to change an option, --push-remove can be used to first +remove the old value, and then add a new --push option with the new +value.

+

NOTE 2: due to implementation details, 'ifconfig' and 'ifconfig-ipv6' +can only be removed with an exact match on the option ( +push-remove ifconfig), no substring matching and no matching on +the IPv4/IPv6 address argument is possible.

+
+--push-resetDon't inherit the global push list for a specific client instance. +Specify this option in a client-specific context such as with a +--client-config-dir configuration file. This option will ignore +--push options at the global config file level.
+--server args

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 .1 address of the given network for +use as the server-side endpoint of the local TUN/TAP interface. If the +optional nopool flag is given, no dynamic IP address pool will +prepared for VPN clients.

+

Valid syntax:

+
+server network netmask [nopool]
+
+

For example, --server 10.8.0.0 255.255.255.0 expands as follows:

+
+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
+
+

Don't use --server if you are ethernet bridging. Use +--server-bridge instead.

+
+--server-bridge args
 

A helper directive similar to --server which is designed to simplify +the configuration of OpenVPN's server mode in ethernet bridging +configurations.

+

Valid syntaxes:

+
+server-bridge gateway netmask pool-start-IP pool-end-IP
+server-bridge [nogw]
+
+

If --server-bridge 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 nogw flag (advanced) indicates that gateway +information should not be pushed to the client.

+

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 brctl 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".

+

Next you you must manually set the IP/netmask on the bridge interface. +The gateway and netmask parameters to --server-bridge 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.

+

Finally, set aside a IP range in the bridged subnet, denoted by +pool-start-IP and pool-end-IP, for OpenVPN to allocate to +connecting clients.

+

For example, server-bridge 10.8.0.4 255.255.255.0 10.8.0.128 +10.8.0.254 expands as follows:

+
+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"
+
+

In another example, --server-bridge (without parameters) expands as +follows:

+
+mode server
+tls-server
+
+push "route-gateway dhcp"
+
+

Or --server-bridge nogw expands as follows:

+
+mode server
+tls-server
+
+
+--stale-routes-check args
 

Remove routes which haven't had activity for n seconds (i.e. the ageing +time). This check is run every t seconds (i.e. check interval).

+

Valid syntax:

+
+stale-routes-check n [t]
+
+

If t is not present it defaults to n.

+

This option helps to keep the dynamic routing table small. See also +--max-routes-per-client

+
+--username-as-common-name
 For --auth-user-pass-verify authentication, use the authenticated +username as the common name, rather than the common name from the client +cert.
+--verify-client-cert mode
 

Specify whether the client is required to supply a valid certificate.

+

Possible mode options are:

+
+
none
+

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.

+

If you use this directive, the entire responsibility of authentication +will rest on your --auth-user-pass-verify script, so keep in mind +that bugs in your script could potentially compromise the security of +your VPN.

+

--verify-client-cert none is functionally equivalent to +--client-cert-not-required.

+
+
optional
+

A client may present a certificate but it is not required to do so. +When using this directive, you should also use a +--auth-user-pass-verify script to ensure that clients are +authenticated using a certificate, a username and password, or +possibly even both.

+

Again, the entire responsibility of authentication will rest on your +--auth-user-pass-verify script, so keep in mind that bugs in your +script could potentially compromise the security of your VPN.

+
+
require
+
This is the default option. A client is required to present a +certificate, otherwise VPN access is refused.
+
+

If you don't use this directive (or use --verify-client-cert require) +but you also specify an --auth-user-pass-verify script, then OpenVPN +will perform double authentication. The client certificate verification +AND the --auth-user-pass-verify script will need to succeed in order +for a client to be authenticated and accepted onto the VPN.

+
+--vlan-tagging

Server-only option. Turns the OpenVPN server instance into a switch that +understands VLAN-tagging, based on IEEE 802.1Q.

+

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 +--vlan-accept setting.

+

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".

+

Using the --vlan-pvid v 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 --client-to-client is activated.

+

The packet filtering takes place in the OpenVPN server. Clients should +not have any VLAN tagging configuration applied.

+

The --vlan-tagging option is off by default. While turned off, +OpenVPN accepts any Ethernet frame and does not perform any special +processing for VLAN-tagged packets.

+

This option can only be activated in --dev tap mode.

+
+--vlan-accept args
 

Configure the VLAN tagging policy for the server TAP device.

+

Valid syntax:

+
+vlan-accept  all|tagged|untagged
+
+

The following modes are available:

+
+
tagged
+
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.
+
untagged
+
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 +--vlan-pvid setting.
+
all (default)
+
Admit all frames. All packets are admitted and then treated like +untagged or tagged mode respectively.
+
Note:
+
Some vendors refer to switch ports running in tagged mode +as "trunk ports" and switch ports running in untagged mode +as "access ports".
+
+

Packets forwarded from clients to the server are VLAN-tagged with the +originating client's PVID, unless the VID matches the global +--vlan-pvid, in which case the tag is removed.

+

If no PVID is configured for a given client (see --vlan-pvid) packets +are tagged with 1 by default.

+
+--vlan-pvid v

Specifies which VLAN identifier a "port" is associated with. Only valid +when --vlan-tagging is speficied.

+

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 --vlan-accept +untagged and --vlan-accept all modes.

+

Valid values for v go from 1 through to 4094. The +global value defaults to 1. If no --vlan-pvid is specified in +the client context, the global value is inherited.

+

In some switch implementations, the PVID is also referred to as "Native +VLAN".

+
+
+
+
+

Encryption Options

+
+

SSL Library information

+ +++ + + + + + + + + + + + +
+--show-ciphers(Standalone) Show all cipher algorithms to use with the --cipher +option.
+--show-digests(Standalone) Show all message digest algorithms to use with the +--auth option.
+--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.

+

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.).

+
+--show-engines(Standalone) Show currently available hardware-based crypto acceleration +engines supported by the OpenSSL library.
+--show-groups(Standalone) Show all available elliptic curves/groups to use with the +--ecdh-curve and tls-groups options.
+
+
+

Generating key material

+ +++ + + + +
+--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.

+

Valid syntax:

+
+--genkey keytype keyfile
+
+

Valid keytype arguments are:

+

secret Standard OpenVPN shared secret keys

+

tls-crypt Alias for secret

+

tls-auth Alias for secret

+

auth-token Key used for --auth-gen-token-key

+

tls-crypt-v2-server TLS Crypt v2 server key

+

tls-crypt-v2-client TLS Crypt v2 client key

+

Examples:

+
+$ 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
+
+
    +

  • Generating Shared Secret Keys +Generate a shared secret, for use with the --secret, --tls-auth +or --tls-crypt options.

    +

    Syntax:

    +
    +$ openvpn --genkey secret|tls-crypt|tls-auth keyfile
+
    +

    The key is saved in keyfile. All three variants (--secret, +tls-crypt and tls-auth) generate the same type of key. The +aliases are added for convenience.

    +

    If using this for --secret, this file must be shared with the peer +over a pre-existing secure channel such as scp(1).

    +
    • +

  • Generating TLS Crypt v2 Server key +Generate a --tls-crypt-v2 key to be used by an OpenVPN server. +The key is stored in keyfile.

    +

    Syntax:

    +
    +--genkey tls-crypt-v2-server keyfile
+
    +
    • +

  • Generating TLS Crypt v2 Client key +Generate a --tls-crypt-v2 key to be used by OpenVPN clients. The +key is stored in keyfile.

    +

    Syntax

    +
    +--genkey tls-crypt-v2-client keyfile [metadata]
+
    +

    If supplied, include the supplied metadata 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).

    +

    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.

    +

    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 +--tls-crypt-v2 option.

    +

    Servers can use --tls-crypt-v2-verify to specify a metadata +verification command.

    +
    • +

  • Generate Authentication Token key +Generate a new secret that can be used with --auth-gen-token-secret

    +

    Syntax:

    +
    +--genkey auth-token [keyfile]
+
    +
    +
    Note:
    +

    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.

    +
    +
    +
    • +
+
+
+
+

Data Channel Renegotiation

+

When running OpenVPN in client/server mode, the data channel will use a +separate ephemeral encryption key which is rotated at regular intervals.

+ +++ + + + + + + + + + +
+--reneg-bytes n
 

Renegotiate data channel key after n 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.

+

If using ciphers with cipher block sizes less than 128-bits, +--reneg-bytes is set to 64MB by default, unless it is explicitly +disabled by setting the value to 0, but this is +HIGHLY DISCOURAGED as this is designed to add some protection against +the SWEET32 attack vector. For more information see the --cipher +option.

+
+--reneg-pkts nRenegotiate data channel key after n packets sent and received +(disabled by default).
+--reneg-sec args
 

Renegotiate data channel key after at most max seconds +(default 3600) and at least min seconds (default is 90% of +max for servers, and equal to max for clients).

+
+reneg-sec max [min]
+
+

The effective --reneg-sec value used is per session +pseudo-uniform-randomized between min and max.

+

With the default value of 3600 this results in an effective per +session value in the range of 3240..:code:3600 seconds for +servers, or just 3600 for clients.

+

When using dual-factor authentication, note that this default value may +cause the end user to be challenged to reauthorize once per hour.

+

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 --reneg-sec to a +higher value on either the client or server, while the other side of the +connection is still using the default value of 3600 seconds, +meaning that the renegotiation will still occur once per 3600 +seconds. The solution is to increase --reneg-sec on both the client and +server, or set it to 0 on one side of the connection (to +disable), and to your chosen value on the other side.

+
+
+
+

TLS Mode Options

+

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.

+

To use TLS mode, each peer that runs OpenVPN should have its own local +certificate/key pair (--cert and --key), signed by the root +certificate which is specified in --ca.

+

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 --ca.

+

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.

+

The OpenVPN project provides a set of scripts for managing RSA +certificates and keys: https://github.com/OpenVPN/easy-rsa

+ +++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+--askpass file

Get certificate password from console or file before we daemonize.

+

Valid syntaxes:

+
+askpass
+askpass file
+
+

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 +--askpass 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 -nodes option when +you use the openssl command line tool to manage certificates and +private keys.

+

If file is specified, read the password from the first line of +file. Keep in mind that storing your password in a file to a certain +extent invalidates the extra security provided by using an encrypted +key.

+
+--ca file

Certificate authority (CA) file in .pem format, also referred to as the +root 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:

+
+openssl req -nodes -new -x509 -keyout ca.key -out ca.crt
+
+

Then edit your openssl.cnf file and edit the certificate variable to +point to your new root certificate ca.crt.

+

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.

+
+--capath dir

Directory containing trusted certificates (CAs and CRLs). Not available +with mbed TLS.

+

CAs in the capath directory are expected to be named <hash>.<n>. CRLs +are expected to be named <hash>.r<n>. See the -CApath option of +openssl verify, and the -hash option of openssl x509, +openssl crl and X509_LOOKUP_hash_dir()(3) +for more information.

+

Similar to the --crl-verify 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.

+
+--cert file

Local peer's signed certificate in .pem format -- must be signed by a +certificate authority whose certificate is in --ca file. 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 --ca 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:

+
+openssl req -nodes -new -keyout mycert.key -out mycert.csr
+
+

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:

+
+openssl ca -out mycert.crt -in mycert.csr
+
+

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 openssl ca command reads the location of the certificate +authority key from its configuration file such as +/usr/share/ssl/openssl.cnf -- note also that for certificate +authority functions, you must set up the files index.txt (may be +empty) and serial (initialize to 01).

+
+--crl-verify args
 

Check peer certificate against a Certificate Revocation List.

+

Valid syntax:

+
+crl-verify file/directory flag
+
+

Examples:

+
+crl-verify crl-file.pem
+crl-verify /etc/openvpn/crls dir
+
+

A CRL (certificate revocation list) is used when a particular key is +compromised but when the overall PKI is still intact.

+

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.

+

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.

+

The option is not mandatory - if the relevant CRL is missing, OpenVPN +will log a warning in the logs - e.g.

+
+VERIFY WARNING: depth=0, unable to get certificate CRL
+
+

but the connection will be allowed. If the optional dir flag +is specified, enable a different mode where the crl-verify 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.

+
+
Note:
+
As the crl file (or directory) is read every time a peer +connects, if you are dropping root privileges with +--user, make sure that this user has sufficient +privileges to read the file.
+
+
+--dh file

File containing Diffie Hellman parameters in .pem format (required for +--tls-server only).

+

Set file to none 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+).

+

Use openssl dhparam -out dh2048.pem 2048 to generate 2048-bit DH +parameters. Diffie Hellman parameters may be considered public.

+
+--ecdh-curve name
 

Specify the curve to use for elliptic curve Diffie Hellman. Available +curves can be listed with --show-curves. The specified curve will +only be used for ECDH TLS-ciphers.

+

This option is not supported in mbed TLS builds of OpenVPN.

+
+--extra-certs file
 

Specify a file containing one or more PEM certs (concatenated +together) that complete the local certificate chain.

+

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 ca file.

+
+--hand-window n
 Handshake Window -- the TLS-based key exchange must finalize within +n seconds of handshake initiation by any peer (default 60 +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 --tran-window seconds to +maintain continuity of transmission of tunnel data.
+--key fileLocal peer's private key in .pem format. Use the private key which was +generated when you built your peer's certificate (see --cert file +above).
+--pkcs12 fileSpecify a PKCS #12 file containing local private key, local certificate, +and root CA certificate. This option can be used instead of --ca, +--cert, and --key. Not available with mbed TLS.
+--remote-cert-eku oid
 

Require that peer certificate was signed with an explicit extended key +usage.

+

This is a useful security option for clients, to ensure that the host +they connect to is a designated server.

+

The extended key usage should be encoded in oid notation, or OpenSSL +symbolic representation.

+
+--remote-cert-ku key-usage
 

Require that peer certificate was signed with an explicit +key-usage.

+

If present in the certificate, the keyUsage 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).

+

If key-usage is a list of usage bits, the keyUsage field +must have at least the same bits set as the bits in one of the values +supplied in the key-usage list.

+

The key-usage values in the list must be encoded in hex, e.g.

+
+remote-cert-ku a0
+
+
+--remote-cert-tls type
 

Require that peer certificate was signed with an explicit key usage +and extended key usage based on RFC3280 TLS rules.

+

Valid syntaxes:

+
+remote-cert-tls server
+remote-cert-tls client
+
+

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.

+

The --remote-cert-tls client option is equivalent to

+
+remote-cert-ku
+remote-cert-eku "TLS Web Client Authentication"
+
+

The --remote-cert-tls server option is equivalent to

+
+remote-cert-ku
+remote-cert-eku "TLS Web Server Authentication"
+
+

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 --remote-cert-tls, --verify-x509-name, or --tls-verify.

+
+--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.

+

Valid syntaxes:

+
+tls-auth file
+tls-auth file 0
+tls-auth file 1
+
+

In a nutshell, --tls-auth enables a kind of "HMAC firewall" on +OpenVPN's TCP/UDP port, where TLS control channel packets bearing an +incorrect HMAC signature can be dropped immediately without response.

+

file (required) is a file in OpenVPN static key format which can be +generated by --genkey.

+

Older versions (up to OpenVPN 2.3) supported a freeform passphrase file. +This is no longer supported in newer versions (v2.4+).

+

See the --secret option for more information on the optional +direction parameter.

+

--tls-auth is recommended when you are running OpenVPN in a mode +where it is listening for packets from any IP address, such as when +--remote is not specified, or --remote is specified with +--float.

+

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.

+

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.

+

--tls-auth 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. --tls-auth can be +strengthened by adding the --replay-persist option which will keep +OpenVPN's replay protection state in a file so that it is not lost +across restarts.

+

It should be emphasized that this feature is optional and that the key +file used with --tls-auth gives a peer nothing more than the power +to initiate a TLS handshake. It is not used to encrypt or authenticate +any tunnel data.

+

Use --tls-crypt instead if you want to use the key file to not only +authenticate, but also encrypt the TLS control channel.

+
+--tls-groups list
 

A list of allowable groups/curves in order of preference.

+

Set the allowed elliptic curves/groups for the TLS session. +These groups are allowed to be used in signatures and key exchange.

+

mbedTLS currently allows all known curves per default.

+

OpenSSL 1.1+ restricts the list per default to

+
+"X25519:secp256r1:X448:secp521r1:secp384r1".
+
+

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 --ecdh-curve, the groups for ecdh will also be picked +from this list.

+

OpenVPN maps the curve name secp256r1 to prime256v1 to allow +specifying the same tls-groups option for mbedTLS and OpenSSL.

+

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.

+
+--tls-cert-profile profile
 

Set the allowed cryptographic algorithms for certificates according to +profile.

+

The following profiles are supported:

+
+
legacy (default)
+
SHA1 and newer, RSA 2048-bit+, any elliptic curve.
+
preferred
+
SHA2 and newer, RSA 2048-bit+, any elliptic curve.
+
suiteb
+
SHA256/SHA384, ECDSA with P-256 or P-384.
+
+

This option is only fully supported for mbed TLS builds. OpenSSL builds +use the following approximation:

+
+
legacy (default)
+
sets "security level 1"
+
preferred
+
sets "security level 2"
+
suiteb
+
sets "security level 3" and --tls-cipher "SUITEB128".
+
+

OpenVPN will migrate to 'preferred' as default in the future. Please +ensure that your keys already comply.

+
+
+
WARNING: --tls-ciphers, --tls-ciphersuites and tls-groups
+
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!
+
+ +++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+--tls-cipher l

A list l of allowable TLS ciphers delimited by a colon (":").

+

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.

+

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.

+

For OpenSSL, the --tls-cipher is used for TLS 1.2 and below.

+

Use --show-tls to see a list of TLS ciphers supported by your crypto +library.

+

The default for --tls-cipher is to use mbed TLS's default cipher list +when using mbed TLS or +DEFAULT:!EXP:!LOW:!MEDIUM:!kDH:!kECDH:!DSS:!PSK:!SRP:!kRSA when +using OpenSSL.

+

The default for --tls-ciphersuites is to use the crypto library's +default.

+
+--tls-ciphersuites l
 Same as --tls-cipher but for TLS 1.3 and up. mbed TLS has no +TLS 1.3 support yet and only the --tls-cipher setting is used.
+--tls-clientEnable TLS and assume client role during TLS handshake.
+--tls-crypt keyfile
 

Encrypt and authenticate all control channel packets with the key from +keyfile. (See --tls-auth for more background.)

+

Encrypting (and authenticating) control channel packets:

+
    +
  • provides more privacy by hiding the certificate used for the TLS +connection,
    • +
  • makes it harder to identify OpenVPN traffic as such,
    • +
  • provides "poor-man's" post-quantum security, against attackers who will +never know the pre-shared key (i.e. no forward secrecy).
    • +
+

In contrast to --tls-auth, --tls-crypt does not require the +user to set --key-direction.

+

Security Considerations

+

All peers use the same --tls-crypt 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.)

+

If IV collisions were to occur, this could result in the security of +--tls-crypt degrading to the same security as using --tls-auth. +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.

+

For large setups or setups where clients are not trusted, consider using +--tls-crypt-v2 instead. That uses per-client unique keys, and +thereby improves the bounds to 'rotate a client key at least once per +8000 years'.

+
+--tls-crypt-v2 keyfile
 

Use client-specific tls-crypt keys.

+

For clients, keyfile is a client-specific tls-crypt key. Such a key +can be generated using the --genkey tls-crypt-v2-client option.

+

For servers, keyfile 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 --genkey +tls-crypt-v2-client).

+

On servers, this option can be used together with the --tls-auth or +--tls-crypt option. In that case, the server will detect whether the +client is using client-specific keys, and automatically select the right +mode.

+
+--tls-crypt-v2-verify cmd
 

Run command cmd 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.

+

OpenVPN supplies the following environment variables to the command:

+
    +
  • script_type is set to tls-crypt-v2-verify
    • +
  • metadata_type is set to 0 if the metadata was user +supplied, or 1 if it's a 64-bit unix timestamp representing +the key creation time.
    • +
  • metadata_file contains the filename of a temporary file that +contains the client metadata.
    • +
+

The command can reject the connection by exiting with a non-zero exit +code.

+
+--tls-exitExit on TLS negotiation failure.
+--tls-export-cert directory
 Store the certificates the clients use upon connection to this +directory. This will be done before --tls-verify 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 peer_cert environment variable.
+--tls-serverEnable 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.
+--tls-timeout n
 Packet retransmit timeout on TLS control channel if no acknowledgment +from remote within n seconds (default 2). When OpenVPN sends +a control packet to its peer, it will expect to receive an +acknowledgement within n 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.
+--tls-version-min args
 

Sets the minimum TLS version we will accept from the peer (default is +"1.0").

+

Valid syntax:

+
+tls-version-min version ['or-highest']
+
+

Examples for version include 1.0, 1.1, or 1.2. If +or-highest is specified and version is not recognized, we will +only accept the highest TLS version supported by the local SSL +implementation.

+
+--tls-version-max version
 Set the maximum TLS version we will use (default is the highest version +supported). Examples for version include 1.0, 1.1, or +1.2.
+--verify-hash args
 

Specify SHA1 or SHA256 fingerprint for level-1 cert.

+

Valid syntax:

+
+verify-hash hash [algo]
+
+

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 hash or certificate verification +will fail. Hash is specified as XX:XX:... For example:

+
+AD:B0:95:D8:09:C8:36:45:12:A9:89:C8:90:09:CB:13:72:A6:AD:16
+
+

The algo flag can be either SHA1 or SHA256. If not +provided, it defaults to SHA1.

+
+--verify-x509-name args
 

Accept connections only if a host's X.509 name is equal to name. The +remote host must also pass all other tests of verification.

+

Valid syntax:

+
+verify-x509 name type
+
+

Which X.509 name is compared to name depends on the setting of type. +type can be subject to match the complete subject DN +(default), name to match a subject RDN or name-prefix to +match a subject RDN prefix. Which RDN is verified as name depends on the +--x509-username-field option. But it defaults to the common name +(CN), e.g. a certificate with a subject DN

+
+C=KG, ST=NA, L=Bishkek, CN=Server-1
+
+

would be matched by:

+
+verify-x509-name 'C=KG, ST=NA, L=Bishkek, CN=Server-1'
+verify-x509-name Server-1 name
+verify-x509-name Server- name-prefix
+
+

The last example is useful if you want a client to only accept +connections to Server-1, Server-2, etc.

+

--verify-x509-name is a useful replacement for the --tls-verify +option to verify the remote host, because --verify-x509-name works +in a --chroot environment without any dependencies.

+

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.

+
+
NOTE:
+
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 name-prefix when your client +certificates are signed by a third party, such as a commercial +web CA.
+
+
+--x509-track attribute
 Save peer X509 attribute value in environment for use by plugins and +management interface. Prepend a + to attribute to save values +from full cert chain. Values will be encoded as +X509_<depth>_<attribute>=<value>. Multiple --x509-track +options can be defined to track multiple attributes.
+--x509-username-field args
 

Field in the X.509 certificate subject to be used as the username +(default CN).

+

Valid syntax:

+
+x509-username-field [ext:]fieldname
+
+

Typically, this option is specified with fieldname as +either of the following:

+
+x509-username-field emailAddress
+x509-username-field ext:subjectAltName
+
+

The first example uses the value of the emailAddress attribute +in the certificate's Subject field as the username. The second example +uses the ext: prefix to signify that the X.509 extension +fieldname subjectAltName be searched for an rfc822Name +(email) field to be used as the username. In cases where there are +multiple email addresses in ext:fieldname, the last occurrence +is chosen.

+

When this option is used, the --verify-x509-name option will match +against the chosen fieldname instead of the Common Name.

+

Only the subjectAltName and issuerAltName X.509 +extensions are supported.

+

Please note: This option has a feature which will convert an +all-lowercase fieldname to uppercase characters, e.g., +ou -> OU. A mixed-case fieldname or one having the +ext: prefix will be left as-is. This automatic upcasing feature is +deprecated and will be removed in a future release.

+
+
+
+

PKCS#11 / SmartCard options

+ +++ + + + + + + + + + + + + + + + + + + + + + + + + + +
+--pkcs11-cert-private args
 

Set if access to certificate object should be performed after login. +Every provider has its own setting.

+

Valid syntaxes:

+
+pkcs11-cert-private 0
+pkcs11-cert-private 1
+
+
+--pkcs11-id name
 Specify the serialized certificate id to be used. The id can be gotten +by the standalone --show-pkcs11-ids option.
+--pkcs11-id-management
 Acquire PKCS#11 id from management interface. In this case a +NEED-STR 'pkcs11-id-request' 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.
+--pkcs11-pin-cache seconds
 Specify how many seconds the PIN can be cached, the default is until the +token is removed.
+--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:

+

0 (default) Try to determine automatically.

+

1 Use sign.

+

2 Use sign recover.

+

4 Use decrypt.

+

8 Use unwrap.

+
+--pkcs11-protected-authentication args
 

Use PKCS#11 protected authentication path, useful for biometric and +external keypad devices. Every provider has its own setting.

+

Valid syntaxes:

+
+pkcs11-protected-authentication 0
+pkcs11-protected-authentication 1
+
+
+--pkcs11-providers provider
 

Specify an RSA Security Inc. PKCS #11 Cryptographic Token Interface +(Cryptoki) providers to load. This option can be used instead of +--cert, --key and --pkcs12.

+

If p11-kit is present on the system, its p11-kit-proxy.so module +will be loaded by default if either the --pkcs11-id or +--pkcs11-id-management options are specified without +--pkcs11-provider being given.

+
+--show-pkcs11-ids args
 

(Standalone) Show PKCS#11 token object list.

+

Valid syntax:

+
+show-pkcs11 [provider] [cert_private]
+
+

Specify cert_private as 1 if certificates are stored as +private objects.

+

If p11-kit is present on the system, the provider argument is +optional; if omitted the default p11-kit-proxy.so module will be +queried.

+

--verb option can be used BEFORE this option to produce debugging +information.

+
+
+
+
+

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 +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 IV_NCP=2.

+

This only causes a problem if --ncp-ciphers option has been changed from the +default of 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-ciphers 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 ./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 ./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.

+
+
+
+

NETWORK CONFIGURATION

+

OpenVPN consists of two sides of network configuration. One side is the +link between the local and remote side, the other side is the virtual +network adapter (tun/tap device).

+ +
+

Virtual Network Adapter (VPN interface)

+

Options in this section relates to configuration of the virtual tun/tap +network interface, including setting the VPN IP address and network +routing.

+ +++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+--bind-dev device
 (Linux only) Set device to bind the server socket to a +Virtual Routing and Forwarding device
+--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. --block-ipv6 +will use the remote IPv6 as source address of the ICMPv6 packets if set, +otherwise will use fe80::7 as source address.

+

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.

+
+
Client config
+
+--ifconfig-ipv6 fd15:53b6:dead::2/64 fd15:53b6:dead::1
+--redirect-gateway ipv6
+--block-ipv6
+
+
+
Server config
+

Push a "valid" ipv6 config to the client and block on the server

+
+--push "ifconfig-ipv6 fd15:53b6:dead::2/64 fd15:53b6:dead::1"
+--push "redirect-gateway ipv6"
+--block-ipv6
+
+
+
+
+--dev device

TUN/TAP virtual network device which can be tunX, tapX, +null or an arbitrary name string (X can be omitted for +a dynamic device.)

+

See examples section below for an example on setting up a TUN device.

+

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:

+
+
tun
+
devices encapsulate IPv4 or IPv6 (OSI Layer 3)
+
tap
+
devices encapsulate Ethernet 802.3 (OSI Layer 2).
+
+

Valid syntaxes:

+
+dev tun2
+dev tap4
+dev ovpn
+
+

When the device name starts with tun or tap, the device +type is extracted automatically. Otherwise the --dev-type option +needs to be added as well.

+
+--dev-node node
 

Explicitly set the device node rather than using /dev/net/tun, +/dev/tun, /dev/tap, etc. If OpenVPN cannot figure out +whether node is a TUN or TAP device based on the name, you should +also specify --dev-type tun or --dev-type tap.

+

Under Mac OS X this option can be used to specify the default tun +implementation. Using --dev-node utun forces usage of the native +Darwin tun kernel support. Use --dev-node utunN to select a specific +utun instance. To force using the tun.kext (/dev/tunX) +use --dev-node tun. When not specifying a --dev-node option +openvpn will first try to open utun, and fall back to tun.kext.

+

On Windows systems, select the TAP-Win32 adapter which is named node +in the Network Connections Control Panel or the raw GUID of the adapter +enclosed by braces. The --show-adapters 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.

+
+--dev-type device-type
 Which device type are we using? device-type should be tun +(OSI Layer 3) or tap (OSI Layer 2). Use this option only if +the TUN/TAP device used with --dev does not begin with tun +or tap.
+--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 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 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:

+
+dhcp-options type [parm]
+
+
+
DOMAIN name
+
Set Connection-specific DNS Suffix to name.
+
DOMAIN-SEARCH name
+
Add name to the domain search list. +Repeat this option to add more entries. Up to +10 domains are supported.
+
DNS address
+

Set primary domain name server IPv4 or IPv6 address. +Repeat this option to set secondary DNS server addresses.

+

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 --up script could act upon it if needed.

+
+
WINS address
+
Set primary WINS server address (NetBIOS over TCP/IP Name Server). +Repeat this option to set secondary WINS server addresses.
+
NBDD address
+
Set primary NBDD server address (NetBIOS over TCP/IP Datagram +Distribution Server). Repeat this option to set secondary NBDD +server addresses.
+
NTP address
+
Set primary NTP server address (Network Time Protocol). +Repeat this option to set secondary NTP server addresses.
+
NBT type
+

Set NetBIOS over TCP/IP Node type. Possible options:

+
+
1
+
b-node (broadcasts)
+
2
+
p-node (point-to-point name queries to a WINS server)
+
4
+
m-node (broadcast then query name server)
+
8
+
h-node (query name server, then broadcast).
+
+
+
NBS scope-id
+
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 NeonSurge@abyss.com)
+
DISABLE-NBT
+
Disable Netbios-over-TCP/IP.
+
+
+--ifconfig args
 

Set TUN/TAP adapter parameters. It requires the IP address 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 --topology subnet, the second argument +is the subnet mask of the virtual network segment which is being created +or connected to.

+

For TUN devices, which facilitate virtual point-to-point IP connections +(when used in --topology net30 or p2p mode), the proper usage of +--ifconfig 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 rn, you will be pinging +across the VPN.

+

For TAP devices, which provide the ability to create virtual ethernet +segments, or TUN devices in --topology subnet mode (which create +virtual "multipoint networks"), --ifconfig 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).

+

This option, while primarily a proxy for the ifconfig(8) command, +is designed to simplify TUN/TAP tunnel configuration by providing a +standard interface to the different ifconfig implementations on +different platforms.

+

--ifconfig parameters which are IP addresses can also be specified +as a DNS or /etc/hosts file resolvable name.

+

For TAP devices, --ifconfig should not be used if the TAP interface +will be getting an IP address lease from a DHCP server.

+

Examples:

+
+# 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
+
+
+--ifconfig-ipv6 args
 

Configure an IPv6 address on the tun device.

+

Valid syntax:

+
+ifconfig-ipv6 ipv6addr/bits [ipv6remote]
+
+

The ipv6addr/bits argument is the IPv6 address to use. The +second parameter is used as route target for --route-ipv6 if no +gateway is specified.

+

The --topology option has no influence with --ifconfig-ipv6

+
+--ifconfig-noexec
 Don't actually execute ifconfig/netsh commands, instead pass +--ifconfig parameters to scripts using environmental variables.
+--ifconfig-nowarn
 

Don't output an options consistency check warning if the --ifconfig +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 --disable-occ option) while only +disabling the ifconfig component of the check.

+

For example, if you have a configuration where the local host uses +--ifconfig but the remote host does not, use --ifconfig-nowarn +on the local host.

+

This option will also silence warnings about potential address conflicts +which occasionally annoy more experienced users by triggering "false +positive" warnings.

+
+--lladdr address
 Specify the link layer address, more commonly known as the MAC address. +Only applied to TAP devices.
+--persist-tun

Don't close and reopen TUN/TAP device or run up/down scripts across +SIGUSR1 or --ping-restart restarts.

+

SIGUSR1 is a restart signal similar to SIGHUP, but which +offers finer-grained control over reset options.

+
+--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.

+

This option performs three steps:

+
    +
  1. Create a static route for the --remote address which +forwards to the pre-existing default gateway. This is done so that +(3) will not create a routing loop.
    2. +
  2. Delete the default gateway route.
    3. +
  3. Set the new default gateway to be the VPN endpoint address +(derived either from --route-gateway or the second parameter to +--ifconfig when --dev tun is specified).
    4. +
+

When the tunnel is torn down, all of the above steps are reversed so +that the original default route is restored.

+

Option flags:

+
+
local
+
Add the local flag if both OpenVPN peers are directly +connected via a common subnet, such as with wireless. The +local flag will cause step (1) above to be omitted.
+
autolocal
+
Try to automatically determine whether to enable local +flag above.
+
def1
+
Use this flag to override the default gateway by using +0.0.0.0/1 and 128.0.0.0/1 rather than +0.0.0.0/0. This has the benefit of overriding but not +wiping out the original default gateway.
+
bypass-dhcp
+
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).
+
bypass-dns
+
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).
+
block-local
+
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.
+
ipv6
+
Redirect IPv6 routing into the tunnel. This works similar to +the def1 flag, that is, more specific IPv6 routes are added +(2000::/4, 3000::/4), covering the whole IPv6 +unicast space.
+
!ipv4
+
Do not redirect IPv4 traffic - typically used in the flag pair +ipv6 !ipv4 to redirect IPv6-only.
+
+
+--redirect-private flags
 Like --redirect-gateway, but omit actually changing the default gateway. +Useful when pushing private subnets.
+--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.

+

Valid syntaxes:

+
+route network/IP
+route network/IP netmask
+route network/IP netmask gateway
+route network/IP netmask gateway metric
+
+

This option is intended as a convenience proxy for the route(8) +shell command, while at the same time providing portable semantics +across OpenVPN's platform space.

+
+
netmask
+
defaults to 255.255.255.255 when not given
+
gateway
+
default taken from --route-gateway or the second +parameter to --ifconfig when --dev tun is specified.
+
metric
+
default taken from --route-metric if set, otherwise 0.
+
+

The default can be specified by leaving an option blank or setting it to +default.

+

The network and gateway parameters can also be specified as a +DNS or /etc/hosts file resolvable name, or as one of three special +keywords:

+
+
vpn_gateway
+
The remote VPN endpoint address (derived either from +--route-gateway or the second parameter to --ifconfig +when --dev tun is specified).
+
net_gateway
+
The pre-existing IP default gateway, read from the +routing table (not supported on all OSes).
+
remote_host
+
The --remote address if OpenVPN is being run in +client mode, and is undefined in server mode.
+
+
+--route-delay args
 

Valid syntaxes:

+
+route-delay
+route-delay n
+route-delay n m
+
+

Delay n seconds (default 0) after connection establishment, +before adding routes. If n is 0, routes will be added +immediately upon connection establishment. If --route-delay is +omitted, routes will be added immediately after TUN/TAP device open and +--up script execution, before any --user or --group privilege +downgrade (or --chroot execution.)

+

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.

+

On Windows, --route-delay tries to be more intelligent by waiting +w seconds (default 30 by default) for the TAP-Win32 adapter +to come up before adding routes.

+
+--route-ipv6 args
 

Setup IPv6 routing in the system to send the specified IPv6 network into +OpenVPN's tun.

+

Valid syntax:

+
+route-ipv6 ipv6addr/bits [gateway] [metric]
+
+

The gateway parameter is only used for IPv6 routes across tap devices, +and if missing, the ipv6remote field from --ifconfig-ipv6 or +--route-ipv6-gateway is used.

+
+--route-gateway arg
 

Specify a default gateway for use with --route.

+

If dhcp is specified as the parameter, the gateway address will +be extracted from a DHCP negotiation with the OpenVPN server-side LAN.

+

Valid syntaxes:

+
+route-gateway gateway
+route-gateway dhcp
+
+
+--route-ipv6-gateway gw
 Specify a default gateway gw for use with --route-ipv6.
+--route-metric m
 Specify a default metric m for use with --route.
+--route-noexecDon't add or remove routes automatically. Instead pass routes to +--route-up script using environmental variables.
+--route-nopull

When used with --client or --pull, accept options pushed by +server EXCEPT for routes, block-outside-dns and dhcp options like DNS +servers.

+

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.

+
+--topology mode
 

Configure virtual addressing topology when running in --dev tun +mode. This directive has no meaning in --dev tap mode, which always +uses a subnet topology.

+

If you set this directive on the server, the --server and +--server-bridge directives will automatically push your chosen +topology setting to clients as well. This directive can also be manually +pushed to clients. Like the --dev directive, this directive must +always be compatible between client and server.

+

mode can be one of:

+
+
net30
+
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.
+
p2p
+
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.
+
subnet
+
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 --dev tap 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 --topology 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 ifconfig(8) command which +sets a subnet instead of a remote endpoint IP address.
+
+

Note: Using --topology subnet changes the interpretation of the +arguments of --ifconfig to mean "address netmask", no longer "local +remote".

+
+--tun-mtu n

Take the TUN device MTU to be n and derive the link MTU from it +(default 1500). In most cases, you will probably want to leave +this parameter set to its default value.

+

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.

+

MTU problems often manifest themselves as connections which hang during +periods of active usage.

+

It's best to use the --fragment and/or --mssfix options to deal +with MTU sizing issues.

+
+--tun-mtu-extra n
 Assume that the TUN/TAP device might return as many as n bytes more +than the --tun-mtu 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.
+
+
+

TUN/TAP standalone operations

+

These two standalone operations will require --dev and optionally +--user and/or --group.

+ +++ + + + + + +
+--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'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.

+

One of the advantages of persistent tunnels is that they eliminate the +need for separate --up and --down scripts to run the appropriate +ifconfig(8) and route(8) commands. These commands can be +placed in the the same shell script which starts or terminates an +OpenVPN session.

+

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 +--ipchange option above).

+

One disadvantage of persistent tunnels is that it is harder to +automatically configure their MTU value (see --link-mtu and +--tun-mtu above).

+

On some platforms such as Windows, TAP-Win32 tunnels are persistent by +default.

+
+--rmtun(Standalone) Remove a persistent tunnel.
+
+
+

Virtual Routing and Forwarding

+

Options in this section relates to configuration of virtual routing and +forwarding in combination with the underlying operating system.

+

As of today this is only supported on Linux, a kernel >= 4.9 is +recommended.

+

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.

+

Another option would be to put the tun/tap interface into a VRF. This could +be done by an up-script which uses the ip link set command shown +below.

+
+

VRF setup with iproute2

+

Create VRF vrf_external and map it to routing table 1023

+
+ip link add vrf_external type vrf table 1023
+
+

Move eth0 into vrf_external

+
+ip link set master vrf_external dev eth0
+
+

Any prefixes configured on eth0 will be moved from the :code`main` +routing table into routing table 1023

+
+
+

VRF setup with ifupdown

+

For Debian based Distributions ifupdown2 provides an almost drop-in +replacement for ifupdown including VRFs and other features. +A configuration for an interface eth0 being part of VRF +code:vrf_external could look like this:

+
+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
+
+
+
+

OpenVPN configuration

+

The OpenVPN configuration needs to contain this line:

+
+bind-dev vrf_external
+
+
+
+

Further reading

+

Wikipedia has nice page one VRFs: https://en.wikipedia.org/wiki/Virtual_routing_and_forwarding

+

This talk from the Network Track of FrOSCon 2018 provides an overview about +advanced layer 2 and layer 3 features of Linux

+
+ +
+
+
+
+
+

SCRIPTING INTEGRATION

+

OpenVPN can execute external scripts in various phases of the lifetime of +the OpenVPN process.

+
+

Script Order of Execution

+
    +

  1. --up

    +

    Executed after TCP/UDP socket bind and TUN/TAP open.

    +
    2. +

  2. --tls-verify

    +

    Executed when we have a still untrusted remote peer.

    +
    3. +

  3. --ipchange

    +

    Executed after connection authentication, or remote IP address change.

    +
    4. +

  4. --client-connect

    +

    Executed in --mode server mode immediately after client +authentication.

    +
    5. +

  5. --route-up

    +

    Executed after connection authentication, either immediately after, or +some number of seconds after as defined by the --route-delay option.

    +
    6. +

  6. --route-pre-down

    +

    Executed right before the routes are removed.

    +
    7. +

  7. --client-disconnect

    +

    Executed in --mode server mode on client instance shutdown.

    +
    8. +

  8. --down

    +

    Executed after TCP/UDP and TUN/TAP close.

    +
    9. +

  9. --learn-address

    +

    Executed in --mode server mode whenever an IPv4 address/route or MAC +address is added to OpenVPN's internal routing table.

    +
    10. +

  10. --auth-user-pass-verify

    +

    Executed in --mode server mode on new client connections, when the +client is still untrusted.

    +
    11. +
+
+
+

SCRIPT HOOKS

+ +++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+--auth-user-pass-verify args
 

Require the client to provide a username/password (possibly in addition +to a client certificate) for authentication.

+

Valid syntax:

+
+auth-user-pass-verify cmd method
+
+

OpenVPN will run command cmd to validate the username/password +provided by the client.

+

cmd 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.

+

If method is set to via-env, OpenVPN will call script +with the environmental variables username and password +set to the username/password strings provided by the client. Beware +that this method is insecure on some platforms which make the environment +of a process publicly visible to other unprivileged processes.

+

If method is set to via-file, 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 script, and the file will be +automatically deleted by OpenVPN after the script returns. The location +of the temporary file is controlled by the --tmp-dir option, and +will default to the current directory if unspecified. For security, +consider setting --tmp-dir to a volatile storage medium such as +/dev/shm (if available) to prevent the username/password file +from touching the hard drive.

+

The script should examine the username and password, returning a success +exit code (0) if the client's authentication request is to be +accepted, or a failure code (1) to reject the client.

+

This directive is designed to enable a plugin-style interface for +extending OpenVPN's authentication capabilities.

+

To protect against a client passing a maliciously formed username or +password string, the username string must consist only of these +characters: alphanumeric, underbar ('_'), dash ('-'), +dot ('.'), or at ('@'). 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 ('_').

+

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.

+

For a sample script that performs PAM authentication, see +sample-scripts/auth-pam.pl in the OpenVPN source distribution.

+
+--client-connect cmd
 

Run command cmd on client connection.

+

cmd 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.

+

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 cmd ), to be used by the command to pass dynamically +generated config file directives back to OpenVPN.

+

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.

+

See the --client-config-dir option below for options which can be +legally used in a dynamically generated config file.

+

Note that the return value of script is significant. If script +returns a non-zero error status, it will cause the client to be +disconnected.

+

If a --client-connect wants to defer the generating of the +configuration then the script needs to use the +client_connect_deferred_file and +client_connect_config_file environment variables, and write +status accordingly into these files. See the Environmental Variables +section for more details.

+
+--client-disconnect cmd
 

Like --client-connect but called on client instance shutdown. Will +not be called unless the --client-connect script and plugins (if +defined) were previously called on this instance with successful (0) +status returns.

+

The exception to this rule is if the --client-disconnect 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.

+

The --client-disconnect command is passed the same pathname as the +corresponding --client-connect command as its last argument (after +any arguments specified in cmd).

+
+--down cmd

Run command cmd after TUN/TAP device close (post --user UID +change and/or --chroot ). cmd 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.

+

Called with the same parameters and environmental variables as the +--up option above.

+

Note that if you reduce privileges by using --user and/or +--group, your --down script will also run at reduced privilege.

+
+--down-preCall --down cmd/script before, rather than after, TUN/TAP close.
+--ipchange cmd

Run command cmd when our remote ip-address is initially +authenticated or changes.

+

cmd 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.

+

When cmd is executed two arguments are appended after any arguments +specified in cmd , as follows:

+
+cmd ip address port number
+
+

Don't use --ipchange in --mode server mode. Use a +--client-connect script instead.

+

See the Environmental Variables section below for additional +parameters passed as environmental variables.

+

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 /etc/hosts file with the current +address of the peer. The script will be run every time the remote peer +changes its IP address.

+

Similarly if our IP address changes due to DHCP, we should configure +our IP address change script (see man page for dhcpcd(8)) to +deliver a SIGHUP or SIGUSR1 signal to OpenVPN. OpenVPN will +then re-establish a connection with its most recently authenticated +peer on its new IP address.

+
+--learn-address cmd
 

Run command cmd to validate client virtual addresses or routes.

+

cmd 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.

+

Three arguments will be appended to any arguments in cmd as follows:

+
+
$1 - [operation]
+
"add", "update", or "delete" based on whether +or not the address is being added to, modified, or deleted from +OpenVPN's internal routing table.
+
$2 - [address]
+
The address being learned or unlearned. This can be an IPv4 address +such as "198.162.10.14", an IPv4 subnet such as +"198.162.10.0/24", or an ethernet MAC address (when +--dev tap is being used) such as "00:FF:01:02:03:04".
+
$3 - [common name]
+
The common name on the certificate associated with the client linked +to this address. Only present for "add" or "update" +operations, not "delete".
+
+

On "add" or "update" methods, if the script returns +a failure code (non-zero), OpenVPN will reject the address and will not +modify its internal routing table.

+

Normally, the cmd 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.

+
+--route-up cmd

Run command cmd after routes are added, subject to --route-delay.

+

cmd 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.

+

See the Environmental Variables section below for additional +parameters passed as environmental variables.

+
+--route-pre-down cmd
 

Run command cmd before routes are removed upon disconnection.

+

cmd 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.

+

See the Environmental Variables section below for additional +parameters passed as environmental variables.

+
+--setenv args

Set a custom environmental variable name=value to pass to script.

+

Valid syntaxes:

+
+setenv name value
+setenv FORWARD_COMPATIBLE 1
+setenv opt config_option
+
+

By setting FORWARD_COMPATIBLE to 1, 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.

+

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.

+

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: setenv opt

+

Versions prior to OpenVPN 2.3.3 will always ignore options set with the +setenv opt directive.

+

See also --ignore-unknown-option

+
+--setenv-safe args
 

Set a custom environmental variable OPENVPN_name to value +to pass to scripts.

+

Valid syntaxes:

+
+setenv-safe name value
+
+

This directive is designed to be pushed by the server to clients, and +the prepending of OPENVPN_ to the environmental variable is a +safety precaution to prevent a LD_PRELOAD style attack from a +malicious or compromised server.

+
+--tls-verify cmd
 

Run command cmd to verify the X509 name of a pending TLS connection +that has otherwise passed all other tests of certification (except for +revocation via --crl-verify directive; the revocation test occurs +after the --tls-verify test).

+

cmd should return 0 to allow the TLS handshake to proceed, +or 1 to fail.

+

cmd 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.

+

When cmd is executed two arguments are appended after any arguments +specified in cmd, as follows:

+
+cmd certificate_depth subject
+
+

These arguments are, respectively, the current certificate depth and the +X509 subject distinguished name (dn) of the peer.

+

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 verify-cn in the OpenVPN distribution.

+

See the Environmental Variables section below for additional +parameters passed as environmental variables.

+
+--up cmd

Run command cmd after successful TUN/TAP device open (pre --user +UID change).

+

cmd 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.

+

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.

+

For --dev tun execute as:

+
+cmd tun_dev tun_mtu link_mtu ifconfig_local_ip ifconfig_remote_ip [init | restart]
+
+

For --dev tap execute as:

+
+cmd tap_dev tap_mtu link_mtu ifconfig_local_ip ifconfig_netmask [init | restart]
+
+

See the Environmental Variables section below for additional +parameters passed as environmental variables.

+

Note that if cmd includes arguments, all OpenVPN-generated arguments +will be appended to them to build an argument list with which the +executable will be called.

+

Typically, cmd will run a script to add routes to the tunnel.

+

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 init. If the --up-restart 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 --persist-tun option will enable such preservation). +A restart can be generated by a SIGUSR1 signal, a --ping-restart +timeout, or a connection reset when the TCP protocol is enabled with the +--proto option. If a restart occurs, and --up-restart has been +specified, the up script will be called with restart as the last +parameter.

+
+
NOTE:
+
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).
+
+

The following standalone example shows how the --up script can be +called in both an initialization and restart context. (NOTE: 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).

+
+openvpn --dev tun --port 9999 --verb 4 --ping-restart 10 \
+        --up 'echo up' --down 'echo down' --persist-tun  \
+        --up-restart
+
+

Note that OpenVPN also provides the --ifconfig option to +automatically ifconfig the TUN device, eliminating the need to define an +--up script, unless you also want to configure routes in the +--up script.

+

If --ifconfig is also specified, OpenVPN will pass the ifconfig +local and remote endpoints on the command line to the --up script so +that they can be used to configure routes such as:

+
+route add -net 10.0.0.0 netmask 255.255.255.0 gw $5
+
+
+--up-delay

Delay TUN/TAP open and possible --up script execution until after +TCP/UDP connection establishment with peer.

+

In --proto udp mode, this option normally requires the use of +--ping to allow connection initiation to be sensed in the absence of +tunnel data, since UDP is a "connectionless" protocol.

+

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.

+
+--up-restartEnable the --up and --down scripts to be called for restarts as +well as initial program start. This option is described more fully above +in the --up option documentation.
+
+
+

String Types and Remapping

+

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 ('_').

+
+
Q: Why is string remapping necessary?
+
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.
+
Q: Can string remapping be disabled?
+
Yes, by using the --no-name-remapping option, however this +should be considered an advanced option.
+
+

Here is a brief rundown of OpenVPN's current string types and the +permitted character class for each string:

+
+
X509 Names
+
Alphanumeric, underbar ('_'), dash ('-'), dot ('.'), at +('@'), colon (':'), slash ('/'), and equal ('='). Alphanumeric is +defined as a character which will cause the C library isalnum() function +to return true.
+
Common Names
+
Alphanumeric, underbar ('_'), dash ('-'), dot ('.'), and at ('@').
+
--auth-user-pass username
+
Same as Common Name, with one exception: +starting with OpenVPN 2.0.1, the username is passed to the +OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY plugin in its raw form, +without string remapping.
+
--auth-user-pass password
+
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.
+
--client-config-dir filename as derived from common name or`username
+
Alphanumeric, underbar ('_'), dash ('-'), and dot ('.') except for "." +or ".." as standalone strings. As of v2.0.1-rc6, the at ('@') character +has been added as well for compatibility with the common name character +class.
+
Environmental variable names
+
Alphanumeric or underbar ('_').
+
Environmental variable values
+
Any printable character.
+
+

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 +('_').

+
+
+

Environmental Variables

+

Once set, a variable is persisted indefinitely until it is reset by a +new value or a restart,

+

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.

+
+
bytes_received
+
Total number of bytes received from client during VPN session. Set prior +to execution of the --client-disconnect script.
+
bytes_sent
+
Total number of bytes sent to client during VPN session. Set prior to +execution of the --client-disconnect script.
+
client_connect_config_file
+
The path to the configuration file that should be written to by the +--client-connect 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 --client-connect script.
+
client_connect_deferred_file
+

This file can be optionally written to in order to to communicate a +status code of the --client-connect script or plgin. Only the +first character in the file is relevant. It must be either 1 +to indicate normal script execution, 0 indicates an error (in +the same way that a non zero exit status does) or 2 to indicate +that the script deferred returning the config file.

+

For deferred (background) handling, the script or plugin MUST write +2 to the file to indicate the deferral and then return with +exit code 0 to signal deferred handler started OK.

+

A background process or similar must then take care of writing the +configuration to the file indicated by the +client_connect_config_file environment variable and when +finished, write the a 1 to this file (or 0 in case of +an error).

+

The absence of any character in the file when the script finishes +executing is interpreted the same as 1. This allows scripts +that are not written to support the defer mechanism to be used +unmodified.

+
+
common_name
+
The X509 common name of an authenticated client. Set prior to execution +of --client-connect, --client-disconnect and +--auth-user-pass-verify scripts.
+
config
+
Name of first --config file. Set on program initiation and reset on +SIGHUP.
+
daemon
+
Set to "1" if the --daemon directive is specified, or "0" otherwise. +Set on program initiation and reset on SIGHUP.
+
daemon_log_redirect
+
Set to "1" if the --log or --log-append directives are +specified, or "0" otherwise. Set on program initiation and reset on +SIGHUP.
+
dev
+
The actual name of the TUN/TAP device, including a unit number if it +exists. Set prior to --up or --down script execution.
+
dev_idx
+
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 --up or --down script execution.
+
foreign_option_{n}
+
An option pushed via --push to a client which does not natively +support it, such as --dhcp-option on a non-Windows system, will be +recorded to this environmental variable sequence prior to --up +script execution.
+
ifconfig_broadcast
+
The broadcast address for the virtual ethernet segment which is derived +from the --ifconfig option when --dev tap is used. Set prior to +OpenVPN calling the ifconfig or netsh (windows version +of ifconfig) commands which normally occurs prior to --up script +execution.
+
ifconfig_ipv6_local
+
The local VPN endpoint IPv6 address specified in the +--ifconfig-ipv6 option (first parameter). Set prior to OpenVPN +calling the ifconfig or code:netsh (windows version of +ifconfig) commands which normally occurs prior to --up script +execution.
+
ifconfig_ipv6_netbits
+
The prefix length of the IPv6 network on the VPN interface. Derived +from the /nnn parameter of the IPv6 address in the --ifconfig-ipv6 +option (first parameter). Set prior to OpenVPN calling the +ifconfig or netsh (windows version of ifconfig) +commands which normally occurs prior to --up script execution.
+
ifconfig_ipv6_remote
+
The remote VPN endpoint IPv6 address specified in the +--ifconfig-ipv6 option (second parameter). Set prior to OpenVPN +calling the ifconfig or netsh (windows version of +ifconfig) commands which normally occurs prior to --up script +execution.
+
ifconfig_local
+
The local VPN endpoint IP address specified in the --ifconfig +option (first parameter). Set prior to OpenVPN calling the +ifconfig or netsh (windows version of ifconfig) +commands which normally occurs prior to --up script execution.
+
ifconfig_remote
+
The remote VPN endpoint IP address specified in the --ifconfig +option (second parameter) when --dev tun is used. Set prior to +OpenVPN calling the ifconfig or netsh (windows version +of ifconfig) commands which normally occurs prior to --up script +execution.
+
ifconfig_netmask
+
The subnet mask of the virtual ethernet segment that is specified as +the second parameter to --ifconfig when --dev tap is being +used. Set prior to OpenVPN calling the ifconfig or +netsh (windows version of ifconfig) commands which normally +occurs prior to --up script execution.
+
ifconfig_pool_local_ip
+
The local virtual IP address for the TUN/TAP tunnel taken from an +--ifconfig-push directive if specified, or otherwise from the +ifconfig pool (controlled by the --ifconfig-pool config file +directive). Only set for --dev tun tunnels. This option is set on +the server prior to execution of the --client-connect and +--client-disconnect scripts.
+
ifconfig_pool_netmask
+
The virtual IP netmask for the TUN/TAP tunnel taken from an +--ifconfig-push directive if specified, or otherwise from the +ifconfig pool (controlled by the --ifconfig-pool config file +directive). Only set for --dev tap tunnels. This option is set on +the server prior to execution of the --client-connect and +--client-disconnect scripts.
+
ifconfig_pool_remote_ip
+
The remote virtual IP address for the TUN/TAP tunnel taken from an +--ifconfig-push directive if specified, or otherwise from the +ifconfig pool (controlled by the --ifconfig-pool config file +directive). This option is set on the server prior to execution of the +--client-connect and --client-disconnect scripts.
+
link_mtu
+
The maximum packet size (not including the IP header) of tunnel data in +UDP tunnel transport mode. Set prior to --up or --down script +execution.
+
local
+
The --local parameter. Set on program initiation and reset on +SIGHUP.
+
local_port
+
The local port number or name, specified by --port or --lport. +Set on program initiation and reset on SIGHUP.
+
password
+
The password provided by a connecting client. Set prior to +--auth-user-pass-verify script execution only when the via-env +modifier is specified, and deleted from the environment after the script +returns.
+
proto
+
The --proto parameter. Set on program initiation and reset on +SIGHUP.
+
remote_{n}
+
The --remote parameter. Set on program initiation and reset on +SIGHUP.
+
remote_port_{n}
+
The remote port number, specified by --port or --rport. Set on +program initiation and reset on SIGHUP.
+
route_net_gateway
+
The pre-existing default IP gateway in the system routing table. Set +prior to --up script execution.
+
route_vpn_gateway
+
The default gateway used by --route options, as specified in either +the --route-gateway option or the second parameter to +--ifconfig when --dev tun is specified. Set prior to --up +script execution.
+
route_{parm}_{n}
+

A set of variables which define each route to be added, and are set +prior to --up script execution.

+

parm will be one of network, netmask", +gateway, or metric.

+

n is the OpenVPN route number, starting from 1.

+

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.

+
+
route_ipv6_{parm}_{n}
+

A set of variables which define each IPv6 route to be added, and are +set prior to --up script execution.

+

parm will be one of network or gateway +(netmask is contained as /nnn in the +route_ipv6_network_{n}, unlike IPv4 where it is passed in a +separate environment variable).

+

n is the OpenVPN route number, starting from 1.

+

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.

+
+
peer_cert
+
Temporary file name containing the client certificate upon connection. +Useful in conjunction with --tls-verify.
+
script_context
+
Set to "init" or "restart" prior to up/down script execution. For more +information, see documentation for --up.
+
script_type
+
Prior to execution of any script, this variable is set to the type of +script being run. It can be one of the following: up, +down, ipchange, route-up, tls-verify, +auth-user-pass-verify, client-connect, +client-disconnect or learn-address. Set prior to +execution of any script.
+
signal
+
The reason for exit or restart. Can be one of sigusr1, +sighup, sigterm, sigint, inactive +(controlled by --inactive option), ping-exit (controlled +by --ping-exit option), ping-restart (controlled by +--ping-restart option), connection-reset (triggered on TCP +connection reset), error or unknown (unknown signal). +This variable is set just prior to down script execution.
+
time_ascii
+
Client connection timestamp, formatted as a human-readable time string. +Set prior to execution of the --client-connect script.
+
time_duration
+
The duration (in seconds) of the client session which is now +disconnecting. Set prior to execution of the --client-disconnect +script.
+
time_unix
+
Client connection timestamp, formatted as a unix integer date/time +value. Set prior to execution of the --client-connect script.
+
tls_digest_{n} / tls_digest_sha256_{n}
+
Contains the certificate SHA1 / SHA256 fingerprint, where n is the +verification level. Only set for TLS connections. Set prior to execution +of --tls-verify script.
+
tls_id_{n}
+
A series of certificate fields from the remote peer, where n is the +verification level. Only set for TLS connections. Set prior to execution +of --tls-verify script.
+
tls_serial_{n}
+
The serial number of the certificate from the remote peer, where n +is the verification level. Only set for TLS connections. Set prior to +execution of --tls-verify 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 +contrib/OCSP_check/OCSP_check.sh script for an example.
+
tls_serial_hex_{n}
+
Like tls_serial_{n}, but in hex form (e.g. +12:34:56:78:9A).
+
tun_mtu
+
The MTU of the TUN/TAP device. Set prior to --up or --down +script execution.
+
trusted_ip / trusted_ip6)
+
Actual IP address of connecting client or peer which has been +authenticated. Set prior to execution of --ipchange, +--client-connect and --client-disconnect scripts. If using ipv6 +endpoints (udp6, tcp6), trusted_ip6 will be set instead.
+
trusted_port
+
Actual port number of connecting client or peer which has been +authenticated. Set prior to execution of --ipchange, +--client-connect and --client-disconnect scripts.
+
untrusted_ip / untrusted_ip6
+
Actual IP address of connecting client or peer which has not been +authenticated yet. Sometimes used to nmap the connecting host in a +--tls-verify script to ensure it is firewalled properly. Set prior +to execution of --tls-verify and --auth-user-pass-verify +scripts. If using ipv6 endpoints (udp6, tcp6), untrusted_ip6 +will be set instead.
+
untrusted_port
+
Actual port number of connecting client or peer which has not been +authenticated yet. Set prior to execution of --tls-verify and +--auth-user-pass-verify scripts.
+
username
+
The username provided by a connecting client. Set prior to +--auth-user-pass-verify script execution only when the +via-env modifier is specified.
+
X509_{n}_{subject_field}
+

An X509 subject field from the remote peer certificate, where n is +the verification level. Only set for TLS connections. Set prior to +execution of --tls-verify script. This variable is similar to +tls_id_{n} 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 "_"). 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.

+
+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
+
+
+
+
+
+

Management Interface Options

+

OpenVPN provides a feature rich socket based management interface for both +server and client mode operations.

+ +++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+--management args
 

Enable a management server on a socket-name Unix socket on those +platforms supporting it, or on a designated TCP port.

+

Valid syntaxes:

+
+management socket-name unix          #
+management socket-name unix pw-file  # (recommended)
+management IP port                   # (INSECURE)
+management IP port pw-file           #
+
+

pw-file, 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.

+

For unix sockets, the default behaviour is to create a unix domain +socket that may be connected to by any process. Use the +--management-client-user and --management-client-group +directives to restrict access.

+

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 tunnel. Tunnel mode will cause the management interface to +listen for a TCP connection on the local VPN address of the TUN/TAP +interface.

+

*BEWARE* of enabling the management interface over TCP. In these cases +you should ALWAYS make use of pw-file to password protect the +management interface. Any user who can connect to this TCP IP:port +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.

+

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 help +for a list of commands.

+

For detailed documentation on the management interface, see the +management-notes.txt file in the management folder of the OpenVPN +source distribution.

+
+--management-client
 

Management interface will connect as a TCP/unix domain client to +IP:port specified by --management rather than listen as a TCP +server or on a unix domain socket.

+

If the client connection fails to connect or is disconnected, a SIGTERM +signal will be generated causing OpenVPN to quit.

+
+--management-client-auth
 Gives management interface client the responsibility to authenticate +clients after their client certificate has been verified. See +management-notes.txt in OpenVPN distribution for detailed notes.
+--management-client-group g
 When the management interface is listening on a unix domain socket, only +allow connections from group g.
+--management-client-pf
 Management interface clients must specify a packet filter file for each +connecting client. See management-notes.txt in OpenVPN +distribution for detailed notes.
+--management-client-user u
 When the management interface is listening on a unix domain socket, only +allow connections from user u.
+--management-external-cert certificate-hint
 Allows usage for external certificate instead of --cert option +(client-only). certificate-hint is an arbitrary string which is +passed to a management interface client as an argument of +NEED-CERTIFICATE notification. Requires --management-external-key.
+--management-external-key args
 

Allows usage for external private key file instead of --key option +(client-only).

+

Valid syntaxes:

+
+management-external-key
+management-external-key nopadding
+management-external-key pkcs1
+management-external-key nopadding pkcs1
+
+

The optional parameters nopadding and pkcs1 signal +support for different padding algorithms. See +doc/mangement-notes.txt for a complete description of this +feature.

+
+--management-forget-disconnect
 

Make OpenVPN forget passwords when management session disconnects.

+

This directive does not affect the --http-proxy username/password. +It is always cached.

+
+--management-hold
 Start OpenVPN in a hibernating state, until a client of the management +interface explicitly starts it with the hold release command.
+--management-log-cache n
 Cache the most recent n lines of log file history for usage by the +management channel.
+--management-query-passwords
 Query management channel for private key password and +--auth-user-pass username/password. Only query the management +channel for inputs which ordinarily would have been queried from the +console.
+--management-query-proxy
 Query management channel for proxy server information for a specific +--remote (client-only).
+--management-query-remote
 Allow management interface to override --remote directives +(client-only).
+--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 --management-client this option is not needed since a disconnect +will always generate a SIGTERM.
+--management-up-down
 Report tunnel up/down events to management interface.
+
+
+

Plug-in Interface Options

+

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.

+ +++ + + + +
+--plugin args

Loads an OpenVPN plug-in module.

+

Valid syntax:

+
+plugin module-name
+plugin module-name "arguments"
+
+

The module-name 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.

+

The module-name 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.

+
+--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
+
+

DEFAULT_DIR is replaced by the default plug-in directory, which is +configured at the build time of OpenVPN. CWD is the current directory +where OpenVPN was started or the directory OpenVPN have switched into +via the --cd option before the --plugin option.

+

For more information and examples on how to build OpenVPN plug-in +modules, see the README file in the plugin folder of the OpenVPN +source distribution.

+

If you are using an RPM install of OpenVPN, see +/usr/share/openvpn/plugin. The documentation is in doc and +the actual plugin modules are in lib.

+

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 (0) in order for the +connection to be authenticated.

+
+
+
+

Windows-Specific Options

+ +++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+--allow-nonadmin TAP-adapter
 (Standalone) Set TAP-adapter to allow access from non-administrative +accounts. If TAP-adapter 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.
+--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.

+

This option is considered unknown on non-Windows platforms and +unsupported on Windows XP, resulting in fatal error. You may want to use +--setenv opt or --ignore-unknown-option (not suitable for +Windows XP) to ignore said error. Note that pushing unknown options from +server does not trigger fatal errors.

+
+--cryptoapicert select-string
 

(Windows/OpenSSL Only) Load the certificate and private key from the +Windows Certificate System Store.

+

Use this option instead of --cert and --key.

+

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.

+

To select a certificate, based on a substring search in the +certificate's subject:

+
+cryptoapicert "SUBJ:Peter Runestig"
+
+

To select a certificate, based on certificate's thumbprint:

+
+cryptoapicert "THUMB:f6 49 24 41 01 b4 ..."
+
+

The thumbprint hex string can easily be copy-and-pasted from the Windows +Certificate Store GUI.

+
+--dhcp-releaseAsk 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.
+--dhcp-renewAsk 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.
+--ip-win32 method
 

When using --ifconfig on Windows, set the TAP-Win32 adapter IP +address and netmask using method. Don't use this option unless you +are also using --ifconfig.

+
+
manual
+
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.
+
dynamic [offset] [lease-time]
+

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:

+
    +
  1. The TCP/IP properties for the TAP-Win32 adapter must be set +to "Obtain an IP address automatically", and
    2. +
  2. OpenVPN needs to claim an IP address in the subnet for use +as the virtual DHCP server address.
    3. +
+

By default in --dev tap mode, OpenVPN will take the normally +unused first address in the subnet. For example, if your subnet is +192.168.4.0 netmask 255.255.255.0, then OpenVPN will take +the IP address 192.168.4.0 to use as the virtual DHCP +server address. In --dev tun mode, OpenVPN will cause the DHCP +server to masquerade as if it were coming from the remote endpoint.

+

The optional offset parameter is an integer which is > -256 +and < 256 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.

+

The Windows ipconfig /all 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.

+

The lease-time 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.

+
+
netsh
+
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.
+
ipapi
+
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."
+
adaptive (Default)
+

Try dynamic method initially and fail over to netsh +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 netsh 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 adaptive mode to use +netsh immediately, rather than trying dynamic first.

+

To "unstick" the adaptive mode from using netsh, +run OpenVPN at least once using the dynamic mode to restore +the TAP-Win32 adapter TCP/IP properties to a DHCP configuration.

+
+
+
+--pause-exitPut 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.
+--register-dnsRun ipconfig /flushdns and ipconfig /registerdns on +connection initiation. This is known to kick Windows into recognizing +pushed DNS servers.
+--route-method m
 

Which method m to use for adding routes on Windows?

+
+
adaptive (default)
+
Try IP helper API first. If that fails, fall back to the route.exe +shell command.
+
ipapi
+
Use IP helper API.
+
exe
+
Call the route.exe shell command.
+
+
+--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.

+

Valid syntax:

+
+service exit-event [0|1]
+
+

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.

+

exit-event 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.

+

The second parameter indicates the initial state of exit-event and +normally defaults to 0.

+

Multiple OpenVPN processes can be simultaneously executed with the same +exit-event parameter. In any case, the controlling process can +signal exit-event, causing all such OpenVPN processes to exit.

+

When executing an OpenVPN process using the --service directive, +OpenVPN will probably not have a console window to output status/error +messages, therefore it is useful to use --log or --log-append to +write these messages to a file.

+
+--show-adapters
 (Standalone) Show available TAP-Win32 adapters which can be selected +using the --dev-node option. On non-Windows systems, the +ifconfig(8) command provides similar functionality.
+--show-net(Standalone) Show OpenVPN's view of the system routing table and network +adapter list.
+--show-net-upOutput 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.
+--show-valid-subnets
 

(Standalone) Show valid subnets for --dev tun 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.

+

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).

+
+--tap-sleep n

Cause OpenVPN to sleep for n seconds immediately after the TAP-Win32 +adapter state is set to "connected".

+

This option is intended to be used to troubleshoot problems with the +--ifconfig and --ip-win32 options, and is used to give the +TAP-Win32 adapter time to come up before Windows IP Helper API +operations are applied to it.

+
+--win-sys path

Set the Windows system directory pathname to use when looking for system +executables such as route.exe and netsh.exe. By default, if this +directive is not specified, OpenVPN will use the SystemRoot environment +variable.

+

This option has changed behaviour since OpenVPN 2.3. Earlier you had to +define --win-sys env to use the SystemRoot environment variable, +otherwise it defaulted to C:\\WINDOWS. It is not needed to use +the env keyword any more, and it will just be ignored. A warning is +logged when this is found in the configuration file.

+
+--windows-driver drv
 Specifies which tun driver to use. Values are tap-windows6 +(default) and wintun. This is a Windows-only option. +wintun" requires --dev tun and the OpenVPN process to run +elevated, or be invoked using the Interactive Service.
+
+
+

Standalone Debug Options

+ +++ + + + + +
+--show-gateway args
 

(Standalone) Show current IPv4 and IPv6 default gateway and interface +towards the gateway (if the protocol in question is enabled).

+

Valid syntax:

+
+--show-gateway
+--show-gateway IPv6-target
+
+

If an IPv6 target address is passed as argument, the IPv6 route for this +host is reported.

+
+
+
+

Advanced Expert Options

+

These are options only required when special tweaking is needed, often +used when debugging or testing out special usage scenarios.

+ +++ + + + + + + + + + + + + + + + + + + + + + + + + + + +
+--hash-size args
 

Set the size of the real address hash table to r and the virtual +address table to v.

+

Valid syntax:

+
+hash-size r v
+
+

By default, both tables are sized at 256 buckets.

+
+--bcast-buffers n
 Allocate n buffers for broadcast datagrams (default 256).
+--persist-local-ip
 Preserve initially resolved local IP address and port number across +SIGUSR1 or --ping-restart restarts.
+--persist-remote-ip
 Preserve most recently authenticated remote IP address and port number +across SIGUSR1 or --ping-restart restarts.
+--prng args

(Advanced) Change the PRNG (Pseudo-random number generator) parameters

+

Valid syntaxes:

+
+prng alg
+prng alg nsl
+
+

Changes the PRNG to use digest algorithm alg (default sha1), +and set nsl (default 16) to the size in bytes of the nonce +secret length (between 16 and 64).

+

Set alg to none to disable the PRNG and use the OpenSSL +RAND_bytes function instead for all of OpenVPN's pseudo-random number +needs.

+
+--rcvbuf sizeSet the TCP/UDP socket receive buffer size. Defaults to operating system +default.
+--shaper n

Limit bandwidth of outgoing tunnel data to n bytes per second on the +TCP/UDP port. Note that this will only work if mode is set to +p2p. If you want to limit the bandwidth in both directions, use +this option on both peers.

+

OpenVPN uses the following algorithm to implement traffic shaping: Given +a shaper rate of n bytes per second, after a datagram write of b +bytes is queued on the TCP/UDP port, wait a minimum of (b / n) +seconds before queuing the next write.

+

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.

+

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.

+

OpenVPN allows n to be between 100 bytes/sec and 100 Mbytes/sec.

+
+--sndbuf sizeSet the TCP/UDP socket send buffer size. Defaults to operating system +default.
+--tcp-queue-limit n
 

Maximum number of output packets queued before TCP (default 64).

+

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.

+
+--txqueuelen n(Linux only) Set the TX queue length on the TUN/TAP interface. +Currently defaults to operating system default.
+
+
+
+

UNSUPPORTED OPTIONS

+

Options listed in this section have been removed from OpenVPN and are no +longer supported

+ +++ + + + + + + + + + + + + + + + +
+--client-cert-not-required
 Removed in OpenVPN 2.5. This should be replaxed with +--verify-client-cert none.
+--ifconfig-pool-linear
 Removed in OpenVPN 2.5. This should be replaced with --topology p2p.
+--key-methodRemoved in OpenVPN 2.5. This option should not be used, as using the old +key-method weakens the VPN tunnel security. The old key-method +was also only needed when the remote side was older than OpenVPN 2.0.
+--no-ivRemoved 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.
+--no-replayRemoved in OpenVPN 2.5. This option should not be used as it weakens the +VPN tunnel security.
+--ns-cert-typeRemoved in OpenVPN 2.5. The nsCertType field is no longer supported +in recent SSL/TLS libraries. If your certificates does not include key +usage and extended key usage fields, they must be upgraded and the +--remote-cert-tls option should be used instead.
+
+
+

CONNECTION PROFILES

+

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 --remote options. For these +use cases, connection profiles are the solution.

+

By enacpulating the --remote option and related options within +<connection> and </connection>, these options are handled as a +group.

+

An OpenVPN client will try each connection profile sequentially until it +achieves a successful connection.

+

--remote-random can be used to initially "scramble" the connection +list.

+

Here is an example of connection profile usage:

+
+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
+
+

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.

+

The following OpenVPN options may be used inside of a <connection> +block:

+

bind, connect-retry, connect-retry-max, connect-timeout, +explicit-exit-notify, float, fragment, http-proxy, +http-proxy-option, key-direction, link-mtu, local, +lport, mssfix, mtu-disc, nobind, port, proto, +remote, rport, socks-proxy, tls-auth, tls-crypt, +tun-mtu and, tun-mtu-extra.

+

A defaulting mechanism exists for specifying options to apply to all +<connection> profiles. If any of the above options (with the +exception of remote ) appear outside of a <connection> block, +but in a configuration file which has one or more <connection> +blocks, the option setting will be used as a default for +<connection> blocks which follow it in the configuration file.

+

For example, suppose the nobind option were placed in the sample +configuration file above, near the top of the file, before the first +<connection> block. The effect would be as if nobind were +declared in all <connection> blocks below it.

+
+
+

INLINE FILE SUPPORT

+

OpenVPN allows including files in the main configuration for the --ca, +--cert, --dh, --extra-certs, --key, --pkcs12, +--secret, --crl-verify, --http-proxy-user-pass, --tls-auth, +--auth-gen-token-secret, --tls-crypt and --tls-crypt-v2 +options.

+

Each inline file started by the line <option> and ended by the line +</option>

+

Here is an example of an inline file usage

+
+<cert>
+-----BEGIN CERTIFICATE-----
+[...]
+-----END CERTIFICATE-----
+</cert>
+
+

When using the inline file feature with --pkcs12 the inline file has +to be base64 encoded. Encoding of a .p12 file into base64 can be done +for example with OpenSSL by running openssl base64 -in input.p12

+
+
+

SIGNALS

+
+
SIGHUP
+
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.
+
SIGUSR1
+

Like SIGHUP`, 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 --persist-tun, --persist-key, +--persist-local-ip and --persist-remote-ip options respectively +(see above).

+

This signal may also be internally generated by a timeout condition, +governed by the --ping-restart option.

+

This signal, when combined with --persist-remote-ip, 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 --ipchange for more information.

+
+
SIGUSR2
+
Causes OpenVPN to display its current statistics (to the syslog file if +--daemon is used, or stdout otherwise).
+
SIGINT, SIGTERM
+
Causes OpenVPN to exit gracefully.
+
+
+
+

EXAMPLES

+

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.

+
+

Firewall Setup:

+

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 --ping 15 to each of the openvpn 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).

+

Please see your operating system guides for how to configure the firewall +on your systems.

+
+
+

VPN Address Setup:

+

For purposes of our example, our two machines will be called +bob.example.com and alice.example.com. If you are constructing a +VPN over the internet, then replace bob.example.com and +alice.example.com with the internet hostname or IP address that each +machine will use to contact the other over the internet.

+

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.

+

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 alice.example.com via +ssh without using the VPN (since ssh has its own built-in security) +you would use the command ssh alice.example.com. However in the same +scenario, you could also use the command telnet 10.4.0.2 to create a +telnet session with alice.example.com over the VPN, that would use the +VPN to secure the session rather than ssh.

+

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.

+
+
+

Example 1: A simple tunnel without security

+

On bob:

+
+openvpn --remote alice.example.com --dev tun1 \
+         --ifconfig 10.4.0.1 10.4.0.2 --verb 9
+
+

On alice:

+
+openvpn --remote bob.example.com --dev tun1 \
+         --ifconfig 10.4.0.2 10.4.0.1 --verb 9
+
+

Now verify the tunnel is working by pinging across the tunnel.

+

On bob:

+
+ping 10.4.0.2
+
+

On alice:

+
+ping 10.4.0.1
+
+

The --verb 9 option will produce verbose output, similar to the +tcpdump(8) program. Omit the --verb 9 option to have OpenVPN run +quietly.

+
+
+

Example 2: A tunnel with static-key security (i.e. using a pre-shared secret)

+

First build a static key on bob.

+
+openvpn --genkey --secret key
+
+

This command will build a key file called key (in ascii format). Now +copy key to alice.example.com over a secure medium such as by using +the scp(1) program.

+

On bob:

+
+openvpn --remote alice.example.com --dev tun1  \
+         --ifconfig 10.4.0.1 10.4.0.2 --verb 5 \
+         --secret key
+
+

On alice:

+
+openvpn --remote bob.example.com --dev tun1   \
+        --ifconfig 10.4.0.2 10.4.0.1 --verb 5 \
+        --secret key
+
+

Now verify the tunnel is working by pinging across the tunnel.

+

On bob:

+
+ping 10.4.0.2
+
+

On alice:

+
+ping 10.4.0.1
+
+
+
+

Example 3: A tunnel with full TLS-based security

+

For this test, we will designate bob as the TLS client and alice +as the TLS server.

+
+
Note:
+
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.*
+
+

First, build a separate certificate/key pair for both bob and alice (see +above where --cert is discussed for more info). Then construct +Diffie Hellman parameters (see above where --dh is discussed for +more info). You can also use the included test files client.crt, +client.key, server.crt, server.key and +ca.crt. The .crt files are certificates/public-keys, the +.key files are private keys, and ca.crt is a certification +authority who has signed both client.crt and server.crt. +For Diffie Hellman parameters you can use the included file +dh2048.pem.

+
+
WARNING:
+
All client, server, and certificate authority certificates +and keys included in the OpenVPN distribution are totally +insecure and should be used for testing only.
+
+

On bob:

+
+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
+
+

On alice:

+
+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
+
+

Now verify the tunnel is working by pinging across the tunnel.

+

On bob:

+
+ping 10.4.0.2
+
+

On alice:

+
+ping 10.4.0.1
+
+

Notice the --reneg-sec 60 option we used above. That tells OpenVPN +to renegotiate the data channel keys every minute. Since we used +--verb 5 above, you will see status information on each new key +negotiation.

+

For production operations, a key renegotiation interval of 60 seconds is +probably too frequent. Omit the --reneg-sec 60 option to use +OpenVPN's default key renegotiation interval of one hour.

+
+
+

Routing:

+

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 10.0.0.0/24 and +alice's is 10.0.1.0/24.

+

First, ensure that IP forwarding is enabled on both peers. On Linux, +enable routing:

+
+echo 1 > /proc/sys/net/ipv4/ip_forward
+
+

This setting is not persistent. Please see your operating systems +documentation how to properly configure IP forwarding, which is also +persistent through system boots.

+

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.

+

On bob:

+
+route add -net 10.0.1.0 netmask 255.255.255.0 gw 10.4.0.2
+
+

On alice:

+
+route add -net 10.0.0.0 netmask 255.255.255.0 gw 10.4.0.1
+
+

Now any machine on the 10.0.0.0/24 subnet can access any machine on the +10.0.1.0/24 subnet over the secure tunnel (or vice versa).

+

In a production environment, you could put the route command(s) in a +script and execute with the --up option.

+
+
+ +
+

HOWTO

+

For a more comprehensive guide to setting up OpenVPN in a production +setting, see the OpenVPN HOWTO at +https://openvpn.net/community-resources/how-to/

+
+
+

PROTOCOL

+

For a description of OpenVPN's underlying protocol, see +https://openvpn.net/community-resources/openvpn-protocol/

+
+
+

WEB

+

OpenVPN's web site is at https://openvpn.net/

+

Go here to download the latest version of OpenVPN, subscribe to the +mailing lists, read the mailing list archives, or browse the SVN +repository.

+
+
+

BUGS

+

Report all bugs to the OpenVPN team info@openvpn.net

+
+
+

SEE ALSO

+

dhcpcd(8), +ifconfig(8), +openssl(1), +route(8), +scp(1) +ssh(1)

+
+
+

NOTES

+

This product includes software developed by the OpenSSL Project +(https://www.openssl.org/)

+

For more information on the TLS protocol, see +http://www.ietf.org/rfc/rfc2246.txt

+

For more information on the LZO real-time compression library see +https://www.oberhumer.com/opensource/lzo/

+
+ +
+

AUTHORS

+

James Yonan james@openvpn.net

+
+
+ + 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.) -- cgit v1.2.3