diff options
Diffstat (limited to 'doc')
37 files changed, 21168 insertions, 7172 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am index c091ce0..1e4fcde 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -5,27 +5,88 @@ # packet encryption, packet authentication, and # packet compression. # -# Copyright (C) 2002-2018 OpenVPN Inc <sales@openvpn.net> +# Copyright (C) 2002-2021 OpenVPN Inc <sales@openvpn.net> # Copyright (C) 2006-2012 Alon Bar-Lev <alon.barlev@gmail.com> # -MAINTAINERCLEANFILES = \ - $(srcdir)/Makefile.in +SUBDIRS = doxygen -CLEANFILES = openvpn.8.html +# +# List of man and HTML pages we build when rst2man/rst2html is available +# +# NOTE: Remember to add source .rst files to $(dist_noinst_DATA) below +# This could be automated with GNU Make, but we need BSD Make support +# +build_man_pages = openvpn.8 openvpn-examples.5 +build_html_pages = openvpn.8.html openvpn-examples.5.html dist_doc_DATA = \ - management-notes.txt + management-notes.txt gui-notes.txt dist_noinst_DATA = \ - README.plugins interactive-service-notes.rst + README.plugins interactive-service-notes.rst \ + openvpn.8.rst \ + openvpn-examples.5.rst \ + man-sections/advanced-options.rst \ + man-sections/client-options.rst \ + man-sections/connection-profiles.rst \ + 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 + + +###### GENERIC RULES ########## + +SUFFIXES = .8.rst .8 .8.html .5.rst .5 .5.html + +MAINTAINERCLEANFILES = \ + $(srcdir)/Makefile.in + +.8.rst.8 .5.rst.5 : +if HAVE_PYDOCUTILS + $(RST2MAN) $< > $@ +else + @echo "Missing python-docutils - skipping man page generation ($@)" +endif + +.8.rst.8.html .5.rst.5.html : +if HAVE_PYDOCUTILS + $(RST2HTML) $< > $@ +else + @echo "Missing python-docutils - skipping html page generation ($@)" +endif + + +if HAVE_PYDOCUTILS +dist_noinst_DATA += $(build_man_pages) +dist_html_DATA = $(build_html_pages) + +# Failsafe - do not delete these files unless we can recreate them +CLEANFILES = $(build_man_pages) $(build_html_pages) + +endif if WIN32 -dist_noinst_DATA += openvpn.8 -nodist_html_DATA = openvpn.8.html -openvpn.8.html: $(srcdir)/openvpn.8 - $(MAN2HTML) < $(srcdir)/openvpn.8 > openvpn.8.html else -dist_man_MANS = openvpn.8 +dist_man_MANS = $(build_man_pages) endif +dist-hook : $(build_man_pages) $(build_html_pages) diff --git a/doc/Makefile.in b/doc/Makefile.in index 6c86ac8..ef41a37 100644 --- a/doc/Makefile.in +++ b/doc/Makefile.in @@ -1,7 +1,7 @@ -# Makefile.in generated by automake 1.16.1 from Makefile.am. +# Makefile.in generated by automake 1.16.2 from Makefile.am. # @configure_input@ -# Copyright (C) 1994-2018 Free Software Foundation, Inc. +# Copyright (C) 1994-2020 Free Software Foundation, Inc. # This Makefile.in is free software; the Free Software Foundation # gives unlimited permission to copy and/or distribute it, @@ -21,7 +21,7 @@ # packet encryption, packet authentication, and # packet compression. # -# Copyright (C) 2002-2018 OpenVPN Inc <sales@openvpn.net> +# Copyright (C) 2002-2021 OpenVPN Inc <sales@openvpn.net> # Copyright (C) 2006-2012 Alon Bar-Lev <alon.barlev@gmail.com> # @@ -99,7 +99,7 @@ PRE_UNINSTALL = : POST_UNINSTALL = : build_triplet = @build@ host_triplet = @host@ -@WIN32_TRUE@am__append_1 = openvpn.8 +@HAVE_PYDOCUTILS_TRUE@am__append_1 = $(build_man_pages) subdir = doc ACLOCAL_M4 = $(top_srcdir)/aclocal.m4 am__aclocal_m4_deps = $(top_srcdir)/m4/ax_emptyarray.m4 \ @@ -112,7 +112,8 @@ am__aclocal_m4_deps = $(top_srcdir)/m4/ax_emptyarray.m4 \ am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \ $(ACLOCAL_M4) DIST_COMMON = $(srcdir)/Makefile.am $(dist_doc_DATA) \ - $(am__dist_noinst_DATA_DIST) $(am__DIST_COMMON) + $(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 @@ -132,6 +133,14 @@ 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;; \ @@ -164,17 +173,89 @@ am__uninstall_files_from_dir = { \ || { echo " ( cd '$$dir' && rm -f" $$files ")"; \ $(am__cd) "$$dir" && rm -f $$files; }; \ } +man5dir = $(mandir)/man5 +am__installdirs = "$(DESTDIR)$(man5dir)" "$(DESTDIR)$(man8dir)" \ + "$(DESTDIR)$(docdir)" "$(DESTDIR)$(htmldir)" man8dir = $(mandir)/man8 -am__installdirs = "$(DESTDIR)$(man8dir)" "$(DESTDIR)$(docdir)" \ - "$(DESTDIR)$(htmldir)" NROFF = nroff MANS = $(dist_man_MANS) +am__dist_html_DATA_DIST = openvpn.8.html openvpn-examples.5.html am__dist_noinst_DATA_DIST = README.plugins \ - interactive-service-notes.rst openvpn.8 -DATA = $(dist_doc_DATA) $(dist_noinst_DATA) $(nodist_html_DATA) + interactive-service-notes.rst openvpn.8.rst \ + openvpn-examples.5.rst man-sections/advanced-options.rst \ + man-sections/client-options.rst \ + man-sections/connection-profiles.rst \ + 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 openvpn-examples.5 +DATA = $(dist_doc_DATA) $(dist_html_DATA) $(dist_noinst_DATA) +RECURSIVE_CLEAN_TARGETS = mostlyclean-recursive clean-recursive \ + distclean-recursive maintainer-clean-recursive +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@ @@ -187,7 +268,8 @@ AWK = @AWK@ CC = @CC@ CCDEPMODE = @CCDEPMODE@ CFLAGS = @CFLAGS@ -CMAKE = @CMAKE@ +CMOCKA_CFLAGS = @CMOCKA_CFLAGS@ +CMOCKA_LIBS = @CMOCKA_LIBS@ CPP = @CPP@ CPPFLAGS = @CPPFLAGS@ CYGPATH_W = @CYGPATH_W@ @@ -201,6 +283,7 @@ ECHO_C = @ECHO_C@ ECHO_N = @ECHO_N@ ECHO_T = @ECHO_T@ EGREP = @EGREP@ +ENABLE_UNITTESTS = @ENABLE_UNITTESTS@ EXEEXT = @EXEEXT@ FGREP = @FGREP@ GIT = @GIT@ @@ -228,7 +311,6 @@ LZ4_LIBS = @LZ4_LIBS@ LZO_CFLAGS = @LZO_CFLAGS@ LZO_LIBS = @LZO_LIBS@ MAKEINFO = @MAKEINFO@ -MAN2HTML = @MAN2HTML@ MANIFEST_TOOL = @MANIFEST_TOOL@ MBEDTLS_CFLAGS = @MBEDTLS_CFLAGS@ MBEDTLS_LIBS = @MBEDTLS_LIBS@ @@ -279,6 +361,8 @@ 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@ @@ -342,6 +426,7 @@ plugindir = @plugindir@ prefix = @prefix@ program_transform_name = @program_transform_name@ psdir = @psdir@ +runstatedir = @runstatedir@ sampledir = @sampledir@ sbindir = @sbindir@ sharedstatedir = @sharedstatedir@ @@ -353,20 +438,54 @@ tmpfilesdir = @tmpfilesdir@ top_build_prefix = @top_build_prefix@ top_builddir = @top_builddir@ top_srcdir = @top_srcdir@ -MAINTAINERCLEANFILES = \ - $(srcdir)/Makefile.in +SUBDIRS = doxygen -CLEANFILES = openvpn.8.html +# +# List of man and HTML pages we build when rst2man/rst2html is available +# +# NOTE: Remember to add source .rst files to $(dist_noinst_DATA) below +# This could be automated with GNU Make, but we need BSD Make support +# +build_man_pages = openvpn.8 openvpn-examples.5 +build_html_pages = openvpn.8.html openvpn-examples.5.html dist_doc_DATA = \ - management-notes.txt + management-notes.txt gui-notes.txt dist_noinst_DATA = README.plugins interactive-service-notes.rst \ - $(am__append_1) -@WIN32_TRUE@nodist_html_DATA = openvpn.8.html -@WIN32_FALSE@dist_man_MANS = openvpn.8 -all: all-am + openvpn.8.rst openvpn-examples.5.rst \ + man-sections/advanced-options.rst \ + man-sections/client-options.rst \ + man-sections/connection-profiles.rst \ + man-sections/encryption-options.rst man-sections/examples.rst \ + 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) + +###### GENERIC RULES ########## +SUFFIXES = .8.rst .8 .8.html .5.rst .5 .5.html +MAINTAINERCLEANFILES = \ + $(srcdir)/Makefile.in + +@HAVE_PYDOCUTILS_TRUE@dist_html_DATA = $(build_html_pages) + +# Failsafe - do not delete these files unless we can recreate them +@HAVE_PYDOCUTILS_TRUE@CLEANFILES = $(build_man_pages) $(build_html_pages) +@WIN32_FALSE@dist_man_MANS = $(build_man_pages) +all: all-recursive .SUFFIXES: +.SUFFIXES: .8.rst .8 .8.html .5.rst .5 .5.html $(srcdir)/Makefile.in: $(srcdir)/Makefile.am $(am__configure_deps) @for dep in $?; do \ case '$(am__configure_deps)' in \ @@ -402,6 +521,49 @@ mostlyclean-libtool: clean-libtool: -rm -rf .libs _libs +install-man5: $(dist_man_MANS) + @$(NORMAL_INSTALL) + @list1=''; \ + list2='$(dist_man_MANS)'; \ + test -n "$(man5dir)" \ + && test -n "`echo $$list1$$list2`" \ + || exit 0; \ + echo " $(MKDIR_P) '$(DESTDIR)$(man5dir)'"; \ + $(MKDIR_P) "$(DESTDIR)$(man5dir)" || exit 1; \ + { for i in $$list1; do echo "$$i"; done; \ + if test -n "$$list2"; then \ + for i in $$list2; do echo "$$i"; done \ + | sed -n '/\.5[a-z]*$$/p'; \ + fi; \ + } | while read p; do \ + if test -f $$p; then d=; else d="$(srcdir)/"; fi; \ + echo "$$d$$p"; echo "$$p"; \ + done | \ + sed -e 'n;s,.*/,,;p;h;s,.*\.,,;s,^[^5][0-9a-z]*$$,5,;x' \ + -e 's,\.[0-9a-z]*$$,,;$(transform);G;s,\n,.,' | \ + sed 'N;N;s,\n, ,g' | { \ + list=; while read file base inst; do \ + if test "$$base" = "$$inst"; then list="$$list $$file"; else \ + echo " $(INSTALL_DATA) '$$file' '$(DESTDIR)$(man5dir)/$$inst'"; \ + $(INSTALL_DATA) "$$file" "$(DESTDIR)$(man5dir)/$$inst" || exit $$?; \ + fi; \ + done; \ + for i in $$list; do echo "$$i"; done | $(am__base_list) | \ + while read files; do \ + test -z "$$files" || { \ + echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(man5dir)'"; \ + $(INSTALL_DATA) $$files "$(DESTDIR)$(man5dir)" || exit $$?; }; \ + done; } + +uninstall-man5: + @$(NORMAL_UNINSTALL) + @list=''; test -n "$(man5dir)" || exit 0; \ + files=`{ for i in $$list; do echo "$$i"; done; \ + l2='$(dist_man_MANS)'; for i in $$l2; do echo "$$i"; done | \ + sed -n '/\.5[a-z]*$$/p'; \ + } | sed -e 's,.*/,,;h;s,.*\.,,;s,^[^5][0-9a-z]*$$,5,;x' \ + -e 's,\.[0-9a-z]*$$,,;$(transform);G;s,\n,.,'`; \ + dir='$(DESTDIR)$(man5dir)'; $(am__uninstall_files_from_dir) install-man8: $(dist_man_MANS) @$(NORMAL_INSTALL) @list1=''; \ @@ -466,9 +628,9 @@ uninstall-dist_docDATA: @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-nodist_htmlDATA: $(nodist_html_DATA) +install-dist_htmlDATA: $(dist_html_DATA) @$(NORMAL_INSTALL) - @list='$(nodist_html_DATA)'; test -n "$(htmldir)" || list=; \ + @list='$(dist_html_DATA)'; test -n "$(htmldir)" || list=; \ if test -n "$$list"; then \ echo " $(MKDIR_P) '$(DESTDIR)$(htmldir)'"; \ $(MKDIR_P) "$(DESTDIR)$(htmldir)" || exit 1; \ @@ -482,17 +644,110 @@ install-nodist_htmlDATA: $(nodist_html_DATA) $(INSTALL_DATA) $$files "$(DESTDIR)$(htmldir)" || exit $$?; \ done -uninstall-nodist_htmlDATA: +uninstall-dist_htmlDATA: @$(NORMAL_UNINSTALL) - @list='$(nodist_html_DATA)'; test -n "$(htmldir)" || list=; \ + @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) -tags TAGS: -ctags CTAGS: - -cscope cscopelist: +# 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 @@ -527,22 +782,51 @@ distdir-am: $(DISTFILES) || 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-am +check: check-recursive all-am: Makefile $(MANS) $(DATA) -installdirs: - for dir in "$(DESTDIR)$(man8dir)" "$(DESTDIR)$(docdir)" "$(DESTDIR)$(htmldir)"; do \ +installdirs: installdirs-recursive +installdirs-am: + for dir in "$(DESTDIR)$(man5dir)" "$(DESTDIR)$(man8dir)" "$(DESTDIR)$(docdir)" "$(DESTDIR)$(htmldir)"; do \ test -z "$$dir" || $(MKDIR_P) "$$dir"; \ done -install: install-am -install-exec: install-exec-am -install-data: install-data-am -uninstall: uninstall-am +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-am +installcheck: installcheck-recursive install-strip: if test -z '$(STRIP)'; then \ $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ @@ -566,96 +850,107 @@ 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: clean-recursive clean-am: clean-generic clean-libtool mostlyclean-am -distclean: distclean-am +distclean: distclean-recursive -rm -f Makefile -distclean-am: clean-am distclean-generic +distclean-am: clean-am distclean-generic distclean-tags -dvi: dvi-am +dvi: dvi-recursive dvi-am: -html: html-am +html: html-recursive html-am: -info: info-am +info: info-recursive info-am: -install-data-am: install-dist_docDATA install-man \ - install-nodist_htmlDATA +install-data-am: install-dist_docDATA install-dist_htmlDATA \ + install-man -install-dvi: install-dvi-am +install-dvi: install-dvi-recursive install-dvi-am: install-exec-am: -install-html: install-html-am +install-html: install-html-recursive install-html-am: -install-info: install-info-am +install-info: install-info-recursive install-info-am: -install-man: install-man8 +install-man: install-man5 install-man8 -install-pdf: install-pdf-am +install-pdf: install-pdf-recursive install-pdf-am: -install-ps: install-ps-am +install-ps: install-ps-recursive install-ps-am: installcheck-am: -maintainer-clean: maintainer-clean-am +maintainer-clean: maintainer-clean-recursive -rm -f Makefile maintainer-clean-am: distclean-am maintainer-clean-generic -mostlyclean: mostlyclean-am +mostlyclean: mostlyclean-recursive mostlyclean-am: mostlyclean-generic mostlyclean-libtool -pdf: pdf-am +pdf: pdf-recursive pdf-am: -ps: ps-am +ps: ps-recursive ps-am: -uninstall-am: uninstall-dist_docDATA uninstall-man \ - uninstall-nodist_htmlDATA +uninstall-am: uninstall-dist_docDATA uninstall-dist_htmlDATA \ + uninstall-man + +uninstall-man: uninstall-man5 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-man5 install-man8 install-pdf \ + install-pdf-am install-ps install-ps-am install-strip \ + installcheck installcheck-am installdirs installdirs-am \ + maintainer-clean maintainer-clean-generic mostlyclean \ + mostlyclean-generic mostlyclean-libtool pdf pdf-am ps ps-am \ + tags tags-am uninstall uninstall-am uninstall-dist_docDATA \ + uninstall-dist_htmlDATA uninstall-man uninstall-man5 \ + uninstall-man8 -uninstall-man: uninstall-man8 +.PRECIOUS: Makefile -.MAKE: install-am install-strip -.PHONY: all all-am check check-am clean clean-generic clean-libtool \ - 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-dist_docDATA 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-nodist_htmlDATA 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 uninstall-dist_docDATA \ - uninstall-man uninstall-man8 uninstall-nodist_htmlDATA +.8.rst.8 .5.rst.5 : +@HAVE_PYDOCUTILS_TRUE@ $(RST2MAN) $< > $@ +@HAVE_PYDOCUTILS_FALSE@ @echo "Missing python-docutils - skipping man page generation ($@)" -.PRECIOUS: Makefile +.8.rst.8.html .5.rst.5.html : +@HAVE_PYDOCUTILS_TRUE@ $(RST2HTML) $< > $@ +@HAVE_PYDOCUTILS_FALSE@ @echo "Missing python-docutils - skipping html page generation ($@)" -@WIN32_TRUE@openvpn.8.html: $(srcdir)/openvpn.8 -@WIN32_TRUE@ $(MAN2HTML) < $(srcdir)/openvpn.8 > openvpn.8.html +dist-hook : $(build_man_pages) $(build_html_pages) # Tell versions [3.59,3.63) of GNU make to not export all variables. # Otherwise a system limit (for SysV at least) may be exceeded. diff --git a/doc/doxygen/Makefile.am b/doc/doxygen/Makefile.am new file mode 100644 index 0000000..82d909d --- /dev/null +++ b/doc/doxygen/Makefile.am @@ -0,0 +1,21 @@ +# +# 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-2021 Fox-IT B.V. <openvpn@foxcrypto.com> +# + +MAINTAINERCLEANFILES = \ + $(srcdir)/Makefile.in + +DISTCLEANFILES = openvpn.doxyfile + +.PHONY: doxygen +doxygen: openvpn.doxyfile + doxygen openvpn.doxyfile + +clean-local: + -rm -rf html latex diff --git a/doc/doxygen/Makefile.in b/doc/doxygen/Makefile.in new file mode 100644 index 0000000..48bd413 --- /dev/null +++ b/doc/doxygen/Makefile.in @@ -0,0 +1,533 @@ +# Makefile.in generated by automake 1.16.2 from Makefile.am. +# @configure_input@ + +# Copyright (C) 1994-2020 Free Software Foundation, Inc. + +# This Makefile.in is free software; the Free Software Foundation +# gives unlimited permission to copy and/or distribute it, +# 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-2021 Fox-IT B.V. <openvpn@foxcrypto.com> +# +VPATH = @srcdir@ +am__is_gnu_make = { \ + if test -z '$(MAKELEVEL)'; then \ + false; \ + elif test -n '$(MAKE_HOST)'; then \ + true; \ + elif test -n '$(MAKE_VERSION)' && test -n '$(CURDIR)'; then \ + true; \ + else \ + false; \ + fi; \ +} +am__make_running_with_option = \ + case $${target_option-} in \ + ?) ;; \ + *) echo "am__make_running_with_option: internal error: invalid" \ + "target option '$${target_option-}' specified" >&2; \ + exit 1;; \ + esac; \ + has_opt=no; \ + sane_makeflags=$$MAKEFLAGS; \ + if $(am__is_gnu_make); then \ + sane_makeflags=$$MFLAGS; \ + else \ + case $$MAKEFLAGS in \ + *\\[\ \ ]*) \ + bs=\\; \ + sane_makeflags=`printf '%s\n' "$$MAKEFLAGS" \ + | sed "s/$$bs$$bs[$$bs $$bs ]*//g"`;; \ + esac; \ + fi; \ + skip_next=no; \ + strip_trailopt () \ + { \ + flg=`printf '%s\n' "$$flg" | sed "s/$$1.*$$//"`; \ + }; \ + for flg in $$sane_makeflags; do \ + test $$skip_next = yes && { skip_next=no; continue; }; \ + case $$flg in \ + *=*|--*) continue;; \ + -*I) strip_trailopt 'I'; skip_next=yes;; \ + -*I?*) strip_trailopt 'I';; \ + -*O) strip_trailopt 'O'; skip_next=yes;; \ + -*O?*) strip_trailopt 'O';; \ + -*l) strip_trailopt 'l'; skip_next=yes;; \ + -*l?*) strip_trailopt 'l';; \ + -[dEDm]) skip_next=yes;; \ + -[JT]) skip_next=yes;; \ + esac; \ + case $$flg in \ + *$$target_option*) has_opt=yes; break;; \ + esac; \ + done; \ + test $$has_opt = yes +am__make_dryrun = (target_option=n; $(am__make_running_with_option)) +am__make_keepgoing = (target_option=k; $(am__make_running_with_option)) +pkgdatadir = $(datadir)/@PACKAGE@ +pkgincludedir = $(includedir)/@PACKAGE@ +pkglibdir = $(libdir)/@PACKAGE@ +pkglibexecdir = $(libexecdir)/@PACKAGE@ +am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd +install_sh_DATA = $(install_sh) -c -m 644 +install_sh_PROGRAM = $(install_sh) -c +install_sh_SCRIPT = $(install_sh) -c +INSTALL_HEADER = $(INSTALL_DATA) +transform = $(program_transform_name) +NORMAL_INSTALL = : +PRE_INSTALL = : +POST_INSTALL = : +NORMAL_UNINSTALL = : +PRE_UNINSTALL = : +POST_UNINSTALL = : +build_triplet = @build@ +host_triplet = @host@ +subdir = doc/doxygen +ACLOCAL_M4 = $(top_srcdir)/aclocal.m4 +am__aclocal_m4_deps = $(top_srcdir)/m4/ax_emptyarray.m4 \ + $(top_srcdir)/m4/ax_socklen_t.m4 \ + $(top_srcdir)/m4/ax_varargs.m4 $(top_srcdir)/m4/libtool.m4 \ + $(top_srcdir)/m4/ltoptions.m4 $(top_srcdir)/m4/ltsugar.m4 \ + $(top_srcdir)/m4/ltversion.m4 $(top_srcdir)/m4/lt~obsolete.m4 \ + $(top_srcdir)/m4/pkg.m4 $(top_srcdir)/version.m4 \ + $(top_srcdir)/compat.m4 $(top_srcdir)/configure.ac +am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \ + $(ACLOCAL_M4) +DIST_COMMON = $(srcdir)/Makefile.am $(am__DIST_COMMON) +mkinstalldirs = $(install_sh) -d +CONFIG_HEADER = $(top_builddir)/config.h \ + $(top_builddir)/include/openvpn-plugin.h +CONFIG_CLEAN_FILES = openvpn.doxyfile +CONFIG_CLEAN_VPATH_FILES = +AM_V_P = $(am__v_P_@AM_V@) +am__v_P_ = $(am__v_P_@AM_DEFAULT_V@) +am__v_P_0 = false +am__v_P_1 = : +AM_V_GEN = $(am__v_GEN_@AM_V@) +am__v_GEN_ = $(am__v_GEN_@AM_DEFAULT_V@) +am__v_GEN_0 = @echo " GEN " $@; +am__v_GEN_1 = +AM_V_at = $(am__v_at_@AM_V@) +am__v_at_ = $(am__v_at_@AM_DEFAULT_V@) +am__v_at_0 = @ +am__v_at_1 = +SOURCES = +DIST_SOURCES = +am__can_run_installinfo = \ + case $$AM_UPDATE_INFO_DIR in \ + n|no|NO) false;; \ + *) (install-info --version) >/dev/null 2>&1;; \ + esac +am__tagged_files = $(HEADERS) $(SOURCES) $(TAGS_FILES) $(LISP) +am__DIST_COMMON = $(srcdir)/Makefile.in $(srcdir)/openvpn.doxyfile.in +DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST) +ACLOCAL = @ACLOCAL@ +AMTAR = @AMTAR@ +AM_DEFAULT_VERBOSITY = @AM_DEFAULT_VERBOSITY@ +AR = @AR@ +AS = @AS@ +AUTOCONF = @AUTOCONF@ +AUTOHEADER = @AUTOHEADER@ +AUTOMAKE = @AUTOMAKE@ +AWK = @AWK@ +CC = @CC@ +CCDEPMODE = @CCDEPMODE@ +CFLAGS = @CFLAGS@ +CMOCKA_CFLAGS = @CMOCKA_CFLAGS@ +CMOCKA_LIBS = @CMOCKA_LIBS@ +CPP = @CPP@ +CPPFLAGS = @CPPFLAGS@ +CYGPATH_W = @CYGPATH_W@ +DEFS = @DEFS@ +DEPDIR = @DEPDIR@ +DLLTOOL = @DLLTOOL@ +DL_LIBS = @DL_LIBS@ +DSYMUTIL = @DSYMUTIL@ +DUMPBIN = @DUMPBIN@ +ECHO_C = @ECHO_C@ +ECHO_N = @ECHO_N@ +ECHO_T = @ECHO_T@ +EGREP = @EGREP@ +ENABLE_UNITTESTS = @ENABLE_UNITTESTS@ +EXEEXT = @EXEEXT@ +FGREP = @FGREP@ +GIT = @GIT@ +GREP = @GREP@ +IFCONFIG = @IFCONFIG@ +INSTALL = @INSTALL@ +INSTALL_DATA = @INSTALL_DATA@ +INSTALL_PROGRAM = @INSTALL_PROGRAM@ +INSTALL_SCRIPT = @INSTALL_SCRIPT@ +INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@ +IPROUTE = @IPROUTE@ +LD = @LD@ +LDFLAGS = @LDFLAGS@ +LIBOBJS = @LIBOBJS@ +LIBPAM_CFLAGS = @LIBPAM_CFLAGS@ +LIBPAM_LIBS = @LIBPAM_LIBS@ +LIBS = @LIBS@ +LIBTOOL = @LIBTOOL@ +LIPO = @LIPO@ +LN_S = @LN_S@ +LTLIBOBJS = @LTLIBOBJS@ +LT_SYS_LIBRARY_PATH = @LT_SYS_LIBRARY_PATH@ +LZ4_CFLAGS = @LZ4_CFLAGS@ +LZ4_LIBS = @LZ4_LIBS@ +LZO_CFLAGS = @LZO_CFLAGS@ +LZO_LIBS = @LZO_LIBS@ +MAKEINFO = @MAKEINFO@ +MANIFEST_TOOL = @MANIFEST_TOOL@ +MBEDTLS_CFLAGS = @MBEDTLS_CFLAGS@ +MBEDTLS_LIBS = @MBEDTLS_LIBS@ +MKDIR_P = @MKDIR_P@ +NETSTAT = @NETSTAT@ +NM = @NM@ +NMEDIT = @NMEDIT@ +OBJDUMP = @OBJDUMP@ +OBJEXT = @OBJEXT@ +OPENSSL_CFLAGS = @OPENSSL_CFLAGS@ +OPENSSL_LIBS = @OPENSSL_LIBS@ +OPENVPN_VERSION_MAJOR = @OPENVPN_VERSION_MAJOR@ +OPENVPN_VERSION_MINOR = @OPENVPN_VERSION_MINOR@ +OPENVPN_VERSION_PATCH = @OPENVPN_VERSION_PATCH@ +OPTIONAL_CRYPTO_CFLAGS = @OPTIONAL_CRYPTO_CFLAGS@ +OPTIONAL_CRYPTO_LIBS = @OPTIONAL_CRYPTO_LIBS@ +OPTIONAL_DL_LIBS = @OPTIONAL_DL_LIBS@ +OPTIONAL_INOTIFY_CFLAGS = @OPTIONAL_INOTIFY_CFLAGS@ +OPTIONAL_INOTIFY_LIBS = @OPTIONAL_INOTIFY_LIBS@ +OPTIONAL_LZ4_CFLAGS = @OPTIONAL_LZ4_CFLAGS@ +OPTIONAL_LZ4_LIBS = @OPTIONAL_LZ4_LIBS@ +OPTIONAL_LZO_CFLAGS = @OPTIONAL_LZO_CFLAGS@ +OPTIONAL_LZO_LIBS = @OPTIONAL_LZO_LIBS@ +OPTIONAL_PKCS11_HELPER_CFLAGS = @OPTIONAL_PKCS11_HELPER_CFLAGS@ +OPTIONAL_PKCS11_HELPER_LIBS = @OPTIONAL_PKCS11_HELPER_LIBS@ +OPTIONAL_SELINUX_LIBS = @OPTIONAL_SELINUX_LIBS@ +OPTIONAL_SYSTEMD_LIBS = @OPTIONAL_SYSTEMD_LIBS@ +OTOOL = @OTOOL@ +OTOOL64 = @OTOOL64@ +P11KIT_CFLAGS = @P11KIT_CFLAGS@ +P11KIT_LIBS = @P11KIT_LIBS@ +PACKAGE = @PACKAGE@ +PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@ +PACKAGE_NAME = @PACKAGE_NAME@ +PACKAGE_STRING = @PACKAGE_STRING@ +PACKAGE_TARNAME = @PACKAGE_TARNAME@ +PACKAGE_URL = @PACKAGE_URL@ +PACKAGE_VERSION = @PACKAGE_VERSION@ +PATH_SEPARATOR = @PATH_SEPARATOR@ +PKCS11_HELPER_CFLAGS = @PKCS11_HELPER_CFLAGS@ +PKCS11_HELPER_LIBS = @PKCS11_HELPER_LIBS@ +PKG_CONFIG = @PKG_CONFIG@ +PKG_CONFIG_LIBDIR = @PKG_CONFIG_LIBDIR@ +PKG_CONFIG_PATH = @PKG_CONFIG_PATH@ +PLUGINDIR = @PLUGINDIR@ +PLUGIN_AUTH_PAM_CFLAGS = @PLUGIN_AUTH_PAM_CFLAGS@ +PLUGIN_AUTH_PAM_LIBS = @PLUGIN_AUTH_PAM_LIBS@ +RANLIB = @RANLIB@ +RC = @RC@ +ROUTE = @ROUTE@ +RST2HTML = @RST2HTML@ +RST2MAN = @RST2MAN@ +SED = @SED@ +SELINUX_LIBS = @SELINUX_LIBS@ +SET_MAKE = @SET_MAKE@ +SHELL = @SHELL@ +SOCKETS_LIBS = @SOCKETS_LIBS@ +STRIP = @STRIP@ +SYSTEMD_ASK_PASSWORD = @SYSTEMD_ASK_PASSWORD@ +SYSTEMD_UNIT_DIR = @SYSTEMD_UNIT_DIR@ +TAP_CFLAGS = @TAP_CFLAGS@ +TAP_WIN_COMPONENT_ID = @TAP_WIN_COMPONENT_ID@ +TAP_WIN_MIN_MAJOR = @TAP_WIN_MIN_MAJOR@ +TAP_WIN_MIN_MINOR = @TAP_WIN_MIN_MINOR@ +TEST_CFLAGS = @TEST_CFLAGS@ +TEST_LDFLAGS = @TEST_LDFLAGS@ +TMPFILES_DIR = @TMPFILES_DIR@ +VERSION = @VERSION@ +abs_builddir = @abs_builddir@ +abs_srcdir = @abs_srcdir@ +abs_top_builddir = @abs_top_builddir@ +abs_top_srcdir = @abs_top_srcdir@ +ac_ct_AR = @ac_ct_AR@ +ac_ct_CC = @ac_ct_CC@ +ac_ct_DUMPBIN = @ac_ct_DUMPBIN@ +am__include = @am__include@ +am__leading_dot = @am__leading_dot@ +am__quote = @am__quote@ +am__tar = @am__tar@ +am__untar = @am__untar@ +bindir = @bindir@ +build = @build@ +build_alias = @build_alias@ +build_cpu = @build_cpu@ +build_os = @build_os@ +build_vendor = @build_vendor@ +builddir = @builddir@ +datadir = @datadir@ +datarootdir = @datarootdir@ +docdir = @docdir@ +dvidir = @dvidir@ +exec_prefix = @exec_prefix@ +host = @host@ +host_alias = @host_alias@ +host_cpu = @host_cpu@ +host_os = @host_os@ +host_vendor = @host_vendor@ +htmldir = @htmldir@ +includedir = @includedir@ +infodir = @infodir@ +install_sh = @install_sh@ +libdir = @libdir@ +libexecdir = @libexecdir@ +libsystemd_CFLAGS = @libsystemd_CFLAGS@ +libsystemd_LIBS = @libsystemd_LIBS@ +localedir = @localedir@ +localstatedir = @localstatedir@ +mandir = @mandir@ +mkdir_p = @mkdir_p@ +oldincludedir = @oldincludedir@ +pdfdir = @pdfdir@ +plugindir = @plugindir@ +prefix = @prefix@ +program_transform_name = @program_transform_name@ +psdir = @psdir@ +runstatedir = @runstatedir@ +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/openvpn.doxyfile.in b/doc/doxygen/openvpn.doxyfile.in new file mode 100644 index 0000000..beb02d9 --- /dev/null +++ b/doc/doxygen/openvpn.doxyfile.in @@ -0,0 +1,279 @@ +# Doxyfile 1.5.5 + +#--------------------------------------------------------------------------- +# Project related configuration options +#--------------------------------------------------------------------------- +DOXYFILE_ENCODING = UTF-8 +PROJECT_NAME = "OpenVPN" +PROJECT_NUMBER = +OUTPUT_DIRECTORY = "@abs_top_builddir@/doc/doxygen" +CREATE_SUBDIRS = NO +OUTPUT_LANGUAGE = English +BRIEF_MEMBER_DESC = YES +REPEAT_BRIEF = YES +ABBREVIATE_BRIEF = "The $name class" \ + "The $name widget" \ + "The $name file" \ + is \ + provides \ + specifies \ + contains \ + represents \ + a \ + an \ + the +ALWAYS_DETAILED_SEC = NO +INLINE_INHERITED_MEMB = NO +FULL_PATH_NAMES = YES +STRIP_FROM_PATH = "@abs_top_srcdir@" +STRIP_FROM_INC_PATH = +SHORT_NAMES = NO +JAVADOC_AUTOBRIEF = YES # NO +QT_AUTOBRIEF = NO +MULTILINE_CPP_IS_BRIEF = NO +DETAILS_AT_TOP = NO +INHERIT_DOCS = YES +SEPARATE_MEMBER_PAGES = NO +TAB_SIZE = 8 +ALIASES = +OPTIMIZE_OUTPUT_FOR_C = YES +OPTIMIZE_OUTPUT_JAVA = NO +OPTIMIZE_FOR_FORTRAN = NO +OPTIMIZE_OUTPUT_VHDL = NO +BUILTIN_STL_SUPPORT = NO +CPP_CLI_SUPPORT = NO +SIP_SUPPORT = NO +DISTRIBUTE_GROUP_DOC = NO +SUBGROUPING = YES +TYPEDEF_HIDES_STRUCT = NO +#--------------------------------------------------------------------------- +# Build related configuration options +#--------------------------------------------------------------------------- +EXTRACT_ALL = YES +EXTRACT_PRIVATE = YES +EXTRACT_STATIC = YES +EXTRACT_LOCAL_CLASSES = YES +EXTRACT_LOCAL_METHODS = YES +EXTRACT_ANON_NSPACES = YES +HIDE_UNDOC_MEMBERS = NO +HIDE_UNDOC_CLASSES = NO +HIDE_FRIEND_COMPOUNDS = NO +HIDE_IN_BODY_DOCS = NO +INTERNAL_DOCS = NO +CASE_SENSE_NAMES = NO +HIDE_SCOPE_NAMES = NO +SHOW_INCLUDE_FILES = YES +INLINE_INFO = YES +SORT_MEMBER_DOCS = YES +SORT_BRIEF_DOCS = NO +SORT_GROUP_NAMES = NO +SORT_BY_SCOPE_NAME = NO +GENERATE_TODOLIST = YES +GENERATE_TESTLIST = YES +GENERATE_BUGLIST = YES +GENERATE_DEPRECATEDLIST= YES +ENABLED_SECTIONS = +MAX_INITIALIZER_LINES = 30 +SHOW_USED_FILES = YES +SHOW_DIRECTORIES = NO +FILE_VERSION_FILTER = +#--------------------------------------------------------------------------- +# configuration options related to warning and progress messages +#--------------------------------------------------------------------------- +QUIET = NO +WARNINGS = YES +WARN_IF_UNDOCUMENTED = YES +WARN_IF_DOC_ERROR = YES +WARN_NO_PARAMDOC = NO +WARN_FORMAT = "$file:$line: $text" +WARN_LOGFILE = +#--------------------------------------------------------------------------- +# configuration options related to the input files +#--------------------------------------------------------------------------- +INPUT = "@abs_top_srcdir@" +INPUT_ENCODING = UTF-8 +FILE_PATTERNS = *.c \ + *.cc \ + *.cxx \ + *.cpp \ + *.c++ \ + *.d \ + *.java \ + *.ii \ + *.ixx \ + *.ipp \ + *.i++ \ + *.inl \ + *.h \ + *.hh \ + *.hxx \ + *.hpp \ + *.h++ \ + *.idl \ + *.odl \ + *.cs \ + *.php \ + *.php3 \ + *.inc \ + *.m \ + *.mm \ + *.dox \ + *.py \ + *.f90 \ + *.f \ + *.vhd \ + *.vhdl +RECURSIVE = YES +EXCLUDE = +EXCLUDE_SYMLINKS = NO +EXCLUDE_PATTERNS = +EXCLUDE_SYMBOLS = +EXAMPLE_PATH = +EXAMPLE_PATTERNS = * +EXAMPLE_RECURSIVE = NO +IMAGE_PATH = +INPUT_FILTER = +FILTER_PATTERNS = +FILTER_SOURCE_FILES = NO +#--------------------------------------------------------------------------- +# configuration options related to source browsing +#--------------------------------------------------------------------------- +SOURCE_BROWSER = YES +INLINE_SOURCES = NO +STRIP_CODE_COMMENTS = YES +REFERENCED_BY_RELATION = YES +REFERENCES_RELATION = YES +REFERENCES_LINK_SOURCE = YES +USE_HTAGS = NO +VERBATIM_HEADERS = YES +#--------------------------------------------------------------------------- +# configuration options related to the alphabetical class index +#--------------------------------------------------------------------------- +ALPHABETICAL_INDEX = NO +COLS_IN_ALPHA_INDEX = 5 +IGNORE_PREFIX = +#--------------------------------------------------------------------------- +# configuration options related to the HTML output +#--------------------------------------------------------------------------- +GENERATE_HTML = YES +HTML_OUTPUT = html +HTML_FILE_EXTENSION = .html +HTML_HEADER = +HTML_FOOTER = +HTML_STYLESHEET = +HTML_ALIGN_MEMBERS = YES +GENERATE_HTMLHELP = NO +GENERATE_DOCSET = NO +DOCSET_FEEDNAME = "Doxygen generated docs" +DOCSET_BUNDLE_ID = org.doxygen.Project +HTML_DYNAMIC_SECTIONS = NO +CHM_FILE = +HHC_LOCATION = +GENERATE_CHI = NO +BINARY_TOC = NO +TOC_EXPAND = NO +DISABLE_INDEX = NO +ENUM_VALUES_PER_LINE = 4 +GENERATE_TREEVIEW = NO +TREEVIEW_WIDTH = 250 +#--------------------------------------------------------------------------- +# configuration options related to the LaTeX output +#--------------------------------------------------------------------------- +GENERATE_LATEX = YES +LATEX_OUTPUT = latex +LATEX_CMD_NAME = latex +MAKEINDEX_CMD_NAME = makeindex +COMPACT_LATEX = YES # NO +PAPER_TYPE = a4wide +EXTRA_PACKAGES = +LATEX_HEADER = +PDF_HYPERLINKS = YES +USE_PDFLATEX = YES +LATEX_BATCHMODE = NO +LATEX_HIDE_INDICES = NO +#--------------------------------------------------------------------------- +# configuration options related to the RTF output +#--------------------------------------------------------------------------- +GENERATE_RTF = NO +RTF_OUTPUT = rtf +COMPACT_RTF = NO +RTF_HYPERLINKS = NO +RTF_STYLESHEET_FILE = +RTF_EXTENSIONS_FILE = +#--------------------------------------------------------------------------- +# configuration options related to the man page output +#--------------------------------------------------------------------------- +GENERATE_MAN = NO +MAN_OUTPUT = man +MAN_EXTENSION = .3 +MAN_LINKS = NO +#--------------------------------------------------------------------------- +# configuration options related to the XML output +#--------------------------------------------------------------------------- +GENERATE_XML = NO +XML_OUTPUT = xml +XML_SCHEMA = +XML_DTD = +XML_PROGRAMLISTING = YES +#--------------------------------------------------------------------------- +# configuration options for the AutoGen Definitions output +#--------------------------------------------------------------------------- +GENERATE_AUTOGEN_DEF = NO +#--------------------------------------------------------------------------- +# configuration options related to the Perl module output +#--------------------------------------------------------------------------- +GENERATE_PERLMOD = NO +PERLMOD_LATEX = NO +PERLMOD_PRETTY = YES +PERLMOD_MAKEVAR_PREFIX = +#--------------------------------------------------------------------------- +# Configuration options related to the preprocessor +#--------------------------------------------------------------------------- +ENABLE_PREPROCESSING = YES +MACRO_EXPANSION = NO +EXPAND_ONLY_PREDEF = NO +SEARCH_INCLUDES = YES +INCLUDE_PATH = +INCLUDE_FILE_PATTERNS = +PREDEFINED = _WIN32 NTLM USE_LZO ENABLE_FRAGMENT P2MP ENABLE_CRYPTO_OPENSSL ENABLE_PLUGIN ENABLE_MANAGEMENT ENABLE_OCC HAVE_GETTIMEOFDAY +EXPAND_AS_DEFINED = +SKIP_FUNCTION_MACROS = YES +#--------------------------------------------------------------------------- +# Configuration::additions related to external references +#--------------------------------------------------------------------------- +TAGFILES = +GENERATE_TAGFILE = +ALLEXTERNALS = NO +EXTERNAL_GROUPS = YES +PERL_PATH = /usr/bin/perl +#--------------------------------------------------------------------------- +# Configuration options related to the dot tool +#--------------------------------------------------------------------------- +CLASS_DIAGRAMS = NO +MSCGEN_PATH = +HIDE_UNDOC_RELATIONS = YES +HAVE_DOT = YES +CLASS_GRAPH = YES +COLLABORATION_GRAPH = YES +GROUP_GRAPHS = YES +UML_LOOK = NO +TEMPLATE_RELATIONS = NO +INCLUDE_GRAPH = YES +INCLUDED_BY_GRAPH = YES +CALL_GRAPH = NO # YES +CALLER_GRAPH = NO # YES +GRAPHICAL_HIERARCHY = YES +DIRECTORY_GRAPH = YES +DOT_IMAGE_FORMAT = png +DOT_PATH = "/usr/bin/dot" +DOTFILE_DIRS = +DOT_GRAPH_MAX_NODES = 50 +MAX_DOT_GRAPH_DEPTH = 1000 +DOT_TRANSPARENT = YES +DOT_MULTI_TARGETS = NO +GENERATE_LEGEND = YES +DOT_CLEANUP = YES +#--------------------------------------------------------------------------- +# Configuration::additions related to the search engine +#--------------------------------------------------------------------------- +SEARCHENGINE = NO diff --git a/doc/gui-notes.txt b/doc/gui-notes.txt new file mode 100644 index 0000000..e3bbf24 --- /dev/null +++ b/doc/gui-notes.txt @@ -0,0 +1,369 @@ +Management Interface "echo" protocol + +================================================================================ +THIS IS A PRELIMINARY VERSION OF THIS DOCUMENT. ALL INFORMATION IN IT +IS SUBJECT TO CHANGE. +================================================================================ + + + CONTENTS + THE OPENVPN --ECHO OPTION + ENVIRONMENT COMMAND + MESSSAGE COMMANDS + PASSWORD COMMANDS + QUOTING + COMMMAND DETAILS + + +========================= +THE OPENVPN --ECHO OPTION +========================= + +The OpenVPN --echo option causes commands to be sent out through the +management interface, typically to a Graphic User Interface (GUI) such +as "OpenVPN for Android", "Tunnelblick" (for macOS), or "Windows +OpenVPN GUI". It can be included in a configuration file or on a +command line, or can be pushed from the server. + +This document describes the commands that can be sent and how they are +interpreted by various GUIs. + + * OpenVPN does not process the commands in an --echo option; it only +sends them out through the management interface. + + * "echo" commands are processed by the GUI if, as, when, and in the +order they are received. If no GUI is present the processing of +commands may be delayed, the commands may never be processed, or only +some commands may be processed. (That can happen if OpenVPN discards +commands because its buffer for the commands fills up.) + + * There is no mechanism for the GUI to acknowledge the receipt, +success, or failure of a command. + + * "echo" commands are stored by OpenVPN (within limits, see the next +point) and sent only when the GUI requests them through the management +interface. "echo" commands in the configuration file or the command +line are typically requested and processed at the start of a +connection attempt. "echo" commands that are pushed by the server are +also typically asked for at the start of a connection attempt but can +be sent at any time. They are processed in the middle of a connection +attempt or after a connection is established, as the "push" options +are received by the client from the server. + + * OpenVPN's storage for echo commands is limited in size, so a large +number of commands or commands with long messages may require that +some commands be removed from the storage. If that happens, some of +the commands may not be sent through the management interface when a +GUI does connect to it or asks for the "echo" commands. + + * On SIGUSR1 and SIGHUP connection restarts, "echo" commands that +were sent through the management interface and have been saved by +OpenVPN are sent again and will be re-processed by the GUI. (The +message commands include a mechanism for muting (skipping) duplicate +messages, see MESSAGE COMMANDS, below.) + + * OpenVPN limits the number of separate arguments in each line of a +configuration file. Arguments may be quoted to work around this +limitation, see QUOTING, below. + + * OpenVPN limits the size of each "echo" command sent over the +management interface to 255 bytes, including overhead characters. To +allow messages of arbitrary length, several message commands can be +concatenated together before being displayed to the user, see MESSAGE +COMMANDS, below. + + * There no indication to the GUI of the source of the command +(configuration file, command line option, or pushed from a server). It +might be possible for the GUI to deduce that a command was pushed from +a server because of timing or other management interface interactions. + + +=================== +ENVIRONMENT COMMAND +=================== + +Typically, a GUI allows users to specify shell commands (typically +scripts) to run at certain points in the connection/disconnection +process, in addition to those provided by OpenVPN options such as +"--up" and "--down". + +The "setenv" command can be used to set environment variables that are +available to the scripts run by the GUI. Each "setenv" command +specifies a value for one environment variable that is available to +the scripts that the GUI runs. + +This is similar to Openvpn's "--setenv" option, which specifies an +additional environment variable that is included in the environment +variables that are available to the scripts that OpenVPN runs. + + +================= +MESSSAGE COMMANDS +================= + +Four commands can be used to display a message to the user from the +OpenVPN configuration or server: + + msg + msg-n + msg-window + msg-notify + +"msg" and "msg-n" commands are concatenated to construct a message. +When a "msg-window"or "msg-notify" command is received the message is +displayed to the user. + +Identical messages (same title, text, and destination) received during +one connection may be ignored or muted. Some GUIs may only show the +first message for a connection, or the first message shown in a window +and the first message shown as a notification. + + +================= +PASSWORD COMMANDS +================= + +Three commands can be used to control the GUI's storage of usernames, +passwords, and private keys: + + disable-save-passwords + forget-passwords + save-passwords + + +======= +QUOTING +======= + + * In a configuration file, the rest of the line is parsed into +separate arguments and then 'echo' and the arguments are passed, each +separated by a single space, through the management interface. For +example: + + echo argument1 argument2 + echo " argument1 argument2" + +will be sent through the management interface as + + >ECHO:timestamp,argument1 argument2 + >ECHO:timestamp, argument1 argument2 + + * In a command line option, the single argument following "--echo" is +parsed similarly, so + + --echo argument1 argument2 + --echo " argument1 argument2" + +will be sent through the management interface as + + >ECHO:timestamp,argument1 argument2 + >ECHO:timestamp, argument1 argument2 + + * In a "push" option in a server configuration file, the single +option following "push" is parsed similarly, so + + push "echo argument1 argument2 argument3 argument4" + push "echo ' argument1 argument2 argument3 argument4'" + +will be sent through the management interface as + + >ECHO:timestamp,argument1 argument2 argument3 argument4 + >ECHO:timestamp, argument1 argument2 argument3 argument4 + + +================ +COMMMAND DETAILS +================ + + +COMMAND -- disable-save-passwords +--------------------------------- + +Syntax: disable-save-passwords + +The GUI is instructed to not allow the user to save passwords or +private keys for the configuration. The user is still allowed to save +usernames. Any passwords or private keys that have been saved will be +forgotten. + +This command will be effective at startup only if present in the +configuration file or as a command line option. If pushed from the +server, saving passwords will be disabled in password prompts only +after the initial prompt has been shown to the user. + + Android: ?????? + + Tunnelblick: Planned. This command will disable saving of +passwords or private keys and forget any saved usernames, passwords, +or private keys regardless of the normal (non-forced) global or +per-configuration settings. A computer administrator can "force" this +setting, overriding this command. + + Windows OpenVPN GUI: Planned. This command will disable saving of +passwords or private keys and forget any saved usernames, passwords, +or private keys regardless of any global settings. + + +COMMAND -- forget-passwords +--------------------------- + +Syntax: forget-passwords + +The GUI is instructed to forget any usernames, passwords, and private +keys it has saved for the configuration. Useful when pushed from the +server so that it is processed after authentication. + + Android: ?????? + + Tunnelblick: Planned. + + Windows OpenVPN GUI: supported since release 2.4.1 (GUI version 11.5.0) + + +COMMAND -- msg +-------------- + +Syntax: msg text + +The text is appended to any previous text from "msg" or "msg-n" +commands, and a newline is appended after that. + +A trailing newline will be removed from the completed message before +it is displayed to the user. + +The text may include any UTF-8 character except a comma (","), CR +(0x0D), LF (0x0A), or NUL (0x00). + +The text may not contain percent ("%") except in "percent encoding" +sequences. To display a percent sign, use %25. + +The text may not contain commas (",") because of constraints imposed +by OpenVPN. Commas should be encoded using "percent encoding" (URL +encoding): a '%' character followed by two hexadecimal digits, the +high- and then low-nibble of the ASCII code for the character to be +shown. Examples: a comma is encoded as %2C or %2c; a percent sign is +encoded as %25. + +Text containing comment characters # and ; must be enclosed in quotes to +survive after option parsing by openvpn. + +The insertion of line endings (CR, LF) in the text is discouraged +because it is OS dependent. Instead, use the "msg" command, which +appends a line ending appropriate for the OS on which the GUI is +running. + + Android: Planned. + + Tunnelblick: Planned. + + Windows OpenVPN GUI: supported since release v2.4.11 / v2.5.1 + (GUI version v11.22.0) + +COMMAND -- msg-n +---------------- + +Syntax: msg-n text + +The text is appended to any previous text from "msg"" or "msg-n"" +commands. (Like "msg" except that no newline is appended.) + +See "COMMAND -- msg" for details about "text". + + Android: Planned. + + Tunnelblick: Planned. + + Windows OpenVPN GUI: supported since release v2.4.11 / v2.5.1 + (GUI version v11.22.0) + +COMMAND -- msg-notify +--------------------- + +Syntax: msg-notify title + +The text from previous "msg" and/or "msg-n" commands is displayed to +the user as a notification with title "title" and the previous text is +forgotten. + + Android: Planned. + + Tunnelblick: Planned. + + Windows OpenVPN GUI: supported since release v2.4.11 / v2.5.1 + (GUI version v11.22.0) + +Note: The max length that will correctly display as a notification +message is OS dependent. + + +COMMAND -- msg-window title +--------------------------- + +Syntax: msg-window title + +The text from previous "msg" and/or "msg-n" commands is displayed to +the user in a non-modal popup window with title "title" and the +previous text is forgotten. How the title is displayed exactly is left +to the implementation. Could be set as the window title or as a +differently formatted text as the heading of the message, for example. + + Android: Planned. + + Tunnelblick: Planned. + + Windows OpenVPN GUI: supported since release v2.4.11 / v2.5.1 + (GUI version v11.22.0) + + +COMMAND -- save-passwords +------------------------- + +Syntax: save-passwords + +The GUI is instructed to allow the user to save usernames, passwords +and private keys for the configuration. + +This command will be effective at startup only if present in the +configuration file or as a command line option. If pushed from the +server, saving passwords will be allowed in password prompts only +after the initial prompt has been shown to the user. + +This command typically has the effect of presenting the password +dialogs to the user with a "save password" checkbox checked. The user +may still uncheck it during the dialog. + + Android: ?????? + + Tunnelblick: Planned. Tunnelblick ignores this command. Usernames, +passwords, and private keys may be saved by default, and this command +will not override the separate Tunnelblick global or per-configuration +settings used to disable saving them. + + Windows OpenVPN GUI: Supported since release 2.4.1 (GUI version 11.5.0) + + +COMMAND -- setenv +----------------- + +Syntax: setenv name value + +Sets an environment variable that will be available to the scripts run +by the GUI. + +This will set environment variable "OPENVPN_name" to value "value" for +the scripts run by the GUI. "name" is changed to "OPENVPN_name" to +prevent overwriting sensitive variables such as PATH. Variables are +set in the order received, with later values replacing earlier ones +for the same "name". + +Names may include only alphanumeric characters and underscores. A +"setenv" command with an invalid name will be ignored. + + Android: ?????? + + Tunnelblick: Planned. + + Windows OpenVPN GUI: supported since release v2.4.7 (GUI version v11.12.0) +The variables set by "setenv" are merged with those for the process +environment. In case of duplicate names the one in the setenv list is +chosen. diff --git a/doc/man-sections/advanced-options.rst b/doc/man-sections/advanced-options.rst new file mode 100644 index 0000000..bedc884 --- /dev/null +++ b/doc/man-sections/advanced-options.rst @@ -0,0 +1,110 @@ +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 + + For IPv6 this queries the route towards ::/128, or the specified IPv6 + target address if passed as argument. + For IPv4 on Linux, Windows, MacOS and BSD it looks for a 0.0.0.0/0 route. + If there are more specific routes, the result will not always be matching + the route of the IPv4 packets to the VPN gateway. + + +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 :code:`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 :code:`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 :code:`sha1`), + and set ``nsl`` (default :code:`16`) to the size in bytes of the nonce + secret length (between 16 and 64). + + Set ``alg`` to :code:`none` to disable the PRNG and use the OpenSSL + RAND\_bytes function instead for all of OpenVPN's pseudo-random number + needs. + +--rcvbuf size + Set 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 + :code:`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 size + Set 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 :code:`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. + diff --git a/doc/man-sections/client-options.rst b/doc/man-sections/client-options.rst new file mode 100644 index 0000000..c5b7ad9 --- /dev/null +++ b/doc/man-sections/client-options.rst @@ -0,0 +1,369 @@ +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 :code:`OPENVPN_PLUGIN_CLIENT_CONNECT` + or :code:`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 + :code:`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 :code:`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-token-user base64username + Companion option to ``--auth-token``. This options allows to override + the username used by the client when reauthenticating with the ``auth-token``. + It also allows to use ``--auth-token`` in setups that normally do not use + username and password. + + The username has to be base64 encoded. + +--auth-user-pass + Authenticate with server using username/password. + + 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 :code:`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 :code:`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: + + :code:`none` + Client will exit with a fatal error (this is the default). + + :code:`nointeract` + Client will retry the connection without requerying + for an ``--auth-user-pass`` username/password. Use this option for + unattended clients. + + :code:`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 :code:`192.168.0.0/255.255.0.0`) defines + the local view of a resource from the client perspective, while + ``alias/netmask`` (for example :code:`10.64.0.0/255.255.0.0`) defines the + remote view from the server perspective. + + Use :code:`snat` (source NAT) for resources owned by the client and + :code:`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 :code:`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 :code:`300`). + +--connect-retry-max n + ``n`` specifies the number of times each ``--remote`` or + ``<connection>`` entry is tried. Specifying ``n`` as :code:`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 :code:`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 :code:`RESTART` control channel command to + connected clients. The ``n`` parameter (default :code:`1` if not present) + controls client behavior. With ``n`` = :code:`1` client will attempt to + reconnect to the same server, with ``n`` = :code:`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`` (:code:`tcp` \| :code:`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 + :code:`text`. The action flag :code:`accept` allows the option, + :code:`ignore` removes it and :code:`reject` flags an error and triggers + a :code:`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 :code:`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 :code:`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 :code:`ignore`. + +--remote args + Remote host name or IP address, port and protocol. + + Valid syntaxes: + :: + + remote host + remote host port + remote host port proto + + The ``port`` and ``proto`` arguments are optional. The OpenVPN client + will try to connect to a server at ``host:port``. The ``proto`` argument + indicates the protocol to use when connecting with the remote, and may be + :code:`tcp` or :code:`udp`. To enforce IPv4 or IPv6 connections add a + :code:`4` or :code:`6` suffix; like :code:`udp4` / :code:`udp6` + / :code:`tcp4` / :code:`tcp6`. + + On the client, multiple ``--remote`` options may be specified for + redundancy, each referring to a different OpenVPN server, in the order + specified by the list of ``--remote`` options. Specifying multiple + ``--remote`` options for this purpose is a special case of the more + general connection-profile feature. See the ``<connection>`` + documentation below. + + 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. + + Examples: + :: + + remote server1.example.net + remote server1.example.net 1194 + remote server2.example.net 1194 tcp + + *Note:* + Since UDP is connectionless, connection failure is defined by + the ``--ping`` and ``--ping-restart`` options. + + Also, 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 + :code:`0` or :code:`1`. + + See management-notes.txt in the OpenVPN distribution for a description of + the OpenVPN challenge/response protocol. + +.. include:: proxy-options.rst diff --git a/doc/man-sections/connection-profiles.rst b/doc/man-sections/connection-profiles.rst new file mode 100644 index 0000000..fd3382b --- /dev/null +++ b/doc/man-sections/connection-profiles.rst @@ -0,0 +1,75 @@ +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. diff --git a/doc/man-sections/encryption-options.rst b/doc/man-sections/encryption-options.rst new file mode 100644 index 0000000..ee34f14 --- /dev/null +++ b/doc/man-sections/encryption-options.rst @@ -0,0 +1,135 @@ +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: + + :code:`secret` Standard OpenVPN shared secret keys + + :code:`tls-crypt` Alias for :code:`secret` + + :code:`tls-auth` Alias for :code:`secret` + + :code:`auth-token` Key used for ``--auth-gen-token-key`` + + :code:`tls-crypt-v2-server` TLS Crypt v2 server key + + :code:`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. + +.. include:: renegotiation.rst +.. include:: tls-options.rst +.. include:: pkcs11-options.rst diff --git a/doc/man-sections/examples.rst b/doc/man-sections/examples.rst new file mode 100644 index 0000000..3f494ea --- /dev/null +++ b/doc/man-sections/examples.rst @@ -0,0 +1,240 @@ +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 :code:`client.crt`, +:code:`client.key`, :code:`server.crt`, :code:`server.key` and +:code:`ca.crt`. The ``.crt`` files are certificates/public-keys, the +``.key`` files are private keys, and :code:`ca.crt` is a certification +authority who has signed both :code:`client.crt` and :code:`server.crt`. +For Diffie Hellman parameters you can use the included file +:code:`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. diff --git a/doc/man-sections/generic-options.rst b/doc/man-sections/generic-options.rst new file mode 100644 index 0000000..d5f0883 --- /dev/null +++ b/doc/man-sections/generic-options.rst @@ -0,0 +1,445 @@ +Generic Options +--------------- +This section covers generic options which are accessible regardless of +which mode OpenVPN is configured as. + +--help + + Show 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 :code:`.` or :code:`..`. + + 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 :code:`/var/log/messages`), except for the output of + scripts and ifconfig commands, which will go to :code:`/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 group + Similar 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 cmd + Set 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 + (:code:`exported_keying_material`) for use by plugins in + :code:`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 + :code:`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. + + The limit on how much memory can be locked and how that limit + is enforced are OS-dependent. On Linux the default limit that an + unprivileged process may lock (RLIMIT_MEMLOCK) is low, and if + privileges are dropped later, future memory allocations will very + likely fail. The limit can be increased using ulimit or systemd + directives depending on how OpenVPN is started. + +--nice n + Change 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 :code:`SIGUSR1` or ``--ping-restart``. + + This option can be combined with ``--user nobody`` to allow restarts + triggered by the :code:`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 :code:`SIGUSR1` + resets, so they don't need to be re-read. + +--remap-usr1 signal + Control whether internally or externally generated :code:`SIGUSR1` signals + are remapped to :code:`SIGHUP` (restart without persisting state) or + SIGTERM (exit). + + ``signal`` can be set to :code:`SIGHUP` or :code:`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``: + + :code:`0` + Strictly no calling of external programs. + + :code:`1` + (Default) Only call built-in executables such as ifconfig, + ip, route, or netsh. + + :code:`2` + Allow calling of built-in executables and user-defined + scripts. + + :code:`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 :code:`execve` or :code:`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 :code:`system` flag was removed is due to + the security implications with shell expansions when executing scripts + via the :code:`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 :code:`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: + + :code:`1` + Traditional format (default). The client list contains the + following fields comma-separated: Common Name, Real Address, Bytes + Received, Bytes Sent, Connected Since. + + :code:`2` + A more reliable format for external processing. Compared to + version :code:`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. + + :code:`3` + Identical to :code:`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 :code:`OPENVPN_PLUGIN_CLIENT_CONNECT` + plug-in hook to dynamically generate client-specific configuration + :code:`client_connect_config_file` and return success/failure via + :code:`client_connect_deferred_file` when using deferred client connect + method + + * :code:`OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY` plug-in hooks returns + success/failure via :code:`auth_control_file` when using deferred auth + method + + * :code:`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 :code:`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 :code:`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``. diff --git a/doc/man-sections/inline-files.rst b/doc/man-sections/inline-files.rst new file mode 100644 index 0000000..819bd3c --- /dev/null +++ b/doc/man-sections/inline-files.rst @@ -0,0 +1,25 @@ +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 :code:`openssl base64 -in input.p12` diff --git a/doc/man-sections/link-options.rst b/doc/man-sections/link-options.rst new file mode 100644 index 0000000..c132a62 --- /dev/null +++ b/doc/man-sections/link-options.rst @@ -0,0 +1,409 @@ +Link Options +------------ +This link options section covers options related to the connection between +the local and the remote host. + +--bind keywords + Bind to local address and port. This is the default unless any of + ``--proto tcp-client`` , ``--http-proxy`` or ``--socks-proxy`` are used. + + If the optional :code:`ipv6only` keyword is present OpenVPN will bind only + to IPv6 (as opposed to IPv6 and IPv4) when a IPv6 socket is opened. + +--float + Allow remote peer to change its IP address and/or port number, such as + due to DHCP (this is the default if ``--remote`` is not used). + ``--float`` when specified with ``--remote`` 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. + + Essentially, ``--float`` tells OpenVPN to accept authenticated packets + from any address, not only the address which was specified in the + ``--remote`` option. + +--fragment max + Enable internal datagram fragmentation so that no UDP datagrams are sent + which are larger than ``max`` bytes. + + The ``max`` parameter is interpreted in the same way as the + ``--link-mtu`` parameter, i.e. the UDP packet size after encapsulation + overhead has been added in, but not including the UDP header itself. + + The ``--fragment`` option only makes sense when you are using the UDP + protocol (``--proto udp``). + + ``--fragment`` adds 4 bytes of overhead per datagram. + + See the ``--mssfix`` option below for an important related option to + ``--fragment``. + + 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. + + Having said that, there are circumstances where using OpenVPN's internal + fragmentation capability may be your only option, such as tunneling a + UDP multicast stream which requires fragmentation. + +--keepalive args + A helper directive designed to simplify the expression of ``--ping`` and + ``--ping-restart``. + + Valid syntax: + :: + + keepalive interval timeout + + 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 ``--ping`` + and ``--ping-restart`` options to the client. If used on both server and + client, the values pushed from server will override the client local + values. + + The ``timeout`` 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. + + For example, ``--keepalive 10 60`` expands as follows: + :: + + 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 + +--link-mtu n + Sets an upper bound on the size of UDP packets which are sent between + OpenVPN peers. *It's best not to set this parameter unless you know what + you're doing.* + +--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. + +--lport port + Set local TCP/UDP port number or name. Cannot be used together with + ``--nobind`` option. + +--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. + +--mode m + Set OpenVPN major mode. By default, OpenVPN runs in point-to-point mode + (:code:`p2p`). OpenVPN 2.0 introduces a new mode (:code:`server`) which + implements a multi-client server capability. + +--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 ``max`` bytes. The default value is :code:`1450`. + + The ``max`` parameter is interpreted in the same way as the + ``--link-mtu`` 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. + + The ``--mssfix`` option only makes sense when you are using the UDP + protocol for OpenVPN peer-to-peer communication, i.e. ``--proto udp``. + + ``--mssfix`` and ``--fragment`` can be ideally used together, where + ``--mssfix`` 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), ``--fragment`` will internally fragment them. + + Both ``--fragment`` and ``--mssfix`` are designed to work around cases + where Path MTU discovery is broken on the network path between OpenVPN + peers. + + The usual symptom of such a breakdown is an OpenVPN connection which + successfully starts, but then stalls during active usage. + + If ``--fragment`` and ``--mssfix`` are used together, ``--mssfix`` will + take its default ``max`` parameter from the ``--fragment max`` option. + + 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: + :: + + --tun-mtu 1500 --fragment 1300 --mssfix + +--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. + + Valid types: + + :code:`no` Never send DF (Don't Fragment) frames + + :code:`maybe` Use per-route hints + + :code:`yes` Always DF (Don't Fragment) + +--mtu-test + To empirically measure MTU on connection startup, add the ``--mtu-test`` + 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 ``--mtu-test`` process normally takes about 3 + minutes to complete. + +--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. + +--passtos + Set the TOS field of the tunnel packet to what the payload's TOS is. + +--ping n + Ping remote over the TCP/UDP control channel if no packets have been + sent for at least ``n`` seconds (specify ``--ping`` on both peers to + cause ping packets to be sent in both directions since OpenVPN ping + packets are not echoed like IP ping packets). When used in one of + OpenVPN's secure modes (where ``--secret``, ``--tls-server`` or + ``--tls-client`` is specified), the ping packet will be + cryptographically secure. + + This option has two intended uses: + + (1) 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. + + (2) To provide a basis for the remote to test the existence of its peer + using the ``--ping-exit`` option. + +--ping-exit n + Causes OpenVPN to exit after ``n`` seconds pass without reception of a + ping or other packet from remote. This option can be combined with + ``--inactive``, ``--ping`` and ``--ping-exit`` to create a two-tiered + inactivity disconnect. + + For example, + :: + + openvpn [options...] --inactive 3600 --ping 10 --ping-exit 60 + + 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. + +--ping-restart n + Similar to ``--ping-exit``, but trigger a :code:`SIGUSR1` restart after + ``n`` seconds pass without reception of a ping or other packet from + remote. + + 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 http://dyndns.org/ + a dynamic DNS client such as + ``ddclient``. + + If the peer cannot be reached, a restart will be triggered, causing the + hostname used with ``--remote`` to be re-resolved (if ``--resolv-retry`` + is also specified). + + In server mode, ``--ping-restart``, ``--inactive`` 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. + + In client mode, the ``--ping-restart`` 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 ``--keepalive`` setting in the + server configuration. To disable the 120 second default, set + ``--ping-restart 0`` on the client. + + See the signals section below for more information on :code:`SIGUSR1`. + + Note that the behavior of ``SIGUSR1`` can be modified by the + ``--persist-tun``, ``--persist-key``, ``--persist-local-ip`` and + ``--persist-remote-ip`` options. + + Also note that ``--ping-exit`` and ``--ping-restart`` are mutually + exclusive and cannot be used together. + +--ping-timer-rem + Run the ``--ping-exit`` / ``--ping-restart`` 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 ``--remote`` peer), and you don't want to + start clocking timeouts until a remote peer connects. + +--proto p + Use protocol ``p`` for communicating with remote host. ``p`` can be + :code:`udp`, :code:`tcp-client`, or :code:`tcp-server`. + + The default protocol is :code:`udp` when ``--proto`` is not specified. + + For UDP operation, ``--proto udp`` should be specified on both peers. + + For TCP operation, one peer must use ``--proto tcp-server`` and the + other must use ``--proto tcp-client``. A peer started with + :code:`tcp-server` will wait indefinitely for an incoming connection. A peer + started with :code:`tcp-client` will attempt to connect, and if that fails, + will sleep for 5 seconds (adjustable via the ``--connect-retry`` option) + and try again infinite or up to N retries (adjustable via the + ``--connect-retry-max`` option). Both TCP client and server will + simulate a SIGUSR1 restart signal if either side resets the connection. + + 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. + + This article outlines some of problems with tunneling IP over TCP: + http://sites.inka.de/sites/bigred/devel/tcp-tcp.html + + There are certain cases, however, where using TCP may be advantageous + from a security and robustness perspective, such as tunneling non-IP or + application-level UDP protocols, or tunneling protocols which don't + possess a built-in reliability layer. + +--port port + TCP/UDP port number or port name for both local and remote (sets both + ``--lport`` and ``--rport`` 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. + +--rport port + Set TCP/UDP port number or name used by the ``--remote`` option. The + port can also be set directly using the ``--remote`` option. + +--replay-window args + Modify the replay protection sliding-window size and time window. + + Valid syntax: + :: + + replay-window n [t] + + Use a replay protection sliding-window of size **n** and a time window + of **t** seconds. + + By default **n** is 64 (the IPSec default) and **t** is 15 seconds. + + This option is only relevant in UDP mode, i.e. when either **--proto + udp** is specified, or no **--proto** option is specified. + + 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. + + (a) The packet cannot be a replay (unless ``--no-replay`` is + specified, which disables replay protection altogether). + + (b) 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 ``n``. + + (c) If a packet arrives out of order, it will only be accepted if it + arrives no later than ``t`` seconds after any packet containing a higher + sequence number. + + 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 ``n``. Satellite links in particular often require this. + + If you run OpenVPN at ``--verb 4``, 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 + ``n``. + + There is some controversy on the appropriate method of handling packet + reordering at the security layer. + + 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? + + The IPSec and OpenVPN approach is to allow packet reordering within a + certain fixed sequence number window. + + OpenVPN adds to the IPSec model by limiting the window size in time as + well as sequence space. + + OpenVPN also adds TCP transport as an option (not offered by IPSec) in + which case OpenVPN can adopt a very strict attitude towards message + deletion and reordering: Don't allow it. Since TCP guarantees + reliability, any packet loss or reordering event can be assumed to be an + attack. + + 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. + + 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. + +--replay-persist file + Persist replay-protection state across sessions using ``file`` to save + and reload the state. + + This option will strengthen protection against replay attacks, + especially when you are using OpenVPN in a dynamic context (such as with + ``--inetd``) when OpenVPN sessions are frequently started and stopped. + + 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. + + This option only makes sense when replay protection is enabled (the + default) and you are using either ``--secret`` (shared-secret key mode) + or TLS mode with ``--tls-auth``. + +--socket-flags flags + Apply the given flags to the OpenVPN transport socket. Currently, only + :code:`TCP_NODELAY` is supported. + + The :code:`TCP_NODELAY` 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. + + This option is pushable from server to client, and should be used on + both client and server for maximum effect. + +--tcp-nodelay + This macro sets the :code:`TCP_NODELAY` socket flag on the server as well + as pushes it to connecting clients. The :code:`TCP_NODELAY` flag disables + the Nagle algorithm on TCP sockets causing packets to be transmitted + immediately with low latency, rather than waiting a short period of time + in order to aggregate several packets into a larger containing packet. + In VPN applications over TCP, :code:`TCP_NODELAY` is generally a good + latency optimization. + + The macro expands as follows: + :: + + if mode server: + socket-flags TCP_NODELAY + push "socket-flags TCP_NODELAY" diff --git a/doc/man-sections/log-options.rst b/doc/man-sections/log-options.rst new file mode 100644 index 0000000..e385d18 --- /dev/null +++ b/doc/man-sections/log-options.rst @@ -0,0 +1,73 @@ +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 + :code:`SIGHUP`, :code:`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 n + Log 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 :code:`1`). Each level shows all + info from the previous levels. Level :code:`3` is recommended if you want + a good summary of what's happening without being swamped by output. + + :code:`0` + No output except fatal errors. + + :code:`1` to :code:`4` + Normal usage range. + + :code:`5` + Outputs :code:`R` and :code:`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. + + :code:`6` to :code:`11` + Debug info range (see :code:`errlevel.h` in the source code for + additional information on debug levels). diff --git a/doc/man-sections/management-options.rst b/doc/man-sections/management-options.rst new file mode 100644 index 0000000..de0d47e --- /dev/null +++ b/doc/man-sections/management-options.rst @@ -0,0 +1,135 @@ +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 :code:`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 + :code:`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 :code:`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 :code:`nopadding` and :code:`pkcs1` signal + support for different padding algorithms. See + :code:`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 :code:`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 :code:`SIGTERM`. + +--management-up-down + Report tunnel up/down events to management interface. diff --git a/doc/man-sections/network-config.rst b/doc/man-sections/network-config.rst new file mode 100644 index 0000000..04b30aa --- /dev/null +++ b/doc/man-sections/network-config.rst @@ -0,0 +1,10 @@ +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). + +.. include:: link-options.rst +.. include:: vpn-network-options.rst +.. include:: virtual-routing-and-forwarding.rst diff --git a/doc/man-sections/pkcs11-options.rst b/doc/man-sections/pkcs11-options.rst new file mode 100644 index 0000000..c064aca --- /dev/null +++ b/doc/man-sections/pkcs11-options.rst @@ -0,0 +1,80 @@ +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 + :code:`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: + + :code:`0` (default) Try to determine automatically. + + :code:`1` Use sign. + + :code:`2` Use sign recover. + + :code:`4` Use decrypt. + + :code:`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 :code:`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 :code:`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 :code:`p11-kit-proxy.so` module will be + queried. + + ``--verb`` option can be used BEFORE this option to produce debugging + information. diff --git a/doc/man-sections/plugin-options.rst b/doc/man-sections/plugin-options.rst new file mode 100644 index 0000000..51c574f --- /dev/null +++ b/doc/man-sections/plugin-options.rst @@ -0,0 +1,57 @@ +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 + :code:`/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 (:code:`0`) in order for the + connection to be authenticated. diff --git a/doc/man-sections/protocol-options.rst b/doc/man-sections/protocol-options.rst new file mode 100644 index 0000000..e9d5d63 --- /dev/null +++ b/doc/man-sections/protocol-options.rst @@ -0,0 +1,281 @@ +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: + + :code:`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. + + :code:`no` + OpenVPN will refuse any non-stub compression. + + :code:`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 :code:`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 :code:`AES-256-GCM`. See ``--data-ciphers`` and + ``--ncp-disable`` for more details on NCP. + + Using :code:`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 :code:`BF-CBC`, :code:`DES`, + :code:`CAST5`, :code:`IDEA` and :code:`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 :code:`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 :code:`lzo`, :code:`lz4`, + :code:`lz4-v2`, :code:`stub`, :code:`stub-v2` or empty. + LZO and LZ4 are different compression algorithms, with LZ4 generally + offering the best performance with least CPU usage. + + The :code:`lz4-v2` and :code:`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 :code:`stub`, :code:`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, :code:`stub` and :code:`stub-v2` wil disable announcing + ``lzo`` and ``lz4`` compression support via *IV_* variables to the + server. + + Note: the :code:`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 :code:`yes`, :code:`no`, or :code:`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 + :code:`on`/:code:`off`/:code:`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 :code:`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 + :code:`AES-256-GCM` and :code:`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-disable + **DEPRECATED** 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 :code:`0` and the other + should use :code:`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 :code:`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. diff --git a/doc/man-sections/proxy-options.rst b/doc/man-sections/proxy-options.rst new file mode 100644 index 0000000..465bea0 --- /dev/null +++ b/doc/man-sections/proxy-options.rst @@ -0,0 +1,65 @@ +--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 :code:`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 :code:`none`, :code:`basic`, or :code:`ntlm`. + + HTTP Digest authentication is supported as well, but only via the + :code:`auto` or :code:`auto-nct` flags (below). This must replace + the ``authfile`` argument. + + The :code:`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. + + :code:`VERSION` ``version`` + Set HTTP version number to ``version`` (default :code:`1.0`). + + :code:`AGENT` ``user-agent`` + Set HTTP "User-Agent" string to ``user-agent``. + + :code:`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 :code:`1080`) and + ``authfile`` can be given. The ``authfile`` is a file containing a + username and password on 2 lines, or :code:`stdin` can be used to + prompt from console. diff --git a/doc/man-sections/renegotiation.rst b/doc/man-sections/renegotiation.rst new file mode 100644 index 0000000..c548440 --- /dev/null +++ b/doc/man-sections/renegotiation.rst @@ -0,0 +1,52 @@ +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 :code:`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 n + Renegotiate 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 :code:`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 :code:`3600` this results in an effective per + session value in the range of :code:`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 :code:`3600` seconds, + meaning that the renegotiation will still occur once per :code:`3600` + seconds. The solution is to increase --reneg-sec on both the client and + server, or set it to :code:`0` on one side of the connection (to + disable), and to your chosen value on the other side. diff --git a/doc/man-sections/script-options.rst b/doc/man-sections/script-options.rst new file mode 100644 index 0000000..03b3dd7 --- /dev/null +++ b/doc/man-sections/script-options.rst @@ -0,0 +1,841 @@ +SCRIPTING INTEGRATION +===================== + +OpenVPN can execute external scripts in various phases of the lifetime of +the OpenVPN process. + + +Script Order of Execution +------------------------- + +#. ``--up`` + + Executed after TCP/UDP socket bind and TUN/TAP open. + +#. ``--tls-verify`` + + Executed when we have a still untrusted remote peer. + +#. ``--ipchange`` + + Executed after connection authentication, or remote IP address change. + +#. ``--client-connect`` + + Executed in **--mode server** mode immediately after client + authentication. + +#. ``--route-up`` + + Executed after connection authentication, either immediately after, or + some number of seconds after as defined by the **--route-delay** option. + +#. ``--route-pre-down`` + + Executed right before the routes are removed. + +#. ``--client-disconnect`` + + Executed in ``--mode server`` mode on client instance shutdown. + +#. ``--down`` + + Executed after TCP/UDP and TUN/TAP close. + +#. ``--learn-address`` + + Executed in ``--mode server`` mode whenever an IPv4 address/route or MAC + address is added to OpenVPN's internal routing table. + +#. ``--auth-user-pass-verify`` + + Executed in ``--mode server`` mode on new client connections, when the + client is still untrusted. + +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 :code:`via-env`, OpenVPN will call ``script`` + with the environmental variables :code:`username` and :code:`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 :code:`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 + :code:`/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 (:code:`0`) if the client's authentication request is to be + accepted, or a failure code (: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 (':code:`_`'), dash (':code:`-`'), + dot (':code:`.`'), or at (':code:`@`'). The password string can consist + of any printable characters except for CR or LF. Any illegal characters + in either the username or password string will be converted to + underbar (':code:`_`'). + + 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 + :code:`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 + :code:`client_connect_deferred_file` and + :code:`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 not passed any extra arguments + (only those arguments specified in cmd, if any). + +--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-pre + Call ``--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 :code:`/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: + + :code:`$1` - [operation] + :code:`"add"`, :code:`"update"`, or :code:`"delete"` based on whether + or not the address is being added to, modified, or deleted from + OpenVPN's internal routing table. + + :code:`$2` - [address] + The address being learned or unlearned. This can be an IPv4 address + such as :code:`"198.162.10.14"`, an IPv4 subnet such as + :code:`"198.162.10.0/24"`, or an ethernet MAC address (when + ``--dev tap`` is being used) such as :code:`"00:FF:01:02:03:04"`. + + :code:`$3` - [common name] + The common name on the certificate associated with the client linked + to this address. Only present for :code:`"add"` or :code:`"update"` + operations, not :code:`"delete"`. + + On :code:`"add"` or :code:`"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 :code:`name=value` to pass to script. + + Valid syntaxes: + :: + + setenv name value + setenv FORWARD_COMPATIBLE 1 + setenv opt config_option + + By setting :code:`FORWARD_COMPATIBLE` to :code:`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 :code:`OPENVPN_name` to :code:`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 :code:`OPENVPN_` to the environmental variable is a + safety precaution to prevent a :code:`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 :code:`0` to allow the TLS handshake to proceed, + or :code:`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-restart + Enable 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 + :code:`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. + +:code:`bytes_received` + Total number of bytes received from client during VPN session. Set prior + to execution of the ``--client-disconnect`` script. + +:code:`bytes_sent` + Total number of bytes sent to client during VPN session. Set prior to + execution of the ``--client-disconnect`` script. + +:code:`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. + +:code:`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 :code:`1` + to indicate normal script execution, :code:`0` indicates an error (in + the same way that a non zero exit status does) or :code:`2` to indicate + that the script deferred returning the config file. + + For deferred (background) handling, the script or plugin MUST write + :code:`2` to the file to indicate the deferral and then return with + exit code :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 + :code:`client_connect_config_file` environment variable and when + finished, write the a :code:`1` to this file (or :code:`0` in case of + an error). + + The absence of any character in the file when the script finishes + executing is interpreted the same as :code:`1`. This allows scripts + that are not written to support the defer mechanism to be used + unmodified. + +:code:`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. + +:code:`config` + Name of first ``--config`` file. Set on program initiation and reset on + SIGHUP. + +:code:`daemon` + Set to "1" if the ``--daemon`` directive is specified, or "0" otherwise. + Set on program initiation and reset on SIGHUP. + +:code:`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. + +:code:`dev` + The actual name of the TUN/TAP device, including a unit number if it + exists. Set prior to ``--up`` or ``--down`` script execution. + +:code:`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. + +:code:`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. + +:code:`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 :code:`ifconfig` or :code:`netsh` (windows version + of ifconfig) commands which normally occurs prior to ``--up`` script + execution. + +:code:`ifconfig_ipv6_local` + The local VPN endpoint IPv6 address specified in the + ``--ifconfig-ipv6`` option (first parameter). Set prior to OpenVPN + calling the :code:`ifconfig` or code:`netsh` (windows version of + ifconfig) commands which normally occurs prior to ``--up`` script + execution. + +:code:`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 + :code:`ifconfig` or :code:`netsh` (windows version of ifconfig) + commands which normally occurs prior to ``--up`` script execution. + +:code:`ifconfig_ipv6_remote` + The remote VPN endpoint IPv6 address specified in the + ``--ifconfig-ipv6`` option (second parameter). Set prior to OpenVPN + calling the :code:`ifconfig` or :code:`netsh` (windows version of + ifconfig) commands which normally occurs prior to ``--up`` script + execution. + +:code:`ifconfig_local` + The local VPN endpoint IP address specified in the ``--ifconfig`` + option (first parameter). Set prior to OpenVPN calling the + :code:`ifconfig` or :code:`netsh` (windows version of ifconfig) + commands which normally occurs prior to ``--up`` script execution. + +:code:`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 :code:`ifconfig` or :code:`netsh` (windows version + of ifconfig) commands which normally occurs prior to ``--up`` script + execution. + +:code:`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 :code:`ifconfig` or + :code:`netsh` (windows version of ifconfig) commands which normally + occurs prior to ``--up`` script execution. + +:code:`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. + +:code:`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. + +:code:`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. + +:code:`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. + +:code:`local` + The ``--local`` parameter. Set on program initiation and reset on + SIGHUP. + +:code:`local_port` + The local port number or name, specified by ``--port`` or ``--lport``. + Set on program initiation and reset on SIGHUP. + +:code:`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. + +:code:`proto` + The ``--proto`` parameter. Set on program initiation and reset on + SIGHUP. + +:code:`remote_{n}` + The ``--remote`` parameter. Set on program initiation and reset on + SIGHUP. + +:code:`remote_port_{n}` + The remote port number, specified by ``--port`` or ``--rport``. Set on + program initiation and reset on SIGHUP. + +:code:`route_net_gateway` + The pre-existing default IP gateway in the system routing table. Set + prior to ``--up`` script execution. + +:code:`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. + +:code:`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 :code:`network`, :code:`netmask"`, + :code:`gateway`, or :code:`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. + +:code:`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 :code:`network`, :code:`gateway` or + :code:`metric`. ``route_ipv6_network_{n}`` contains :code:`netmask` + as :code:`/nnn`, 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. + +:code:`peer_cert` + Temporary file name containing the client certificate upon connection. + Useful in conjunction with ``--tls-verify``. + +:code:`script_context` + Set to "init" or "restart" prior to up/down script execution. For more + information, see documentation for ``--up``. + +:code:`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: :code:`up`, + :code:`down`, :code:`ipchange`, :code:`route-up`, :code:`tls-verify`, + :code:`auth-user-pass-verify`, :code:`client-connect`, + :code:`client-disconnect` or :code:`learn-address`. Set prior to + execution of any script. + +:code:`signal` + The reason for exit or restart. Can be one of :code:`sigusr1`, + :code:`sighup`, :code:`sigterm`, :code:`sigint`, :code:`inactive` + (controlled by ``--inactive`` option), :code:`ping-exit` (controlled + by ``--ping-exit`` option), :code:`ping-restart` (controlled by + ``--ping-restart`` option), :code:`connection-reset` (triggered on TCP + connection reset), :code:`error` or :code:`unknown` (unknown signal). + This variable is set just prior to down script execution. + +:code:`time_ascii` + Client connection timestamp, formatted as a human-readable time string. + Set prior to execution of the ``--client-connect`` script. + +:code:`time_duration` + The duration (in seconds) of the client session which is now + disconnecting. Set prior to execution of the ``--client-disconnect`` + script. + +:code:`time_unix` + Client connection timestamp, formatted as a unix integer date/time + value. Set prior to execution of the ``--client-connect`` script. + +:code:`tls_digest_{n}` / :code:`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. + +:code:`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. + +:code:`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 + :code:`contrib/OCSP_check/OCSP_check.sh` script for an example. + +:code:`tls_serial_hex_{n}` + Like :code:`tls_serial_{n}`, but in hex form (e.g. + :code:`12:34:56:78:9A`). + +:code:`tun_mtu` + The MTU of the TUN/TAP device. Set prior to ``--up`` or ``--down`` + script execution. + +:code:`trusted_ip` / :code:`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), :code:`trusted_ip6` will be set instead. + +:code:`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. + +:code:`untrusted_ip` / :code:`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), :code:`untrusted_ip6` + will be set instead. + +:code:`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. + +:code:`username` + The username provided by a connecting client. Set prior to + ``--auth-user-pass-verify`` script execution only when the + :code:`via-env` modifier is specified. + +:code:`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 + :code:`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 ":code:`_`"). 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 diff --git a/doc/man-sections/server-options.rst b/doc/man-sections/server-options.rst new file mode 100644 index 0000000..ac0df55 --- /dev/null +++ b/doc/man-sections/server-options.rst @@ -0,0 +1,812 @@ +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 :code:`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 :code:`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: + + :code:`Initial` + No token from client. + + :code:`Authenticated` + Token is valid and not expired. + + :code:`Expired` + Token is valid but has expired. + + :code:`Invalid` + Token is invalid (failed HMAC or wrong length) + + :code:`AuthenticatedEmptyUser` / :code:`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 :code:`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-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. + +--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. If the host part of the given IPv6 + address is ``0``, the pool starts at ``ipv6addr`` +1. + +--ifconfig-pool-persist args + Persist/unpersist ifconfig-pool data to ``file``, at ``seconds`` + intervals (default :code:`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 + :code:`<Common-Name>,<IP-address>`. + + If ``seconds`` = :code:`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. Use ``--client-config-dir`` file for static IP (next choice). + + 3. Use ``--ifconfig-pool`` allocation for dynamic IP (last + choice). + +--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 :code:`wait` and :code:`nowait` option must match what is specified + in the inetd/xinetd config file. The :code:`nowait` mode can only be used + with ``--proto tcp-server`` The default is :code:`wait`. The + :code:`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 :code:`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 + :code:`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 (:code:`""`). 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: + + :code:`IV_VER=<version>` + The client OpenVPN version + + :code:`IV_PLAT=[linux|solaris|openbsd|mac|netbsd|freebsd|win]` + The client OS platform + + :code:`IV_LZO_STUB=1` + If client was built with LZO stub capability + + :code:`IV_LZ4=1` + If the client supports LZ4 compressions. + + :code:`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. + + :code:`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*. + + :code:`IV_CIPHERS=<ncp-ciphers>` + The client announces the list of supported ciphers configured with the + ``--data-ciphers`` option to the server. + + :code:`IV_GUI_VER=<gui_id> <version>` + The UI version of a UI if one is running, for example + :code:`de.blinkt.openvpn 0.5.47` for the Android app. + + :code:`IV_SSO=[crtext,][openurl,][proxy_url]` + Additional authentication methods supported by the client. + This may be set by the client UI/GUI using ``--setenv`` + + When ``--push-peer-info`` is enabled the additional information consists + of the following data: + + :code:`IV_HWADDR=<string>` + This is intended to be a unique and persistent ID of the client. + The string value can be any readable ASCII string up to 64 bytes. + OpenVPN 2.x and some other implementations use the MAC address of + the client's interface used to reach the default gateway. If this + string is generated by the client, it should be consistent and + preserved across independent session and preferably + re-installations and upgrades. + + :code:`IV_SSL=<version string>` + The ssl version used by the client, e.g. + :code:`OpenSSL 1.0.2f 28 Jan 2016`. + + :code:`IV_PLAT_VER=x.y` + The version of the operating system, e.g. 6.1 for Windows 7. + + :code:`UV_<name>=<value>` + Client environment variables whose names start with + :code:`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 :code:`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 ( + :code:`push-remove ifconfig`), no substring matching and no matching on + the IPv4/IPv6 address argument is possible. + +--push-reset + Don'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. + + *NOTE*: ``--push-reset`` is very thorough: it will remove almost + all options from the list of to-be-pushed options. In many cases, + some of these options will need to be re-configured afterwards - + specifically, ``--topology subnet`` and ``--route-gateway`` will get + lost and this will break client configs in many cases. Thus, for most + purposes, ``--push-remove`` is better suited to selectively remove + push options for individual clients. + +--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 :code:`.1` address of the given network for + use as the server-side endpoint of the local TUN/TAP interface. If the + optional :code:`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 :code:`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 :code:`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 + +--server-ipv6 args + Convenience-function to enable a number of IPv6 related options at once, + namely ``--ifconfig-ipv6``, ``--ifconfig-ipv6-pool`` and + ``--push tun-ipv6``. + + Valid syntax: + :: + + server-ipv6 ipv6addr/bits + + Pushing of the ``--tun-ipv6`` directive is done for older clients which + require an explicit ``--tun-ipv6`` in their configuration. + +--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 + Use the authenticated username as the common-name, rather than the + common-name from the client certificate. Requires that some form of + ``--auth-user-pass`` verification is in effect. As the replacement happens + after ``--auth-user-pass`` verification, the verification script or + plugin will still receive the common-name from the certificate. + + The common_name environment variable passed to scripts and plugins invoked + after authentication (e.g, client-connect script) and file names parsed in + client-config directory will match the username. + +--verify-client-cert mode + Specify whether the client is required to supply a valid certificate. + + Possible ``mode`` options are: + + :code:`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``. + + :code:`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. + + :code:`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: + + :code:`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. + + :code:`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. + + :code:`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 :code:`tagged` mode + as "trunk ports" and switch ports running in :code:`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 :code:`1` through to :code:`4094`. The + global value defaults to :code:`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". diff --git a/doc/man-sections/signals.rst b/doc/man-sections/signals.rst new file mode 100644 index 0000000..63611b3 --- /dev/null +++ b/doc/man-sections/signals.rst @@ -0,0 +1,30 @@ +SIGNALS +======= + +:code:`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. + +:code:`SIGUSR1` + Like :code:`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. + +:code:`SIGUSR2` + Causes OpenVPN to display its current statistics (to the syslog file if + ``--daemon`` is used, or stdout otherwise). + +:code:`SIGINT`, :code:`SIGTERM` + Causes OpenVPN to exit gracefully. diff --git a/doc/man-sections/tls-options.rst b/doc/man-sections/tls-options.rst new file mode 100644 index 0000000..f0b6d3d --- /dev/null +++ b/doc/man-sections/tls-options.rst @@ -0,0 +1,668 @@ +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 + :code:`/usr/share/ssl/openssl.cnf` -- note also that for certificate + authority functions, you must set up the files :code:`index.txt` (may be + empty) and :code:`serial` (initialize to :code:`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 :code:`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 :code:`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 :code:`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 file + Local 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 file + Specify 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 :code:`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 :code:`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: + + :code:`legacy` (default) + SHA1 and newer, RSA 2048-bit+, any elliptic curve. + + :code:`preferred` + SHA2 and newer, RSA 2048-bit+, any elliptic curve. + + :code:`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: + + :code:`legacy` (default) + sets "security level 1" + + :code:`preferred` + sets "security level 2" + + :code:`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 (":code:`:`"). + + 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 + :code:`DEFAULT:!EXP:!LOW:!MEDIUM:!kDH:!kECDH:!DSS:!PSK:!SRP:!kRSA` when + using OpenSSL. + +--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. + + The default for `--tls-ciphersuites` is to use the crypto library's + default. + +--tls-client + Enable 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 :code:`--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 :code:`--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: + + * :code:`script_type` is set to :code:`tls-crypt-v2-verify` + + * :code:`metadata_type` is set to :code:`0` if the metadata was user + supplied, or :code:`1` if it's a 64-bit unix timestamp representing + the key creation time. + + * :code:`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-exit + Exit 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-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. + +--tls-timeout n + Packet retransmit timeout on TLS control channel if no acknowledgment + from remote within ``n`` seconds (default :code:`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 :code:`1.0`, :code:`1.1`, or :code:`1.2`. If + :code:`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 :code:`1.0`, :code:`1.1`, or + :code:`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 :code:`SHA1` or :code:`SHA256`. If not + provided, it defaults to :code:`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 :code:`subject` to match the complete subject DN + (default), :code:`name` to match a subject RDN or :code:`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 :code:`Server-1`, :code:`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 :code:`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 :code:`+` to ``attribute`` to save values + from full cert chain. Values will be encoded as + :code:`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 :code:`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 :code:`emailAddress` attribute + in the certificate's Subject field as the username. The second example + uses the :code:`ext:` prefix to signify that the X.509 extension + ``fieldname`` :code:`subjectAltName` be searched for an rfc822Name + (email) field to be used as the username. In cases where there are + multiple email addresses in :code:`ext:fieldname`, 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 :code:`subjectAltName` and :code:`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., + :code:`ou` -> :code:`OU`. A mixed-case ``fieldname`` or one having the + :code:`ext:` prefix will be left as-is. This automatic upcasing feature is + deprecated and will be removed in a future release. diff --git a/doc/man-sections/unsupported-options.rst b/doc/man-sections/unsupported-options.rst new file mode 100644 index 0000000..05ba3ca --- /dev/null +++ b/doc/man-sections/unsupported-options.rst @@ -0,0 +1,32 @@ + +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-method + Removed 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-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. + +--no-replay + Removed in OpenVPN 2.5. This option should not be used as it weakens the + VPN tunnel security. + +--ns-cert-type + Removed 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. diff --git a/doc/man-sections/virtual-routing-and-forwarding.rst b/doc/man-sections/virtual-routing-and-forwarding.rst new file mode 100644 index 0000000..28c13ee --- /dev/null +++ b/doc/man-sections/virtual-routing-and-forwarding.rst @@ -0,0 +1,78 @@ +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 :code:`ip link set` command shown +below. + + +VRF setup with iproute2 +``````````````````````` + +Create VRF :code:`vrf_external` and map it to routing table :code:`1023` +:: + + ip link add vrf_external type vrf table 1023 + +Move :code:`eth0` into :code:`vrf_external` +:: + + ip link set master vrf_external dev eth0 + +Any prefixes configured on :code:`eth0` will be moved from the :code`main` +routing table into routing table `1023` + + +VRF setup with ifupdown +``````````````````````` + +For Debian based Distributions :code:`ifupdown2` provides an almost drop-in +replacement for :code:`ifupdown` including VRFs and other features. +A configuration for an interface :code:`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 + + - Slides: https://www.slideshare.net/BarbarossaTM/l2l3-fr-fortgeschrittene-helle-und-dunkle-magie-im-linuxnetzwerkstack + - Video (german): https://media.ccc.de/v/froscon2018-2247-l2\_l3\_fur\_fortgeschrittene\_-\_helle\_und\_dunkle\_magie\_im\_linux-netzwerkstack diff --git a/doc/man-sections/vpn-network-options.rst b/doc/man-sections/vpn-network-options.rst new file mode 100644 index 0000000..029834a --- /dev/null +++ b/doc/man-sections/vpn-network-options.rst @@ -0,0 +1,556 @@ +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 :code:`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 (to avoid IPv6 connections from dual-stacked + clients leaking around IPv4-only VPN services). + + **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 + + Note: this option does not influence traffic sent from the server + towards the client (neither on the server nor on the client side). + This is not seen as necessary, as such traffic can be most easily + avoided by not configuring IPv6 on the server tun, or setting up a + server-side firewall rule. + +--dev device + TUN/TAP virtual network device which can be :code:`tunX`, :code:`tapX`, + :code:`null` or an arbitrary name string (:code:`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: + + :code:`tun` + devices encapsulate IPv4 or IPv6 (OSI Layer 3) + + :code:`tap` + devices encapsulate Ethernet 802.3 (OSI Layer 2). + + Valid syntaxes: + :: + + dev tun2 + dev tap4 + dev ovpn + + When the device name starts with :code:`tun` or :code:`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 :code:`/dev/net/tun`, + :code:`/dev/tun`, :code:`/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 :code:`tun.kext` (:code:`/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 :code:`tun` + (OSI Layer 3) or :code:`tap` (OSI Layer 2). Use this option only if + the TUN/TAP device used with ``--dev`` does not begin with :code:`tun` + or :code:`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 :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: + :: + + dhcp-options type [parm] + + :code:`DOMAIN` ``name`` + Set Connection-specific DNS Suffix to :code:`name`. + + :code:`ADAPTER_DOMAIN_SUFFIX` ``name`` + Alias to :code:`DOMAIN`. This is a compatibility option, it + should not be used in new deployments. + + :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. + + 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. + + :code:`WINS` ``address`` + Set primary WINS server address (NetBIOS over TCP/IP Name Server). + Repeat this option to set secondary WINS server addresses. + + :code:`NBDD` ``address`` + Set primary NBDD server address (NetBIOS over TCP/IP Datagram + Distribution Server). Repeat this option to set secondary NBDD + server addresses. + + :code:`NTP` ``address`` + Set primary NTP server address (Network Time Protocol). + Repeat this option to set secondary NTP server addresses. + + :code:`NBT` ``type`` + Set NetBIOS over TCP/IP Node type. Possible options: + + :code:`1` + b-node (broadcasts) + + :code:`2` + p-node (point-to-point name queries to a WINS server) + + :code:`4` + m-node (broadcast then query name server) + + :code:`8` + h-node (query name server, then broadcast). + + :code:`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) + + :code:`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 + :code:`SIGUSR1` or ``--ping-restart`` restarts. + + :code:`SIGUSR1` is a restart signal similar to :code:`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) Delete the default gateway route. + + (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). + + When the tunnel is torn down, all of the above steps are reversed so + that the original default route is restored. + + Option flags: + + :code:`local` + Add the :code:`local` flag if both OpenVPN peers are directly + connected via a common subnet, such as with wireless. The + :code:`local` flag will cause step ``(1)`` above to be omitted. + + :code:`autolocal` + Try to automatically determine whether to enable :code:`local` + flag above. + + :code:`def1` + Use this flag to override the default gateway by using + :code:`0.0.0.0/1` and :code:`128.0.0.0/1` rather than + :code:`0.0.0.0/0`. This has the benefit of overriding but not + wiping out the original default gateway. + + :code:`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). + + :code:`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). + + :code:`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. + + :code:`ipv6` + Redirect IPv6 routing into the tunnel. This works similar to + the :code:`def1` flag, that is, more specific IPv6 routes are added + (:code:`2000::/4`, :code:`3000::/4`), covering the whole IPv6 + unicast space. + + :code:`!ipv4` + Do not redirect IPv4 traffic - typically used in the flag pair + :code:`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 :code:`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 :code:`0`. + + The default can be specified by leaving an option blank or setting it to + :code:`default`. + + The ``network`` and ``gateway`` parameters can also be specified as a + DNS or :code:`/etc/hosts` file resolvable name, or as one of three special + keywords: + + :code:`vpn_gateway` + The remote VPN endpoint address (derived either from + ``--route-gateway`` or the second parameter to ``--ifconfig`` + when ``--dev tun`` is specified). + + :code:`net_gateway` + The pre-existing IP default gateway, read from the + routing table (not supported on all OSes). + + :code:`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 :code:`0`) after connection establishment, + before adding routes. If ``n`` is :code:`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 :code:`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 :code:`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-noexec + Don'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 :code:`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: + + :code:`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. + + :code:`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. + + :code:`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 :code:`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. diff --git a/doc/man-sections/windows-options.rst b/doc/man-sections/windows-options.rst new file mode 100644 index 0000000..eacb9af --- /dev/null +++ b/doc/man-sections/windows-options.rst @@ -0,0 +1,244 @@ +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-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. + +--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. + +--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``. + + :code:`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. + + :code:`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) OpenVPN needs to claim an IP address in the subnet for use + as the virtual DHCP server address. + + By default in ``--dev tap`` mode, OpenVPN will take the normally + unused first address in the subnet. For example, if your subnet is + :code:`192.168.4.0 netmask 255.255.255.0`, then OpenVPN will take + the IP address :code:`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 > :code:`-256` + and < :code:`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 :code:`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. + + :code:`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. + + :code:`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." + + :code:`adaptive` (Default) + Try :code:`dynamic` method initially and fail over to :code:`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 :code:`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 :code:`adaptive` mode to use + :code:`netsh` immediately, rather than trying :code:`dynamic` first. + + To "unstick" the :code:`adaptive` mode from using :code:`netsh`, + run OpenVPN at least once using the :code:`dynamic` mode to restore + the TAP-Win32 adapter TCP/IP properties to a DHCP configuration. + +--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. + +--register-dns + Run :code:`ipconfig /flushdns` and :code:`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? + + :code:`adaptive` (default) + Try IP helper API first. If that fails, fall back to the route.exe + shell command. + + :code:`ipapi` + Use IP helper API. + + :code:`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-up + Output OpenVPN's view of the system routing table and network adapter + list to the syslog or log file after the TUN/TAP adapter has been + brought up and any routes have been added. + +--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 :code:`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 :code:`tap-windows6` + (default) and :code:`wintun`. This is a Windows-only option. + :code:`wintun`" requires ``--dev tun`` and the OpenVPN process to run + elevated, or be invoked using the Interactive Service. diff --git a/doc/management-notes.txt b/doc/management-notes.txt index 96a0d7d..c203442 100644 --- a/doc/management-notes.txt +++ b/doc/management-notes.txt @@ -137,6 +137,16 @@ history while simultaneously activating real-time updates: The size of the echo buffer is currently hardcoded to 100 messages. + +Generally speaking, the OpenVPN Core does not understand echo +messages at all (so a cooperating GUI and Server can use this +mechanism for arbitrary information transport). + +This said, a few echo commands have been agreed upon between the +community maintained OpenVPN Windows GUI and Tunnelblick for MacOS, +and documentation of these can be found in doc/gui-notes.txt. + + COMMAND -- exit, quit --------------------- @@ -189,7 +199,7 @@ Command examples: COMMAND -- kill --------------- -In server mode, kill a particlar client instance. +In server mode, kill a particular client instance. Command examples: @@ -397,6 +407,7 @@ RECONNECTING -- A restart has occurred. EXITING -- A graceful exit is in progress. RESOLVE -- (Client only) DNS lookup TCP_CONNECT -- (Client only) Connecting to TCP server +AUTH_PENDING -- (Client only) Authentication pending Command examples: @@ -427,6 +438,11 @@ Fields (e)-(h) are shown for CONNECTED state, (e) is available starting from OpenVPN 2.1 (f)-(i) are available starting from OpenVPN 2.4 +For AUTH_PENDING, if (c) is present, it would read +as "timeout number" where number is the number of seconds +before authentication will timeout. It is printed as an +unsigned integer (%u). + Real-time state notifications will have a ">STATE:" prefix prepended to them. @@ -465,8 +481,12 @@ Command examples: COMMAND -- version ------------------ -Show the current OpenVPN and Management Interface versions. +Set the version (integer) of Management Interface supported by the +client or show the current OpenVPN and Management Interface versions. +Command examples: + version 2 -- Change management version of client to 2 (default = 1) + version -- Show the version of OpenVPN and its Management Interface COMMAND -- auth-retry --------------------- @@ -588,6 +608,127 @@ interface to approve client connections. CID,KID -- client ID and Key ID. See documentation for ">CLIENT:" notification for more info. +COMMAND -- client-pending-auth (OpenVPN 2.5 or higher) +---------------------------------------------------- + +Instruct OpenVPN server to send AUTH_PENDING and INFO_PRE message +to signal a pending authenticating to the client. A pending auth means +that the connecting requires extra authentication like a one time +password or doing a single sign on via web. + + client-pending-auth {CID} {EXTRA} {TIMEOUT} + +The server will send AUTH_PENDING and INFO_PRE,{EXTRA} to the client. If the +client supports accepting keywords to AUTH_PENDING (announced via IV_PROTO), +TIMEOUT parameter will be also be announced to the client to allow it to modify +its own timeout. The client is expected to inform the user that authentication +is pending and display the extra information and also show the user the +remaining time to complete the auth if applicable. + +Receiving an AUTH_PENDING message will make the client change its timeout to +the timeout proposed by the server, even if the timeout is shorter. +If the client does not receive a packet from the server for hand-window the +connection times out regardless of the timeout. This ensures that the connection +still times out relatively quickly in case of network problems. The client will +continuously send PULL_REQUEST messages to the server until the timeout is reached. +This message also triggers an ACK message from the server that resets the +hand-window based timeout. + +Both client and server limit the maximum timeout to the smaller value of half the +--tls-reneg minimum time and --hand-window time (defaults to 60s). + +For the format of {EXTRA} see below. For OpenVPN server this is a stateless +operation and needs to be followed by a client-deny/client-auth[-nt] command +(that is the result of the out of band authentication). + +Before issuing a client-pending-auth to a client instead of a +client-auth/client-deny, the server should check the IV_SSO +environment variable for whether the method is supported. Currently +defined methods are crtext for challenge/response using text +(e.g., TOTP), openurl and proxy_url for opening a URL in the client to +continue authentication. A client supporting the first two methods would +set + + setenv IV_SSO openurl,crtext + +The variable name IV_SSO is historic as AUTH_PENDING was first used +to signal single sign on support. To keep compatibility with existing +implementations the name IV_SSO is kept in lieu of a better name. + +The management interface of the client receives notification of +pending auth via + +>STATE:datetime,AUTH_PENDING,[timeout number] + +If {EXTRA} is present the client is informed using INFOMSG +notification as + +>INFOMSG:{EXTRA} + +where {EXTRA} is formatted as received from the server. +Currently defined formats for {EXTRA} are detailed below. + +openurl +======== +For a web based extra authentication (like for +SSO/SAML) {EXTRA} should be + + OPEN_URL:url + +and client should ask the user to open the URL to continue. + +The space in a control message is limited, so this url should be kept +short to avoid issues. If a longer url is required a URL that redirects +to the longer URL should be sent instead. + +A complete documentation how URLs should be handled on the client is available +in the openvpn3 repository: + +https://github.com/OpenVPN/openvpn3/blob/master/doc/webauth.md + +proxy_url +======== +This is a variant of openurl that allows opening a url via an +HTTP proxy. It could be used to avoid issues with OpenVPN connection's +persist-tun that may cause the web server to be unreachable. +The client should announce proxy_url in its IV_SSO and parse the +PROXY_URL message. The format of {EXTRA} in this case is + + PROXY_URL:<proxy>:<proxy_port>:<proxyuser_base64>:<proxy_password_base64>:url + +The proxy should be a literal IPv4 address or IPv6 address enclosed in [] to avoid +ambiguity in parsing. A literal IP address is preferred as DNS might not be +available when the client needs to open the url. The IP address will usually +be the address that client uses to connect to the VPN server. For dual-homed +VPN servers, the server should respond with the same address that the client +connects to. + +This address is also usually excluded from being redirected over the VPN +by a host route. If the platform (like Android) uses another way of protecting +the VPN connection from routing loops, the client needs to also exclude the +connection to the proxy in the same manner. + +Should another IP be used, then the VPN configuration should include a route +statement to exclude that address from being routed over the VPN. + +crtext +======= +The format of {EXTRA} is similar to the already used two step authentication +described in Challenge/Response Protocol section of this document. Since +most of the fields are not necessary or can be inferred, only the <flags> +and <challenge_text> fields are used: + + CR_TEXT:<flags>:<challenge_text> + +<flags>: a series of optional, comma-separated flags: + E : echo the response when the user types it. + R : a response is required. + +<challenge_text>: the challenge text to be shown to the user. + +The client should return the response to the crtext challenge +using the cr-response command. + COMMAND -- client-deny (OpenVPN 2.1 or higher) ----------------------------------------------- @@ -802,34 +943,70 @@ To accept connecting to the host and port directly, use this command: proxy NONE -COMMAND -- rsa-sig (OpenVPN 2.3 or higher) ------------------------------------------- +COMMAND -- cr-response (OpenVPN 2.5 or higher) +------------------------------------------------- +Provides support for sending responses to a challenge/response +query via INFOMSG,CR_TEXT (client-only). The response should +be base64 encoded: + + cr-response SGFsbG8gV2VsdCE= + +This command is intended to be used after the client receives a +CR_TEXT challenge (see client-pending-auth section). The argument +to cr-response is the base64 encoded answer to the challenge and +depends on the challenge itself. For a TOTP challenge this would be +a number encoded as base64; for a challenge like "what day is it today?" +it would be a string encoded as base64. + +COMMAND -- pk-sig (OpenVPN 2.5 or higher, management version > 1) +COMMAND -- rsa-sig (OpenVPN 2.3 or higher, management version <= 1) +----------------------------------------------------------------- Provides support for external storage of the private key. Requires the --management-external-key option. This option can be used instead of "key" in client mode, and allows the client to run without the need to load the -actual private key. When the SSL protocol needs to perform an RSA sign +actual private key. When the SSL protocol needs to perform a sign operation, the data to be signed will be sent to the management interface via a notification as follows: ->RSA_SIGN:[BASE64_DATA] +>PK_SIGN:[BASE64_DATA],[ALG] (if client announces support for management version > 2) +>PK_SIGN:[BASE64_DATA] (if client announces support for management version > 1) +>RSA_SIGN:[BASE64_DATA] (only older clients will be prompted like this) -The management interface client should then create a PKCS#1 v1.5 signature of +The management interface client should then create an appropriate signature of the (decoded) BASE64_DATA using the private key and return the SSL signature as follows: -rsa-sig +pk-sig (or rsa-sig) [BASE64_SIG_LINE] . . . END -Base64 encoded output of RSA_private_encrypt() (OpenSSL) or mbedtls_pk_sign() -(mbed TLS) will provide a correct signature. +Base 64 encoded output of RSA_private_encrypt for RSA or ECDSA_sign() +for EC using OpenSSL or mbedtls_pk_sign() using mbed TLS will provide a +correct signature. +The rsa-sig interface expects PKCS1 padded signatures for RSA keys +(RSA_PKCS1_PADDING). EC signatures are always unpadded. This capability is intended to allow the use of arbitrary cryptographic service providers with OpenVPN via the management interface. +New and updated clients are expected to use the version command to announce +a version > 1 and handle '>PK_SIGN' prompt and respond with 'pk-sig'. + +The signature algorithm is indicated in the PK_SIGN request only if the +management client-version is > 2. In particular, to support TLS1.3 and +TLS1.2 using OpenSSL 1.1.1, unpadded signature support is required and this +can be indicated in the signing request only if the client version is > 2" + +The currently defined padding algorithms are: + + - RSA_PKCS1_PADDING - PKCS1 padding and RSA signature + - RSA_NO_PADDING - No padding may be added for the signature + - ECDSA - EC signature. + + COMMAND -- certificate (OpenVPN 2.4 or higher) ---------------------------------------------- Provides support for external storage of the certificate. Requires the @@ -920,6 +1097,9 @@ PASSWORD -- Used to tell the management interface client that OpenVPN STATE -- Shows the current OpenVPN state, as controlled by the "state" command. +INFOMSG -- Authentication related info from server such as + CR_TEXT or OPEN_URL. See description under client-pending-auth + The CLIENT notification ----------------------- @@ -969,6 +1149,35 @@ CLIENT notification types: >CLIENT:ADDRESS,{CID},{ADDR},{PRI} +(5) Text based challenge/Response + + >CLIENT:CR_RESPONSE,{CID},{KID},{response_base64} + >CLIENT:ENV,name1=val1 + >CLIENT:ENV,name2=val2 + >CLIENT:ENV,... + >CLIENT:ENV,END + + Use of the cr-response command on the client side will trigger this + message on the server side. + + CR_RESPONSE notification fulfills the same purpose as the + CRV1 response in the traditional challenge/response. See that section + below for more details. Since this uses the same cid as in the original + client-pending-auth challenge, we do not include the username and opaque + session data in this notification. The string {response_base64} only contains + the actual response received from the client. + + It is important to note that OpenVPN2 merely passes the authentication + information and does not do any further checks. (E.g. if a CR was issued + before or if multiple CR responses were sent from the client or if + data has a valid base64 encoding) + + This interface should be be sufficient for almost all challenge/response + system that can be implemented with a single round and base64 encoding of the + response. Mechanisms that need multiple rounds or more complex answers + should implement a different response type than CR_RESPONSE. + + Variables: CID -- Client ID, numerical ID for each connecting client, sequence = 0,1,2,... diff --git a/doc/openvpn-examples.5 b/doc/openvpn-examples.5 new file mode 100644 index 0000000..c9d5488 --- /dev/null +++ b/doc/openvpn-examples.5 @@ -0,0 +1,374 @@ +.\" Man page generated from reStructuredText. +. +.TH OPENVPN EXAMPLES 5 "" "" "Configuration files" +.SH NAME +openvpn examples \- Secure IP tunnel daemon +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.SH INTRODUCTION +.sp +This man page gives a few simple examples to create OpenVPN setups and configuration files. +.SH EXAMPLES +.sp +Prior to running these examples, you should have OpenVPN installed on +two machines with network connectivity between them. If you have not yet +installed OpenVPN, consult the INSTALL file included in the OpenVPN +distribution. +.SS Firewall Setup: +.sp +If firewalls exist between the two machines, they should be set to +forward the port OpenVPN is configured to use, in both directions. +The default for OpenVPN is 1194/udp. If you do not have control +over the firewalls between the two machines, you may still be able to +use OpenVPN by adding \fB\-\-ping 15\fP to each of the \fBopenvpn\fP commands +used below in the examples (this will cause each peer to send out a UDP +ping to its remote peer once every 15 seconds which will cause many +stateful firewalls to forward packets in both directions without an +explicit firewall rule). +.sp +Please see your operating system guides for how to configure the firewall +on your systems. +.SS VPN Address Setup: +.sp +For purposes of our example, our two machines will be called +\fBbob.example.com\fP and \fBalice.example.com\fP\&. If you are constructing a +VPN over the internet, then replace \fBbob.example.com\fP and +\fBalice.example.com\fP with the internet hostname or IP address that each +machine will use to contact the other over the internet. +.sp +Now we will choose the tunnel endpoints. Tunnel endpoints are private IP +addresses that only have meaning in the context of the VPN. Each machine +will use the tunnel endpoint of the other machine to access it over the +VPN. In our example, the tunnel endpoint for bob.example.com will be +10.4.0.1 and for alice.example.com, 10.4.0.2. +.sp +Once the VPN is established, you have essentially created a secure +alternate path between the two hosts which is addressed by using the +tunnel endpoints. You can control which network traffic passes between +the hosts (a) over the VPN or (b) independently of the VPN, by choosing +whether to use (a) the VPN endpoint address or (b) the public internet +address, to access the remote host. For example if you are on +bob.example.com and you wish to connect to \fBalice.example.com\fP via +\fBssh\fP without using the VPN (since \fBssh\fP has its own built\-in security) +you would use the command \fBssh alice.example.com\fP\&. However in the same +scenario, you could also use the command \fBtelnet 10.4.0.2\fP to create a +telnet session with alice.example.com over the VPN, that would use the +VPN to secure the session rather than \fBssh\fP\&. +.sp +You can use any address you wish for the tunnel endpoints but make sure +that they are private addresses (such as those that begin with 10 or +192.168) and that they are not part of any existing subnet on the +networks of either peer, unless you are bridging. If you use an address +that is part of your local subnet for either of the tunnel endpoints, +you will get a weird feedback loop. +.SS Example 1: A simple tunnel without security +.sp +On bob: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +openvpn \-\-remote alice.example.com \-\-dev tun1 \e + \-\-ifconfig 10.4.0.1 10.4.0.2 \-\-verb 9 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +On alice: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +openvpn \-\-remote bob.example.com \-\-dev tun1 \e + \-\-ifconfig 10.4.0.2 10.4.0.1 \-\-verb 9 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Now verify the tunnel is working by pinging across the tunnel. +.sp +On bob: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +ping 10.4.0.2 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +On alice: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +ping 10.4.0.1 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The \fB\-\-verb 9\fP option will produce verbose output, similar to the +\fBtcpdump\fP(8) program. Omit the \fB\-\-verb 9\fP option to have OpenVPN run +quietly. +.SS Example 2: A tunnel with static\-key security (i.e. using a pre\-shared secret) +.sp +First build a static key on bob. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +openvpn \-\-genkey \-\-secret key +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +This command will build a key file called \fBkey\fP (in ascii format). Now +copy \fBkey\fP to \fBalice.example.com\fP over a secure medium such as by using +the \fBscp\fP(1) program. +.sp +On bob: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +openvpn \-\-remote alice.example.com \-\-dev tun1 \e + \-\-ifconfig 10.4.0.1 10.4.0.2 \-\-verb 5 \e + \-\-secret key +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +On alice: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +openvpn \-\-remote bob.example.com \-\-dev tun1 \e + \-\-ifconfig 10.4.0.2 10.4.0.1 \-\-verb 5 \e + \-\-secret key +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Now verify the tunnel is working by pinging across the tunnel. +.sp +On bob: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +ping 10.4.0.2 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +On alice: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +ping 10.4.0.1 +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Example 3: A tunnel with full TLS\-based security +.sp +For this test, we will designate \fBbob\fP as the TLS client and \fBalice\fP +as the TLS server. +.INDENT 0.0 +.TP +.B \fINote:\fP +The client or server designation only has +meaning for the TLS subsystem. It has no bearing on OpenVPN\(aqs +peer\-to\-peer, UDP\-based communication model.* +.UNINDENT +.sp +First, build a separate certificate/key pair for both bob and alice (see +above where \fB\-\-cert\fP is discussed for more info). Then construct +Diffie Hellman parameters (see above where \fB\-\-dh\fP is discussed for +more info). You can also use the included test files \fBclient.crt\fP, +\fBclient.key\fP, \fBserver.crt\fP, \fBserver.key\fP and +\fBca.crt\fP\&. The \fB\&.crt\fP files are certificates/public\-keys, the +\fB\&.key\fP files are private keys, and \fBca.crt\fP is a certification +authority who has signed both \fBclient.crt\fP and \fBserver.crt\fP\&. +For Diffie Hellman parameters you can use the included file +\fBdh2048.pem\fP\&. +.INDENT 0.0 +.TP +.B \fIWARNING:\fP +All client, server, and certificate authority certificates +and keys included in the OpenVPN distribution are totally +insecure and should be used for testing only. +.UNINDENT +.sp +On bob: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +openvpn \-\-remote alice.example.com \-\-dev tun1 \e + \-\-ifconfig 10.4.0.1 10.4.0.2 \e + \-\-tls\-client \-\-ca ca.crt \e + \-\-cert client.crt \-\-key client.key \e + \-\-reneg\-sec 60 \-\-verb 5 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +On alice: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +openvpn \-\-remote bob.example.com \-\-dev tun1 \e + \-\-ifconfig 10.4.0.2 10.4.0.1 \e + \-\-tls\-server \-\-dh dh1024.pem \-\-ca ca.crt \e + \-\-cert server.crt \-\-key server.key \e + \-\-reneg\-sec 60 \-\-verb 5 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Now verify the tunnel is working by pinging across the tunnel. +.sp +On bob: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +ping 10.4.0.2 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +On alice: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +ping 10.4.0.1 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Notice the \fB\-\-reneg\-sec 60\fP option we used above. That tells OpenVPN +to renegotiate the data channel keys every minute. Since we used +\fB\-\-verb 5\fP above, you will see status information on each new key +negotiation. +.sp +For production operations, a key renegotiation interval of 60 seconds is +probably too frequent. Omit the \fB\-\-reneg\-sec 60\fP option to use +OpenVPN\(aqs default key renegotiation interval of one hour. +.SS Routing: +.sp +Assuming you can ping across the tunnel, the next step is to route a +real subnet over the secure tunnel. Suppose that bob and alice have two +network interfaces each, one connected to the internet, and the other to +a private network. Our goal is to securely connect both private +networks. We will assume that bob\(aqs private subnet is \fI10.0.0.0/24\fP and +alice\(aqs is \fI10.0.1.0/24\fP\&. +.sp +First, ensure that IP forwarding is enabled on both peers. On Linux, +enable routing: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +echo 1 > /proc/sys/net/ipv4/ip_forward +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +This setting is not persistent. Please see your operating systems +documentation how to properly configure IP forwarding, which is also +persistent through system boots. +.sp +If your system is configured with a firewall. Please see your operating +systems guide on how to configure the firewall. You typically want to +allow traffic coming from and going to the tun/tap adapter OpenVPN is +configured to use. +.sp +On bob: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +route add \-net 10.0.1.0 netmask 255.255.255.0 gw 10.4.0.2 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +On alice: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +route add \-net 10.0.0.0 netmask 255.255.255.0 gw 10.4.0.1 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Now any machine on the \fI10.0.0.0/24\fP subnet can access any machine on the +\fI10.0.1.0/24\fP subnet over the secure tunnel (or vice versa). +.sp +In a production environment, you could put the route command(s) in a +script and execute with the \fB\-\-up\fP option. +.\" Generated by docutils manpage writer. +. diff --git a/doc/openvpn-examples.5.html b/doc/openvpn-examples.5.html new file mode 100644 index 0000000..a0dac40 --- /dev/null +++ b/doc/openvpn-examples.5.html @@ -0,0 +1,582 @@ +<?xml version="1.0" encoding="utf-8" ?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> +<meta name="generator" content="Docutils 0.16: http://docutils.sourceforge.net/" /> +<title>openvpn examples</title> +<style type="text/css"> + +/* +:Author: David Goodger (goodger@python.org) +:Id: $Id: html4css1.css 7952 2016-07-26 18:15:59Z milde $ +:Copyright: This stylesheet has been placed in the public domain. + +Default cascading style sheet for the HTML output of Docutils. + +See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to +customize this style sheet. +*/ + +/* used to remove borders from tables and images */ +.borderless, table.borderless td, table.borderless th { + border: 0 } + +table.borderless td, table.borderless th { + /* Override padding for "table.docutils td" with "! important". + The right padding separates the table cells. */ + padding: 0 0.5em 0 0 ! important } + +.first { + /* Override more specific margin styles with "! important". */ + margin-top: 0 ! important } + +.last, .with-subtitle { + margin-bottom: 0 ! important } + +.hidden { + display: none } + +.subscript { + vertical-align: sub; + font-size: smaller } + +.superscript { + vertical-align: super; + font-size: smaller } + +a.toc-backref { + text-decoration: none ; + color: black } + +blockquote.epigraph { + margin: 2em 5em ; } + +dl.docutils dd { + margin-bottom: 0.5em } + +object[type="image/svg+xml"], object[type="application/x-shockwave-flash"] { + overflow: hidden; +} + +/* Uncomment (and remove this text!) to get bold-faced definition list terms +dl.docutils dt { + font-weight: bold } +*/ + +div.abstract { + margin: 2em 5em } + +div.abstract p.topic-title { + font-weight: bold ; + text-align: center } + +div.admonition, div.attention, div.caution, div.danger, div.error, +div.hint, div.important, div.note, div.tip, div.warning { + margin: 2em ; + border: medium outset ; + padding: 1em } + +div.admonition p.admonition-title, div.hint p.admonition-title, +div.important p.admonition-title, div.note p.admonition-title, +div.tip p.admonition-title { + font-weight: bold ; + font-family: sans-serif } + +div.attention p.admonition-title, div.caution p.admonition-title, +div.danger p.admonition-title, div.error p.admonition-title, +div.warning p.admonition-title, .code .error { + color: red ; + font-weight: bold ; + font-family: sans-serif } + +/* Uncomment (and remove this text!) to get reduced vertical space in + compound paragraphs. +div.compound .compound-first, div.compound .compound-middle { + margin-bottom: 0.5em } + +div.compound .compound-last, div.compound .compound-middle { + margin-top: 0.5em } +*/ + +div.dedication { + margin: 2em 5em ; + text-align: center ; + font-style: italic } + +div.dedication p.topic-title { + font-weight: bold ; + font-style: normal } + +div.figure { + margin-left: 2em ; + margin-right: 2em } + +div.footer, div.header { + clear: both; + font-size: smaller } + +div.line-block { + display: block ; + margin-top: 1em ; + margin-bottom: 1em } + +div.line-block div.line-block { + margin-top: 0 ; + margin-bottom: 0 ; + margin-left: 1.5em } + +div.sidebar { + margin: 0 0 0.5em 1em ; + border: medium outset ; + padding: 1em ; + background-color: #ffffee ; + width: 40% ; + float: right ; + clear: right } + +div.sidebar p.rubric { + font-family: sans-serif ; + font-size: medium } + +div.system-messages { + margin: 5em } + +div.system-messages h1 { + color: red } + +div.system-message { + border: medium outset ; + padding: 1em } + +div.system-message p.system-message-title { + color: red ; + font-weight: bold } + +div.topic { + margin: 2em } + +h1.section-subtitle, h2.section-subtitle, h3.section-subtitle, +h4.section-subtitle, h5.section-subtitle, h6.section-subtitle { + margin-top: 0.4em } + +h1.title { + text-align: center } + +h2.subtitle { + text-align: center } + +hr.docutils { + width: 75% } + +img.align-left, .figure.align-left, object.align-left, table.align-left { + clear: left ; + float: left ; + margin-right: 1em } + +img.align-right, .figure.align-right, object.align-right, table.align-right { + clear: right ; + float: right ; + margin-left: 1em } + +img.align-center, .figure.align-center, object.align-center { + display: block; + margin-left: auto; + margin-right: auto; +} + +table.align-center { + margin-left: auto; + margin-right: auto; +} + +.align-left { + text-align: left } + +.align-center { + clear: both ; + text-align: center } + +.align-right { + text-align: right } + +/* reset inner alignment in figures */ +div.align-right { + text-align: inherit } + +/* div.align-center * { */ +/* text-align: left } */ + +.align-top { + vertical-align: top } + +.align-middle { + vertical-align: middle } + +.align-bottom { + vertical-align: bottom } + +ol.simple, ul.simple { + margin-bottom: 1em } + +ol.arabic { + list-style: decimal } + +ol.loweralpha { + list-style: lower-alpha } + +ol.upperalpha { + list-style: upper-alpha } + +ol.lowerroman { + list-style: lower-roman } + +ol.upperroman { + list-style: upper-roman } + +p.attribution { + text-align: right ; + margin-left: 50% } + +p.caption { + font-style: italic } + +p.credits { + font-style: italic ; + font-size: smaller } + +p.label { + white-space: nowrap } + +p.rubric { + font-weight: bold ; + font-size: larger ; + color: maroon ; + text-align: center } + +p.sidebar-title { + font-family: sans-serif ; + font-weight: bold ; + font-size: larger } + +p.sidebar-subtitle { + font-family: sans-serif ; + font-weight: bold } + +p.topic-title { + font-weight: bold } + +pre.address { + margin-bottom: 0 ; + margin-top: 0 ; + font: inherit } + +pre.literal-block, pre.doctest-block, pre.math, pre.code { + margin-left: 2em ; + margin-right: 2em } + +pre.code .ln { color: grey; } /* line numbers */ +pre.code, code { background-color: #eeeeee } +pre.code .comment, code .comment { color: #5C6576 } +pre.code .keyword, code .keyword { color: #3B0D06; font-weight: bold } +pre.code .literal.string, code .literal.string { color: #0C5404 } +pre.code .name.builtin, code .name.builtin { color: #352B84 } +pre.code .deleted, code .deleted { background-color: #DEB0A1} +pre.code .inserted, code .inserted { background-color: #A3D289} + +span.classifier { + font-family: sans-serif ; + font-style: oblique } + +span.classifier-delimiter { + font-family: sans-serif ; + font-weight: bold } + +span.interpreted { + font-family: sans-serif } + +span.option { + white-space: nowrap } + +span.pre { + white-space: pre } + +span.problematic { + color: red } + +span.section-subtitle { + /* font-size relative to parent (h1..h6 element) */ + font-size: 80% } + +table.citation { + border-left: solid 1px gray; + margin-left: 1px } + +table.docinfo { + margin: 2em 4em } + +table.docutils { + margin-top: 0.5em ; + margin-bottom: 0.5em } + +table.footnote { + border-left: solid 1px black; + margin-left: 1px } + +table.docutils td, table.docutils th, +table.docinfo td, table.docinfo th { + padding-left: 0.5em ; + padding-right: 0.5em ; + vertical-align: top } + +table.docutils th.field-name, table.docinfo th.docinfo-name { + font-weight: bold ; + text-align: left ; + white-space: nowrap ; + padding-left: 0 } + +/* "booktabs" style (no vertical lines) */ +table.docutils.booktabs { + border: 0px; + border-top: 2px solid; + border-bottom: 2px solid; + border-collapse: collapse; +} +table.docutils.booktabs * { + border: 0px; +} +table.docutils.booktabs th { + border-bottom: thin solid; + text-align: left; +} + +h1 tt.docutils, h2 tt.docutils, h3 tt.docutils, +h4 tt.docutils, h5 tt.docutils, h6 tt.docutils { + font-size: 100% } + +ul.auto-toc { + list-style-type: none } + +</style> +</head> +<body> +<div class="document" id="openvpn-examples"> +<h1 class="title">openvpn examples</h1> +<h2 class="subtitle" id="secure-ip-tunnel-daemon">Secure IP tunnel daemon</h2> +<table class="docinfo" frame="void" rules="none"> +<col class="docinfo-name" /> +<col class="docinfo-content" /> +<tbody valign="top"> +<tr class="manual-section field"><th class="docinfo-name">Manual section:</th><td class="field-body">5</td> +</tr> +<tr class="manual-group field"><th class="docinfo-name">Manual group:</th><td class="field-body">Configuration files</td> +</tr> +</tbody> +</table> +<div class="section" id="introduction"> +<h1>INTRODUCTION</h1> +<p>This man page gives a few simple examples to create OpenVPN setups and configuration files.</p> +</div> +<div class="section" id="examples"> +<h1>EXAMPLES</h1> +<p>Prior to running these examples, you should have OpenVPN installed on +two machines with network connectivity between them. If you have not yet +installed OpenVPN, consult the INSTALL file included in the OpenVPN +distribution.</p> +<div class="section" id="firewall-setup"> +<h2>Firewall Setup:</h2> +<p>If firewalls exist between the two machines, they should be set to +forward the port OpenVPN is configured to use, in both directions. +The default for OpenVPN is 1194/udp. If you do not have control +over the firewalls between the two machines, you may still be able to +use OpenVPN by adding <tt class="docutils literal"><span class="pre">--ping</span> 15</tt> to each of the <tt class="docutils literal">openvpn</tt> commands +used below in the examples (this will cause each peer to send out a UDP +ping to its remote peer once every 15 seconds which will cause many +stateful firewalls to forward packets in both directions without an +explicit firewall rule).</p> +<p>Please see your operating system guides for how to configure the firewall +on your systems.</p> +</div> +<div class="section" id="vpn-address-setup"> +<h2>VPN Address Setup:</h2> +<p>For purposes of our example, our two machines will be called +<tt class="docutils literal">bob.example.com</tt> and <tt class="docutils literal">alice.example.com</tt>. If you are constructing a +VPN over the internet, then replace <tt class="docutils literal">bob.example.com</tt> and +<tt class="docutils literal">alice.example.com</tt> with the internet hostname or IP address that each +machine will use to contact the other over the internet.</p> +<p>Now we will choose the tunnel endpoints. Tunnel endpoints are private IP +addresses that only have meaning in the context of the VPN. Each machine +will use the tunnel endpoint of the other machine to access it over the +VPN. In our example, the tunnel endpoint for bob.example.com will be +10.4.0.1 and for alice.example.com, 10.4.0.2.</p> +<p>Once the VPN is established, you have essentially created a secure +alternate path between the two hosts which is addressed by using the +tunnel endpoints. You can control which network traffic passes between +the hosts (a) over the VPN or (b) independently of the VPN, by choosing +whether to use (a) the VPN endpoint address or (b) the public internet +address, to access the remote host. For example if you are on +bob.example.com and you wish to connect to <tt class="docutils literal">alice.example.com</tt> via +<tt class="docutils literal">ssh</tt> without using the VPN (since <strong>ssh</strong> has its own built-in security) +you would use the command <tt class="docutils literal">ssh alice.example.com</tt>. However in the same +scenario, you could also use the command <tt class="docutils literal">telnet 10.4.0.2</tt> to create a +telnet session with alice.example.com over the VPN, that would use the +VPN to secure the session rather than <tt class="docutils literal">ssh</tt>.</p> +<p>You can use any address you wish for the tunnel endpoints but make sure +that they are private addresses (such as those that begin with 10 or +192.168) and that they are not part of any existing subnet on the +networks of either peer, unless you are bridging. If you use an address +that is part of your local subnet for either of the tunnel endpoints, +you will get a weird feedback loop.</p> +</div> +<div class="section" id="example-1-a-simple-tunnel-without-security"> +<h2>Example 1: A simple tunnel without security</h2> +<p>On bob:</p> +<pre class="literal-block"> +openvpn --remote alice.example.com --dev tun1 \ + --ifconfig 10.4.0.1 10.4.0.2 --verb 9 +</pre> +<p>On alice:</p> +<pre class="literal-block"> +openvpn --remote bob.example.com --dev tun1 \ + --ifconfig 10.4.0.2 10.4.0.1 --verb 9 +</pre> +<p>Now verify the tunnel is working by pinging across the tunnel.</p> +<p>On bob:</p> +<pre class="literal-block"> +ping 10.4.0.2 +</pre> +<p>On alice:</p> +<pre class="literal-block"> +ping 10.4.0.1 +</pre> +<p>The <tt class="docutils literal"><span class="pre">--verb</span> 9</tt> option will produce verbose output, similar to the +<tt class="docutils literal">tcpdump</tt>(8) program. Omit the <tt class="docutils literal"><span class="pre">--verb</span> 9</tt> option to have OpenVPN run +quietly.</p> +</div> +<div class="section" id="example-2-a-tunnel-with-static-key-security-i-e-using-a-pre-shared-secret"> +<h2>Example 2: A tunnel with static-key security (i.e. using a pre-shared secret)</h2> +<p>First build a static key on bob.</p> +<pre class="literal-block"> +openvpn --genkey --secret key +</pre> +<p>This command will build a key file called <tt class="docutils literal">key</tt> (in ascii format). Now +copy <tt class="docutils literal">key</tt> to <tt class="docutils literal">alice.example.com</tt> over a secure medium such as by using +the <tt class="docutils literal">scp</tt>(1) program.</p> +<p>On bob:</p> +<pre class="literal-block"> +openvpn --remote alice.example.com --dev tun1 \ + --ifconfig 10.4.0.1 10.4.0.2 --verb 5 \ + --secret key +</pre> +<p>On alice:</p> +<pre class="literal-block"> +openvpn --remote bob.example.com --dev tun1 \ + --ifconfig 10.4.0.2 10.4.0.1 --verb 5 \ + --secret key +</pre> +<p>Now verify the tunnel is working by pinging across the tunnel.</p> +<p>On bob:</p> +<pre class="literal-block"> +ping 10.4.0.2 +</pre> +<p>On alice:</p> +<pre class="literal-block"> +ping 10.4.0.1 +</pre> +</div> +<div class="section" id="example-3-a-tunnel-with-full-tls-based-security"> +<h2>Example 3: A tunnel with full TLS-based security</h2> +<p>For this test, we will designate <tt class="docutils literal">bob</tt> as the TLS client and <tt class="docutils literal">alice</tt> +as the TLS server.</p> +<dl class="docutils"> +<dt><em>Note:</em></dt> +<dd>The client or server designation only has +meaning for the TLS subsystem. It has no bearing on OpenVPN's +peer-to-peer, UDP-based communication model.*</dd> +</dl> +<p>First, build a separate certificate/key pair for both bob and alice (see +above where <tt class="docutils literal"><span class="pre">--cert</span></tt> is discussed for more info). Then construct +Diffie Hellman parameters (see above where <tt class="docutils literal"><span class="pre">--dh</span></tt> is discussed for +more info). You can also use the included test files <code>client.crt</code>, +<code>client.key</code>, <code>server.crt</code>, <code>server.key</code> and +<code>ca.crt</code>. The <tt class="docutils literal">.crt</tt> files are certificates/public-keys, the +<tt class="docutils literal">.key</tt> files are private keys, and <code>ca.crt</code> is a certification +authority who has signed both <code>client.crt</code> and <code>server.crt</code>. +For Diffie Hellman parameters you can use the included file +<code>dh2048.pem</code>.</p> +<dl class="docutils"> +<dt><em>WARNING:</em></dt> +<dd>All client, server, and certificate authority certificates +and keys included in the OpenVPN distribution are totally +insecure and should be used for testing only.</dd> +</dl> +<p>On bob:</p> +<pre class="literal-block"> +openvpn --remote alice.example.com --dev tun1 \ + --ifconfig 10.4.0.1 10.4.0.2 \ + --tls-client --ca ca.crt \ + --cert client.crt --key client.key \ + --reneg-sec 60 --verb 5 +</pre> +<p>On alice:</p> +<pre class="literal-block"> +openvpn --remote bob.example.com --dev tun1 \ + --ifconfig 10.4.0.2 10.4.0.1 \ + --tls-server --dh dh1024.pem --ca ca.crt \ + --cert server.crt --key server.key \ + --reneg-sec 60 --verb 5 +</pre> +<p>Now verify the tunnel is working by pinging across the tunnel.</p> +<p>On bob:</p> +<pre class="literal-block"> +ping 10.4.0.2 +</pre> +<p>On alice:</p> +<pre class="literal-block"> +ping 10.4.0.1 +</pre> +<p>Notice the <tt class="docutils literal"><span class="pre">--reneg-sec</span> 60</tt> option we used above. That tells OpenVPN +to renegotiate the data channel keys every minute. Since we used +<tt class="docutils literal"><span class="pre">--verb</span> 5</tt> above, you will see status information on each new key +negotiation.</p> +<p>For production operations, a key renegotiation interval of 60 seconds is +probably too frequent. Omit the <tt class="docutils literal"><span class="pre">--reneg-sec</span> 60</tt> option to use +OpenVPN's default key renegotiation interval of one hour.</p> +</div> +<div class="section" id="routing"> +<h2>Routing:</h2> +<p>Assuming you can ping across the tunnel, the next step is to route a +real subnet over the secure tunnel. Suppose that bob and alice have two +network interfaces each, one connected to the internet, and the other to +a private network. Our goal is to securely connect both private +networks. We will assume that bob's private subnet is <em>10.0.0.0/24</em> and +alice's is <em>10.0.1.0/24</em>.</p> +<p>First, ensure that IP forwarding is enabled on both peers. On Linux, +enable routing:</p> +<pre class="literal-block"> +echo 1 > /proc/sys/net/ipv4/ip_forward +</pre> +<p>This setting is not persistent. Please see your operating systems +documentation how to properly configure IP forwarding, which is also +persistent through system boots.</p> +<p>If your system is configured with a firewall. Please see your operating +systems guide on how to configure the firewall. You typically want to +allow traffic coming from and going to the tun/tap adapter OpenVPN is +configured to use.</p> +<p>On bob:</p> +<pre class="literal-block"> +route add -net 10.0.1.0 netmask 255.255.255.0 gw 10.4.0.2 +</pre> +<p>On alice:</p> +<pre class="literal-block"> +route add -net 10.0.0.0 netmask 255.255.255.0 gw 10.4.0.1 +</pre> +<p>Now any machine on the <em>10.0.0.0/24</em> subnet can access any machine on the +<em>10.0.1.0/24</em> subnet over the secure tunnel (or vice versa).</p> +<p>In a production environment, you could put the route command(s) in a +script and execute with the <tt class="docutils literal"><span class="pre">--up</span></tt> option.</p> +</div> +</div> +</div> +</body> +</html> diff --git a/doc/openvpn-examples.5.rst b/doc/openvpn-examples.5.rst new file mode 100644 index 0000000..988b602 --- /dev/null +++ b/doc/openvpn-examples.5.rst @@ -0,0 +1,17 @@ +=============================== + openvpn examples +=============================== +------------------------- + Secure IP tunnel daemon +------------------------- + +:Manual section: 5 +:Manual group: Configuration files + + +INTRODUCTION +============ + +This man page gives a few simple examples to create OpenVPN setups and configuration files. + +.. include:: man-sections/examples.rst diff --git a/doc/openvpn.8 b/doc/openvpn.8 index 8038e1f..ceb6348 100644 --- a/doc/openvpn.8 +++ b/doc/openvpn.8 @@ -1,180 +1,195 @@ -.\" 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) 2002-2018 OpenVPN Inc <sales@openvpn.net> -.\" -.\" 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. -.\" -.\" Manual page for openvpn -.\" -.\" SH section heading -.\" SS subsection heading -.\" LP paragraph -.\" IP indented paragraph -.\" TP hanging label -.\" -.\" .nf -- no formatting -.\" .fi -- resume formatting -.\" .ft 3 -- boldface -.\" .ft -- normal face -.\" .in +|-{n} -- indent -.\" -.\" Support macros - this is not present on all platforms -.\" Continuation line for .TP header. -.de TQ -. br -. ns -. TP \\$1\" no doublequotes around argument! -.. -.\" End of TQ macro -.TH openvpn 8 "28 February 2018" -.\"********************************************************* +.\" Man page generated from reStructuredText. +. +.TH OPENVPN 8 "" "" "System Manager's Manual" .SH NAME -openvpn \- secure IP tunnel daemon. -.\"********************************************************* +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 -.ft 3 -openvpn [ options ... ] -.ft -.\"********************************************************* +.nf +\fBopenvpn\fP [ options ... ] +\fBopenvpn\fP \fB\-\-help\fP +.fi +.sp .SH INTRODUCTION -.LP -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: -.I http://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 -.B openvpn +.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 -.LP -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 -.B (Static Key mode) -or -public key security -.B (SSL/TLS mode) -using client & server certificates. -OpenVPN also -supports non\-encrypted TCP/UDP tunnels. - -OpenVPN is designed to work with the -.B TUN/TAP -virtual networking interface that exists on most platforms. - +.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 -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. -.\"********************************************************* +.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 \-\-config file -Load additional config options from -.B file -where each line corresponds to one command line option, -but with the leading '\-\-' removed. - -If -.B \-\-config file -is the only option to the openvpn command, -the -.B \-\-config -can be removed, and the command can be given as -.B 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: - +.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 3 -.in +4 -\\\\ Maps to a single backslash character (\\). -\\" Pass a literal doublequote character ("), don't +.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. -\\[SPACE] Pass a literal space or tab character, don't +\e[SPACE] Pass a literal space or tab character, don\(aqt interpret it as a parameter delimiter. -.in -4 -.ft +.ft P .fi - -For example on Windows, use double backslashes to -represent pathnames: - +.UNINDENT +.UNINDENT +.sp +For example on Windows, use double backslashes to represent pathnames: +.INDENT 7.0 +.INDENT 3.5 +.sp .nf -.ft 3 -.in +4 -secret "c:\\\\OpenVPN\\\\secret.key" -.in -4 -.ft +.ft C +secret "c:\e\eOpenVPN\e\esecret.key" +.ft P .fi - -For examples of configuration files, -see -.I http://openvpn.net/examples.html - +.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 3 -.in +4 +.ft C # # Sample OpenVPN configuration file for # using a pre\-shared static key. # -# '#' or ';' may be used to delimit comments. +# \(aq#\(aq or \(aq;\(aq may be used to delimit comments. # Use a dynamic tun device. dev tun @@ -188,6697 +203,5644 @@ ifconfig 10.1.0.1 10.1.0.2 # Our pre\-shared static key secret static.key -.in -4 -.ft +.ft P .fi -.\"********************************************************* -.SS Tunnel Options: -.TP -.B \-\-mode m -Set OpenVPN major mode. By default, OpenVPN runs in -point\-to\-point mode ("p2p"). OpenVPN 2.0 introduces -a new mode ("server") which implements a multi\-client -server capability. -.\"********************************************************* -.TP -.B \-\-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 -.B \-\-remote host [port] [proto] -Remote host name or IP address. On the client, multiple -.B \-\-remote -options may be specified for redundancy, each referring -to a different OpenVPN server. Specifying multiple -.B \-\-remote -options for this purpose is a special case of the more -general connection\-profile feature. See the -.B <connection> -documentation below. - -The OpenVPN client will try to connect to a server at -.B host:port -in the order specified by the list of -.B \-\-remote -options. - -.B 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 -.B \-\-ping -and -.B \-\-ping\-restart -options. - -Note the following corner case: If you use multiple -.B \-\-remote -options, AND you are dropping root privileges on -the client with -.B \-\-user -and/or -.B \-\-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 -.B \-\-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, -.B \-\-remote -will act as a filter, rejecting connections from any host which does -not match -.B host. - -If -.B 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. -.\"********************************************************* +.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 \-\-remote\-random\-hostname -Prepend a random string (6 bytes, 12 hex characters) to hostname to prevent -DNS caching. For example, "foo.bar.gov" would be modified to -"<random\-chars>.foo.bar.gov". -.\"********************************************************* -.TP -.B <connection> -Define a client connection -profile. Client connection profiles are groups of OpenVPN options that -describe how to connect to a given OpenVPN server. Client connection -profiles are specified within an OpenVPN configuration file, and -each profile is bracketed by -.B <connection> -and -.B </connection>. - -An OpenVPN client will try each connection profile sequentially -until it achieves a successful connection. - -.B \-\-remote\-random -can be used to initially "scramble" the connection -list. - -Here is an example of connection profile usage: - +.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 3 -.in +4 -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 -.in -4 -.ft +.ft C +ignore\-unknown\-options opt1 opt2 opt3 ... optN +.ft P .fi - -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 -.B <connection> -block: - -.B bind, -.B connect\-retry, -.B connect\-retry\-max, -.B connect\-timeout, -.B explicit\-exit\-notify, -.B float, -.B fragment, -.B http\-proxy, -.B http\-proxy\-option, -.B link\-mtu, -.B local, -.B lport, -.B mssfix, -.B mtu\-disc, -.B nobind, -.B port, -.B proto, -.B remote, -.B rport, -.B socks\-proxy, -.B tun\-mtu and -.B tun\-mtu\-extra. - -A defaulting mechanism exists for specifying options to apply to -all -.B <connection> -profiles. If any of the above options (with the exception of -.B remote -) appear outside of a -.B <connection> -block, but in a configuration file which has one or more -.B <connection> -blocks, the option setting will be used as a default for -.B <connection> -blocks which follow it in the configuration file. - -For example, suppose the -.B nobind -option were placed in the sample configuration file above, near -the top of the file, before the first -.B <connection> -block. The effect would be as if -.B nobind -were declared in all -.B <connection> -blocks below it. -.\"********************************************************* -.TP -.B \-\-proto\-force p -When iterating through connection profiles, -only consider profiles using protocol -.B p -('tcp'|'udp'). -.\"********************************************************* -.TP -.B \-\-remote\-random -When multiple -.B \-\-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. -.\"********************************************************* -.TP -.B \-\-proto p -Use protocol -.B p -for communicating with remote host. -.B p -can be -.B udp, -.B tcp\-client, -or -.B tcp\-server. - -The default protocol is -.B udp -when -.B \-\-proto -is not specified. - -For UDP operation, -.B \-\-proto udp -should be specified on both peers. - -For TCP operation, one peer must use -.B \-\-proto tcp\-server -and the other must use -.B \-\-proto tcp\-client. -A peer started with -.B tcp\-server -will wait indefinitely for an incoming connection. A peer -started with -.B tcp\-client -will attempt to connect, and if that fails, will sleep for 5 -seconds (adjustable via the -.B \-\-connect\-retry -option) and try again infinite or up to N retries (adjustable via the -.B \-\-connect\-retry\-max -option). Both TCP client and server will simulate -a SIGUSR1 restart signal if either side resets the connection. - -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. - -This article outlines some of problems with tunneling IP over TCP: - -.I http://sites.inka.de/sites/bigred/devel/tcp\-tcp.html - -There are certain cases, however, where using TCP may be advantageous from -a security and robustness perspective, such as tunneling non\-IP or -application\-level UDP protocols, or tunneling protocols which don't -possess a built\-in reliability layer. -.\"********************************************************* -.TP -.B \-\-connect\-retry n [max] -Wait -.B 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. The optional argument -.B max -specifies the maximum value of wait time in seconds at which it gets -capped (default=300). -.\"********************************************************* -.TP -.B \-\-connect\-retry\-max n -.B n -specifies the number of times each -.B \-\-remote -or -.B <connection> -entry is tried. Specifying -.B n -as one would try each entry exactly once. A successful connection -resets the counter. (default=unlimited). -.\"********************************************************* -.TP -.B \-\-show\-proxy\-settings -Show sensed HTTP or SOCKS proxy settings. Currently, only Windows clients -support this option. -.\"********************************************************* -.TP -.B \-\-http\-proxy server port [authfile|'auto'|'auto\-nct'] [auth\-method] -Connect to remote host through an HTTP proxy at address -.B server -and port -.B port. -If HTTP Proxy\-Authenticate is required, -.B authfile -is a file containing a username and password on 2 lines, or -"stdin" to prompt from console. Its content can also be specified -in the config file with the -.B \-\-http\-proxy\-user\-pass -option. (See section on inline files) - -.B auth\-method -should be one of "none", "basic", or "ntlm". - -HTTP Digest authentication is supported as well, but only via -the -.B auto -or -.B auto\-nct -flags (below). - -The -.B auto -flag causes OpenVPN to automatically determine the -.B 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 -.B 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. -.\"********************************************************* -.TP -.B \-\-http\-proxy\-option type [parm] -Set extended HTTP proxy options. -Repeat to set multiple options. - -.B VERSION version \-\- -Set HTTP version number to -.B version -(default=1.0). - -.B AGENT user\-agent \-\- -Set HTTP "User\-Agent" string to -.B user\-agent. - -.B CUSTOM\-HEADER name content \-\- -Adds the custom Header with -.B name -as name and -.B content -as the content of the custom HTTP header. -.\"********************************************************* -.TP -.B \-\-socks\-proxy server [port] [authfile] -Connect to remote host through a Socks5 proxy at address -.B server -and port -.B port -(default=1080). -.B authfile -(optional) is a file containing a username and password on 2 lines, or -"stdin" to prompt from console. -.\"********************************************************* -.TP -.B \-\-resolv\-retry n -If hostname resolve fails for -.B \-\-remote, -retry resolve for -.B n -seconds before failing. - -Set -.B n -to "infinite" to retry indefinitely. - -By default, -.B \-\-resolv\-retry infinite -is enabled. You can disable by setting n=0. -.\"********************************************************* -.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 -.B \-\-remote -is not used). -.B \-\-float -when specified with -.B \-\-remote -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. - -Essentially, -.B \-\-float -tells OpenVPN to accept authenticated packets -from any address, not only the address which was specified in the -.B \-\-remote -option. -.\"********************************************************* -.TP -.B \-\-ipchange cmd -Run command -.B cmd -when our remote ip\-address is initially authenticated or -changes. - -.B 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. - -When -.B cmd -is executed two arguments are appended after any arguments specified in -.B cmd -, as follows: - -.B cmd ip_address port_number - -Don't use -.B \-\-ipchange -in -.B \-\-mode server -mode. Use a -.B \-\-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 -.I /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 -.I our -IP address changes due to DHCP, we should configure -our IP address change script (see man page for -.BR dhcpcd (8) -) to deliver a -.B SIGHUP -or -.B SIGUSR1 -signal to OpenVPN. OpenVPN will then -reestablish a connection with its most recently authenticated -peer on its new IP address. -.\"********************************************************* -.TP -.B \-\-port port -TCP/UDP port number or port name for both local and remote (sets both -.B \-\-lport -and -.B \-\-rport -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 -.B \-\-lport port -Set local TCP/UDP port number or name. Cannot be used together with -.B \-\-nobind -option. -.\"********************************************************* -.TP -.B \-\-rport port -Set TCP/UDP port number or name used by the -.B \-\-remote -option. The port can also be set directly using the -.B \-\-remote -option. -.\"********************************************************* -.TP -.B \-\-bind [ipv6only] -Bind to local address and port. This is the default unless any of -.B \-\-proto tcp\-client -, -.B \-\-http\-proxy -or -.B \-\-socks\-proxy -are used. - -If the -.B ipv6only -keyword is present OpenVPN will bind only to IPv6 (as oposed -to IPv6 and IPv4) when a IPv6 socket is opened. - -.\"********************************************************* -.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 -.B \-\-remote -option. -.\"********************************************************* -.TP -.B \-\-dev tunX | tapX | null -TUN/TAP virtual network device ( -.B 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. - -.B tun -devices encapsulate IPv4 or IPv6 (OSI Layer 3) while -.B tap -devices encapsulate Ethernet 802.3 (OSI Layer 2). -.\"********************************************************* -.TP -.B \-\-dev\-type device\-type -Which device type are we using? -.B device\-type -should be -.B tun -(OSI Layer 3) -or -.B tap -(OSI Layer 2). -Use this option only if the TUN/TAP device used with -.B \-\-dev -does not begin with -.B tun -or -.B tap. -.\"********************************************************* -.TP -.B \-\-topology mode -Configure virtual addressing topology when running in -.B \-\-dev tun -mode. This directive has no meaning in -.B \-\-dev tap -mode, which always uses a -.B subnet -topology. - -If you set this directive on the server, the -.B \-\-server -and -.B \-\-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 -.B \-\-dev -directive, this directive must always be compatible between client and server. - -.B mode -can be one of: - -.B 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. - -.B 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. This mode -is functionally equivalent to the -.B \-\-ifconfig\-pool\-linear -directive which is available in OpenVPN 2.0, is deprecated and will be -removed in OpenVPN 2.5 - -.B 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 -.B \-\-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 -.B \-\-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 -.BR ifconfig (8) -command which sets a subnet instead of a remote endpoint IP address. - -This option exists in OpenVPN 2.1 or higher. - -Note: Using -.B \-\-topology subnet -changes the interpretation of the arguments of -.B \-\-ifconfig -to mean "address netmask", no longer "local remote". -.\"********************************************************* -.TP -.B \-\-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 -.B node -is a TUN or TAP device based on the name, you should -also specify -.B \-\-dev\-type tun -or -.B \-\-dev\-type tap. - -Under Mac OS X this option can be used to specify the default tun -implementation. Using -.B \-\-dev\-node utun -forces usage of the native Darwin tun kernel support. Use -.B \-\-dev\-node utunN -to select a specific utun instance. To force using the tun.kext (/dev/tunX) use -.B \-\-dev\-node tun\fR. -When not specifying a -.B \-\-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 -.B node -in the Network Connections Control Panel or the -raw GUID of the adapter enclosed by braces. -The -.B \-\-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. -.TP -.B \-\-lladdr address -Specify the link layer address, more commonly known as the MAC address. -Only applied to TAP devices. -.\"********************************************************* -.TP -.B \-\-iproute cmd -Set alternate command to execute instead of default iproute2 command. +.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 -.B \-\-ifconfig l rn -Set TUN/TAP adapter parameters. -.B l -is the IP address of the local VPN endpoint. -For TUN devices in point\-to\-point mode, -.B rn -is the IP address of the remote VPN endpoint. -For TAP devices, or TUN devices used with -.B \-\-topology subnet, -.B rn -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 -.B \-\-topology net30 -or -.B p2p -mode), -the proper usage of -.B \-\-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 -.B rn, -you will be pinging across the VPN. - -For TAP devices, which provide -the ability to create virtual -ethernet segments, or TUN devices in -.B \-\-topology subnet -mode (which create virtual "multipoint networks"), -.B \-\-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 -.BR ifconfig (8) -command, is designed to simplify TUN/TAP -tunnel configuration by providing a -standard interface to the different -ifconfig implementations on different -platforms. - -.B \-\-ifconfig -parameters which are IP addresses can -also be specified as a DNS or /etc/hosts -file resolvable name. - -For TAP devices, -.B \-\-ifconfig -should not be used if the TAP interface will be -getting an IP address lease from a DHCP -server. -.\"********************************************************* .TP -.B \-\-ifconfig\-noexec -Don't actually execute ifconfig/netsh commands, instead -pass -.B \-\-ifconfig -parameters to scripts using environmental variables. -.\"********************************************************* -.TP -.B \-\-ifconfig\-nowarn -Don't output an options consistency check warning -if the -.B \-\-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 -.B \-\-disable\-occ -option) while only disabling the ifconfig component of -the check. - -For example, -if you have a configuration where the local host uses -.B \-\-ifconfig -but the remote host does not, use -.B \-\-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. -.\"********************************************************* -.TP -.B \-\-route network/IP [netmask] [gateway] [metric] -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. - -This option is intended as -a convenience proxy for the -.BR route (8) -shell command, -while at the same time providing portable semantics -across OpenVPN's platform space. - -.B netmask -default \-\- 255.255.255.255 - -.B gateway -default \-\- taken from -.B \-\-route\-gateway -or the second parameter to -.B \-\-ifconfig -when -.B \-\-dev tun -is specified. - -.B metric -default \-\- taken from -.B \-\-route\-metric -otherwise 0. - -The default can be specified by leaving an option blank or setting -it to "default". - -The -.B network -and -.B gateway -parameters can -also be specified as a DNS or /etc/hosts -file resolvable name, or as one of three special keywords: - -.B vpn_gateway -\-\- The remote VPN endpoint address -(derived either from -.B \-\-route\-gateway -or the second parameter to -.B \-\-ifconfig -when -.B \-\-dev tun -is specified). - -.B net_gateway -\-\- The pre\-existing IP default gateway, read from the routing -table (not supported on all OSes). - -.B remote_host -\-\- The -.B \-\-remote -address if OpenVPN is being run in client mode, and is undefined in server mode. -.\"********************************************************* -.TP -.B \-\-route\-gateway gw|'dhcp' -Specify a default gateway -.B gw -for use with -.B \-\-route. - -If -.B dhcp -is specified as the parameter, -the gateway address will be extracted from a DHCP -negotiation with the OpenVPN server\-side LAN. -.\"********************************************************* -.TP -.B \-\-route\-metric m -Specify a default metric -.B m -for use with -.B \-\-route. -.\"********************************************************* -.TP -.B \-\-route\-delay [n] [w] -Delay -.B n -seconds (default=0) after connection -establishment, before adding routes. If -.B n -is 0, routes will be added immediately upon connection -establishment. If -.B \-\-route\-delay -is omitted, routes will be added immediately after TUN/TAP device -open and -.B \-\-up -script execution, before any -.B \-\-user -or -.B \-\-group -privilege downgrade (or -.B \-\-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, -.B \-\-route\-delay -tries to be more intelligent by waiting -.B w -seconds (w=30 by default) -for the TAP\-Win32 adapter to come up before adding routes. -.\"********************************************************* -.TP -.B \-\-route\-up cmd -Run command -.B cmd -after routes are added, subject to -.B \-\-route\-delay. - -.B 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. - -See the "Environmental Variables" section below for -additional parameters passed as environmental variables. -.\"********************************************************* -.TP -.B \-\-route\-pre\-down cmd -Run command -.B cmd -before routes are removed upon disconnection. - -.B 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. - -See the "Environmental Variables" section below for -additional parameters passed as environmental variables. -.\"********************************************************* -.TP -.B \-\-route\-noexec -Don't add or remove routes automatically. Instead pass routes to -.B \-\-route\-up -script using environmental variables. -.\"********************************************************* -.TP -.B \-\-route\-nopull -When used with -.B \-\-client -or -.B \-\-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. -.\"********************************************************* +.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 \-\-allow\-pull\-fqdn -Allow client to pull DNS names from server (rather than being limited -to IP address) for -.B \-\-ifconfig, -.B \-\-route, -and -.B \-\-route\-gateway. -.\"********************************************************* -.TP -.B \-\-client\-nat snat|dnat network netmask alias -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. - -.B network/netmask -(for example 192.168.0.0/255.255.0.0) -defines the local view of a resource from the client perspective, while -.B alias/netmask -(for example 10.64.0.0/255.255.0.0) -defines the remote view from the server perspective. - -Use -.B snat -(source NAT) for resources owned by the client and -.B dnat -(destination NAT) for remote resources. - -Set -.B \-\-verb 6 -for debugging info showing the transformation of src/dest -addresses in packets. -.\"********************************************************* +.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. +.sp +The limit on how much memory can be locked and how that limit +is enforced are OS\-dependent. On Linux the default limit that an +unprivileged process may lock (RLIMIT_MEMLOCK) is low, and if +privileges are dropped later, future memory allocations will very +likely fail. The limit can be increased using ulimit or systemd +directives depending on how OpenVPN is started. +.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 \-\-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: - -.B (1) -Create a static route for the -.B \-\-remote -address which forwards to the pre\-existing default gateway. -This is done so that -.B (3) -will not create a routing loop. - -.B (2) -Delete the default gateway route. - -.B (3) -Set the new default gateway to be the VPN endpoint address (derived either from -.B \-\-route\-gateway -or the second parameter to -.B \-\-ifconfig -when -.B \-\-dev tun -is specified). - -When the tunnel is torn down, all of the above steps are reversed so -that the original default route is restored. - -Option flags: - -.B local \-\- -Add the -.B local -flag if both OpenVPN peers are directly connected via a common subnet, -such as with wireless. The -.B local -flag will cause step -.B 1 -above to be omitted. - -.B autolocal \-\- -Try to automatically determine whether to enable -.B local -flag above. - -.B 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. - -.B 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). - -.B 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). - -.B 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. - -.B ipv6 \-\- -Redirect IPv6 routing into the tunnel. This works similar to the -.B def1 -flag, that is, more specific IPv6 routes are added (2000::/4, 3000::/4), -covering the whole IPv6 unicast space. - -.B !ipv4 \-\- -Do not redirect IPv4 traffic \- typically used in the flag pair -.B "ipv6 !ipv4" -to redirect IPv6\-only. -.\"********************************************************* -.TP -.B \-\-link\-mtu n -Sets an upper bound on the size of UDP packets which are sent -between OpenVPN peers. It's best not to set this parameter unless -you know what you're doing. -.\"********************************************************* -.\"********************************************************* -.TP -.B \-\-redirect\-private [flags] -Like \-\-redirect\-gateway, but omit actually changing the default -gateway. Useful when pushing private subnets. -.\"********************************************************* -.TP -.B \-\-tun\-mtu n -Take the TUN device MTU to be -.B 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 or 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 -.B \-\-fragment -and/or -.B \-\-mssfix -options to deal with MTU sizing issues. -.\"********************************************************* -.TP -.B \-\-tun\-mtu\-extra n -Assume that the TUN/TAP device might return as many as -.B n -bytes more than the -.B \-\-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. -.\"********************************************************* -.TP -.B \-\-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. - -.B 'no' -\-\- Never send DF (Don't Fragment) frames -.br -.B 'maybe' -\-\- Use per\-route hints -.br -.B 'yes' -\-\- Always DF (Don't Fragment) -.br -.\"********************************************************* +.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 -.B \-\-mtu\-test -To empirically measure MTU on connection startup, -add the -.B \-\-mtu\-test -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 -.B \-\-mtu\-test -process normally takes about 3 minutes to complete. -.\"********************************************************* -.TP -.B \-\-fragment max -Enable internal datagram fragmentation so -that no UDP datagrams are sent which -are larger than -.B max -bytes. - -The -.B max -parameter is interpreted in the same way as the -.B \-\-link\-mtu -parameter, i.e. the UDP packet size after encapsulation -overhead has been added in, but not including -the UDP header itself. - -The -.B \-\-fragment -option only makes sense when you are using the UDP protocol ( -.B \-\-proto udp -). - -.B \-\-fragment -adds 4 bytes of overhead per datagram. - -See the -.B \-\-mssfix -option below for an important related option to -.B \-\-fragment. - -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. - -Having said that, there are circumstances where using OpenVPN's -internal fragmentation capability may be your only option, such -as tunneling a UDP multicast stream which requires fragmentation. -.\"********************************************************* +.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 \-\-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 -.B max -bytes. The default value is -.B 1450. - -The -.B max -parameter is interpreted in the same way as the -.B \-\-link\-mtu -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. - -The -.B \-\-mssfix -option only makes sense when you are using the UDP protocol -for OpenVPN peer\-to\-peer communication, i.e. -.B \-\-proto udp. - -.B \-\-mssfix -and -.B \-\-fragment -can be ideally used together, where -.B \-\-mssfix -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), -.B \-\-fragment -will internally fragment them. - -Both -.B \-\-fragment -and -.B \-\-mssfix -are designed to work around cases where Path MTU discovery -is broken on the network path between OpenVPN peers. - -The usual symptom of such a breakdown is an OpenVPN -connection which successfully starts, but then stalls -during active usage. - -If -.B \-\-fragment -and -.B \-\-mssfix -are used together, -.B \-\-mssfix -will take its default -.B max -parameter from the -.B \-\-fragment max -option. - -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: - -.B \-\-tun\-mtu 1500 \-\-fragment 1300 \-\-mssfix -.\"********************************************************* +.B \fB0\fP +Strictly no calling of external programs. .TP -.B \-\-sndbuf size -Set the TCP/UDP socket send buffer size. -Defaults to operation system default. -.\"********************************************************* +.B \fB1\fP +(Default) Only call built\-in executables such as ifconfig, +ip, route, or netsh. .TP -.B \-\-rcvbuf size -Set the TCP/UDP socket receive buffer size. -Defaults to operation system default. -.\"********************************************************* +.B \fB2\fP +Allow calling of built\-in executables and user\-defined +scripts. .TP -.B \-\-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 -.B \-\-socket\-flags flags... -Apply the given flags to the OpenVPN transport socket. -Currently, only -.B TCP_NODELAY -is supported. - -The -.B TCP_NODELAY -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. - -This option is pushable from server to client, and should be used -on both client and server for maximum effect. -.\"********************************************************* -.TP -.B \-\-txqueuelen n -(Linux only) Set the TX queue length on the TUN/TAP interface. -Currently defaults to 100. -.\"********************************************************* -.TP -.B \-\-shaper n -Limit bandwidth of outgoing tunnel data to -.B 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 -.I n -bytes per second, after a datagram write of -.I b -bytes is queued on the TCP/UDP port, wait a minimum of -.I (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 -.B n -to be between 100 bytes/sec and 100 Mbytes/sec. -.\"********************************************************* -.TP -.B \-\-inactive n [bytes] -Causes OpenVPN to exit after -.B 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. - -If the optional -.B bytes -parameter is included, -exit if less than -.B bytes -of combined in/out traffic are produced on the tun/tap device -in -.B 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. -.\"********************************************************* -.TP -.B \-\-ping n -Ping remote over the TCP/UDP control channel -if no packets have been sent for at least -.B n -seconds (specify -.B \-\-ping -on both peers to cause ping packets to be sent in both directions since -OpenVPN ping packets are not echoed like IP ping packets). -When used in one of OpenVPN's secure modes (where -.B \-\-secret, \-\-tls\-server, -or -.B \-\-tls\-client -is specified), the ping packet -will be cryptographically secure. - -This option has two intended uses: - -(1) 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. - -(2) To provide a basis for the remote to test the existence -of its peer using the -.B \-\-ping\-exit -option. -.\"********************************************************* -.TP -.B \-\-ping\-exit n -Causes OpenVPN to exit after -.B n -seconds pass without reception of a ping -or other packet from remote. -This option can be combined with -.B \-\-inactive, \-\-ping, -and -.B \-\-ping\-exit -to create a two\-tiered inactivity disconnect. - -For example, - -.B openvpn [options...] \-\-inactive 3600 \-\-ping 10 \-\-ping\-exit 60 - -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 -.B \-\-ping\-restart n -Similar to -.B \-\-ping\-exit, -but trigger a -.B SIGUSR1 -restart after -.B n -seconds pass without reception of a ping -or other packet from remote. - -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 -.I http://dyndns.org/ -+ a dynamic DNS client such -as -.B ddclient. - -If the peer cannot be reached, a restart will be triggered, causing -the hostname used with -.B \-\-remote -to be re\-resolved (if -.B \-\-resolv\-retry -is also specified). - -In server mode, -.B \-\-ping\-restart, \-\-inactive, -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. - -In client mode, the -.B \-\-ping\-restart -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 -.B \-\-keepalive -setting in the server configuration. -To disable the 120 second default, set -.B \-\-ping\-restart 0 -on the client. - -See the signals section below for more information -on -.B SIGUSR1. - -Note that the behavior of -.B SIGUSR1 -can be modified by the -.B \-\-persist\-tun, \-\-persist\-key, \-\-persist\-local\-ip, -and -.B \-\-persist\-remote\-ip -options. - -Also note that -.B \-\-ping\-exit -and -.B \-\-ping\-restart -are mutually exclusive and cannot be used together. -.\"********************************************************* -.TP -.B \-\-keepalive interval timeout -A helper directive designed to simplify the expression of -.B \-\-ping -and -.B \-\-ping\-restart. - -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 -.B \-\-ping -and -.B \-\-ping\-restart -options to the client. If used on both server and client, -the values pushed from server will override the client local values. - -The -.B timeout -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. - -For example, -.B \-\-keepalive 10 60 -expands as follows: - +.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 3 -.in +4 - 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 -.in -4 -.ft +.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 -.\"********************************************************* -.TP -.B \-\-ping\-timer\-rem -Run the -.B \-\-ping\-exit -/ -.B \-\-ping\-restart -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 -.B \-\-remote -peer), and you don't want to start clocking timeouts until a remote -peer connects. -.\"********************************************************* -.TP -.B \-\-persist\-tun -Don't close and reopen TUN/TAP device or run up/down scripts -across -.B SIGUSR1 -or -.B \-\-ping\-restart -restarts. - -.B SIGUSR1 -is a restart signal similar to -.B SIGHUP, -but which offers finer\-grained control over -reset options. -.\"********************************************************* -.TP -.B \-\-persist\-key -Don't re\-read key files across -.B SIGUSR1 -or -.B \-\-ping\-restart. - -This option can be combined with -.B \-\-user nobody -to allow restarts triggered by the -.B SIGUSR1 +.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. -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 -.B SIGUSR1 -resets, so they don't need to be re\-read. -.\"********************************************************* +.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 \-\-persist\-local\-ip -Preserve initially resolved local IP address and port number -across -.B SIGUSR1 -or -.B \-\-ping\-restart -restarts. -.\"********************************************************* -.TP -.B \-\-persist\-remote\-ip -Preserve most recently authenticated remote IP address and port number -across -.B SIGUSR1 +.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 -.B \-\-ping\-restart -restarts. -.\"********************************************************* -.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 -.B \-\-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 -.B \-\-reneg -options (see below), then are discarded. - -The downside -of using -.B \-\-mlock -is that it will reduce the amount of physical -memory available to other applications. -.\"********************************************************* -.TP -.B \-\-up cmd -Run command -.B cmd -after successful TUN/TAP device open -(pre -.B \-\-user -UID change). - -.B 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. - -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 -.B \-\-dev tun -execute as: - -.B cmd tun_dev tun_mtu link_mtu ifconfig_local_ip ifconfig_remote_ip [ init | restart ] - -For -.B \-\-dev tap -execute as: - -.B 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 -.B 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, -.B 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 -.I init. -If the -.B \-\-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 -.B \-\-persist\-tun -option will enable such preservation). A restart -can be generated by a SIGUSR1 signal, a -.B \-\-ping\-restart -timeout, or a connection reset when the TCP protocol is enabled -with the -.B \-\-proto -option. If a restart occurs, and -.B \-\-up\-restart -has been specified, the up script will be called with -.I 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 -.B \-\-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). - -.B 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 -.B \-\-ifconfig -option to automatically ifconfig the TUN device, -eliminating the need to define an -.B \-\-up -script, unless you also want to configure routes -in the -.B \-\-up -script. - -If -.B \-\-ifconfig -is also specified, OpenVPN will pass the ifconfig local -and remote endpoints on the command line to the -.B \-\-up -script so that they can be used to configure routes such as: - -.B route add \-net 10.0.0.0 netmask 255.255.255.0 gw $5 -.\"********************************************************* -.TP -.B \-\-up\-delay -Delay TUN/TAP open and possible -.B \-\-up -script execution -until after TCP/UDP connection establishment with peer. - -In -.B \-\-proto udp -mode, this option normally requires the use of -.B \-\-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. -.\"********************************************************* -.TP -.B \-\-down cmd -Run command -.B cmd -after TUN/TAP device close -(post -.B \-\-user -UID change and/or -.B \-\-chroot -). -.B 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 -.B \-\-up -option above. - -Note that if you reduce privileges by using -.B \-\-user -and/or -.B \-\-group, -your -.B \-\-down -script will also run at reduced privilege. -.\"********************************************************* -.TP -.B \-\-down\-pre -Call -.B \-\-down -cmd/script before, rather than after, TUN/TAP close. -.\"********************************************************* -.TP -.B \-\-up\-restart -Enable the -.B \-\-up -and -.B \-\-down -scripts to be called for restarts as well as initial program start. -This option is described more fully above in the -.B \-\-up -option documentation. -.\"********************************************************* -.TP -.B \-\-setenv name value -Set a custom environmental variable -.B name=value -to pass to script. -.\"********************************************************* -.TP -.B \-\-setenv FORWARD_COMPATIBLE 1 -Relax config file syntax checking 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: -.B setenv opt - -Versions prior to OpenVPN 2.3.3 will always ignore options set with the -.B setenv opt -directive. - -See also -.B \-\-ignore\-unknown\-option -.\"********************************************************* -.TP -.B \-\-setenv\-safe name value -Set a custom environmental variable -.B OPENVPN_name=value -to pass to script. - -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. -.\"********************************************************* -.TP -.B \-\-ignore\-unknown\-option opt1 opt2 opt3 ... optN -When one of options -.B 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 -.B \-\-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. - -.B \-\-ignore\-unknown\-option -is available since OpenVPN 2.3.3. -.\"********************************************************* -.TP -.B \-\-script\-security level -This directive offers policy\-level control over OpenVPN's usage of external programs -and scripts. Lower -.B level -values are more restrictive, higher values are more permissive. Settings for -.B level: - -.B 0 \-\- -Strictly no calling of external programs. -.br -.B 1 \-\- -(Default) Only call built\-in executables such as ifconfig, ip, route, or netsh. -.br -.B 2 \-\- -Allow calling of built\-in executables and user\-defined scripts. -.br -.B 3 \-\- -Allow passwords to be passed to scripts via environmental variables (potentially unsafe). - -OpenVPN releases before v2.3 also supported a -.B method -flag which indicated how OpenVPN should call external commands and scripts. This -could be either -.B execve -or -.B 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 -.B 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: - +.INDENT 7.0 +.INDENT 3.5 +.sp .nf -.ft 3 -.in +4 -\-\-up 'C:\\\\Windows\\\\System32\\\\wscript.exe C:\\\\Program\\ Files\\\\OpenVPN\\\\config\\\\my\-up\-script.vbs' -.in -4 -.ft +.ft C +openvpn \-\-test\-crypto \-\-secret key \-\-verb 9 +.ft P .fi - -Please note the single quote marks and the escaping of the backslashes (\\) and -the space character. - -The reason the support for the -.B system -flag was removed is due to the security implications with shell expansions -when executing scripts via the system() call. -.\"********************************************************* +.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 \-\-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 -.B \-\-dev tun -while the other peer uses -.B \-\-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. -.\"********************************************************* -.TP -.B \-\-user user -Change the user ID of the OpenVPN process to -.B 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 -.B user -to -.I 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 -.B SIGUSR1 -signal -(for example in response -to a DHCP reset), you should make use of one or more of the -.B \-\-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 -.BR ifconfig -on the TUN device). -.\"********************************************************* -.TP -.B \-\-group group -Similar to the -.B \-\-user -option, -this option changes the group ID of the OpenVPN process to -.B group -after initialization. -.\"********************************************************* -.TP -.B \-\-cd dir -Change directory to -.B dir -prior to reading any files such as -configuration files, key files, scripts, etc. -.B 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 -.B \-\-daemon -mode, and you want to consolidate all of -your OpenVPN control files in one location. -.\"********************************************************* -.TP -.B \-\-chroot dir -Chroot to -.B dir -after initialization. -.B \-\-chroot -essentially redefines -.B 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 -.B 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 -.B 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. -.\"********************************************************* -.TP -.B \-\-setcon context -Apply SELinux -.B 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 -.B \-\-user -and -.B \-\-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 -.B \-\-persist\-key -and -.B \-\-persist\-tun -options. -.\"********************************************************* -.TP -.B \-\-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 -.B \-\-daemon -is parsed on the command line even though -the daemonization point occurs later. If one of the -.B \-\-log -options is present, it will supercede syslog -redirection. - -The optional -.B progname -parameter will cause OpenVPN to report its program name -to the system logger as -.B progname. -This can be useful in linking OpenVPN messages -in the syslog file with specific tunnels. -When unspecified, -.B progname -defaults to "openvpn". - -When OpenVPN is run with the -.B \-\-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 -.B \-\-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 -.B \-\-daemon -together with -.B \-\-auth\-user\-pass -(entered on console) and -.B \-\-auth\-nocache -will fail as soon as key renegotiation (and reauthentication) occurs. -.\"********************************************************* -.TP -.B \-\-syslog [progname] -Direct log output to system logger, but do not become a daemon. -See -.B \-\-daemon -directive above for description of -.B progname -parameter. +.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 -.B \-\-log -options. -.\"********************************************************* +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 \-\-passtos -Set the TOS field of the tunnel packet to what the payload's TOS is. -.\"********************************************************* +.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 -.B \-\-inetd [wait|nowait] [progname] -Use this option when OpenVPN is being run from the inetd or -.BR xinetd(8) -server. - -The -.B wait/nowait -option must match what is specified in the inetd/xinetd -config file. The -.B nowait -mode can only be used with -.B \-\-proto tcp\-server. -The default is -.B wait. -The -.B 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: -.I http://openvpn.net/faq.html#oneport - -This option precludes the use of -.B \-\-daemon, \-\-local, -or -.B \-\-remote. -Note that this option causes message and error output to be handled in the same -way as the -.B \-\-daemon -option. The optional -.B progname -parameter is also handled exactly as in -.B \-\-daemon. - -Also note that in -.B 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: -.I http://openvpn.net/1xhowto.html -.\"********************************************************* -.TP -.B \-\-log file -Output logging messages to -.B file, -including output to stdout/stderr which -is generated by called scripts. -If -.B file -already exists it will be truncated. -This option takes effect -immediately when it is parsed in the command line -and will supercede syslog output if -.B \-\-daemon -or -.B \-\-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 -.B \-\-ping\-restart. - -Note that on Windows, when OpenVPN is started as a service, -logging occurs by default without the need to specify -this option. -.\"********************************************************* -.TP -.B \-\-log\-append file -Append logging messages to -.B file. -If -.B file -does not exist, it will be created. -This option behaves exactly like -.B \-\-log -except that it appends to rather -than truncating the log file. -.\"********************************************************* +.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. -.\"********************************************************* +Avoid writing timestamps to log messages, even when they otherwise would +be prepended. In particular, this applies to log messages sent to +stdout. .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 -.B \-\-writepid file -Write OpenVPN's main process ID to -.B file. -.\"********************************************************* -.TP -.B \-\-nice n -Change process priority after initialization -( -.B n -greater than 0 is lower priority, -.B n -less than zero is higher priority). -.\"********************************************************* -.\".TP -.\".B \-\-nice\-work n -.\"Change priority of background TLS work thread. The TLS thread -.\"feature is enabled when OpenVPN is built -.\"with pthread support, and you are running OpenVPN -.\"in TLS mode (i.e. with -.\".B \-\-tls\-client -.\"or -.\".B \-\-tls\-server -.\"specified). -.\" -.\"Using a TLS thread offloads the CPU\-intensive process of SSL/TLS\-based -.\"key exchange to a background thread so that it does not become -.\"a latency bottleneck in the tunnel packet forwarding process. -.\" -.\"The parameter -.\".B n -.\"is interpreted exactly as with the -.\".B \-\-nice -.\"option above, but in relation to the work thread rather -.\"than the main thread. -.\"********************************************************* +.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 -.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'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 -.B \-\-proto udp -is specified, and when -.B \-\-shaper -is NOT specified. -.\"********************************************************* +.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 \-\-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 -.B \-\-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. - -Note: this option is only relevant for UDP servers. - -Note 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). -.\"********************************************************* -.TP -.B \-\-echo [parms...] -Echo -.B parms -to log output. - -Designed to be used to send messages to a controlling application -which is receiving the OpenVPN log output. -.\"********************************************************* -.TP -.B \-\-remap\-usr1 signal -Control whether internally or externally -generated SIGUSR1 signals are remapped to -SIGHUP (restart without persisting state) or -SIGTERM (exit). - -.B signal -can be set to "SIGHUP" or "SIGTERM". By default, no remapping -occurs. -.\"********************************************************* -.TP -.B \-\-verb n -Set output verbosity to -.B 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. - -.B 0 \-\- +.B \fB0\fP No output except fatal errors. -.br -.B 1 to 4 \-\- -Normal usage range. -.br -.B 5 \-\- -Output -.B R -and -.B 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. -.br -.B 6 to 11 \-\- -Debug info range (see errlevel.h for additional -information on debug levels). -.\"********************************************************* -.TP -.B \-\-status file [n] -Write operational status to -.B file -every -.B n -seconds. - -Status can also be written to the syslog by sending a -.B 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 -.B \-\-status\-version -option in that case. - -For clients or instances running in point\-to\-point mode, it will contain the -traffic statistics. -.\"********************************************************* .TP -.B \-\-status\-version [n] -Set the status file format version number to -.B n\fR. - -This only affects the status file on servers with multi\-client capability -enabled. - -.B 1 -\-\- traditional format (default). The client list contains the following -fields comma\-separated: Common Name, Real Address, Bytes Received, Bytes Sent, -Connected Since. -.br -.B 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. -Future versions may extend the number of fields. -.br -.B 3 -\-\- identical to 2, but fields are tab\-separated. - -.\"********************************************************* -.TP -.B \-\-mute n -Log at most -.B n -consecutive messages in the same category. This is useful to -limit repetitive logging of similar message types. -.\"********************************************************* +.B \fB1\fP to \fB4\fP +Normal usage range. .TP -.B \-\-compress [algorithm] -Enable a compression algorithm. - -The -.B algorithm -parameter may be "lzo", "lz4", or empty. LZO and LZ4 -are different compression algorithms, with LZ4 generally +.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. -For backwards compatibility with OpenVPN versions before v2.4, use "lzo" -(which is identical to the older option "\-\-comp\-lzo yes"). - -If the -.B algorithm -parameter is empty, compression will be turned off, but the packet -framing for compression will still be enabled, allowing a different -setting to be pushed later. - -.B Security Considerations - -Compression and encryption is a tricky combination. If an attacker knows or is -able to control (parts of) the plaintext 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 which also leverage compression 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. - -.\"********************************************************* -.TP -.B \-\-comp\-lzo [mode] -.B DEPRECATED -This option will be removed in a future OpenVPN release. Use the -newer -.B \-\-compress -instead. - -Use LZO compression \-\- may add up to 1 byte per -packet for incompressible data. -.B 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. - +.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 -.B \-\-comp\-lzo -directive, such as -.B \-\-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 -.B \-\-client\-config\-dir -file, specify the compression setting for the client, -for example: - +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 3 -.in +4 +.ft C comp\-lzo yes push "comp\-lzo yes" -.in -4 -.ft +.ft P .fi - -The first line sets the -.B comp\-lzo -setting for the server -side of the link, the second sets the client side. -.\"********************************************************* +.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 -When used in conjunction with -.B \-\-comp\-lzo, -this option will disable OpenVPN's adaptive compression algorithm. -Normally, adaptive compression is enabled with -.B \-\-comp\-lzo. - +\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 \-\-management socket\-name unix [pw\-file] \ \ \ \ \ (recommended) -.TQ -.B \-\-management IP port [pw\-file] -Enable a management server on a -.B socket\-name -Unix socket on those platforms supporting it, or on -a designated TCP port. - -.B 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 -.B \-\-management\-client\-user -and -.B \-\-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 -.B tunnel. -Tunnel mode will cause the management interface to listen for a -TCP connection on the local VPN address of the TUN/TAP interface. - -.B BEWARE -of enabling the management interface over TCP. In these cases you should -.I ALWAYS -make use of -.B pw\-file -to password protect the management interface. Any user who can connect to this -TCP -.B 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 -.I management\-notes.txt -file in the management folder of the OpenVPN source distribution. - +(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 \-\-management\-client -Management interface will connect as a TCP/unix domain client to -.B IP:port -specified by -.B \-\-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. -.\"********************************************************* +.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 \-\-management\-query\-passwords -Query management channel for private key password and -.B \-\-auth\-user\-pass -username/password. Only query the management channel -for inputs which ordinarily would have been queried from the -console. -.\"********************************************************* +.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 \-\-management\-query\-proxy -Query management channel for proxy server information for a specific -.B \-\-remote -(client\-only). -.\"********************************************************* +.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 \-\-management\-query\-remote -Allow management interface to override -.B \-\-remote -directives (client\-only). -.\"********************************************************* -.TP -.B \-\-management\-external\-key -Allows usage for external private key file instead of -.B \-\-key -option (client\-only). -.\"********************************************************* -.TP -.B \-\-management\-external\-cert certificate\-hint -Allows usage for external certificate instead of -.B \-\-cert -option (client\-only). -.B 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. -.\"********************************************************* +.B \-\-allow\-recursive\-routing +When this option is set, OpenVPN will not drop incoming tun packets with +same destination as host. .TP -.B \-\-management\-forget\-disconnect -Make OpenVPN forget passwords when management session -disconnects. - -This directive does not affect the -.B \-\-http\-proxy -username/password. It is always cached. -.\"********************************************************* +.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 \-\-management\-hold -Start OpenVPN in a hibernating state, until a client -of the management interface explicitly starts it -with the -.B hold release -command. -.\"********************************************************* +.BI \-\-auth\-token\-user \ base64username +Companion option to \fB\-\-auth\-token\fP\&. This options allows to override +the username used by the client when reauthenticating with the \fBauth\-token\fP\&. +It also allows to use \fB\-\-auth\-token\fP in setups that normally do not use +username and password. +.sp +The username has to be base64 encoded. .TP -.B \-\-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. -.\"********************************************************* -.TP -.B \-\-management\-log\-cache n -Cache the most recent -.B n -lines of log file history for usage -by the management channel. -.\"********************************************************* +.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 \-\-management\-up\-down -Report tunnel up/down events to management interface. -.B -.\"********************************************************* +.B \fBnone\fP +Client will exit with a fatal error (this is the default). .TP -.B \-\-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. -.\"********************************************************* +.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 \-\-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. -.\"********************************************************* -.TP -.B \-\-management\-client\-user u -When the management interface is listening on a unix domain socket, -only allow connections from user -.B u. -.\"********************************************************* -.TP -.B \-\-management\-client\-group g -When the management interface is listening on a unix domain socket, -only allow connections from group -.B g. -.\"********************************************************* -.TP -.B \-\-plugin module\-pathname [init\-string] -Load plug\-in module from the file -.B module\-pathname, -passing -.B init\-string -as an argument -to the module initialization function. Multiple -plugin modules may be loaded into one OpenVPN -process. - -The -.B module\-pathname -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. - +.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 3 -.in +4 -.B \-\-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 -.in -4 +.ft C +pull +tls\-client +.ft P .fi - -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 swithed into via the -.B \-\-cd -option before the -.B \-\-plugin -option. - -For more information and examples on how to build OpenVPN -plug\-in modules, see the README file in the -.B 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 -.B doc -and the actual plugin modules are in -.B 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. -.\"********************************************************* -.TP -.B \-\-keying\-material\-exporter label len -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. - -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. -.\"********************************************************* -.SS Server Mode -Starting with OpenVPN 2.0, a multi\-client TCP/UDP server mode -is supported, and can be enabled with the -.B \-\-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. -.\"********************************************************* -.TP -.B \-\-server network netmask ['nopool'] -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. - -For example, -.B \-\-server 10.8.0.0 255.255.255.0 -expands as follows: - +.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 3 -.in +4 - 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 - -.in -4 -.ft +.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 - -Don't use -.B \-\-server -if you are ethernet bridging. Use -.B \-\-server\-bridge -instead. -.\"********************************************************* +.UNINDENT +.UNINDENT +.sp +\fBnetwork/netmask\fP (for example \fB192.168.0.0/255.255.0.0\fP) defines +the local view of a resource from the client perspective, while +\fBalias/netmask\fP (for example \fB10.64.0.0/255.255.0.0\fP) defines the +remote view from the server perspective. +.sp +Use \fBsnat\fP (source NAT) for resources owned by the client and +\fBdnat\fP (destination NAT) for remote resources. +.sp +Set \fB\-\-verb 6\fP for debugging info showing the transformation of +src/dest addresses in packets. +.TP +.BI \-\-connect\-retry \ n +Wait \fBn\fP seconds between connection attempts (default \fB5\fP). +Repeated reconnection attempts are slowed down after 5 retries per +remote by doubling the wait time after each unsuccessful attempt. An +optional argument \fBmax\fP specifies the maximum value of wait time in +seconds at which it gets capped (default \fB300\fP). +.TP +.BI \-\-connect\-retry\-max \ n +\fBn\fP specifies the number of times each \fB\-\-remote\fP or +\fB<connection>\fP entry is tried. Specifying \fBn\fP as \fB1\fP would try +each entry exactly once. A successful connection resets the counter. +(default \fIunlimited\fP). +.TP +.BI \-\-connect\-timeout \ n +See \fB\-\-server\-poll\-timeout\fP\&. +.TP +.BI \-\-explicit\-exit\-notify \ n +In UDP client mode or point\-to\-point mode, send server/peer an exit +notification if tunnel is restarted or OpenVPN process is exited. In +client mode, on exit/restart, this option will tell the server to +immediately close its client instance object rather than waiting for a +timeout. +.sp +The \fBn\fP parameter (default \fB1\fP if not present) controls the +maximum number of attempts that the client will try to resend the exit +notification message. +.sp +In UDP server mode, send \fBRESTART\fP control channel command to +connected clients. The \fBn\fP parameter (default \fB1\fP if not present) +controls client behavior. With \fBn\fP = \fB1\fP client will attempt to +reconnect to the same server, with \fBn\fP = \fB2\fP client will advance +to the next server. +.sp +OpenVPN will not send any exit notifications unless this option is +enabled. .TP -.B \-\-server\-bridge gateway netmask pool\-start\-IP pool\-end\-IP +.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 \-\-server\-bridge ['nogw'] - -A helper directive similar to -.B \-\-server -which is designed to simplify the configuration -of OpenVPN's server mode in ethernet bridging configurations. - -If -.B \-\-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 -.B 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 -.B 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 -.B gateway -and -.B netmask -parameters to -.B \-\-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 -.B pool\-start\-IP -and -.B pool\-end\-IP, -for OpenVPN to allocate to connecting -clients. - -For example, -.B server\-bridge 10.8.0.4 255.255.255.0 10.8.0.128 10.8.0.254 -expands as follows: - +.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 3 -.in +4 -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 -4 -.ft +.ft C +pull\-filter accept text +pull\-filter ignore text +pull\-filter reject text +.ft P .fi - -In another example, -.B \-\-server\-bridge -(without parameters) expands as follows: - +.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 3 -.in +4 -mode server -tls\-server - -push "route\-gateway dhcp" -.in -4 -.ft +.ft C +pull\-filter ignore "route" +.ft P .fi - -Or -.B \-\-server\-bridge nogw -expands as follows: - +.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 3 -.in +4 -mode server -tls\-server -.in -4 -.ft +.ft C +pull\-filter accept "route 192.168.1." +pull\-filter ignore "route " +.ft P .fi -.\"********************************************************* -.TP -.B \-\-push "option" -Push a config file option back to the client for remote -execution. Note that -.B -option -must be enclosed in double quotes (""). The client must specify -.B \-\-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: -.B \-\-route, \-\-route\-gateway, \-\-route\-delay, \-\-redirect\-gateway, -.B \-\-ip\-win32, \-\-dhcp\-option, -.B \-\-inactive, \-\-ping, \-\-ping\-exit, \-\-ping\-restart, -.B \-\-setenv, -.B \-\-auth\-token, -.B \-\-persist\-key, \-\-persist\-tun, \-\-echo, -.B \-\-comp\-lzo, -.B \-\-socket\-flags, -.B \-\-sndbuf, \-\-rcvbuf -.\"********************************************************* +.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, port and protocol. +.sp +Valid syntaxes: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +remote host +remote host port +remote host port proto +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The \fBport\fP and \fBproto\fP arguments are optional. The OpenVPN client +will try to connect to a server at \fBhost:port\fP\&. The \fBproto\fP argument +indicates the protocol to use when connecting with the remote, and may be +\fBtcp\fP or \fBudp\fP\&. To enforce IPv4 or IPv6 connections add a +\fB4\fP or \fB6\fP suffix; like \fBudp4\fP / \fBudp6\fP +/ \fBtcp4\fP / \fBtcp6\fP\&. +.sp +On the client, multiple \fB\-\-remote\fP options may be specified for +redundancy, each referring to a different OpenVPN server, in the order +specified by the list of \fB\-\-remote\fP options. Specifying multiple +\fB\-\-remote\fP options for this purpose is a special case of the more +general connection\-profile feature. See the \fB<connection>\fP +documentation below. +.sp +The 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 +Examples: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +remote server1.example.net +remote server1.example.net 1194 +remote server2.example.net 1194 tcp +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 7.0 +.TP +.B \fINote:\fP +Since UDP is connectionless, connection failure is defined by +the \fB\-\-ping\fP and \fB\-\-ping\-restart\fP options. +.sp +Also, 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. +.UNINDENT +.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 \-\-push\-reset -Don't inherit the global push list for a specific client instance. -Specify this option in a client\-specific context such -as with a -.B \-\-client\-config\-dir -configuration file. This option will ignore -.B \-\-push -options at the global config file level. -.\"********************************************************* -.TP -.B \-\-push\-remove opt -selectively remove all -.B \-\-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 -.B \-\-push\-remove route -would remove all -.B \-\-push route ... -and -.B \-\-push route\-ipv6 ... -statements, while -.B \-\-push\-remove 'route\-ipv6 2001:' -would only remove IPv6 routes for 2001:... networks. - -.B \-\-push\-remove -can only be used in a client\-specific context, like in a -.B \-\-client\-config\-dir -file, or -.B \-\-client\-connect -script or plugin \-\- similar to -.B \-\-push\-reset, -just more selective. - -NOTE: to -.I change -an option, -.B \-\-push\-remove -can be used to first remove the old value, and then add a new -.B \-\-push -option with the new value. -.\"********************************************************* +.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 \-\-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=2 \-\- if the client supports peer\-id floating mechansim - -IV_NCP=2 \-\- negotiable ciphers, client supports -.B \-\-cipher -pushed by the server, a value of 2 or greater indicates client -supports AES\-GCM\-128 and AES\-GCM\-256. - -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 -.B \-\-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_" -.\"********************************************************* +.B \-\-remote\-random\-hostname +Prepend a random string (6 bytes, 12 hex characters) to hostname to +prevent DNS caching. For example, "foo.bar.gov" would be modified to +"<random\-chars>.foo.bar.gov". .TP -.B \-\-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 -.B \-\-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 -.B \-\-client\-config\-dir -or dynamically generated using a -.B \-\-client\-connect -script. -.\"********************************************************* -.TP -.B \-\-ifconfig\-pool start\-IP end\-IP [netmask] -Set aside a pool of subnets to be -dynamically allocated to connecting clients, similar -to a DHCP server. 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 -.B netmask -parameter will also be pushed to clients. - -.\"********************************************************* -.TP -.B \-\-ifconfig\-pool\-persist file [seconds] -Persist/unpersist ifconfig\-pool -data to -.B file, -at -.B seconds -intervals (default=600), as well as on program startup and -shutdown. - -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 -.B \-\-persist\-tun -option. - -.B file -is a comma\-delimited ASCII file, formatted as -<Common\-Name>,<IP\-address>. - -If -.B seconds -= 0, -.B file -will be treated as read\-only. This is useful if -you would like to treat -.B 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 -.B \-\-ifconfig\-push - -.\"********************************************************* +.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 \-\-ifconfig\-pool\-linear -.B DEPRECATED -This option will be removed in OpenVPN 2.5 - -Modifies the -.B \-\-ifconfig\-pool -directive to -allocate individual TUN interface addresses for -clients rather than /30 subnets. NOTE: This option -is incompatible with Windows clients. - -This option is deprecated, and should be replaced with -.B \-\-topology p2p -which is functionally equivalent. -.\"********************************************************* -.TP -.B \-\-ifconfig\-push local remote\-netmask [alias] -Push virtual IP endpoints for client tunnel, -overriding the \-\-ifconfig\-pool dynamic allocation. - -The parameters -.B local -and -.B remote\-netmask -are set according to the -.B \-\-ifconfig -directive which you want to execute on the client machine to -configure the remote end of the tunnel. Note that the parameters -.B local -and -.B 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 -.B 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 -.B local/remote\-netmask -will refer to the server view while -.B 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 -.B \-\-client\-config\-dir -or dynamically generated using a -.B \-\-client\-connect -script. - -Remember also to include a -.B \-\-route -directive in the main OpenVPN config file which encloses -.B 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: - -.B 1 -\-\- Use -.B \-\-client\-connect script -generated file for static IP (first choice). -.br -.B 2 -\-\- Use -.B \-\-client\-config\-dir -file for static IP (next choice). -.br -.B 3 -\-\- Use -.B \-\-ifconfig\-pool -allocation for dynamic IP (last choice). -.br -.\"********************************************************* -.TP -.B \-\-iroute network [netmask] -Generate an internal route to a specific -client. The -.B netmask -parameter, if omitted, defaults to 255.255.255.255. - -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 -.B \-\-route -directive). The reason why two routes are needed -is that the -.B \-\-route -directive routes the packet from the kernel -to OpenVPN. Once in OpenVPN, the -.B \-\-iroute -directive routes to the specific client. - -This option must be specified either in a client -instance config file using -.B \-\-client\-config\-dir -or dynamically generated using a -.B \-\-client\-connect -script. - -The -.B \-\-iroute -directive also has an important interaction with -.B \-\-push -"route ...". -.B \-\-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 -.B \-\-push -"route ..." -together with -.B \-\-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. -.\"********************************************************* +.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 -.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 -.B \-\-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. -.\"********************************************************* +.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 \-\-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 -.B \-\-client\-connect cmd -Run -.B command cmd -on client connection. - -.B 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. - -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 -.B 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 -.B \-\-client\-config\-dir -option below for options which -can be legally used in a dynamically generated config file. - -Note that the return value of -.B script -is significant. If -.B script -returns a non\-zero error status, it will cause the client -to be disconnected. -.\"********************************************************* -.TP -.B \-\-client\-disconnect cmd -Like -.B \-\-client\-connect -but called on client instance shutdown. Will not be called -unless the -.B \-\-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 -.B \-\-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 -.B \-\-client\-disconnect -command is passed the same pathname as the corresponding -.B \-\-client\-connect -command as its last argument. (after any arguments specified in -.B cmd -). -.B -.\"********************************************************* -.TP -.B \-\-client\-config\-dir dir -Specify a directory -.B 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 -.B \-\-ifconfig\-push, -as well as fixed subnets owned by the client using -.B \-\-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: -.B \-\-push, \-\-push\-reset, \-\-push\-remove, \-\-iroute, \-\-ifconfig\-push, -and -.B \-\-config. -.\"********************************************************* +.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 -.B \-\-client\-config\-dir -file. -.\"********************************************************* -.TP -.B \-\-tmp\-dir dir -Specify a directory -.B 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: - -* -.B \-\-client\-connect -scripts to dynamically generate client\-specific -configuration files. - -* -.B OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY -plugin hook to return success/failure via auth_control_file -when using deferred auth method - -* -.B OPENVPN_PLUGIN_ENABLE_PF -plugin hook to pass filtering rules via pf_file -.\"********************************************************* -.TP -.B \-\-hash\-size r v -Set the size of the real address hash table to -.B r -and the virtual address table to -.B v. -By default, both tables are sized at 256 buckets. -.\"********************************************************* +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 \-\-bcast\-buffers n -Allocate -.B n -buffers for broadcast datagrams (default=256). -.\"********************************************************* +.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 \-\-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. -.\"********************************************************* +.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 \-\-tcp\-nodelay -This macro sets the TCP_NODELAY socket flag on the server -as well as pushes it to connecting clients. The TCP_NODELAY -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, TCP_NODELAY -is generally a good latency optimization. - -The macro expands as follows: - +.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 3 -.in +4 - if mode server: - socket\-flags TCP_NODELAY - push "socket\-flags TCP_NODELAY" -.in -4 -.ft +.ft C +ifconfig\-pool start\-IP end\-IP [netmask] +.ft P .fi -.\"********************************************************* -.TP -.B \-\-max\-clients n -Limit server to a maximum of -.B n -concurrent clients. -.\"********************************************************* -.TP -.B \-\-max\-routes\-per\-client n -Allow a maximum of -.B 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 -.B \-\-client\-config\-dir -file or auto\-generated by a -.B \-\-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. -.\"********************************************************* -.TP -.B \-\-stale\-routes\-check n [t] -Remove routes haven't had activity for -.B n -seconds (i.e. the ageing time). - -This check is ran every -.B t -seconds (i.e. check interval). - -If -.B t -is not present it defaults to -.B n - -This option helps to keep the dynamic routing table small. -See also -.B \-\-max\-routes\-per\-client -.\"********************************************************* -.TP -.B \-\-connect\-freq n sec -Allow a maximum of -.B n -new connections per -.B sec -seconds from clients. 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 -.B \-\-proto udp -and either -.B \-\-tls\-auth -or -.B \-\-tls\-crypt\fR. -.\"********************************************************* +.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. If the host part of the given IPv6 +address is \fB0\fP, the pool starts at \fBipv6addr\fP +1. +.TP +.BI \-\-ifconfig\-pool\-persist \ args +Persist/unpersist ifconfig\-pool data to \fBfile\fP, at \fBseconds\fP +intervals (default \fB600\fP), as well as on program startup and shutdown. +.sp +Valid syntax: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +ifconfig\-pool\-persist file [seconds] +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The goal of this option is to provide a long\-term association between +clients (denoted by their common name) and the virtual IP address +assigned to them from the ifconfig\-pool. Maintaining a long\-term +association is good for clients because it allows them to effectively +use the \fB\-\-persist\-tun\fP option. +.sp +\fBfile\fP is a comma\-delimited ASCII file, formatted as +\fB<Common\-Name>,<IP\-address>\fP\&. +.sp +If \fBseconds\fP = \fB0\fP, \fBfile\fP will be treated as read\-only. This +is useful if you would like to treat \fBfile\fP as a configuration file. +.sp +Note that the entries in this file are treated by OpenVPN as +\fIsuggestions\fP only, based on past associations between a common name and +IP address. They do not guarantee that the given common name will always +receive the given IP address. If you want guaranteed assignment, use +\fB\-\-ifconfig\-push\fP +.TP +.BI \-\-ifconfig\-push \ args +Push virtual IP endpoints for client tunnel, overriding the +\fB\-\-ifconfig\-pool\fP dynamic allocation. +.sp +Valid syntax: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +ifconfig\-push local remote\-netmask [alias] +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The parameters \fBlocal\fP and \fBremote\-netmask\fP are set according to the +\fB\-\-ifconfig\fP directive which you want to execute on the client machine +to configure the remote end of the tunnel. Note that the parameters +\fBlocal\fP and \fBremote\-netmask\fP are from the perspective of the client, +not the server. They may be DNS names rather than IP addresses, in which +case they will be resolved on the server at the time of client +connection. +.sp +The optional \fBalias\fP parameter may be used in cases where NAT causes +the client view of its local endpoint to differ from the server view. In +this case \fBlocal/remote\-netmask\fP will refer to the server view while +\fBalias/remote\-netmask\fP will refer to the client view. +.sp +This option must be associated with a specific client instance, which +means that it must be specified either in a client instance config file +using \fB\-\-client\-config\-dir\fP or dynamically generated using a +\fB\-\-client\-connect\fP script. +.sp +Remember also to include a \fB\-\-route\fP directive in the main OpenVPN +config file which encloses \fBlocal\fP, so that the kernel will know to +route it to the server\(aqs TUN/TAP interface. +.sp +OpenVPN\(aqs internal client IP address selection algorithm works as +follows: +.INDENT 7.0 +.IP 1. 3 +Use \fB\-\-client\-connect script\fP generated file for static IP +(first choice). +.IP 2. 3 +Use \fB\-\-client\-config\-dir\fP file for static IP (next choice). +.IP 3. 3 +Use \fB\-\-ifconfig\-pool\fP allocation for dynamic IP (last +choice). +.UNINDENT +.TP +.BI \-\-ifconfig\-ipv6\-push \ args +for \fB\-\-client\-config\-dir\fP per\-client static IPv6 interface +configuration, see \fB\-\-client\-config\-dir\fP and \fB\-\-ifconfig\-push\fP for +more details. +.sp +Valid syntax: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +ifconfig\-ipv6\-push ipv6addr/bits ipv6remote +.ft P +.fi +.UNINDENT +.UNINDENT +.TP +.BI \-\-inetd \ args +Valid syntaxes: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +inetd +inetd wait +inetd nowait +inetd wait progname +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Use this option when OpenVPN is being run from the inetd or \fBxinetd\fP(8) +server. +.sp +The \fBwait\fP and \fBnowait\fP option must match what is specified +in the inetd/xinetd config file. The \fBnowait\fP mode can only be used +with \fB\-\-proto tcp\-server\fP The default is \fBwait\fP\&. The +\fBnowait\fP mode can be used to instantiate the OpenVPN daemon as a +classic TCP server, where client connection requests are serviced on a +single port number. For additional information on this kind of +configuration, see the OpenVPN FAQ: +\fI\%https://community.openvpn.net/openvpn/wiki/325\-openvpn\-as\-a\-\-forking\-tcp\-server\-which\-can\-service\-multiple\-clients\-over\-a\-single\-tcp\-port\fP +.sp +This option precludes the use of \fB\-\-daemon\fP, \fB\-\-local\fP or +\fB\-\-remote\fP\&. Note that this option causes message and error output to +be handled in the same way as the \fB\-\-daemon\fP option. The optional +\fBprogname\fP parameter is also handled exactly as in \fB\-\-daemon\fP\&. +.sp +Also note that in \fBwait\fP mode, each OpenVPN tunnel requires a separate +TCP/UDP port and a separate inetd or xinetd entry. See the OpenVPN 1.x +HOWTO for an example on using OpenVPN with xinetd: +\fI\%https://openvpn.net/community\-resources/1xhowto/\fP .TP -.B \-\-learn\-address cmd -Run command -.B cmd -to validate client virtual addresses or routes. - -.B 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. - -Three arguments will be appended to any arguments in -.B cmd -as follows: - -.B [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. -.br -.B [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 -.B \-\-dev tap -is being used) such as "00:FF:01:02:03:04". -.br -.B [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 -.B 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. -.\"********************************************************* -.TP -.B \-\-auth\-user\-pass\-verify cmd method -Require the client to provide a username/password (possibly -in addition to a client certificate) for authentication. - -OpenVPN will run -.B command cmd -to validate the username/password -provided by the client. - -.B 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. - -If -.B method -is set to "via\-env", OpenVPN will call -.B script -with the environmental variables -.B username -and -.B password -set to the username/password strings provided by the client. -Be aware that this method is insecure on some platforms which -make the environment of a process publicly visible to other -unprivileged processes. - -If -.B 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 -.B script, -and the file will be automatically deleted by OpenVPN after -the script returns. The location of the temporary file is -controlled by the -.B \-\-tmp\-dir -option, and will default to the current directory if unspecified. -For security, consider setting -.B \-\-tmp\-dir -to a volatile storage medium such as -.B /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 -.B sample\-scripts/auth\-pam.pl -in the OpenVPN source distribution. -.\"********************************************************* -.TP -.B \-\-auth\-gen\-token [lifetime] -After successful user/password authentication, the OpenVPN -server will with this option generate a temporary -authentication token and push that to 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 -.B 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. - -This feature is useful for environments which is 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. -.\"********************************************************* +.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. - -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, no\-iv, tls\-auth, key\-method, tls\-server, and tls\-client. - -This option requires that -.B \-\-disable\-occ -NOT be used. -.\"********************************************************* -.TP -.B \-\-auth\-user\-pass\-optional -Allow connections by clients that do not specify a username/password. -Normally, when -.B \-\-auth\-user\-pass\-verify -or -.B \-\-management\-client\-auth -is 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 \-\-client\-cert\-not\-required -.B DEPRECATED -This option will be removed in OpenVPN 2.5 - -Don't require client certificate, client will authenticate -using username/password only. Be aware that using this directive -is less secure than requiring certificates from all clients. - -.B Please note: -This is replaced by -.B \-\-verify\-client\-cert -which allows for more flexibility. The option -.B \-\-verify\-client\-cert none -is functionally equivalent to -.B \-\-client\-cert\-not\-required -. - -.\"********************************************************* +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 -.B \-\-verify\-client\-cert none|optional|require -Specify whether the client is required to supply a valid certificate. - -Possible options are - -.B none -: a client certificate is not required. the client need 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 -.B \-\-auth\-user\-pass\-verify -script, so keep in mind that bugs in your script -could potentially compromise the security of your VPN. - -.B \-\-verify\-client\-cert none -is functionally equivalent to -.B \-\-client\-cert\-not\-required. - -.B optional -: a client may present a certificate but it is not required to do so. -When using this directive, you should also use a -.B \-\-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 -.B \-\-auth\-user\-pass\-verify -script, so keep in mind that bugs in your script -could potentially compromise the security of your VPN. - -.B 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 -.B \-\-verify\-client\-cert require -) but you also specify an -.B \-\-auth\-user\-pass\-verify -script, then OpenVPN will perform double authentication. The -client certificate verification AND the -.B \-\-auth\-user\-pass\-verify -script will need to succeed in order for a client to be -authenticated and accepted onto the VPN. -.\"********************************************************* +.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 \-\-username\-as\-common\-name -For -.B \-\-auth\-user\-pass\-verify -authentication, use -the authenticated username as the common name, -rather than the common name from the client cert. -.\"********************************************************* -.TP -.B \-\-compat\-names [no\-remapping] -.B DEPRECATED -This option will be removed in OpenVPN 2.5 - -Until OpenVPN v2.3 the format of the X.509 Subject fields was formatted -like this: -.IP -.B -/C=US/L=Somewhere/CN=John Doe/emailAddress=john@example.com -.IP -In addition the old behaviour was to remap any character other than -alphanumeric, underscore ('_'), dash ('\-'), dot ('.'), and slash ('/') to -underscore ('_'). The X.509 Subject string as returned by the -.B tls_id -environmental variable, could additionally contain colon (':') or equal ('='). -.IP -When using the -.B \-\-compat\-names -option, this old formatting and remapping will be re\-enabled again. This is -purely implemented for compatibility reasons when using older plug\-ins or -scripts which does not handle the new formatting or UTF\-8 characters. -.IP -In OpenVPN 2.3 the formatting of these fields changed into a more -standardised format. It now looks like: -.IP -.B -C=US, L=Somewhere, CN=John Doe, emailAddress=john@example.com -.IP -The new default format in OpenVPN 2.3 also does not do the character remapping -which happened earlier. This new format enables proper support for UTF\-8 -characters in the usernames, X.509 Subject fields and Common Name variables and -it complies to the RFC 2253, UTF\-8 String Representation of Distinguished -Names. - -The -.B no\-remapping -mode flag can be used with the -.B -\-\-compat\-names -option to be compatible with the now deprecated \-\-no\-name\-remapping option. -It is only available at the server. When this mode flag is used, the Common Name, -Subject, and username strings are allowed to include any printable character -including space, but excluding control characters such as tab, newline, and -carriage\-return. no\-remapping is only available on the server side. - -.B Please note: -This option is immediately deprecated. It is only implemented -to make the transition to the new formatting less intrusive. It will be -removed in OpenVPN 2.5. So please update your scripts/plug\-ins where necessary. -.\"********************************************************* -.TP -.B \-\-no\-name\-remapping -.B DEPRECATED -This option will be removed in OpenVPN 2.5 - -The -.B \-\-no\-name\-remapping -option is an alias for -.B \-\-compat\-names\ no\-remapping. -It ensures compatibility with server configurations using the -.B \-\-no\-name\-remapping -option. - -.B Please note: -This option is now deprecated. It will be removed in OpenVPN 2.5. -So please make sure you support the new X.509 name formatting -described with the -.B \-\-compat\-names -option as soon as possible. -.\"********************************************************* -.TP -.B \-\-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 -.B host:port. -Currently only designed to work with HTTP/HTTPS, -though it would be theoretically possible to extend to -other protocols such as ssh. - -.B 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. -.\"********************************************************* -.SS Client Mode -Use client mode when connecting to an OpenVPN server -which has -.B \-\-server, \-\-server\-bridge, -or -.B \-\-mode server -in it's configuration. -.\"********************************************************* +.B \-\-push\-peer\-info +Push additional information about the client to server. The following +data is always pushed to the server: +.INDENT 7.0 +.TP +.B \fBIV_VER=<version>\fP +The client OpenVPN version +.TP +.B \fBIV_PLAT=[linux|solaris|openbsd|mac|netbsd|freebsd|win]\fP +The client OS platform +.TP +.B \fBIV_LZO_STUB=1\fP +If client was built with LZO stub capability +.TP +.B \fBIV_LZ4=1\fP +If the client supports LZ4 compressions. +.TP +.B \fBIV_PROTO\fP +Details about protocol extensions that the peer supports. The +variable is a bitfield and the bits are defined as follows +(starting a bit 0 for the first (unused) bit: +.INDENT 7.0 +.IP \(bu 2 +bit 1: The peer supports peer\-id floating mechanism +.IP \(bu 2 +bit 2: The client expects a push\-reply and the server may +send this reply without waiting for a push\-request first. +.UNINDENT +.TP +.B \fBIV_NCP=2\fP +Negotiable ciphers, client supports \fB\-\-cipher\fP pushed by +the server, a value of 2 or greater indicates client supports +\fIAES\-GCM\-128\fP and \fIAES\-GCM\-256\fP\&. +.TP +.B \fBIV_CIPHERS=<ncp\-ciphers>\fP +The client announces the list of supported ciphers configured with the +\fB\-\-data\-ciphers\fP option to the server. +.TP +.B \fBIV_GUI_VER=<gui_id> <version>\fP +The UI version of a UI if one is running, for example +\fBde.blinkt.openvpn 0.5.47\fP for the Android app. +.TP +.B \fBIV_SSO=[crtext,][openurl,][proxy_url]\fP +Additional authentication methods supported by the client. +This may be set by the client UI/GUI using \fB\-\-setenv\fP +.UNINDENT +.sp +When \fB\-\-push\-peer\-info\fP is enabled the additional information consists +of the following data: +.INDENT 7.0 +.TP +.B \fBIV_HWADDR=<string>\fP +This is intended to be a unique and persistent ID of the client. +The string value can be any readable ASCII string up to 64 bytes. +OpenVPN 2.x and some other implementations use the MAC address of +the client\(aqs interface used to reach the default gateway. If this +string is generated by the client, it should be consistent and +preserved across independent session and preferably +re\-installations and upgrades. +.TP +.B \fBIV_SSL=<version string>\fP +The ssl version used by the client, e.g. +\fBOpenSSL 1.0.2f 28 Jan 2016\fP\&. +.TP +.B \fBIV_PLAT_VER=x.y\fP +The version of the operating system, e.g. 6.1 for Windows 7. +.TP +.B \fBUV_<name>=<value>\fP +Client environment variables whose names start with +\fBUV_\fP +.UNINDENT +.TP +.BI \-\-push\-remove \ opt +Selectively remove all \fB\-\-push\fP options matching "opt" from the option +list for a client. \fBopt\fP is matched as a substring against the whole +option string to\-be\-pushed to the client, so \fB\-\-push\-remove route\fP +would remove all \fB\-\-push route ...\fP and \fB\-\-push route\-ipv6 ...\fP +statements, while \fB\-\-push\-remove "route\-ipv6 2001:"\fP would only remove +IPv6 routes for \fB2001:...\fP networks. +.sp +\fB\-\-push\-remove\fP can only be used in a client\-specific context, like in +a \fB\-\-client\-config\-dir\fP file, or \fB\-\-client\-connect\fP script or plugin +\-\- similar to \fB\-\-push\-reset\fP, just more selective. +.sp +\fINOTE\fP: to \fIchange\fP an option, \fB\-\-push\-remove\fP can be used to first +remove the old value, and then add a new \fB\-\-push\fP option with the new +value. +.sp +\fINOTE 2\fP: due to implementation details, \(aqifconfig\(aq and \(aqifconfig\-ipv6\(aq +can only be removed with an exact match on the option ( +\fBpush\-remove ifconfig\fP), no substring matching and no matching on +the IPv4/IPv6 address argument is possible. .TP -.B \-\-client -A helper directive designed to simplify the configuration -of OpenVPN's client mode. This directive is equivalent to: - +.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. +.sp +\fINOTE\fP: \fB\-\-push\-reset\fP is very thorough: it will remove almost +all options from the list of to\-be\-pushed options. In many cases, +some of these options will need to be re\-configured afterwards \- +specifically, \fB\-\-topology subnet\fP and \fB\-\-route\-gateway\fP will get +lost and this will break client configs in many cases. Thus, for most +purposes, \fB\-\-push\-remove\fP is better suited to selectively remove +push options for individual clients. +.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 3 -.in +4 - pull - tls\-client -.in -4 -.ft +.ft C +server network netmask [nopool] +.ft P .fi -.\"********************************************************* -.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 -.B \-\-pull -option is implied by -.B \-\-client -). - -In particular, -.B \-\-pull -allows the server to push routes to the client, so you should -not use -.B \-\-pull -or -.B \-\-client -in situations where you don't trust the server to have control -over the client's routing table. -.\"********************************************************* -.TP -.B \-\-pull\-filter accept|ignore|reject \fItext\fR -Filter options received from the server if the option starts with -\fItext\fR. Runs on client. The action flag -.B accept -allows the option, -.B ignore -removes it and -.B 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 \fItext\fR against the -received option so that - +.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 3 -.in +4 -\-\-pull\-filter ignore "route" -.in -4 -.ft +.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 - -would remove all pushed options starting with -.B route -which would include, for example, -.B route\-gateway. -Enclose \fItext\fR in quotes to embed spaces. - +.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 3 -.in +4 -\-\-pull\-filter accept "route 192.168.1." -\-\-pull\-filter ignore "route " -.in -4 -.ft +.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 -would remove all routes that do not start with 192.168.1. - -This option may be used only on clients. -Note that -.B 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 -.B ignore. -.\"********************************************************* -.TP -.B \-\-auth\-user\-pass [up] -Authenticate with server using username/password. -.B up -is a file containing username/password on 2 lines. If the -password line is missing, OpenVPN will prompt for one. - -If -.B up -is omitted, username/password will be prompted from the -console. - -The server configuration must specify an -.B \-\-auth\-user\-pass\-verify -script to verify the username/password provided by -the client. -.\"********************************************************* -.TP -.B \-\-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 -.B \-\-auth\-user\-pass -authentication, or if the server\-side -.B \-\-client\-connect -script returns an error status when the client -tries to connect. - -.B type -can be one of: - -.B none \-\- -Client will exit with a fatal error (this is the default). -.br -.B nointeract \-\- -Client will retry the connection without requerying for an -.B \-\-auth\-user\-pass -username/password. Use this option for unattended clients. -.br -.B interact \-\- -Client will requery for an -.B \-\-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. -.\"********************************************************* -.TP -.B \-\-static\-challenge t e -Enable static challenge/response protocol using challenge text -.B t, -with -echo flag given by -.B e -(0|1). - -The echo flag indicates whether or not the user's response -to the challenge should be echoed. - -See management\-notes.txt in the OpenVPN distribution for a -description of the OpenVPN challenge/response protocol. -.\"********************************************************* -.TP -\fB\-\-server\-poll\-timeout n\fR, \fB\-\-connect\-timeout n\fR -When connecting to a remote server do not wait for more than -.B n -seconds waiting for a response before trying the next server. -The default value is 120s. This timeout includes proxy and TCP -connect timeouts. -.\"********************************************************* -.TP -.B \-\-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 -.B n -parameter (default=1) 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 -.B n -parameter (default=1) controls client behavior. With -.B n -= 1 client will attempt to reconnect -to the same server, with -.B n -= 2 client will advance to the next 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 -OpenVPN will not send any exit -notifications unless this option is enabled. +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 \-\-server\-ipv6 \ args +Convenience\-function to enable a number of IPv6 related options at once, +namely \fB\-\-ifconfig\-ipv6\fP, \fB\-\-ifconfig\-ipv6\-pool\fP and +\fB\-\-push tun\-ipv6\fP\&. +.sp +Valid syntax: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +server\-ipv6 ipv6addr/bits +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Pushing of the \fB\-\-tun\-ipv6\fP directive is done for older clients which +require an explicit \fB\-\-tun\-ipv6\fP in their configuration. +.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 \-\-allow\-recursive\-routing -When this option is set, OpenVPN will not drop incoming tun packets -with same destination as host. -.\"********************************************************* -.SS Data Channel Encryption Options: -These options are meaningful for both Static & TLS\-negotiated key modes -(must be compatible between peers). -.\"********************************************************* -.TP -.B \-\-secret file [direction] -Enable Static Key encryption mode (non\-TLS). -Use pre\-shared secret -.B file -which was generated with -.B \-\-genkey. - -The optional -.B 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 -.B direction -parameter is omitted, 2 keys are used bidirectionally, one for HMAC -and the other for encryption/decryption. - -The -.B 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 -.B direction -parameter requires that -.B 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 -.B direction -parameter, will also support 2048 bit key file generation -using the -.B \-\-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 -.B 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. -.\"********************************************************* +.B \-\-username\-as\-common\-name +Use the authenticated username as the common\-name, rather than the +common\-name from the client certificate. Requires that some form of +\fB\-\-auth\-user\-pass\fP verification is in effect. As the replacement happens +after \fB\-\-auth\-user\-pass\fP verification, the verification script or +plugin will still receive the common\-name from the certificate. +.sp +The common_name environment variable passed to scripts and plugins invoked +after authentication (e.g, client\-connect script) and file names parsed in +client\-config directory will match the username. +.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 \-\-key\-direction -Alternative way of specifying the optional direction parameter for the -.B \-\-tls\-auth -and -.B \-\-secret -options. Useful when using inline files (See section on inline files). -.\"********************************************************* -.TP -.B \-\-auth alg -Authenticate data channel packets and (if enabled) -.B tls\-auth -control channel packets with HMAC using message digest algorithm -.B alg. -(The default is -.B 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, the specified -.B \-\-auth -algorithm is ignored for the data channel, and the authentication method of the -AEAD cipher is used instead. Note that -.B alg -still specifies the digest used for -.B tls\-auth\fR. - -In static\-key encryption mode, the HMAC key -is included in the key file generated by -.B \-\-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 -.B alg=none -to disable authentication. - -For more information on HMAC see -.I http://www.cs.ucsd.edu/users/mihir/papers/hmac.html -.\"********************************************************* +.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 \-\-cipher alg -Encrypt data channel packets with cipher algorithm -.B alg. - -The default is -.B 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 -.B AES\-256\-GCM. -See -.B \-\-ncp\-ciphers -and -.B \-\-ncp\-disable -for more details on NCP. - -Using -.B 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 -.B BF\-CBC, DES, CAST5, IDEA -and -.B RC2 -ciphers will be removed in OpenVPN 2.6. - -To see other ciphers that are available with OpenVPN, use the .B \-\-show\-ciphers +(Standalone) Show all cipher algorithms to use with the \fB\-\-cipher\fP option. - -Set -.B alg=none -to disable encryption. - -.\"********************************************************* -.TP -.B \-\-ncp\-ciphers cipher_list -Restrict the allowed ciphers to be negotiated to the ciphers in -.B cipher_list\fR. -.B cipher_list -is a colon\-separated list of ciphers, and defaults to -"AES\-256\-GCM:AES\-128\-GCM". - -For servers, the first cipher from -.B cipher_list -will be pushed to clients that support cipher negotiation. - -Cipher negotiation is enabled in client\-server mode only. I.e. if -.B \-\-mode -is set to 'server' (server\-side, implied by setting -.B \-\-server -), or if -.B \-\-pull -is specified (client\-side, implied by setting \-\-client). - -If both peers support and do not disable NCP, the negotiated cipher will -override the cipher specified by -.B \-\-cipher\fR. - -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 -.B \-\-cipher -setting, but the peer cipher is one of the ciphers specified in -.B \-\-ncp\-ciphers\fR. -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 "\-\-ncp\-ciphers -AES\-256\-GCM:AES\-256\-CBC" set can either specify "\-\-cipher BF\-CBC" or -"\-\-cipher AES\-256\-CBC" and both will work. - -.\"********************************************************* .TP -.B \-\-ncp\-disable -Disable "negotiable crypto parameters". This completely disables cipher -negotiation. -.\"********************************************************* +.B \-\-show\-digests +(Standalone) Show all message digest algorithms to use with the +\fB\-\-auth\fP option. .TP -.B \-\-keysize n -.B 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 -.B \-\-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. -.\"********************************************************* -.TP -.B \-\-prng alg [nsl] -(Advanced) For PRNG (Pseudo\-random number generator), -use digest algorithm -.B alg -(default=sha1), and set -.B nsl -(default=16) -to the size in bytes of the nonce secret length (between 16 and 64). - -Set -.B alg=none -to disable the PRNG and use the OpenSSL RAND_bytes function -instead for all of OpenVPN's pseudo\-random number needs. -.\"********************************************************* +.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 \-\-engine [engine\-name] -Enable OpenSSL hardware\-based crypto engine functionality. - -If -.B engine\-name -is specified, -use a specific crypto engine. Use the .B \-\-show\-engines -standalone option to list the crypto engines which are -supported by OpenSSL. -.\"********************************************************* -.TP -.B \-\-no\-replay -.B DEPRECATED -This option will be removed in OpenVPN 2.5. - -(Advanced) Disable OpenVPN's protection against replay attacks. -Don't use this option unless you are prepared to make -a tradeoff of greater efficiency in exchange for less -security. - -OpenVPN provides datagram replay protection by default. - -Replay protection is accomplished -by tagging each outgoing datagram with an identifier -that is guaranteed to be unique for the key being used. -The peer that receives the datagram will check for -the uniqueness of the identifier. If the identifier -was already received in a previous datagram, OpenVPN -will drop the packet. Replay protection is important -to defeat attacks such as a SYN flood attack, where -the attacker listens in the wire, intercepts a TCP -SYN packet (identifying it by the context in which -it occurs in relation to other packets), then floods -the receiving peer with copies of this packet. - -OpenVPN's replay protection is implemented in slightly -different ways, depending on the key management mode -you have selected. - -In Static Key mode -or when using an CFB or OFB mode cipher, OpenVPN uses a -64 bit unique identifier that combines a time stamp with -an incrementing sequence number. - -When using TLS mode for key exchange and a CBC cipher -mode, OpenVPN uses only a 32 bit sequence number without -a time stamp, since OpenVPN can guarantee the uniqueness -of this value for each key. As in IPSec, if the sequence number is -close to wrapping back to zero, OpenVPN will trigger -a new key exchange. - -To check for replays, OpenVPN uses -the -.I sliding window -algorithm used -by IPSec. -.\"********************************************************* -.TP -.B \-\-replay\-window n [t] -Use a replay protection sliding\-window of size -.B n -and a time window of -.B t -seconds. - -By default -.B n -is 64 (the IPSec default) and -.B t -is 15 seconds. - -This option is only relevant in UDP mode, i.e. -when either -.B \-\-proto udp -is specified, or no -.B \-\-proto -option is specified. - -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. - -.B (a) -The packet cannot be a replay (unless -.B \-\-no\-replay -is specified, which disables replay protection altogether). - -.B (b) -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 -.B n. - -.B (c) -If a packet arrives out of order, it will only be accepted if it arrives no later -than -.B t -seconds after any packet containing a higher sequence number. - -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 -.B n. -Satellite links in particular often require this. - -If you run OpenVPN at -.B \-\-verb 4, -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 -.B n. - -There is some controversy on the appropriate method of handling packet -reordering at the security layer. - -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? - -The IPSec and OpenVPN approach is to allow packet reordering within a certain -fixed sequence number window. - -OpenVPN adds to the IPSec model by limiting the window size in time as well as -sequence space. - -OpenVPN also adds TCP transport as an option (not offered by IPSec) in which -case OpenVPN can adopt a very strict attitude towards message deletion and -reordering: Don't allow it. Since TCP guarantees reliability, any packet -loss or reordering event can be assumed to be an attack. - -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. - -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 -.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 \-\-replay\-persist file -Persist replay\-protection state across sessions using -.B file -to save and reload the state. - -This option will strengthen protection against replay attacks, -especially when you are using OpenVPN in a dynamic context (such -as with -.B \-\-inetd) -when OpenVPN sessions are frequently started and stopped. - -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. - -This option only makes sense when replay protection is enabled -(the default) and you are using either -.B \-\-secret -(shared\-secret key mode) or TLS mode with -.B \-\-tls\-auth. -.\"********************************************************* -.TP -.B \-\-no\-iv -.B DEPRECATED -This option will be removed in OpenVPN 2.5. - -(Advanced) Disable OpenVPN's use of IV (cipher initialization vector). -Don't use this option unless you are prepared to make -a tradeoff of greater efficiency in exchange for less -security. - -OpenVPN uses an IV by default, and requires it for CFB and -OFB cipher modes (which are totally insecure without it). -Using an IV is important for security when multiple -messages are being encrypted/decrypted with the same key. - -IV is implemented differently depending on the cipher mode used. - -In CBC mode, OpenVPN uses a pseudo\-random IV for each packet. - -In CFB/OFB mode, OpenVPN uses a unique sequence number and time stamp -as the IV. In fact, in CFB/OFB mode, OpenVPN uses a datagram -space\-saving optimization that uses the unique identifier for -datagram replay protection as the IV. -.\"********************************************************* +(Standalone) Show currently available hardware\-based crypto acceleration +engines supported by the OpenSSL library. .TP -.B \-\-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. - -.\"********************************************************* +.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 -.B \-\-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 -.B \-\-dev -or -.B \-\-remote. - -The typical usage of -.B \-\-test\-crypto -would be something like this: - -.B openvpn \-\-test\-crypto \-\-secret key - -or - -.B 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. -.\"********************************************************* -.SS 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. - +.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 .. \fB3600\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 ( -.B \-\-cert -and -.B \-\-key -), signed by the root certificate which is specified -in -.B \-\-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 -.B \-\-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 & keys: -.I https://github.com/OpenVPN/easy\-rsa -.\"********************************************************* +certificate/key pair (\fB\-\-cert\fP and \fB\-\-key\fP), signed by the root +certificate which is specified in \fB\-\-ca\fP\&. +.sp +When two OpenVPN peers connect, each presents its local certificate to +the other. Each peer will then check that its partner peer presented a +certificate which was signed by the master root certificate as specified +in \fB\-\-ca\fP\&. +.sp +If that check on both peers succeeds, then the TLS negotiation will +succeed, both OpenVPN peers will exchange temporary session keys, and +the tunnel will begin passing data. +.sp +The OpenVPN project provides a set of scripts for managing RSA +certificates and keys: \fI\%https://github.com/OpenVPN/easy\-rsa\fP +.INDENT 0.0 +.TP +.BI \-\-askpass \ file +Get certificate password from console or \fBfile\fP before we daemonize. +.sp +Valid syntaxes: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +askpass +askpass file +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +For the extremely security conscious, it is possible to protect your +private key with a password. Of course this means that every time the +OpenVPN daemon is started you must be there to type the password. The +\fB\-\-askpass\fP option allows you to start OpenVPN from the command line. +It will query you for a password before it daemonizes. To protect a +private key with a password you should omit the \fB\-nodes\fP option when +you use the \fBopenssl\fP command line tool to manage certificates and +private keys. +.sp +If \fBfile\fP is specified, read the password from the first line of +\fBfile\fP\&. Keep in mind that storing your password in a file to a certain +extent invalidates the extra security provided by using an encrypted +key. +.TP +.BI \-\-ca \ file +Certificate authority (CA) file in .pem format, also referred to as the +\fIroot\fP certificate. This file can have multiple certificates in .pem +format, concatenated together. You can construct your own certificate +authority certificate and private key by using a command such as: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +openssl req \-nodes \-new \-x509 \-keyout ca.key \-out ca.crt +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Then edit your openssl.cnf file and edit the \fBcertificate\fP variable to +point to your new root certificate \fBca.crt\fP\&. +.sp +For testing purposes only, the OpenVPN distribution includes a sample CA +certificate (ca.crt). Of course you should never use the test +certificates and test keys distributed with OpenVPN in a production +environment, since by virtue of the fact that they are distributed with +OpenVPN, they are totally insecure. +.TP +.BI \-\-capath \ dir +Directory containing trusted certificates (CAs and CRLs). Not available +with mbed TLS. +.sp +CAs in the capath directory are expected to be named <hash>.<n>. CRLs +are expected to be named <hash>.r<n>. See the \fB\-CApath\fP option of +\fBopenssl verify\fP, and the \fB\-hash\fP option of \fBopenssl x509\fP, +\fBopenssl crl\fP and \fBX509_LOOKUP_hash_dir()\fP(3) +for more information. +.sp +Similar to the \fB\-\-crl\-verify\fP option, CRLs are not mandatory \- +OpenVPN will log the usual warning in the logs if the relevant CRL is +missing, but the connection will be allowed. +.TP +.BI \-\-cert \ file +Local peer\(aqs signed certificate in .pem format \-\- must be signed by a +certificate authority whose certificate is in \fB\-\-ca file\fP\&. Each peer +in an OpenVPN link running in TLS mode should have its own certificate +and private key file. In addition, each certificate should have been +signed by the key of a certificate authority whose public key resides in +the \fB\-\-ca\fP certificate authority file. You can easily make your own +certificate authority (see above) or pay money to use a commercial +service such as thawte.com (in which case you will be helping to finance +the world\(aqs second space tourist :). To generate a certificate, you can +use a command such as: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +openssl req \-nodes \-new \-keyout mycert.key \-out mycert.csr +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +If your certificate authority private key lives on another machine, copy +the certificate signing request (mycert.csr) to this other machine (this +can be done over an insecure channel such as email). Now sign the +certificate with a command such as: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +openssl ca \-out mycert.crt \-in mycert.csr +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Now copy the certificate (mycert.crt) back to the peer which initially +generated the .csr file (this can be over a public medium). Note that +the \fBopenssl ca\fP command reads the location of the certificate +authority key from its configuration file such as +\fB/usr/share/ssl/openssl.cnf\fP \-\- note also that for certificate +authority functions, you must set up the files \fBindex.txt\fP (may be +empty) and \fBserial\fP (initialize to \fB01\fP). +.TP +.BI \-\-crl\-verify \ args +Check peer certificate against a Certificate Revocation List. +.sp +Valid syntax: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +crl\-verify file/directory flag +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Examples: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +crl\-verify crl\-file.pem +crl\-verify /etc/openvpn/crls dir +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +A CRL (certificate revocation list) is used when a particular key is +compromised but when the overall PKI is still intact. +.sp +Suppose you had a PKI consisting of a CA, root certificate, and a number +of client certificates. Suppose a laptop computer containing a client +key and certificate was stolen. By adding the stolen certificate to the +CRL file, you could reject any connection which attempts to use it, +while preserving the overall integrity of the PKI. +.sp +The only time when it would be necessary to rebuild the entire PKI from +scratch would be if the root certificate key itself was compromised. +.sp +The option is not mandatory \- if the relevant CRL is missing, OpenVPN +will log a warning in the logs \- e.g. +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +VERIFY WARNING: depth=0, unable to get certificate CRL +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +but the connection will be allowed. If the optional \fBdir\fP flag +is specified, enable a different mode where the \fBcrl\-verify\fP is +pointed at a directory containing files named as revoked serial numbers +(the files may be empty, the contents are never read). If a client +requests a connection, where the client certificate serial number +(decimal string) is the name of a file present in the directory, it will +be rejected. +.INDENT 7.0 +.TP +.B \fINote:\fP +As the crl file (or directory) is read every time a peer +connects, if you are dropping root privileges with +\fB\-\-user\fP, make sure that this user has sufficient +privileges to read the file. +.UNINDENT +.TP +.BI \-\-dh \ file +File containing Diffie Hellman parameters in .pem format (required for +\fB\-\-tls\-server\fP only). +.sp +Set \fBfile\fP to \fBnone\fP to disable Diffie Hellman key exchange (and +use ECDH only). Note that this requires peers to be using an SSL library +that supports ECDH TLS cipher suites (e.g. OpenSSL 1.0.1+, or +mbed TLS 2.0+). +.sp +Use \fBopenssl dhparam \-out dh2048.pem 2048\fP to generate 2048\-bit DH +parameters. Diffie Hellman parameters may be considered public. +.TP +.BI \-\-ecdh\-curve \ name +Specify the curve to use for elliptic curve Diffie Hellman. Available +curves can be listed with \fB\-\-show\-curves\fP\&. The specified curve will +only be used for ECDH TLS\-ciphers. +.sp +This option is not supported in mbed TLS builds of OpenVPN. .TP -.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. -.\"********************************************************* +.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. +.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. +.sp +The default for \fI\-\-tls\-ciphersuites\fP is to use the crypto library\(aqs +default. .TP .B \-\-tls\-client Enable TLS and assume client role during TLS handshake. -.\"********************************************************* .TP -.B \-\-ca file -Certificate authority (CA) file in .pem format, also referred to as the -.I 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: - -.B openssl req \-nodes \-new \-x509 \-keyout ca.key \-out ca.crt - -Then edit your openssl.cnf file and edit the -.B certificate -variable to point to your new root certificate -.B 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. -.\"********************************************************* -.TP -.B \-\-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 -.B \-CApath -option of -.B openssl verify -, and the -.B \-hash -option of -.B openssl x509 -, -.B openssl crl -and -.BR X509_LOOKUP_hash_dir (3) -for more information. - -Similarly to the -.B \-\-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. -.\"********************************************************* -.TP -.B \-\-dh file -File containing Diffie Hellman parameters -in .pem format (required for -.B \-\-tls\-server -only). - -Set -.B file=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 -.B openssl dhparam \-out dh2048.pem 2048 -to generate 2048\-bit DH parameters. Diffie Hellman parameters may be considered -public. -.\"********************************************************* +.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 \-\-ecdh\-curve name -Specify the curve to use for elliptic curve Diffie Hellman. Available -curves can be listed with -.BR \-\-show\-curves . -The specified curve will only be used for ECDH TLS\-ciphers. - -This option is not supported in mbed TLS builds of OpenVPN. -.\"********************************************************* -.TP -.B \-\-cert file -Local peer's signed certificate in .pem format \-\- must be signed -by a certificate authority whose certificate is in -.B \-\-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 -.B \-\-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: - -.B 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: - -.B 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 -.B openssl ca -command reads the location of the certificate authority key from its -configuration file such as -.B /usr/share/ssl/openssl.cnf -\-\- note also -that for certificate authority functions, you must set up the files -.B index.txt -(may be empty) and -.B serial -(initialize to -.B -01 -). -.\"********************************************************* -.TP -.B \-\-extra\-certs file -Specify a -.B 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 -.B ca -file. -.\"********************************************************* -.TP -.B \-\-key file -Local peer's private key in .pem format. Use the private key which was generated -when you built your peer's certificate (see -.B \-\-cert file -above). -.\"********************************************************* -.TP -.B \-\-tls\-version\-min version ['or\-highest'] -Sets the minimum -TLS version we will accept from the peer (default is "1.0"). -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. -.\"********************************************************* -.TP -.B \-\-tls\-version\-max version +.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 "1.0", "1.1", or "1.2". -.\"********************************************************* -.TP -.B \-\-pkcs12 file -Specify a PKCS #12 file containing local private key, -local certificate, and root CA certificate. -This option can be used instead of -.B \-\-ca, \-\-cert, -and -.B \-\-key. -Not available with mbed TLS. -.\"********************************************************* -.TP -.B \-\-verify\-hash hash [algo] -Specify SHA1 or SHA256 fingerprint for level\-1 cert. 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 -.B hash -or certificate verification will fail. Hash is specified -as XX:XX:... For example: - +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 3 -.in +4 +.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 -.in -4 -.ft +.ft P .fi - -The -.B algo -flag can be either SHA1 or SHA256. If not provided, it defaults to SHA1. -.\"********************************************************* +.UNINDENT +.UNINDENT +.sp +The \fBalgo\fP flag can be either \fBSHA1\fP or \fBSHA256\fP\&. If not +provided, it defaults to \fBSHA1\fP\&. +.TP +.BI \-\-verify\-x509\-name \ args +Accept connections only if a host\(aqs X.509 name is equal to \fBname.\fP The +remote host must also pass all other tests of verification. +.sp +Valid syntax: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +verify\-x509 name type +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Which X.509 name is compared to \fBname\fP depends on the setting of type. +\fBtype\fP can be \fBsubject\fP to match the complete subject DN +(default), \fBname\fP to match a subject RDN or \fBname\-prefix\fP to +match a subject RDN prefix. Which RDN is verified as name depends on the +\fB\-\-x509\-username\-field\fP option. But it defaults to the common name +(CN), e.g. a certificate with a subject DN +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +C=KG, ST=NA, L=Bishkek, CN=Server\-1 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +would be matched by: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +verify\-x509\-name \(aqC=KG, ST=NA, L=Bishkek, CN=Server\-1\(aq +verify\-x509\-name Server\-1 name +verify\-x509\-name Server\- name\-prefix +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The last example is useful if you want a client to only accept +connections to \fBServer\-1\fP, \fBServer\-2\fP, etc. +.sp +\fB\-\-verify\-x509\-name\fP is a useful replacement for the \fB\-\-tls\-verify\fP +option to verify the remote host, because \fB\-\-verify\-x509\-name\fP works +in a \fB\-\-chroot\fP environment without any dependencies. +.sp +Using a name prefix is a useful alternative to managing a CRL +(Certificate Revocation List) on the client, since it allows the client +to refuse all certificates except for those associated with designated +servers. +.INDENT 7.0 +.TP +.B \fINOTE:\fP +Test against a name prefix only when you are using OpenVPN +with a custom CA certificate that is under your control. Never use +this option with type \fBname\-prefix\fP when your client +certificates are signed by a third party, such as a commercial +web CA. +.UNINDENT +.TP +.BI \-\-x509\-track \ attribute +Save peer X509 \fBattribute\fP value in environment for use by plugins and +management interface. Prepend a \fB+\fP to \fBattribute\fP to save values +from full cert chain. Values will be encoded as +\fBX509_<depth>_<attribute>=<value>\fP\&. Multiple \fB\-\-x509\-track\fP +options can be defined to track multiple attributes. .TP -.B \-\-pkcs11\-cert\-private [0|1]... +.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 -.B \-\-pkcs11\-id name +.BI \-\-pkcs11\-id \ name Specify the serialized certificate id to be used. The id can be gotten -by the standalone -.B \-\-show\-pkcs11\-ids -option. -.\"********************************************************* +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 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. -.\"********************************************************* -.TP -.B \-\-pkcs11\-pin\-cache seconds -Specify how many seconds the PIN can be cached, the default is until the token is removed. -.\"********************************************************* -.TP -.B \-\-pkcs11\-protected\-authentication [0|1]... -Use PKCS#11 protected authentication path, useful for biometric and external -keypad devices. -Every provider has its own setting. -.\"********************************************************* -.TP -.B \-\-pkcs11\-providers provider... -Specify a RSA Security Inc. PKCS #11 Cryptographic Token Interface (Cryptoki) providers -to load. -This option can be used instead of -.B \-\-cert, \-\-key, -and -.B \-\-pkcs12. - -If p11\-kit is present on the system, its -.B p11\-kit\-proxy.so -module will be loaded by default if either the -.B \-\-pkcs11\-id -or -.B \-\-pkcs11\-id\-management -options are specified without -.B \-\-pkcs11\-provider -being given. -.\"********************************************************* +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 -.B \-\-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: - -.B 0 -(default) \-\- Try to determine automatically. -.br -.B 1 -\-\- Use sign. -.br -.B 2 -\-\- Use sign recover. -.br -.B 4 -\-\- Use decrypt. -.br -.B 8 -\-\- Use unwrap. -.br -.\"********************************************************* -.TP -.B \-\-cryptoapicert select\-string -Load the certificate and private key from the -Windows Certificate System Store (Windows/OpenSSL Only). - -Use this option instead of -.B \-\-cert -and -.B \-\-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: - -.B cryptoapicert -"SUBJ:Peter Runestig" - -To select a certificate, based on certificate's thumbprint: - -.B cryptoapicert -"THUMB:f6 49 24 41 01 b4 ..." - -The thumbprint hex string can easily be copy\-and\-pasted from the Windows -Certificate Store GUI. - -.\"********************************************************* +.BI \-\-pkcs11\-pin\-cache \ seconds +Specify how many seconds the PIN can be cached, the default is until the +token is removed. .TP -.B \-\-key\-method m -.B DEPRECATED -This option will be removed in OpenVPN 2.5 - -Use data channel key negotiation method -.B m. -The key method must match on both sides of the connection. - -After OpenVPN negotiates a TLS session, a new set of keys -for protecting the tunnel data channel is generated and -exchanged over the TLS session. - -In method 1 (the default for OpenVPN 1.x), both sides generate -random encrypt and HMAC\-send keys which are forwarded to -the other host over the TLS channel. Method 1 is -.B deprecated in OpenVPN 2.4 -, and -.B will be removed in OpenVPN 2.5\fR. - -In method 2, (the default for OpenVPN 2.0) -the client generates a random key. Both client -and server also generate some random seed material. All key source -material is exchanged over the TLS channel. The actual -keys are generated using the TLS PRF function, taking source -entropy from both client and server. Method 2 is designed to -closely parallel the key generation process used by TLS 1.0. - -Note that in TLS mode, two separate levels -of keying occur: - -(1) The TLS connection is initially negotiated, with both sides -of the connection producing certificates and verifying the certificate -(or other authentication info provided) of -the other side. The -.B \-\-key\-method -parameter has no effect on this process. - -(2) After the TLS connection is established, the tunnel session keys are -separately negotiated over the existing secure TLS channel. Here, -.B \-\-key\-method -determines the derivation of the tunnel session keys. -.\"********************************************************* -.TP -.B \-\-tls\-cipher l -.TQ -.B \-\-tls\-ciphersuites l -A list -.B 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 -.B \-\-tls-cipher -is used for TLS 1.2 and below. For TLS 1.3 and up, the -.B \-\-tls\-ciphersuites -setting is used. mbed TLS has no TLS 1.3 support yet and only the -.B \-\-tls-cipher -setting is used. - -Use -.B \-\-show\-tls -to see a list of TLS ciphers supported by your crypto library. - -Warning! -.B \-\-tls\-cipher -and -.B \-\-tls\-ciphersuites -are expert features, which \- if used correcly \- 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! - -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. -.\"********************************************************* +.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 \-\-tls\-cert\-profile profile -Set the allowed cryptographic algorithms for certificates according to -.B profile\fN. - -The following profiles are supported: - -.B legacy -(default): SHA1 and newer, RSA 2048-bit+, any elliptic curve. - -.B preferred -: SHA2 and newer, RSA 2048-bit+, any elliptic curve. - -.B 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: - -.B legacy -(default): sets "security level 1" - -.B preferred -: sets "security level 2" - -.B 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. -.\"********************************************************* -.TP -.B \-\-tls\-timeout n -Packet retransmit timeout on TLS control channel -if no acknowledgment from remote within -.B n -seconds (default=2). When OpenVPN sends a control -packet to its peer, it will expect to receive an -acknowledgement within -.B 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. -.\"********************************************************* -.TP -.B \-\-reneg\-bytes n -Renegotiate data channel key after -.B 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 -.B HIGHLY DISCOURAGED -as this is designed to add some protection against the SWEET32 attack vector. -For more information see the \-\-cipher option. -.\"********************************************************* -.TP -.B \-\-reneg\-pkts n -Renegotiate data channel key after -.B n -packets sent and received (disabled by default). -.\"********************************************************* -.TP -.B \-\-reneg\-sec n -Renegotiate data channel key after -.B n -seconds (default=3600). - -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 -.B \-\-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. -.\"********************************************************* -.TP -.B \-\-hand\-window n -Handshake Window \-\- the TLS\-based key exchange must finalize within -.B 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 -.B \-\-tran\-window -seconds to maintain continuity of transmission of tunnel -data. -.\"********************************************************* -.TP -.B \-\-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. -.\"********************************************************* +.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 -.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. - -If the daemon is reset by a signal or -.B \-\-ping\-restart, -it will allow one new connection. - -.B \-\-single\-session -can be used with -.B \-\-ping\-exit -or -.B \-\-inactive -to create a single dynamic session that will exit when finished. -.\"********************************************************* +.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 -.B \-\-tls\-exit -Exit on TLS negotiation failure. -.\"********************************************************* +.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 -.B \-\-tls\-auth file [direction] -Add an additional layer of HMAC authentication on top of the TLS control channel -to mitigate DoS attacks and attacks on the TLS stack. - -In a nutshell, -.B \-\-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. - -.B file -(required) is a file in OpenVPN static key format which can be generated by -.B \-\-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 -.B \-\-secret -option for more information on the optional -.B direction -parameter. - -.B \-\-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 -.B \-\-remote -is not specified, or -.B \-\-remote -is specified with -.B \-\-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. - -.B \-\-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. -.B \-\-tls\-auth -can be strengthened by adding the -.B \-\-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 -.B \-\-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 -.B \-\-tls\-crypt -instead if you want to use the key file to not only authenticate, but also -encrypt the TLS control channel. -.\"********************************************************* +.BI \-\-lport \ port +Set local TCP/UDP port number or name. Cannot be used together with +\fB\-\-nobind\fP option. .TP -.B \-\-tls\-crypt keyfile - -Encrypt and authenticate all control channel packets with the key from -.B keyfile. -(See -.B \-\-tls\-auth -for more background.) - -Encrypting (and authenticating) control channel packets: -.RS -.IP \[bu] 2 -provides more privacy by hiding the certificate used for the TLS connection, -.IP \[bu] -makes it harder to identify OpenVPN traffic as such, -.IP \[bu] -provides "poor\-man's" post\-quantum security, against attackers who will never -know the pre\-shared key (i.e. no forward secrecy). -.RE - -.IP -In contrast to -.B \-\-tls\-auth\fR, -.B \-\-tls\-crypt -does *not* require the user to set -.B \-\-key\-direction\fR. - -.B Security Considerations - -All peers use the same -.B \-\-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 -.B \-\-tls\-crypt -degrading to the same security as using -.B \-\-tls\-auth\fR. -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. -.\"********************************************************* -.TP -.B \-\-askpass [file] -Get certificate password from console or -.B file -before we daemonize. - -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 -.B \-\-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 -.B \-nodes -option when you use the -.B openssl -command line tool to manage certificates and private keys. - -If -.B file -is specified, read the password from the first line of -.B 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. -.\"********************************************************* +.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 -.B \-\-auth\-nocache -Don't cache -.B \-\-askpass -or -.B \-\-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 -.B \-\-http\-proxy -username/password. It is always cached. -.\"********************************************************* +.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 -.B \-\-auth\-token token -This is not an option to be used directly in any configuration files, -but rather push this option from a -.B \-\-client\-connect -script or a -.B \-\-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 -.B \-\-auth\-user\-pass\-verify -script or -.B \-\-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 have been set. If -the OpenVPN server side rejects the authentication token, the -client will receive an AUTH_FAIL 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 -.B \-\-client\-connect -script or -.B \-\-plugin -needs to put - +.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 3 -.in +4 -push "auth\-token UNIQUE_TOKEN_VALUE" -.in -4 -.ft +.ft C +\-\-tun\-mtu 1500 \-\-fragment 1300 \-\-mssfix +.ft P .fi - -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 acording to -.B \-\-auth-retry -. -.\"********************************************************* -.TP -.B \-\-tls\-verify cmd -Run command -.B cmd -to verify the X509 name of a -pending TLS connection that has otherwise passed all other -tests of certification (except for revocation via -.B \-\-crl\-verify -directive; the revocation test occurs after the -.B \-\-tls\-verify -test). - -.B cmd -should return 0 to allow the TLS handshake to proceed, or 1 to fail. - -.B 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. - -When -.B cmd -is executed two arguments are appended after any arguments specified in -.B cmd -, as follows: - -.B 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 -.B verify\-cn -in the OpenVPN distribution. - -See the "Environmental Variables" section below for -additional parameters passed as environmental variables. -.\"********************************************************* -.TP -.B \-\-tls\-export\-cert directory -Store the certificates the clients uses 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. -.\"********************************************************* -.TP -.B \-\-x509\-username\-field [ext:\]fieldname -Field in the X.509 certificate subject to be used as the username (default=CN). -Typically, this option is specified with -.B fieldname -as either of the following: - -.B \-\-x509\-username\-field -emailAddress -.br -.B \-\-x509\-username\-field ext:\fRsubjectAltName - -The first example uses the value of the "emailAddress" attribute in the -certificate's Subject field as the username. The second example uses -the -.B ext: -prefix to signify that the X.509 extension -.B fieldname -"subjectAltName" be searched for an rfc822Name (email) field to be used -as the username. In cases where there are multiple email addresses -in -.B ext:fieldname\fR, -the last occurrence is chosen. - -When this option is used, the -.B \-\-verify\-x509\-name -option will match against the chosen -.B fieldname -instead of the Common Name. - -Only the subjectAltName and issuerAltName X.509 extensions are supported. - -.B Please note: -This option has a feature which will convert an all\-lowercase -.B fieldname -to uppercase characters, e.g., ou \-> OU. A mixed\-case -.B fieldname -or one having the -.B ext: -prefix will be left as\-is. This automatic upcasing feature -is deprecated and will be removed in a future release. -.\"********************************************************* -.TP -.B \-\-verify\-x509\-name name type -Accept connections only if a host's X.509 name is equal to -.B name. -The remote host must also pass all other tests of verification. - -Which X.509 name is compared to -.B name -depends on the setting of type. -.B 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 -.B \-\-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: - -.B \-\-verify\-x509\-name 'C=KG, ST=NA, L=Bishkek, CN=Server\-1' -and -.B \-\-verify\-x509\-name Server\-1 name -or you could use -.B \-\-verify\-x509\-name Server\- name\-prefix -if you want a client to only accept connections to "Server\-1", "Server\-2", etc. - -.B \-\-verify\-x509\-name -is a useful replacement for the -.B \-\-tls\-verify -option to verify the remote host, because -.B \-\-verify\-x509\-name -works in a -.B \-\-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. - -.B 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. -.\"********************************************************* -.TP -.B \-\-x509\-track attribute -Save peer X509 -.B attribute -value in environment for use by plugins and management interface. -Prepend a '+' to -.B attribute -to save values from full cert chain. Values will be encoded -as X509_<depth>_<attribute>=<value>. Multiple -.B \-\-x509\-track -options can be defined to track multiple attributes. -.\"********************************************************* +.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 \-\-ns\-cert\-type client|server -.B DEPRECATED -This option will be removed in OpenVPN 2.5. Use the more modern equivalent -.B \-\-remote\-cert\-tls -instead. This option will be removed in OpenVPN 2.5. - -Require that peer certificate was signed with an explicit -.B nsCertType -designation of "client" or "server". - -This is a useful security option for clients, to ensure that -the host they connect with is a designated server. - -See the easy\-rsa/build\-key\-server script for an example -of how to generate a certificate with the -.B nsCertType -field set to "server". - -If the server certificate's nsCertType field is set -to "server", then the clients can verify this with -.B \-\-ns\-cert\-type server. - -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 -.B \-\-ns\-cert\-type, \-\-verify\-x509\-name, -or -.B \-\-tls\-verify. -.\"********************************************************* +.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 \-\-remote\-cert\-ku [v...] -Require that peer certificate was signed with an explicit -.B 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 the list -.B v... -is also supplied, the keyUsage field must have -.B at least -the same bits set as the bits in -.B one of -the values supplied in the list -.B v... - -The key usage values in the list must be encoded in hex, e.g. -"\-\-remote\-cert\-ku a0" -.\"********************************************************* +.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 \-\-remote\-cert\-eku oid -Require that peer certificate was signed with an explicit -.B 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. -.\"********************************************************* +.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 \-\-remote\-cert\-tls client|server -Require that peer certificate was signed with an explicit -.B key usage -and -.B extended key usage -based on RFC3280 TLS rules. - -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 -.B \-\-remote\-cert\-tls client -option is equivalent to -.B -\-\-remote\-cert\-ku \-\-remote\-cert\-eku "TLS Web Client Authentication" - -The -.B \-\-remote\-cert\-tls server -option is equivalent to -.B -\-\-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 -.B \-\-remote\-cert\-tls, \-\-verify\-x509\-name, -or -.B \-\-tls\-verify. -.\"********************************************************* +.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 -.B \-\-crl\-verify crl ['dir'] -Check peer certificate against the file -.B crl -in PEM format. - -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. "\fIVERIFY WARNING: depth=0, unable to get -certificate CRL\fR" \- but the connection will be allowed. - -If the optional -.B dir -flag is specified, enable a different mode where -.B crl -is 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 -.B \-\-user, -make sure that this user has sufficient privileges to read the file. -.\"********************************************************* -.SS SSL Library information: -.\"********************************************************* +.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 \-\-show\-ciphers -(Standalone) -Show all cipher algorithms to use with the -.B \-\-cipher -option. -.\"********************************************************* +.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 (to avoid IPv6 connections from dual\-stacked +clients leaking around IPv4\-only VPN services). +.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 +.sp +Note: this option does not influence traffic sent from the server +towards the client (neither on the server nor on the client side). +This is not seen as necessary, as such traffic can be most easily +avoided by not configuring IPv6 on the server tun, or setting up a +server\-side firewall rule. +.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 \fBADAPTER_DOMAIN_SUFFIX\fP \fBname\fP +Alias to \fBDOMAIN\fP\&. This is a compatibility option, it +should not be used in new deployments. +.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 \-\-show\-digests -(Standalone) -Show all message digest algorithms to use with the -.B \-\-auth -option. -.\"********************************************************* +.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 \-\-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. +.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 -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.). -.\"********************************************************* +# 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 \-\-show\-engines -(Standalone) -Show currently available hardware\-based crypto acceleration -engines supported by the OpenSSL library. -.\"********************************************************* +.B \-\-ifconfig\-noexec +Don\(aqt actually execute ifconfig/netsh commands, instead pass +\fB\-\-ifconfig\fP parameters to scripts using environmental variables. .TP -.B \-\-show\-curves -(Standalone) -Show all available elliptic curves to use with the -.B \-\-ecdh\-curve -option. -.\"********************************************************* -.SS Generate a random key: -Used only for non\-TLS static key encryption mode. -.\"********************************************************* -.TP -.B \-\-genkey -(Standalone) -Generate a random key to be used as a shared secret, -for use with the -.B \-\-secret -option. This file must be shared with the -peer over a pre\-existing secure channel such as -.BR scp (1) -. -.\"********************************************************* +.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 -.B \-\-secret file -Write key to -.B file. -.\"********************************************************* -.SS TUN/TAP persistent tunnel config mode: -Available with Linux 2.4.7+. These options comprise a standalone mode -of OpenVPN which can be used to create and delete persistent tunnels. -.\"********************************************************* +.BI \-\-lladdr \ address +Specify the link layer address, more commonly known as the MAC address. +Only applied to TAP devices. .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'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 -.B \-\-up -and -.B \-\-down -scripts to run the appropriate -.BR ifconfig (8) -and -.BR 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 -.B \-\-ipchange -option above). - -One disadvantage of persistent tunnels is that it is harder to automatically -configure their MTU value (see -.B \-\-link\-mtu -and -.B \-\-tun\-mtu -above). - -On some platforms such as Windows, TAP\-Win32 tunnels are persistent by -default. -.\"********************************************************* +.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 -.B \-\-rmtun -(Standalone) -Remove a persistent tunnel. -.\"********************************************************* +.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 \-\-dev tunX | tapX -TUN/TAP device -.\"********************************************************* +.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 \-\-user user -Optional user to be owner of this tunnel. -.\"********************************************************* +.B \fBautolocal\fP +Try to automatically determine whether to enable \fBlocal\fP +flag above. .TP -.B \-\-group group -Optional group to be owner of this tunnel. -.\"********************************************************* -.SS Windows\-Specific Options: -.\"********************************************************* +.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 \-\-win\-sys path -Set the Windows system directory pathname to use when looking for system -executables such as -.B route.exe -and -.B netsh.exe. -By default, if this directive is -not specified, OpenVPN will use the SystemRoot environment variable. - -This option have changed behaviour in OpenVPN 2.3. Earlier you had to -define -.B \-\-win\-sys env -to use the SystemRoot environment variable, otherwise it defaulted to C:\\WINDOWS. -It is not needed to use the -.B env -keyword any more, and it will just be ignored. A warning is logged when this -is found in the configuration file. -.\"********************************************************* -.TP -.B \-\-ip\-win32 method -When using -.B \-\-ifconfig -on Windows, set the TAP\-Win32 adapter -IP address and netmask using -.B method. -Don't use this option unless you are also using -.B \-\-ifconfig. - -.B 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. - -.B 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) OpenVPN needs to claim an IP address in the subnet for use -as the virtual DHCP server address. By default in -.B \-\-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 -.B \-\-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 -.B 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 -.B 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. - -.B 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. - -.B 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." - -.B adaptive \-\- -(Default) Try -.B dynamic -method initially and fail over to -.B 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 -.B 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 -.B adaptive -mode to use -.B netsh -immediately, rather than trying -.B dynamic -first. To "unstick" the -.B adaptive -mode from using -.B netsh, -run OpenVPN at least once using the -.B dynamic -mode to restore the TAP\-Win32 adapter TCP/IP properties -to a DHCP configuration. -.\"********************************************************* -.TP -.B \-\-route\-method m -Which method -.B m -to use for adding routes on Windows? - -.B adaptive -(default) \-\- Try IP helper API first. If that fails, fall -back to the route.exe shell command. -.br -.B ipapi -\-\- Use IP helper API. -.br -.B exe -\-\- Call the route.exe shell command. -.\"********************************************************* -.TP -.B \-\-dhcp\-option type [parm] -Set extended TAP\-Win32 TCP/IP properties, must -be used with -.B \-\-ip\-win32 dynamic -or -.B \-\-ip\-win32 adaptive. -This option can be used to set additional TCP/IP properties -on the TAP\-Win32 adapter, and is particularly useful for -configuring an OpenVPN client to access a Samba server -across the VPN. - -.B DOMAIN name \-\- -Set Connection\-specific DNS Suffix. - -.B DNS addr \-\- -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 -.B \-\-up -script could act upon it if needed. - -.B WINS addr \-\- -Set primary WINS server address (NetBIOS over TCP/IP Name Server). -Repeat this option to set secondary WINS server addresses. - -.B NBDD addr \-\- -Set primary NBDD server address (NetBIOS over TCP/IP Datagram Distribution Server) -Repeat this option -to set secondary NBDD server addresses. - -.B NTP addr \-\- -Set primary NTP server address (Network Time Protocol). -Repeat this option -to set secondary NTP server addresses. - -.B NBT type \-\- -Set NetBIOS over TCP/IP Node type. Possible options: -.B 1 -= b\-node (broadcasts), -.B 2 -= p\-node (point\-to\-point -name queries to a WINS server), -.B 4 -= m\-node (broadcast -then query name server), and -.B 8 -= h\-node (query name server, then broadcast). - -.B 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) - -.B DISABLE\-NBT \-\- -Disable Netbios\-over\-TCP/IP. - -Note that if -.B \-\-dhcp\-option -is pushed via -.B \-\-push -to a non\-windows client, the option will be saved in the client's -environment before the up script is called, under -the name "foreign_option_{n}". -.\"********************************************************* -.TP -.B \-\-tap\-sleep n -Cause OpenVPN to sleep for -.B 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 -.B \-\-ifconfig -and -.B \-\-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. -.\"********************************************************* +.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 \-\-show\-net\-up -Output OpenVPN's view of the system routing table and network -adapter list to the syslog or log file after the TUN/TAP adapter -has been brought up and any routes have been added. -.\"********************************************************* +.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 \-\-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 -.B \-\-setenv opt -or -.B \-\-ignore\-unknown\-option -(not suitable for Windows XP) to ignore said error. -Note that pushing unknown options from server does not trigger -fatal errors. -.\"********************************************************* +.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 \-\-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. -.\"********************************************************* +.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 \-\-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. -.\"********************************************************* +.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 -.B \-\-register\-dns -Run ipconfig /flushdns and ipconfig /registerdns on connection initiation. -This is known to kick Windows into -recognizing pushed DNS servers. -.\"********************************************************* +.BI \-\-route\-ipv6\-gateway \ gw +Specify a default gateway \fBgw\fP for use with \fB\-\-route\-ipv6\fP\&. .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. -.\"********************************************************* +.BI \-\-route\-metric \ m +Specify a default metric \fBm\fP for use with \fB\-\-route\fP\&. .TP -.B \-\-service exit\-event [0|1] -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. 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. - -.B 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 -.B exit\-event -and normally defaults to 0. - -Multiple OpenVPN processes can be simultaneously executed with the same -.B exit\-event -parameter. In any case, the controlling process can signal -.B exit\-event, -causing all such OpenVPN processes to exit. - -When executing an OpenVPN process using the -.B \-\-service -directive, OpenVPN will probably not have a console -window to output status/error -messages, therefore it is useful to use -.B \-\-log -or -.B \-\-log\-append -to write these messages to a file. -.\"********************************************************* +.B \-\-route\-noexec +Don\(aqt add or remove routes automatically. Instead pass routes to +\fB\-\-route\-up\fP script using environmental variables. .TP -.B \-\-show\-adapters -(Standalone) -Show available TAP\-Win32 adapters which can be selected using the -.B \-\-dev\-node -option. On non\-Windows systems, the -.BR ifconfig (8) -command provides similar functionality. -.\"********************************************************* -.TP -.B \-\-allow\-nonadmin [TAP\-adapter] -(Standalone) -Set -.B TAP\-adapter -to allow access from non\-administrative accounts. If -.B 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. -.\"********************************************************* +.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 \-\-show\-valid\-subnets -(Standalone) -Show valid subnets for -.B \-\-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). -.\"********************************************************* +.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 \-\-show\-net -(Standalone) -Show OpenVPN's view of the system routing table and network -adapter list. -.\"********************************************************* -.SS PKCS#11 Standalone Options: -.\"********************************************************* -.TP -.B \-\-show\-pkcs11\-ids [provider] [cert_private] -(Standalone) -Show PKCS#11 token object list. Specify cert_private as 1 -if certificates are stored as private objects. - -If p11\-kit is present on the system, the -.B provider -argument is optional; if omitted the default -.B p11\-kit\-proxy.so -module will be queried. - -.B \-\-verb -option can be used BEFORE this option to produce debugging information. -.\"********************************************************* -.SS Standalone Debug Options: -.\"********************************************************* -.TP -.B \-\-show\-gateway [v6target] -(Standalone) -Show current IPv4 and IPv6 default gateway and interface towards the -gateway (if the protocol in question is enabled). If an IPv6 address -is passed as argument, the IPv6 route for this host is reported. -.\"********************************************************* -.SS IPv6 Related Options -.\"********************************************************* -The following options exist to support IPv6 tunneling in peer\-to\-peer -and client\-server mode. All options are modeled after their IPv4 -counterparts, so more detailed explanations given there apply here -as well (except for -.B \-\-topology -, which has no effect on IPv6). -.TP -.B \-\-ifconfig\-ipv6 ipv6addr/bits ipv6remote -configure IPv6 address -.B ipv6addr/bits -on the ``tun'' device. The second parameter is used as route target for -.B \-\-route\-ipv6 -if no gateway is specified. -.TP -.B \-\-route\-ipv6 ipv6addr/bits [gateway] [metric] -setup IPv6 routing in the system to send the specified IPv6 network -into OpenVPN's ``tun''. The gateway parameter is only used for -IPv6 routes across ``tap'' devices, and if missing, the ``ipv6remote'' -field from -.B \-\-ifconfig\-ipv6 -is used. -.TP -.B \-\-server\-ipv6 ipv6addr/bits -convenience\-function to enable a number of IPv6 related options at -once, namely -.B \-\-ifconfig\-ipv6, \-\-ifconfig\-ipv6\-pool -and -.B \-\-push tun\-ipv6 -Is only accepted if ``\-\-mode server'' or ``\-\-server'' is set. Pushing of the -.B \-\-tun\-ipv6 -directive is done for older clients which require an explicit -``\-\-tun\-ipv6'' in their configuration. -.TP -.B \-\-ifconfig\-ipv6\-pool ipv6addr/bits -Specify an IPv6 address pool for dynamic assignment to clients. The -pool starts at -.B ipv6addr -and matches the offset determined from the start of the IPv4 pool. -.TP -.B \-\-ifconfig\-ipv6\-push ipv6addr/bits ipv6remote -for ccd/ per\-client static IPv6 interface configuration, see -.B \-\-client\-config\-dir -and -.B \-\-ifconfig\-push -for more details. -.TP -.B \-\-iroute\-ipv6 ipv6addr/bits -for ccd/ per\-client static IPv6 route configuration, see -.B \-\-iroute -for more details how to setup and use this, and how -.B \-\-iroute -and -.B \-\-route -interact. - -.\"********************************************************* -.SH SCRIPTING AND ENVIRONMENTAL VARIABLES -OpenVPN exports a series -of environmental variables for use by user\-defined scripts. -.\"********************************************************* -.SS Script Order of Execution -.\"********************************************************* +.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 \-\-up -Executed after TCP/UDP socket bind and TUN/TAP open. -.\"********************************************************* +.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 \-\-tls\-verify +.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. -.\"********************************************************* -.TP -.B \-\-ipchange +.IP 3. 4 +\fB\-\-ipchange\fP +.sp Executed after connection authentication, or remote IP address change. -.\"********************************************************* -.TP -.B \-\-client\-connect -Executed in -.B \-\-mode server -mode immediately after client authentication. -.\"********************************************************* -.TP -.B \-\-route\-up -Executed after connection authentication, either -immediately after, or some number of seconds after -as defined by the -.B \-\-route\-delay -option. -.\"********************************************************* -.TP -.B \-\-route\-pre\-down +.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 not passed any extra arguments +(only those arguments specified in cmd, if any). +.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 \-\-client\-disconnect -Executed in -.B \-\-mode server -mode on client instance shutdown. -.\"********************************************************* +.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 -.B \-\-down -Executed after TCP/UDP and TUN/TAP close. -.\"********************************************************* -.TP -.B \-\-learn\-address -Executed in -.B \-\-mode server -mode whenever an IPv4 address/route or MAC address is added to OpenVPN's -internal routing table. -.\"********************************************************* -.TP -.B \-\-auth\-user\-pass\-verify -Executed in -.B \-\-mode server -mode on new client connections, when the client is -still untrusted. -.\"********************************************************* +.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 -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 ('_'). - -.B Q: -Why is string remapping necessary? - -.B A: -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. - -.B Q: -Can string remapping be disabled? - -.B A: -Yes, by using the -.B \-\-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 +.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: - -.B 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. - -.B Common Names: -Alphanumeric, underbar ('_'), dash ('\-'), dot ('.'), and at -('@'). - -.B \-\-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, +.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. - -.B \-\-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. - -.B \-\-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. - -.B Environmental variable names: -Alphanumeric or underbar ('_'). - -.B 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 ('_'). -.\"********************************************************* -.SS 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. -.\"********************************************************* -.TP -.B bytes_received -Total number of bytes received from client during VPN session. -Set prior to execution of the -.B \-\-client\-disconnect -script. -.\"********************************************************* .TP -.B bytes_sent -Total number of bytes sent to client during VPN session. -Set prior to execution of the -.B \-\-client\-disconnect -script. -.\"********************************************************* -.TP -.B common_name -The X509 common name of an authenticated client. -Set prior to execution of -.B \-\-client\-connect, \-\-client\-disconnect, -and -.B \-\-auth\-user\-pass\-verify -scripts. -.\"********************************************************* +.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 config -Name of first -.B \-\-config -file. -Set on program initiation and reset on SIGHUP. -.\"********************************************************* +.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 daemon -Set to "1" if the -.B \-\-daemon -directive is specified, or "0" otherwise. -Set on program initiation and reset on SIGHUP. -.\"********************************************************* +.B \fIEnvironmental variable names\fP +Alphanumeric or underbar (\(aq_\(aq). .TP -.B daemon_log_redirect -Set to "1" if the -.B \-\-log -or -.B \-\-log\-append -directives are specified, or "0" otherwise. +.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 dev -The actual name of the TUN/TAP device, including -a unit number if it exists. -Set prior to -.B \-\-up -or -.B \-\-down -script execution. -.\"********************************************************* -.TP -.B 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 -.B \-\-up -or -.B \-\-down -script execution. -.\"********************************************************* -.TP -.B foreign_option_{n} -An option pushed via -.B \-\-push -to a client which does not natively support it, -such as -.B \-\-dhcp\-option -on a non\-Windows system, will be recorded to this -environmental variable sequence prior to -.B \-\-up -script execution. -.\"********************************************************* -.TP -.B ifconfig_broadcast -The broadcast address for the virtual -ethernet segment which is derived from the -.B \-\-ifconfig -option when -.B \-\-dev tap -is used. -Set prior to OpenVPN calling the -.I ifconfig -or -.I netsh -(windows version of ifconfig) commands which -normally occurs prior to -.B \-\-up -script execution. -.\"********************************************************* +.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 ifconfig_ipv6_local -The local VPN endpoint IPv6 address specified in the -.B \-\-ifconfig\-ipv6 -option (first parameter). -Set prior to OpenVPN calling the -.I ifconfig -or -.I netsh -(windows version of ifconfig) commands which -normally occurs prior to -.B \-\-up -script execution. -.\"********************************************************* -.TP -.B 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 -.B \-\-ifconfig\-ipv6 -option (first parameter). -Set prior to OpenVPN calling the -.I ifconfig -or -.I netsh -(windows version of ifconfig) commands which -normally occurs prior to -.B \-\-up -script execution. -.\"********************************************************* +.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 ifconfig_ipv6_remote -The remote VPN endpoint IPv6 address specified in the -.B \-\-ifconfig\-ipv6 -option (second parameter). -Set prior to OpenVPN calling the -.I ifconfig -or -.I netsh -(windows version of ifconfig) commands which -normally occurs prior to -.B \-\-up -script execution. -.\"********************************************************* -.TP -.B ifconfig_local -The local VPN endpoint IP address specified in the -.B \-\-ifconfig -option (first parameter). -Set prior to OpenVPN calling the -.I ifconfig -or -.I netsh -(windows version of ifconfig) commands which -normally occurs prior to -.B \-\-up -script execution. -.\"********************************************************* -.TP -.B ifconfig_remote -The remote VPN endpoint IP address specified in the -.B \-\-ifconfig -option (second parameter) when -.B \-\-dev tun -is used. -Set prior to OpenVPN calling the -.I ifconfig -or -.I netsh -(windows version of ifconfig) commands which -normally occurs prior to -.B \-\-up -script execution. -.\"********************************************************* -.TP -.B ifconfig_netmask -The subnet mask of the virtual ethernet segment -that is specified as the second parameter to -.B \-\-ifconfig -when -.B \-\-dev tap -is being used. -Set prior to OpenVPN calling the -.I ifconfig -or -.I netsh -(windows version of ifconfig) commands which -normally occurs prior to -.B \-\-up -script execution. -.\"********************************************************* -.TP -.B ifconfig_pool_local_ip -The local -virtual IP address for the TUN/TAP tunnel taken from an -.B \-\-ifconfig\-push -directive if specified, or otherwise from -the ifconfig pool (controlled by the -.B \-\-ifconfig\-pool -config file directive). -Only set for -.B \-\-dev tun -tunnels. -This option is set on the server prior to execution -of the -.B \-\-client\-connect -and -.B \-\-client\-disconnect -scripts. -.\"********************************************************* -.TP -.B ifconfig_pool_netmask -The -virtual IP netmask for the TUN/TAP tunnel taken from an -.B \-\-ifconfig\-push -directive if specified, or otherwise from -the ifconfig pool (controlled by the -.B \-\-ifconfig\-pool -config file directive). -Only set for -.B \-\-dev tap -tunnels. -This option is set on the server prior to execution -of the -.B \-\-client\-connect -and -.B \-\-client\-disconnect -scripts. -.\"********************************************************* -.TP -.B ifconfig_pool_remote_ip -The remote -virtual IP address for the TUN/TAP tunnel taken from an -.B \-\-ifconfig\-push -directive if specified, or otherwise from -the ifconfig pool (controlled by the -.B \-\-ifconfig\-pool -config file directive). -This option is set on the server prior to execution -of the -.B \-\-client\-connect -and -.B \-\-client\-disconnect -scripts. -.\"********************************************************* +.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 link_mtu -The maximum packet size (not including the IP header) -of tunnel data in UDP tunnel transport mode. -Set prior to -.B \-\-up -or -.B \-\-down +.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 local -The -.B \-\-local -parameter. -Set on program initiation and reset on SIGHUP. -.\"********************************************************* +.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 local_port -The local port number or name, specified by -.B \-\-port -or -.B \-\-lport. -Set on program initiation and reset on SIGHUP. -.\"********************************************************* -.TP -.B password -The password provided by a connecting client. -Set prior to -.B \-\-auth\-user\-pass\-verify -script execution only when the -.B via\-env -modifier is specified, and deleted from the environment -after the script returns. -.\"********************************************************* -.TP -.B proto -The -.B \-\-proto -parameter. +.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 remote_{n} -The -.B \-\-remote -parameter. -Set on program initiation and reset on SIGHUP. -.\"********************************************************* +.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 remote_port_{n} -The remote port number, specified by -.B \-\-port -or -.B \-\-rport. -Set on program initiation and reset on SIGHUP. -.\"********************************************************* +.B \fBproto\fP +The \fB\-\-proto\fP parameter. Set on program initiation and reset on +SIGHUP. .TP -.B route_net_gateway -The pre\-existing default IP gateway in the system routing -table. -Set prior to -.B \-\-up -script execution. -.\"********************************************************* -.TP -.B route_vpn_gateway -The default gateway used by -.B \-\-route -options, as specified in either the -.B \-\-route\-gateway -option or the second parameter to -.B \-\-ifconfig -when -.B \-\-dev tun -is specified. -Set prior to -.B \-\-up -script execution. -.\"********************************************************* +.B \fBremote_{n}\fP +The \fB\-\-remote\fP parameter. Set on program initiation and reset on +SIGHUP. .TP -.B route_{parm}_{n} -A set of variables which define each route to be added, and -are set prior to -.B \-\-up -script execution. - -.B parm -will be one of "network", "netmask", "gateway", or "metric". - -.B 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. -.\"********************************************************* -.TP -.B route_ipv6_{parm}_{n} -A set of variables which define each IPv6 route to be added, and -are set prior to -.B \-\-up +.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. - -.B 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). - -.B 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. -.\"********************************************************* -.TP -.B peer_cert -Temporary file name containing the client certificate upon -connection. Useful in conjunction with \-\-tls\-verify -.\"********************************************************* -.TP -.B script_context -Set to "init" or "restart" prior to up/down script execution. -For more information, see -documentation for -.B \-\-up. -.\"********************************************************* -.TP -.B 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: -.B up, down, ipchange, route\-up, tls\-verify, auth\-user\-pass\-verify, -.B client\-connect, client\-disconnect, -or -.B learn\-address. -Set prior to execution of any script. -.\"********************************************************* -.TP -.B signal -The reason for exit or restart. Can be one of -.B sigusr1, sighup, sigterm, sigint, inactive -(controlled by -.B \-\-inactive -option), -.B ping\-exit -(controlled by -.B \-\-ping\-exit -option), -.B ping\-restart -(controlled by -.B \-\-ping\-restart -option), -.B connection\-reset -(triggered on TCP connection reset), -.B error, -or -.B unknown -(unknown signal). This variable is set just prior to down script execution. -.\"********************************************************* -.TP -.B time_ascii -Client connection timestamp, formatted as a human\-readable -time string. -Set prior to execution of the -.B \-\-client\-connect -script. -.\"********************************************************* .TP -.B time_duration +.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, \fBgateway\fP or +\fBmetric\fP\&. \fBroute_ipv6_network_{n}\fP contains \fBnetmask\fP +as \fB/nnn\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 -.B \-\-client\-disconnect +disconnecting. Set prior to execution of the \fB\-\-client\-disconnect\fP script. -.\"********************************************************* .TP -.B time_unix -Client connection timestamp, formatted as a unix integer -date/time value. -Set prior to execution of the -.B \-\-client\-connect -script. -.\"********************************************************* -.TP -.B tls_digest_{n} / tls_digest_sha256_{n} -Contains the certificate SHA1 / SHA256 fingerprint, where -.B n -is the verification level. Only set for TLS connections. Set prior -to execution of -.B \-\-tls\-verify -script. -.\"********************************************************* -.TP -.B tls_id_{n} -A series of certificate fields from the remote peer, -where -.B n -is the verification level. Only set for TLS connections. Set prior -to execution of -.B \-\-tls\-verify -script. -.\"********************************************************* -.TP -.B tls_serial_{n} -The serial number of the certificate from the remote peer, -where -.B n -is the verification level. Only set for TLS connections. Set prior -to execution of -.B \-\-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. -.\"********************************************************* -.TP -.B tls_serial_hex_{n} -Like -.B tls_serial_{n}\fR, -but in hex form (e.g. "12:34:56:78:9A"). -.\"********************************************************* -.TP -.B tun_mtu -The MTU of the TUN/TAP device. -Set prior to -.B \-\-up -or -.B \-\-down +.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 trusted_ip (or trusted_ip6) -Actual IP address of connecting client or peer which has been authenticated. -Set prior to execution of -.B \-\-ipchange, \-\-client\-connect, -and -.B \-\-client\-disconnect -scripts. -If using ipv6 endpoints (udp6, tcp6), -.B trusted_ip6 -will be set instead. -.\"********************************************************* -.TP -.B trusted_port -Actual port number of connecting client or peer which has been authenticated. -Set prior to execution of -.B \-\-ipchange, \-\-client\-connect, -and -.B \-\-client\-disconnect -scripts. -.\"********************************************************* -.TP -.B untrusted_ip (or untrusted_ip6) -Actual IP address of connecting client or peer which has not been authenticated -yet. Sometimes used to -.B nmap -the connecting host in a -.B \-\-tls\-verify -script to ensure it is firewalled properly. -Set prior to execution of -.B \-\-tls\-verify -and -.B \-\-auth\-user\-pass\-verify -scripts. -If using ipv6 endpoints (udp6, tcp6), -.B untrusted_ip6 +.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 untrusted_port -Actual port number of connecting client or peer which has not been authenticated -yet. -Set prior to execution of -.B \-\-tls\-verify -and -.B \-\-auth\-user\-pass\-verify -scripts. -.\"********************************************************* -.TP -.B username -The username provided by a connecting client. -Set prior to -.B \-\-auth\-user\-pass\-verify -script execution only when the -.B via\-env -modifier is specified. -.\"********************************************************* -.TP -.B X509_{n}_{subject_field} -An X509 subject field from the remote peer certificate, -where -.B n -is the verification level. Only set for TLS connections. Set prior -to execution of -.B \-\-tls\-verify -script. This variable is similar to -.B 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. - +.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 3 -.in +4 +.ft C X509_0_emailAddress=me@myhost.mydomain X509_0_CN=Test\-Client X509_0_O=OpenVPN\-TEST @@ -6889,455 +5851,858 @@ X509_1_O=OpenVPN\-TEST X509_1_L=BISHKEK X509_1_ST=NA X509_1_C=KG -.in -4 -.ft +.ft P .fi -.\"********************************************************* -.SH INLINE FILE SUPPORT -OpenVPN allows including files in the main configuration for the -.B \-\-ca, \-\-cert, \-\-dh, \-\-extra\-certs, \-\-key, \-\-pkcs12, \-\-secret, -.B \-\-crl\-verify, \-\-http\-proxy\-user\-pass, \-\-tls\-auth -and -.B \-\-tls\-crypt -options. +.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 +For IPv6 this queries the route towards ::/128, or the specified IPv6 +target address if passed as argument. +For IPv4 on Linux, Windows, MacOS and BSD it looks for a 0.0.0.0/0 route. +If there are more specific routes, the result will not always be matching +the route of the IPv4 packets to the VPN gateway. +.UNINDENT +.SS Advanced Expert Options +.sp +These are options only required when special tweaking is needed, often +used when debugging or testing out special usage scenarios. +.INDENT 0.0 +.TP +.BI \-\-hash\-size \ args +Set the size of the real address hash table to \fBr\fP and the virtual +address table to \fBv\fP\&. +.sp +Valid syntax: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +hash\-size r v +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +By default, both tables are sized at 256 buckets. +.TP +.BI \-\-bcast\-buffers \ n +Allocate \fBn\fP buffers for broadcast datagrams (default \fB256\fP). +.TP +.B \-\-persist\-local\-ip +Preserve initially resolved local IP address and port number across +\fBSIGUSR1\fP or \fB\-\-ping\-restart\fP restarts. +.TP +.B \-\-persist\-remote\-ip +Preserve most recently authenticated remote IP address and port number +across \fBSIGUSR1\fP or \fB\-\-ping\-restart\fP restarts. +.TP +.BI \-\-prng \ args +\fI(Advanced)\fP Change the PRNG (Pseudo\-random number generator) parameters +.sp +Valid syntaxes: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +prng alg +prng alg nsl +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Changes the PRNG to use digest algorithm \fBalg\fP (default \fBsha1\fP), +and set \fBnsl\fP (default \fB16\fP) to the size in bytes of the nonce +secret length (between 16 and 64). +.sp +Set \fBalg\fP to \fBnone\fP to disable the PRNG and use the OpenSSL +RAND_bytes function instead for all of OpenVPN\(aqs pseudo\-random number +needs. +.TP +.BI \-\-rcvbuf \ size +Set the TCP/UDP socket receive buffer size. Defaults to operating system +default. +.TP +.BI \-\-shaper \ n +Limit bandwidth of outgoing tunnel data to \fBn\fP bytes per second on the +TCP/UDP port. Note that this will only work if mode is set to +\fBp2p\fP\&. If you want to limit the bandwidth in both directions, use +this option on both peers. +.sp +OpenVPN uses the following algorithm to implement traffic shaping: Given +a shaper rate of \fBn\fP bytes per second, after a datagram write of \fBb\fP +bytes is queued on the TCP/UDP port, wait a minimum of \fB(b / n)\fP +seconds before queuing the next write. +.sp +It should be noted that OpenVPN supports multiple tunnels between the +same two peers, allowing you to construct full\-speed and reduced +bandwidth tunnels at the same time, routing low\-priority data such as +off\-site backups over the reduced bandwidth tunnel, and other data over +the full\-speed tunnel. +.sp +Also note that for low bandwidth tunnels (under 1000 bytes per second), +you should probably use lower MTU values as well (see above), otherwise +the packet latency will grow so large as to trigger timeouts in the TLS +layer and TCP connections running over the tunnel. +.sp +OpenVPN allows \fBn\fP to be between 100 bytes/sec and 100 Mbytes/sec. +.TP +.BI \-\-sndbuf \ size +Set the TCP/UDP socket send buffer size. Defaults to operating system +default. +.TP +.BI \-\-tcp\-queue\-limit \ n +Maximum number of output packets queued before TCP (default \fB64\fP). +.sp +When OpenVPN is tunneling data from a TUN/TAP device to a remote client +over a TCP connection, it is possible that the TUN/TAP device might +produce data at a faster rate than the TCP connection can support. When +the number of output packets queued before sending to the TCP socket +reaches this limit for a given client connection, OpenVPN will start to +drop outgoing packets directed at this client. +.TP +.BI \-\-txqueuelen \ n +\fI(Linux only)\fP Set the TX queue length on the TUN/TAP interface. +Currently defaults to operating system default. +.UNINDENT +.SH UNSUPPORTED OPTIONS +.sp +Options listed in this section have been removed from OpenVPN and are no +longer supported +.INDENT 0.0 +.TP +.B \-\-client\-cert\-not\-required +Removed in OpenVPN 2.5. This should be replaxed with +\fB\-\-verify\-client\-cert none\fP\&. +.TP +.B \-\-ifconfig\-pool\-linear +Removed in OpenVPN 2.5. This should be replaced with \fB\-\-topology p2p\fP\&. +.TP +.B \-\-key\-method +Removed in OpenVPN 2.5. This option should not be used, as using the old +\fBkey\-method\fP weakens the VPN tunnel security. The old \fBkey\-method\fP +was also only needed when the remote side was older than OpenVPN 2.0. +.TP +.B \-\-no\-iv +Removed in OpenVPN 2.5. This option should not be used as it weakens the +VPN tunnel security. This has been a NOOP option since OpenVPN 2.4. +.TP +.B \-\-no\-replay +Removed in OpenVPN 2.5. This option should not be used as it weakens the +VPN tunnel security. +.TP +.B \-\-ns\-cert\-type +Removed in OpenVPN 2.5. The \fBnsCertType\fP field is no longer supported +in recent SSL/TLS libraries. If your certificates does not include \fIkey +usage\fP and \fIextended key usage\fP fields, they must be upgraded and the +\fB\-\-remote\-cert\-tls\fP option should be used instead. +.UNINDENT +.SH CONNECTION PROFILES +.sp +Client configuration files may contain multiple remote servers which +it will attempt to connect against. But there are some configuration +options which are related to specific \fB\-\-remote\fP options. For these +use cases, connection profiles are the solution. +.sp +By enacpulating the \fB\-\-remote\fP option and related options within +\fB<connection>\fP and \fB</connection>\fP, these options are handled as a +group. +.sp +An OpenVPN client will try each connection profile sequentially until it +achieves a successful connection. +.sp +\fB\-\-remote\-random\fP can be used to initially "scramble" the connection +list. +.sp +Here is an example of connection profile usage: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +client +dev tun -Each inline file started by the line -.B <option> -and ended by the line -.B </option> +<connection> +remote 198.19.34.56 1194 udp +</connection> -Here is an example of an inline file usage +<connection> +remote 198.19.34.56 443 tcp +</connection> +<connection> +remote 198.19.34.56 443 tcp +http\-proxy 192.168.0.8 8080 +</connection> + +<connection> +remote 198.19.36.99 443 tcp +http\-proxy 192.168.0.8 8080 +</connection> + +persist\-key +persist\-tun +pkcs12 client.p12 +remote\-cert\-tls server +verb 3 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +First we try to connect to a server at 198.19.34.56:1194 using UDP. If +that fails, we then try to connect to 198.19.34.56:443 using TCP. If +that also fails, then try connecting through an HTTP proxy at +192.168.0.8:8080 to 198.19.34.56:443 using TCP. Finally, try to connect +through the same proxy to a server at 198.19.36.99:443 using TCP. +.sp +The following OpenVPN options may be used inside of a \fB<connection>\fP +block: +.sp +\fBbind\fP, \fBconnect\-retry\fP, \fBconnect\-retry\-max\fP, \fBconnect\-timeout\fP, +\fBexplicit\-exit\-notify\fP, \fBfloat\fP, \fBfragment\fP, \fBhttp\-proxy\fP, +\fBhttp\-proxy\-option\fP, \fBkey\-direction\fP, \fBlink\-mtu\fP, \fBlocal\fP, +\fBlport\fP, \fBmssfix\fP, \fBmtu\-disc\fP, \fBnobind\fP, \fBport\fP, \fBproto\fP, +\fBremote\fP, \fBrport\fP, \fBsocks\-proxy\fP, \fBtls\-auth\fP, \fBtls\-crypt\fP, +\fBtun\-mtu and\fP, \fBtun\-mtu\-extra\fP\&. +.sp +A defaulting mechanism exists for specifying options to apply to all +\fB<connection>\fP profiles. If any of the above options (with the +exception of \fBremote\fP ) appear outside of a \fB<connection>\fP block, +but in a configuration file which has one or more \fB<connection>\fP +blocks, the option setting will be used as a default for +\fB<connection>\fP blocks which follow it in the configuration file. +.sp +For example, suppose the \fBnobind\fP option were placed in the sample +configuration file above, near the top of the file, before the first +\fB<connection>\fP block. The effect would be as if \fBnobind\fP were +declared in all \fB<connection>\fP blocks below it. +.SH INLINE FILE SUPPORT +.sp +OpenVPN allows including files in the main configuration for the \fB\-\-ca\fP, +\fB\-\-cert\fP, \fB\-\-dh\fP, \fB\-\-extra\-certs\fP, \fB\-\-key\fP, \fB\-\-pkcs12\fP, +\fB\-\-secret\fP, \fB\-\-crl\-verify\fP, \fB\-\-http\-proxy\-user\-pass\fP, \fB\-\-tls\-auth\fP, +\fB\-\-auth\-gen\-token\-secret\fP, \fB\-\-tls\-crypt\fP and \fB\-\-tls\-crypt\-v2\fP +options. +.sp +Each inline file started by the line \fB<option>\fP and ended by the line +\fB</option>\fP +.sp +Here is an example of an inline file usage +.INDENT 0.0 +.INDENT 3.5 +.sp .nf -.ft 3 -.in +4 +.ft C <cert> \-\-\-\-\-BEGIN CERTIFICATE\-\-\-\-\- [...] \-\-\-\-\-END CERTIFICATE\-\-\-\-\- </cert> -.in -4 -.ft +.ft P .fi - -When using the inline file feature with -.B \-\-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 -.B openssl base64 \-in input.p12 - +.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 -.TP -.B 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. -.\"********************************************************* -.TP -.B SIGUSR1 -Like -.B 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 -.B \-\-persist\-tun, \-\-persist\-key, \-\-persist\-local\-ip, -and -.B \-\-persist\-remote\-ip -options respectively (see above). - -This signal may also be internally generated by a timeout condition, governed -by the -.B \-\-ping\-restart -option. - -This signal, when combined with -.B \-\-persist\-remote\-ip, -may be -sent when the underlying parameters of the host's network interface change +.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 -.B \-\-ipchange -above for more information. -.\"********************************************************* -.TP -.B SIGUSR2 -Causes OpenVPN to display its current statistics (to the syslog -file if -.B \-\-daemon -is used, or stdout otherwise). -.\"********************************************************* -.TP -.B SIGINT, SIGTERM +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. -.\"********************************************************* -.SH TUN/TAP DRIVER SETUP -If you are running Linux 2.4.7 or higher, you probably have the TUN/TAP driver -already installed. If so, there are still a few things you need to do: - -Make device: -.B mknod /dev/net/tun c 10 200 - -Load driver: -.B modprobe tun -.\"********************************************************* -.SH 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. -.\"********************************************************* -.SS TUN/TAP Setup: -If you are using Linux 2.4 or higher, -make the tun device node and load the tun module: -.IP -.B mknod /dev/net/tun c 10 200 -.LP -.IP -.B modprobe tun -.LP -If you installed from RPM, the -.B mknod -step may be omitted, because the RPM install does that for you. - -Only Linux 2.4 and newer are supported. - -For other platforms, consult the INSTALL file at -.I http://openvpn.net/install.html -for more information. -.\"********************************************************* -.SS Firewall Setup: -If firewalls exist between -the two machines, they should be set to forward UDP port 1194 -in both directions. If you do not have control over the firewalls -between the two machines, you may still be able to use OpenVPN by adding -.B \-\-ping 15 -to each of the -.B 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). - -If you are using a Linux iptables\-based firewall, you may need to enter -the following command to allow incoming packets on the TUN device: -.IP -.B iptables \-A INPUT \-i tun+ \-j ACCEPT -.LP -See the firewalls section below for more information on configuring firewalls -for use with OpenVPN. -.\"********************************************************* -.SS VPN Address Setup: -For purposes -of our example, our two machines will be called -.B bob.example.com -and -.B alice.example.com. -If you are constructing a VPN over the internet, then replace -.B bob.example.com -and -.B 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 -.B ssh -without using the VPN (since -.B ssh -has its own built\-in security) you would use the command -.B ssh alice.example.com. -However in the same scenario, you could also use the command -.B 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 -.B 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. -.\"********************************************************* -.SS Example 1: A simple tunnel without security -.LP -On bob: -.IP -.B openvpn \-\-remote alice.example.com \-\-dev tun1 \-\-ifconfig 10.4.0.1 10.4.0.2 \-\-verb 9 -.LP -On alice: -.IP -.B openvpn \-\-remote bob.example.com \-\-dev tun1 \-\-ifconfig 10.4.0.2 10.4.0.1 \-\-verb 9 -.LP -Now verify the tunnel is working by pinging across the tunnel. -.LP -On bob: -.IP -.B ping 10.4.0.2 -.LP -On alice: -.IP -.B ping 10.4.0.1 -.LP -The -.B \-\-verb 9 -option will produce verbose output, similar to the -.BR tcpdump (8) -program. Omit the -.B \-\-verb 9 -option to have OpenVPN run quietly. -.\"********************************************************* -.SS Example 2: A tunnel with static\-key security (i.e. using a pre\-shared secret) -First build a static key on bob. -.IP -.B openvpn \-\-genkey \-\-secret key -.LP -This command will build a random key file called -.B key -(in ascii format). -Now copy -.B key -to alice over a secure medium such as by -using the -.BR scp (1) -program. -.LP -On bob: -.IP -.B openvpn \-\-remote alice.example.com \-\-dev tun1 \-\-ifconfig 10.4.0.1 10.4.0.2 \-\-verb 5 \-\-secret key -.LP -On alice: -.IP -.B openvpn \-\-remote bob.example.com \-\-dev tun1 \-\-ifconfig 10.4.0.2 10.4.0.1 \-\-verb 5 \-\-secret key -.LP -Now verify the tunnel is working by pinging across the tunnel. -.LP -On bob: -.IP -.B ping 10.4.0.2 -.LP -On alice: -.IP -.B ping 10.4.0.1 -.\"********************************************************* -.SS Example 3: A tunnel with full TLS\-based security -For this test, we will designate -.B bob -as the TLS client and -.B alice -as the TLS server. -.I Note that 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 -.B \-\-cert -is discussed for more info). Then construct -Diffie Hellman parameters (see above where -.B \-\-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 dh1024.pem. -.I Note that all client, server, and certificate authority certificates and keys included in the OpenVPN distribution are totally insecure and should be used for testing only. -.LP -On bob: -.IP -.B 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 -.LP -On alice: -.IP -.B 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 -.LP -Now verify the tunnel is working by pinging across the tunnel. -.LP -On bob: -.IP -.B ping 10.4.0.2 -.LP -On alice: -.IP -.B ping 10.4.0.1 -.LP -Notice the -.B \-\-reneg\-sec 60 -option we used above. That tells OpenVPN to renegotiate -the data channel keys every minute. -Since we used -.B \-\-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 -.B \-\-reneg\-sec 60 -option to use OpenVPN's default key renegotiation interval of one hour. -.\"********************************************************* -.SS 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. -.LP -First, ensure that IP forwarding is enabled on both peers. -On Linux, enable routing: -.IP -.B echo 1 > /proc/sys/net/ipv4/ip_forward -.LP -and enable TUN packet forwarding through the firewall: -.IP -.B iptables \-A FORWARD \-i tun+ \-j ACCEPT -.LP -On bob: -.IP -.B route add \-net 10.0.1.0 netmask 255.255.255.0 gw 10.4.0.2 -.LP -On alice: -.IP -.B route add \-net 10.0.0.0 netmask 255.255.255.0 gw 10.4.0.1 -.LP -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 -.B \-\-up -option. -.\"********************************************************* -.SH FIREWALLS -OpenVPN's usage of a single UDP port makes it fairly firewall\-friendly. -You should add an entry to your firewall rules to allow incoming OpenVPN -packets. On Linux 2.4+: -.IP -.B iptables \-A INPUT \-p udp \-s 1.2.3.4 \-\-dport 1194 \-j ACCEPT -.LP -This will allow incoming packets on UDP port 1194 (OpenVPN's default UDP port) -from an OpenVPN peer at 1.2.3.4. - -If you are using HMAC\-based packet authentication (the default in any of -OpenVPN's secure modes), having the firewall filter on source -address can be considered optional, since HMAC packet authentication -is a much more secure method of verifying the authenticity of -a packet source. In that case: -.IP -.B iptables \-A INPUT \-p udp \-\-dport 1194 \-j ACCEPT -.LP -would be adequate and would not render the host inflexible with -respect to its peer having a dynamic IP address. - -OpenVPN also works well on stateful firewalls. In some cases, you may -not need to add any static rules to the firewall list if you are -using a stateful firewall that knows how to track UDP connections. -If you specify -.B \-\-ping n, -OpenVPN will be guaranteed -to send a packet to its peer at least once every -.B n -seconds. If -.B n -is less than the stateful firewall connection timeout, you can -maintain an OpenVPN connection indefinitely without explicit -firewall rules. - -You should also add firewall rules to allow incoming IP traffic on -TUN or TAP devices such as: -.IP -.B iptables \-A INPUT \-i tun+ \-j ACCEPT -.LP -to allow input packets from tun devices, -.IP -.B iptables \-A FORWARD \-i tun+ \-j ACCEPT -.LP -to allow input packets from tun devices to be forwarded to -other hosts on the local network, -.IP -.B iptables \-A INPUT \-i tap+ \-j ACCEPT -.LP -to allow input packets from tap devices, and -.IP -.B iptables \-A FORWARD \-i tap+ \-j ACCEPT -.LP -to allow input packets from tap devices to be forwarded to -other hosts on the local network. - -These rules are secure if you use packet authentication, -since no incoming packets will arrive on a TUN or TAP -virtual device -unless they first pass an HMAC authentication test. -.\"********************************************************* +.UNINDENT .SH FAQ -.I http://openvpn.net/faq.html -.\"********************************************************* +.sp +\fI\%https://community.openvpn.net/openvpn/wiki/FAQ\fP .SH HOWTO -For a more comprehensive guide to setting up OpenVPN -in a production setting, see the OpenVPN HOWTO at -.I http://openvpn.net/howto.html -.\"********************************************************* +.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 -For a description of OpenVPN's underlying protocol, -see -.I http://openvpn.net/security.html -.\"********************************************************* +.sp +For a description of OpenVPN\(aqs underlying protocol, see +\fI\%https://openvpn.net/community\-resources/openvpn\-protocol/\fP .SH WEB -OpenVPN's web site is at -.I http://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. -.\"********************************************************* +.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 -Report all bugs to the OpenVPN team <info@openvpn.net>. -.\"********************************************************* -.SH "SEE ALSO" -.BR dhcpcd (8), -.BR ifconfig (8), -.BR openssl (1), -.BR route (8), -.BR scp (1) -.BR ssh (1) -.\"********************************************************* -.SH NOTES -.LP -This product includes software developed by the -OpenSSL Project ( -.I http://www.openssl.org/ -) - +.sp +Report all bugs to the OpenVPN team \fI\%info@openvpn.net\fP +.SH SEE ALSO +.sp +\fBopenvpn\-examples\fP(5), +\fBdhcpcd\fP(8), +\fBifconfig\fP(8), +\fBopenssl\fP(1), +\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 -.I http://www.ietf.org/rfc/rfc2246.txt - +\fI\%http://www.ietf.org/rfc/rfc2246.txt\fP +.sp For more information on the LZO real\-time compression library see -.I http://www.oberhumer.com/opensource/lzo/ -.\"********************************************************* +\fI\%https://www.oberhumer.com/opensource/lzo/\fP .SH COPYRIGHT -Copyright (C) 2002\-2018 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. -.\"********************************************************* +.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 -James Yonan <jim@yonan.net> +.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..1c0c65e --- /dev/null +++ b/doc/openvpn.8.html @@ -0,0 +1,5899 @@ +<?xml version="1.0" encoding="utf-8" ?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> +<meta name="generator" content="Docutils 0.16: http://docutils.sourceforge.net/" /> +<title>openvpn</title> +<style type="text/css"> + +/* +:Author: David Goodger (goodger@python.org) +:Id: $Id: html4css1.css 7952 2016-07-26 18:15:59Z milde $ +:Copyright: This stylesheet has been placed in the public domain. + +Default cascading style sheet for the HTML output of Docutils. + +See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to +customize this style sheet. +*/ + +/* used to remove borders from tables and images */ +.borderless, table.borderless td, table.borderless th { + border: 0 } + +table.borderless td, table.borderless th { + /* Override padding for "table.docutils td" with "! important". + The right padding separates the table cells. */ + padding: 0 0.5em 0 0 ! important } + +.first { + /* Override more specific margin styles with "! important". */ + margin-top: 0 ! important } + +.last, .with-subtitle { + margin-bottom: 0 ! important } + +.hidden { + display: none } + +.subscript { + vertical-align: sub; + font-size: smaller } + +.superscript { + vertical-align: super; + font-size: smaller } + +a.toc-backref { + text-decoration: none ; + color: black } + +blockquote.epigraph { + margin: 2em 5em ; } + +dl.docutils dd { + margin-bottom: 0.5em } + +object[type="image/svg+xml"], object[type="application/x-shockwave-flash"] { + overflow: hidden; +} + +/* Uncomment (and remove this text!) to get bold-faced definition list terms +dl.docutils dt { + font-weight: bold } +*/ + +div.abstract { + margin: 2em 5em } + +div.abstract p.topic-title { + font-weight: bold ; + text-align: center } + +div.admonition, div.attention, div.caution, div.danger, div.error, +div.hint, div.important, div.note, div.tip, div.warning { + margin: 2em ; + border: medium outset ; + padding: 1em } + +div.admonition p.admonition-title, div.hint p.admonition-title, +div.important p.admonition-title, div.note p.admonition-title, +div.tip p.admonition-title { + font-weight: bold ; + font-family: sans-serif } + +div.attention p.admonition-title, div.caution p.admonition-title, +div.danger p.admonition-title, div.error p.admonition-title, +div.warning p.admonition-title, .code .error { + color: red ; + font-weight: bold ; + font-family: sans-serif } + +/* Uncomment (and remove this text!) to get reduced vertical space in + compound paragraphs. +div.compound .compound-first, div.compound .compound-middle { + margin-bottom: 0.5em } + +div.compound .compound-last, div.compound .compound-middle { + margin-top: 0.5em } +*/ + +div.dedication { + margin: 2em 5em ; + text-align: center ; + font-style: italic } + +div.dedication p.topic-title { + font-weight: bold ; + font-style: normal } + +div.figure { + margin-left: 2em ; + margin-right: 2em } + +div.footer, div.header { + clear: both; + font-size: smaller } + +div.line-block { + display: block ; + margin-top: 1em ; + margin-bottom: 1em } + +div.line-block div.line-block { + margin-top: 0 ; + margin-bottom: 0 ; + margin-left: 1.5em } + +div.sidebar { + margin: 0 0 0.5em 1em ; + border: medium outset ; + padding: 1em ; + background-color: #ffffee ; + width: 40% ; + float: right ; + clear: right } + +div.sidebar p.rubric { + font-family: sans-serif ; + font-size: medium } + +div.system-messages { + margin: 5em } + +div.system-messages h1 { + color: red } + +div.system-message { + border: medium outset ; + padding: 1em } + +div.system-message p.system-message-title { + color: red ; + font-weight: bold } + +div.topic { + margin: 2em } + +h1.section-subtitle, h2.section-subtitle, h3.section-subtitle, +h4.section-subtitle, h5.section-subtitle, h6.section-subtitle { + margin-top: 0.4em } + +h1.title { + text-align: center } + +h2.subtitle { + text-align: center } + +hr.docutils { + width: 75% } + +img.align-left, .figure.align-left, object.align-left, table.align-left { + clear: left ; + float: left ; + margin-right: 1em } + +img.align-right, .figure.align-right, object.align-right, table.align-right { + clear: right ; + float: right ; + margin-left: 1em } + +img.align-center, .figure.align-center, object.align-center { + display: block; + margin-left: auto; + margin-right: auto; +} + +table.align-center { + margin-left: auto; + margin-right: auto; +} + +.align-left { + text-align: left } + +.align-center { + clear: both ; + text-align: center } + +.align-right { + text-align: right } + +/* reset inner alignment in figures */ +div.align-right { + text-align: inherit } + +/* div.align-center * { */ +/* text-align: left } */ + +.align-top { + vertical-align: top } + +.align-middle { + vertical-align: middle } + +.align-bottom { + vertical-align: bottom } + +ol.simple, ul.simple { + margin-bottom: 1em } + +ol.arabic { + list-style: decimal } + +ol.loweralpha { + list-style: lower-alpha } + +ol.upperalpha { + list-style: upper-alpha } + +ol.lowerroman { + list-style: lower-roman } + +ol.upperroman { + list-style: upper-roman } + +p.attribution { + text-align: right ; + margin-left: 50% } + +p.caption { + font-style: italic } + +p.credits { + font-style: italic ; + font-size: smaller } + +p.label { + white-space: nowrap } + +p.rubric { + font-weight: bold ; + font-size: larger ; + color: maroon ; + text-align: center } + +p.sidebar-title { + font-family: sans-serif ; + font-weight: bold ; + font-size: larger } + +p.sidebar-subtitle { + font-family: sans-serif ; + font-weight: bold } + +p.topic-title { + font-weight: bold } + +pre.address { + margin-bottom: 0 ; + margin-top: 0 ; + font: inherit } + +pre.literal-block, pre.doctest-block, pre.math, pre.code { + margin-left: 2em ; + margin-right: 2em } + +pre.code .ln { color: grey; } /* line numbers */ +pre.code, code { background-color: #eeeeee } +pre.code .comment, code .comment { color: #5C6576 } +pre.code .keyword, code .keyword { color: #3B0D06; font-weight: bold } +pre.code .literal.string, code .literal.string { color: #0C5404 } +pre.code .name.builtin, code .name.builtin { color: #352B84 } +pre.code .deleted, code .deleted { background-color: #DEB0A1} +pre.code .inserted, code .inserted { background-color: #A3D289} + +span.classifier { + font-family: sans-serif ; + font-style: oblique } + +span.classifier-delimiter { + font-family: sans-serif ; + font-weight: bold } + +span.interpreted { + font-family: sans-serif } + +span.option { + white-space: nowrap } + +span.pre { + white-space: pre } + +span.problematic { + color: red } + +span.section-subtitle { + /* font-size relative to parent (h1..h6 element) */ + font-size: 80% } + +table.citation { + border-left: solid 1px gray; + margin-left: 1px } + +table.docinfo { + margin: 2em 4em } + +table.docutils { + margin-top: 0.5em ; + margin-bottom: 0.5em } + +table.footnote { + border-left: solid 1px black; + margin-left: 1px } + +table.docutils td, table.docutils th, +table.docinfo td, table.docinfo th { + padding-left: 0.5em ; + padding-right: 0.5em ; + vertical-align: top } + +table.docutils th.field-name, table.docinfo th.docinfo-name { + font-weight: bold ; + text-align: left ; + white-space: nowrap ; + padding-left: 0 } + +/* "booktabs" style (no vertical lines) */ +table.docutils.booktabs { + border: 0px; + border-top: 2px solid; + border-bottom: 2px solid; + border-collapse: collapse; +} +table.docutils.booktabs * { + border: 0px; +} +table.docutils.booktabs th { + border-bottom: thin solid; + text-align: left; +} + +h1 tt.docutils, h2 tt.docutils, h3 tt.docutils, +h4 tt.docutils, h5 tt.docutils, h6 tt.docutils { + font-size: 100% } + +ul.auto-toc { + list-style-type: none } + +</style> +</head> +<body> +<div class="document" id="openvpn"> +<h1 class="title">openvpn</h1> +<h2 class="subtitle" id="secure-ip-tunnel-daemon">Secure IP tunnel daemon</h2> +<table class="docinfo" frame="void" rules="none"> +<col class="docinfo-name" /> +<col class="docinfo-content" /> +<tbody valign="top"> +<tr class="manual-section field"><th class="docinfo-name">Manual section:</th><td class="field-body">8</td> +</tr> +<tr class="manual-group field"><th class="docinfo-name">Manual group:</th><td class="field-body">System Manager's Manual</td> +</tr> +</tbody> +</table> +<div class="section" id="synopsis"> +<h1>SYNOPSIS</h1> +<div class="line-block"> +<div class="line"><tt class="docutils literal">openvpn</tt> [ options ... ]</div> +<div class="line"><tt class="docutils literal">openvpn</tt> <tt class="docutils literal"><span class="pre">--help</span></tt></div> +</div> +</div> +<div class="section" id="introduction"> +<h1>INTRODUCTION</h1> +<p>OpenVPN is an open source VPN daemon by James Yonan. Because OpenVPN +tries to be a universal VPN tool offering a great deal of flexibility, +there are a lot of options on this manual page. If you're new to +OpenVPN, you might want to skip ahead to the examples section where you +will see how to construct simple VPNs on the command line without even +needing a configuration file.</p> +<p>Also note that there's more documentation and examples on the OpenVPN +web site: <a class="reference external" href="https://openvpn.net/">https://openvpn.net/</a></p> +<p>And if you would like to see a shorter version of this manual, see the +openvpn usage message which can be obtained by running <strong>openvpn</strong> +without any parameters.</p> +</div> +<div class="section" id="description"> +<h1>DESCRIPTION</h1> +<p>OpenVPN is a robust and highly flexible VPN daemon. OpenVPN supports +SSL/TLS security, ethernet bridging, TCP or UDP tunnel transport through +proxies or NAT, support for dynamic IP addresses and DHCP, scalability +to hundreds or thousands of users, and portability to most major OS +platforms.</p> +<p>OpenVPN is tightly bound to the OpenSSL library, and derives much of its +crypto capabilities from it.</p> +<p>OpenVPN supports conventional encryption using a pre-shared secret key +<strong>(Static Key mode)</strong> or public key security <strong>(SSL/TLS mode)</strong> using +client & server certificates. OpenVPN also supports non-encrypted +TCP/UDP tunnels.</p> +<p>OpenVPN is designed to work with the <strong>TUN/TAP</strong> virtual networking +interface that exists on most platforms.</p> +<p>Overall, OpenVPN aims to offer many of the key features of IPSec but +with a relatively lightweight footprint.</p> +</div> +<div class="section" id="options"> +<h1>OPTIONS</h1> +<p>OpenVPN allows any option to be placed either on the command line or in +a configuration file. Though all command line options are preceded by a +double-leading-dash ("--"), this prefix can be removed when an option is +placed in a configuration file.</p> +<div class="section" id="generic-options"> +<h2>Generic Options</h2> +<p>This section covers generic options which are accessible regardless of +which mode OpenVPN is configured as.</p> +<table class="docutils option-list" frame="void" rules="none"> +<col class="option" /> +<col class="description" /> +<tbody valign="top"> +<tr><td class="option-group"> +<kbd><span class="option">--help</span></kbd></td> +<td>Show options.</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--auth-nocache</span></kbd></td> +<td><p class="first">Don't cache <tt class="docutils literal"><span class="pre">--askpass</span></tt> or <tt class="docutils literal"><span class="pre">--auth-user-pass</span></tt> username/passwords in +virtual memory.</p> +<p>If specified, this directive will cause OpenVPN to immediately forget +username/password inputs after they are used. As a result, when OpenVPN +needs a username/password, it will prompt for input from stdin, which +may be multiple times during the duration of an OpenVPN session.</p> +<p>When using <tt class="docutils literal"><span class="pre">--auth-nocache</span></tt> in combination with a user/password file +and <tt class="docutils literal"><span class="pre">--chroot</span></tt> or <tt class="docutils literal"><span class="pre">--daemon</span></tt>, make sure to use an absolute path.</p> +<p class="last">This directive does not affect the <tt class="docutils literal"><span class="pre">--http-proxy</span></tt> username/password. +It is always cached.</p> +</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--cd <var>dir</var></span></kbd></td> +<td><p class="first">Change directory to <tt class="docutils literal">dir</tt> prior to reading any files such as +configuration files, key files, scripts, etc. <tt class="docutils literal">dir</tt> should be an +absolute path, with a leading "/", and without any references to the +current directory such as <code>.</code> or <code>..</code>.</p> +<p class="last">This option is useful when you are running OpenVPN in <tt class="docutils literal"><span class="pre">--daemon</span></tt> mode, +and you want to consolidate all of your OpenVPN control files in one +location.</p> +</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--chroot <var>dir</var></span></kbd></td> +<td><p class="first">Chroot to <tt class="docutils literal">dir</tt> after initialization. <tt class="docutils literal"><span class="pre">--chroot</span></tt> essentially +redefines <tt class="docutils literal">dir</tt> as being the top level directory tree (/). OpenVPN +will therefore be unable to access any files outside this tree. This can +be desirable from a security standpoint.</p> +<p>Since the chroot operation is delayed until after initialization, most +OpenVPN options that reference files will operate in a pre-chroot +context.</p> +<p>In many cases, the <tt class="docutils literal">dir</tt> parameter can point to an empty directory, +however complications can result when scripts or restarts are executed +after the chroot operation.</p> +<p class="last">Note: The SSL library will probably need /dev/urandom to be available +inside the chroot directory <tt class="docutils literal">dir</tt>. This is because SSL libraries +occasionally need to collect fresh random. Newer linux kernels and some +BSDs implement a getrandom() or getentropy() syscall that removes the +need for /dev/urandom to be available.</p> +</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--config <var>file</var></span></kbd></td> +<td><p class="first">Load additional config options from <tt class="docutils literal">file</tt> where each line corresponds +to one command line option, but with the leading '--' removed.</p> +<p>If <tt class="docutils literal"><span class="pre">--config</span> file</tt> is the only option to the openvpn command, the +<tt class="docutils literal"><span class="pre">--config</span></tt> can be removed, and the command can be given as <tt class="docutils literal">openvpn +file</tt></p> +<p>Note that configuration files can be nested to a reasonable depth.</p> +<p>Double quotation or single quotation characters ("", '') can be used to +enclose single parameters containing whitespace, and "#" or ";" +characters in the first column can be used to denote comments.</p> +<p>Note that OpenVPN 2.0 and higher performs backslash-based shell escaping +for characters not in single quotations, so the following mappings +should be observed:</p> +<pre class="literal-block"> +\\ Maps to a single backslash character (\). +\" 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. +</pre> +<p>For example on Windows, use double backslashes to represent pathnames:</p> +<pre class="literal-block"> +secret "c:\\OpenVPN\\secret.key" +</pre> +<p>For examples of configuration files, see +<a class="reference external" href="https://openvpn.net/community-resources/how-to/">https://openvpn.net/community-resources/how-to/</a></p> +<p>Here is an example configuration file:</p> +<pre class="last literal-block"> +# +# Sample OpenVPN configuration file for +# using a pre-shared static key. +# +# '#' or ';' may be used to delimit comments. + +# Use a dynamic tun device. +dev tun + +# Our remote peer +remote mypeer.mydomain + +# 10.1.0.1 is our local VPN endpoint +# 10.1.0.2 is our remote VPN endpoint +ifconfig 10.1.0.1 10.1.0.2 + +# Our pre-shared static key +secret static.key +</pre> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--daemon <var>progname</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Become a daemon after all initialization functions are completed. This +option will cause all message and error output to be sent to the syslog +file (such as <code>/var/log/messages</code>), except for the output of +scripts and ifconfig commands, which will go to <code>/dev/null</code> unless +otherwise redirected. The syslog redirection occurs immediately at the +point that <tt class="docutils literal"><span class="pre">--daemon</span></tt> is parsed on the command line even though the +daemonization point occurs later. If one of the <tt class="docutils literal"><span class="pre">--log</span></tt> options is +present, it will supersede syslog redirection.</p> +<p>The optional <tt class="docutils literal">progname</tt> parameter will cause OpenVPN to report its +program name to the system logger as <tt class="docutils literal">progname</tt>. This can be useful in +linking OpenVPN messages in the syslog file with specific tunnels. When +unspecified, <tt class="docutils literal">progname</tt> defaults to "openvpn".</p> +<p>When OpenVPN is run with the <tt class="docutils literal"><span class="pre">--daemon</span></tt> option, it will try to delay +daemonization until the majority of initialization functions which are +capable of generating fatal errors are complete. This means that +initialization scripts can test the return status of the openvpn command +for a fairly reliable indication of whether the command has correctly +initialized and entered the packet forwarding event loop.</p> +<p>In OpenVPN, the vast majority of errors which occur after initialization +are non-fatal.</p> +<p>Note: as soon as OpenVPN has daemonized, it can not ask for usernames, +passwords, or key pass phrases anymore. This has certain consequences, +namely that using a password-protected private key will fail unless the +<tt class="docutils literal"><span class="pre">--askpass</span></tt> option is used to tell OpenVPN to ask for the pass phrase +(this requirement is new in v2.3.7, and is a consequence of calling +daemon() before initializing the crypto layer).</p> +<p class="last">Further, using <tt class="docutils literal"><span class="pre">--daemon</span></tt> together with <tt class="docutils literal"><span class="pre">--auth-user-pass</span></tt> (entered +on console) and <tt class="docutils literal"><span class="pre">--auth-nocache</span></tt> will fail as soon as key +renegotiation (and reauthentication) occurs.</p> +</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--disable-occ</span></kbd></td> +<td><p class="first">Don't output a warning message if option inconsistencies are detected +between peers. An example of an option inconsistency would be where one +peer uses <tt class="docutils literal"><span class="pre">--dev</span> tun</tt> while the other peer uses <tt class="docutils literal"><span class="pre">--dev</span> tap</tt>.</p> +<p class="last">Use of this option is discouraged, but is provided as a temporary fix in +situations where a recent version of OpenVPN must connect to an old +version.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--engine <var>engine-name</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Enable OpenSSL hardware-based crypto engine functionality.</p> +<p class="last">If <tt class="docutils literal"><span class="pre">engine-name</span></tt> is specified, use a specific crypto engine. Use the +<tt class="docutils literal"><span class="pre">--show-engines</span></tt> standalone option to list the crypto engines which +are supported by OpenSSL.</p> +</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--fast-io</span></kbd></td> +<td><p class="first">(Experimental) Optimize TUN/TAP/UDP I/O writes by avoiding a call to +poll/epoll/select prior to the write operation. The purpose of such a +call would normally be to block until the device or socket is ready to +accept the write. Such blocking is unnecessary on some platforms which +don't support write blocking on UDP sockets or TUN/TAP devices. In such +cases, one can optimize the event loop by avoiding the poll/epoll/select +call, improving CPU efficiency by 5% to 10%.</p> +<p class="last">This option can only be used on non-Windows systems, when <tt class="docutils literal"><span class="pre">--proto</span> +udp</tt> is specified, and when <tt class="docutils literal"><span class="pre">--shaper</span></tt> is NOT specified.</p> +</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--group <var>group</var></span></kbd></td> +<td>Similar to the <tt class="docutils literal"><span class="pre">--user</span></tt> option, this option changes the group ID of +the OpenVPN process to <tt class="docutils literal">group</tt> after initialization.</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--ignore-unknown-option <var>args</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Valid syntax:</p> +<pre class="literal-block"> +ignore-unknown-options opt1 opt2 opt3 ... optN +</pre> +<p>When one of options <tt class="docutils literal">opt1 ... optN</tt> is encountered in the configuration +file the configuration file parsing does not fail if this OpenVPN version +does not support the option. Multiple <tt class="docutils literal"><span class="pre">--ignore-unknown-option</span></tt> options +can be given to support a larger number of options to ignore.</p> +<p>This option should be used with caution, as there are good security +reasons for having OpenVPN fail if it detects problems in a config file. +Having said that, there are valid reasons for wanting new software +features to gracefully degrade when encountered by older software +versions.</p> +<p class="last"><tt class="docutils literal"><span class="pre">--ignore-unknown-option</span></tt> is available since OpenVPN 2.3.3.</p> +</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--iproute <var>cmd</var></span></kbd></td> +<td>Set alternate command to execute instead of default <tt class="docutils literal">iproute2</tt> command. +May be used in order to execute OpenVPN in unprivileged environment.</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--keying-material-exporter <var>args</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Save Exported Keying Material [RFC5705] of len bytes (must be between 16 +and 4095 bytes) using <tt class="docutils literal">label</tt> in environment +(<code>exported_keying_material</code>) for use by plugins in +<code>OPENVPN_PLUGIN_TLS_FINAL</code> callback.</p> +<p>Valid syntax:</p> +<pre class="literal-block"> +keying-material-exporter label len +</pre> +<p class="last">Note that exporter <tt class="docutils literal">labels</tt> have the potential to collide with existing +PRF labels. In order to prevent this, labels <em>MUST</em> begin with +<code>EXPORTER</code>.</p> +</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--mlock</span></kbd></td> +<td><p class="first">Disable paging by calling the POSIX mlockall function. Requires that +OpenVPN be initially run as root (though OpenVPN can subsequently +downgrade its UID using the <tt class="docutils literal"><span class="pre">--user</span></tt> option).</p> +<p>Using this option ensures that key material and tunnel data are never +written to disk due to virtual memory paging operations which occur +under most modern operating systems. It ensures that even if an attacker +was able to crack the box running OpenVPN, he would not be able to scan +the system swap file to recover previously used ephemeral keys, which +are used for a period of time governed by the <tt class="docutils literal"><span class="pre">--reneg</span></tt> options (see +below), then are discarded.</p> +<p>The downside of using <tt class="docutils literal"><span class="pre">--mlock</span></tt> is that it will reduce the amount of +physical memory available to other applications.</p> +<p class="last">The limit on how much memory can be locked and how that limit +is enforced are OS-dependent. On Linux the default limit that an +unprivileged process may lock (RLIMIT_MEMLOCK) is low, and if +privileges are dropped later, future memory allocations will very +likely fail. The limit can be increased using ulimit or systemd +directives depending on how OpenVPN is started.</p> +</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--nice <var>n</var></span></kbd></td> +<td>Change process priority after initialization (<tt class="docutils literal">n</tt> greater than 0 is +lower priority, <tt class="docutils literal">n</tt> less than zero is higher priority).</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--persist-key</span></kbd></td> +<td><p class="first">Don't re-read key files across <code>SIGUSR1</code> or <tt class="docutils literal"><span class="pre">--ping-restart</span></tt>.</p> +<p>This option can be combined with <tt class="docutils literal"><span class="pre">--user</span> nobody</tt> to allow restarts +triggered by the <code>SIGUSR1</code> signal. Normally if you drop root +privileges in OpenVPN, the daemon cannot be restarted since it will now +be unable to re-read protected key files.</p> +<p class="last">This option solves the problem by persisting keys across <code>SIGUSR1</code> +resets, so they don't need to be re-read.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--remap-usr1 <var>signal</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Control whether internally or externally generated <code>SIGUSR1</code> signals +are remapped to <code>SIGHUP</code> (restart without persisting state) or +SIGTERM (exit).</p> +<p class="last"><tt class="docutils literal">signal</tt> can be set to <code>SIGHUP</code> or <code>SIGTERM</code>. By default, +no remapping occurs.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--script-security <var>level</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">This directive offers policy-level control over OpenVPN's usage of +external programs and scripts. Lower <tt class="docutils literal">level</tt> values are more +restrictive, higher values are more permissive. Settings for <tt class="docutils literal">level</tt>:</p> +<dl class="docutils"> +<dt><code>0</code></dt> +<dd>Strictly no calling of external programs.</dd> +<dt><code>1</code></dt> +<dd>(Default) Only call built-in executables such as ifconfig, +ip, route, or netsh.</dd> +<dt><code>2</code></dt> +<dd>Allow calling of built-in executables and user-defined +scripts.</dd> +<dt><code>3</code></dt> +<dd>Allow passwords to be passed to scripts via environmental +variables (potentially unsafe).</dd> +</dl> +<p>OpenVPN releases before v2.3 also supported a <tt class="docutils literal">method</tt> flag which +indicated how OpenVPN should call external commands and scripts. This +could be either <code>execve</code> or <code>system</code>. As of OpenVPN 2.3, this +flag is no longer accepted. In most *nix environments the execve() +approach has been used without any issues.</p> +<p>Some directives such as <tt class="docutils literal"><span class="pre">--up</span></tt> allow options to be passed to the +external script. In these cases make sure the script name does not +contain any spaces or the configuration parser will choke because it +can't determine where the script name ends and script options start.</p> +<p>To run scripts in Windows in earlier OpenVPN versions you needed to +either add a full path to the script interpreter which can parse the +script or use the <tt class="docutils literal">system</tt> flag to run these scripts. As of OpenVPN +2.3 it is now a strict requirement to have full path to the script +interpreter when running non-executables files. This is not needed for +executable files, such as .exe, .com, .bat or .cmd files. For example, +if you have a Visual Basic script, you must use this syntax now:</p> +<pre class="literal-block"> +--up 'C:\\Windows\\System32\\wscript.exe C:\\Program\ Files\\OpenVPN\\config\\my-up-script.vbs' +</pre> +<p>Please note the single quote marks and the escaping of the backslashes +(\) and the space character.</p> +<p class="last">The reason the support for the <code>system</code> flag was removed is due to +the security implications with shell expansions when executing scripts +via the <code>system()</code> call.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--setcon <var>context</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Apply SELinux <tt class="docutils literal">context</tt> after initialization. This essentially +provides the ability to restrict OpenVPN's rights to only network I/O +operations, thanks to SELinux. This goes further than <tt class="docutils literal"><span class="pre">--user</span></tt> and +<tt class="docutils literal"><span class="pre">--chroot</span></tt> in that those two, while being great security features, +unfortunately do not protect against privilege escalation by +exploitation of a vulnerable system call. You can of course combine all +three, but please note that since setcon requires access to /proc you +will have to provide it inside the chroot directory (e.g. with mount +--bind).</p> +<p>Since the setcon operation is delayed until after initialization, +OpenVPN can be restricted to just network-related system calls, whereas +by applying the context before startup (such as the OpenVPN one provided +in the SELinux Reference Policies) you will have to allow many things +required only during initialization.</p> +<p class="last">Like with chroot, complications can result when scripts or restarts are +executed after the setcon operation, which is why you should really +consider using the <tt class="docutils literal"><span class="pre">--persist-key</span></tt> and <tt class="docutils literal"><span class="pre">--persist-tun</span></tt> options.</p> +</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--status <var>args</var></span></kbd></td> +<td><p class="first">Write operational status to <tt class="docutils literal">file</tt> every <tt class="docutils literal">n</tt> seconds.</p> +<p>Valid syntaxes:</p> +<pre class="literal-block"> +status file +status file n +</pre> +<p>Status can also be written to the syslog by sending a <code>SIGUSR2</code> +signal.</p> +<p>With multi-client capability enabled on a server, the status file +includes a list of clients and a routing table. The output format can be +controlled by the <tt class="docutils literal"><span class="pre">--status-version</span></tt> option in that case.</p> +<p class="last">For clients or instances running in point-to-point mode, it will contain +the traffic statistics.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--status-version <var>n</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Set the status file format version number to <tt class="docutils literal">n</tt>.</p> +<p>This only affects the status file on servers with multi-client +capability enabled. Valid status version values:</p> +<dl class="last docutils"> +<dt><code>1</code></dt> +<dd>Traditional format (default). The client list contains the +following fields comma-separated: Common Name, Real Address, Bytes +Received, Bytes Sent, Connected Since.</dd> +<dt><code>2</code></dt> +<dd>A more reliable format for external processing. Compared to +version <code>1</code>, the client list contains some additional fields: +Virtual Address, Virtual IPv6 Address, Username, Client ID, Peer ID, +Data Channel Cipher. Future versions may extend the number of fields.</dd> +<dt><code>3</code></dt> +<dd>Identical to <code>2</code>, but fields are tab-separated.</dd> +</dl> +</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--test-crypto</span></kbd></td> +<td><p class="first">Do a self-test of OpenVPN's crypto options by encrypting and decrypting +test packets using the data channel encryption options specified above. +This option does not require a peer to function, and therefore can be +specified without <tt class="docutils literal"><span class="pre">--dev</span></tt> or <tt class="docutils literal"><span class="pre">--remote</span></tt>.</p> +<p>The typical usage of <tt class="docutils literal"><span class="pre">--test-crypto</span></tt> would be something like this:</p> +<pre class="literal-block"> +openvpn --test-crypto --secret key +</pre> +<p>or</p> +<pre class="literal-block"> +openvpn --test-crypto --secret key --verb 9 +</pre> +<p class="last">This option is very useful to test OpenVPN after it has been ported to a +new platform, or to isolate problems in the compiler, OpenSSL crypto +library, or OpenVPN's crypto code. Since it is a self-test mode, +problems with encryption and authentication can be debugged +independently of network and tunnel issues.</p> +</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--tmp-dir <var>dir</var></span></kbd></td> +<td><p class="first">Specify a directory <tt class="docutils literal">dir</tt> for temporary files. This directory will be +used by openvpn processes and script to communicate temporary data with +openvpn main process. Note that the directory must be writable by the +OpenVPN process after it has dropped it's root privileges.</p> +<p>This directory will be used by in the following cases:</p> +<ul class="last simple"> +<li><tt class="docutils literal"><span class="pre">--client-connect</span></tt> scripts and <code>OPENVPN_PLUGIN_CLIENT_CONNECT</code> +plug-in hook to dynamically generate client-specific configuration +<code>client_connect_config_file</code> and return success/failure via +<code>client_connect_deferred_file</code> when using deferred client connect +method</li> +<li><code>OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY</code> plug-in hooks returns +success/failure via <code>auth_control_file</code> when using deferred auth +method</li> +<li><code>OPENVPN_PLUGIN_ENABLE_PF</code> plugin hook to pass filtering rules +via <tt class="docutils literal">pf_file</tt></li> +</ul> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--use-prediction-resistance</span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Enable prediction resistance on mbed TLS's RNG.</p> +<p>Enabling prediction resistance causes the RNG to reseed in each call for +random. Reseeding this often can quickly deplete the kernel entropy +pool.</p> +<p class="last">If you need this option, please consider running a daemon that adds +entropy to the kernel pool.</p> +</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--user <var>user</var></span></kbd></td> +<td><p class="first">Change the user ID of the OpenVPN process to <tt class="docutils literal">user</tt> after +initialization, dropping privileges in the process. This option is +useful to protect the system in the event that some hostile party was +able to gain control of an OpenVPN session. Though OpenVPN's security +features make this unlikely, it is provided as a second line of defense.</p> +<p class="last">By setting <tt class="docutils literal">user</tt> to <code>nobody</code> or somebody similarly unprivileged, +the hostile party would be limited in what damage they could cause. Of +course once you take away privileges, you cannot return them to an +OpenVPN session. This means, for example, that if you want to reset an +OpenVPN daemon with a <code>SIGUSR1</code> signal (for example in response to +a DHCP reset), you should make use of one or more of the <tt class="docutils literal"><span class="pre">--persist</span></tt> +options to ensure that OpenVPN doesn't need to execute any privileged +operations in order to restart (such as re-reading key files or running +<tt class="docutils literal">ifconfig</tt> on the TUN device).</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--writepid <var>file</var></span></kbd></td> +</tr> +<tr><td> </td><td>Write OpenVPN's main process ID to <tt class="docutils literal">file</tt>.</td></tr> +</tbody> +</table> +</div> +<div class="section" id="log-options"> +<h2>Log options</h2> +<table class="docutils option-list" frame="void" rules="none"> +<col class="option" /> +<col class="description" /> +<tbody valign="top"> +<tr><td class="option-group"> +<kbd><span class="option">--echo <var>parms</var></span></kbd></td> +<td><p class="first">Echo <tt class="docutils literal">parms</tt> to log output.</p> +<p class="last">Designed to be used to send messages to a controlling application which +is receiving the OpenVPN log output.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--errors-to-stderr</span></kbd></td> +</tr> +<tr><td> </td><td>Output errors to stderr instead of stdout unless log output is +redirected by one of the <tt class="docutils literal"><span class="pre">--log</span></tt> options.</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--log <var>file</var></span></kbd></td> +<td><p class="first">Output logging messages to <tt class="docutils literal">file</tt>, including output to stdout/stderr +which is generated by called scripts. If <tt class="docutils literal">file</tt> already exists it will +be truncated. This option takes effect immediately when it is parsed in +the command line and will supersede syslog output if <tt class="docutils literal"><span class="pre">--daemon</span></tt> or +<tt class="docutils literal"><span class="pre">--inetd</span></tt> is also specified. This option is persistent over the entire +course of an OpenVPN instantiation and will not be reset by +<code>SIGHUP</code>, <code>SIGUSR1</code>, or <tt class="docutils literal"><span class="pre">--ping-restart</span></tt>.</p> +<p class="last">Note that on Windows, when OpenVPN is started as a service, logging +occurs by default without the need to specify this option.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--log-append <var>file</var></span></kbd></td> +</tr> +<tr><td> </td><td>Append logging messages to <tt class="docutils literal">file</tt>. If <tt class="docutils literal">file</tt> does not exist, it will +be created. This option behaves exactly like <tt class="docutils literal"><span class="pre">--log</span></tt> except that it +appends to rather than truncating the log file.</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--machine-readable-output</span></kbd></td> +</tr> +<tr><td> </td><td>Always write timestamps and message flags to log messages, even when +they otherwise would not be prefixed. In particular, this applies to log +messages sent to stdout.</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--mute <var>n</var></span></kbd></td> +<td>Log at most <tt class="docutils literal">n</tt> consecutive messages in the same category. This is +useful to limit repetitive logging of similar message types.</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--mute-replay-warnings</span></kbd></td> +</tr> +<tr><td> </td><td>Silence the output of replay warnings, which are a common false alarm on +WiFi networks. This option preserves the security of the replay +protection code without the verbosity associated with warnings about +duplicate packets.</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--suppress-timestamps</span></kbd></td> +</tr> +<tr><td> </td><td>Avoid writing timestamps to log messages, even when they otherwise would +be prepended. In particular, this applies to log messages sent to +stdout.</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--syslog <var>progname</var></span></kbd></td> +</tr> +<tr><td> </td><td>Direct log output to system logger, but do not become a daemon. See +<tt class="docutils literal"><span class="pre">--daemon</span></tt> directive above for description of <tt class="docutils literal">progname</tt> parameter.</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--verb <var>n</var></span></kbd></td> +<td><p class="first">Set output verbosity to <tt class="docutils literal">n</tt> (default <code>1</code>). Each level shows all +info from the previous levels. Level <code>3</code> is recommended if you want +a good summary of what's happening without being swamped by output.</p> +<dl class="last docutils"> +<dt><code>0</code></dt> +<dd>No output except fatal errors.</dd> +<dt><code>1</code> to <code>4</code></dt> +<dd>Normal usage range.</dd> +<dt><code>5</code></dt> +<dd>Outputs <code>R</code> and <code>W</code> characters to the console for +each packet read and write, uppercase is used for TCP/UDP +packets and lowercase is used for TUN/TAP packets.</dd> +<dt><code>6</code> to <code>11</code></dt> +<dd>Debug info range (see <code>errlevel.h</code> in the source code for +additional information on debug levels).</dd> +</dl> +</td></tr> +</tbody> +</table> +</div> +<div class="section" id="protocol-options"> +<h2>Protocol options</h2> +<p>Options in this section affect features available in the OpenVPN wire +protocol. Many of these options also define the encryption options +of the data channel in the OpenVPN wire protocol. These options must be +configured in a compatible way between both the local and remote side.</p> +<table class="docutils option-list" frame="void" rules="none"> +<col class="option" /> +<col class="description" /> +<tbody valign="top"> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--allow-compression <var>mode</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">As described in the <tt class="docutils literal"><span class="pre">--compress</span></tt> option, compression is a potentially +dangerous option. This option allows controlling the behaviour of +OpenVPN when compression is used and allowed.</p> +<p>Valid syntaxes:</p> +<pre class="literal-block"> +allow-compression +allow-compression mode +</pre> +<p>The <tt class="docutils literal">mode</tt> argument can be one of the following values:</p> +<dl class="last docutils"> +<dt><code>asym</code> (default)</dt> +<dd>OpenVPN will only <em>decompress downlink packets</em> but <em>not compress +uplink packets</em>. This also allows migrating to disable compression +when changing both server and client configurations to remove +compression at the same time is not a feasible option.</dd> +<dt><code>no</code></dt> +<dd>OpenVPN will refuse any non-stub compression.</dd> +<dt><code>yes</code></dt> +<dd>OpenVPN will send and receive compressed packets.</dd> +</dl> +</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--auth <var>alg</var></span></kbd></td> +<td><p class="first">Authenticate data channel packets and (if enabled) <tt class="docutils literal"><span class="pre">tls-auth</span></tt> control +channel packets with HMAC using message digest algorithm <tt class="docutils literal">alg</tt>. (The +default is <tt class="docutils literal">SHA1</tt> ). HMAC is a commonly used message authentication +algorithm (MAC) that uses a data string, a secure hash algorithm and a +key to produce a digital signature.</p> +<p>The OpenVPN data channel protocol uses encrypt-then-mac (i.e. first +encrypt a packet then HMAC the resulting ciphertext), which prevents +padding oracle attacks.</p> +<p>If an AEAD cipher mode (e.g. GCM) is chosen then the specified <tt class="docutils literal"><span class="pre">--auth</span></tt> +algorithm is ignored for the data channel and the authentication method +of the AEAD cipher is used instead. Note that <tt class="docutils literal">alg</tt> still specifies +the digest used for <tt class="docutils literal"><span class="pre">tls-auth</span></tt>.</p> +<p>In static-key encryption mode, the HMAC key is included in the key file +generated by <tt class="docutils literal"><span class="pre">--genkey</span></tt>. In TLS mode, the HMAC key is dynamically +generated and shared between peers via the TLS control channel. If +OpenVPN receives a packet with a bad HMAC it will drop the packet. HMAC +usually adds 16 or 20 bytes per packet. Set <tt class="docutils literal">alg=none</tt> to disable +authentication.</p> +<p class="last">For more information on HMAC see +<a class="reference external" href="http://www.cs.ucsd.edu/users/mihir/papers/hmac.html">http://www.cs.ucsd.edu/users/mihir/papers/hmac.html</a></p> +</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--cipher <var>alg</var></span></kbd></td> +<td><p class="first">This option is deprecated for server-client mode. <tt class="docutils literal"><span class="pre">--data-ciphers</span></tt> +or possibly <cite>--data-ciphers-fallback`</cite> should be used instead.</p> +<p>Encrypt data channel packets with cipher algorithm <tt class="docutils literal">alg</tt>.</p> +<p>The default is <code>BF-CBC</code>, an abbreviation for Blowfish in Cipher +Block Chaining mode. When cipher negotiation (NCP) is allowed, +OpenVPN 2.4 and newer on both client and server side will automatically +upgrade to <code>AES-256-GCM</code>. See <tt class="docutils literal"><span class="pre">--data-ciphers</span></tt> and +<tt class="docutils literal"><span class="pre">--ncp-disable</span></tt> for more details on NCP.</p> +<p>Using <code>BF-CBC</code> is no longer recommended, because of its 64-bit +block size. This small block size allows attacks based on collisions, as +demonstrated by SWEET32. See +<a class="reference external" href="https://community.openvpn.net/openvpn/wiki/SWEET32">https://community.openvpn.net/openvpn/wiki/SWEET32</a> +for details. Due to this, support for <code>BF-CBC</code>, <code>DES</code>, +<code>CAST5</code>, <code>IDEA</code> and <code>RC2</code> ciphers will be removed in +OpenVPN 2.6.</p> +<p>To see other ciphers that are available with OpenVPN, use the +<tt class="docutils literal"><span class="pre">--show-ciphers</span></tt> option.</p> +<p class="last">Set <tt class="docutils literal">alg</tt> to <code>none</code> to disable encryption.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--compress <var>algorithm</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first"><strong>DEPRECATED</strong> Enable a compression algorithm. Compression is generally +not recommended. VPN tunnels which use compression are susceptible to +the VORALCE attack vector.</p> +<p>The <tt class="docutils literal">algorithm</tt> parameter may be <code>lzo</code>, <code>lz4</code>, +<code>lz4-v2</code>, <code>stub</code>, <code>stub-v2</code> or empty. +LZO and LZ4 are different compression algorithms, with LZ4 generally +offering the best performance with least CPU usage.</p> +<p>The <code>lz4-v2</code> and <code>stub-v2</code> variants implement a better +framing that does not add overhead when packets cannot be compressed. All +other variants always add one extra framing byte compared to no +compression framing.</p> +<p>If the <tt class="docutils literal">algorithm</tt> parameter is <code>stub</code>, <code>stub-v2</code> or empty, +compression will be turned off, but the packet framing for compression +will still be enabled, allowing a different setting to be pushed later. +Additionally, <code>stub</code> and <code>stub-v2</code> wil disable announcing +<tt class="docutils literal">lzo</tt> and <tt class="docutils literal">lz4</tt> compression support via <em>IV_</em> variables to the +server.</p> +<p>Note: the <code>stub</code> (or empty) option is NOT compatible with the older +option <tt class="docutils literal"><span class="pre">--comp-lzo</span> no</tt>.</p> +<p><strong>*Security Considerations*</strong></p> +<p class="last">Compression and encryption is a tricky combination. If an attacker knows +or is able to control (parts of) the plain-text of packets that contain +secrets, the attacker might be able to extract the secret if compression +is enabled. See e.g. the <em>CRIME</em> and <em>BREACH</em> attacks on TLS and +<em>VORACLE</em> on VPNs which also leverage to break encryption. If you are not +entirely sure that the above does not apply to your traffic, you are +advised to <em>not</em> enable compression.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--comp-lzo <var>mode</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first"><strong>DEPRECATED</strong> Enable LZO compression algorithm. Compression is +generally not recommended. VPN tunnels which uses compression are +suspectible to the VORALCE attack vector.</p> +<p>Use LZO compression -- may add up to 1 byte per packet for incompressible +data. <tt class="docutils literal">mode</tt> may be <code>yes</code>, <code>no</code>, or <code>adaptive</code> +(default).</p> +<p>In a server mode setup, it is possible to selectively turn compression +on or off for individual clients.</p> +<p>First, make sure the client-side config file enables selective +compression by having at least one <tt class="docutils literal"><span class="pre">--comp-lzo</span></tt> directive, such as +<tt class="docutils literal"><span class="pre">--comp-lzo</span> no</tt>. This will turn off compression by default, but allow +a future directive push from the server to dynamically change the +<code>on</code>/<code>off</code>/<code>adaptive</code> setting.</p> +<p>Next in a <tt class="docutils literal"><span class="pre">--client-config-dir</span></tt> file, specify the compression setting +for the client, for example:</p> +<pre class="literal-block"> +comp-lzo yes +push "comp-lzo yes" +</pre> +<p class="last">The first line sets the <tt class="docutils literal"><span class="pre">comp-lzo</span></tt> setting for the server side of the +link, the second sets the client side.</p> +</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--comp-noadapt</span></kbd></td> +<td><p class="first"><strong>DEPRECATED</strong> When used in conjunction with <tt class="docutils literal"><span class="pre">--comp-lzo</span></tt>, this option +will disable OpenVPN's adaptive compression algorithm. Normally, adaptive +compression is enabled with <tt class="docutils literal"><span class="pre">--comp-lzo</span></tt>.</p> +<p class="last">Adaptive compression tries to optimize the case where you have +compression enabled, but you are sending predominantly incompressible +(or pre-compressed) packets over the tunnel, such as an FTP or rsync +transfer of a large, compressed file. With adaptive compression, OpenVPN +will periodically sample the compression process to measure its +efficiency. If the data being sent over the tunnel is already +compressed, the compression efficiency will be very low, triggering +openvpn to disable compression for a period of time until the next +re-sample test.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--key-direction</span></kbd></td> +</tr> +<tr><td> </td><td>Alternative way of specifying the optional direction parameter for the +<tt class="docutils literal"><span class="pre">--tls-auth</span></tt> and <tt class="docutils literal"><span class="pre">--secret</span></tt> options. Useful when using inline files +(See section on inline files).</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--keysize <var>n</var></span></kbd></td> +<td><p class="first"><strong>DEPRECATED</strong> This option will be removed in OpenVPN 2.6.</p> +<p class="last">Size of cipher key in bits (optional). If unspecified, defaults to +cipher-specific default. The <tt class="docutils literal"><span class="pre">--show-ciphers</span></tt> option (see below) shows +all available OpenSSL ciphers, their default key sizes, and whether the +key size can be changed. Use care in changing a cipher's default key +size. Many ciphers have not been extensively cryptanalyzed with +non-standard key lengths, and a larger key may offer no real guarantee +of greater security, or may even reduce security.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--data-ciphers <var>cipher-list</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Restrict the allowed ciphers to be negotiated to the ciphers in +<tt class="docutils literal"><span class="pre">cipher-list</span></tt>. <tt class="docutils literal"><span class="pre">cipher-list</span></tt> is a colon-separated list of ciphers, +and defaults to <code>AES-256-GCM:AES-128-GCM</code>.</p> +<p>For servers, the first cipher from <tt class="docutils literal"><span class="pre">cipher-list</span></tt> that is also +supported by the client will be pushed to clients that support cipher +negotiation.</p> +<p>Cipher negotiation is enabled in client-server mode only. I.e. if +<tt class="docutils literal"><span class="pre">--mode</span></tt> is set to 'server' (server-side, implied by setting +<tt class="docutils literal"><span class="pre">--server</span></tt> ), or if <tt class="docutils literal"><span class="pre">--pull</span></tt> is specified (client-side, implied by +setting --client).</p> +<p>If no common cipher is found during cipher negotiation, the connection +is terminated. To support old clients/old servers that do not provide any +cipher negotiation support see <tt class="docutils literal"><span class="pre">--data-ciphers-fallback</span></tt>.</p> +<p>Additionally, to allow for more smooth transition, if NCP is enabled, +OpenVPN will inherit the cipher of the peer if that cipher is different +from the local <tt class="docutils literal"><span class="pre">--cipher</span></tt> setting, but the peer cipher is one of the +ciphers specified in <tt class="docutils literal"><span class="pre">--data-ciphers</span></tt>. E.g. a non-NCP client (<=v2.3, +or with --ncp-disabled set) connecting to a NCP server (v2.4+) with +<tt class="docutils literal"><span class="pre">--cipher</span> <span class="pre">BF-CBC</span></tt> and <tt class="docutils literal"><span class="pre">--data-ciphers</span> <span class="pre">AES-256-GCM:AES-256-CBC</span></tt> set can +either specify <tt class="docutils literal"><span class="pre">--cipher</span> <span class="pre">BF-CBC</span></tt> or <tt class="docutils literal"><span class="pre">--cipher</span> <span class="pre">AES-256-CBC</span></tt> and both +will work.</p> +<p>Note for using NCP with an OpenVPN 2.4 peer: This list must include the +<code>AES-256-GCM</code> and <code>AES-128-GCM</code> ciphers.</p> +<p>This list is restricted to be 127 chars long after conversion to OpenVPN +ciphers.</p> +<p class="last">This option was called <tt class="docutils literal"><span class="pre">--ncp-ciphers</span></tt> in OpenVPN 2.4 but has been renamed +to <tt class="docutils literal"><span class="pre">--data-ciphers</span></tt> in OpenVPN 2.5 to more accurately reflect its meaning.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--data-ciphers-fallback <var>alg</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Configure a cipher that is used to fall back to if we could not determine +which cipher the peer is willing to use.</p> +<p class="last">This option should only be needed to +connect to peers that are running OpenVPN 2.3 and older version, and +have been configured with <cite>--enable-small</cite> +(typically used on routers or other embedded devices).</p> +</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--ncp-disable</span></kbd></td> +<td><strong>DEPRECATED</strong> Disable "Negotiable Crypto Parameters". This completely +disables cipher negotiation.</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--secret <var>args</var></span></kbd></td> +<td><p class="first">Enable Static Key encryption mode (non-TLS). Use pre-shared secret +<tt class="docutils literal">file</tt> which was generated with <tt class="docutils literal"><span class="pre">--genkey</span></tt>.</p> +<p>Valid syntaxes:</p> +<pre class="literal-block"> +secret file +secret file direction +</pre> +<p>The optional <tt class="docutils literal">direction</tt> parameter enables the use of 4 distinct keys +(HMAC-send, cipher-encrypt, HMAC-receive, cipher-decrypt), so that each +data flow direction has a different set of HMAC and cipher keys. This +has a number of desirable security properties including eliminating +certain kinds of DoS and message replay attacks.</p> +<p>When the <tt class="docutils literal">direction</tt> parameter is omitted, 2 keys are used +bidirectionally, one for HMAC and the other for encryption/decryption.</p> +<p>The <tt class="docutils literal">direction</tt> parameter should always be complementary on either +side of the connection, i.e. one side should use <code>0</code> and the other +should use <code>1</code>, or both sides should omit it altogether.</p> +<p>The <tt class="docutils literal">direction</tt> parameter requires that <tt class="docutils literal">file</tt> contains a 2048 bit +key. While pre-1.5 versions of OpenVPN generate 1024 bit key files, any +version of OpenVPN which supports the <tt class="docutils literal">direction</tt> parameter, will also +support 2048 bit key file generation using the <tt class="docutils literal"><span class="pre">--genkey</span></tt> option.</p> +<p>Static key encryption mode has certain advantages, the primary being +ease of configuration.</p> +<p>There are no certificates or certificate authorities or complicated +negotiation handshakes and protocols. The only requirement is that you +have a pre-existing secure channel with your peer (such as <tt class="docutils literal">ssh</tt>) to +initially copy the key. This requirement, along with the fact that your +key never changes unless you manually generate a new one, makes it +somewhat less secure than TLS mode (see below). If an attacker manages +to steal your key, everything that was ever encrypted with it is +compromised. Contrast that to the perfect forward secrecy features of +TLS mode (using Diffie Hellman key exchange), where even if an attacker +was able to steal your private key, he would gain no information to help +him decrypt past sessions.</p> +<p class="last">Another advantageous aspect of Static Key encryption mode is that it is +a handshake-free protocol without any distinguishing signature or +feature (such as a header or protocol handshake sequence) that would +mark the ciphertext packets as being generated by OpenVPN. Anyone +eavesdropping on the wire would see nothing but random-looking data.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--tran-window <var>n</var></span></kbd></td> +</tr> +<tr><td> </td><td>Transition window -- our old key can live this many seconds after a new +a key renegotiation begins (default <code>3600</code> seconds). This feature +allows for a graceful transition from old to new key, and removes the key +renegotiation sequence from the critical path of tunnel data forwarding.</td></tr> +</tbody> +</table> +</div> +<div class="section" id="client-options"> +<h2>Client Options</h2> +<p>The client options are used when connecting to an OpenVPN server configured +to use <tt class="docutils literal"><span class="pre">--server</span></tt>, <tt class="docutils literal"><span class="pre">--server-bridge</span></tt>, or <tt class="docutils literal"><span class="pre">--mode</span> server</tt> in its +configuration.</p> +<table class="docutils option-list" frame="void" rules="none"> +<col class="option" /> +<col class="description" /> +<tbody valign="top"> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--allow-pull-fqdn</span></kbd></td> +</tr> +<tr><td> </td><td>Allow client to pull DNS names from server (rather than being limited to +IP address) for <tt class="docutils literal"><span class="pre">--ifconfig</span></tt>, <tt class="docutils literal"><span class="pre">--route</span></tt>, and <tt class="docutils literal"><span class="pre">--route-gateway</span></tt>.</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--allow-recursive-routing</span></kbd></td> +</tr> +<tr><td> </td><td>When this option is set, OpenVPN will not drop incoming tun packets with +same destination as host.</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--auth-token <var>token</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">This is not an option to be used directly in any configuration files, +but rather push this option from a <tt class="docutils literal"><span class="pre">--client-connect</span></tt> script or a +<tt class="docutils literal"><span class="pre">--plugin</span></tt> which hooks into the <code>OPENVPN_PLUGIN_CLIENT_CONNECT</code> +or <code>OPENVPN_PLUGIN_CLIENT_CONNECT_V2</code> calls. This option provides a +possibility to replace the clients password with an authentication token +during the lifetime of the OpenVPN client.</p> +<p>Whenever the connection is renegotiated and the +<tt class="docutils literal"><span class="pre">--auth-user-pass-verify</span></tt> script or <tt class="docutils literal"><span class="pre">--plugin</span></tt> making use of the +<code>OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY</code> hook is triggered, it will +pass over this token as the password instead of the password the user +provided. The authentication token can only be reset by a full reconnect +where the server can push new options to the client. The password the +user entered is never preserved once an authentication token has been +set. If the OpenVPN server side rejects the authentication token then +the client will receive an <code>AUTH_FAILED</code> and disconnect.</p> +<p>The purpose of this is to enable two factor authentication methods, such +as HOTP or TOTP, to be used without needing to retrieve a new OTP code +each time the connection is renegotiated. Another use case is to cache +authentication data on the client without needing to have the users +password cached in memory during the life time of the session.</p> +<p>To make use of this feature, the <tt class="docutils literal"><span class="pre">--client-connect</span></tt> script or +<tt class="docutils literal"><span class="pre">--plugin</span></tt> needs to put</p> +<pre class="literal-block"> +push "auth-token UNIQUE_TOKEN_VALUE" +</pre> +<p>into the file/buffer for dynamic configuration data. This will then make +the OpenVPN server to push this value to the client, which replaces the +local password with the <tt class="docutils literal">UNIQUE_TOKEN_VALUE</tt>.</p> +<p class="last">Newer clients (2.4.7+) will fall back to the original password method +after a failed auth. Older clients will keep using the token value and +react according to <tt class="docutils literal"><span class="pre">--auth-retry</span></tt></p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--auth-token-user <var>base64username</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Companion option to <tt class="docutils literal"><span class="pre">--auth-token</span></tt>. This options allows to override +the username used by the client when reauthenticating with the <tt class="docutils literal"><span class="pre">auth-token</span></tt>. +It also allows to use <tt class="docutils literal"><span class="pre">--auth-token</span></tt> in setups that normally do not use +username and password.</p> +<p class="last">The username has to be base64 encoded.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--auth-user-pass</span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Authenticate with server using username/password.</p> +<p>Valid syntaxes:</p> +<pre class="literal-block"> +auth-user-pass +auth-user-pass up +</pre> +<p>If <tt class="docutils literal">up</tt> is present, it must be a file containing username/password on 2 +lines. If the password line is missing, OpenVPN will prompt for one.</p> +<p>If <tt class="docutils literal">up</tt> is omitted, username/password will be prompted from the +console.</p> +<p class="last">The server configuration must specify an <tt class="docutils literal"><span class="pre">--auth-user-pass-verify</span></tt> +script to verify the username/password provided by the client.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--auth-retry <var>type</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Controls how OpenVPN responds to username/password verification errors +such as the client-side response to an <code>AUTH_FAILED</code> message from +the server or verification failure of the private key password.</p> +<p>Normally used to prevent auth errors from being fatal on the client +side, and to permit username/password requeries in case of error.</p> +<p>An <code>AUTH_FAILED</code> message is generated by the server if the client +fails <tt class="docutils literal"><span class="pre">--auth-user-pass</span></tt> authentication, or if the server-side +<tt class="docutils literal"><span class="pre">--client-connect</span></tt> script returns an error status when the client +tries to connect.</p> +<p><tt class="docutils literal">type</tt> can be one of:</p> +<dl class="docutils"> +<dt><code>none</code></dt> +<dd>Client will exit with a fatal error (this is the default).</dd> +<dt><code>nointeract</code></dt> +<dd>Client will retry the connection without requerying +for an <tt class="docutils literal"><span class="pre">--auth-user-pass</span></tt> username/password. Use this option for +unattended clients.</dd> +<dt><code>interact</code></dt> +<dd>Client will requery for an <tt class="docutils literal"><span class="pre">--auth-user-pass</span></tt> +username/password and/or private key password before attempting a +reconnection.</dd> +</dl> +<p class="last">Note that while this option cannot be pushed, it can be controlled from +the management interface.</p> +</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--client</span></kbd></td> +<td><p class="first">A helper directive designed to simplify the configuration of OpenVPN's +client mode. This directive is equivalent to:</p> +<pre class="last literal-block"> +pull +tls-client +</pre> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--client-nat <var>args</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">This pushable client option sets up a stateless one-to-one NAT rule on +packet addresses (not ports), and is useful in cases where routes or +ifconfig settings pushed to the client would create an IP numbering +conflict.</p> +<p>Examples:</p> +<pre class="literal-block"> +client-nat snat 192.168.0.0/255.255.0.0 +client-nat dnat 10.64.0.0/255.255.0.0 +</pre> +<p><tt class="docutils literal">network/netmask</tt> (for example <code>192.168.0.0/255.255.0.0</code>) defines +the local view of a resource from the client perspective, while +<tt class="docutils literal">alias/netmask</tt> (for example <code>10.64.0.0/255.255.0.0</code>) defines the +remote view from the server perspective.</p> +<p>Use <code>snat</code> (source NAT) for resources owned by the client and +<code>dnat</code> (destination NAT) for remote resources.</p> +<p class="last">Set <tt class="docutils literal"><span class="pre">--verb</span> 6</tt> for debugging info showing the transformation of +src/dest addresses in packets.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--connect-retry <var>n</var></span></kbd></td> +</tr> +<tr><td> </td><td>Wait <tt class="docutils literal">n</tt> seconds between connection attempts (default <code>5</code>). +Repeated reconnection attempts are slowed down after 5 retries per +remote by doubling the wait time after each unsuccessful attempt. An +optional argument <tt class="docutils literal">max</tt> specifies the maximum value of wait time in +seconds at which it gets capped (default <code>300</code>).</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--connect-retry-max <var>n</var></span></kbd></td> +</tr> +<tr><td> </td><td><tt class="docutils literal">n</tt> specifies the number of times each <tt class="docutils literal"><span class="pre">--remote</span></tt> or +<tt class="docutils literal"><connection></tt> entry is tried. Specifying <tt class="docutils literal">n</tt> as <code>1</code> would try +each entry exactly once. A successful connection resets the counter. +(default <em>unlimited</em>).</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--connect-timeout <var>n</var></span></kbd></td> +</tr> +<tr><td> </td><td>See <tt class="docutils literal"><span class="pre">--server-poll-timeout</span></tt>.</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--explicit-exit-notify <var>n</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">In UDP client mode or point-to-point mode, send server/peer an exit +notification if tunnel is restarted or OpenVPN process is exited. In +client mode, on exit/restart, this option will tell the server to +immediately close its client instance object rather than waiting for a +timeout.</p> +<p>The <strong>n</strong> parameter (default <code>1</code> if not present) controls the +maximum number of attempts that the client will try to resend the exit +notification message.</p> +<p>In UDP server mode, send <code>RESTART</code> control channel command to +connected clients. The <tt class="docutils literal">n</tt> parameter (default <code>1</code> if not present) +controls client behavior. With <tt class="docutils literal">n</tt> = <code>1</code> client will attempt to +reconnect to the same server, with <tt class="docutils literal">n</tt> = <code>2</code> client will advance +to the next server.</p> +<p class="last">OpenVPN will not send any exit notifications unless this option is +enabled.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--inactive <var>args</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Causes OpenVPN to exit after <tt class="docutils literal">n</tt> seconds of inactivity on the TUN/TAP +device. The time length of inactivity is measured since the last +incoming or outgoing tunnel packet. The default value is 0 seconds, +which disables this feature.</p> +<p>Valid syntaxes:</p> +<pre class="literal-block"> +inactive n +inactive n bytes +</pre> +<p>If the optional <tt class="docutils literal">bytes</tt> parameter is included, exit if less than +<tt class="docutils literal">bytes</tt> of combined in/out traffic are produced on the tun/tap device +in <tt class="docutils literal">n</tt> seconds.</p> +<p class="last">In any case, OpenVPN's internal ping packets (which are just keepalives) +and TLS control packets are not considered "activity", nor are they +counted as traffic, as they are used internally by OpenVPN and are not +an indication of actual user activity.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--proto-force <var>p</var></span></kbd></td> +</tr> +<tr><td> </td><td>When iterating through connection profiles, only consider profiles using +protocol <tt class="docutils literal">p</tt> (<code>tcp</code> | <code>udp</code>).</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--pull</span></kbd></td> +<td><p class="first">This option must be used on a client which is connecting to a +multi-client server. It indicates to OpenVPN that it should accept +options pushed by the server, provided they are part of the legal set of +pushable options (note that the <tt class="docutils literal"><span class="pre">--pull</span></tt> option is implied by +<tt class="docutils literal"><span class="pre">--client</span></tt> ).</p> +<p class="last">In particular, <tt class="docutils literal"><span class="pre">--pull</span></tt> allows the server to push routes to the +client, so you should not use <tt class="docutils literal"><span class="pre">--pull</span></tt> or <tt class="docutils literal"><span class="pre">--client</span></tt> in situations +where you don't trust the server to have control over the client's +routing table.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--pull-filter <var>args</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Filter options on the client pushed by the server to the client.</p> +<p>Valid syntaxes:</p> +<pre class="literal-block"> +pull-filter accept text +pull-filter ignore text +pull-filter reject text +</pre> +<p>Filter options received from the server if the option starts with +<code>text</code>. The action flag <code>accept</code> allows the option, +<code>ignore</code> removes it and <code>reject</code> flags an error and triggers +a <code>SIGUSR1</code> restart. The filters may be specified multiple times, +and each filter is applied in the order it is specified. The filtering of +each option stops as soon as a match is found. Unmatched options are accepted +by default.</p> +<p>Prefix comparison is used to match <code>text</code> against the received option so +that</p> +<pre class="literal-block"> +pull-filter ignore "route" +</pre> +<p>would remove all pushed options starting with <tt class="docutils literal">route</tt> which would +include, for example, <tt class="docutils literal"><span class="pre">route-gateway</span></tt>. Enclose <em>text</em> in quotes to +embed spaces.</p> +<pre class="literal-block"> +pull-filter accept "route 192.168.1." +pull-filter ignore "route " +</pre> +<p>would remove all routes that do not start with <tt class="docutils literal">192.168.1</tt>.</p> +<p class="last"><em>Note</em> that <code>reject</code> may result in a repeated cycle of failure and +reconnect, unless multiple remotes are specified and connection to the +next remote succeeds. To silently ignore an option pushed by the server, +use <code>ignore</code>.</p> +</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--remote <var>args</var></span></kbd></td> +<td><p class="first">Remote host name or IP address, port and protocol.</p> +<p>Valid syntaxes:</p> +<pre class="literal-block"> +remote host +remote host port +remote host port proto +</pre> +<p>The <tt class="docutils literal">port</tt> and <tt class="docutils literal">proto</tt> arguments are optional. The OpenVPN client +will try to connect to a server at <tt class="docutils literal">host:port</tt>. The <tt class="docutils literal">proto</tt> argument +indicates the protocol to use when connecting with the remote, and may be +<code>tcp</code> or <code>udp</code>. To enforce IPv4 or IPv6 connections add a +<code>4</code> or <code>6</code> suffix; like <code>udp4</code> / <code>udp6</code> +/ <code>tcp4</code> / <code>tcp6</code>.</p> +<p>On the client, multiple <tt class="docutils literal"><span class="pre">--remote</span></tt> options may be specified for +redundancy, each referring to a different OpenVPN server, in the order +specified by the list of <tt class="docutils literal"><span class="pre">--remote</span></tt> options. Specifying multiple +<tt class="docutils literal"><span class="pre">--remote</span></tt> options for this purpose is a special case of the more +general connection-profile feature. See the <tt class="docutils literal"><connection></tt> +documentation below.</p> +<p>The client will move on to the next host in the list, in the event of +connection failure. Note that at any given time, the OpenVPN client will +at most be connected to one server.</p> +<p>Examples:</p> +<pre class="literal-block"> +remote server1.example.net +remote server1.example.net 1194 +remote server2.example.net 1194 tcp +</pre> +<dl class="docutils"> +<dt><em>Note:</em></dt> +<dd><p class="first">Since UDP is connectionless, connection failure is defined by +the <tt class="docutils literal"><span class="pre">--ping</span></tt> and <tt class="docutils literal"><span class="pre">--ping-restart</span></tt> options.</p> +<p class="last">Also, if you use multiple <tt class="docutils literal"><span class="pre">--remote</span></tt> options, AND you are dropping +root privileges on the client with <tt class="docutils literal"><span class="pre">--user</span></tt> and/or <tt class="docutils literal"><span class="pre">--group</span></tt> AND +the client is running a non-Windows OS, if the client needs to switch +to a different server, and that server pushes back different TUN/TAP +or route settings, the client may lack the necessary privileges to +close and reopen the TUN/TAP interface. This could cause the client +to exit with a fatal error.</p> +</dd> +</dl> +<p>If <tt class="docutils literal"><span class="pre">--remote</span></tt> is unspecified, OpenVPN will listen for packets from any +IP address, but will not act on those packets unless they pass all +authentication tests. This requirement for authentication is binding on +all potential peers, even those from known and supposedly trusted IP +addresses (it is very easy to forge a source IP address on a UDP +packet).</p> +<p>When used in TCP mode, <tt class="docutils literal"><span class="pre">--remote</span></tt> will act as a filter, rejecting +connections from any host which does not match <tt class="docutils literal">host</tt>.</p> +<p class="last">If <tt class="docutils literal">host</tt> is a DNS name which resolves to multiple IP addresses, +OpenVPN will try them in the order that the system getaddrinfo() +presents them, so priorization and DNS randomization is done by the +system library. Unless an IP version is forced by the protocol +specification (4/6 suffix), OpenVPN will try both IPv4 and IPv6 +addresses, in the order getaddrinfo() returns them.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--remote-random</span></kbd></td> +</tr> +<tr><td> </td><td>When multiple <tt class="docutils literal"><span class="pre">--remote</span></tt> address/ports are specified, or if connection +profiles are being used, initially randomize the order of the list as a +kind of basic load-balancing measure.</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--remote-random-hostname</span></kbd></td> +</tr> +<tr><td> </td><td>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".</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--resolv-retry <var>n</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">If hostname resolve fails for <tt class="docutils literal"><span class="pre">--remote</span></tt>, retry resolve for <tt class="docutils literal">n</tt> +seconds before failing.</p> +<p>Set <tt class="docutils literal">n</tt> to "infinite" to retry indefinitely.</p> +<p class="last">By default, <tt class="docutils literal"><span class="pre">--resolv-retry</span> infinite</tt> is enabled. You can disable by +setting n=0.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--single-session</span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">After initially connecting to a remote peer, disallow any new +connections. Using this option means that a remote peer cannot connect, +disconnect, and then reconnect.</p> +<p>If the daemon is reset by a signal or <tt class="docutils literal"><span class="pre">--ping-restart</span></tt>, it will allow +one new connection.</p> +<p class="last"><tt class="docutils literal"><span class="pre">--single-session</span></tt> can be used with <tt class="docutils literal"><span class="pre">--ping-exit</span></tt> or <tt class="docutils literal"><span class="pre">--inactive</span></tt> +to create a single dynamic session that will exit when finished.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--server-poll-timeout <var>n</var></span></kbd></td> +</tr> +<tr><td> </td><td>When connecting to a remote server do not wait for more than <tt class="docutils literal">n</tt> +seconds for a response before trying the next server. The default value +is 120s. This timeout includes proxy and TCP connect timeouts.</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--static-challenge <var>args</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Enable static challenge/response protocol</p> +<p>Valid syntax:</p> +<pre class="literal-block"> +static-challenge text echo +</pre> +<p>The <tt class="docutils literal">text</tt> challenge text is presented to the user which describes what +information is requested. The <tt class="docutils literal">echo</tt> flag indicates if the user's +input should be echoed on the screen. Valid <tt class="docutils literal">echo</tt> values are +<code>0</code> or <code>1</code>.</p> +<p class="last">See management-notes.txt in the OpenVPN distribution for a description of +the OpenVPN challenge/response protocol.</p> +</td></tr> +</tbody> +</table> +<table class="docutils option-list" frame="void" rules="none"> +<col class="option" /> +<col class="description" /> +<tbody valign="top"> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--show-proxy-settings</span></kbd></td> +</tr> +<tr><td> </td><td>Show sensed HTTP or SOCKS proxy settings. Currently, only Windows +clients support this option.</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--http-proxy <var>args</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Connect to remote host through an HTTP proxy. This requires at least an +address <tt class="docutils literal">server</tt> and <tt class="docutils literal">port</tt> argument. If HTTP Proxy-Authenticate +is required, a file name to an <tt class="docutils literal">authfile</tt> file containing a username +and password on 2 lines can be given, or <code>stdin</code> to prompt from +console. Its content can also be specified in the config file with the +<tt class="docutils literal"><span class="pre">--http-proxy-user-pass</span></tt> option. (See section on inline files)</p> +<p>The last optional argument is an <tt class="docutils literal"><span class="pre">auth-method</span></tt> which should be one +of <code>none</code>, <code>basic</code>, or <code>ntlm</code>.</p> +<p>HTTP Digest authentication is supported as well, but only via the +<code>auto</code> or <code>auto-nct</code> flags (below). This must replace +the <tt class="docutils literal">authfile</tt> argument.</p> +<p>The <code>auto</code> flag causes OpenVPN to automatically determine the +<tt class="docutils literal"><span class="pre">auth-method</span></tt> and query stdin or the management interface for +username/password credentials, if required. This flag exists on OpenVPN +2.1 or higher.</p> +<p>The <tt class="docutils literal"><span class="pre">auto-nct</span></tt> flag (no clear-text auth) instructs OpenVPN to +automatically determine the authentication method, but to reject weak +authentication protocols such as HTTP Basic Authentication.</p> +<p>Examples:</p> +<pre class="last literal-block"> +http-proxy proxy.example.net 3128 +http-proxy proxy.example.net 3128 authfile.txt +http-proxy proxy.example.net 3128 stdin +http-proxy proxy.example.net 3128 auto basic +http-proxy proxy.example.net 3128 auto-nct ntlm +</pre> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--http-proxy-option <var>args</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Set extended HTTP proxy options. Requires an option <tt class="docutils literal">type</tt> as argument +and an optional <tt class="docutils literal">parameter</tt> to the type. Repeat to set multiple +options.</p> +<dl class="docutils"> +<dt><code>VERSION</code> <tt class="docutils literal">version</tt></dt> +<dd>Set HTTP version number to <tt class="docutils literal">version</tt> (default <code>1.0</code>).</dd> +<dt><code>AGENT</code> <tt class="docutils literal"><span class="pre">user-agent</span></tt></dt> +<dd>Set HTTP "User-Agent" string to <tt class="docutils literal"><span class="pre">user-agent</span></tt>.</dd> +<dt><code>CUSTOM-HEADER</code> <tt class="docutils literal">name</tt> <tt class="docutils literal">content</tt></dt> +<dd>Adds the custom Header with <tt class="docutils literal">name</tt> as name and <tt class="docutils literal">content</tt> as +the content of the custom HTTP header.</dd> +</dl> +<p>Examples:</p> +<pre class="last literal-block"> +http-proxy-option VERSION 1.1 +http-proxy-option AGENT OpenVPN/2.4 +http-proxy-option X-Proxy-Flag some-flags +</pre> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--socks-proxy <var>args</var></span></kbd></td> +</tr> +<tr><td> </td><td>Connect to remote host through a Socks5 proxy. A required <tt class="docutils literal">server</tt> +argument is needed. Optionally a <tt class="docutils literal">port</tt> (default <code>1080</code>) and +<tt class="docutils literal">authfile</tt> can be given. The <tt class="docutils literal">authfile</tt> is a file containing a +username and password on 2 lines, or <code>stdin</code> can be used to +prompt from console.</td></tr> +</tbody> +</table> +</div> +<div class="section" id="server-options"> +<h2>Server Options</h2> +<p>Starting with OpenVPN 2.0, a multi-client TCP/UDP server mode is +supported, and can be enabled with the <tt class="docutils literal"><span class="pre">--mode</span> server</tt> option. In +server mode, OpenVPN will listen on a single port for incoming client +connections. All client connections will be routed through a single tun +or tap interface. This mode is designed for scalability and should be +able to support hundreds or even thousands of clients on sufficiently +fast hardware. SSL/TLS authentication must be used in this mode.</p> +<table class="docutils option-list" frame="void" rules="none"> +<col class="option" /> +<col class="description" /> +<tbody valign="top"> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--auth-gen-token <var>args</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Returns an authentication token to successfully authenticated clients.</p> +<p>Valid syntax:</p> +<pre class="literal-block"> +auth-gen-token [lifetime] [external-auth] +</pre> +<p>After successful user/password authentication, the OpenVPN server will +with this option generate a temporary authentication token and push that +to the client. On the following renegotiations, the OpenVPN client will pass +this token instead of the users password. On the server side the server +will do the token authentication internally and it will NOT do any +additional authentications against configured external user/password +authentication mechanisms.</p> +<p>The tokens implemented by this mechanism include an initial timestamp and +a renew timestamp and are secured by HMAC.</p> +<p>The <tt class="docutils literal">lifetime</tt> argument defines how long the generated token is valid. +The lifetime is defined in seconds. If lifetime is not set or it is set +to <code>0</code>, the token will never expire.</p> +<p>The token will expire either after the configured <tt class="docutils literal">lifetime</tt> of the +token is reached or after not being renewed for more than 2 * +<tt class="docutils literal"><span class="pre">reneg-sec</span></tt> seconds. Clients will be sent renewed tokens on every TLS +renogiation to keep the client's token updated. This is done to +invalidate a token if a client is disconnected for a sufficently long +time, while at the same time permitting much longer token lifetimes for +active clients.</p> +<p>This feature is useful for environments which are configured to use One +Time Passwords (OTP) as part of the user/password authentications and +that authentication mechanism does not implement any auth-token support.</p> +<p>When the <code>external-auth</code> keyword is present the normal +authentication method will always be called even if auth-token succeeds. +Normally other authentications method are skipped if auth-token +verification suceeds or fails.</p> +<p>This option postpones this decision to the external authentication +methods and checks the validity of the account and do other checks.</p> +<p>In this mode the environment will have a <tt class="docutils literal">session_id</tt> variable that +holds the session id from auth-gen-token. Also an environment variable +<tt class="docutils literal">session_state</tt> is present. This variable indicates whether the +auth-token has succeeded or not. It can have the following values:</p> +<dl class="docutils"> +<dt><code>Initial</code></dt> +<dd>No token from client.</dd> +<dt><code>Authenticated</code></dt> +<dd>Token is valid and not expired.</dd> +<dt><code>Expired</code></dt> +<dd>Token is valid but has expired.</dd> +<dt><code>Invalid</code></dt> +<dd>Token is invalid (failed HMAC or wrong length)</dd> +<dt><code>AuthenticatedEmptyUser</code> / <code>ExpiredEmptyUser</code></dt> +<dd>The token is not valid with the username sent from the client but +would be valid (or expired) if we assume an empty username was +used instead. These two cases are a workaround for behaviour in +OpenVPN 3. If this workaround is not needed these two cases should +be handled in the same way as <code>Invalid</code>.</dd> +</dl> +<p class="last"><strong>Warning:</strong> Use this feature only if you want your authentication +method called on every verification. Since the external authentication +is called it needs to also indicate a success or failure of the +authentication. It is strongly recommended to return an authentication +failure in the case of the Invalid/Expired auth-token with the +external-auth option unless the client could authenticate in another +acceptable way (e.g. client certificate), otherwise returning success +will lead to authentication bypass (as does returning success on a wrong +password from a script).</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--auth-gen-token-secret <var>file</var></span></kbd></td> +</tr> +<tr><td> </td><td>Specifies a file that holds a secret for the HMAC used in +<tt class="docutils literal"><span class="pre">--auth-gen-token</span></tt> If <tt class="docutils literal">file</tt> is not present OpenVPN will generate a +random secret on startup. This file should be used if auth-token should +validate after restarting a server or if client should be able to roam +between multiple OpenVPN servers with their auth-token.</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--auth-user-pass-optional</span></kbd></td> +</tr> +<tr><td> </td><td>Allow connections by clients that do not specify a username/password. +Normally, when <tt class="docutils literal"><span class="pre">--auth-user-pass-verify</span></tt> or +<tt class="docutils literal"><span class="pre">--management-client-auth</span></tt> are specified (or an authentication plugin +module), the OpenVPN server daemon will require connecting clients to +specify a username and password. This option makes the submission of a +username/password by clients optional, passing the responsibility to the +user-defined authentication module/script to accept or deny the client +based on other factors (such as the setting of X509 certificate fields). +When this option is used, and a connecting client does not submit a +username/password, the user-defined authentication module/script will +see the username and password as being set to empty strings (""). The +authentication module/script MUST have logic to detect this condition +and respond accordingly.</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--ccd-exclusive</span></kbd></td> +</tr> +<tr><td> </td><td>Require, as a condition of authentication, that a connecting client has +a <tt class="docutils literal"><span class="pre">--client-config-dir</span></tt> file.</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--client-config-dir <var>dir</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Specify a directory <tt class="docutils literal">dir</tt> for custom client config files. After a +connecting client has been authenticated, OpenVPN will look in this +directory for a file having the same name as the client's X509 common +name. If a matching file exists, it will be opened and parsed for +client-specific configuration options. If no matching file is found, +OpenVPN will instead try to open and parse a default file called +"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.</p> +<p>This file can specify a fixed IP address for a given client using +<tt class="docutils literal"><span class="pre">--ifconfig-push</span></tt>, as well as fixed subnets owned by the client using +<tt class="docutils literal"><span class="pre">--iroute</span></tt>.</p> +<p>One of the useful properties of this option is that it allows client +configuration files to be conveniently created, edited, or removed while +the server is live, without needing to restart the server.</p> +<p class="last">The following options are legal in a client-specific context: <tt class="docutils literal"><span class="pre">--push</span></tt>, +<tt class="docutils literal"><span class="pre">--push-reset</span></tt>, <tt class="docutils literal"><span class="pre">--push-remove</span></tt>, <tt class="docutils literal"><span class="pre">--iroute</span></tt>, <tt class="docutils literal"><span class="pre">--ifconfig-push</span></tt>, +<tt class="docutils literal"><span class="pre">--vlan-pvid</span></tt> and <tt class="docutils literal"><span class="pre">--config</span></tt>.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--client-to-client</span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Because the OpenVPN server mode handles multiple clients through a +single tun or tap interface, it is effectively a router. The +<tt class="docutils literal"><span class="pre">--client-to-client</span></tt> flag tells OpenVPN to internally route +client-to-client traffic rather than pushing all client-originating +traffic to the TUN/TAP interface.</p> +<p class="last">When this option is used, each client will "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.</p> +</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--disable</span></kbd></td> +<td><p class="first">Disable a particular client (based on the common name) from connecting. +Don't use this option to disable a client due to key or password +compromise. Use a CRL (certificate revocation list) instead (see the +<tt class="docutils literal"><span class="pre">--crl-verify</span></tt> option).</p> +<p class="last">This option must be associated with a specific client instance, which +means that it must be specified either in a client instance config file +using <tt class="docutils literal"><span class="pre">--client-config-dir</span></tt> or dynamically generated using a +<tt class="docutils literal"><span class="pre">--client-connect</span></tt> script.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--connect-freq <var>args</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Allow a maximum of <tt class="docutils literal">n</tt> new connections per <tt class="docutils literal">sec</tt> seconds from +clients.</p> +<p>Valid syntax:</p> +<pre class="literal-block"> +connect-freq n sec +</pre> +<p>This is designed to contain DoS attacks which flood the server +with connection requests using certificates which will ultimately fail +to authenticate.</p> +<p>This is an imperfect solution however, because in a real DoS scenario, +legitimate connections might also be refused.</p> +<p class="last">For the best protection against DoS attacks in server mode, use +<tt class="docutils literal"><span class="pre">--proto</span> udp</tt> and either <tt class="docutils literal"><span class="pre">--tls-auth</span></tt> or <tt class="docutils literal"><span class="pre">--tls-crypt</span></tt>.</p> +</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--duplicate-cn</span></kbd></td> +<td>Allow multiple clients with the same common name to concurrently +connect. In the absence of this option, OpenVPN will disconnect a client +instance upon connection of a new client having the same common name.</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--ifconfig-pool <var>args</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Set aside a pool of subnets to be dynamically allocated to connecting +clients, similar to a DHCP server.</p> +<p>Valid syntax:</p> +<pre class="literal-block"> +ifconfig-pool start-IP end-IP [netmask] +</pre> +<p class="last">For tun-style tunnels, each client +will be given a /30 subnet (for interoperability with Windows clients). +For tap-style tunnels, individual addresses will be allocated, and the +optional <tt class="docutils literal">netmask</tt> parameter will also be pushed to clients.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--ifconfig-ipv6-pool <var>args</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Specify an IPv6 address pool for dynamic assignment to clients.</p> +<p>Valid args:</p> +<pre class="literal-block"> +ifconfig-ipv6-pool ipv6addr/bits +</pre> +<p class="last">The pool starts at <tt class="docutils literal">ipv6addr</tt> and matches the offset determined from +the start of the IPv4 pool. If the host part of the given IPv6 +address is <tt class="docutils literal">0</tt>, the pool starts at <tt class="docutils literal">ipv6addr</tt> +1.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--ifconfig-pool-persist <var>args</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Persist/unpersist ifconfig-pool data to <tt class="docutils literal">file</tt>, at <tt class="docutils literal">seconds</tt> +intervals (default <code>600</code>), as well as on program startup and shutdown.</p> +<p>Valid syntax:</p> +<pre class="literal-block"> +ifconfig-pool-persist file [seconds] +</pre> +<p>The goal of this option is to provide a long-term association between +clients (denoted by their common name) and the virtual IP address +assigned to them from the ifconfig-pool. Maintaining a long-term +association is good for clients because it allows them to effectively +use the <tt class="docutils literal"><span class="pre">--persist-tun</span></tt> option.</p> +<p><tt class="docutils literal">file</tt> is a comma-delimited ASCII file, formatted as +<code><Common-Name>,<IP-address></code>.</p> +<p>If <tt class="docutils literal">seconds</tt> = <code>0</code>, <tt class="docutils literal">file</tt> will be treated as read-only. This +is useful if you would like to treat <tt class="docutils literal">file</tt> as a configuration file.</p> +<p class="last">Note that the entries in this file are treated by OpenVPN as +<em>suggestions</em> only, based on past associations between a common name and +IP address. They do not guarantee that the given common name will always +receive the given IP address. If you want guaranteed assignment, use +<tt class="docutils literal"><span class="pre">--ifconfig-push</span></tt></p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--ifconfig-push <var>args</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Push virtual IP endpoints for client tunnel, overriding the +<tt class="docutils literal"><span class="pre">--ifconfig-pool</span></tt> dynamic allocation.</p> +<p>Valid syntax:</p> +<pre class="literal-block"> +ifconfig-push local remote-netmask [alias] +</pre> +<p>The parameters <tt class="docutils literal">local</tt> and <tt class="docutils literal"><span class="pre">remote-netmask</span></tt> are set according to the +<tt class="docutils literal"><span class="pre">--ifconfig</span></tt> directive which you want to execute on the client machine +to configure the remote end of the tunnel. Note that the parameters +<tt class="docutils literal">local</tt> and <tt class="docutils literal"><span class="pre">remote-netmask</span></tt> are from the perspective of the client, +not the server. They may be DNS names rather than IP addresses, in which +case they will be resolved on the server at the time of client +connection.</p> +<p>The optional <tt class="docutils literal">alias</tt> parameter may be used in cases where NAT causes +the client view of its local endpoint to differ from the server view. In +this case <tt class="docutils literal"><span class="pre">local/remote-netmask</span></tt> will refer to the server view while +<tt class="docutils literal"><span class="pre">alias/remote-netmask</span></tt> will refer to the client view.</p> +<p>This option must be associated with a specific client instance, which +means that it must be specified either in a client instance config file +using <tt class="docutils literal"><span class="pre">--client-config-dir</span></tt> or dynamically generated using a +<tt class="docutils literal"><span class="pre">--client-connect</span></tt> script.</p> +<p>Remember also to include a <tt class="docutils literal"><span class="pre">--route</span></tt> directive in the main OpenVPN +config file which encloses <tt class="docutils literal">local</tt>, so that the kernel will know to +route it to the server's TUN/TAP interface.</p> +<p>OpenVPN's internal client IP address selection algorithm works as +follows:</p> +<ol class="last arabic simple"> +<li>Use <tt class="docutils literal"><span class="pre">--client-connect</span> script</tt> generated file for static IP +(first choice).</li> +<li>Use <tt class="docutils literal"><span class="pre">--client-config-dir</span></tt> file for static IP (next choice).</li> +<li>Use <tt class="docutils literal"><span class="pre">--ifconfig-pool</span></tt> allocation for dynamic IP (last +choice).</li> +</ol> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--ifconfig-ipv6-push <var>args</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">for <tt class="docutils literal"><span class="pre">--client-config-dir</span></tt> per-client static IPv6 interface +configuration, see <tt class="docutils literal"><span class="pre">--client-config-dir</span></tt> and <tt class="docutils literal"><span class="pre">--ifconfig-push</span></tt> for +more details.</p> +<p>Valid syntax:</p> +<pre class="last literal-block"> +ifconfig-ipv6-push ipv6addr/bits ipv6remote +</pre> +</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--inetd <var>args</var></span></kbd></td> +<td><p class="first">Valid syntaxes:</p> +<pre class="literal-block"> +inetd +inetd wait +inetd nowait +inetd wait progname +</pre> +<p>Use this option when OpenVPN is being run from the inetd or <tt class="docutils literal">xinetd</tt>(8) +server.</p> +<p>The <code>wait</code> and <code>nowait</code> option must match what is specified +in the inetd/xinetd config file. The <code>nowait</code> mode can only be used +with <tt class="docutils literal"><span class="pre">--proto</span> <span class="pre">tcp-server</span></tt> The default is <code>wait</code>. The +<code>nowait</code> mode can be used to instantiate the OpenVPN daemon as a +classic TCP server, where client connection requests are serviced on a +single port number. For additional information on this kind of +configuration, see the OpenVPN FAQ: +<a class="reference external" href="https://community.openvpn.net/openvpn/wiki/325-openvpn-as-a--forking-tcp-server-which-can-service-multiple-clients-over-a-single-tcp-port">https://community.openvpn.net/openvpn/wiki/325-openvpn-as-a--forking-tcp-server-which-can-service-multiple-clients-over-a-single-tcp-port</a></p> +<p>This option precludes the use of <tt class="docutils literal"><span class="pre">--daemon</span></tt>, <tt class="docutils literal"><span class="pre">--local</span></tt> or +<tt class="docutils literal"><span class="pre">--remote</span></tt>. Note that this option causes message and error output to +be handled in the same way as the <tt class="docutils literal"><span class="pre">--daemon</span></tt> option. The optional +<tt class="docutils literal">progname</tt> parameter is also handled exactly as in <tt class="docutils literal"><span class="pre">--daemon</span></tt>.</p> +<p class="last">Also note that in <tt class="docutils literal">wait</tt> mode, each OpenVPN tunnel requires a separate +TCP/UDP port and a separate inetd or xinetd entry. See the OpenVPN 1.x +HOWTO for an example on using OpenVPN with xinetd: +<a class="reference external" href="https://openvpn.net/community-resources/1xhowto/">https://openvpn.net/community-resources/1xhowto/</a></p> +</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--multihome</span></kbd></td> +<td><p class="first">Configure a multi-homed UDP server. This option needs to be used when a +server has more than one IP address (e.g. multiple interfaces, or +secondary IP addresses), and is not using <tt class="docutils literal"><span class="pre">--local</span></tt> to force binding +to one specific address only. This option will add some extra lookups to +the packet path to ensure that the UDP reply packets are always sent +from the address that the client is talking to. This is not supported on +all platforms, and it adds more processing, so it's not enabled by +default.</p> +<dl class="last docutils"> +<dt><em>Notes:</em></dt> +<dd><ul class="first last simple"> +<li>This option is only relevant for UDP servers.</li> +<li>If you do an IPv6+IPv4 dual-stack bind on a Linux machine with +multiple IPv4 address, connections to IPv4 addresses will not +work right on kernels before 3.15, due to missing kernel +support for the IPv4-mapped case (some distributions have +ported this to earlier kernel versions, though).</li> +</ul> +</dd> +</dl> +</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--iroute <var>args</var></span></kbd></td> +<td><p class="first">Generate an internal route to a specific client. The <tt class="docutils literal">netmask</tt> +parameter, if omitted, defaults to <code>255.255.255.255</code>.</p> +<p>Valid syntax:</p> +<pre class="literal-block"> +iroute network [netmask] +</pre> +<p>This directive can be used to route a fixed subnet from the server to a +particular client, regardless of where the client is connecting from. +Remember that you must also add the route to the system routing table as +well (such as by using the <tt class="docutils literal"><span class="pre">--route</span></tt> directive). The reason why two +routes are needed is that the <tt class="docutils literal"><span class="pre">--route</span></tt> directive routes the packet +from the kernel to OpenVPN. Once in OpenVPN, the <tt class="docutils literal"><span class="pre">--iroute</span></tt> directive +routes to the specific client.</p> +<p>This option must be specified either in a client instance config file +using <tt class="docutils literal"><span class="pre">--client-config-dir</span></tt> or dynamically generated using a +<tt class="docutils literal"><span class="pre">--client-connect</span></tt> script.</p> +<p class="last">The <tt class="docutils literal"><span class="pre">--iroute</span></tt> directive also has an important interaction with +<tt class="docutils literal"><span class="pre">--push</span> "route <span class="pre">..."</span></tt>. <tt class="docutils literal"><span class="pre">--iroute</span></tt> essentially defines a subnet which +is owned by a particular client (we will call this client <em>A</em>). If you +would like other clients to be able to reach <em>A</em>'s subnet, you can use +<tt class="docutils literal"><span class="pre">--push</span> "route <span class="pre">..."</span></tt> together with <tt class="docutils literal"><span class="pre">--client-to-client</span></tt> to effect +this. In order for all clients to see <em>A</em>'s subnet, OpenVPN must push +this route to all clients EXCEPT for <em>A</em>, since the subnet is already +owned by <em>A</em>. OpenVPN accomplishes this by not not pushing a route to +a client if it matches one of the client's iroutes.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--iroute-ipv6 <var>args</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">for <tt class="docutils literal"><span class="pre">--client-config-dir</span></tt> per-client static IPv6 route configuration, +see <tt class="docutils literal"><span class="pre">--iroute</span></tt> for more details how to setup and use this, and how +<tt class="docutils literal"><span class="pre">--iroute</span></tt> and <tt class="docutils literal"><span class="pre">--route</span></tt> interact.</p> +<p>Valid syntax:</p> +<pre class="last literal-block"> +iroute-ipv6 ipv6addr/bits +</pre> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--max-clients <var>n</var></span></kbd></td> +</tr> +<tr><td> </td><td>Limit server to a maximum of <tt class="docutils literal">n</tt> concurrent clients.</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--max-routes-per-client <var>n</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Allow a maximum of <tt class="docutils literal">n</tt> internal routes per client (default +<code>256</code>). This is designed to help contain DoS attacks where an +authenticated client floods the server with packets appearing to come +from many unique MAC addresses, forcing the server to deplete virtual +memory as its internal routing table expands. This directive can be used +in a <tt class="docutils literal"><span class="pre">--client-config-dir</span></tt> file or auto-generated by a +<tt class="docutils literal"><span class="pre">--client-connect</span></tt> script to override the global value for a particular +client.</p> +<p class="last">Note that this directive affects OpenVPN's internal routing table, not +the kernel routing table.</p> +</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--opt-verify</span></kbd></td> +<td><p class="first">Clients that connect with options that are incompatible with those of the +server will be disconnected.</p> +<p>Options that will be compared for compatibility include <tt class="docutils literal"><span class="pre">dev-type</span></tt>, +<tt class="docutils literal"><span class="pre">link-mtu</span></tt>, <tt class="docutils literal"><span class="pre">tun-mtu</span></tt>, <tt class="docutils literal">proto</tt>, <tt class="docutils literal">ifconfig</tt>, +<tt class="docutils literal"><span class="pre">comp-lzo</span></tt>, <tt class="docutils literal">fragment</tt>, <tt class="docutils literal">keydir</tt>, <tt class="docutils literal">cipher</tt>, +<tt class="docutils literal">auth</tt>, <tt class="docutils literal">keysize</tt>, <tt class="docutils literal">secret</tt>, <tt class="docutils literal"><span class="pre">no-replay</span></tt>, +<tt class="docutils literal"><span class="pre">tls-auth</span></tt>, <tt class="docutils literal"><span class="pre">key-method</span></tt>, <tt class="docutils literal"><span class="pre">tls-server</span></tt> +and <tt class="docutils literal"><span class="pre">tls-client</span></tt>.</p> +<p class="last">This option requires that <tt class="docutils literal"><span class="pre">--disable-occ</span></tt> NOT be used.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--port-share <var>args</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Share OpenVPN TCP with another service</p> +<p>Valid syntax:</p> +<pre class="literal-block"> +port-share host port [dir] +</pre> +<p>When run in TCP server mode, share the OpenVPN port with another +application, such as an HTTPS server. If OpenVPN senses a connection to +its port which is using a non-OpenVPN protocol, it will proxy the +connection to the server at <tt class="docutils literal">host</tt>:<tt class="docutils literal">port</tt>. Currently only designed to +work with HTTP/HTTPS, though it would be theoretically possible to +extend to other protocols such as ssh.</p> +<p><tt class="docutils literal">dir</tt> specifies an optional directory where a temporary file with name +N containing content C will be dynamically generated for each proxy +connection, where N is the source IP:port of the client connection and C +is the source IP:port of the connection to the proxy receiver. This +directory can be used as a dictionary by the proxy receiver to determine +the origin of the connection. Each generated file will be automatically +deleted when the proxied connection is torn down.</p> +<p class="last">Not implemented on Windows.</p> +</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--push <var>option</var></span></kbd></td> +<td><p class="first">Push a config file option back to the client for remote execution. Note +that <tt class="docutils literal">option</tt> must be enclosed in double quotes (<code>""</code>). The +client must specify <tt class="docutils literal"><span class="pre">--pull</span></tt> in its config file. The set of options +which can be pushed is limited by both feasibility and security. Some +options such as those which would execute scripts are banned, since they +would effectively allow a compromised server to execute arbitrary code +on the client. Other options such as TLS or MTU parameters cannot be +pushed because the client needs to know them before the connection to the +server can be initiated.</p> +<p class="last">This is a partial list of options which can currently be pushed: +<tt class="docutils literal"><span class="pre">--route</span></tt>, <tt class="docutils literal"><span class="pre">--route-gateway</span></tt>, <tt class="docutils literal"><span class="pre">--route-delay</span></tt>, +<tt class="docutils literal"><span class="pre">--redirect-gateway</span></tt>, <tt class="docutils literal"><span class="pre">--ip-win32</span></tt>, <tt class="docutils literal"><span class="pre">--dhcp-option</span></tt>, +<tt class="docutils literal"><span class="pre">--inactive</span></tt>, <tt class="docutils literal"><span class="pre">--ping</span></tt>, <tt class="docutils literal"><span class="pre">--ping-exit</span></tt>, <tt class="docutils literal"><span class="pre">--ping-restart</span></tt>, +<tt class="docutils literal"><span class="pre">--setenv</span></tt>, <tt class="docutils literal"><span class="pre">--auth-token</span></tt>, <tt class="docutils literal"><span class="pre">--persist-key</span></tt>, <tt class="docutils literal"><span class="pre">--persist-tun</span></tt>, +<tt class="docutils literal"><span class="pre">--echo</span></tt>, <tt class="docutils literal"><span class="pre">--comp-lzo</span></tt>, <tt class="docutils literal"><span class="pre">--socket-flags</span></tt>, <tt class="docutils literal"><span class="pre">--sndbuf</span></tt>, +<tt class="docutils literal"><span class="pre">--rcvbuf</span></tt></p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--push-peer-info</span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Push additional information about the client to server. The following +data is always pushed to the server:</p> +<dl class="docutils"> +<dt><code>IV_VER=<version></code></dt> +<dd>The client OpenVPN version</dd> +<dt><code>IV_PLAT=[linux|solaris|openbsd|mac|netbsd|freebsd|win]</code></dt> +<dd>The client OS platform</dd> +<dt><code>IV_LZO_STUB=1</code></dt> +<dd>If client was built with LZO stub capability</dd> +<dt><code>IV_LZ4=1</code></dt> +<dd>If the client supports LZ4 compressions.</dd> +<dt><code>IV_PROTO</code></dt> +<dd><p class="first">Details about protocol extensions that the peer supports. The +variable is a bitfield and the bits are defined as follows +(starting a bit 0 for the first (unused) bit:</p> +<ul class="last simple"> +<li>bit 1: The peer supports peer-id floating mechanism</li> +<li>bit 2: The client expects a push-reply and the server may +send this reply without waiting for a push-request first.</li> +</ul> +</dd> +<dt><code>IV_NCP=2</code></dt> +<dd>Negotiable ciphers, client supports <tt class="docutils literal"><span class="pre">--cipher</span></tt> pushed by +the server, a value of 2 or greater indicates client supports +<em>AES-GCM-128</em> and <em>AES-GCM-256</em>.</dd> +<dt><code>IV_CIPHERS=<ncp-ciphers></code></dt> +<dd>The client announces the list of supported ciphers configured with the +<tt class="docutils literal"><span class="pre">--data-ciphers</span></tt> option to the server.</dd> +<dt><code>IV_GUI_VER=<gui_id> <version></code></dt> +<dd>The UI version of a UI if one is running, for example +<code>de.blinkt.openvpn 0.5.47</code> for the Android app.</dd> +<dt><code>IV_SSO=[crtext,][openurl,][proxy_url]</code></dt> +<dd>Additional authentication methods supported by the client. +This may be set by the client UI/GUI using <tt class="docutils literal"><span class="pre">--setenv</span></tt></dd> +</dl> +<p>When <tt class="docutils literal"><span class="pre">--push-peer-info</span></tt> is enabled the additional information consists +of the following data:</p> +<dl class="last docutils"> +<dt><code>IV_HWADDR=<string></code></dt> +<dd>This is intended to be a unique and persistent ID of the client. +The string value can be any readable ASCII string up to 64 bytes. +OpenVPN 2.x and some other implementations use the MAC address of +the client's interface used to reach the default gateway. If this +string is generated by the client, it should be consistent and +preserved across independent session and preferably +re-installations and upgrades.</dd> +<dt><code>IV_SSL=<version string></code></dt> +<dd>The ssl version used by the client, e.g. +<code>OpenSSL 1.0.2f 28 Jan 2016</code>.</dd> +<dt><code>IV_PLAT_VER=x.y</code></dt> +<dd>The version of the operating system, e.g. 6.1 for Windows 7.</dd> +<dt><code>UV_<name>=<value></code></dt> +<dd>Client environment variables whose names start with +<code>UV_</code></dd> +</dl> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--push-remove <var>opt</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Selectively remove all <tt class="docutils literal"><span class="pre">--push</span></tt> options matching "opt" from the option +list for a client. <tt class="docutils literal">opt</tt> is matched as a substring against the whole +option string to-be-pushed to the client, so <tt class="docutils literal"><span class="pre">--push-remove</span> route</tt> +would remove all <tt class="docutils literal"><span class="pre">--push</span> route ...</tt> and <tt class="docutils literal"><span class="pre">--push</span> <span class="pre">route-ipv6</span> ...</tt> +statements, while <tt class="docutils literal"><span class="pre">--push-remove</span> <span class="pre">"route-ipv6</span> 2001:"</tt> would only remove +IPv6 routes for <code>2001:...</code> networks.</p> +<p><tt class="docutils literal"><span class="pre">--push-remove</span></tt> can only be used in a client-specific context, like in +a <tt class="docutils literal"><span class="pre">--client-config-dir</span></tt> file, or <tt class="docutils literal"><span class="pre">--client-connect</span></tt> script or plugin +-- similar to <tt class="docutils literal"><span class="pre">--push-reset</span></tt>, just more selective.</p> +<p><em>NOTE</em>: to <em>change</em> an option, <tt class="docutils literal"><span class="pre">--push-remove</span></tt> can be used to first +remove the old value, and then add a new <tt class="docutils literal"><span class="pre">--push</span></tt> option with the new +value.</p> +<p class="last"><em>NOTE 2</em>: due to implementation details, 'ifconfig' and 'ifconfig-ipv6' +can only be removed with an exact match on the option ( +<code>push-remove ifconfig</code>), no substring matching and no matching on +the IPv4/IPv6 address argument is possible.</p> +</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--push-reset</span></kbd></td> +<td><p class="first">Don't inherit the global push list for a specific client instance. +Specify this option in a client-specific context such as with a +<tt class="docutils literal"><span class="pre">--client-config-dir</span></tt> configuration file. This option will ignore +<tt class="docutils literal"><span class="pre">--push</span></tt> options at the global config file level.</p> +<p class="last"><em>NOTE</em>: <tt class="docutils literal"><span class="pre">--push-reset</span></tt> is very thorough: it will remove almost +all options from the list of to-be-pushed options. In many cases, +some of these options will need to be re-configured afterwards - +specifically, <tt class="docutils literal"><span class="pre">--topology</span> subnet</tt> and <tt class="docutils literal"><span class="pre">--route-gateway</span></tt> will get +lost and this will break client configs in many cases. Thus, for most +purposes, <tt class="docutils literal"><span class="pre">--push-remove</span></tt> is better suited to selectively remove +push options for individual clients.</p> +</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--server <var>args</var></span></kbd></td> +<td><p class="first">A helper directive designed to simplify the configuration of OpenVPN's +server mode. This directive will set up an OpenVPN server which will +allocate addresses to clients out of the given network/netmask. The +server itself will take the <code>.1</code> address of the given network for +use as the server-side endpoint of the local TUN/TAP interface. If the +optional <code>nopool</code> flag is given, no dynamic IP address pool will +prepared for VPN clients.</p> +<p>Valid syntax:</p> +<pre class="literal-block"> +server network netmask [nopool] +</pre> +<p>For example, <tt class="docutils literal"><span class="pre">--server</span> 10.8.0.0 255.255.255.0</tt> expands as follows:</p> +<pre class="literal-block"> +mode server +tls-server +push "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 +</pre> +<p class="last">Don't use <tt class="docutils literal"><span class="pre">--server</span></tt> if you are ethernet bridging. Use +<tt class="docutils literal"><span class="pre">--server-bridge</span></tt> instead.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--server-bridge <var>args</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">A helper directive similar to <tt class="docutils literal"><span class="pre">--server</span></tt> which is designed to simplify +the configuration of OpenVPN's server mode in ethernet bridging +configurations.</p> +<p>Valid syntaxes:</p> +<pre class="literal-block"> +server-bridge gateway netmask pool-start-IP pool-end-IP +server-bridge [nogw] +</pre> +<p>If <tt class="docutils literal"><span class="pre">--server-bridge</span></tt> is used without any parameters, it will enable a +DHCP-proxy mode, where connecting OpenVPN clients will receive an IP +address for their TAP adapter from the DHCP server running on the +OpenVPN server-side LAN. Note that only clients that support the binding +of a DHCP client with the TAP adapter (such as Windows) can support this +mode. The optional <code>nogw</code> flag (advanced) indicates that gateway +information should not be pushed to the client.</p> +<p>To configure ethernet bridging, you must first use your OS's bridging +capability to bridge the TAP interface with the ethernet NIC interface. +For example, on Linux this is done with the <code>brctl</code> tool, and with +Windows XP it is done in the Network Connections Panel by selecting the +ethernet and TAP adapters and right-clicking on "Bridge Connections".</p> +<p>Next you you must manually set the IP/netmask on the bridge interface. +The <tt class="docutils literal">gateway</tt> and <tt class="docutils literal">netmask</tt> parameters to <tt class="docutils literal"><span class="pre">--server-bridge</span></tt> can be +set to either the IP/netmask of the bridge interface, or the IP/netmask +of the default gateway/router on the bridged subnet.</p> +<p>Finally, set aside a IP range in the bridged subnet, denoted by +<tt class="docutils literal"><span class="pre">pool-start-IP</span></tt> and <tt class="docutils literal"><span class="pre">pool-end-IP</span></tt>, for OpenVPN to allocate to +connecting clients.</p> +<p>For example, <tt class="docutils literal"><span class="pre">server-bridge</span> 10.8.0.4 255.255.255.0 10.8.0.128 +10.8.0.254</tt> expands as follows:</p> +<pre class="literal-block"> +mode server +tls-server + +ifconfig-pool 10.8.0.128 10.8.0.254 255.255.255.0 +push "route-gateway 10.8.0.4" +</pre> +<p>In another example, <tt class="docutils literal"><span class="pre">--server-bridge</span></tt> (without parameters) expands as +follows:</p> +<pre class="literal-block"> +mode server +tls-server + +push "route-gateway dhcp" +</pre> +<p>Or <tt class="docutils literal"><span class="pre">--server-bridge</span> nogw</tt> expands as follows:</p> +<pre class="last literal-block"> +mode server +tls-server +</pre> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--server-ipv6 <var>args</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Convenience-function to enable a number of IPv6 related options at once, +namely <tt class="docutils literal"><span class="pre">--ifconfig-ipv6</span></tt>, <tt class="docutils literal"><span class="pre">--ifconfig-ipv6-pool</span></tt> and +<tt class="docutils literal"><span class="pre">--push</span> <span class="pre">tun-ipv6</span></tt>.</p> +<p>Valid syntax:</p> +<pre class="literal-block"> +server-ipv6 ipv6addr/bits +</pre> +<p class="last">Pushing of the <tt class="docutils literal"><span class="pre">--tun-ipv6</span></tt> directive is done for older clients which +require an explicit <tt class="docutils literal"><span class="pre">--tun-ipv6</span></tt> in their configuration.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--stale-routes-check <var>args</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Remove routes which haven't had activity for <tt class="docutils literal">n</tt> seconds (i.e. the ageing +time). This check is run every <tt class="docutils literal">t</tt> seconds (i.e. check interval).</p> +<p>Valid syntax:</p> +<pre class="literal-block"> +stale-routes-check n [t] +</pre> +<p>If <tt class="docutils literal">t</tt> is not present it defaults to <tt class="docutils literal">n</tt>.</p> +<p class="last">This option helps to keep the dynamic routing table small. See also +<tt class="docutils literal"><span class="pre">--max-routes-per-client</span></tt></p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--username-as-common-name</span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Use the authenticated username as the common-name, rather than the +common-name from the client certificate. Requires that some form of +<tt class="docutils literal"><span class="pre">--auth-user-pass</span></tt> verification is in effect. As the replacement happens +after <tt class="docutils literal"><span class="pre">--auth-user-pass</span></tt> verification, the verification script or +plugin will still receive the common-name from the certificate.</p> +<p class="last">The common_name environment variable passed to scripts and plugins invoked +after authentication (e.g, client-connect script) and file names parsed in +client-config directory will match the username.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--verify-client-cert <var>mode</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Specify whether the client is required to supply a valid certificate.</p> +<p>Possible <tt class="docutils literal">mode</tt> options are:</p> +<dl class="docutils"> +<dt><code>none</code></dt> +<dd><p class="first">A client certificate is not required. the client needs to +authenticate using username/password only. Be aware that using this +directive is less secure than requiring certificates from all +clients.</p> +<p>If you use this directive, the entire responsibility of authentication +will rest on your <tt class="docutils literal"><span class="pre">--auth-user-pass-verify</span></tt> script, so keep in mind +that bugs in your script could potentially compromise the security of +your VPN.</p> +<p class="last"><tt class="docutils literal"><span class="pre">--verify-client-cert</span> none</tt> is functionally equivalent to +<tt class="docutils literal"><span class="pre">--client-cert-not-required</span></tt>.</p> +</dd> +<dt><code>optional</code></dt> +<dd><p class="first">A client may present a certificate but it is not required to do so. +When using this directive, you should also use a +<tt class="docutils literal"><span class="pre">--auth-user-pass-verify</span></tt> script to ensure that clients are +authenticated using a certificate, a username and password, or +possibly even both.</p> +<p class="last">Again, the entire responsibility of authentication will rest on your +<tt class="docutils literal"><span class="pre">--auth-user-pass-verify</span></tt> script, so keep in mind that bugs in your +script could potentially compromise the security of your VPN.</p> +</dd> +<dt><code>require</code></dt> +<dd>This is the default option. A client is required to present a +certificate, otherwise VPN access is refused.</dd> +</dl> +<p class="last">If you don't use this directive (or use <tt class="docutils literal"><span class="pre">--verify-client-cert</span> require</tt>) +but you also specify an <tt class="docutils literal"><span class="pre">--auth-user-pass-verify</span></tt> script, then OpenVPN +will perform double authentication. The client certificate verification +AND the <tt class="docutils literal"><span class="pre">--auth-user-pass-verify</span></tt> script will need to succeed in order +for a client to be authenticated and accepted onto the VPN.</p> +</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--vlan-tagging</span></kbd></td> +<td><p class="first">Server-only option. Turns the OpenVPN server instance into a switch that +understands VLAN-tagging, based on IEEE 802.1Q.</p> +<p>The server TAP device and each of the connecting clients is seen as a +port of the switch. All client ports are in untagged mode and the server +TAP device is VLAN-tagged, untagged or accepts both, depending on the +<tt class="docutils literal"><span class="pre">--vlan-accept</span></tt> setting.</p> +<p>Ethernet frames with a prepended 802.1Q tag are called "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".</p> +<p>Using the <tt class="docutils literal"><span class="pre">--vlan-pvid</span> v</tt> option once per client (see +--client-config-dir), each port can be associated with a certain VID. +Packets can only be forwarded between ports having the same VID. +Therefore, clients with differing VIDs are completely separated from +one-another, even if <tt class="docutils literal"><span class="pre">--client-to-client</span></tt> is activated.</p> +<p>The packet filtering takes place in the OpenVPN server. Clients should +not have any VLAN tagging configuration applied.</p> +<p>The <tt class="docutils literal"><span class="pre">--vlan-tagging</span></tt> option is off by default. While turned off, +OpenVPN accepts any Ethernet frame and does not perform any special +processing for VLAN-tagged packets.</p> +<p class="last">This option can only be activated in <tt class="docutils literal"><span class="pre">--dev</span> tap mode</tt>.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--vlan-accept <var>args</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Configure the VLAN tagging policy for the server TAP device.</p> +<p>Valid syntax:</p> +<pre class="literal-block"> +vlan-accept all|tagged|untagged +</pre> +<p>The following modes are available:</p> +<dl class="docutils"> +<dt><code>tagged</code></dt> +<dd>Admit only VLAN-tagged frames. Only VLAN-tagged packets are accepted, +while untagged or priority-tagged packets are dropped when entering +the server TAP device.</dd> +<dt><code>untagged</code></dt> +<dd>Admit only untagged and prio-tagged frames. VLAN-tagged packets are +not accepted, while untagged or priority-tagged packets entering the +server TAP device are tagged with the value configured for the global +<tt class="docutils literal"><span class="pre">--vlan-pvid</span></tt> setting.</dd> +<dt><code>all</code> (default)</dt> +<dd>Admit all frames. All packets are admitted and then treated like +untagged or tagged mode respectively.</dd> +<dt><em>Note</em>:</dt> +<dd>Some vendors refer to switch ports running in <code>tagged</code> mode +as "trunk ports" and switch ports running in <code>untagged</code> mode +as "access ports".</dd> +</dl> +<p>Packets forwarded from clients to the server are VLAN-tagged with the +originating client's PVID, unless the VID matches the global +<tt class="docutils literal"><span class="pre">--vlan-pvid</span></tt>, in which case the tag is removed.</p> +<p class="last">If no <em>PVID</em> is configured for a given client (see --vlan-pvid) packets +are tagged with 1 by default.</p> +</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--vlan-pvid <var>v</var></span></kbd></td> +<td><p class="first">Specifies which VLAN identifier a "port" is associated with. Only valid +when <tt class="docutils literal"><span class="pre">--vlan-tagging</span></tt> is speficied.</p> +<p>In the client context, the setting specifies which VLAN ID a client is +associated with. In the global context, the VLAN ID of the server TAP +device is set. The latter only makes sense for <tt class="docutils literal"><span class="pre">--vlan-accept</span> +untagged</tt> and <tt class="docutils literal"><span class="pre">--vlan-accept</span> all</tt> modes.</p> +<p>Valid values for <tt class="docutils literal">v</tt> go from <code>1</code> through to <code>4094</code>. The +global value defaults to <code>1</code>. If no <tt class="docutils literal"><span class="pre">--vlan-pvid</span></tt> is specified in +the client context, the global value is inherited.</p> +<p class="last">In some switch implementations, the <em>PVID</em> is also referred to as "Native +VLAN".</p> +</td></tr> +</tbody> +</table> +</div> +</div> +<div class="section" id="encryption-options"> +<h1>Encryption Options</h1> +<div class="section" id="ssl-library-information"> +<h2>SSL Library information</h2> +<table class="docutils option-list" frame="void" rules="none"> +<col class="option" /> +<col class="description" /> +<tbody valign="top"> +<tr><td class="option-group"> +<kbd><span class="option">--show-ciphers</span></kbd></td> +<td>(Standalone) Show all cipher algorithms to use with the <tt class="docutils literal"><span class="pre">--cipher</span></tt> +option.</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--show-digests</span></kbd></td> +<td>(Standalone) Show all message digest algorithms to use with the +<tt class="docutils literal"><span class="pre">--auth</span></tt> option.</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--show-tls</span></kbd></td> +<td><p class="first">(Standalone) Show all TLS ciphers supported by the crypto library. +OpenVPN uses TLS to secure the control channel, over which the keys that +are used to protect the actual VPN traffic are exchanged. The TLS +ciphers will be sorted from highest preference (most secure) to lowest.</p> +<p class="last">Be aware that whether a cipher suite in this list can actually work +depends on the specific setup of both peers (e.g. both peers must +support the cipher, and an ECDSA cipher suite will not work if you are +using an RSA certificate, etc.).</p> +</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--show-engines</span></kbd></td> +<td>(Standalone) Show currently available hardware-based crypto acceleration +engines supported by the OpenSSL library.</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--show-groups</span></kbd></td> +<td>(Standalone) Show all available elliptic curves/groups to use with the +<tt class="docutils literal"><span class="pre">--ecdh-curve</span></tt> and <tt class="docutils literal"><span class="pre">tls-groups</span></tt> options.</td></tr> +</tbody> +</table> +</div> +<div class="section" id="generating-key-material"> +<h2>Generating key material</h2> +<table class="docutils option-list" frame="void" rules="none"> +<col class="option" /> +<col class="description" /> +<tbody valign="top"> +<tr><td class="option-group"> +<kbd><span class="option">--genkey <var>args</var></span></kbd></td> +<td><p class="first">(Standalone) Generate a key to be used of the type keytype. if keyfile +is left out or empty the key will be output on stdout. See the following +sections for the different keytypes.</p> +<p>Valid syntax:</p> +<pre class="literal-block"> +--genkey keytype keyfile +</pre> +<p>Valid keytype arguments are:</p> +<p><code>secret</code> Standard OpenVPN shared secret keys</p> +<p><code>tls-crypt</code> Alias for <code>secret</code></p> +<p><code>tls-auth</code> Alias for <code>secret</code></p> +<p><code>auth-token</code> Key used for <tt class="docutils literal"><span class="pre">--auth-gen-token-key</span></tt></p> +<p><code>tls-crypt-v2-server</code> TLS Crypt v2 server key</p> +<p><code>tls-crypt-v2-client</code> TLS Crypt v2 client key</p> +<p>Examples:</p> +<pre class="literal-block"> +$ openvpn --genkey secret shared.key +$ openvpn --genkey tls-crypt shared.key +$ openvpn --genkey tls-auth shared.key +$ openvpn --genkey tls-crypt-v2-server v2crypt-server.key +$ openvpn --tls-crypt-v2 v2crypt-server.key --genkey tls-crypt-v2-client v2crypt-client-1.key +</pre> +<ul class="last"> +<li><p class="first">Generating <em>Shared Secret Keys</em> +Generate a shared secret, for use with the <tt class="docutils literal"><span class="pre">--secret</span></tt>, <tt class="docutils literal"><span class="pre">--tls-auth</span></tt> +or <tt class="docutils literal"><span class="pre">--tls-crypt</span></tt> options.</p> +<p>Syntax:</p> +<pre class="literal-block"> +$ openvpn --genkey secret|tls-crypt|tls-auth keyfile +</pre> +<p>The key is saved in <tt class="docutils literal">keyfile</tt>. All three variants (<tt class="docutils literal"><span class="pre">--secret</span></tt>, +<tt class="docutils literal"><span class="pre">tls-crypt</span></tt> and <tt class="docutils literal"><span class="pre">tls-auth</span></tt>) generate the same type of key. The +aliases are added for convenience.</p> +<p>If using this for <tt class="docutils literal"><span class="pre">--secret</span></tt>, this file must be shared with the peer +over a pre-existing secure channel such as <tt class="docutils literal">scp</tt>(1).</p> +</li> +<li><p class="first">Generating <em>TLS Crypt v2 Server key</em> +Generate a <tt class="docutils literal"><span class="pre">--tls-crypt-v2</span></tt> key to be used by an OpenVPN server. +The key is stored in <tt class="docutils literal">keyfile</tt>.</p> +<p>Syntax:</p> +<pre class="literal-block"> +--genkey tls-crypt-v2-server keyfile +</pre> +</li> +<li><p class="first">Generating <em>TLS Crypt v2 Client key</em> +Generate a --tls-crypt-v2 key to be used by OpenVPN clients. The +key is stored in <tt class="docutils literal">keyfile</tt>.</p> +<p>Syntax</p> +<pre class="literal-block"> +--genkey tls-crypt-v2-client keyfile [metadata] +</pre> +<p>If supplied, include the supplied <tt class="docutils literal">metadata</tt> in the wrapped client +key. This metadata must be supplied in base64-encoded form. The +metadata must be at most 735 bytes long (980 bytes in base64).</p> +<p>If no metadata is supplied, OpenVPN will use a 64-bit unix timestamp +representing the current time in UTC, encoded in network order, as +metadata for the generated key.</p> +<p>A tls-crypt-v2 client key is wrapped using a server key. To generate a +client key, the user must therefore supply the server key using the +<tt class="docutils literal"><span class="pre">--tls-crypt-v2</span></tt> option.</p> +<p>Servers can use <tt class="docutils literal"><span class="pre">--tls-crypt-v2-verify</span></tt> to specify a metadata +verification command.</p> +</li> +<li><p class="first">Generate <em>Authentication Token key</em> +Generate a new secret that can be used with <strong>--auth-gen-token-secret</strong></p> +<p>Syntax:</p> +<pre class="literal-block"> +--genkey auth-token [keyfile] +</pre> +<dl class="docutils"> +<dt><em>Note:</em></dt> +<dd><p class="first last">This file should be kept secret to the server as anyone that has +access to this file will be able to generate auth tokens that the +OpenVPN server will accept as valid.</p> +</dd> +</dl> +</li> +</ul> +</td></tr> +</tbody> +</table> +</div> +<div class="section" id="data-channel-renegotiation"> +<h2>Data Channel Renegotiation</h2> +<p>When running OpenVPN in client/server mode, the data channel will use a +separate ephemeral encryption key which is rotated at regular intervals.</p> +<table class="docutils option-list" frame="void" rules="none"> +<col class="option" /> +<col class="description" /> +<tbody valign="top"> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--reneg-bytes <var>n</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Renegotiate data channel key after <tt class="docutils literal">n</tt> bytes sent or received +(disabled by default with an exception, see below). OpenVPN allows the +lifetime of a key to be expressed as a number of bytes +encrypted/decrypted, a number of packets, or a number of seconds. A key +renegotiation will be forced if any of these three criteria are met by +either peer.</p> +<p class="last">If using ciphers with cipher block sizes less than 128-bits, +<tt class="docutils literal"><span class="pre">--reneg-bytes</span></tt> is set to 64MB by default, unless it is explicitly +disabled by setting the value to <code>0</code>, but this is +<strong>HIGHLY DISCOURAGED</strong> as this is designed to add some protection against +the SWEET32 attack vector. For more information see the <tt class="docutils literal"><span class="pre">--cipher</span></tt> +option.</p> +</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--reneg-pkts <var>n</var></span></kbd></td> +<td>Renegotiate data channel key after <strong>n</strong> packets sent and received +(disabled by default).</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--reneg-sec <var>args</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Renegotiate data channel key after at most <tt class="docutils literal">max</tt> seconds +(default <code>3600</code>) and at least <tt class="docutils literal">min</tt> seconds (default is 90% of +<tt class="docutils literal">max</tt> for servers, and equal to <tt class="docutils literal">max</tt> for clients).</p> +<pre class="literal-block"> +reneg-sec max [min] +</pre> +<p>The effective <tt class="docutils literal"><span class="pre">--reneg-sec</span></tt> value used is per session +pseudo-uniform-randomized between <tt class="docutils literal">min</tt> and <tt class="docutils literal">max</tt>.</p> +<p>With the default value of <code>3600</code> this results in an effective per +session value in the range of <code>3240</code> .. <code>3600</code> seconds for +servers, or just 3600 for clients.</p> +<p>When using dual-factor authentication, note that this default value may +cause the end user to be challenged to reauthorize once per hour.</p> +<p class="last">Also, keep in mind that this option can be used on both the client and +server, and whichever uses the lower value will be the one to trigger +the renegotiation. A common mistake is to set <tt class="docutils literal"><span class="pre">--reneg-sec</span></tt> to a +higher value on either the client or server, while the other side of the +connection is still using the default value of <code>3600</code> seconds, +meaning that the renegotiation will still occur once per <code>3600</code> +seconds. The solution is to increase --reneg-sec on both the client and +server, or set it to <code>0</code> on one side of the connection (to +disable), and to your chosen value on the other side.</p> +</td></tr> +</tbody> +</table> +</div> +<div class="section" id="tls-mode-options"> +<h2>TLS Mode Options</h2> +<p>TLS mode is the most powerful crypto mode of OpenVPN in both security +and flexibility. TLS mode works by establishing control and data +channels which are multiplexed over a single TCP/UDP port. OpenVPN +initiates a TLS session over the control channel and uses it to exchange +cipher and HMAC keys to protect the data channel. TLS mode uses a robust +reliability layer over the UDP connection for all control channel +communication, while the data channel, over which encrypted tunnel data +passes, is forwarded without any mediation. The result is the best of +both worlds: a fast data channel that forwards over UDP with only the +overhead of encrypt, decrypt, and HMAC functions, and a control channel +that provides all of the security features of TLS, including +certificate-based authentication and Diffie Hellman forward secrecy.</p> +<p>To use TLS mode, each peer that runs OpenVPN should have its own local +certificate/key pair (<tt class="docutils literal"><span class="pre">--cert</span></tt> and <tt class="docutils literal"><span class="pre">--key</span></tt>), signed by the root +certificate which is specified in <tt class="docutils literal"><span class="pre">--ca</span></tt>.</p> +<p>When two OpenVPN peers connect, each presents its local certificate to +the other. Each peer will then check that its partner peer presented a +certificate which was signed by the master root certificate as specified +in <tt class="docutils literal"><span class="pre">--ca</span></tt>.</p> +<p>If that check on both peers succeeds, then the TLS negotiation will +succeed, both OpenVPN peers will exchange temporary session keys, and +the tunnel will begin passing data.</p> +<p>The OpenVPN project provides a set of scripts for managing RSA +certificates and keys: <a class="reference external" href="https://github.com/OpenVPN/easy-rsa">https://github.com/OpenVPN/easy-rsa</a></p> +<table class="docutils option-list" frame="void" rules="none"> +<col class="option" /> +<col class="description" /> +<tbody valign="top"> +<tr><td class="option-group"> +<kbd><span class="option">--askpass <var>file</var></span></kbd></td> +<td><p class="first">Get certificate password from console or <tt class="docutils literal">file</tt> before we daemonize.</p> +<p>Valid syntaxes:</p> +<pre class="literal-block"> +askpass +askpass file +</pre> +<p>For the extremely security conscious, it is possible to protect your +private key with a password. Of course this means that every time the +OpenVPN daemon is started you must be there to type the password. The +<tt class="docutils literal"><span class="pre">--askpass</span></tt> option allows you to start OpenVPN from the command line. +It will query you for a password before it daemonizes. To protect a +private key with a password you should omit the <tt class="docutils literal"><span class="pre">-nodes</span></tt> option when +you use the <tt class="docutils literal">openssl</tt> command line tool to manage certificates and +private keys.</p> +<p class="last">If <tt class="docutils literal">file</tt> is specified, read the password from the first line of +<tt class="docutils literal">file</tt>. Keep in mind that storing your password in a file to a certain +extent invalidates the extra security provided by using an encrypted +key.</p> +</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--ca <var>file</var></span></kbd></td> +<td><p class="first">Certificate authority (CA) file in .pem format, also referred to as the +<em>root</em> certificate. This file can have multiple certificates in .pem +format, concatenated together. You can construct your own certificate +authority certificate and private key by using a command such as:</p> +<pre class="literal-block"> +openssl req -nodes -new -x509 -keyout ca.key -out ca.crt +</pre> +<p>Then edit your openssl.cnf file and edit the <tt class="docutils literal">certificate</tt> variable to +point to your new root certificate <tt class="docutils literal">ca.crt</tt>.</p> +<p class="last">For testing purposes only, the OpenVPN distribution includes a sample CA +certificate (ca.crt). Of course you should never use the test +certificates and test keys distributed with OpenVPN in a production +environment, since by virtue of the fact that they are distributed with +OpenVPN, they are totally insecure.</p> +</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--capath <var>dir</var></span></kbd></td> +<td><p class="first">Directory containing trusted certificates (CAs and CRLs). Not available +with mbed TLS.</p> +<p>CAs in the capath directory are expected to be named <hash>.<n>. CRLs +are expected to be named <hash>.r<n>. See the <tt class="docutils literal"><span class="pre">-CApath</span></tt> option of +<tt class="docutils literal">openssl verify</tt>, and the <tt class="docutils literal"><span class="pre">-hash</span></tt> option of <tt class="docutils literal">openssl x509</tt>, +<tt class="docutils literal">openssl crl</tt> and <tt class="docutils literal">X509_LOOKUP_hash_dir()</tt>(3) +for more information.</p> +<p class="last">Similar to the <tt class="docutils literal"><span class="pre">--crl-verify</span></tt> option, CRLs are not mandatory - +OpenVPN will log the usual warning in the logs if the relevant CRL is +missing, but the connection will be allowed.</p> +</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--cert <var>file</var></span></kbd></td> +<td><p class="first">Local peer's signed certificate in .pem format -- must be signed by a +certificate authority whose certificate is in <tt class="docutils literal"><span class="pre">--ca</span> file</tt>. Each peer +in an OpenVPN link running in TLS mode should have its own certificate +and private key file. In addition, each certificate should have been +signed by the key of a certificate authority whose public key resides in +the <tt class="docutils literal"><span class="pre">--ca</span></tt> certificate authority file. You can easily make your own +certificate authority (see above) or pay money to use a commercial +service such as thawte.com (in which case you will be helping to finance +the world's second space tourist :). To generate a certificate, you can +use a command such as:</p> +<pre class="literal-block"> +openssl req -nodes -new -keyout mycert.key -out mycert.csr +</pre> +<p>If your certificate authority private key lives on another machine, copy +the certificate signing request (mycert.csr) to this other machine (this +can be done over an insecure channel such as email). Now sign the +certificate with a command such as:</p> +<pre class="literal-block"> +openssl ca -out mycert.crt -in mycert.csr +</pre> +<p class="last">Now copy the certificate (mycert.crt) back to the peer which initially +generated the .csr file (this can be over a public medium). Note that +the <tt class="docutils literal">openssl ca</tt> command reads the location of the certificate +authority key from its configuration file such as +<code>/usr/share/ssl/openssl.cnf</code> -- note also that for certificate +authority functions, you must set up the files <code>index.txt</code> (may be +empty) and <code>serial</code> (initialize to <code>01</code>).</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--crl-verify <var>args</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Check peer certificate against a Certificate Revocation List.</p> +<p>Valid syntax:</p> +<pre class="literal-block"> +crl-verify file/directory flag +</pre> +<p>Examples:</p> +<pre class="literal-block"> +crl-verify crl-file.pem +crl-verify /etc/openvpn/crls dir +</pre> +<p>A CRL (certificate revocation list) is used when a particular key is +compromised but when the overall PKI is still intact.</p> +<p>Suppose you had a PKI consisting of a CA, root certificate, and a number +of client certificates. Suppose a laptop computer containing a client +key and certificate was stolen. By adding the stolen certificate to the +CRL file, you could reject any connection which attempts to use it, +while preserving the overall integrity of the PKI.</p> +<p>The only time when it would be necessary to rebuild the entire PKI from +scratch would be if the root certificate key itself was compromised.</p> +<p>The option is not mandatory - if the relevant CRL is missing, OpenVPN +will log a warning in the logs - e.g.</p> +<pre class="literal-block"> +VERIFY WARNING: depth=0, unable to get certificate CRL +</pre> +<p>but the connection will be allowed. If the optional <code>dir</code> flag +is specified, enable a different mode where the <tt class="docutils literal"><span class="pre">crl-verify</span></tt> is +pointed at a directory containing files named as revoked serial numbers +(the files may be empty, the contents are never read). If a client +requests a connection, where the client certificate serial number +(decimal string) is the name of a file present in the directory, it will +be rejected.</p> +<dl class="last docutils"> +<dt><em>Note:</em></dt> +<dd>As the crl file (or directory) is read every time a peer +connects, if you are dropping root privileges with +<tt class="docutils literal"><span class="pre">--user</span></tt>, make sure that this user has sufficient +privileges to read the file.</dd> +</dl> +</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--dh <var>file</var></span></kbd></td> +<td><p class="first">File containing Diffie Hellman parameters in .pem format (required for +<tt class="docutils literal"><span class="pre">--tls-server</span></tt> only).</p> +<p>Set <tt class="docutils literal">file</tt> to <code>none</code> to disable Diffie Hellman key exchange (and +use ECDH only). Note that this requires peers to be using an SSL library +that supports ECDH TLS cipher suites (e.g. OpenSSL 1.0.1+, or +mbed TLS 2.0+).</p> +<p class="last">Use <tt class="docutils literal">openssl dhparam <span class="pre">-out</span> dh2048.pem 2048</tt> to generate 2048-bit DH +parameters. Diffie Hellman parameters may be considered public.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--ecdh-curve <var>name</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Specify the curve to use for elliptic curve Diffie Hellman. Available +curves can be listed with <tt class="docutils literal"><span class="pre">--show-curves</span></tt>. The specified curve will +only be used for ECDH TLS-ciphers.</p> +<p class="last">This option is not supported in mbed TLS builds of OpenVPN.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--extra-certs <var>file</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Specify a <tt class="docutils literal">file</tt> containing one or more PEM certs (concatenated +together) that complete the local certificate chain.</p> +<p class="last">This option is useful for "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 <tt class="docutils literal">ca</tt> file.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--hand-window <var>n</var></span></kbd></td> +</tr> +<tr><td> </td><td>Handshake Window -- the TLS-based key exchange must finalize within +<tt class="docutils literal">n</tt> seconds of handshake initiation by any peer (default <code>60</code> +seconds). If the handshake fails we will attempt to reset our connection +with our peer and try again. Even in the event of handshake failure we +will still use our expiring key for up to <tt class="docutils literal"><span class="pre">--tran-window</span></tt> seconds to +maintain continuity of transmission of tunnel data.</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--key <var>file</var></span></kbd></td> +<td>Local peer's private key in .pem format. Use the private key which was +generated when you built your peer's certificate (see <tt class="docutils literal"><span class="pre">--cert</span> file</tt> +above).</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--pkcs12 <var>file</var></span></kbd></td> +<td>Specify a PKCS #12 file containing local private key, local certificate, +and root CA certificate. This option can be used instead of <tt class="docutils literal"><span class="pre">--ca</span></tt>, +<tt class="docutils literal"><span class="pre">--cert</span></tt>, and <tt class="docutils literal"><span class="pre">--key</span></tt>. Not available with mbed TLS.</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--remote-cert-eku <var>oid</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Require that peer certificate was signed with an explicit <em>extended key +usage</em>.</p> +<p>This is a useful security option for clients, to ensure that the host +they connect to is a designated server.</p> +<p class="last">The extended key usage should be encoded in <em>oid notation</em>, or <em>OpenSSL +symbolic representation</em>.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--remote-cert-ku <var>key-usage</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Require that peer certificate was signed with an explicit +<tt class="docutils literal"><span class="pre">key-usage</span></tt>.</p> +<p>If present in the certificate, the <code>keyUsage</code> value is validated by +the TLS library during the TLS handshake. Specifying this option without +arguments requires this extension to be present (so the TLS library will +verify it).</p> +<p>If <tt class="docutils literal"><span class="pre">key-usage</span></tt> is a list of usage bits, the <code>keyUsage</code> field +must have <em>at least</em> the same bits set as the bits in <em>one of</em> the values +supplied in the <tt class="docutils literal"><span class="pre">key-usage</span></tt> list.</p> +<p>The <tt class="docutils literal"><span class="pre">key-usage</span></tt> values in the list must be encoded in hex, e.g.</p> +<pre class="last literal-block"> +remote-cert-ku a0 +</pre> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--remote-cert-tls <var>type</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Require that peer certificate was signed with an explicit <em>key usage</em> +and <em>extended key usage</em> based on RFC3280 TLS rules.</p> +<p>Valid syntaxes:</p> +<pre class="literal-block"> +remote-cert-tls server +remote-cert-tls client +</pre> +<p>This is a useful security option for clients, to ensure that the host +they connect to is a designated server. Or the other way around; for a +server to verify that only hosts with a client certificate can connect.</p> +<p>The <tt class="docutils literal"><span class="pre">--remote-cert-tls</span> client</tt> option is equivalent to</p> +<pre class="literal-block"> +remote-cert-ku +remote-cert-eku "TLS Web Client Authentication" +</pre> +<p>The <tt class="docutils literal"><span class="pre">--remote-cert-tls</span> server</tt> option is equivalent to</p> +<pre class="literal-block"> +remote-cert-ku +remote-cert-eku "TLS Web Server Authentication" +</pre> +<p class="last">This is an important security precaution to protect against a +man-in-the-middle attack where an authorized client attempts to connect +to another client by impersonating the server. The attack is easily +prevented by having clients verify the server certificate using any one +of <tt class="docutils literal"><span class="pre">--remote-cert-tls</span></tt>, <tt class="docutils literal"><span class="pre">--verify-x509-name</span></tt>, or <tt class="docutils literal"><span class="pre">--tls-verify</span></tt>.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--tls-auth <var>args</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Add an additional layer of HMAC authentication on top of the TLS control +channel to mitigate DoS attacks and attacks on the TLS stack.</p> +<p>Valid syntaxes:</p> +<pre class="literal-block"> +tls-auth file +tls-auth file 0 +tls-auth file 1 +</pre> +<p>In a nutshell, <tt class="docutils literal"><span class="pre">--tls-auth</span></tt> enables a kind of "HMAC firewall" on +OpenVPN's TCP/UDP port, where TLS control channel packets bearing an +incorrect HMAC signature can be dropped immediately without response.</p> +<p><tt class="docutils literal">file</tt> (required) is a file in OpenVPN static key format which can be +generated by <tt class="docutils literal"><span class="pre">--genkey</span></tt>.</p> +<p>Older versions (up to OpenVPN 2.3) supported a freeform passphrase file. +This is no longer supported in newer versions (v2.4+).</p> +<p>See the <tt class="docutils literal"><span class="pre">--secret</span></tt> option for more information on the optional +<tt class="docutils literal">direction</tt> parameter.</p> +<p><tt class="docutils literal"><span class="pre">--tls-auth</span></tt> is recommended when you are running OpenVPN in a mode +where it is listening for packets from any IP address, such as when +<tt class="docutils literal"><span class="pre">--remote</span></tt> is not specified, or <tt class="docutils literal"><span class="pre">--remote</span></tt> is specified with +<tt class="docutils literal"><span class="pre">--float</span></tt>.</p> +<p>The rationale for this feature is as follows. TLS requires a +multi-packet exchange before it is able to authenticate a peer. During +this time before authentication, OpenVPN is allocating resources (memory +and CPU) to this potential peer. The potential peer is also exposing +many parts of OpenVPN and the OpenSSL library to the packets it is +sending. Most successful network attacks today seek to either exploit +bugs in programs (such as buffer overflow attacks) or force a program to +consume so many resources that it becomes unusable. Of course the first +line of defense is always to produce clean, well-audited code. OpenVPN +has been written with buffer overflow attack prevention as a top +priority. But as history has shown, many of the most widely used network +applications have, from time to time, fallen to buffer overflow attacks.</p> +<p>So as a second line of defense, OpenVPN offers this special layer of +authentication on top of the TLS control channel so that every packet on +the control channel is authenticated by an HMAC signature and a unique +ID for replay protection. This signature will also help protect against +DoS (Denial of Service) attacks. An important rule of thumb in reducing +vulnerability to DoS attacks is to minimize the amount of resources a +potential, but as yet unauthenticated, client is able to consume.</p> +<p><tt class="docutils literal"><span class="pre">--tls-auth</span></tt> does this by signing every TLS control channel packet +with an HMAC signature, including packets which are sent before the TLS +level has had a chance to authenticate the peer. The result is that +packets without the correct signature can be dropped immediately upon +reception, before they have a chance to consume additional system +resources such as by initiating a TLS handshake. <tt class="docutils literal"><span class="pre">--tls-auth</span></tt> can be +strengthened by adding the <tt class="docutils literal"><span class="pre">--replay-persist</span></tt> option which will keep +OpenVPN's replay protection state in a file so that it is not lost +across restarts.</p> +<p>It should be emphasized that this feature is optional and that the key +file used with <tt class="docutils literal"><span class="pre">--tls-auth</span></tt> gives a peer nothing more than the power +to initiate a TLS handshake. It is not used to encrypt or authenticate +any tunnel data.</p> +<p class="last">Use <tt class="docutils literal"><span class="pre">--tls-crypt</span></tt> instead if you want to use the key file to not only +authenticate, but also encrypt the TLS control channel.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--tls-groups <var>list</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">A list of allowable groups/curves in order of preference.</p> +<p>Set the allowed elliptic curves/groups for the TLS session. +These groups are allowed to be used in signatures and key exchange.</p> +<p>mbedTLS currently allows all known curves per default.</p> +<p>OpenSSL 1.1+ restricts the list per default to</p> +<pre class="literal-block"> +"X25519:secp256r1:X448:secp521r1:secp384r1". +</pre> +<p>If you use certificates that use non-standard curves, you +might need to add them here. If you do not force the ecdh curve +by using <tt class="docutils literal"><span class="pre">--ecdh-curve</span></tt>, the groups for ecdh will also be picked +from this list.</p> +<p>OpenVPN maps the curve name <cite>secp256r1</cite> to <cite>prime256v1</cite> to allow +specifying the same tls-groups option for mbedTLS and OpenSSL.</p> +<p class="last">Warning: this option not only affects elliptic curve certificates +but also the key exchange in TLS 1.3 and using this option improperly +will disable TLS 1.3.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--tls-cert-profile <var>profile</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Set the allowed cryptographic algorithms for certificates according to +<tt class="docutils literal">profile</tt>.</p> +<p>The following profiles are supported:</p> +<dl class="docutils"> +<dt><code>legacy</code> (default)</dt> +<dd>SHA1 and newer, RSA 2048-bit+, any elliptic curve.</dd> +<dt><code>preferred</code></dt> +<dd>SHA2 and newer, RSA 2048-bit+, any elliptic curve.</dd> +<dt><code>suiteb</code></dt> +<dd>SHA256/SHA384, ECDSA with P-256 or P-384.</dd> +</dl> +<p>This option is only fully supported for mbed TLS builds. OpenSSL builds +use the following approximation:</p> +<dl class="docutils"> +<dt><code>legacy</code> (default)</dt> +<dd>sets "security level 1"</dd> +<dt><code>preferred</code></dt> +<dd>sets "security level 2"</dd> +<dt><code>suiteb</code></dt> +<dd>sets "security level 3" and <tt class="docutils literal"><span class="pre">--tls-cipher</span> "SUITEB128"</tt>.</dd> +</dl> +<p class="last">OpenVPN will migrate to 'preferred' as default in the future. Please +ensure that your keys already comply.</p> +</td></tr> +</tbody> +</table> +<dl class="docutils"> +<dt><em>WARNING:</em> <tt class="docutils literal"><span class="pre">--tls-ciphers</span></tt>, <tt class="docutils literal"><span class="pre">--tls-ciphersuites</span></tt> and <tt class="docutils literal"><span class="pre">tls-groups</span></tt></dt> +<dd>These options are expert features, which - if used correctly - can +improve the security of your VPN connection. But it is also easy to +unwittingly use them to carefully align a gun with your foot, or just +break your connection. Use with care!</dd> +</dl> +<table class="docutils option-list" frame="void" rules="none"> +<col class="option" /> +<col class="description" /> +<tbody valign="top"> +<tr><td class="option-group"> +<kbd><span class="option">--tls-cipher <var>l</var></span></kbd></td> +<td><p class="first">A list <tt class="docutils literal">l</tt> of allowable TLS ciphers delimited by a colon ("<code>:</code>").</p> +<p>These setting can be used to ensure that certain cipher suites are used +(or not used) for the TLS connection. OpenVPN uses TLS to secure the +control channel, over which the keys that are used to protect the actual +VPN traffic are exchanged.</p> +<p>The supplied list of ciphers is (after potential OpenSSL/IANA name +translation) simply supplied to the crypto library. Please see the +OpenSSL and/or mbed TLS documentation for details on the cipher list +interpretation.</p> +<p>For OpenSSL, the <tt class="docutils literal"><span class="pre">--tls-cipher</span></tt> is used for TLS 1.2 and below.</p> +<p>Use <tt class="docutils literal"><span class="pre">--show-tls</span></tt> to see a list of TLS ciphers supported by your crypto +library.</p> +<p class="last">The default for <tt class="docutils literal"><span class="pre">--tls-cipher</span></tt> is to use mbed TLS's default cipher list +when using mbed TLS or +<code>DEFAULT:!EXP:!LOW:!MEDIUM:!kDH:!kECDH:!DSS:!PSK:!SRP:!kRSA</code> when +using OpenSSL.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--tls-ciphersuites <var>l</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Same as <tt class="docutils literal"><span class="pre">--tls-cipher</span></tt> but for TLS 1.3 and up. mbed TLS has no +TLS 1.3 support yet and only the <tt class="docutils literal"><span class="pre">--tls-cipher</span></tt> setting is used.</p> +<p class="last">The default for <cite>--tls-ciphersuites</cite> is to use the crypto library's +default.</p> +</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--tls-client</span></kbd></td> +<td>Enable TLS and assume client role during TLS handshake.</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--tls-crypt <var>keyfile</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Encrypt and authenticate all control channel packets with the key from +<tt class="docutils literal">keyfile</tt>. (See <tt class="docutils literal"><span class="pre">--tls-auth</span></tt> for more background.)</p> +<p>Encrypting (and authenticating) control channel packets:</p> +<ul class="simple"> +<li>provides more privacy by hiding the certificate used for the TLS +connection,</li> +<li>makes it harder to identify OpenVPN traffic as such,</li> +<li>provides "poor-man's" post-quantum security, against attackers who will +never know the pre-shared key (i.e. no forward secrecy).</li> +</ul> +<p>In contrast to <tt class="docutils literal"><span class="pre">--tls-auth</span></tt>, <tt class="docutils literal"><span class="pre">--tls-crypt</span></tt> does <em>not</em> require the +user to set <tt class="docutils literal"><span class="pre">--key-direction</span></tt>.</p> +<p><strong>Security Considerations</strong></p> +<p>All peers use the same <tt class="docutils literal"><span class="pre">--tls-crypt</span></tt> pre-shared group key to +authenticate and encrypt control channel messages. To ensure that IV +collisions remain unlikely, this key should not be used to encrypt more +than 2^48 client-to-server or 2^48 server-to-client control channel +messages. A typical initial negotiation is about 10 packets in each +direction. Assuming both initial negotiation and renegotiations are at +most 2^16 (65536) packets (to be conservative), and (re)negotiations +happen each minute for each user (24/7), this limits the tls-crypt key +lifetime to 8171 years divided by the number of users. So a setup with +1000 users should rotate the key at least once each eight years. (And a +setup with 8000 users each year.)</p> +<p>If IV collisions were to occur, this could result in the security of +<tt class="docutils literal"><span class="pre">--tls-crypt</span></tt> degrading to the same security as using <tt class="docutils literal"><span class="pre">--tls-auth</span></tt>. +That is, the control channel still benefits from the extra protection +against active man-in-the-middle-attacks and DoS attacks, but may no +longer offer extra privacy and post-quantum security on top of what TLS +itself offers.</p> +<p class="last">For large setups or setups where clients are not trusted, consider using +<tt class="docutils literal"><span class="pre">--tls-crypt-v2</span></tt> instead. That uses per-client unique keys, and +thereby improves the bounds to 'rotate a client key at least once per +8000 years'.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--tls-crypt-v2 <var>keyfile</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Use client-specific tls-crypt keys.</p> +<p>For clients, <tt class="docutils literal">keyfile</tt> is a client-specific tls-crypt key. Such a key +can be generated using the <code>--genkey tls-crypt-v2-client</code> option.</p> +<p>For servers, <tt class="docutils literal">keyfile</tt> is used to unwrap client-specific keys supplied +by the client during connection setup. This key must be the same as the +key used to generate the client-specific key (see <code>--genkey +tls-crypt-v2-client</code>).</p> +<p class="last">On servers, this option can be used together with the <tt class="docutils literal"><span class="pre">--tls-auth</span></tt> or +<tt class="docutils literal"><span class="pre">--tls-crypt</span></tt> option. In that case, the server will detect whether the +client is using client-specific keys, and automatically select the right +mode.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--tls-crypt-v2-verify <var>cmd</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Run command <tt class="docutils literal">cmd</tt> to verify the metadata of the client-specific +tls-crypt-v2 key of a connecting client. This allows server +administrators to reject client connections, before exposing the TLS +stack (including the notoriously dangerous X.509 and ASN.1 stacks) to +the connecting client.</p> +<p>OpenVPN supplies the following environment variables to the command:</p> +<ul class="simple"> +<li><code>script_type</code> is set to <code>tls-crypt-v2-verify</code></li> +<li><code>metadata_type</code> is set to <code>0</code> if the metadata was user +supplied, or <code>1</code> if it's a 64-bit unix timestamp representing +the key creation time.</li> +<li><code>metadata_file</code> contains the filename of a temporary file that +contains the client metadata.</li> +</ul> +<p class="last">The command can reject the connection by exiting with a non-zero exit +code.</p> +</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--tls-exit</span></kbd></td> +<td>Exit on TLS negotiation failure.</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--tls-export-cert <var>directory</var></span></kbd></td> +</tr> +<tr><td> </td><td>Store the certificates the clients use upon connection to this +directory. This will be done before <tt class="docutils literal"><span class="pre">--tls-verify</span></tt> is called. The +certificates will use a temporary name and will be deleted when the +tls-verify script returns. The file name used for the certificate is +available via the <tt class="docutils literal">peer_cert</tt> environment variable.</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--tls-server</span></kbd></td> +<td>Enable TLS and assume server role during TLS handshake. Note that +OpenVPN is designed as a peer-to-peer application. The designation of +client or server is only for the purpose of negotiating the TLS control +channel.</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--tls-timeout <var>n</var></span></kbd></td> +</tr> +<tr><td> </td><td>Packet retransmit timeout on TLS control channel if no acknowledgment +from remote within <tt class="docutils literal">n</tt> seconds (default <code>2</code>). When OpenVPN sends +a control packet to its peer, it will expect to receive an +acknowledgement within <tt class="docutils literal">n</tt> seconds or it will retransmit the packet, +subject to a TCP-like exponential backoff algorithm. This parameter only +applies to control channel packets. Data channel packets (which carry +encrypted tunnel data) are never acknowledged, sequenced, or +retransmitted by OpenVPN because the higher level network protocols +running on top of the tunnel such as TCP expect this role to be left to +them.</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--tls-version-min <var>args</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Sets the minimum TLS version we will accept from the peer (default is +"1.0").</p> +<p>Valid syntax:</p> +<pre class="literal-block"> +tls-version-min version ['or-highest'] +</pre> +<p class="last">Examples for version include <code>1.0</code>, <code>1.1</code>, or <code>1.2</code>. If +<code>or-highest</code> is specified and version is not recognized, we will +only accept the highest TLS version supported by the local SSL +implementation.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--tls-version-max <var>version</var></span></kbd></td> +</tr> +<tr><td> </td><td>Set the maximum TLS version we will use (default is the highest version +supported). Examples for version include <code>1.0</code>, <code>1.1</code>, or +<code>1.2</code>.</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--verify-hash <var>args</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Specify SHA1 or SHA256 fingerprint for level-1 cert.</p> +<p>Valid syntax:</p> +<pre class="literal-block"> +verify-hash hash [algo] +</pre> +<p>The level-1 cert is the CA (or intermediate cert) that signs the leaf +certificate, and is one removed from the leaf certificate in the +direction of the root. When accepting a connection from a peer, the +level-1 cert fingerprint must match <tt class="docutils literal">hash</tt> or certificate verification +will fail. Hash is specified as XX:XX:... For example:</p> +<pre class="literal-block"> +AD:B0:95:D8:09:C8:36:45:12:A9:89:C8:90:09:CB:13:72:A6:AD:16 +</pre> +<p class="last">The <tt class="docutils literal">algo</tt> flag can be either <code>SHA1</code> or <code>SHA256</code>. If not +provided, it defaults to <code>SHA1</code>.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--verify-x509-name <var>args</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Accept connections only if a host's X.509 name is equal to <strong>name.</strong> The +remote host must also pass all other tests of verification.</p> +<p>Valid syntax:</p> +<pre class="literal-block"> +verify-x509 name type +</pre> +<p>Which X.509 name is compared to <tt class="docutils literal">name</tt> depends on the setting of type. +<tt class="docutils literal">type</tt> can be <code>subject</code> to match the complete subject DN +(default), <code>name</code> to match a subject RDN or <code>name-prefix</code> to +match a subject RDN prefix. Which RDN is verified as name depends on the +<tt class="docutils literal"><span class="pre">--x509-username-field</span></tt> option. But it defaults to the common name +(CN), e.g. a certificate with a subject DN</p> +<pre class="literal-block"> +C=KG, ST=NA, L=Bishkek, CN=Server-1 +</pre> +<p>would be matched by:</p> +<pre class="literal-block"> +verify-x509-name 'C=KG, ST=NA, L=Bishkek, CN=Server-1' +verify-x509-name Server-1 name +verify-x509-name Server- name-prefix +</pre> +<p>The last example is useful if you want a client to only accept +connections to <code>Server-1</code>, <code>Server-2</code>, etc.</p> +<p><tt class="docutils literal"><span class="pre">--verify-x509-name</span></tt> is a useful replacement for the <tt class="docutils literal"><span class="pre">--tls-verify</span></tt> +option to verify the remote host, because <tt class="docutils literal"><span class="pre">--verify-x509-name</span></tt> works +in a <tt class="docutils literal"><span class="pre">--chroot</span></tt> environment without any dependencies.</p> +<p>Using a name prefix is a useful alternative to managing a CRL +(Certificate Revocation List) on the client, since it allows the client +to refuse all certificates except for those associated with designated +servers.</p> +<dl class="last docutils"> +<dt><em>NOTE:</em></dt> +<dd>Test against a name prefix only when you are using OpenVPN +with a custom CA certificate that is under your control. Never use +this option with type <code>name-prefix</code> when your client +certificates are signed by a third party, such as a commercial +web CA.</dd> +</dl> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--x509-track <var>attribute</var></span></kbd></td> +</tr> +<tr><td> </td><td>Save peer X509 <strong>attribute</strong> value in environment for use by plugins and +management interface. Prepend a <code>+</code> to <tt class="docutils literal">attribute</tt> to save values +from full cert chain. Values will be encoded as +<code>X509_<depth>_<attribute>=<value></code>. Multiple <tt class="docutils literal"><span class="pre">--x509-track</span></tt> +options can be defined to track multiple attributes.</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--x509-username-field <var>args</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Field in the X.509 certificate subject to be used as the username +(default <code>CN</code>).</p> +<p>Valid syntax:</p> +<pre class="literal-block"> +x509-username-field [ext:]fieldname +</pre> +<p>Typically, this option is specified with <strong>fieldname</strong> as +either of the following:</p> +<pre class="literal-block"> +x509-username-field emailAddress +x509-username-field ext:subjectAltName +</pre> +<p>The first example uses the value of the <code>emailAddress</code> attribute +in the certificate's Subject field as the username. The second example +uses the <code>ext:</code> prefix to signify that the X.509 extension +<tt class="docutils literal">fieldname</tt> <code>subjectAltName</code> be searched for an rfc822Name +(email) field to be used as the username. In cases where there are +multiple email addresses in <code>ext:fieldname</code>, the last occurrence +is chosen.</p> +<p>When this option is used, the <tt class="docutils literal"><span class="pre">--verify-x509-name</span></tt> option will match +against the chosen <tt class="docutils literal">fieldname</tt> instead of the Common Name.</p> +<p>Only the <code>subjectAltName</code> and <code>issuerAltName</code> X.509 +extensions are supported.</p> +<p class="last"><strong>Please note:</strong> This option has a feature which will convert an +all-lowercase <tt class="docutils literal">fieldname</tt> to uppercase characters, e.g., +<code>ou</code> -> <code>OU</code>. A mixed-case <tt class="docutils literal">fieldname</tt> or one having the +<code>ext:</code> prefix will be left as-is. This automatic upcasing feature is +deprecated and will be removed in a future release.</p> +</td></tr> +</tbody> +</table> +</div> +<div class="section" id="pkcs-11-smartcard-options"> +<h2>PKCS#11 / SmartCard options</h2> +<table class="docutils option-list" frame="void" rules="none"> +<col class="option" /> +<col class="description" /> +<tbody valign="top"> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--pkcs11-cert-private <var>args</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Set if access to certificate object should be performed after login. +Every provider has its own setting.</p> +<p>Valid syntaxes:</p> +<pre class="last literal-block"> +pkcs11-cert-private 0 +pkcs11-cert-private 1 +</pre> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--pkcs11-id <var>name</var></span></kbd></td> +</tr> +<tr><td> </td><td>Specify the serialized certificate id to be used. The id can be gotten +by the standalone <tt class="docutils literal"><span class="pre">--show-pkcs11-ids</span></tt> option.</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--pkcs11-id-management</span></kbd></td> +</tr> +<tr><td> </td><td>Acquire PKCS#11 id from management interface. In this case a +<code>NEED-STR 'pkcs11-id-request'</code> real-time message will be triggered, +application may use pkcs11-id-count command to retrieve available number of +certificates, and pkcs11-id-get command to retrieve certificate id and +certificate body.</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--pkcs11-pin-cache <var>seconds</var></span></kbd></td> +</tr> +<tr><td> </td><td>Specify how many seconds the PIN can be cached, the default is until the +token is removed.</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--pkcs11-private-mode <var>mode</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Specify which method to use in order to perform private key operations. +A different mode can be specified for each provider. Mode is encoded as +hex number, and can be a mask one of the following:</p> +<p><code>0</code> (default) Try to determine automatically.</p> +<p><code>1</code> Use sign.</p> +<p><code>2</code> Use sign recover.</p> +<p><code>4</code> Use decrypt.</p> +<p class="last"><code>8</code> Use unwrap.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--pkcs11-protected-authentication <var>args</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Use PKCS#11 protected authentication path, useful for biometric and +external keypad devices. Every provider has its own setting.</p> +<p>Valid syntaxes:</p> +<pre class="last literal-block"> +pkcs11-protected-authentication 0 +pkcs11-protected-authentication 1 +</pre> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--pkcs11-providers <var>provider</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Specify an RSA Security Inc. PKCS #11 Cryptographic Token Interface +(Cryptoki) providers to load. This option can be used instead of +<tt class="docutils literal"><span class="pre">--cert</span></tt>, <tt class="docutils literal"><span class="pre">--key</span></tt> and <tt class="docutils literal"><span class="pre">--pkcs12</span></tt>.</p> +<p class="last">If p11-kit is present on the system, its <code>p11-kit-proxy.so</code> module +will be loaded by default if either the <tt class="docutils literal"><span class="pre">--pkcs11-id</span></tt> or +<tt class="docutils literal"><span class="pre">--pkcs11-id-management</span></tt> options are specified without +<tt class="docutils literal"><span class="pre">--pkcs11-provider</span></tt> being given.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--show-pkcs11-ids <var>args</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">(Standalone) Show PKCS#11 token object list.</p> +<p>Valid syntax:</p> +<pre class="literal-block"> +show-pkcs11 [provider] [cert_private] +</pre> +<p>Specify <tt class="docutils literal">cert_private</tt> as <code>1</code> if certificates are stored as +private objects.</p> +<p>If <em>p11-kit</em> is present on the system, the <tt class="docutils literal">provider</tt> argument is +optional; if omitted the default <code>p11-kit-proxy.so</code> module will be +queried.</p> +<p class="last"><tt class="docutils literal"><span class="pre">--verb</span></tt> option can be used BEFORE this option to produce debugging +information.</p> +</td></tr> +</tbody> +</table> +</div> +</div> +<div class="section" id="data-channel-cipher-negotiation"> +<h1>Data channel cipher negotiation</h1> +<p>OpenVPN 2.4 and higher have the capability to negotiate the data cipher that +is used to encrypt data packets. This section describes the mechanism in more detail and the +different backwards compatibility mechanism with older server and clients.</p> +<div class="section" id="openvpn-2-5-and-higher-behaviour"> +<h2>OpenVPN 2.5 and higher behaviour</h2> +<p>When both client and server are at least running OpenVPN 2.5, that the order of +the ciphers of the server's <tt class="docutils literal"><span class="pre">--data-ciphers</span></tt> is used to pick the the data cipher. +That means that the first cipher in that list that is also in the client's +<tt class="docutils literal"><span class="pre">--data-ciphers</span></tt> list is chosen. If no common cipher is found the client is rejected +with a AUTH_FAILED message (as seen in client log):</p> +<blockquote> +AUTH: Received control message: AUTH_FAILED,Data channel cipher negotiation failed (no shared cipher)</blockquote> +<p>OpenVPN 2.5 will only allow the ciphers specified in <tt class="docutils literal"><span class="pre">--data-ciphers</span></tt>. To ensure +backwards compatibility also if a cipher is specified using the <tt class="docutils literal"><span class="pre">--cipher</span></tt> option +it is automatically added to this list. If both options are unset the default is +<code>AES-256-GCM:AES-128-GCM</code>.</p> +</div> +<div class="section" id="openvpn-2-4-clients"> +<h2>OpenVPN 2.4 clients</h2> +<p>The negotiation support in OpenVPN 2.4 was the first iteration of the implementation +and still had some quirks. Its main goal was "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 <tt class="docutils literal"><span class="pre">--ncp-disable</span></tt> will always announce support for +<cite>AES-256-GCM</cite> and <cite>AES-128-GCM</cite> to a server by sending <code>IV_NCP=2</code>.</p> +<p>This only causes a problem if <tt class="docutils literal"><span class="pre">--ncp-ciphers</span></tt> option has been changed from the +default of <code>AES-256-GCM:AES-128-GCM</code> to a value that does not include +these two ciphers. When a OpenVPN servers try to use <cite>AES-256-GCM</cite> or +<cite>AES-128-GCM</cite> the connection will then fail. It is therefore recommended to +always have the <cite>AES-256-GCM</cite> and <cite>AES-128-GCM</cite> ciphers to the <tt class="docutils literal"><span class="pre">--ncp-ciphers</span></tt> +options to avoid this behaviour.</p> +</div> +<div class="section" id="openvpn-3-clients"> +<h2>OpenVPN 3 clients</h2> +<p>Clients based on the OpenVPN 3.x library (<a class="reference external" href="https://github.com/openvpn/openvpn3/">https://github.com/openvpn/openvpn3/</a>) +do not have a configurable <tt class="docutils literal"><span class="pre">--ncp-ciphers</span></tt> or <tt class="docutils literal"><span class="pre">--data-ciphers</span></tt> option. Instead +these clients will announce support for all their supported AEAD ciphers +(<cite>AES-256-GCM</cite>, <cite>AES-128-GCM</cite> and in newer versions also <cite>Chacha20-Poly1305</cite>).</p> +<p>To support OpenVPN 3.x based clients at least one of these ciphers needs to be +included in the server's <tt class="docutils literal"><span class="pre">--data-ciphers</span></tt> option.</p> +</div> +<div class="section" id="openvpn-2-3-and-older-clients-and-clients-with-ncp-disable"> +<h2>OpenVPN 2.3 and older clients (and clients with <tt class="docutils literal"><span class="pre">--ncp-disable</span></tt>)</h2> +<p>When a client without cipher negotiation support connects to a server the +cipher specified with the <tt class="docutils literal"><span class="pre">--cipher</span></tt> option in the client configuration +must be included in the <tt class="docutils literal"><span class="pre">--data-ciphers</span></tt> option of the server to allow +the client to connect. Otherwise the client will be sent the <tt class="docutils literal">AUTH_FAILED</tt> +message that indicates no shared cipher.</p> +<p>If the client is 2.3 or older and has been configured with the +<tt class="docutils literal"><span class="pre">--enable-small</span></tt> <code>./configure</code> argument, using +<tt class="docutils literal"><span class="pre">data-ciphers-fallback</span> cipher</tt> in the server config file with the explicit +cipher used by the client is necessary.</p> +</div> +<div class="section" id="openvpn-2-4-server"> +<h2>OpenVPN 2.4 server</h2> +<p>When a client indicates support for <cite>AES-128-GCM</cite> and <cite>AES-256-GCM</cite> +(with <tt class="docutils literal">IV_NCP=2</tt>) an OpenVPN 2.4 server will send the first +cipher of the <tt class="docutils literal"><span class="pre">--ncp-ciphers</span></tt> to the OpenVPN client regardless of what +the cipher is. To emulate the behaviour of an OpenVPN 2.4 client as close +as possible and have compatibility to a setup that depends on this quirk, +adding <cite>AES-128-GCM</cite> and <cite>AES-256-GCM</cite> to the client's <tt class="docutils literal"><span class="pre">--data-ciphers</span></tt> +option is required. OpenVPN 2.5+ will only announce the <tt class="docutils literal">IV_NCP=2</tt> flag if +those ciphers are present.</p> +</div> +<div class="section" id="openvpn-2-3-and-older-servers-and-servers-with-ncp-disable"> +<h2>OpenVPN 2.3 and older servers (and servers with <tt class="docutils literal"><span class="pre">--ncp-disable</span></tt>)</h2> +<p>The cipher used by the server must be included in <tt class="docutils literal"><span class="pre">--data-ciphers</span></tt> to +allow the client connecting to a server without cipher negotiation +support. +(For compatibility OpenVPN 2.5 will also accept the cipher set with +<tt class="docutils literal"><span class="pre">--cipher</span></tt>)</p> +<p>If the server is 2.3 or older and has been configured with the +<tt class="docutils literal"><span class="pre">--enable-small</span></tt> <code>./configure</code> argument, adding +<tt class="docutils literal"><span class="pre">data-ciphers-fallback</span> cipher</tt> to the client config with the explicit +cipher used by the server is necessary.</p> +</div> +<div class="section" id="blowfish-in-cbc-mode-bf-cbc-deprecation"> +<h2>Blowfish in CBC mode (BF-CBC) deprecation</h2> +<p>The <tt class="docutils literal"><span class="pre">--cipher</span></tt> option defaulted to <tt class="docutils literal"><span class="pre">BF-CBC</span></tt> in OpenVPN 2.4 and older +version. The default was never changed to ensure backwards compatibility. +In OpenVPN 2.5 this behaviour has now been changed so that if the <tt class="docutils literal"><span class="pre">--cipher</span></tt> +is not explicitly set it does not allow the weak <tt class="docutils literal"><span class="pre">BF-CBC</span></tt> cipher any more +and needs to explicitly added as <tt class="docutils literal"><span class="pre">--cipher</span> <span class="pre">BFC-CBC</span></tt> or added to +<tt class="docutils literal"><span class="pre">--data-ciphers</span></tt>.</p> +<p>We strongly recommend to switching away from BF-CBC to a +more secure cipher as soon as possible instead.</p> +</div> +</div> +<div class="section" id="network-configuration"> +<h1>NETWORK CONFIGURATION</h1> +<p>OpenVPN consists of two sides of network configuration. One side is the +<em>link</em> between the local and remote side, the other side is the <em>virtual +network adapter</em> (tun/tap device).</p> +<div class="section" id="link-options"> +<h2>Link Options</h2> +<p>This link options section covers options related to the connection between +the local and the remote host.</p> +<table class="docutils option-list" frame="void" rules="none"> +<col class="option" /> +<col class="description" /> +<tbody valign="top"> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--bind <var>keywords</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Bind to local address and port. This is the default unless any of +<tt class="docutils literal"><span class="pre">--proto</span> <span class="pre">tcp-client</span></tt> , <tt class="docutils literal"><span class="pre">--http-proxy</span></tt> or <tt class="docutils literal"><span class="pre">--socks-proxy</span></tt> are used.</p> +<p class="last">If the optional <code>ipv6only</code> keyword is present OpenVPN will bind only +to IPv6 (as opposed to IPv6 and IPv4) when a IPv6 socket is opened.</p> +</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--float</span></kbd></td> +<td><p class="first">Allow remote peer to change its IP address and/or port number, such as +due to DHCP (this is the default if <tt class="docutils literal"><span class="pre">--remote</span></tt> is not used). +<tt class="docutils literal"><span class="pre">--float</span></tt> when specified with <tt class="docutils literal"><span class="pre">--remote</span></tt> allows an OpenVPN session +to initially connect to a peer at a known address, however if packets +arrive from a new address and pass all authentication tests, the new +address will take control of the session. This is useful when you are +connecting to a peer which holds a dynamic address such as a dial-in +user or DHCP client.</p> +<p class="last">Essentially, <tt class="docutils literal"><span class="pre">--float</span></tt> tells OpenVPN to accept authenticated packets +from any address, not only the address which was specified in the +<tt class="docutils literal"><span class="pre">--remote</span></tt> option.</p> +</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--fragment <var>max</var></span></kbd></td> +<td><p class="first">Enable internal datagram fragmentation so that no UDP datagrams are sent +which are larger than <tt class="docutils literal">max</tt> bytes.</p> +<p>The <tt class="docutils literal">max</tt> parameter is interpreted in the same way as the +<tt class="docutils literal"><span class="pre">--link-mtu</span></tt> parameter, i.e. the UDP packet size after encapsulation +overhead has been added in, but not including the UDP header itself.</p> +<p>The <tt class="docutils literal"><span class="pre">--fragment</span></tt> option only makes sense when you are using the UDP +protocol (<tt class="docutils literal"><span class="pre">--proto</span> udp</tt>).</p> +<p><tt class="docutils literal"><span class="pre">--fragment</span></tt> adds 4 bytes of overhead per datagram.</p> +<p>See the <tt class="docutils literal"><span class="pre">--mssfix</span></tt> option below for an important related option to +<tt class="docutils literal"><span class="pre">--fragment</span></tt>.</p> +<p>It should also be noted that this option is not meant to replace UDP +fragmentation at the IP stack level. It is only meant as a last resort +when path MTU discovery is broken. Using this option is less efficient +than fixing path MTU discovery for your IP link and using native IP +fragmentation instead.</p> +<p class="last">Having said that, there are circumstances where using OpenVPN's internal +fragmentation capability may be your only option, such as tunneling a +UDP multicast stream which requires fragmentation.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--keepalive <var>args</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">A helper directive designed to simplify the expression of <tt class="docutils literal"><span class="pre">--ping</span></tt> and +<tt class="docutils literal"><span class="pre">--ping-restart</span></tt>.</p> +<p>Valid syntax:</p> +<pre class="literal-block"> +keepalive interval timeout +</pre> +<p>This option can be used on both client and server side, but it is enough +to add this on the server side as it will push appropriate <tt class="docutils literal"><span class="pre">--ping</span></tt> +and <tt class="docutils literal"><span class="pre">--ping-restart</span></tt> options to the client. If used on both server and +client, the values pushed from server will override the client local +values.</p> +<p>The <tt class="docutils literal">timeout</tt> argument will be twice as long on the server side. This +ensures that a timeout is detected on client side before the server side +drops the connection.</p> +<p>For example, <tt class="docutils literal"><span class="pre">--keepalive</span> 10 60</tt> expands as follows:</p> +<pre class="last literal-block"> +if mode server: + ping 10 # Argument: interval + ping-restart 120 # Argument: timeout*2 + push "ping 10" # Argument: interval + push "ping-restart 60" # Argument: timeout +else + ping 10 # Argument: interval + ping-restart 60 # Argument: timeout +</pre> +</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--link-mtu <var>n</var></span></kbd></td> +<td>Sets an upper bound on the size of UDP packets which are sent between +OpenVPN peers. <em>It's best not to set this parameter unless you know what +you're doing.</em></td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--local <var>host</var></span></kbd></td> +<td>Local host name or IP address for bind. If specified, OpenVPN will bind +to this address only. If unspecified, OpenVPN will bind to all +interfaces.</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--lport <var>port</var></span></kbd></td> +<td>Set local TCP/UDP port number or name. Cannot be used together with +<tt class="docutils literal"><span class="pre">--nobind</span></tt> option.</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--mark <var>value</var></span></kbd></td> +<td>Mark encrypted packets being sent with value. The mark value can be +matched in policy routing and packetfilter rules. This option is only +supported in Linux and does nothing on other operating systems.</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--mode <var>m</var></span></kbd></td> +<td>Set OpenVPN major mode. By default, OpenVPN runs in point-to-point mode +(<code>p2p</code>). OpenVPN 2.0 introduces a new mode (<code>server</code>) which +implements a multi-client server capability.</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--mssfix <var>max</var></span></kbd></td> +<td><p class="first">Announce to TCP sessions running over the tunnel that they should limit +their send packet sizes such that after OpenVPN has encapsulated them, +the resulting UDP packet size that OpenVPN sends to its peer will not +exceed <tt class="docutils literal">max</tt> bytes. The default value is <code>1450</code>.</p> +<p>The <tt class="docutils literal">max</tt> parameter is interpreted in the same way as the +<tt class="docutils literal"><span class="pre">--link-mtu</span></tt> parameter, i.e. the UDP packet size after encapsulation +overhead has been added in, but not including the UDP header itself. +Resulting packet would be at most 28 bytes larger for IPv4 and 48 bytes +for IPv6 (20/40 bytes for IP header and 8 bytes for UDP header). Default +value of 1450 allows IPv4 packets to be transmitted over a link with MTU +1473 or higher without IP level fragmentation.</p> +<p>The <tt class="docutils literal"><span class="pre">--mssfix</span></tt> option only makes sense when you are using the UDP +protocol for OpenVPN peer-to-peer communication, i.e. <tt class="docutils literal"><span class="pre">--proto</span> udp</tt>.</p> +<p><tt class="docutils literal"><span class="pre">--mssfix</span></tt> and <tt class="docutils literal"><span class="pre">--fragment</span></tt> can be ideally used together, where +<tt class="docutils literal"><span class="pre">--mssfix</span></tt> will try to keep TCP from needing packet fragmentation in +the first place, and if big packets come through anyhow (from protocols +other than TCP), <tt class="docutils literal"><span class="pre">--fragment</span></tt> will internally fragment them.</p> +<p>Both <tt class="docutils literal"><span class="pre">--fragment</span></tt> and <tt class="docutils literal"><span class="pre">--mssfix</span></tt> are designed to work around cases +where Path MTU discovery is broken on the network path between OpenVPN +peers.</p> +<p>The usual symptom of such a breakdown is an OpenVPN connection which +successfully starts, but then stalls during active usage.</p> +<p>If <tt class="docutils literal"><span class="pre">--fragment</span></tt> and <tt class="docutils literal"><span class="pre">--mssfix</span></tt> are used together, <tt class="docutils literal"><span class="pre">--mssfix</span></tt> will +take its default <tt class="docutils literal">max</tt> parameter from the <tt class="docutils literal"><span class="pre">--fragment</span> max</tt> option.</p> +<p>Therefore, one could lower the maximum UDP packet size to 1300 (a good +first try for solving MTU-related connection problems) with the +following options:</p> +<pre class="last literal-block"> +--tun-mtu 1500 --fragment 1300 --mssfix +</pre> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--mtu-disc <var>type</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Should we do Path MTU discovery on TCP/UDP channel? Only supported on +OSes such as Linux that supports the necessary system call to set.</p> +<p>Valid types:</p> +<p><code>no</code> Never send DF (Don't Fragment) frames</p> +<p><code>maybe</code> Use per-route hints</p> +<p class="last"><code>yes</code> Always DF (Don't Fragment)</p> +</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--mtu-test</span></kbd></td> +<td>To empirically measure MTU on connection startup, add the <tt class="docutils literal"><span class="pre">--mtu-test</span></tt> +option to your configuration. OpenVPN will send ping packets of various +sizes to the remote peer and measure the largest packets which were +successfully received. The <tt class="docutils literal"><span class="pre">--mtu-test</span></tt> process normally takes about 3 +minutes to complete.</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--nobind</span></kbd></td> +<td>Do not bind to local address and port. The IP stack will allocate a +dynamic port for returning packets. Since the value of the dynamic port +could not be known in advance by a peer, this option is only suitable +for peers which will be initiating connections by using the --remote +option.</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--passtos</span></kbd></td> +<td>Set the TOS field of the tunnel packet to what the payload's TOS is.</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--ping <var>n</var></span></kbd></td> +<td><p class="first">Ping remote over the TCP/UDP control channel if no packets have been +sent for at least <tt class="docutils literal">n</tt> seconds (specify <tt class="docutils literal"><span class="pre">--ping</span></tt> on both peers to +cause ping packets to be sent in both directions since OpenVPN ping +packets are not echoed like IP ping packets). When used in one of +OpenVPN's secure modes (where <tt class="docutils literal"><span class="pre">--secret</span></tt>, <tt class="docutils literal"><span class="pre">--tls-server</span></tt> or +<tt class="docutils literal"><span class="pre">--tls-client</span></tt> is specified), the ping packet will be +cryptographically secure.</p> +<p>This option has two intended uses:</p> +<ol class="last arabic simple"> +<li>Compatibility with stateful firewalls. The periodic ping will ensure +that a stateful firewall rule which allows OpenVPN UDP packets to +pass will not time out.</li> +<li>To provide a basis for the remote to test the existence of its peer +using the <tt class="docutils literal"><span class="pre">--ping-exit</span></tt> option.</li> +</ol> +</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--ping-exit <var>n</var></span></kbd></td> +<td><p class="first">Causes OpenVPN to exit after <tt class="docutils literal">n</tt> seconds pass without reception of a +ping or other packet from remote. This option can be combined with +<tt class="docutils literal"><span class="pre">--inactive</span></tt>, <tt class="docutils literal"><span class="pre">--ping</span></tt> and <tt class="docutils literal"><span class="pre">--ping-exit</span></tt> to create a two-tiered +inactivity disconnect.</p> +<p>For example,</p> +<pre class="literal-block"> +openvpn [options...] --inactive 3600 --ping 10 --ping-exit 60 +</pre> +<p class="last">when used on both peers will cause OpenVPN to exit within 60 seconds if +its peer disconnects, but will exit after one hour if no actual tunnel +data is exchanged.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--ping-restart <var>n</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Similar to <tt class="docutils literal"><span class="pre">--ping-exit</span></tt>, but trigger a <code>SIGUSR1</code> restart after +<tt class="docutils literal">n</tt> seconds pass without reception of a ping or other packet from +remote.</p> +<p>This option is useful in cases where the remote peer has a dynamic IP +address and a low-TTL DNS name is used to track the IP address using a +service such as <a class="reference external" href="http://dyndns.org/">http://dyndns.org/</a> + a dynamic DNS client such as +<tt class="docutils literal">ddclient</tt>.</p> +<p>If the peer cannot be reached, a restart will be triggered, causing the +hostname used with <tt class="docutils literal"><span class="pre">--remote</span></tt> to be re-resolved (if <tt class="docutils literal"><span class="pre">--resolv-retry</span></tt> +is also specified).</p> +<p>In server mode, <tt class="docutils literal"><span class="pre">--ping-restart</span></tt>, <tt class="docutils literal"><span class="pre">--inactive</span></tt> or any other type of +internally generated signal will always be applied to individual client +instance objects, never to whole server itself. Note also in server mode +that any internally generated signal which would normally cause a +restart, will cause the deletion of the client instance object instead.</p> +<p>In client mode, the <tt class="docutils literal"><span class="pre">--ping-restart</span></tt> parameter is set to 120 seconds +by default. This default will hold until the client pulls a replacement +value from the server, based on the <tt class="docutils literal"><span class="pre">--keepalive</span></tt> setting in the +server configuration. To disable the 120 second default, set +<tt class="docutils literal"><span class="pre">--ping-restart</span> 0</tt> on the client.</p> +<p>See the signals section below for more information on <code>SIGUSR1</code>.</p> +<p>Note that the behavior of <tt class="docutils literal">SIGUSR1</tt> can be modified by the +<tt class="docutils literal"><span class="pre">--persist-tun</span></tt>, <tt class="docutils literal"><span class="pre">--persist-key</span></tt>, <tt class="docutils literal"><span class="pre">--persist-local-ip</span></tt> and +<tt class="docutils literal"><span class="pre">--persist-remote-ip</span></tt> options.</p> +<p class="last">Also note that <tt class="docutils literal"><span class="pre">--ping-exit</span></tt> and <tt class="docutils literal"><span class="pre">--ping-restart</span></tt> are mutually +exclusive and cannot be used together.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--ping-timer-rem</span></kbd></td> +</tr> +<tr><td> </td><td>Run the <tt class="docutils literal"><span class="pre">--ping-exit</span></tt> / <tt class="docutils literal"><span class="pre">--ping-restart</span></tt> timer only if we have a +remote address. Use this option if you are starting the daemon in listen +mode (i.e. without an explicit <tt class="docutils literal"><span class="pre">--remote</span></tt> peer), and you don't want to +start clocking timeouts until a remote peer connects.</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--proto <var>p</var></span></kbd></td> +<td><p class="first">Use protocol <tt class="docutils literal">p</tt> for communicating with remote host. <tt class="docutils literal">p</tt> can be +<code>udp</code>, <code>tcp-client</code>, or <code>tcp-server</code>.</p> +<p>The default protocol is <code>udp</code> when <tt class="docutils literal"><span class="pre">--proto</span></tt> is not specified.</p> +<p>For UDP operation, <tt class="docutils literal"><span class="pre">--proto</span> udp</tt> should be specified on both peers.</p> +<p>For TCP operation, one peer must use <tt class="docutils literal"><span class="pre">--proto</span> <span class="pre">tcp-server</span></tt> and the +other must use <tt class="docutils literal"><span class="pre">--proto</span> <span class="pre">tcp-client</span></tt>. A peer started with +<code>tcp-server</code> will wait indefinitely for an incoming connection. A peer +started with <code>tcp-client</code> will attempt to connect, and if that fails, +will sleep for 5 seconds (adjustable via the <tt class="docutils literal"><span class="pre">--connect-retry</span></tt> option) +and try again infinite or up to N retries (adjustable via the +<tt class="docutils literal"><span class="pre">--connect-retry-max</span></tt> option). Both TCP client and server will +simulate a SIGUSR1 restart signal if either side resets the connection.</p> +<p>OpenVPN is designed to operate optimally over UDP, but TCP capability is +provided for situations where UDP cannot be used. In comparison with +UDP, TCP will usually be somewhat less efficient and less robust when +used over unreliable or congested networks.</p> +<p>This article outlines some of problems with tunneling IP over TCP: +<a class="reference external" href="http://sites.inka.de/sites/bigred/devel/tcp-tcp.html">http://sites.inka.de/sites/bigred/devel/tcp-tcp.html</a></p> +<p class="last">There are certain cases, however, where using TCP may be advantageous +from a security and robustness perspective, such as tunneling non-IP or +application-level UDP protocols, or tunneling protocols which don't +possess a built-in reliability layer.</p> +</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--port <var>port</var></span></kbd></td> +<td>TCP/UDP port number or port name for both local and remote (sets both +<tt class="docutils literal"><span class="pre">--lport</span></tt> and <tt class="docutils literal"><span class="pre">--rport</span></tt> options to given port). The current default +of 1194 represents the official IANA port number assignment for OpenVPN +and has been used since version 2.0-beta17. Previous versions used port +5000 as the default.</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--rport <var>port</var></span></kbd></td> +<td>Set TCP/UDP port number or name used by the <tt class="docutils literal"><span class="pre">--remote</span></tt> option. The +port can also be set directly using the <tt class="docutils literal"><span class="pre">--remote</span></tt> option.</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--replay-window <var>args</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Modify the replay protection sliding-window size and time window.</p> +<p>Valid syntax:</p> +<pre class="literal-block"> +replay-window n [t] +</pre> +<p>Use a replay protection sliding-window of size <strong>n</strong> and a time window +of <strong>t</strong> seconds.</p> +<p>By default <strong>n</strong> is 64 (the IPSec default) and <strong>t</strong> is 15 seconds.</p> +<p>This option is only relevant in UDP mode, i.e. when either <strong>--proto +udp</strong> is specified, or no <strong>--proto</strong> option is specified.</p> +<p>When OpenVPN tunnels IP packets over UDP, there is the possibility that +packets might be dropped or delivered out of order. Because OpenVPN, +like IPSec, is emulating the physical network layer, it will accept an +out-of-order packet sequence, and will deliver such packets in the same +order they were received to the TCP/IP protocol stack, provided they +satisfy several constraints.</p> +<ol class="loweralpha simple"> +<li>The packet cannot be a replay (unless <tt class="docutils literal"><span class="pre">--no-replay</span></tt> is +specified, which disables replay protection altogether).</li> +<li>If a packet arrives out of order, it will only be accepted if +the difference between its sequence number and the highest sequence +number received so far is less than <tt class="docutils literal">n</tt>.</li> +<li>If a packet arrives out of order, it will only be accepted if it +arrives no later than <tt class="docutils literal">t</tt> seconds after any packet containing a higher +sequence number.</li> +</ol> +<p>If you are using a network link with a large pipeline (meaning that the +product of bandwidth and latency is high), you may want to use a larger +value for <tt class="docutils literal">n</tt>. Satellite links in particular often require this.</p> +<p>If you run OpenVPN at <tt class="docutils literal"><span class="pre">--verb</span> 4</tt>, you will see the message +"Replay-window backtrack occurred [x]" every time the maximum sequence +number backtrack seen thus far increases. This can be used to calibrate +<tt class="docutils literal">n</tt>.</p> +<p>There is some controversy on the appropriate method of handling packet +reordering at the security layer.</p> +<p>Namely, to what extent should the security layer protect the +encapsulated protocol from attacks which masquerade as the kinds of +normal packet loss and reordering that occur over IP networks?</p> +<p>The IPSec and OpenVPN approach is to allow packet reordering within a +certain fixed sequence number window.</p> +<p>OpenVPN adds to the IPSec model by limiting the window size in time as +well as sequence space.</p> +<p>OpenVPN also adds TCP transport as an option (not offered by IPSec) in +which case OpenVPN can adopt a very strict attitude towards message +deletion and reordering: Don't allow it. Since TCP guarantees +reliability, any packet loss or reordering event can be assumed to be an +attack.</p> +<p>In this sense, it could be argued that TCP tunnel transport is preferred +when tunneling non-IP or UDP application protocols which might be +vulnerable to a message deletion or reordering attack which falls within +the normal operational parameters of IP networks.</p> +<p class="last">So I would make the statement that one should never tunnel a non-IP +protocol or UDP application protocol over UDP, if the protocol might be +vulnerable to a message deletion or reordering attack that falls within +the normal operating parameters of what is to be expected from the +physical IP layer. The problem is easily fixed by simply using TCP as +the VPN transport layer.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--replay-persist <var>file</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Persist replay-protection state across sessions using <tt class="docutils literal">file</tt> to save +and reload the state.</p> +<p>This option will strengthen protection against replay attacks, +especially when you are using OpenVPN in a dynamic context (such as with +<tt class="docutils literal"><span class="pre">--inetd</span></tt>) when OpenVPN sessions are frequently started and stopped.</p> +<p>This option will keep a disk copy of the current replay protection state +(i.e. the most recent packet timestamp and sequence number received from +the remote peer), so that if an OpenVPN session is stopped and +restarted, it will reject any replays of packets which were already +received by the prior session.</p> +<p class="last">This option only makes sense when replay protection is enabled (the +default) and you are using either <tt class="docutils literal"><span class="pre">--secret</span></tt> (shared-secret key mode) +or TLS mode with <tt class="docutils literal"><span class="pre">--tls-auth</span></tt>.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--socket-flags <var>flags</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Apply the given flags to the OpenVPN transport socket. Currently, only +<code>TCP_NODELAY</code> is supported.</p> +<p>The <code>TCP_NODELAY</code> socket flag is useful in TCP mode, and causes the +kernel to send tunnel packets immediately over the TCP connection without +trying to group several smaller packets into a larger packet. This can +result in a considerably improvement in latency.</p> +<p class="last">This option is pushable from server to client, and should be used on +both client and server for maximum effect.</p> +</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--tcp-nodelay</span></kbd></td> +<td><p class="first">This macro sets the <code>TCP_NODELAY</code> socket flag on the server as well +as pushes it to connecting clients. The <code>TCP_NODELAY</code> flag disables +the Nagle algorithm on TCP sockets causing packets to be transmitted +immediately with low latency, rather than waiting a short period of time +in order to aggregate several packets into a larger containing packet. +In VPN applications over TCP, <code>TCP_NODELAY</code> is generally a good +latency optimization.</p> +<p>The macro expands as follows:</p> +<pre class="last literal-block"> +if mode server: + socket-flags TCP_NODELAY + push "socket-flags TCP_NODELAY" +</pre> +</td></tr> +</tbody> +</table> +</div> +<div class="section" id="virtual-network-adapter-vpn-interface"> +<h2>Virtual Network Adapter (VPN interface)</h2> +<p>Options in this section relates to configuration of the virtual tun/tap +network interface, including setting the VPN IP address and network +routing.</p> +<table class="docutils option-list" frame="void" rules="none"> +<col class="option" /> +<col class="description" /> +<tbody valign="top"> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--bind-dev <var>device</var></span></kbd></td> +</tr> +<tr><td> </td><td>(Linux only) Set <tt class="docutils literal">device</tt> to bind the server socket to a +<a class="reference internal" href="#virtual-routing-and-forwarding">Virtual Routing and Forwarding</a> device</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--block-ipv6</span></kbd></td> +<td><p class="first">On the client, instead of sending IPv6 packets over the VPN tunnel, all +IPv6 packets are answered with an ICMPv6 no route host message. On the +server, all IPv6 packets from clients are answered with an ICMPv6 no +route to host message. This options is intended for cases when IPv6 +should be blocked and other options are not available. <tt class="docutils literal"><span class="pre">--block-ipv6</span></tt> +will use the remote IPv6 as source address of the ICMPv6 packets if set, +otherwise will use <code>fe80::7</code> as source address.</p> +<p>For this option to make sense you actually have to route traffic to the +tun interface. The following example config block would send all IPv6 +traffic to OpenVPN and answer all requests with no route to host, +effectively blocking IPv6 (to avoid IPv6 connections from dual-stacked +clients leaking around IPv4-only VPN services).</p> +<dl class="docutils"> +<dt><strong>Client config</strong></dt> +<dd><pre class="first last literal-block"> +--ifconfig-ipv6 fd15:53b6:dead::2/64 fd15:53b6:dead::1 +--redirect-gateway ipv6 +--block-ipv6 +</pre> +</dd> +<dt><strong>Server config</strong></dt> +<dd><p class="first">Push a "valid" ipv6 config to the client and block on the server</p> +<pre class="last literal-block"> +--push "ifconfig-ipv6 fd15:53b6:dead::2/64 fd15:53b6:dead::1" +--push "redirect-gateway ipv6" +--block-ipv6 +</pre> +</dd> +</dl> +<p class="last">Note: this option does not influence traffic sent from the server +towards the client (neither on the server nor on the client side). +This is not seen as necessary, as such traffic can be most easily +avoided by not configuring IPv6 on the server tun, or setting up a +server-side firewall rule.</p> +</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--dev <var>device</var></span></kbd></td> +<td><p class="first">TUN/TAP virtual network device which can be <code>tunX</code>, <code>tapX</code>, +<code>null</code> or an arbitrary name string (<code>X</code> can be omitted for +a dynamic device.)</p> +<p>See examples section below for an example on setting up a TUN device.</p> +<p>You must use either tun devices on both ends of the connection or tap +devices on both ends. You cannot mix them, as they represent different +underlying network layers:</p> +<dl class="docutils"> +<dt><code>tun</code></dt> +<dd>devices encapsulate IPv4 or IPv6 (OSI Layer 3)</dd> +<dt><code>tap</code></dt> +<dd>devices encapsulate Ethernet 802.3 (OSI Layer 2).</dd> +</dl> +<p>Valid syntaxes:</p> +<pre class="literal-block"> +dev tun2 +dev tap4 +dev ovpn +</pre> +<p class="last">When the device name starts with <code>tun</code> or <code>tap</code>, the device +type is extracted automatically. Otherwise the <tt class="docutils literal"><span class="pre">--dev-type</span></tt> option +needs to be added as well.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--dev-node <var>node</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Explicitly set the device node rather than using <code>/dev/net/tun</code>, +<code>/dev/tun</code>, <code>/dev/tap</code>, etc. If OpenVPN cannot figure out +whether <tt class="docutils literal">node</tt> is a TUN or TAP device based on the name, you should +also specify <tt class="docutils literal"><span class="pre">--dev-type</span> tun</tt> or <tt class="docutils literal"><span class="pre">--dev-type</span> tap</tt>.</p> +<p>Under Mac OS X this option can be used to specify the default tun +implementation. Using <tt class="docutils literal"><span class="pre">--dev-node</span> utun</tt> forces usage of the native +Darwin tun kernel support. Use <tt class="docutils literal"><span class="pre">--dev-node</span> utunN</tt> to select a specific +utun instance. To force using the <code>tun.kext</code> (<code>/dev/tunX</code>) +use <tt class="docutils literal"><span class="pre">--dev-node</span> tun</tt>. When not specifying a <tt class="docutils literal"><span class="pre">--dev-node</span></tt> option +openvpn will first try to open utun, and fall back to tun.kext.</p> +<p class="last">On Windows systems, select the TAP-Win32 adapter which is named <tt class="docutils literal">node</tt> +in the Network Connections Control Panel or the raw GUID of the adapter +enclosed by braces. The <tt class="docutils literal"><span class="pre">--show-adapters</span></tt> option under Windows can +also be used to enumerate all available TAP-Win32 adapters and will show +both the network connections control panel name and the GUID for each +TAP-Win32 adapter.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--dev-type <var>device-type</var></span></kbd></td> +</tr> +<tr><td> </td><td>Which device type are we using? <tt class="docutils literal"><span class="pre">device-type</span></tt> should be <code>tun</code> +(OSI Layer 3) or <code>tap</code> (OSI Layer 2). Use this option only if +the TUN/TAP device used with <tt class="docutils literal"><span class="pre">--dev</span></tt> does not begin with <code>tun</code> +or <code>tap</code>.</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--dhcp-option <var>args</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Set additional network parameters on supported platforms. May be specified +on the client or pushed from the server. On Windows these options are +handled by the <tt class="docutils literal"><span class="pre">tap-windows6</span></tt> driver by default or directly by OpenVPN +if dhcp is disabled or the <tt class="docutils literal">wintun</tt> driver is in use. The +<tt class="docutils literal">OpenVPN for Android</tt> client also handles them internally.</p> +<p>On all other platforms these options are only saved in the client's +environment under the name <code>foreign_options_{n}</code> before the +<tt class="docutils literal"><span class="pre">--up</span></tt> script is called. A plugin or an <tt class="docutils literal"><span class="pre">--up</span></tt> script must be used to +pick up and interpret these as required. Many Linux distributions include +such scripts and some third-party user interfaces such as tunnelblick also +come with scripts that process these options.</p> +<p>Valid syntax:</p> +<pre class="literal-block"> +dhcp-options type [parm] +</pre> +<dl class="last docutils"> +<dt><code>DOMAIN</code> <tt class="docutils literal">name</tt></dt> +<dd>Set Connection-specific DNS Suffix to <code>name</code>.</dd> +<dt><code>ADAPTER_DOMAIN_SUFFIX</code> <tt class="docutils literal">name</tt></dt> +<dd>Alias to <code>DOMAIN</code>. This is a compatibility option, it +should not be used in new deployments.</dd> +<dt><code>DOMAIN-SEARCH</code> <tt class="docutils literal">name</tt></dt> +<dd>Add <code>name</code> to the domain search list. +Repeat this option to add more entries. Up to +10 domains are supported.</dd> +<dt><code>DNS</code> <tt class="docutils literal">address</tt></dt> +<dd><p class="first">Set primary domain name server IPv4 or IPv6 address. +Repeat this option to set secondary DNS server addresses.</p> +<p class="last">Note: DNS IPv6 servers are currently set using netsh (the existing +DHCP code can only do IPv4 DHCP, and that protocol only permits +IPv4 addresses anywhere). The option will be put into the +environment, so an <tt class="docutils literal"><span class="pre">--up</span></tt> script could act upon it if needed.</p> +</dd> +<dt><code>WINS</code> <tt class="docutils literal">address</tt></dt> +<dd>Set primary WINS server address (NetBIOS over TCP/IP Name Server). +Repeat this option to set secondary WINS server addresses.</dd> +<dt><code>NBDD</code> <tt class="docutils literal">address</tt></dt> +<dd>Set primary NBDD server address (NetBIOS over TCP/IP Datagram +Distribution Server). Repeat this option to set secondary NBDD +server addresses.</dd> +<dt><code>NTP</code> <tt class="docutils literal">address</tt></dt> +<dd>Set primary NTP server address (Network Time Protocol). +Repeat this option to set secondary NTP server addresses.</dd> +<dt><code>NBT</code> <tt class="docutils literal">type</tt></dt> +<dd><p class="first">Set NetBIOS over TCP/IP Node type. Possible options:</p> +<dl class="last docutils"> +<dt><code>1</code></dt> +<dd>b-node (broadcasts)</dd> +<dt><code>2</code></dt> +<dd>p-node (point-to-point name queries to a WINS server)</dd> +<dt><code>4</code></dt> +<dd>m-node (broadcast then query name server)</dd> +<dt><code>8</code></dt> +<dd>h-node (query name server, then broadcast).</dd> +</dl> +</dd> +<dt><code>NBS</code> <tt class="docutils literal"><span class="pre">scope-id</span></tt></dt> +<dd>Set NetBIOS over TCP/IP Scope. A NetBIOS Scope ID provides an +extended naming service for the NetBIOS over TCP/IP (Known as NBT) +module. The primary purpose of a NetBIOS scope ID is to isolate +NetBIOS traffic on a single network to only those nodes with the +same NetBIOS scope ID. The NetBIOS scope ID is a character string +that is appended to the NetBIOS name. The NetBIOS scope ID on two +hosts must match, or the two hosts will not be able to communicate. +The NetBIOS Scope ID also allows computers to use the same computer +name, as they have different scope IDs. The Scope ID becomes a part +of the NetBIOS name, making the name unique. (This description of +NetBIOS scopes courtesy of <a class="reference external" href="mailto:NeonSurge@abyss.com">NeonSurge@abyss.com</a>)</dd> +<dt><code>DISABLE-NBT</code></dt> +<dd>Disable Netbios-over-TCP/IP.</dd> +</dl> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--ifconfig <var>args</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Set TUN/TAP adapter parameters. It requires the <em>IP address</em> of the local +VPN endpoint. For TUN devices in point-to-point mode, the next argument +must be the VPN IP address of the remote VPN endpoint. For TAP devices, +or TUN devices used with <tt class="docutils literal"><span class="pre">--topology</span> subnet</tt>, the second argument +is the subnet mask of the virtual network segment which is being created +or connected to.</p> +<p>For TUN devices, which facilitate virtual point-to-point IP connections +(when used in <tt class="docutils literal"><span class="pre">--topology</span> net30</tt> or <tt class="docutils literal">p2p</tt> mode), the proper usage of +<tt class="docutils literal"><span class="pre">--ifconfig</span></tt> is to use two private IP addresses which are not a member +of any existing subnet which is in use. The IP addresses may be +consecutive and should have their order reversed on the remote peer. +After the VPN is established, by pinging <tt class="docutils literal">rn</tt>, you will be pinging +across the VPN.</p> +<p>For TAP devices, which provide the ability to create virtual ethernet +segments, or TUN devices in <tt class="docutils literal"><span class="pre">--topology</span> subnet</tt> mode (which create +virtual "multipoint networks"), <tt class="docutils literal"><span class="pre">--ifconfig</span></tt> is used to set an IP +address and subnet mask just as a physical ethernet adapter would be +similarly configured. If you are attempting to connect to a remote +ethernet bridge, the IP address and subnet should be set to values which +would be valid on the the bridged ethernet segment (note also that DHCP +can be used for the same purpose).</p> +<p>This option, while primarily a proxy for the <tt class="docutils literal">ifconfig</tt>(8) command, +is designed to simplify TUN/TAP tunnel configuration by providing a +standard interface to the different ifconfig implementations on +different platforms.</p> +<p><tt class="docutils literal"><span class="pre">--ifconfig</span></tt> parameters which are IP addresses can also be specified +as a DNS or /etc/hosts file resolvable name.</p> +<p>For TAP devices, <tt class="docutils literal"><span class="pre">--ifconfig</span></tt> should not be used if the TAP interface +will be getting an IP address lease from a DHCP server.</p> +<p>Examples:</p> +<pre class="last literal-block"> +# tun device in net30/p2p mode +ifconfig 10.8.0.2 10.8.0.1 + +# tun/tap device in subnet mode +ifconfig 10.8.0.2 255.255.255.0 +</pre> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--ifconfig-ipv6 <var>args</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Configure an IPv6 address on the <em>tun</em> device.</p> +<p>Valid syntax:</p> +<pre class="literal-block"> +ifconfig-ipv6 ipv6addr/bits [ipv6remote] +</pre> +<p>The <tt class="docutils literal">ipv6addr/bits</tt> argument is the IPv6 address to use. The +second parameter is used as route target for <tt class="docutils literal"><span class="pre">--route-ipv6</span></tt> if no +gateway is specified.</p> +<p class="last">The <tt class="docutils literal"><span class="pre">--topology</span></tt> option has no influence with <tt class="docutils literal"><span class="pre">--ifconfig-ipv6</span></tt></p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--ifconfig-noexec</span></kbd></td> +</tr> +<tr><td> </td><td>Don't actually execute ifconfig/netsh commands, instead pass +<tt class="docutils literal"><span class="pre">--ifconfig</span></tt> parameters to scripts using environmental variables.</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--ifconfig-nowarn</span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Don't output an options consistency check warning if the <tt class="docutils literal"><span class="pre">--ifconfig</span></tt> +option on this side of the connection doesn't match the remote side. +This is useful when you want to retain the overall benefits of the +options consistency check (also see <tt class="docutils literal"><span class="pre">--disable-occ</span></tt> option) while only +disabling the ifconfig component of the check.</p> +<p>For example, if you have a configuration where the local host uses +<tt class="docutils literal"><span class="pre">--ifconfig</span></tt> but the remote host does not, use <tt class="docutils literal"><span class="pre">--ifconfig-nowarn</span></tt> +on the local host.</p> +<p class="last">This option will also silence warnings about potential address conflicts +which occasionally annoy more experienced users by triggering "false +positive" warnings.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--lladdr <var>address</var></span></kbd></td> +</tr> +<tr><td> </td><td>Specify the link layer address, more commonly known as the MAC address. +Only applied to TAP devices.</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--persist-tun</span></kbd></td> +<td><p class="first">Don't close and reopen TUN/TAP device or run up/down scripts across +<code>SIGUSR1</code> or <tt class="docutils literal"><span class="pre">--ping-restart</span></tt> restarts.</p> +<p class="last"><code>SIGUSR1</code> is a restart signal similar to <code>SIGHUP</code>, but which +offers finer-grained control over reset options.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--redirect-gateway <var>flags</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Automatically execute routing commands to cause all outgoing IP traffic +to be redirected over the VPN. This is a client-side option.</p> +<p>This option performs three steps:</p> +<ol class="arabic simple"> +<li>Create a static route for the <tt class="docutils literal"><span class="pre">--remote</span></tt> address which +forwards to the pre-existing default gateway. This is done so that +<tt class="docutils literal">(3)</tt> will not create a routing loop.</li> +<li>Delete the default gateway route.</li> +<li>Set the new default gateway to be the VPN endpoint address +(derived either from <tt class="docutils literal"><span class="pre">--route-gateway</span></tt> or the second parameter to +<tt class="docutils literal"><span class="pre">--ifconfig</span></tt> when <tt class="docutils literal"><span class="pre">--dev</span> tun</tt> is specified).</li> +</ol> +<p>When the tunnel is torn down, all of the above steps are reversed so +that the original default route is restored.</p> +<p>Option flags:</p> +<dl class="last docutils"> +<dt><code>local</code></dt> +<dd>Add the <code>local</code> flag if both OpenVPN peers are directly +connected via a common subnet, such as with wireless. The +<code>local</code> flag will cause step <tt class="docutils literal">(1)</tt> above to be omitted.</dd> +<dt><code>autolocal</code></dt> +<dd>Try to automatically determine whether to enable <code>local</code> +flag above.</dd> +<dt><code>def1</code></dt> +<dd>Use this flag to override the default gateway by using +<code>0.0.0.0/1</code> and <code>128.0.0.0/1</code> rather than +<code>0.0.0.0/0</code>. This has the benefit of overriding but not +wiping out the original default gateway.</dd> +<dt><code>bypass-dhcp</code></dt> +<dd>Add a direct route to the DHCP server (if it is non-local) which +bypasses the tunnel (Available on Windows clients, may not be +available on non-Windows clients).</dd> +<dt><code>bypass-dns</code></dt> +<dd>Add a direct route to the DNS server(s) (if they are non-local) +which bypasses the tunnel (Available on Windows clients, may +not be available on non-Windows clients).</dd> +<dt><code>block-local</code></dt> +<dd>Block access to local LAN when the tunnel is active, except for +the LAN gateway itself. This is accomplished by routing the local +LAN (except for the LAN gateway address) into the tunnel.</dd> +<dt><code>ipv6</code></dt> +<dd>Redirect IPv6 routing into the tunnel. This works similar to +the <code>def1</code> flag, that is, more specific IPv6 routes are added +(<code>2000::/4</code>, <code>3000::/4</code>), covering the whole IPv6 +unicast space.</dd> +<dt><code>!ipv4</code></dt> +<dd>Do not redirect IPv4 traffic - typically used in the flag pair +<code>ipv6 !ipv4</code> to redirect IPv6-only.</dd> +</dl> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--redirect-private <var>flags</var></span></kbd></td> +</tr> +<tr><td> </td><td>Like <tt class="docutils literal"><span class="pre">--redirect-gateway</span></tt>, but omit actually changing the default gateway. +Useful when pushing private subnets.</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--route <var>args</var></span></kbd></td> +<td><p class="first">Add route to routing table after connection is established. Multiple +routes can be specified. Routes will be automatically torn down in +reverse order prior to TUN/TAP device close.</p> +<p>Valid syntaxes:</p> +<pre class="literal-block"> +route network/IP +route network/IP netmask +route network/IP netmask gateway +route network/IP netmask gateway metric +</pre> +<p>This option is intended as a convenience proxy for the <tt class="docutils literal">route</tt>(8) +shell command, while at the same time providing portable semantics +across OpenVPN's platform space.</p> +<dl class="docutils"> +<dt><tt class="docutils literal">netmask</tt></dt> +<dd>defaults to <code>255.255.255.255</code> when not given</dd> +<dt><tt class="docutils literal">gateway</tt></dt> +<dd>default taken from <tt class="docutils literal"><span class="pre">--route-gateway</span></tt> or the second +parameter to <tt class="docutils literal"><span class="pre">--ifconfig</span></tt> when <tt class="docutils literal"><span class="pre">--dev</span> tun</tt> is specified.</dd> +<dt><tt class="docutils literal">metric</tt></dt> +<dd>default taken from <tt class="docutils literal"><span class="pre">--route-metric</span></tt> if set, otherwise <code>0</code>.</dd> +</dl> +<p>The default can be specified by leaving an option blank or setting it to +<code>default</code>.</p> +<p>The <tt class="docutils literal">network</tt> and <tt class="docutils literal">gateway</tt> parameters can also be specified as a +DNS or <code>/etc/hosts</code> file resolvable name, or as one of three special +keywords:</p> +<dl class="last docutils"> +<dt><code>vpn_gateway</code></dt> +<dd>The remote VPN endpoint address (derived either from +<tt class="docutils literal"><span class="pre">--route-gateway</span></tt> or the second parameter to <tt class="docutils literal"><span class="pre">--ifconfig</span></tt> +when <tt class="docutils literal"><span class="pre">--dev</span> tun</tt> is specified).</dd> +<dt><code>net_gateway</code></dt> +<dd>The pre-existing IP default gateway, read from the +routing table (not supported on all OSes).</dd> +<dt><code>remote_host</code></dt> +<dd>The <tt class="docutils literal"><span class="pre">--remote</span></tt> address if OpenVPN is being run in +client mode, and is undefined in server mode.</dd> +</dl> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--route-delay <var>args</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Valid syntaxes:</p> +<pre class="literal-block"> +route-delay +route-delay n +route-delay n m +</pre> +<p>Delay <tt class="docutils literal">n</tt> seconds (default <code>0</code>) after connection establishment, +before adding routes. If <tt class="docutils literal">n</tt> is <code>0</code>, routes will be added +immediately upon connection establishment. If <tt class="docutils literal"><span class="pre">--route-delay</span></tt> is +omitted, routes will be added immediately after TUN/TAP device open and +<tt class="docutils literal"><span class="pre">--up</span></tt> script execution, before any <tt class="docutils literal"><span class="pre">--user</span></tt> or <tt class="docutils literal"><span class="pre">--group</span></tt> privilege +downgrade (or <tt class="docutils literal"><span class="pre">--chroot</span></tt> execution.)</p> +<p>This option is designed to be useful in scenarios where DHCP is used to +set tap adapter addresses. The delay will give the DHCP handshake time +to complete before routes are added.</p> +<p class="last">On Windows, <tt class="docutils literal"><span class="pre">--route-delay</span></tt> tries to be more intelligent by waiting +<tt class="docutils literal">w</tt> seconds (default <code>30</code> by default) for the TAP-Win32 adapter +to come up before adding routes.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--route-ipv6 <var>args</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Setup IPv6 routing in the system to send the specified IPv6 network into +OpenVPN's <em>tun</em>.</p> +<p>Valid syntax:</p> +<pre class="literal-block"> +route-ipv6 ipv6addr/bits [gateway] [metric] +</pre> +<p class="last">The gateway parameter is only used for IPv6 routes across <em>tap</em> devices, +and if missing, the <tt class="docutils literal">ipv6remote</tt> field from <tt class="docutils literal"><span class="pre">--ifconfig-ipv6</span></tt> or +<tt class="docutils literal"><span class="pre">--route-ipv6-gateway</span></tt> is used.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--route-gateway <var>arg</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Specify a default <em>gateway</em> for use with <tt class="docutils literal"><span class="pre">--route</span></tt>.</p> +<p>If <code>dhcp</code> is specified as the parameter, the gateway address will +be extracted from a DHCP negotiation with the OpenVPN server-side LAN.</p> +<p>Valid syntaxes:</p> +<pre class="last literal-block"> +route-gateway gateway +route-gateway dhcp +</pre> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--route-ipv6-gateway <var>gw</var></span></kbd></td> +</tr> +<tr><td> </td><td>Specify a default gateway <tt class="docutils literal">gw</tt> for use with <tt class="docutils literal"><span class="pre">--route-ipv6</span></tt>.</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--route-metric <var>m</var></span></kbd></td> +</tr> +<tr><td> </td><td>Specify a default metric <tt class="docutils literal">m</tt> for use with <tt class="docutils literal"><span class="pre">--route</span></tt>.</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--route-noexec</span></kbd></td> +<td>Don't add or remove routes automatically. Instead pass routes to +<tt class="docutils literal"><span class="pre">--route-up</span></tt> script using environmental variables.</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--route-nopull</span></kbd></td> +<td><p class="first">When used with <tt class="docutils literal"><span class="pre">--client</span></tt> or <tt class="docutils literal"><span class="pre">--pull</span></tt>, accept options pushed by +server EXCEPT for routes, block-outside-dns and dhcp options like DNS +servers.</p> +<p class="last">When used on the client, this option effectively bars the server from +adding routes to the client's routing table, however note that this +option still allows the server to set the TCP/IP properties of the +client's TUN/TAP interface.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--topology <var>mode</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Configure virtual addressing topology when running in <tt class="docutils literal"><span class="pre">--dev</span> tun</tt> +mode. This directive has no meaning in <tt class="docutils literal"><span class="pre">--dev</span> tap</tt> mode, which always +uses a <code>subnet</code> topology.</p> +<p>If you set this directive on the server, the <tt class="docutils literal"><span class="pre">--server</span></tt> and +<tt class="docutils literal"><span class="pre">--server-bridge</span></tt> directives will automatically push your chosen +topology setting to clients as well. This directive can also be manually +pushed to clients. Like the <tt class="docutils literal"><span class="pre">--dev</span></tt> directive, this directive must +always be compatible between client and server.</p> +<p><tt class="docutils literal">mode</tt> can be one of:</p> +<dl class="docutils"> +<dt><code>net30</code></dt> +<dd>Use a point-to-point topology, by allocating one /30 subnet +per client. This is designed to allow point-to-point semantics when some +or all of the connecting clients might be Windows systems. This is the +default on OpenVPN 2.0.</dd> +<dt><code>p2p</code></dt> +<dd>Use a point-to-point topology where the remote endpoint of +the client's tun interface always points to the local endpoint of the +server's tun interface. This mode allocates a single IP address per +connecting client. Only use when none of the connecting clients are +Windows systems.</dd> +<dt><code>subnet</code></dt> +<dd>Use a subnet rather than a point-to-point topology by +configuring the tun interface with a local IP address and subnet mask, +similar to the topology used in <tt class="docutils literal"><span class="pre">--dev</span> tap</tt> and ethernet bridging +mode. This mode allocates a single IP address per connecting client and +works on Windows as well. Only available when server and clients are +OpenVPN 2.1 or higher, or OpenVPN 2.0.x which has been manually patched +with the <tt class="docutils literal"><span class="pre">--topology</span></tt> directive code. When used on Windows, requires +version 8.2 or higher of the TAP-Win32 driver. When used on *nix, +requires that the tun driver supports an <tt class="docutils literal">ifconfig</tt>(8) command which +sets a subnet instead of a remote endpoint IP address.</dd> +</dl> +<p class="last"><em>Note:</em> Using <tt class="docutils literal"><span class="pre">--topology</span> subnet</tt> changes the interpretation of the +arguments of <tt class="docutils literal"><span class="pre">--ifconfig</span></tt> to mean "address netmask", no longer "local +remote".</p> +</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--tun-mtu <var>n</var></span></kbd></td> +<td><p class="first">Take the TUN device MTU to be <strong>n</strong> and derive the link MTU from it +(default <code>1500</code>). In most cases, you will probably want to leave +this parameter set to its default value.</p> +<p>The MTU (Maximum Transmission Units) is the maximum datagram size in +bytes that can be sent unfragmented over a particular network path. +OpenVPN requires that packets on the control and data channels be sent +unfragmented.</p> +<p>MTU problems often manifest themselves as connections which hang during +periods of active usage.</p> +<p class="last">It's best to use the <tt class="docutils literal"><span class="pre">--fragment</span></tt> and/or <tt class="docutils literal"><span class="pre">--mssfix</span></tt> options to deal +with MTU sizing issues.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--tun-mtu-extra <var>n</var></span></kbd></td> +</tr> +<tr><td> </td><td>Assume that the TUN/TAP device might return as many as <tt class="docutils literal">n</tt> bytes more +than the <tt class="docutils literal"><span class="pre">--tun-mtu</span></tt> size on read. This parameter defaults to 0, which +is sufficient for most TUN devices. TAP devices may introduce additional +overhead in excess of the MTU size, and a setting of 32 is the default +when TAP devices are used. This parameter only controls internal OpenVPN +buffer sizing, so there is no transmission overhead associated with +using a larger value.</td></tr> +</tbody> +</table> +</div> +<div class="section" id="tun-tap-standalone-operations"> +<h2>TUN/TAP standalone operations</h2> +<p>These two standalone operations will require <tt class="docutils literal"><span class="pre">--dev</span></tt> and optionally +<tt class="docutils literal"><span class="pre">--user</span></tt> and/or <tt class="docutils literal"><span class="pre">--group</span></tt>.</p> +<table class="docutils option-list" frame="void" rules="none"> +<col class="option" /> +<col class="description" /> +<tbody valign="top"> +<tr><td class="option-group"> +<kbd><span class="option">--mktun</span></kbd></td> +<td><p class="first">(Standalone) Create a persistent tunnel on platforms which support them +such as Linux. Normally TUN/TAP tunnels exist only for the period of +time that an application has them open. This option takes advantage of +the TUN/TAP driver's ability to build persistent tunnels that live +through multiple instantiations of OpenVPN and die only when they are +deleted or the machine is rebooted.</p> +<p>One of the advantages of persistent tunnels is that they eliminate the +need for separate <tt class="docutils literal"><span class="pre">--up</span></tt> and <tt class="docutils literal"><span class="pre">--down</span></tt> scripts to run the appropriate +<tt class="docutils literal">ifconfig</tt>(8) and <tt class="docutils literal">route</tt>(8) commands. These commands can be +placed in the the same shell script which starts or terminates an +OpenVPN session.</p> +<p>Another advantage is that open connections through the TUN/TAP-based +tunnel will not be reset if the OpenVPN peer restarts. This can be +useful to provide uninterrupted connectivity through the tunnel in the +event of a DHCP reset of the peer's public IP address (see the +<tt class="docutils literal"><span class="pre">--ipchange</span></tt> option above).</p> +<p>One disadvantage of persistent tunnels is that it is harder to +automatically configure their MTU value (see <tt class="docutils literal"><span class="pre">--link-mtu</span></tt> and +<tt class="docutils literal"><span class="pre">--tun-mtu</span></tt> above).</p> +<p class="last">On some platforms such as Windows, TAP-Win32 tunnels are persistent by +default.</p> +</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--rmtun</span></kbd></td> +<td>(Standalone) Remove a persistent tunnel.</td></tr> +</tbody> +</table> +</div> +<div class="section" id="virtual-routing-and-forwarding"> +<h2>Virtual Routing and Forwarding</h2> +<p>Options in this section relates to configuration of virtual routing and +forwarding in combination with the underlying operating system.</p> +<p>As of today this is only supported on Linux, a kernel >= 4.9 is +recommended.</p> +<p>This could come in handy when for example the external network should be +only used as a means to connect to some VPN endpoints and all regular +traffic should only be routed through any tunnel(s). This could be +achieved by setting up a VRF and configuring the interface connected to +the external network to be part of the VRF. The examples below will cover +this setup.</p> +<p>Another option would be to put the tun/tap interface into a VRF. This could +be done by an up-script which uses the <code>ip link set</code> command shown +below.</p> +<div class="section" id="vrf-setup-with-iproute2"> +<h3>VRF setup with iproute2</h3> +<p>Create VRF <code>vrf_external</code> and map it to routing table <code>1023</code></p> +<pre class="literal-block"> +ip link add vrf_external type vrf table 1023 +</pre> +<p>Move <code>eth0</code> into <code>vrf_external</code></p> +<pre class="literal-block"> +ip link set master vrf_external dev eth0 +</pre> +<p>Any prefixes configured on <code>eth0</code> will be moved from the :code`main` +routing table into routing table <cite>1023</cite></p> +</div> +<div class="section" id="vrf-setup-with-ifupdown"> +<h3>VRF setup with ifupdown</h3> +<p>For Debian based Distributions <code>ifupdown2</code> provides an almost drop-in +replacement for <code>ifupdown</code> including VRFs and other features. +A configuration for an interface <code>eth0</code> being part of VRF +code:<cite>vrf_external</cite> could look like this:</p> +<pre class="literal-block"> +auto eth0 +iface eth0 + address 192.0.2.42/24 + address 2001:db8:08:15::42/64 + gateway 192.0.2.1 + gateway 2001:db8:08:15::1 + vrf vrf_external + +auto vrf_external +iface vrf_external + vrf-table 1023 +</pre> +</div> +<div class="section" id="openvpn-configuration"> +<h3>OpenVPN configuration</h3> +<p>The OpenVPN configuration needs to contain this line:</p> +<pre class="literal-block"> +bind-dev vrf_external +</pre> +</div> +<div class="section" id="further-reading"> +<h3>Further reading</h3> +<p>Wikipedia has nice page one VRFs: <a class="reference external" href="https://en.wikipedia.org/wiki/Virtual_routing_and_forwarding">https://en.wikipedia.org/wiki/Virtual_routing_and_forwarding</a></p> +<p>This talk from the Network Track of FrOSCon 2018 provides an overview about +advanced layer 2 and layer 3 features of Linux</p> +<blockquote> +<ul class="simple"> +<li>Slides: <a class="reference external" href="https://www.slideshare.net/BarbarossaTM/l2l3-fr-fortgeschrittene-helle-und-dunkle-magie-im-linuxnetzwerkstack">https://www.slideshare.net/BarbarossaTM/l2l3-fr-fortgeschrittene-helle-und-dunkle-magie-im-linuxnetzwerkstack</a></li> +<li>Video (german): <a class="reference external" href="https://media.ccc.de/v/froscon2018-2247-l2_l3_fur_fortgeschrittene_-_helle_und_dunkle_magie_im_linux-netzwerkstack">https://media.ccc.de/v/froscon2018-2247-l2_l3_fur_fortgeschrittene_-_helle_und_dunkle_magie_im_linux-netzwerkstack</a></li> +</ul> +</blockquote> +</div> +</div> +</div> +<div class="section" id="scripting-integration"> +<h1>SCRIPTING INTEGRATION</h1> +<p>OpenVPN can execute external scripts in various phases of the lifetime of +the OpenVPN process.</p> +<div class="section" id="script-order-of-execution"> +<h2>Script Order of Execution</h2> +<ol class="arabic"> +<li><p class="first"><tt class="docutils literal"><span class="pre">--up</span></tt></p> +<p>Executed after TCP/UDP socket bind and TUN/TAP open.</p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">--tls-verify</span></tt></p> +<p>Executed when we have a still untrusted remote peer.</p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">--ipchange</span></tt></p> +<p>Executed after connection authentication, or remote IP address change.</p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">--client-connect</span></tt></p> +<p>Executed in <strong>--mode server</strong> mode immediately after client +authentication.</p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">--route-up</span></tt></p> +<p>Executed after connection authentication, either immediately after, or +some number of seconds after as defined by the <strong>--route-delay</strong> option.</p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">--route-pre-down</span></tt></p> +<p>Executed right before the routes are removed.</p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">--client-disconnect</span></tt></p> +<p>Executed in <tt class="docutils literal"><span class="pre">--mode</span> server</tt> mode on client instance shutdown.</p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">--down</span></tt></p> +<p>Executed after TCP/UDP and TUN/TAP close.</p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">--learn-address</span></tt></p> +<p>Executed in <tt class="docutils literal"><span class="pre">--mode</span> server</tt> mode whenever an IPv4 address/route or MAC +address is added to OpenVPN's internal routing table.</p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">--auth-user-pass-verify</span></tt></p> +<p>Executed in <tt class="docutils literal"><span class="pre">--mode</span> server</tt> mode on new client connections, when the +client is still untrusted.</p> +</li> +</ol> +</div> +<div class="section" id="script-hooks"> +<h2>SCRIPT HOOKS</h2> +<table class="docutils option-list" frame="void" rules="none"> +<col class="option" /> +<col class="description" /> +<tbody valign="top"> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--auth-user-pass-verify <var>args</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Require the client to provide a username/password (possibly in addition +to a client certificate) for authentication.</p> +<p>Valid syntax:</p> +<pre class="literal-block"> +auth-user-pass-verify cmd method +</pre> +<p>OpenVPN will run command <tt class="docutils literal">cmd</tt> to validate the username/password +provided by the client.</p> +<p><tt class="docutils literal">cmd</tt> consists of a path to a script (or executable program), optionally +followed by arguments. The path and arguments may be single- or +double-quoted and/or escaped using a backslash, and should be separated +by one or more spaces.</p> +<p>If <tt class="docutils literal">method</tt> is set to <code>via-env</code>, OpenVPN will call <tt class="docutils literal">script</tt> +with the environmental variables <code>username</code> and <code>password</code> +set to the username/password strings provided by the client. <em>Beware</em> +that this method is insecure on some platforms which make the environment +of a process publicly visible to other unprivileged processes.</p> +<p>If <tt class="docutils literal">method</tt> is set to <code>via-file</code>, OpenVPN will write the username +and password to the first two lines of a temporary file. The filename +will be passed as an argument to <tt class="docutils literal">script</tt>, and the file will be +automatically deleted by OpenVPN after the script returns. The location +of the temporary file is controlled by the <tt class="docutils literal"><span class="pre">--tmp-dir</span></tt> option, and +will default to the current directory if unspecified. For security, +consider setting <tt class="docutils literal"><span class="pre">--tmp-dir</span></tt> to a volatile storage medium such as +<code>/dev/shm</code> (if available) to prevent the username/password file +from touching the hard drive.</p> +<p>The script should examine the username and password, returning a success +exit code (<code>0</code>) if the client's authentication request is to be +accepted, or a failure code (<code>1</code>) to reject the client.</p> +<p>This directive is designed to enable a plugin-style interface for +extending OpenVPN's authentication capabilities.</p> +<p>To protect against a client passing a maliciously formed username or +password string, the username string must consist only of these +characters: alphanumeric, underbar ('<code>_</code>'), dash ('<code>-</code>'), +dot ('<code>.</code>'), or at ('<code>@</code>'). The password string can consist +of any printable characters except for CR or LF. Any illegal characters +in either the username or password string will be converted to +underbar ('<code>_</code>').</p> +<p>Care must be taken by any user-defined scripts to avoid creating a +security vulnerability in the way that these strings are handled. Never +use these strings in such a way that they might be escaped or evaluated +by a shell interpreter.</p> +<p class="last">For a sample script that performs PAM authentication, see +<code>sample-scripts/auth-pam.pl</code> in the OpenVPN source distribution.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--client-connect <var>cmd</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Run command <tt class="docutils literal">cmd</tt> on client connection.</p> +<p><tt class="docutils literal">cmd</tt> consists of a path to a script (or executable program), optionally +followed by arguments. The path and arguments may be single- or +double-quoted and/or escaped using a backslash, and should be separated +by one or more spaces.</p> +<p>The command is passed the common name and IP address of the +just-authenticated client as environmental variables (see environmental +variable section below). The command is also passed the pathname of a +freshly created temporary file as the last argument (after any arguments +specified in <tt class="docutils literal">cmd</tt> ), to be used by the command to pass dynamically +generated config file directives back to OpenVPN.</p> +<p>If the script wants to generate a dynamic config file to be applied on +the server when the client connects, it should write it to the file +named by the last argument.</p> +<p>See the <tt class="docutils literal"><span class="pre">--client-config-dir</span></tt> option below for options which can be +legally used in a dynamically generated config file.</p> +<p>Note that the return value of <tt class="docutils literal">script</tt> is significant. If <tt class="docutils literal">script</tt> +returns a non-zero error status, it will cause the client to be +disconnected.</p> +<p class="last">If a <tt class="docutils literal"><span class="pre">--client-connect</span></tt> wants to defer the generating of the +configuration then the script needs to use the +<code>client_connect_deferred_file</code> and +<code>client_connect_config_file</code> environment variables, and write +status accordingly into these files. See the <a class="reference internal" href="#environmental-variables">Environmental Variables</a> +section for more details.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--client-disconnect <var>cmd</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Like <tt class="docutils literal"><span class="pre">--client-connect</span></tt> but called on client instance shutdown. Will +not be called unless the <tt class="docutils literal"><span class="pre">--client-connect</span></tt> script and plugins (if +defined) were previously called on this instance with successful (0) +status returns.</p> +<p>The exception to this rule is if the <tt class="docutils literal"><span class="pre">--client-disconnect</span></tt> command or +plugins are cascaded, and at least one client-connect function +succeeded, then ALL of the client-disconnect functions for scripts and +plugins will be called on client instance object deletion, even in cases +where some of the related client-connect functions returned an error +status.</p> +<p class="last">The <tt class="docutils literal"><span class="pre">--client-disconnect</span></tt> command is not passed any extra arguments +(only those arguments specified in cmd, if any).</p> +</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--down <var>cmd</var></span></kbd></td> +<td><p class="first">Run command <tt class="docutils literal">cmd</tt> after TUN/TAP device close (post <tt class="docutils literal"><span class="pre">--user</span></tt> UID +change and/or <tt class="docutils literal"><span class="pre">--chroot</span></tt> ). <tt class="docutils literal">cmd</tt> consists of a path to script (or +executable program), optionally followed by arguments. The path and +arguments may be single- or double-quoted and/or escaped using a +backslash, and should be separated by one or more spaces.</p> +<p>Called with the same parameters and environmental variables as the +<tt class="docutils literal"><span class="pre">--up</span></tt> option above.</p> +<p class="last">Note that if you reduce privileges by using <tt class="docutils literal"><span class="pre">--user</span></tt> and/or +<tt class="docutils literal"><span class="pre">--group</span></tt>, your <tt class="docutils literal"><span class="pre">--down</span></tt> script will also run at reduced privilege.</p> +</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--down-pre</span></kbd></td> +<td>Call <tt class="docutils literal"><span class="pre">--down</span></tt> cmd/script before, rather than after, TUN/TAP close.</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--ipchange <var>cmd</var></span></kbd></td> +<td><p class="first">Run command <tt class="docutils literal">cmd</tt> when our remote ip-address is initially +authenticated or changes.</p> +<p><tt class="docutils literal">cmd</tt> consists of a path to a script (or executable program), optionally +followed by arguments. The path and arguments may be single- or +double-quoted and/or escaped using a backslash, and should be separated +by one or more spaces.</p> +<p>When <tt class="docutils literal">cmd</tt> is executed two arguments are appended after any arguments +specified in <tt class="docutils literal">cmd</tt> , as follows:</p> +<pre class="literal-block"> +cmd ip address port number +</pre> +<p>Don't use <tt class="docutils literal"><span class="pre">--ipchange</span></tt> in <tt class="docutils literal"><span class="pre">--mode</span> server</tt> mode. Use a +<tt class="docutils literal"><span class="pre">--client-connect</span></tt> script instead.</p> +<p>See the <a class="reference internal" href="#environmental-variables">Environmental Variables</a> section below for additional +parameters passed as environmental variables.</p> +<p>If you are running in a dynamic IP address environment where the IP +addresses of either peer could change without notice, you can use this +script, for example, to edit the <code>/etc/hosts</code> file with the current +address of the peer. The script will be run every time the remote peer +changes its IP address.</p> +<p class="last">Similarly if <em>our</em> IP address changes due to DHCP, we should configure +our IP address change script (see man page for <tt class="docutils literal">dhcpcd</tt>(8)) to +deliver a <tt class="docutils literal">SIGHUP</tt> or <tt class="docutils literal">SIGUSR1</tt> signal to OpenVPN. OpenVPN will +then re-establish a connection with its most recently authenticated +peer on its new IP address.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--learn-address <var>cmd</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Run command <tt class="docutils literal">cmd</tt> to validate client virtual addresses or routes.</p> +<p><tt class="docutils literal">cmd</tt> consists of a path to a script (or executable program), optionally +followed by arguments. The path and arguments may be single- or +double-quoted and/or escaped using a backslash, and should be separated +by one or more spaces.</p> +<p>Three arguments will be appended to any arguments in <tt class="docutils literal">cmd</tt> as follows:</p> +<dl class="docutils"> +<dt><code>$1</code> - [operation]</dt> +<dd><code>"add"</code>, <code>"update"</code>, or <code>"delete"</code> based on whether +or not the address is being added to, modified, or deleted from +OpenVPN's internal routing table.</dd> +<dt><code>$2</code> - [address]</dt> +<dd>The address being learned or unlearned. This can be an IPv4 address +such as <code>"198.162.10.14"</code>, an IPv4 subnet such as +<code>"198.162.10.0/24"</code>, or an ethernet MAC address (when +<tt class="docutils literal"><span class="pre">--dev</span> tap</tt> is being used) such as <code>"00:FF:01:02:03:04"</code>.</dd> +<dt><code>$3</code> - [common name]</dt> +<dd>The common name on the certificate associated with the client linked +to this address. Only present for <code>"add"</code> or <code>"update"</code> +operations, not <code>"delete"</code>.</dd> +</dl> +<p>On <code>"add"</code> or <code>"update"</code> methods, if the script returns +a failure code (non-zero), OpenVPN will reject the address and will not +modify its internal routing table.</p> +<p class="last">Normally, the <tt class="docutils literal">cmd</tt> script will use the information provided above to +set appropriate firewall entries on the VPN TUN/TAP interface. Since +OpenVPN provides the association between virtual IP or MAC address and +the client's authenticated common name, it allows a user-defined script +to configure firewall access policies with regard to the client's +high-level common name, rather than the low level client virtual +addresses.</p> +</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--route-up <var>cmd</var></span></kbd></td> +<td><p class="first">Run command <tt class="docutils literal">cmd</tt> after routes are added, subject to <tt class="docutils literal"><span class="pre">--route-delay</span></tt>.</p> +<p><tt class="docutils literal">cmd</tt> consists of a path to a script (or executable program), optionally +followed by arguments. The path and arguments may be single- or +double-quoted and/or escaped using a backslash, and should be separated +by one or more spaces.</p> +<p class="last">See the <a class="reference internal" href="#environmental-variables">Environmental Variables</a> section below for additional +parameters passed as environmental variables.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--route-pre-down <var>cmd</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Run command <tt class="docutils literal">cmd</tt> before routes are removed upon disconnection.</p> +<p><tt class="docutils literal">cmd</tt> consists of a path to a script (or executable program), optionally +followed by arguments. The path and arguments may be single- or +double-quoted and/or escaped using a backslash, and should be separated +by one or more spaces.</p> +<p class="last">See the <a class="reference internal" href="#environmental-variables">Environmental Variables</a> section below for additional +parameters passed as environmental variables.</p> +</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--setenv <var>args</var></span></kbd></td> +<td><p class="first">Set a custom environmental variable <code>name=value</code> to pass to script.</p> +<p>Valid syntaxes:</p> +<pre class="literal-block"> +setenv name value +setenv FORWARD_COMPATIBLE 1 +setenv opt config_option +</pre> +<p>By setting <code>FORWARD_COMPATIBLE</code> to <code>1</code>, the config file +syntax checking is relaxed so that unknown directives will trigger a +warning but not a fatal error, on the assumption that a given unknown +directive might be valid in future OpenVPN versions.</p> +<p>This option should be used with caution, as there are good security +reasons for having OpenVPN fail if it detects problems in a config file. +Having said that, there are valid reasons for wanting new software +features to gracefully degrade when encountered by older software +versions.</p> +<p>It is also possible to tag a single directive so as not to trigger a +fatal error if the directive isn't recognized. To do this, prepend the +following before the directive: <tt class="docutils literal">setenv opt</tt></p> +<p>Versions prior to OpenVPN 2.3.3 will always ignore options set with the +<tt class="docutils literal">setenv opt</tt> directive.</p> +<p class="last">See also <tt class="docutils literal"><span class="pre">--ignore-unknown-option</span></tt></p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--setenv-safe <var>args</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Set a custom environmental variable <code>OPENVPN_name</code> to <code>value</code> +to pass to scripts.</p> +<p>Valid syntaxes:</p> +<pre class="literal-block"> +setenv-safe name value +</pre> +<p class="last">This directive is designed to be pushed by the server to clients, and +the prepending of <code>OPENVPN_</code> to the environmental variable is a +safety precaution to prevent a <code>LD_PRELOAD</code> style attack from a +malicious or compromised server.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--tls-verify <var>cmd</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Run command <tt class="docutils literal">cmd</tt> to verify the X509 name of a pending TLS connection +that has otherwise passed all other tests of certification (except for +revocation via <tt class="docutils literal"><span class="pre">--crl-verify</span></tt> directive; the revocation test occurs +after the <tt class="docutils literal"><span class="pre">--tls-verify</span></tt> test).</p> +<p><tt class="docutils literal">cmd</tt> should return <code>0</code> to allow the TLS handshake to proceed, +or <code>1</code> to fail.</p> +<p><tt class="docutils literal">cmd</tt> consists of a path to a script (or executable program), optionally +followed by arguments. The path and arguments may be single- or +double-quoted and/or escaped using a backslash, and should be separated +by one or more spaces.</p> +<p>When <tt class="docutils literal">cmd</tt> is executed two arguments are appended after any arguments +specified in <tt class="docutils literal">cmd</tt>, as follows:</p> +<pre class="literal-block"> +cmd certificate_depth subject +</pre> +<p>These arguments are, respectively, the current certificate depth and the +X509 subject distinguished name (dn) of the peer.</p> +<p>This feature is useful if the peer you want to trust has a certificate +which was signed by a certificate authority who also signed many other +certificates, where you don't necessarily want to trust all of them, but +rather be selective about which peer certificate you will accept. This +feature allows you to write a script which will test the X509 name on a +certificate and decide whether or not it should be accepted. For a +simple perl script which will test the common name field on the +certificate, see the file <tt class="docutils literal"><span class="pre">verify-cn</span></tt> in the OpenVPN distribution.</p> +<p class="last">See the <a class="reference internal" href="#environmental-variables">Environmental Variables</a> section below for additional +parameters passed as environmental variables.</p> +</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--up <var>cmd</var></span></kbd></td> +<td><p class="first">Run command <tt class="docutils literal">cmd</tt> after successful TUN/TAP device open (pre <tt class="docutils literal"><span class="pre">--user</span></tt> +UID change).</p> +<p><tt class="docutils literal">cmd</tt> consists of a path to a script (or executable program), optionally +followed by arguments. The path and arguments may be single- or +double-quoted and/or escaped using a backslash, and should be separated +by one or more spaces.</p> +<p>The up command is useful for specifying route commands which route IP +traffic destined for private subnets which exist at the other end of the +VPN connection into the tunnel.</p> +<p>For <tt class="docutils literal"><span class="pre">--dev</span> tun</tt> execute as:</p> +<pre class="literal-block"> +cmd tun_dev tun_mtu link_mtu ifconfig_local_ip ifconfig_remote_ip [init | restart] +</pre> +<p>For <tt class="docutils literal"><span class="pre">--dev</span> tap</tt> execute as:</p> +<pre class="literal-block"> +cmd tap_dev tap_mtu link_mtu ifconfig_local_ip ifconfig_netmask [init | restart] +</pre> +<p>See the <a class="reference internal" href="#environmental-variables">Environmental Variables</a> section below for additional +parameters passed as environmental variables.</p> +<p>Note that if <tt class="docutils literal">cmd</tt> includes arguments, all OpenVPN-generated arguments +will be appended to them to build an argument list with which the +executable will be called.</p> +<p>Typically, <tt class="docutils literal">cmd</tt> will run a script to add routes to the tunnel.</p> +<p>Normally the up script is called after the TUN/TAP device is opened. In +this context, the last command line parameter passed to the script will +be <em>init.</em> If the <tt class="docutils literal"><span class="pre">--up-restart</span></tt> option is also used, the up script +will be called for restarts as well. A restart is considered to be a +partial reinitialization of OpenVPN where the TUN/TAP instance is +preserved (the <tt class="docutils literal"><span class="pre">--persist-tun</span></tt> option will enable such preservation). +A restart can be generated by a SIGUSR1 signal, a <tt class="docutils literal"><span class="pre">--ping-restart</span></tt> +timeout, or a connection reset when the TCP protocol is enabled with the +<tt class="docutils literal"><span class="pre">--proto</span></tt> option. If a restart occurs, and <tt class="docutils literal"><span class="pre">--up-restart</span></tt> has been +specified, the up script will be called with <em>restart</em> as the last +parameter.</p> +<dl class="docutils"> +<dt><em>NOTE:</em></dt> +<dd>On restart, OpenVPN will not pass the full set of environment +variables to the script. Namely, everything related to routing and +gateways will not be passed, as nothing needs to be done anyway - all +the routing setup is already in place. Additionally, the up-restart +script will run with the downgraded UID/GID settings (if configured).</dd> +</dl> +<p>The following standalone example shows how the <tt class="docutils literal"><span class="pre">--up</span></tt> script can be +called in both an initialization and restart context. (<em>NOTE:</em> for +security reasons, don't run the following example unless UDP port 9999 +is blocked by your firewall. Also, the example will run indefinitely, so +you should abort with control-c).</p> +<pre class="literal-block"> +openvpn --dev tun --port 9999 --verb 4 --ping-restart 10 \ + --up 'echo up' --down 'echo down' --persist-tun \ + --up-restart +</pre> +<p>Note that OpenVPN also provides the <tt class="docutils literal"><span class="pre">--ifconfig</span></tt> option to +automatically ifconfig the TUN device, eliminating the need to define an +<tt class="docutils literal"><span class="pre">--up</span></tt> script, unless you also want to configure routes in the +<tt class="docutils literal"><span class="pre">--up</span></tt> script.</p> +<p>If <tt class="docutils literal"><span class="pre">--ifconfig</span></tt> is also specified, OpenVPN will pass the ifconfig +local and remote endpoints on the command line to the <tt class="docutils literal"><span class="pre">--up</span></tt> script so +that they can be used to configure routes such as:</p> +<pre class="last literal-block"> +route add -net 10.0.0.0 netmask 255.255.255.0 gw $5 +</pre> +</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--up-delay</span></kbd></td> +<td><p class="first">Delay TUN/TAP open and possible <tt class="docutils literal"><span class="pre">--up</span></tt> script execution until after +TCP/UDP connection establishment with peer.</p> +<p>In <tt class="docutils literal"><span class="pre">--proto</span> udp</tt> mode, this option normally requires the use of +<tt class="docutils literal"><span class="pre">--ping</span></tt> to allow connection initiation to be sensed in the absence of +tunnel data, since UDP is a "connectionless" protocol.</p> +<p class="last">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.</p> +</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--up-restart</span></kbd></td> +<td>Enable the <tt class="docutils literal"><span class="pre">--up</span></tt> and <tt class="docutils literal"><span class="pre">--down</span></tt> scripts to be called for restarts as +well as initial program start. This option is described more fully above +in the <tt class="docutils literal"><span class="pre">--up</span></tt> option documentation.</td></tr> +</tbody> +</table> +</div> +<div class="section" id="string-types-and-remapping"> +<h2>String Types and Remapping</h2> +<p>In certain cases, OpenVPN will perform remapping of characters in +strings. Essentially, any characters outside the set of permitted +characters for each string type will be converted to underbar ('_').</p> +<dl class="docutils"> +<dt><em>Q: Why is string remapping necessary?</em></dt> +<dd>It's an important security feature to prevent the malicious +coding of strings from untrusted sources to be passed as parameters to +scripts, saved in the environment, used as a common name, translated to +a filename, etc.</dd> +<dt><em>Q: Can string remapping be disabled?</em></dt> +<dd>Yes, by using the <tt class="docutils literal"><span class="pre">--no-name-remapping</span></tt> option, however this +should be considered an advanced option.</dd> +</dl> +<p>Here is a brief rundown of OpenVPN's current string types and the +permitted character class for each string:</p> +<dl class="docutils"> +<dt><em>X509 Names</em></dt> +<dd>Alphanumeric, underbar ('_'), dash ('-'), dot ('.'), at +('@'), colon (':'), slash ('/'), and equal ('='). Alphanumeric is +defined as a character which will cause the C library isalnum() function +to return true.</dd> +<dt><em>Common Names</em></dt> +<dd>Alphanumeric, underbar ('_'), dash ('-'), dot ('.'), and at ('@').</dd> +<dt><em>--auth-user-pass username</em></dt> +<dd>Same as Common Name, with one exception: +starting with OpenVPN 2.0.1, the username is passed to the +<code>OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY</code> plugin in its raw form, +without string remapping.</dd> +<dt><em>--auth-user-pass password</em></dt> +<dd>Any "printable" character except CR or LF. Printable is defined to be +a character which will cause the C library isprint() function to +return true.</dd> +<dt><em>--client-config-dir filename as derived from common name or`username</em></dt> +<dd>Alphanumeric, underbar ('_'), dash ('-'), and dot ('.') except for "." +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.</dd> +<dt><em>Environmental variable names</em></dt> +<dd>Alphanumeric or underbar ('_').</dd> +<dt><em>Environmental variable values</em></dt> +<dd>Any printable character.</dd> +</dl> +<p>For all cases, characters in a string which are not members of the legal +character class for that string type will be remapped to underbar +('_').</p> +</div> +<div class="section" id="environmental-variables"> +<h2>Environmental Variables</h2> +<p>Once set, a variable is persisted indefinitely until it is reset by a +new value or a restart,</p> +<p>As of OpenVPN 2.0-beta12, in server mode, environmental variables set by +OpenVPN are scoped according to the client objects they are associated +with, so there should not be any issues with scripts having access to +stale, previously set variables which refer to different client +instances.</p> +<dl class="docutils"> +<dt><code>bytes_received</code></dt> +<dd>Total number of bytes received from client during VPN session. Set prior +to execution of the <tt class="docutils literal"><span class="pre">--client-disconnect</span></tt> script.</dd> +<dt><code>bytes_sent</code></dt> +<dd>Total number of bytes sent to client during VPN session. Set prior to +execution of the <tt class="docutils literal"><span class="pre">--client-disconnect</span></tt> script.</dd> +<dt><code>client_connect_config_file</code></dt> +<dd>The path to the configuration file that should be written to by the +<tt class="docutils literal"><span class="pre">--client-connect</span></tt> script (optional, if per-session configuration +is desired). This is the same file name as passed via command line +argument on the call to the <tt class="docutils literal"><span class="pre">--client-connect</span></tt> script.</dd> +<dt><code>client_connect_deferred_file</code></dt> +<dd><p class="first">This file can be optionally written to in order to to communicate a +status code of the <tt class="docutils literal"><span class="pre">--client-connect</span></tt> script or plgin. Only the +first character in the file is relevant. It must be either <code>1</code> +to indicate normal script execution, <code>0</code> indicates an error (in +the same way that a non zero exit status does) or <code>2</code> to indicate +that the script deferred returning the config file.</p> +<p>For deferred (background) handling, the script or plugin MUST write +<code>2</code> to the file to indicate the deferral and then return with +exit code <code>0</code> to signal <tt class="docutils literal">deferred handler started OK</tt>.</p> +<p>A background process or similar must then take care of writing the +configuration to the file indicated by the +<code>client_connect_config_file</code> environment variable and when +finished, write the a <code>1</code> to this file (or <code>0</code> in case of +an error).</p> +<p class="last">The absence of any character in the file when the script finishes +executing is interpreted the same as <code>1</code>. This allows scripts +that are not written to support the defer mechanism to be used +unmodified.</p> +</dd> +<dt><code>common_name</code></dt> +<dd>The X509 common name of an authenticated client. Set prior to execution +of <tt class="docutils literal"><span class="pre">--client-connect</span></tt>, <tt class="docutils literal"><span class="pre">--client-disconnect</span></tt> and +<tt class="docutils literal"><span class="pre">--auth-user-pass-verify</span></tt> scripts.</dd> +<dt><code>config</code></dt> +<dd>Name of first <tt class="docutils literal"><span class="pre">--config</span></tt> file. Set on program initiation and reset on +SIGHUP.</dd> +<dt><code>daemon</code></dt> +<dd>Set to "1" if the <tt class="docutils literal"><span class="pre">--daemon</span></tt> directive is specified, or "0" otherwise. +Set on program initiation and reset on SIGHUP.</dd> +<dt><code>daemon_log_redirect</code></dt> +<dd>Set to "1" if the <tt class="docutils literal"><span class="pre">--log</span></tt> or <tt class="docutils literal"><span class="pre">--log-append</span></tt> directives are +specified, or "0" otherwise. Set on program initiation and reset on +SIGHUP.</dd> +<dt><code>dev</code></dt> +<dd>The actual name of the TUN/TAP device, including a unit number if it +exists. Set prior to <tt class="docutils literal"><span class="pre">--up</span></tt> or <tt class="docutils literal"><span class="pre">--down</span></tt> script execution.</dd> +<dt><code>dev_idx</code></dt> +<dd>On Windows, the device index of the TUN/TAP adapter (to be used in +netsh.exe calls which sometimes just do not work right with interface +names). Set prior to <tt class="docutils literal"><span class="pre">--up</span></tt> or <tt class="docutils literal"><span class="pre">--down</span></tt> script execution.</dd> +<dt><code>foreign_option_{n}</code></dt> +<dd>An option pushed via <tt class="docutils literal"><span class="pre">--push</span></tt> to a client which does not natively +support it, such as <tt class="docutils literal"><span class="pre">--dhcp-option</span></tt> on a non-Windows system, will be +recorded to this environmental variable sequence prior to <tt class="docutils literal"><span class="pre">--up</span></tt> +script execution.</dd> +<dt><code>ifconfig_broadcast</code></dt> +<dd>The broadcast address for the virtual ethernet segment which is derived +from the <tt class="docutils literal"><span class="pre">--ifconfig</span></tt> option when <tt class="docutils literal"><span class="pre">--dev</span> tap</tt> is used. Set prior to +OpenVPN calling the <code>ifconfig</code> or <code>netsh</code> (windows version +of ifconfig) commands which normally occurs prior to <tt class="docutils literal"><span class="pre">--up</span></tt> script +execution.</dd> +<dt><code>ifconfig_ipv6_local</code></dt> +<dd>The local VPN endpoint IPv6 address specified in the +<tt class="docutils literal"><span class="pre">--ifconfig-ipv6</span></tt> option (first parameter). Set prior to OpenVPN +calling the <code>ifconfig</code> or code:<cite>netsh</cite> (windows version of +ifconfig) commands which normally occurs prior to <tt class="docutils literal"><span class="pre">--up</span></tt> script +execution.</dd> +<dt><code>ifconfig_ipv6_netbits</code></dt> +<dd>The prefix length of the IPv6 network on the VPN interface. Derived +from the /nnn parameter of the IPv6 address in the <tt class="docutils literal"><span class="pre">--ifconfig-ipv6</span></tt> +option (first parameter). Set prior to OpenVPN calling the +<code>ifconfig</code> or <code>netsh</code> (windows version of ifconfig) +commands which normally occurs prior to <tt class="docutils literal"><span class="pre">--up</span></tt> script execution.</dd> +<dt><code>ifconfig_ipv6_remote</code></dt> +<dd>The remote VPN endpoint IPv6 address specified in the +<tt class="docutils literal"><span class="pre">--ifconfig-ipv6</span></tt> option (second parameter). Set prior to OpenVPN +calling the <code>ifconfig</code> or <code>netsh</code> (windows version of +ifconfig) commands which normally occurs prior to <tt class="docutils literal"><span class="pre">--up</span></tt> script +execution.</dd> +<dt><code>ifconfig_local</code></dt> +<dd>The local VPN endpoint IP address specified in the <tt class="docutils literal"><span class="pre">--ifconfig</span></tt> +option (first parameter). Set prior to OpenVPN calling the +<code>ifconfig</code> or <code>netsh</code> (windows version of ifconfig) +commands which normally occurs prior to <tt class="docutils literal"><span class="pre">--up</span></tt> script execution.</dd> +<dt><code>ifconfig_remote</code></dt> +<dd>The remote VPN endpoint IP address specified in the <tt class="docutils literal"><span class="pre">--ifconfig</span></tt> +option (second parameter) when <tt class="docutils literal"><span class="pre">--dev</span> tun</tt> is used. Set prior to +OpenVPN calling the <code>ifconfig</code> or <code>netsh</code> (windows version +of ifconfig) commands which normally occurs prior to <tt class="docutils literal"><span class="pre">--up</span></tt> script +execution.</dd> +<dt><code>ifconfig_netmask</code></dt> +<dd>The subnet mask of the virtual ethernet segment that is specified as +the second parameter to <tt class="docutils literal"><span class="pre">--ifconfig</span></tt> when <tt class="docutils literal"><span class="pre">--dev</span> tap</tt> is being +used. Set prior to OpenVPN calling the <code>ifconfig</code> or +<code>netsh</code> (windows version of ifconfig) commands which normally +occurs prior to <tt class="docutils literal"><span class="pre">--up</span></tt> script execution.</dd> +<dt><code>ifconfig_pool_local_ip</code></dt> +<dd>The local virtual IP address for the TUN/TAP tunnel taken from an +<tt class="docutils literal"><span class="pre">--ifconfig-push</span></tt> directive if specified, or otherwise from the +ifconfig pool (controlled by the <tt class="docutils literal"><span class="pre">--ifconfig-pool</span></tt> config file +directive). Only set for <tt class="docutils literal"><span class="pre">--dev</span> tun</tt> tunnels. This option is set on +the server prior to execution of the <tt class="docutils literal"><span class="pre">--client-connect</span></tt> and +<tt class="docutils literal"><span class="pre">--client-disconnect</span></tt> scripts.</dd> +<dt><code>ifconfig_pool_netmask</code></dt> +<dd>The virtual IP netmask for the TUN/TAP tunnel taken from an +<tt class="docutils literal"><span class="pre">--ifconfig-push</span></tt> directive if specified, or otherwise from the +ifconfig pool (controlled by the <tt class="docutils literal"><span class="pre">--ifconfig-pool</span></tt> config file +directive). Only set for <tt class="docutils literal"><span class="pre">--dev</span> tap</tt> tunnels. This option is set on +the server prior to execution of the <tt class="docutils literal"><span class="pre">--client-connect</span></tt> and +<tt class="docutils literal"><span class="pre">--client-disconnect</span></tt> scripts.</dd> +<dt><code>ifconfig_pool_remote_ip</code></dt> +<dd>The remote virtual IP address for the TUN/TAP tunnel taken from an +<tt class="docutils literal"><span class="pre">--ifconfig-push</span></tt> directive if specified, or otherwise from the +ifconfig pool (controlled by the <tt class="docutils literal"><span class="pre">--ifconfig-pool</span></tt> config file +directive). This option is set on the server prior to execution of the +<tt class="docutils literal"><span class="pre">--client-connect</span></tt> and <tt class="docutils literal"><span class="pre">--client-disconnect</span></tt> scripts.</dd> +<dt><code>link_mtu</code></dt> +<dd>The maximum packet size (not including the IP header) of tunnel data in +UDP tunnel transport mode. Set prior to <tt class="docutils literal"><span class="pre">--up</span></tt> or <tt class="docutils literal"><span class="pre">--down</span></tt> script +execution.</dd> +<dt><code>local</code></dt> +<dd>The <tt class="docutils literal"><span class="pre">--local</span></tt> parameter. Set on program initiation and reset on +SIGHUP.</dd> +<dt><code>local_port</code></dt> +<dd>The local port number or name, specified by <tt class="docutils literal"><span class="pre">--port</span></tt> or <tt class="docutils literal"><span class="pre">--lport</span></tt>. +Set on program initiation and reset on SIGHUP.</dd> +<dt><code>password</code></dt> +<dd>The password provided by a connecting client. Set prior to +<tt class="docutils literal"><span class="pre">--auth-user-pass-verify</span></tt> script execution only when the <tt class="docutils literal"><span class="pre">via-env</span></tt> +modifier is specified, and deleted from the environment after the script +returns.</dd> +<dt><code>proto</code></dt> +<dd>The <tt class="docutils literal"><span class="pre">--proto</span></tt> parameter. Set on program initiation and reset on +SIGHUP.</dd> +<dt><code>remote_{n}</code></dt> +<dd>The <tt class="docutils literal"><span class="pre">--remote</span></tt> parameter. Set on program initiation and reset on +SIGHUP.</dd> +<dt><code>remote_port_{n}</code></dt> +<dd>The remote port number, specified by <tt class="docutils literal"><span class="pre">--port</span></tt> or <tt class="docutils literal"><span class="pre">--rport</span></tt>. Set on +program initiation and reset on SIGHUP.</dd> +<dt><code>route_net_gateway</code></dt> +<dd>The pre-existing default IP gateway in the system routing table. Set +prior to <tt class="docutils literal"><span class="pre">--up</span></tt> script execution.</dd> +<dt><code>route_vpn_gateway</code></dt> +<dd>The default gateway used by <tt class="docutils literal"><span class="pre">--route</span></tt> options, as specified in either +the <tt class="docutils literal"><span class="pre">--route-gateway</span></tt> option or the second parameter to +<tt class="docutils literal"><span class="pre">--ifconfig</span></tt> when <tt class="docutils literal"><span class="pre">--dev</span> tun</tt> is specified. Set prior to <tt class="docutils literal"><span class="pre">--up</span></tt> +script execution.</dd> +<dt><code>route_{parm}_{n}</code></dt> +<dd><p class="first">A set of variables which define each route to be added, and are set +prior to <tt class="docutils literal"><span class="pre">--up</span></tt> script execution.</p> +<p><tt class="docutils literal">parm</tt> will be one of <code>network</code>, <code>netmask"</code>, +<code>gateway</code>, or <code>metric</code>.</p> +<p><tt class="docutils literal">n</tt> is the OpenVPN route number, starting from 1.</p> +<p class="last">If the network or gateway are resolvable DNS names, their IP address +translations will be recorded rather than their names as denoted on the +command line or configuration file.</p> +</dd> +<dt><code>route_ipv6_{parm}_{n}</code></dt> +<dd><p class="first">A set of variables which define each IPv6 route to be added, and are +set prior to <strong>--up</strong> script execution.</p> +<p><tt class="docutils literal">parm</tt> will be one of <code>network</code>, <code>gateway</code> or +<code>metric</code>. <tt class="docutils literal">route_ipv6_network_{n}</tt> contains <code>netmask</code> +as <code>/nnn</code>, unlike IPv4 where it is passed in a separate environment +variable.</p> +<p><tt class="docutils literal">n</tt> is the OpenVPN route number, starting from 1.</p> +<p class="last">If the network or gateway are resolvable DNS names, their IP address +translations will be recorded rather than their names as denoted on the +command line or configuration file.</p> +</dd> +<dt><code>peer_cert</code></dt> +<dd>Temporary file name containing the client certificate upon connection. +Useful in conjunction with <tt class="docutils literal"><span class="pre">--tls-verify</span></tt>.</dd> +<dt><code>script_context</code></dt> +<dd>Set to "init" or "restart" prior to up/down script execution. For more +information, see documentation for <tt class="docutils literal"><span class="pre">--up</span></tt>.</dd> +<dt><code>script_type</code></dt> +<dd>Prior to execution of any script, this variable is set to the type of +script being run. It can be one of the following: <code>up</code>, +<code>down</code>, <code>ipchange</code>, <code>route-up</code>, <code>tls-verify</code>, +<code>auth-user-pass-verify</code>, <code>client-connect</code>, +<code>client-disconnect</code> or <code>learn-address</code>. Set prior to +execution of any script.</dd> +<dt><code>signal</code></dt> +<dd>The reason for exit or restart. Can be one of <code>sigusr1</code>, +<code>sighup</code>, <code>sigterm</code>, <code>sigint</code>, <code>inactive</code> +(controlled by <tt class="docutils literal"><span class="pre">--inactive</span></tt> option), <code>ping-exit</code> (controlled +by <tt class="docutils literal"><span class="pre">--ping-exit</span></tt> option), <code>ping-restart</code> (controlled by +<tt class="docutils literal"><span class="pre">--ping-restart</span></tt> option), <code>connection-reset</code> (triggered on TCP +connection reset), <code>error</code> or <code>unknown</code> (unknown signal). +This variable is set just prior to down script execution.</dd> +<dt><code>time_ascii</code></dt> +<dd>Client connection timestamp, formatted as a human-readable time string. +Set prior to execution of the <tt class="docutils literal"><span class="pre">--client-connect</span></tt> script.</dd> +<dt><code>time_duration</code></dt> +<dd>The duration (in seconds) of the client session which is now +disconnecting. Set prior to execution of the <tt class="docutils literal"><span class="pre">--client-disconnect</span></tt> +script.</dd> +<dt><code>time_unix</code></dt> +<dd>Client connection timestamp, formatted as a unix integer date/time +value. Set prior to execution of the <tt class="docutils literal"><span class="pre">--client-connect</span></tt> script.</dd> +<dt><code>tls_digest_{n}</code> / <code>tls_digest_sha256_{n}</code></dt> +<dd>Contains the certificate SHA1 / SHA256 fingerprint, where <tt class="docutils literal">n</tt> is the +verification level. Only set for TLS connections. Set prior to execution +of <tt class="docutils literal"><span class="pre">--tls-verify</span></tt> script.</dd> +<dt><code>tls_id_{n}</code></dt> +<dd>A series of certificate fields from the remote peer, where <tt class="docutils literal">n</tt> is the +verification level. Only set for TLS connections. Set prior to execution +of <tt class="docutils literal"><span class="pre">--tls-verify</span></tt> script.</dd> +<dt><code>tls_serial_{n}</code></dt> +<dd>The serial number of the certificate from the remote peer, where <tt class="docutils literal">n</tt> +is the verification level. Only set for TLS connections. Set prior to +execution of <tt class="docutils literal"><span class="pre">--tls-verify</span></tt> script. This is in the form of a decimal +string like "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 +<code>contrib/OCSP_check/OCSP_check.sh</code> script for an example.</dd> +<dt><code>tls_serial_hex_{n}</code></dt> +<dd>Like <code>tls_serial_{n}</code>, but in hex form (e.g. +<code>12:34:56:78:9A</code>).</dd> +<dt><code>tun_mtu</code></dt> +<dd>The MTU of the TUN/TAP device. Set prior to <tt class="docutils literal"><span class="pre">--up</span></tt> or <tt class="docutils literal"><span class="pre">--down</span></tt> +script execution.</dd> +<dt><code>trusted_ip</code> / <code>trusted_ip6</code>)</dt> +<dd>Actual IP address of connecting client or peer which has been +authenticated. Set prior to execution of <tt class="docutils literal"><span class="pre">--ipchange</span></tt>, +<tt class="docutils literal"><span class="pre">--client-connect</span></tt> and <tt class="docutils literal"><span class="pre">--client-disconnect</span></tt> scripts. If using ipv6 +endpoints (udp6, tcp6), <code>trusted_ip6</code> will be set instead.</dd> +<dt><code>trusted_port</code></dt> +<dd>Actual port number of connecting client or peer which has been +authenticated. Set prior to execution of <tt class="docutils literal"><span class="pre">--ipchange</span></tt>, +<tt class="docutils literal"><span class="pre">--client-connect</span></tt> and <tt class="docutils literal"><span class="pre">--client-disconnect</span></tt> scripts.</dd> +<dt><code>untrusted_ip</code> / <code>untrusted_ip6</code></dt> +<dd>Actual IP address of connecting client or peer which has not been +authenticated yet. Sometimes used to <em>nmap</em> the connecting host in a +<tt class="docutils literal"><span class="pre">--tls-verify</span></tt> script to ensure it is firewalled properly. Set prior +to execution of <tt class="docutils literal"><span class="pre">--tls-verify</span></tt> and <tt class="docutils literal"><span class="pre">--auth-user-pass-verify</span></tt> +scripts. If using ipv6 endpoints (udp6, tcp6), <code>untrusted_ip6</code> +will be set instead.</dd> +<dt><code>untrusted_port</code></dt> +<dd>Actual port number of connecting client or peer which has not been +authenticated yet. Set prior to execution of <tt class="docutils literal"><span class="pre">--tls-verify</span></tt> and +<tt class="docutils literal"><span class="pre">--auth-user-pass-verify</span></tt> scripts.</dd> +<dt><code>username</code></dt> +<dd>The username provided by a connecting client. Set prior to +<tt class="docutils literal"><span class="pre">--auth-user-pass-verify</span></tt> script execution only when the +<code>via-env</code> modifier is specified.</dd> +<dt><code>X509_{n}_{subject_field}</code></dt> +<dd><p class="first">An X509 subject field from the remote peer certificate, where <tt class="docutils literal">n</tt> is +the verification level. Only set for TLS connections. Set prior to +execution of <tt class="docutils literal"><span class="pre">--tls-verify</span></tt> script. This variable is similar to +<code>tls_id_{n}</code> except the component X509 subject fields are broken +out, and no string remapping occurs on these field values (except for +remapping of control characters to "<code>_</code>"). For example, the +following variables would be set on the OpenVPN server using the sample +client certificate in sample-keys (client.crt). Note that the +verification level is 0 for the client certificate and 1 for the CA +certificate.</p> +<pre class="last literal-block"> +X509_0_emailAddress=me@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 +</pre> +</dd> +</dl> +</div> +<div class="section" id="management-interface-options"> +<h2>Management Interface Options</h2> +<p>OpenVPN provides a feature rich socket based management interface for both +server and client mode operations.</p> +<table class="docutils option-list" frame="void" rules="none"> +<col class="option" /> +<col class="description" /> +<tbody valign="top"> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--management <var>args</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Enable a management server on a <tt class="docutils literal"><span class="pre">socket-name</span></tt> Unix socket on those +platforms supporting it, or on a designated TCP port.</p> +<p>Valid syntaxes:</p> +<pre class="literal-block"> +management socket-name unix # +management socket-name unix pw-file # (recommended) +management IP port # (INSECURE) +management IP port pw-file # +</pre> +<p><tt class="docutils literal"><span class="pre">pw-file</span></tt>, if specified, is a password file where the password must +be on first line. Instead of a filename it can use the keyword stdin +which will prompt the user for a password to use when OpenVPN is +starting.</p> +<p>For unix sockets, the default behaviour is to create a unix domain +socket that may be connected to by any process. Use the +<tt class="docutils literal"><span class="pre">--management-client-user</span></tt> and <tt class="docutils literal"><span class="pre">--management-client-group</span></tt> +directives to restrict access.</p> +<p>The management interface provides a special mode where the TCP +management link can operate over the tunnel itself. To enable this mode, +set IP to <tt class="docutils literal">tunnel</tt>. Tunnel mode will cause the management interface to +listen for a TCP connection on the local VPN address of the TUN/TAP +interface.</p> +<p><strong>*BEWARE*</strong> of enabling the management interface over TCP. In these cases +you should <em>ALWAYS</em> make use of <tt class="docutils literal"><span class="pre">pw-file</span></tt> to password protect the +management interface. Any user who can connect to this TCP <tt class="docutils literal">IP:port</tt> +will be able to manage and control (and interfere with) the OpenVPN +process. It is also strongly recommended to set IP to 127.0.0.1 +(localhost) to restrict accessibility of the management server to local +clients.</p> +<p>While the management port is designed for programmatic control of +OpenVPN by other applications, it is possible to telnet to the port, +using a telnet client in "raw" mode. Once connected, type <code>help</code> +for a list of commands.</p> +<p class="last">For detailed documentation on the management interface, see the +<em>management-notes.txt</em> file in the management folder of the OpenVPN +source distribution.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--management-client</span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Management interface will connect as a TCP/unix domain client to +<tt class="docutils literal">IP:port</tt> specified by <tt class="docutils literal"><span class="pre">--management</span></tt> rather than listen as a TCP +server or on a unix domain socket.</p> +<p class="last">If the client connection fails to connect or is disconnected, a SIGTERM +signal will be generated causing OpenVPN to quit.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--management-client-auth</span></kbd></td> +</tr> +<tr><td> </td><td>Gives management interface client the responsibility to authenticate +clients after their client certificate has been verified. See +<code>management-notes.txt</code> in OpenVPN distribution for detailed notes.</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--management-client-group <var>g</var></span></kbd></td> +</tr> +<tr><td> </td><td>When the management interface is listening on a unix domain socket, only +allow connections from group <tt class="docutils literal">g</tt>.</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--management-client-pf</span></kbd></td> +</tr> +<tr><td> </td><td>Management interface clients must specify a packet filter file for each +connecting client. See <code>management-notes.txt</code> in OpenVPN +distribution for detailed notes.</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--management-client-user <var>u</var></span></kbd></td> +</tr> +<tr><td> </td><td>When the management interface is listening on a unix domain socket, only +allow connections from user <tt class="docutils literal">u</tt>.</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--management-external-cert <var>certificate-hint</var></span></kbd></td> +</tr> +<tr><td> </td><td>Allows usage for external certificate instead of <tt class="docutils literal"><span class="pre">--cert</span></tt> option +(client-only). <tt class="docutils literal"><span class="pre">certificate-hint</span></tt> is an arbitrary string which is +passed to a management interface client as an argument of +<em>NEED-CERTIFICATE</em> notification. Requires <tt class="docutils literal"><span class="pre">--management-external-key</span></tt>.</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--management-external-key <var>args</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Allows usage for external private key file instead of <tt class="docutils literal"><span class="pre">--key</span></tt> option +(client-only).</p> +<p>Valid syntaxes:</p> +<pre class="literal-block"> +management-external-key +management-external-key nopadding +management-external-key pkcs1 +management-external-key nopadding pkcs1 +</pre> +<p class="last">The optional parameters <code>nopadding</code> and <code>pkcs1</code> signal +support for different padding algorithms. See +<code>doc/mangement-notes.txt</code> for a complete description of this +feature.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--management-forget-disconnect</span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Make OpenVPN forget passwords when management session disconnects.</p> +<p class="last">This directive does not affect the <tt class="docutils literal"><span class="pre">--http-proxy</span></tt> username/password. +It is always cached.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--management-hold</span></kbd></td> +</tr> +<tr><td> </td><td>Start OpenVPN in a hibernating state, until a client of the management +interface explicitly starts it with the <code>hold release</code> command.</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--management-log-cache <var>n</var></span></kbd></td> +</tr> +<tr><td> </td><td>Cache the most recent <tt class="docutils literal">n</tt> lines of log file history for usage by the +management channel.</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--management-query-passwords</span></kbd></td> +</tr> +<tr><td> </td><td>Query management channel for private key password and +<tt class="docutils literal"><span class="pre">--auth-user-pass</span></tt> username/password. Only query the management +channel for inputs which ordinarily would have been queried from the +console.</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--management-query-proxy</span></kbd></td> +</tr> +<tr><td> </td><td>Query management channel for proxy server information for a specific +<tt class="docutils literal"><span class="pre">--remote</span></tt> (client-only).</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--management-query-remote</span></kbd></td> +</tr> +<tr><td> </td><td>Allow management interface to override <tt class="docutils literal"><span class="pre">--remote</span></tt> directives +(client-only).</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--management-signal</span></kbd></td> +</tr> +<tr><td> </td><td>Send SIGUSR1 signal to OpenVPN if management session disconnects. This +is useful when you wish to disconnect an OpenVPN session on user logoff. +For <tt class="docutils literal"><span class="pre">--management-client</span></tt> this option is not needed since a disconnect +will always generate a <code>SIGTERM</code>.</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--management-up-down</span></kbd></td> +</tr> +<tr><td> </td><td>Report tunnel up/down events to management interface.</td></tr> +</tbody> +</table> +</div> +<div class="section" id="plug-in-interface-options"> +<h2>Plug-in Interface Options</h2> +<p>OpenVPN can be extended by loading external plug-in modules at runtime. These +plug-ins must be prebuilt and adhere to the OpenVPN Plug-In API.</p> +<table class="docutils option-list" frame="void" rules="none"> +<col class="option" /> +<col class="description" /> +<tbody valign="top"> +<tr><td class="option-group"> +<kbd><span class="option">--plugin <var>args</var></span></kbd></td> +<td><p class="first">Loads an OpenVPN plug-in module.</p> +<p>Valid syntax:</p> +<pre class="literal-block"> +plugin module-name +plugin module-name "arguments" +</pre> +<p>The <tt class="docutils literal"><span class="pre">module-name</span></tt> needs to be the first +argument, indicating the plug-in to load. The second argument is an +optional init string which will be passed directly to the plug-in. +If the init consists of multiple arguments it must be enclosed in +double-quotes ("). Multiple plugin modules may be loaded into one +OpenVPN process.</p> +<p>The <tt class="docutils literal"><span class="pre">module-name</span></tt> argument can be just a filename or a filename +with a relative or absolute path. The format of the filename and path +defines if the plug-in will be loaded from a default plug-in directory +or outside this directory.</p> +<pre class="literal-block"> +--plugin path Effective directory used +===================== ============================= + myplug.so DEFAULT_DIR/myplug.so + subdir/myplug.so DEFAULT_DIR/subdir/myplug.so + ./subdir/myplug.so CWD/subdir/myplug.so + /usr/lib/my/plug.so /usr/lib/my/plug.so +</pre> +<p><tt class="docutils literal">DEFAULT_DIR</tt> is replaced by the default plug-in directory, which is +configured at the build time of OpenVPN. <tt class="docutils literal">CWD</tt> is the current directory +where OpenVPN was started or the directory OpenVPN have switched into +via the <tt class="docutils literal"><span class="pre">--cd</span></tt> option before the <tt class="docutils literal"><span class="pre">--plugin</span></tt> option.</p> +<p>For more information and examples on how to build OpenVPN plug-in +modules, see the README file in the <tt class="docutils literal">plugin</tt> folder of the OpenVPN +source distribution.</p> +<p>If you are using an RPM install of OpenVPN, see +<code>/usr/share/openvpn/plugin</code>. The documentation is in <tt class="docutils literal">doc</tt> and +the actual plugin modules are in <tt class="docutils literal">lib</tt>.</p> +<p class="last">Multiple plugin modules can be cascaded, and modules can be used in +tandem with scripts. The modules will be called by OpenVPN in the order +that they are declared in the config file. If both a plugin and script +are configured for the same callback, the script will be called last. If +the return code of the module/script controls an authentication function +(such as tls-verify, auth-user-pass-verify, or client-connect), then +every module and script must return success (<code>0</code>) in order for the +connection to be authenticated.</p> +</td></tr> +</tbody> +</table> +</div> +<div class="section" id="windows-specific-options"> +<h2>Windows-Specific Options</h2> +<table class="docutils option-list" frame="void" rules="none"> +<col class="option" /> +<col class="description" /> +<tbody valign="top"> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--allow-nonadmin <var>TAP-adapter</var></span></kbd></td> +</tr> +<tr><td> </td><td>(Standalone) Set <tt class="docutils literal"><span class="pre">TAP-adapter</span></tt> to allow access from non-administrative +accounts. If <tt class="docutils literal"><span class="pre">TAP-adapter</span></tt> is omitted, all TAP adapters on the system +will be configured to allow non-admin access. The non-admin access +setting will only persist for the length of time that the TAP-Win32 +device object and driver remain loaded, and will need to be re-enabled +after a reboot, or if the driver is unloaded and reloaded. This +directive can only be used by an administrator.</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--block-outside-dns</span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Block DNS servers on other network adapters to prevent DNS leaks. This +option prevents any application from accessing TCP or UDP port 53 except +one inside the tunnel. It uses Windows Filtering Platform (WFP) and +works on Windows Vista or later.</p> +<p class="last">This option is considered unknown on non-Windows platforms and +unsupported on Windows XP, resulting in fatal error. You may want to use +<tt class="docutils literal"><span class="pre">--setenv</span> opt</tt> or <tt class="docutils literal"><span class="pre">--ignore-unknown-option</span></tt> (not suitable for +Windows XP) to ignore said error. Note that pushing unknown options from +server does not trigger fatal errors.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--cryptoapicert <var>select-string</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first"><em>(Windows/OpenSSL Only)</em> Load the certificate and private key from the +Windows Certificate System Store.</p> +<p>Use this option instead of <tt class="docutils literal"><span class="pre">--cert</span></tt> and <tt class="docutils literal"><span class="pre">--key</span></tt>.</p> +<p>This makes it possible to use any smart card, supported by Windows, but +also any kind of certificate, residing in the Cert Store, where you have +access to the private key. This option has been tested with a couple of +different smart cards (GemSAFE, Cryptoflex, and Swedish Post Office eID) +on the client side, and also an imported PKCS12 software certificate on +the server side.</p> +<p>To select a certificate, based on a substring search in the +certificate's subject:</p> +<pre class="literal-block"> +cryptoapicert "SUBJ:Peter Runestig" +</pre> +<p>To select a certificate, based on certificate's thumbprint:</p> +<pre class="literal-block"> +cryptoapicert "THUMB:f6 49 24 41 01 b4 ..." +</pre> +<p class="last">The thumbprint hex string can easily be copy-and-pasted from the Windows +Certificate Store GUI.</p> +</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--dhcp-release</span></kbd></td> +<td>Ask Windows to release the TAP adapter lease on shutdown. This option +has no effect now, as it is enabled by default starting with +OpenVPN 2.4.1.</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--dhcp-renew</span></kbd></td> +<td>Ask Windows to renew the TAP adapter lease on startup. This option is +normally unnecessary, as Windows automatically triggers a DHCP +renegotiation on the TAP adapter when it comes up, however if you set +the TAP-Win32 adapter Media Status property to "Always Connected", you +may need this flag.</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--ip-win32 <var>method</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">When using <tt class="docutils literal"><span class="pre">--ifconfig</span></tt> on Windows, set the TAP-Win32 adapter IP +address and netmask using <tt class="docutils literal">method</tt>. Don't use this option unless you +are also using <tt class="docutils literal"><span class="pre">--ifconfig</span></tt>.</p> +<dl class="last docutils"> +<dt><code>manual</code></dt> +<dd>Don't set the IP address or netmask automatically. Instead +output a message to the console telling the user to configure the +adapter manually and indicating the IP/netmask which OpenVPN +expects the adapter to be set to.</dd> +<dt><code>dynamic [offset] [lease-time]</code></dt> +<dd><p class="first">Automatically set the IP address and netmask by replying to DHCP +query messages generated by the kernel. This mode is probably the +"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:</p> +<ol class="arabic simple"> +<li>The TCP/IP properties for the TAP-Win32 adapter must be set +to "Obtain an IP address automatically", and</li> +<li>OpenVPN needs to claim an IP address in the subnet for use +as the virtual DHCP server address.</li> +</ol> +<p>By default in <tt class="docutils literal"><span class="pre">--dev</span> tap</tt> mode, OpenVPN will take the normally +unused first address in the subnet. For example, if your subnet is +<code>192.168.4.0 netmask 255.255.255.0</code>, then OpenVPN will take +the IP address <code>192.168.4.0</code> to use as the virtual DHCP +server address. In <tt class="docutils literal"><span class="pre">--dev</span> tun</tt> mode, OpenVPN will cause the DHCP +server to masquerade as if it were coming from the remote endpoint.</p> +<p>The optional offset parameter is an integer which is > <code>-256</code> +and < <code>256</code> and which defaults to -1. If offset is positive, +the DHCP server will masquerade as the IP address at network +address + offset. If offset is negative, the DHCP server will +masquerade as the IP address at broadcast address + offset.</p> +<p>The Windows <code>ipconfig /all</code> command can be used to show what +Windows thinks the DHCP server address is. OpenVPN will "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.</p> +<p class="last">The <tt class="docutils literal"><span class="pre">lease-time</span></tt> parameter controls the lease time of the DHCP +assignment given to the TAP-Win32 adapter, and is denoted in +seconds. Normally a very long lease time is preferred because it +prevents routes involving the TAP-Win32 adapter from being lost +when the system goes to sleep. The default lease time is one year.</p> +</dd> +<dt><code>netsh</code></dt> +<dd>Automatically set the IP address and netmask using the Windows +command-line "netsh" command. This method appears to work correctly +on Windows XP but not Windows 2000.</dd> +<dt><code>ipapi</code></dt> +<dd>Automatically set the IP address and netmask using the Windows IP +Helper API. This approach does not have ideal semantics, though +testing has indicated that it works okay in practice. If you use +this option, it is best to leave the TCP/IP properties for the +TAP-Win32 adapter in their default state, i.e. "Obtain an IP +address automatically."</dd> +<dt><code>adaptive</code> (Default)</dt> +<dd><p class="first">Try <code>dynamic</code> method initially and fail over to <code>netsh</code> +if the DHCP negotiation with the TAP-Win32 adapter does not succeed +in 20 seconds. Such failures have been known to occur when certain +third-party firewall packages installed on the client machine block +the DHCP negotiation used by the TAP-Win32 adapter. Note that if +the <code>netsh</code> failover occurs, the TAP-Win32 adapter TCP/IP +properties will be reset from DHCP to static, and this will cause +future OpenVPN startups using the <code>adaptive</code> mode to use +<code>netsh</code> immediately, rather than trying <code>dynamic</code> first.</p> +<p class="last">To "unstick" the <code>adaptive</code> mode from using <code>netsh</code>, +run OpenVPN at least once using the <code>dynamic</code> mode to restore +the TAP-Win32 adapter TCP/IP properties to a DHCP configuration.</p> +</dd> +</dl> +</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--pause-exit</span></kbd></td> +<td>Put up a "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.</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--register-dns</span></kbd></td> +<td>Run <code>ipconfig /flushdns</code> and <code>ipconfig /registerdns</code> on +connection initiation. This is known to kick Windows into recognizing +pushed DNS servers.</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--route-method <var>m</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Which method <tt class="docutils literal">m</tt> to use for adding routes on Windows?</p> +<dl class="last docutils"> +<dt><code>adaptive</code> (default)</dt> +<dd>Try IP helper API first. If that fails, fall back to the route.exe +shell command.</dd> +<dt><code>ipapi</code></dt> +<dd>Use IP helper API.</dd> +<dt><code>exe</code></dt> +<dd>Call the route.exe shell command.</dd> +</dl> +</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--service <var>args</var></span></kbd></td> +<td><p class="first">Should be used when OpenVPN is being automatically executed by another +program in such a context that no interaction with the user via display +or keyboard is possible.</p> +<p>Valid syntax:</p> +<pre class="literal-block"> +service exit-event [0|1] +</pre> +<p>In general, end-users should never need to explicitly use this option, +as it is automatically added by the OpenVPN service wrapper when a given +OpenVPN configuration is being run as a service.</p> +<p><tt class="docutils literal"><span class="pre">exit-event</span></tt> is the name of a Windows global event object, and OpenVPN +will continuously monitor the state of this event object and exit when +it becomes signaled.</p> +<p>The second parameter indicates the initial state of <tt class="docutils literal"><span class="pre">exit-event</span></tt> and +normally defaults to 0.</p> +<p>Multiple OpenVPN processes can be simultaneously executed with the same +<tt class="docutils literal"><span class="pre">exit-event</span></tt> parameter. In any case, the controlling process can +signal <tt class="docutils literal"><span class="pre">exit-event</span></tt>, causing all such OpenVPN processes to exit.</p> +<p class="last">When executing an OpenVPN process using the <tt class="docutils literal"><span class="pre">--service</span></tt> directive, +OpenVPN will probably not have a console window to output status/error +messages, therefore it is useful to use <tt class="docutils literal"><span class="pre">--log</span></tt> or <tt class="docutils literal"><span class="pre">--log-append</span></tt> to +write these messages to a file.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--show-adapters</span></kbd></td> +</tr> +<tr><td> </td><td>(Standalone) Show available TAP-Win32 adapters which can be selected +using the <tt class="docutils literal"><span class="pre">--dev-node</span></tt> option. On non-Windows systems, the +<tt class="docutils literal">ifconfig</tt>(8) command provides similar functionality.</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--show-net</span></kbd></td> +<td>(Standalone) Show OpenVPN's view of the system routing table and network +adapter list.</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--show-net-up</span></kbd></td> +<td>Output OpenVPN's view of the system routing table and network adapter +list to the syslog or log file after the TUN/TAP adapter has been +brought up and any routes have been added.</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--show-valid-subnets</span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">(Standalone) Show valid subnets for <tt class="docutils literal"><span class="pre">--dev</span> tun</tt> emulation. Since the +TAP-Win32 driver exports an ethernet interface to Windows, and since TUN +devices are point-to-point in nature, it is necessary for the TAP-Win32 +driver to impose certain constraints on TUN endpoint address selection.</p> +<p class="last">Namely, the point-to-point endpoints used in TUN device emulation must +be the middle two addresses of a /30 subnet (netmask 255.255.255.252).</p> +</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--tap-sleep <var>n</var></span></kbd></td> +<td><p class="first">Cause OpenVPN to sleep for <tt class="docutils literal">n</tt> seconds immediately after the TAP-Win32 +adapter state is set to "connected".</p> +<p class="last">This option is intended to be used to troubleshoot problems with the +<tt class="docutils literal"><span class="pre">--ifconfig</span></tt> and <tt class="docutils literal"><span class="pre">--ip-win32</span></tt> options, and is used to give the +TAP-Win32 adapter time to come up before Windows IP Helper API +operations are applied to it.</p> +</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--win-sys <var>path</var></span></kbd></td> +<td><p class="first">Set the Windows system directory pathname to use when looking for system +executables such as <tt class="docutils literal">route.exe</tt> and <tt class="docutils literal">netsh.exe</tt>. By default, if this +directive is not specified, OpenVPN will use the SystemRoot environment +variable.</p> +<p class="last">This option has changed behaviour since OpenVPN 2.3. Earlier you had to +define <tt class="docutils literal"><span class="pre">--win-sys</span> env</tt> to use the SystemRoot environment variable, +otherwise it defaulted to <code>C:\\WINDOWS</code>. It is not needed to use +the <tt class="docutils literal">env</tt> keyword any more, and it will just be ignored. A warning is +logged when this is found in the configuration file.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--windows-driver <var>drv</var></span></kbd></td> +</tr> +<tr><td> </td><td>Specifies which tun driver to use. Values are <code>tap-windows6</code> +(default) and <code>wintun</code>. This is a Windows-only option. +<code>wintun</code>" requires <tt class="docutils literal"><span class="pre">--dev</span> tun</tt> and the OpenVPN process to run +elevated, or be invoked using the Interactive Service.</td></tr> +</tbody> +</table> +</div> +<div class="section" id="standalone-debug-options"> +<h2>Standalone Debug Options</h2> +<table class="docutils option-list" frame="void" rules="none"> +<col class="option" /> +<col class="description" /> +<tbody valign="top"> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--show-gateway <var>args</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">(Standalone) Show current IPv4 and IPv6 default gateway and interface +towards the gateway (if the protocol in question is enabled).</p> +<p>Valid syntax:</p> +<pre class="literal-block"> +--show-gateway +--show-gateway IPv6-target +</pre> +<p class="last">For IPv6 this queries the route towards ::/128, or the specified IPv6 +target address if passed as argument. +For IPv4 on Linux, Windows, MacOS and BSD it looks for a 0.0.0.0/0 route. +If there are more specific routes, the result will not always be matching +the route of the IPv4 packets to the VPN gateway.</p> +</td></tr> +</tbody> +</table> +</div> +<div class="section" id="advanced-expert-options"> +<h2>Advanced Expert Options</h2> +<p>These are options only required when special tweaking is needed, often +used when debugging or testing out special usage scenarios.</p> +<table class="docutils option-list" frame="void" rules="none"> +<col class="option" /> +<col class="description" /> +<tbody valign="top"> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--hash-size <var>args</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Set the size of the real address hash table to <tt class="docutils literal">r</tt> and the virtual +address table to <tt class="docutils literal">v</tt>.</p> +<p>Valid syntax:</p> +<pre class="literal-block"> +hash-size r v +</pre> +<p class="last">By default, both tables are sized at 256 buckets.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--bcast-buffers <var>n</var></span></kbd></td> +</tr> +<tr><td> </td><td>Allocate <tt class="docutils literal">n</tt> buffers for broadcast datagrams (default <code>256</code>).</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--persist-local-ip</span></kbd></td> +</tr> +<tr><td> </td><td>Preserve initially resolved local IP address and port number across +<tt class="docutils literal">SIGUSR1</tt> or <tt class="docutils literal"><span class="pre">--ping-restart</span></tt> restarts.</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--persist-remote-ip</span></kbd></td> +</tr> +<tr><td> </td><td>Preserve most recently authenticated remote IP address and port number +across <code>SIGUSR1</code> or <tt class="docutils literal"><span class="pre">--ping-restart</span></tt> restarts.</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--prng <var>args</var></span></kbd></td> +<td><p class="first"><em>(Advanced)</em> Change the PRNG (Pseudo-random number generator) parameters</p> +<p>Valid syntaxes:</p> +<pre class="literal-block"> +prng alg +prng alg nsl +</pre> +<p>Changes the PRNG to use digest algorithm <strong>alg</strong> (default <code>sha1</code>), +and set <tt class="docutils literal">nsl</tt> (default <code>16</code>) to the size in bytes of the nonce +secret length (between 16 and 64).</p> +<p class="last">Set <tt class="docutils literal">alg</tt> to <code>none</code> to disable the PRNG and use the OpenSSL +RAND_bytes function instead for all of OpenVPN's pseudo-random number +needs.</p> +</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--rcvbuf <var>size</var></span></kbd></td> +<td>Set the TCP/UDP socket receive buffer size. Defaults to operating system +default.</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--shaper <var>n</var></span></kbd></td> +<td><p class="first">Limit bandwidth of outgoing tunnel data to <tt class="docutils literal">n</tt> bytes per second on the +TCP/UDP port. Note that this will only work if mode is set to +<code>p2p</code>. If you want to limit the bandwidth in both directions, use +this option on both peers.</p> +<p>OpenVPN uses the following algorithm to implement traffic shaping: Given +a shaper rate of <tt class="docutils literal">n</tt> bytes per second, after a datagram write of <tt class="docutils literal">b</tt> +bytes is queued on the TCP/UDP port, wait a minimum of <tt class="docutils literal">(b / n)</tt> +seconds before queuing the next write.</p> +<p>It should be noted that OpenVPN supports multiple tunnels between the +same two peers, allowing you to construct full-speed and reduced +bandwidth tunnels at the same time, routing low-priority data such as +off-site backups over the reduced bandwidth tunnel, and other data over +the full-speed tunnel.</p> +<p>Also note that for low bandwidth tunnels (under 1000 bytes per second), +you should probably use lower MTU values as well (see above), otherwise +the packet latency will grow so large as to trigger timeouts in the TLS +layer and TCP connections running over the tunnel.</p> +<p class="last">OpenVPN allows <tt class="docutils literal">n</tt> to be between 100 bytes/sec and 100 Mbytes/sec.</p> +</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--sndbuf <var>size</var></span></kbd></td> +<td>Set the TCP/UDP socket send buffer size. Defaults to operating system +default.</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--tcp-queue-limit <var>n</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Maximum number of output packets queued before TCP (default <code>64</code>).</p> +<p class="last">When OpenVPN is tunneling data from a TUN/TAP device to a remote client +over a TCP connection, it is possible that the TUN/TAP device might +produce data at a faster rate than the TCP connection can support. When +the number of output packets queued before sending to the TCP socket +reaches this limit for a given client connection, OpenVPN will start to +drop outgoing packets directed at this client.</p> +</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--txqueuelen <var>n</var></span></kbd></td> +<td><em>(Linux only)</em> Set the TX queue length on the TUN/TAP interface. +Currently defaults to operating system default.</td></tr> +</tbody> +</table> +</div> +</div> +<div class="section" id="unsupported-options"> +<h1>UNSUPPORTED OPTIONS</h1> +<p>Options listed in this section have been removed from OpenVPN and are no +longer supported</p> +<table class="docutils option-list" frame="void" rules="none"> +<col class="option" /> +<col class="description" /> +<tbody valign="top"> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--client-cert-not-required</span></kbd></td> +</tr> +<tr><td> </td><td>Removed in OpenVPN 2.5. This should be replaxed with +<tt class="docutils literal"><span class="pre">--verify-client-cert</span> none</tt>.</td></tr> +<tr><td class="option-group" colspan="2"> +<kbd><span class="option">--ifconfig-pool-linear</span></kbd></td> +</tr> +<tr><td> </td><td>Removed in OpenVPN 2.5. This should be replaced with <tt class="docutils literal"><span class="pre">--topology</span> p2p</tt>.</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--key-method</span></kbd></td> +<td>Removed in OpenVPN 2.5. This option should not be used, as using the old +<tt class="docutils literal"><span class="pre">key-method</span></tt> weakens the VPN tunnel security. The old <tt class="docutils literal"><span class="pre">key-method</span></tt> +was also only needed when the remote side was older than OpenVPN 2.0.</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--no-iv</span></kbd></td> +<td>Removed in OpenVPN 2.5. This option should not be used as it weakens the +VPN tunnel security. This has been a NOOP option since OpenVPN 2.4.</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--no-replay</span></kbd></td> +<td>Removed in OpenVPN 2.5. This option should not be used as it weakens the +VPN tunnel security.</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--ns-cert-type</span></kbd></td> +<td>Removed in OpenVPN 2.5. The <tt class="docutils literal">nsCertType</tt> field is no longer supported +in recent SSL/TLS libraries. If your certificates does not include <em>key +usage</em> and <em>extended key usage</em> fields, they must be upgraded and the +<tt class="docutils literal"><span class="pre">--remote-cert-tls</span></tt> option should be used instead.</td></tr> +</tbody> +</table> +</div> +<div class="section" id="connection-profiles"> +<h1>CONNECTION PROFILES</h1> +<p>Client configuration files may contain multiple remote servers which +it will attempt to connect against. But there are some configuration +options which are related to specific <tt class="docutils literal"><span class="pre">--remote</span></tt> options. For these +use cases, connection profiles are the solution.</p> +<p>By enacpulating the <tt class="docutils literal"><span class="pre">--remote</span></tt> option and related options within +<tt class="docutils literal"><connection></tt> and <tt class="docutils literal"></connection></tt>, these options are handled as a +group.</p> +<p>An OpenVPN client will try each connection profile sequentially until it +achieves a successful connection.</p> +<p><tt class="docutils literal"><span class="pre">--remote-random</span></tt> can be used to initially "scramble" the connection +list.</p> +<p>Here is an example of connection profile usage:</p> +<pre class="literal-block"> +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 +</pre> +<p>First we try to connect to a server at 198.19.34.56:1194 using UDP. If +that fails, we then try to connect to 198.19.34.56:443 using TCP. If +that also fails, then try connecting through an HTTP proxy at +192.168.0.8:8080 to 198.19.34.56:443 using TCP. Finally, try to connect +through the same proxy to a server at 198.19.36.99:443 using TCP.</p> +<p>The following OpenVPN options may be used inside of a <tt class="docutils literal"><connection></tt> +block:</p> +<p><tt class="docutils literal">bind</tt>, <tt class="docutils literal"><span class="pre">connect-retry</span></tt>, <tt class="docutils literal"><span class="pre">connect-retry-max</span></tt>, <tt class="docutils literal"><span class="pre">connect-timeout</span></tt>, +<tt class="docutils literal"><span class="pre">explicit-exit-notify</span></tt>, <tt class="docutils literal">float</tt>, <tt class="docutils literal">fragment</tt>, <tt class="docutils literal"><span class="pre">http-proxy</span></tt>, +<tt class="docutils literal"><span class="pre">http-proxy-option</span></tt>, <tt class="docutils literal"><span class="pre">key-direction</span></tt>, <tt class="docutils literal"><span class="pre">link-mtu</span></tt>, <tt class="docutils literal">local</tt>, +<tt class="docutils literal">lport</tt>, <tt class="docutils literal">mssfix</tt>, <tt class="docutils literal"><span class="pre">mtu-disc</span></tt>, <tt class="docutils literal">nobind</tt>, <tt class="docutils literal">port</tt>, <tt class="docutils literal">proto</tt>, +<tt class="docutils literal">remote</tt>, <tt class="docutils literal">rport</tt>, <tt class="docutils literal"><span class="pre">socks-proxy</span></tt>, <tt class="docutils literal"><span class="pre">tls-auth</span></tt>, <tt class="docutils literal"><span class="pre">tls-crypt</span></tt>, +<tt class="docutils literal"><span class="pre">tun-mtu</span> and</tt>, <tt class="docutils literal"><span class="pre">tun-mtu-extra</span></tt>.</p> +<p>A defaulting mechanism exists for specifying options to apply to all +<tt class="docutils literal"><connection></tt> profiles. If any of the above options (with the +exception of <tt class="docutils literal">remote</tt> ) appear outside of a <tt class="docutils literal"><connection></tt> block, +but in a configuration file which has one or more <tt class="docutils literal"><connection></tt> +blocks, the option setting will be used as a default for +<tt class="docutils literal"><connection></tt> blocks which follow it in the configuration file.</p> +<p>For example, suppose the <tt class="docutils literal">nobind</tt> option were placed in the sample +configuration file above, near the top of the file, before the first +<tt class="docutils literal"><connection></tt> block. The effect would be as if <tt class="docutils literal">nobind</tt> were +declared in all <tt class="docutils literal"><connection></tt> blocks below it.</p> +</div> +<div class="section" id="inline-file-support"> +<h1>INLINE FILE SUPPORT</h1> +<p>OpenVPN allows including files in the main configuration for the <tt class="docutils literal"><span class="pre">--ca</span></tt>, +<tt class="docutils literal"><span class="pre">--cert</span></tt>, <tt class="docutils literal"><span class="pre">--dh</span></tt>, <tt class="docutils literal"><span class="pre">--extra-certs</span></tt>, <tt class="docutils literal"><span class="pre">--key</span></tt>, <tt class="docutils literal"><span class="pre">--pkcs12</span></tt>, +<tt class="docutils literal"><span class="pre">--secret</span></tt>, <tt class="docutils literal"><span class="pre">--crl-verify</span></tt>, <tt class="docutils literal"><span class="pre">--http-proxy-user-pass</span></tt>, <tt class="docutils literal"><span class="pre">--tls-auth</span></tt>, +<tt class="docutils literal"><span class="pre">--auth-gen-token-secret</span></tt>, <tt class="docutils literal"><span class="pre">--tls-crypt</span></tt> and <tt class="docutils literal"><span class="pre">--tls-crypt-v2</span></tt> +options.</p> +<p>Each inline file started by the line <tt class="docutils literal"><option></tt> and ended by the line +<tt class="docutils literal"></option></tt></p> +<p>Here is an example of an inline file usage</p> +<pre class="literal-block"> +<cert> +-----BEGIN CERTIFICATE----- +[...] +-----END CERTIFICATE----- +</cert> +</pre> +<p>When using the inline file feature with <tt class="docutils literal"><span class="pre">--pkcs12</span></tt> the inline file has +to be base64 encoded. Encoding of a .p12 file into base64 can be done +for example with OpenSSL by running <code>openssl base64 -in input.p12</code></p> +</div> +<div class="section" id="signals"> +<h1>SIGNALS</h1> +<dl class="docutils"> +<dt><code>SIGHUP</code></dt> +<dd>Cause OpenVPN to close all TUN/TAP and network connections, restart, +re-read the configuration file (if any), and reopen TUN/TAP and network +connections.</dd> +<dt><code>SIGUSR1</code></dt> +<dd><p class="first">Like <code>SIGHUP`</code>, except don't re-read configuration file, and +possibly don't close and reopen TUN/TAP device, re-read key files, +preserve local IP address/port, or preserve most recently authenticated +remote IP address/port based on <tt class="docutils literal"><span class="pre">--persist-tun</span></tt>, <tt class="docutils literal"><span class="pre">--persist-key</span></tt>, +<tt class="docutils literal"><span class="pre">--persist-local-ip</span></tt> and <tt class="docutils literal"><span class="pre">--persist-remote-ip</span></tt> options respectively +(see above).</p> +<p>This signal may also be internally generated by a timeout condition, +governed by the <tt class="docutils literal"><span class="pre">--ping-restart</span></tt> option.</p> +<p class="last">This signal, when combined with <tt class="docutils literal"><span class="pre">--persist-remote-ip</span></tt>, may be sent +when the underlying parameters of the host's network interface change +such as when the host is a DHCP client and is assigned a new IP address. +See <tt class="docutils literal"><span class="pre">--ipchange</span></tt> for more information.</p> +</dd> +<dt><code>SIGUSR2</code></dt> +<dd>Causes OpenVPN to display its current statistics (to the syslog file if +<tt class="docutils literal"><span class="pre">--daemon</span></tt> is used, or stdout otherwise).</dd> +<dt><code>SIGINT</code>, <code>SIGTERM</code></dt> +<dd>Causes OpenVPN to exit gracefully.</dd> +</dl> +</div> +<div class="section" id="faq"> +<h1>FAQ</h1> +<p><a class="reference external" href="https://community.openvpn.net/openvpn/wiki/FAQ">https://community.openvpn.net/openvpn/wiki/FAQ</a></p> +</div> +<div class="section" id="howto"> +<h1>HOWTO</h1> +<p>For a more comprehensive guide to setting up OpenVPN in a production +setting, see the OpenVPN HOWTO at +<a class="reference external" href="https://openvpn.net/community-resources/how-to/">https://openvpn.net/community-resources/how-to/</a></p> +</div> +<div class="section" id="protocol"> +<h1>PROTOCOL</h1> +<p>For a description of OpenVPN's underlying protocol, see +<a class="reference external" href="https://openvpn.net/community-resources/openvpn-protocol/">https://openvpn.net/community-resources/openvpn-protocol/</a></p> +</div> +<div class="section" id="web"> +<h1>WEB</h1> +<p>OpenVPN's web site is at <a class="reference external" href="https://openvpn.net/">https://openvpn.net/</a></p> +<p>Go here to download the latest version of OpenVPN, subscribe to the +mailing lists, read the mailing list archives, or browse the SVN +repository.</p> +</div> +<div class="section" id="bugs"> +<h1>BUGS</h1> +<p>Report all bugs to the OpenVPN team <a class="reference external" href="mailto:info@openvpn.net">info@openvpn.net</a></p> +</div> +<div class="section" id="see-also"> +<h1>SEE ALSO</h1> +<p><tt class="docutils literal"><span class="pre">openvpn-examples</span></tt>(5), +<tt class="docutils literal">dhcpcd</tt>(8), +<tt class="docutils literal">ifconfig</tt>(8), +<tt class="docutils literal">openssl</tt>(1), +<tt class="docutils literal">route</tt>(8), +<tt class="docutils literal">scp</tt>(1) +<tt class="docutils literal">ssh</tt>(1)</p> +</div> +<div class="section" id="notes"> +<h1>NOTES</h1> +<p>This product includes software developed by the OpenSSL Project +(<a class="reference external" href="https://www.openssl.org/">https://www.openssl.org/</a>)</p> +<p>For more information on the TLS protocol, see +<a class="reference external" href="http://www.ietf.org/rfc/rfc2246.txt">http://www.ietf.org/rfc/rfc2246.txt</a></p> +<p>For more information on the LZO real-time compression library see +<a class="reference external" href="https://www.oberhumer.com/opensource/lzo/">https://www.oberhumer.com/opensource/lzo/</a></p> +</div> +<div class="section" id="copyright"> +<h1>COPYRIGHT</h1> +<p>Copyright (C) 2002-2020 OpenVPN Inc This program is free software; you +can redistribute it and/or modify it under the terms of the GNU General +Public License version 2 as published by the Free Software Foundation.</p> +</div> +<div class="section" id="authors"> +<h1>AUTHORS</h1> +<p>James Yonan <a class="reference external" href="mailto:james@openvpn.net">james@openvpn.net</a></p> +</div> +</div> +</body> +</html> diff --git a/doc/openvpn.8.rst b/doc/openvpn.8.rst new file mode 100644 index 0000000..9954674 --- /dev/null +++ b/doc/openvpn.8.rst @@ -0,0 +1,170 @@ +========= + 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. + +.. include:: man-sections/generic-options.rst +.. include:: man-sections/log-options.rst +.. include:: man-sections/protocol-options.rst +.. include:: man-sections/client-options.rst +.. include:: man-sections/server-options.rst +.. include:: man-sections/encryption-options.rst +.. include:: man-sections/cipher-negotiation.rst +.. include:: man-sections/network-config.rst +.. include:: man-sections/script-options.rst +.. include:: man-sections/management-options.rst +.. include:: man-sections/plugin-options.rst +.. include:: man-sections/windows-options.rst +.. include:: man-sections/advanced-options.rst +.. include:: man-sections/unsupported-options.rst +.. include:: man-sections/connection-profiles.rst +.. include:: man-sections/inline-files.rst +.. include:: man-sections/signals.rst + + +FAQ +=== + +https://community.openvpn.net/openvpn/wiki/FAQ + + + +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 +======== + +``openvpn-examples``\(5), +``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/ + + + +COPYRIGHT +========= + +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. + +AUTHORS +======= + +James Yonan james@openvpn.net |