diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Makefile.am | 31 | ||||
| -rw-r--r-- | doc/Makefile.in | 552 | ||||
| -rw-r--r-- | doc/README.plugins | 47 | ||||
| -rw-r--r-- | doc/management-notes.txt | 1039 | ||||
| -rw-r--r-- | doc/openvpn.8 | 6439 |
5 files changed, 8108 insertions, 0 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am new file mode 100644 index 0000000..d33e1ed --- /dev/null +++ b/doc/Makefile.am @@ -0,0 +1,31 @@ +# +# OpenVPN -- An application to securely tunnel IP networks +# over a single UDP port, with support for SSL/TLS-based +# session authentication and key exchange, +# packet encryption, packet authentication, and +# packet compression. +# +# Copyright (C) 2002-2010 OpenVPN Technologies, Inc. <sales@openvpn.net> +# Copyright (C) 2006-2012 Alon Bar-Lev <alon.barlev@gmail.com> +# + +MAINTAINERCLEANFILES = \ + $(srcdir)/Makefile.in + +CLEANFILES = openvpn.8.html + +dist_doc_DATA = \ + management-notes.txt + +dist_noinst_DATA = \ + README.plugins + +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 +endif + diff --git a/doc/Makefile.in b/doc/Makefile.in new file mode 100644 index 0000000..4371dc4 --- /dev/null +++ b/doc/Makefile.in @@ -0,0 +1,552 @@ +# Makefile.in generated by automake 1.11.1 from Makefile.am. +# @configure_input@ + +# Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, +# 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, +# Inc. +# This Makefile.in is free software; the Free Software Foundation +# gives unlimited permission to copy and/or distribute it, +# with or without modifications, as long as this notice is preserved. + +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY, to the extent permitted by law; without +# even the implied warranty of MERCHANTABILITY or FITNESS FOR A +# PARTICULAR PURPOSE. + +@SET_MAKE@ + +# +# OpenVPN -- An application to securely tunnel IP networks +# over a single UDP port, with support for SSL/TLS-based +# session authentication and key exchange, +# packet encryption, packet authentication, and +# packet compression. +# +# Copyright (C) 2002-2010 OpenVPN Technologies, Inc. <sales@openvpn.net> +# Copyright (C) 2006-2012 Alon Bar-Lev <alon.barlev@gmail.com> +# + +VPATH = @srcdir@ +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@ +@WIN32_TRUE@am__append_1 = openvpn.8 +subdir = doc +DIST_COMMON = $(am__dist_noinst_DATA_DIST) $(dist_doc_DATA) \ + $(dist_man_MANS) $(srcdir)/Makefile.am $(srcdir)/Makefile.in +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) +mkinstalldirs = $(install_sh) -d +CONFIG_HEADER = $(top_builddir)/config.h +CONFIG_CLEAN_FILES = +CONFIG_CLEAN_VPATH_FILES = +SOURCES = +DIST_SOURCES = +am__vpath_adj_setup = srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; +am__vpath_adj = case $$p in \ + $(srcdir)/*) f=`echo "$$p" | sed "s|^$$srcdirstrip/||"`;; \ + *) f=$$p;; \ + esac; +am__strip_dir = f=`echo $$p | sed -e 's|^.*/||'`; +am__install_max = 40 +am__nobase_strip_setup = \ + srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*|]/\\\\&/g'` +am__nobase_strip = \ + for p in $$list; do echo "$$p"; done | sed -e "s|$$srcdirstrip/||" +am__nobase_list = $(am__nobase_strip_setup); \ + for p in $$list; do echo "$$p $$p"; done | \ + sed "s| $$srcdirstrip/| |;"' / .*\//!s/ .*/ ./; s,\( .*\)/[^/]*$$,\1,' | \ + $(AWK) 'BEGIN { files["."] = "" } { files[$$2] = files[$$2] " " $$1; \ + if (++n[$$2] == $(am__install_max)) \ + { print $$2, files[$$2]; n[$$2] = 0; files[$$2] = "" } } \ + END { for (dir in files) print dir, files[dir] }' +am__base_list = \ + sed '$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;s/\n/ /g' | \ + sed '$$!N;$$!N;$$!N;$$!N;s/\n/ /g' +man8dir = $(mandir)/man8 +am__installdirs = "$(DESTDIR)$(man8dir)" "$(DESTDIR)$(docdir)" \ + "$(DESTDIR)$(htmldir)" +NROFF = nroff +MANS = $(dist_man_MANS) +am__dist_noinst_DATA_DIST = README.plugins openvpn.8 +DATA = $(dist_doc_DATA) $(dist_noinst_DATA) $(nodist_html_DATA) +DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST) +ACLOCAL = @ACLOCAL@ +AMTAR = @AMTAR@ +AR = @AR@ +AS = @AS@ +AUTOCONF = @AUTOCONF@ +AUTOHEADER = @AUTOHEADER@ +AUTOMAKE = @AUTOMAKE@ +AWK = @AWK@ +CC = @CC@ +CCDEPMODE = @CCDEPMODE@ +CFLAGS = @CFLAGS@ +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@ +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@ +LZO_CFLAGS = @LZO_CFLAGS@ +LZO_LIBS = @LZO_LIBS@ +MAKEINFO = @MAKEINFO@ +MAN2HTML = @MAN2HTML@ +MKDIR_P = @MKDIR_P@ +NETSTAT = @NETSTAT@ +NM = @NM@ +NMEDIT = @NMEDIT@ +OBJDUMP = @OBJDUMP@ +OBJEXT = @OBJEXT@ +OPENSSL_CRYPTO_CFLAGS = @OPENSSL_CRYPTO_CFLAGS@ +OPENSSL_CRYPTO_LIBS = @OPENSSL_CRYPTO_LIBS@ +OPENSSL_SSL_CFLAGS = @OPENSSL_SSL_CFLAGS@ +OPENSSL_SSL_LIBS = @OPENSSL_SSL_LIBS@ +OPTIONAL_CRYPTO_CFLAGS = @OPTIONAL_CRYPTO_CFLAGS@ +OPTIONAL_CRYPTO_LIBS = @OPTIONAL_CRYPTO_LIBS@ +OPTIONAL_DL_LIBS = @OPTIONAL_DL_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@ +OTOOL = @OTOOL@ +OTOOL64 = @OTOOL64@ +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@ +PLUGIN_AUTH_PAM_CFLAGS = @PLUGIN_AUTH_PAM_CFLAGS@ +PLUGIN_AUTH_PAM_LIBS = @PLUGIN_AUTH_PAM_LIBS@ +POLARSSL_CFLAGS = @POLARSSL_CFLAGS@ +POLARSSL_LIBS = @POLARSSL_LIBS@ +RANLIB = @RANLIB@ +RC = @RC@ +ROUTE = @ROUTE@ +SED = @SED@ +SELINUX_LIBS = @SELINUX_LIBS@ +SET_MAKE = @SET_MAKE@ +SHELL = @SHELL@ +SOCKETS_LIBS = @SOCKETS_LIBS@ +STRIP = @STRIP@ +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@ +VERSION = @VERSION@ +abs_builddir = @abs_builddir@ +abs_srcdir = @abs_srcdir@ +abs_top_builddir = @abs_top_builddir@ +abs_top_srcdir = @abs_top_srcdir@ +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@ +localedir = @localedir@ +localstatedir = @localstatedir@ +mandir = @mandir@ +mkdir_p = @mkdir_p@ +oldincludedir = @oldincludedir@ +pdfdir = @pdfdir@ +plugindir = @plugindir@ +prefix = @prefix@ +program_transform_name = @program_transform_name@ +psdir = @psdir@ +sampledir = @sampledir@ +sbindir = @sbindir@ +sharedstatedir = @sharedstatedir@ +srcdir = @srcdir@ +sysconfdir = @sysconfdir@ +target_alias = @target_alias@ +top_build_prefix = @top_build_prefix@ +top_builddir = @top_builddir@ +top_srcdir = @top_srcdir@ +MAINTAINERCLEANFILES = \ + $(srcdir)/Makefile.in + +CLEANFILES = openvpn.8.html +dist_doc_DATA = \ + management-notes.txt + +dist_noinst_DATA = README.plugins $(am__append_1) +@WIN32_TRUE@nodist_html_DATA = openvpn.8.html +@WIN32_FALSE@dist_man_MANS = openvpn.8 +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) --gnu doc/Makefile'; \ + $(am__cd) $(top_srcdir) && \ + $(AUTOMAKE) --gnu doc/Makefile +.PRECIOUS: 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__depfiles_maybe)'; \ + cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe);; \ + esac; + +$(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh + +$(top_srcdir)/configure: $(am__configure_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +$(ACLOCAL_M4): $(am__aclocal_m4_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +$(am__aclocal_m4_deps): + +mostlyclean-libtool: + -rm -f *.lo + +clean-libtool: + -rm -rf .libs _libs +install-man8: $(dist_man_MANS) + @$(NORMAL_INSTALL) + test -z "$(man8dir)" || $(MKDIR_P) "$(DESTDIR)$(man8dir)" + @list=''; test -n "$(man8dir)" || exit 0; \ + { for i in $$list; do echo "$$i"; done; \ + l2='$(dist_man_MANS)'; for i in $$l2; do echo "$$i"; done | \ + sed -n '/\.8[a-z]*$$/p'; \ + } | while read p; do \ + if test -f $$p; then d=; else d="$(srcdir)/"; fi; \ + echo "$$d$$p"; echo "$$p"; \ + done | \ + sed -e 'n;s,.*/,,;p;h;s,.*\.,,;s,^[^8][0-9a-z]*$$,8,;x' \ + -e 's,\.[0-9a-z]*$$,,;$(transform);G;s,\n,.,' | \ + sed 'N;N;s,\n, ,g' | { \ + list=; while read file base inst; do \ + if test "$$base" = "$$inst"; then list="$$list $$file"; else \ + echo " $(INSTALL_DATA) '$$file' '$(DESTDIR)$(man8dir)/$$inst'"; \ + $(INSTALL_DATA) "$$file" "$(DESTDIR)$(man8dir)/$$inst" || exit $$?; \ + fi; \ + done; \ + for i in $$list; do echo "$$i"; done | $(am__base_list) | \ + while read files; do \ + test -z "$$files" || { \ + echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(man8dir)'"; \ + $(INSTALL_DATA) $$files "$(DESTDIR)$(man8dir)" || exit $$?; }; \ + done; } + +uninstall-man8: + @$(NORMAL_UNINSTALL) + @list=''; test -n "$(man8dir)" || exit 0; \ + files=`{ for i in $$list; do echo "$$i"; done; \ + l2='$(dist_man_MANS)'; for i in $$l2; do echo "$$i"; done | \ + sed -n '/\.8[a-z]*$$/p'; \ + } | sed -e 's,.*/,,;h;s,.*\.,,;s,^[^8][0-9a-z]*$$,8,;x' \ + -e 's,\.[0-9a-z]*$$,,;$(transform);G;s,\n,.,'`; \ + test -z "$$files" || { \ + echo " ( cd '$(DESTDIR)$(man8dir)' && rm -f" $$files ")"; \ + cd "$(DESTDIR)$(man8dir)" && rm -f $$files; } +install-dist_docDATA: $(dist_doc_DATA) + @$(NORMAL_INSTALL) + test -z "$(docdir)" || $(MKDIR_P) "$(DESTDIR)$(docdir)" + @list='$(dist_doc_DATA)'; test -n "$(docdir)" || list=; \ + for p in $$list; do \ + if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ + echo "$$d$$p"; \ + done | $(am__base_list) | \ + while read files; do \ + echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(docdir)'"; \ + $(INSTALL_DATA) $$files "$(DESTDIR)$(docdir)" || exit $$?; \ + done + +uninstall-dist_docDATA: + @$(NORMAL_UNINSTALL) + @list='$(dist_doc_DATA)'; test -n "$(docdir)" || list=; \ + files=`for p in $$list; do echo $$p; done | sed -e 's|^.*/||'`; \ + test -n "$$files" || exit 0; \ + echo " ( cd '$(DESTDIR)$(docdir)' && rm -f" $$files ")"; \ + cd "$(DESTDIR)$(docdir)" && rm -f $$files +install-nodist_htmlDATA: $(nodist_html_DATA) + @$(NORMAL_INSTALL) + test -z "$(htmldir)" || $(MKDIR_P) "$(DESTDIR)$(htmldir)" + @list='$(nodist_html_DATA)'; test -n "$(htmldir)" || list=; \ + for p in $$list; do \ + if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ + echo "$$d$$p"; \ + done | $(am__base_list) | \ + while read files; do \ + echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(htmldir)'"; \ + $(INSTALL_DATA) $$files "$(DESTDIR)$(htmldir)" || exit $$?; \ + done + +uninstall-nodist_htmlDATA: + @$(NORMAL_UNINSTALL) + @list='$(nodist_html_DATA)'; test -n "$(htmldir)" || list=; \ + files=`for p in $$list; do echo $$p; done | sed -e 's|^.*/||'`; \ + test -n "$$files" || exit 0; \ + echo " ( cd '$(DESTDIR)$(htmldir)' && rm -f" $$files ")"; \ + cd "$(DESTDIR)$(htmldir)" && rm -f $$files +tags: TAGS +TAGS: + +ctags: CTAGS +CTAGS: + + +distdir: $(DISTFILES) + @list='$(MANS)'; if test -n "$$list"; then \ + list=`for p in $$list; do \ + if test -f $$p; then d=; else d="$(srcdir)/"; fi; \ + if test -f "$$d$$p"; then echo "$$d$$p"; else :; fi; done`; \ + if test -n "$$list" && \ + grep 'ab help2man is required to generate this page' $$list >/dev/null; then \ + echo "error: found man pages containing the \`missing help2man' replacement text:" >&2; \ + grep -l 'ab help2man is required to generate this page' $$list | sed 's/^/ /' >&2; \ + echo " to fix them, install help2man, remove and regenerate the man pages;" >&2; \ + echo " typically \`make maintainer-clean' will remove them" >&2; \ + exit 1; \ + else :; fi; \ + else :; fi + @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 $(MANS) $(DATA) +installdirs: + for dir in "$(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-am: all-am + @$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am + +installcheck: installcheck-am +install-strip: + $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ + install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ + `test -z '$(STRIP)' || \ + echo "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'"` install +mostlyclean-generic: + +clean-generic: + -test -z "$(CLEANFILES)" || rm -f $(CLEANFILES) + +distclean-generic: + -test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES) + -test . = "$(srcdir)" || test -z "$(CONFIG_CLEAN_VPATH_FILES)" || rm -f $(CONFIG_CLEAN_VPATH_FILES) + +maintainer-clean-generic: + @echo "This command is intended for maintainers to use" + @echo "it deletes files that may require special tools to rebuild." + -test -z "$(MAINTAINERCLEANFILES)" || rm -f $(MAINTAINERCLEANFILES) +clean: clean-am + +clean-am: clean-generic clean-libtool 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-dist_docDATA install-man \ + install-nodist_htmlDATA + +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-man8 + +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: uninstall-dist_docDATA uninstall-man \ + uninstall-nodist_htmlDATA + +uninstall-man: uninstall-man8 + +.MAKE: install-am install-strip + +.PHONY: all all-am check check-am clean clean-generic clean-libtool \ + 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 uninstall uninstall-am \ + uninstall-dist_docDATA uninstall-man uninstall-man8 \ + uninstall-nodist_htmlDATA + +@WIN32_TRUE@openvpn.8.html: $(srcdir)/openvpn.8 +@WIN32_TRUE@ $(MAN2HTML) < $(srcdir)/openvpn.8 > openvpn.8.html + +# Tell versions [3.59,3.63) of GNU make to not export all variables. +# Otherwise a system limit (for SysV at least) may be exceeded. +.NOEXPORT: diff --git a/doc/README.plugins b/doc/README.plugins new file mode 100644 index 0000000..6e490c5 --- /dev/null +++ b/doc/README.plugins @@ -0,0 +1,47 @@ +OpenVPN Plugins +--------------- + +Starting with OpenVPN 2.0-beta17, compiled plugin modules are +supported on any *nix OS which includes libdl or on Windows. +One or more modules may be loaded into OpenVPN using +the --plugin directive, and each plugin module is capable of +intercepting any of the script callbacks which OpenVPN supports: + +(1) up +(2) down +(3) route-up +(4) ipchange +(5) tls-verify +(6) auth-user-pass-verify +(7) client-connect +(8) client-disconnect +(9) learn-address + +See the openvpn-plugin.h file in the top-level directory of the +OpenVPN source distribution for more detailed information +on the plugin interface. + +Included Plugins +---------------- + +auth-pam -- Authenticate using PAM and a split privilege + execution model which functions even if + root privileges or the execution environment + have been altered with --user/--group/--chroot. + Tested on Linux only. + +down-root -- Enable the running of down scripts with root privileges + even if --user/--group/--chroot have been used + to drop root privileges or change the execution + environment. Not applicable on Windows. + +examples -- A simple example that demonstrates a portable + plugin, i.e. one which can be built for *nix + or Windows from the same source. + +Building Plugins +---------------- + +cd to the top-level directory of a plugin, and use the +"make" command to build it. The examples plugin is +built using a build script, not a makefile. diff --git a/doc/management-notes.txt b/doc/management-notes.txt new file mode 100644 index 0000000..79e71ad --- /dev/null +++ b/doc/management-notes.txt @@ -0,0 +1,1039 @@ +OpenVPN Management Interface Notes +---------------------------------- + +The OpenVPN Management interface allows OpenVPN to +be administratively controlled from an external program via +a TCP or unix domain socket. + +The interface has been specifically designed for developers +who would like to programmatically or remotely control +an OpenVPN daemon, and can be used when OpenVPN is running +as a client or server. + +The management interface is implemented using a client/server TCP +connection or unix domain socket where OpenVPN will listen on a +provided IP address and port for incoming management client connections. + +The management protocol is currently cleartext without an explicit +security layer. For this reason, it is recommended that the +management interface either listen on a unix domain socket, +localhost (127.0.0.1), or on the local VPN address. It's possible +to remotely connect to the management interface over the VPN itself, +though some capabilities will be limited in this mode, such as the +ability to provide private key passwords. + +The management interface is enabled in the OpenVPN +configuration file using the following directive: + +--management + +See the man page for documentation on this and related +directives. + +Once OpenVPN has started with the management layer enabled, +you can telnet to the management port (make sure to use +a telnet client which understands "raw" mode). + +Once connected to the management port, you can use +the "help" command to list all commands. + +COMMAND -- bytecount +-------------------- + +The bytecount command is used to request real-time notification +of OpenVPN bandwidth usage. + +Command syntax: + + bytecount n (where n > 0) -- set up automatic notification of + bandwidth usage once every n seconds + bytecount 0 -- turn off bytecount notifications + +If OpenVPN is running as a client, the bytecount notification +will look like this: + + >BYTECOUNT:{BYTES_IN},{BYTES_OUT} + +BYTES_IN is the number of bytes that have been received from +the server and BYTES_OUT is the number of bytes that have been +sent to the server. + +If OpenVPN is running as a server, the bytecount notification +will look like this: + + >BYTECOUNT_CLI:{CID},{BYTES_IN},{BYTES_OUT} + +CID is the Client ID, BYTES_IN is the number of bytes that have +been received from the client and BYTES_OUT is the number of +bytes that have been sent to the client. + +Note that when the bytecount command is used on the server, every +connected client will report its bandwidth numbers once every n +seconds. + +When the client disconnects, the final bandwidth numbers will be +placed in the 'bytes_received' and 'bytes_sent' environmental variables +as included in the >CLIENT:DISCONNECT notification. + +COMMAND -- echo +--------------- + +The echo capability is used to allow GUI-specific +parameters to be either embedded in the OpenVPN config file +or pushed to an OpenVPN client from a server. + +Command examples: + + echo on -- turn on real-time notification of echo messages + echo all -- print the current echo history list + echo off -- turn off real-time notification of echo messages + echo on all -- atomically enable real-time notification, + plus show any messages in history buffer + +For example, suppose you are developing a OpenVPN GUI and +you want to give the OpenVPN server the ability to ask +the GUI to forget any saved passwords. + +In the OpenVPN server config file, add: + + push "echo forget-passwords" + +When the OpenVPN client receives its pulled list of directives +from the server, the "echo forget-passwords" directive will +be in the list, and it will cause the management interface +to save the "forget-passwords" string in its list of echo +parameters. + +The management client can use "echo all" to output the full +list of echoed parameters, "echo on" to turn on real-time +notification of echoed parameters via the ">ECHO:" prefix, +or "echo off" to turn off real-time notification. + +When the GUI connects to the OpenVPN management socket, it +can issue an "echo all" command, which would produce output +like this: + + 1101519562,forget-passwords + END + +Essentially the echo command allowed us to pass parameters from +the OpenVPN server to the OpenVPN client, and then to the +management client (such as a GUI). The large integer is the +unix date/time when the echo parameter was received. + +If the management client had issued the command "echo on", +it would have enabled real-time notifications of echo +parameters. In this case, our "forget-passwords" message +would be output like this: + + >ECHO:1101519562,forget-passwords + +Like the log command, the echo command can atomically show +history while simultaneously activating real-time updates: + + echo on all + +The size of the echo buffer is currently hardcoded to 100 +messages. + +COMMAND -- exit, quit +--------------------- + +Close the managment session, and resume listening on the +management port for connections from other clients. Currently, +the OpenVPN daemon can at most support a single management client +any one time. + +COMMAND -- help +--------------- + +Print a summary of commands. + +COMMAND -- hold +--------------- + +The hold command can be used to manipulate the hold flag, +or release OpenVPN from a hold state. + +If the hold flag is set on initial startup or +restart, OpenVPN will hibernate prior to initializing +the tunnel until the management interface receives +a "hold release" command. + +The --management-hold directive of OpenVPN can be used +to start OpenVPN with the hold flag set. + +The hold flag setting is persistent and will not +be reset by restarts. + +OpenVPN will indicate that it is in a hold state by +sending a real-time notification to the management +client: + + >HOLD:Waiting for hold release + +Command examples: + + hold -- show current hold flag, 0=off, 1=on. + hold on -- turn on hold flag so that future restarts + will hold. + hold off -- turn off hold flag so that future restarts will + not hold. + hold release -- leave hold state and start OpenVPN, but + do not alter the current hold flag setting. + +COMMAND -- kill +--------------- + +In server mode, kill a particlar client instance. + +Command examples: + + kill Test-Client -- kill the client instance having a + common name of "Test-Client". + kill 1.2.3.4:4000 -- kill the client instance having a + source address and port of 1.2.3.4:4000 + +Use the "status" command to see which clients are connected. + +COMMAND -- log +-------------- + +Show the OpenVPN log file. Only the most recent n lines +of the log file are cached by the management interface, where +n is controlled by the OpenVPN --management-log-cache directive. + +Command examples: + + log on -- Enable real-time output of log messages. + log all -- Show currently cached log file history. + log on all -- Atomically show all currently cached log file + history then enable real-time notification of + new log file messages. + log off -- Turn off real-time notification of log messages. + log 20 -- Show the most recent 20 lines of log file history. + +Real-time notification format: + +Real-time log messages begin with the ">LOG:" prefix followed +by the following comma-separated fields: + + (a) unix integer date/time, + (b) zero or more message flags in a single string: + I -- informational + F -- fatal error + N -- non-fatal error + W -- warning + D -- debug, and + (c) message text. + +COMMAND -- mute +--------------- + +Change the OpenVPN --mute parameter. The mute parameter is +used to silence repeating messages of the same message +category. + +Command examples: + + mute 40 -- change the mute parameter to 40 + mute -- show the current mute setting + +COMMAND -- net +-------------- + +(Windows Only) Produce output equivalent to the OpenVPN +--show-net directive. The output includes OpenVPN's view +of the system network adapter list and routing table based +on information returned by the Windows IP helper API. + +COMMAND -- pid +-------------- + +Shows the process ID of the current OpenVPN process. + +COMMAND -- password and username +-------------------------------- + + The password command is used to pass passwords to OpenVPN. + + If OpenVPN is run with the --management-query-passwords + directive, it will query the management interface for RSA + private key passwords and the --auth-user-pass + username/password. + + When OpenVPN needs a password from the management interface, + it will produce a real-time ">PASSWORD:" message. + + Example 1: + + >PASSWORD:Need 'Private Key' password + + OpenVPN is indicating that it needs a password of type + "Private Key". + + The management client should respond to this query as follows: + + password "Private Key" foo + + Example 2: + + >PASSWORD:Need 'Auth' username/password + + OpenVPN needs a --auth-user-pass password. The management + client should respond: + + username "Auth" foo + password "Auth" bar + + The username/password itself can be in quotes, and special + characters such as double quote or backslash must be escaped, + for example, + + password "Private Key" "foo\"bar" + + The escaping rules are the same as for the config file. + See the "Command Parsing" section below for more info. + + The PASSWORD real-time message type can also be used to + indicate password or other types of authentication failure: + + Example 3: The private key password is incorrect and OpenVPN + is exiting: + + >PASSWORD:Verification Failed: 'Private Key' + + Example 4: The --auth-user-pass username/password failed, + and OpenVPN is exiting: + + >PASSWORD:Verification Failed: 'Auth' + + Example 5: The --auth-user-pass username/password failed, + and the server provided a custom client-reason-text string + using the client-deny server-side management interface command. + + >PASSWORD:Verification Failed: 'custom server-generated string' + +COMMAND -- forget-passwords +--------------------------- + +The forget-passwords command will cause the daemon to forget passwords +entered during the session. + +Command example: + + forget-passwords -- forget passwords entered so far. + +COMMAND -- signal +----------------- + +The signal command will send a signal to the OpenVPN daemon. +The signal can be one of SIGHUP, SIGTERM, SIGUSR1, or SIGUSR2. + +Command example: + + signal SIGUSR1 -- send a SIGUSR1 signal to daemon + +COMMAND -- state +---------------- + +Show the current OpenVPN state, show state history, or +enable real-time notification of state changes. + +These are the OpenVPN states: + +CONNECTING -- OpenVPN's initial state. +WAIT -- (Client only) Waiting for initial response + from server. +AUTH -- (Client only) Authenticating with server. +GET_CONFIG -- (Client only) Downloading configuration options + from server. +ASSIGN_IP -- Assigning IP address to virtual network + interface. +ADD_ROUTES -- Adding routes to system. +CONNECTED -- Initialization Sequence Completed. +RECONNECTING -- A restart has occurred. +EXITING -- A graceful exit is in progress. + +Command examples: + + state -- Print current OpenVPN state. + state on -- Enable real-time notification of state changes. + state off -- Disable real-time notification of state changes. + state all -- Print current state history. + state 3 -- Print the 3 most recent state transitions. + state on all -- Atomically show state history while at the + same time enable real-time state notification + of future state transitions. + +The output format consists of 4 comma-separated parameters: + (a) the integer unix date/time, + (b) the state name, + (c) optional descriptive string (used mostly on RECONNECTING + and EXITING to show the reason for the disconnect), + (d) optional TUN/TAP local IP address (shown for ASSIGN_IP + and CONNECTED), and + (e) optional address of remote server (OpenVPN 2.1 or higher). + +Real-time state notifications will have a ">STATE:" prefix +prepended to them. + +COMMAND -- status +----------------- + +Show current daemon status information, in the same format as +that produced by the OpenVPN --status directive. + +Command examples: + +status -- Show status information using the default status + format version. + +status 3 -- Show status information using the format of + --status-version 3. + +COMMAND -- username +------------------- + +See the "password" section above. + +COMMAND -- verb +--------------- + +Change the OpenVPN --verb parameter. The verb parameter +controls the output verbosity, and may range from 0 (no output) +to 15 (maximum output). See the OpenVPN man page for additional +info on verbosity levels. + +Command examples: + + verb 4 -- change the verb parameter to 4 + mute -- show the current verb setting + +COMMAND -- version +------------------ + +Show the current OpenVPN and Management Interface versions. + + +COMMAND -- auth-retry +--------------------- + +Set the --auth-retry setting to control how OpenVPN responds to +username/password authentication errors. See the manual page +for more info. + +Command examples: + + auth-retry interact -- Don't exit when bad username/passwords are entered. + Query for new input and retry. + +COMMAND -- needok (OpenVPN 2.1 or higher) +------------------------------------------ + +Confirm a ">NEED-OK" real-time notification, normally used by +OpenVPN to block while waiting for a specific user action. + +Example: + + OpenVPN needs the user to insert a cryptographic token, + so it sends a real-time notification: + + >NEED-OK:Need 'token-insertion-request' confirmation MSG:Please insert your cryptographic token + + The management client, if it is a GUI, can flash a dialog + box containing the text after the "MSG:" marker to the user. + When the user acknowledges the dialog box, + the management client can issue this command: + + needok token-insertion-request ok + or + needok token-insertion-request cancel + +COMMAND -- needstr (OpenVPN 2.1 or higher) +------------------------------------------- + +Confirm a ">NEED-STR" real-time notification, normally used by +OpenVPN to block while waiting for a specific user input. + +Example: + + OpenVPN needs the user to specify some input, so it sends a + real-time notification: + + >NEED-STR:Need 'name' input MSG:Please specify your name + + The management client, if it is a GUI, can flash a dialog + box containing the text after the "MSG:" marker to the user. + When the user acknowledges the dialog box, + the management client can issue this command: + + needstr name "John" + +COMMAND -- pkcs11-id-count (OpenVPN 2.1 or higher) +--------------------------------------------------- + +Retrieve available number of certificates. + +Example: + + pkcs11-id-count + >PKCS11ID-COUNT:5 + +COMMAND -- pkcs11-id-get (OpenVPN 2.1 or higher) +------------------------------------------------- + +Retrieve certificate by index, the ID string should be provided +as PKCS#11 identity, the blob is BASE64 encoded certificate. + +Example: + + pkcs11-id-get 1 + PKCS11ID-ENTRY:'1', ID:'<snip>', BLOB:'<snip>' + +COMMAND -- client-auth (OpenVPN 2.1 or higher) +----------------------------------------------- + +Authorize a ">CLIENT:CONNECT" or ">CLIENT:REAUTH" request and specify +"client-connect" configuration directives in a subsequent text block. + +The OpenVPN server should have been started with the +--management-client-auth directive so that it will ask the management +interface to approve client connections. + + + client-auth {CID} {KID} + line_1 + line_2 + ... + line_n + END + +CID,KID -- client ID and Key ID. See documentation for ">CLIENT:" +notification for more info. + +line_1 to line_n -- client-connect configuration text block, as would be +returned by a --client-connect script. The text block may be null, with +"END" immediately following the "client-auth" line (using a null text +block is equivalent to using the client-auth-nt command). + +A client-connect configuration text block contains OpenVPN directives +that will be applied to the client instance object representing a newly +connected client. + +COMMAND -- client-auth-nt (OpenVPN 2.1 or higher) +-------------------------------------------------- + +Authorize a ">CLIENT:CONNECT" or ">CLIENT:REAUTH" request without specifying +client-connect configuration text. + +The OpenVPN server should have been started with the +--management-client-auth directive so that it will ask the management +interface to approve client connections. + + client-auth-nt {CID} {KID} + +CID,KID -- client ID and Key ID. See documentation for ">CLIENT:" +notification for more info. + +COMMAND -- client-deny (OpenVPN 2.1 or higher) +----------------------------------------------- + +Deny a ">CLIENT:CONNECT" or ">CLIENT:REAUTH" request. + + client-deny {CID} {KID} "reason-text" ["client-reason-text"] + +CID,KID -- client ID and Key ID. See documentation for ">CLIENT:" +notification for more info. + +reason-text: a human-readable message explaining why the authentication +request was denied. This message will be output to the OpenVPN log +file or syslog. + +client-reason-text: a message that will be sent to the client as +part of the AUTH_FAILED message. + +Note that client-deny denies a specific Key ID (pertaining to a +TLS renegotiation). A client-deny command issued in response to +an initial TLS key negotiation (notified by ">CLIENT:CONNECT") will +terminate the client session after returning "AUTH-FAILED" to the client. +On the other hand, a client-deny command issued in response to +a TLS renegotiation (">CLIENT:REAUTH") will invalidate the renegotiated +key, however the TLS session associated with the currently active +key will continue to live for up to --tran-window seconds before +expiration. + +To immediately kill a client session, use "client-kill". + +COMMAND -- client-kill (OpenVPN 2.1 or higher) +----------------------------------------------- + +Immediately kill a client instance by CID. + + client-kill {CID} + +CID -- client ID. See documentation for ">CLIENT:" notification for more +info. + +COMMAND -- client-pf (OpenVPN 2.1 or higher) +--------------------------------------------- + +Push a packet filter file to a specific client. + +The OpenVPN server should have been started with the +--management-client-pf directive so that it will require that +VPN tunnel packets sent or received by client instances must +conform to that client's packet filter configuration. + + client-pf {CID} + line_1 + line_2 + ... + line_n + END + +CID -- client ID. See documentation for ">CLIENT:" notification for +more info. + +line_1 to line_n -- the packet filter configuration file for this +client. + +Packet filter file grammar: + + [CLIENTS DROP|ACCEPT] + {+|-}common_name1 + {+|-}common_name2 + . . . + [SUBNETS DROP|ACCEPT] + {+|-}subnet1 + {+|-}subnet2 + . . . + [END] + + Subnet: IP-ADDRESS | IP-ADDRESS/NUM_NETWORK_BITS | "unknown" + + CLIENTS refers to the set of clients (by their common-name) which + this instance is allowed ('+') to connect to, or is excluded ('-') + from connecting to. Note that in the case of client-to-client + connections, such communication must be allowed by the packet filter + configuration files of both clients AND the --client-to-client + directive must have been specified in the OpenVPN server config. + + SUBNETS refers to IP addresses or IP address subnets which this + client instance may connect to ('+') or is excluded ('-') from + connecting to, and applies to IPv4 and ARP packets. The special + "unknown" tag refers to packets of unknown type, i.e. a packet that + is not IPv4 or ARP. + + DROP or ACCEPT defines default policy when there is no explicit match + for a common-name or subnet. The [END] tag must exist. + + Notes: + + * The SUBNETS section currently only supports IPv4 addresses and + subnets. + + * A given client or subnet rule applies to both incoming and + outgoing packets. + + * The CLIENTS list is order-invariant. Because the list is stored + as a hash-table, the order of the list does not affect its function. + + * The SUBNETS table is scanned sequentially, and the first item to + match is chosen. Therefore the SUBNETS table is NOT order-invariant. + + * No client-to-client communication is allowed unless the + --client-to-client configuration directive is enabled AND + the CLIENTS list of BOTH clients allows the communication. + +Example packet filter spec, as transmitted to the management interface: + + client-pf 42 + [CLIENTS ACCEPT] + -accounting + -enigma + [SUBNETS DROP] + -10.46.79.9 + +10.0.0.0/8 + [END] + END + +The above example sets the packet filter policy for the client +identified by CID=42. This client may connect to all other clients +except those having a common name of "accounting" or "enigma". +The client may only interact with external IP addresses in the +10.0.0.0/8 subnet, however access to 10.46.79.9 is specifically +excluded. + +Another example packet filter spec, as transmitted to the +management interface: + + client-pf 99 + [CLIENTS DENY] + +public + [SUBNETS ACCEPT] + +10.10.0.1 + -10.0.0.0/8 + -unknown + [END] + END + +The above example sets the packet filter policy for the client +identified by CID=99. This client may not connect to any other +clients except those having a common name of "public". It may +interact with any external IP address except those in the +10.0.0.0/8 netblock. However interaction with one address in +the 10.0.0.0/8 netblock is allowed: 10.10.0.1. Also, the client +may not interact with external IP addresses using an "unknown" +protocol (i.e. one that is not IPv4 or ARP). + +COMMAND -- remote (OpenVPN AS 2.1.5/OpenVPN 2.3 or higher) +-------------------------------------------- + +Provide remote host/port in response to a >REMOTE notification +(client only). Requires that the --management-query-remote +directive is used. + + remote ACTION [HOST PORT] + +The "remote" command should only be given in response to a >REMOTE +notification. For example, the following >REMOTE notification +indicates that the client config file would ordinarily connect +to vpn.example.com port 1194 (UDP): + + >REMOTE:vpn.example.com,1194,udp + +Now, suppose we want to override the host and port, connecting +instead to vpn.otherexample.com port 1234. After receiving +the above notification, use this command: + + remote MOD vpn.otherexample.com 1234 + +To accept the same host and port as the client would ordinarily +have connected to, use this command: + + remote ACCEPT + +To skip the current connection entry and advance to the next one, +use this command: + + remote SKIP + +COMMAND -- proxy (OpenVPN 2.3 or higher) +-------------------------------------------- + +Provide proxy server host/port and flags in response to a >PROXY +notification (client only). Requires that the --management-query-proxy +directive is used. + + proxy TYPE HOST PORT ["nct"] + +The "proxy" command must only be given in response to a >PROXY +notification. Use the "nct" flag if you only want to allow +non-cleartext auth with the proxy server. The following >PROXY +notification indicates that the client config file would ordinarily +connect to the first --remote configured, vpn.example.com using TCP: + + >PROXY:1,TCP,vpn.example.com + +Now, suppose we want to connect to the remote host using the proxy server +proxy.intranet port 8080 with secure authentication only, if required. +After receiving the above notification, use this command: + + proxy HTTP proxy.intranet 8080 nct + +You can also use the SOCKS keyword to pass a SOCKS server address, like: + + proxy SOCKS fe00::1 1080 + +To accept connecting to the host and port directly, use this command: + + proxy NONE + +COMMAND -- rsa-sig (OpenVPN 2.3 or higher) +------------------------------------------ +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 +operation, the data to be signed will be sent to the management interface +via a notification as follows: + +>RSA_SIGN:[BASE64_DATA] + +The management interface client should then sign BASE64_DATA +using the private key and return the SSL signature as follows: + +rsa-sig +[BASE64_SIG_LINE] +. +. +. +END + +Base64 encoded output of RSA_sign(NID_md5_sha1,... will provide a +correct signature. + +This capability is intended to allow the use of arbitrarycryptographic +service providers with OpenVPN via the management interface. + + +OUTPUT FORMAT +------------- + +(1) Command success/failure indicated by "SUCCESS: [text]" or + "ERROR: [text]". + +(2) For commands which print multiple lines of output, + the last line will be "END". + +(3) Real-time messages will be in the form ">[source]:[text]", + where source is "CLIENT", "ECHO", "FATAL", "HOLD", "INFO", "LOG", + "NEED-OK", "PASSWORD", or "STATE". + +REAL-TIME MESSAGE FORMAT +------------------------ + +The OpenVPN management interface produces two kinds of +output: (a) output from a command, or (b) asynchronous, +real-time output which can be generated at any time. + +Real-time messages start with a '>' character in the first +column and are immediately followed by a type keyword +indicating the type of real-time message. The following +types are currently defined: + +BYTECOUNT -- Real-time bandwidth usage notification, as enabled + by "bytecount" command when OpenVPN is running as + a client. + +BYTECOUNT_CLI -- Real-time bandwidth usage notification per-client, + as enabled by "bytecount" command when OpenVPN is + running as a server. + +CLIENT -- Notification of client connections and disconnections + on an OpenVPN server. Enabled when OpenVPN is started + with the --management-client-auth option. CLIENT + notifications may be multi-line. See "The CLIENT + notification" section below for detailed info. + +ECHO -- Echo messages as controlled by the "echo" command. + +FATAL -- A fatal error which is output to the log file just + prior to OpenVPN exiting. + +HOLD -- Used to indicate that OpenVPN is in a holding state + and will not start until it receives a + "hold release" command. + +INFO -- Informational messages such as the welcome message. + +LOG -- Log message output as controlled by the "log" command. + +NEED-OK -- OpenVPN needs the end user to do something, such as + insert a cryptographic token. The "needok" command can + be used to tell OpenVPN to continue. + +NEED-STR -- OpenVPN needs information from end, such as + a certificate to use. The "needstr" command can + be used to tell OpenVPN to continue. + +PASSWORD -- Used to tell the management client that OpenVPN + needs a password, also to indicate password + verification failure. + +STATE -- Shows the current OpenVPN state, as controlled + by the "state" command. + +The CLIENT notification +----------------------- + +The ">CLIENT:" notification is enabled by the --management-client-auth +OpenVPN configuration directive that gives the management interface client +the responsibility to authenticate OpenVPN clients after their client +certificate has been verified. CLIENT notifications may be multi-line, and +the sequentiality of a given CLIENT notification, its associated environmental +variables, and the terminating ">CLIENT:ENV,END" line are guaranteed to be +atomic. + +CLIENT notification types: + +(1) Notify new client connection ("CONNECT") or existing client TLS session + renegotiation ("REAUTH"). Information about the client is provided + by a list of environmental variables which are documented in the OpenVPN + man page. The environmental variables passed are equivalent to those + that would be passed to an --auth-user-pass-verify script. + + >CLIENT:CONNECT|REAUTH,{CID},{KID} + >CLIENT:ENV,name1=val1 + >CLIENT:ENV,name2=val2 + >CLIENT:ENV,... + >CLIENT:ENV,END + +(2) Notify successful client authentication and session initiation. + Called after CONNECT. + + >CLIENT:ESTABLISHED,{CID} + >CLIENT:ENV,name1=val1 + >CLIENT:ENV,name2=val2 + >CLIENT:ENV,... + >CLIENT:ENV,END + +(3) Notify existing client disconnection. The environmental variables passed + are equivalent to those that would be passed to a --client-disconnect + script. + + >CLIENT:DISCONNECT,{CID} + >CLIENT:ENV,name1=val1 + >CLIENT:ENV,name2=val2 + >CLIENT:ENV,... + >CLIENT:ENV,END + +(4) Notify that a particular virtual address or subnet + is now associated with a specific client. + + >CLIENT:ADDRESS,{CID},{ADDR},{PRI} + +Variables: + +CID -- Client ID, numerical ID for each connecting client, sequence = 0,1,2,... +KID -- Key ID, numerical ID for the key associated with a given client TLS session, + sequence = 0,1,2,... +PRI -- Primary (1) or Secondary (0) VPN address/subnet. All clients have at least + one primary IP address. Secondary address/subnets are associated with + client-specific "iroute" directives. +ADDR -- IPv4 address/subnet in the form 1.2.3.4 or 1.2.3.0/255.255.255.0 + +In the unlikely scenario of an extremely long-running OpenVPN server, +CID and KID should be assumed to recycle to 0 after (2^32)-1, however this +recycling behavior is guaranteed to be collision-free. + +Command Parsing +--------------- + +The management interface uses the same command line lexical analyzer +as is used by the OpenVPN config file parser. + +Whitespace is a parameter separator. + +Double quotation or single quotation characters ("", '') can be used +to enclose parameters containing whitespace. + +Backslash-based shell escaping is performed, using the following +mappings, when not in single quotations: + +\\ 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. + +Challenge/Response Protocol +--------------------------- + +The OpenVPN Challenge/Response Protocol allows an OpenVPN server to +generate challenge questions that are shown to the user, and to see +the user's responses to those challenges. Based on the responses, the +server can allow or deny access. + +In this way, the OpenVPN Challenge/Response Protocol can be used +to implement multi-factor authentication. Two different +variations on the challenge/response protocol are supported: the +"Dynamic" and "Static" protocols. + +The basic idea of Challenge/Response is that the user must enter an +additional piece of information, in addition to the username and +password, to successfully authenticate. Normally, this information +is used to prove that the user posesses a certain key-like device +such as cryptographic token or a particular mobile phone. + +Dynamic protocol: + +The OpenVPN dynamic challenge/response protocol works by returning +a specially formatted error message after initial successful +authentication. This error message contains the challenge question, +and is formatted as such: + + CRV1:<flags>:<state_id>:<username_base64>:<challenge_text> + +flags: a series of optional, comma-separated flags: + E : echo the response when the user types it + R : a response is required + +state_id: an opaque string that should be returned to the server + along with the response. + +username_base64 : the username formatted as base64 + +challenge_text : the challenge text to be shown to the user + +Example challenge: + + CRV1:R,E:Om01u7Fh4LrGBS7uh0SWmzwabUiGiW6l:Y3Ix:Please enter token PIN + +After showing the challenge_text and getting a response from the user +(if R flag is specified), the client should submit the following +auth creds back to the OpenVPN server: + +Username: [username decoded from username_base64] +Password: CRV1::<state_id>::<response_text> + +Where state_id is taken from the challenge request and response_text +is what the user entered in response to the challenge_text. +If the R flag is not present, response_text may be the empty +string. + +Example response (suppose the user enters "8675309" for the token PIN): + + Username: cr1 ("Y3Ix" base64 decoded) + Password: CRV1::Om01u7Fh4LrGBS7uh0SWmzwabUiGiW6l::8675309 + +Static protocol: + +The static protocol differs from the dynamic protocol in that the +challenge question and response field is given to the user in the +initial username/password dialog, and the username, password, and +response are delivered back to the server in a single transaction. + +The "static-challenge" directive is used to give the challenge text +to OpenVPN and indicate whether or not the response should be echoed. + +When the "static-challenge" directive is used, the management +interface will respond as such when credentials are needed: + + >PASSWORD:Need 'Auth' username/password SC:<ECHO>,<TEXT> + + ECHO: "1" if response should be echoed, "0" to not echo + TEXT: challenge text that should be shown to the user to + facilitate their response + +For example: + + >PASSWORD:Need 'Auth' username/password SC:1,Please enter token PIN + +The above notification indicates that OpenVPN needs a --auth-user-pass +password plus a response to a static challenge ("Please enter token PIN"). +The "1" after the "SC:" indicates that the response should be echoed. + +The management interface client in this case should add the static +challenge text to the auth dialog followed by a field for the user to +enter a response. Then the client should pack the password and response +together into an encoded password: + + username "Auth" foo + password "Auth" "SCRV1:<BASE64_PASSWORD>:<BASE64_RESPONSE>" + +For example, if the user entered "bar" as the password and 8675309 +as the PIN, the following management interface commands should be +issued: + + username "Auth" foo + password "Auth" "SCRV1:Zm9v:ODY3NTMwOQ==" + +Client-side support for challenge/response protocol: + +Currently, the Access Server client and standalone OpenVPN +client support both static and dynamic challenge/response +protocols. However, any OpenVPN client UI that drives OpenVPN +via the management interface needs to add explicit support +for the challenge/response protocol. diff --git a/doc/openvpn.8 b/doc/openvpn.8 new file mode 100644 index 0000000..2ed5201 --- /dev/null +++ b/doc/openvpn.8 @@ -0,0 +1,6439 @@ +.\" 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-2010 OpenVPN Technologies, 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 (see the file COPYING included with this +.\" distribution); if not, write to the Free Software Foundation, Inc., +.\" 59 Temple Place, Suite 330, Boston, MA 02111-1307 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 +.\" +.TH openvpn 8 "17 November 2008" +.\"********************************************************* +.SH NAME +openvpn \- secure IP tunnel daemon. +.\"********************************************************* +.SH SYNOPSIS +.ft 3 +openvpn [ options ... ] +.ft +.\"********************************************************* +.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 +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. + +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. +.\"********************************************************* +.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: + +.nf +.ft 3 +.in +4 +\\\\ 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. +.in -4 +.ft +.fi + +For example on Windows, use double backslashes to +represent pathnames: + +.nf +.ft 3 +.in +4 +secret "c:\\\\OpenVPN\\\\secret.key" +.in -4 +.ft +.fi + +For examples of configuration files, +see +.I http://openvpn.net/examples.html + +Here is an example configuration file: + +.nf +.ft 3 +.in +4 +# +# 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 +.in -4 +.ft +.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". + +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, +one will be randomly +chosen, providing a sort of basic load-balancing and +failover capability. +.\"********************************************************* +.TP +.B \-\-remote-random-hostname +Add a random string (6 characters) to first DNS label of 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: + +.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 +http-proxy-retry +</connection> + +<connection> +remote 198.19.36.99 443 tcp +http-proxy 192.168.0.8 8080 +http-proxy-retry +</connection> + +persist-key +persist-tun +pkcs12 client.p12 +ns-cert-type server +verb 3 +.in -4 +.ft +.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 float, +.B http-proxy, +.B http-proxy-option, +.B http-proxy-retry, +.B http-proxy-timeout, +.B local, +.B lport, +.B nobind, +.B port, +.B proto, +.B remote, +.B rport, +.B socks-proxy, and +.B socks-proxy-retry. + +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 +For +.B \-\-proto tcp-client, +take +.B n +as the +number of seconds to wait +between connection retries (default=5). +.\"********************************************************* +.TP +.B \-\-connect-timeout n +For +.B \-\-proto tcp-client, +set connection timeout to +.B n +seconds (default=10). +.\"********************************************************* +.TP +.B \-\-connect-retry-max n +For +.B \-\-proto tcp-client, +take +.B n +as the +number of retries of connection attempt (default=infinite). +.\"********************************************************* +.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. + +.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-retry +Retry indefinitely on HTTP proxy errors. If an HTTP proxy error +occurs, simulate a SIGUSR1 reset. +.\"********************************************************* +.TP +.B \-\-http-proxy-timeout n +Set proxy timeout to +.B n +seconds, default=5. +.\"********************************************************* +.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. +.\"********************************************************* +.TP +.B \-\-socks-proxy server [port] +Connect to remote host through a Socks5 proxy at address +.B server +and port +.B port +(default=1080). +.\"********************************************************* +.TP +.B \-\-socks-proxy-retry +Retry indefinitely on Socks proxy errors. If a Socks proxy error +occurs, simulate a SIGUSR1 reset. +.\"********************************************************* +.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 for both local and remote. 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 +TCP/UDP port number for bind. +.\"********************************************************* +.TP +.B \-\-rport port +TCP/UDP port number for remote. +.\"********************************************************* +.TP +.B \-\-bind +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. +.\"********************************************************* +.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 and is now deprecated. + +.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. +.\"********************************************************* +.TP +.B \-\-tun-ipv6 +Build a tun link capable of forwarding IPv6 traffic. +Should be used in conjunction with +.B \-\-dev tun +or +.B \-\-dev tunX. +A warning will be displayed +if no specific IPv6 TUN support for your OS has been compiled into OpenVPN. + +See below for further IPv6-related configuration options. +.\"********************************************************* +.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. + +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. +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, +.B rn +is the IP address of the remote VPN endpoint. +For TAP devices, +.B rn +is the subnet mask of the virtual ethernet segment +which is being created or connected to. + +For TUN devices, which facilitate virtual +point-to-point IP connections, +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, +.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 \-\-max-routes n +Allow a maximum number of n +.B \-\-route +options to be specified, either in the local configuration file, +or pulled from an OpenVPN server. By default, n=100. +.\"********************************************************* +.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 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. +.\"********************************************************* +.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. +.\"********************************************************* +.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 servers 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. +.\"********************************************************* +.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 +.\"********************************************************* +.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. +.\"********************************************************* +.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. + +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 +.\"********************************************************* +.TP +.B \-\-sndbuf size +Set the TCP/UDP socket send buffer size. +Currently defaults to 65536 bytes. +.\"********************************************************* +.TP +.B \-\-rcvbuf size +Set the TCP/UDP socket receive buffer size. +Currently defaults to 65536 bytes. +.\"********************************************************* +.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. +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 n m +A helper directive designed to simplify the expression of +.B \-\-ping +and +.B \-\-ping-restart +in server mode configurations. + +The server timeout is set twice the value of the second argument. +This ensures that a timeout is dectected on client side +before the server side drops the connection. + +For example, +.B \-\-keepalive 10 60 +expands as follows: + +.nf +.ft 3 +.in +4 + if mode server: + ping 10 + ping-restart 120 + push "ping 10" + push "ping-restart 60" + else + ping 10 + ping-restart 60 +.in -4 +.ft +.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 +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. +.\"********************************************************* +.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 +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. + +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. +.\"********************************************************* +.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 \-\-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 v2.3, this flag is no longer accepted. In most *nix environments the execve() +approach has been used without any issues. + +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 v2.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: + +.nf +.ft 3 +.in +4 +\-\-up 'C:\\\\Windows\\\\System32\\\\wscript.exe C:\\\\Program\\ Files\\\\OpenVPN\\\\config\\\\my-up-script.vbs' +.in -4 +.ft +.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. +.\"********************************************************* +.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. +.\"********************************************************* +.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. +.\"********************************************************* +.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. +.TP +.B \-\-errors-to-stderr +Output errors to stderr instead of stdout unless log output is redirected by one of the +.B \-\-log +options. +.\"********************************************************* +.TP +.B \-\-passtos +Set the TOS field of the tunnel packet to what the payload's TOS is. +.\"********************************************************* +.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. +.\"********************************************************* +.TP +.B \-\-suppress-timestamps +Avoid writing timestamps to log messages, even when they +otherwise would be prepended. In particular, this applies to +log messages sent to stdout. +.\"********************************************************* +.TP +.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. +.\"********************************************************* +.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. +.\"********************************************************* +.TP +.B \-\-multihome +Configure a multi-homed UDP server. This option can be used when +OpenVPN has been configured to listen on all interfaces, and will +attempt to bind client sessions to the interface on which packets +are being received, so that outgoing packets will be sent out +of the same interface. Note that this option is only relevant for +UDP servers and currently is only implemented on Linux. + +Note: clients connecting to a +.B \-\-multihome +server should always use the +.B \-\-nobind +option. +.\"********************************************************* +.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 \-\- +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. +.\"********************************************************* +.TP +.B \-\-status-version [n] +Choose the status file format version number. Currently +.B n +can be 1, 2, or 3 and defaults to 1. +.\"********************************************************* +.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. +.\"********************************************************* +.TP +.B \-\-comp-lzo [mode] +Use fast 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. + +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: + +.nf +.ft 3 +.in +4 +comp-lzo yes +push "comp-lzo yes" +.in -4 +.ft +.fi + +The first line sets the +.B comp-lzo +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. + +Adaptive compression tries to optimize the case where you have +compression enabled, but you are sending predominantly uncompressible +(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 IP port [pw-file] +Enable a TCP server on +.B IP:port +to handle daemon management functions. +.B pw-file, +if specified, +is a password file (password on first line) +or "stdin" to prompt from standard input. The password +provided will set the password which TCP clients will need +to provide in order to access management functions. + +The management interface can also listen on a unix domain socket, +for those platforms that support it. To use a unix domain socket, specify +the unix socket pathname in place of +.B IP +and set +.B port +to 'unix'. While the default behavior is to create a unix domain socket +that may be connected to by any process, the +.B \-\-management-client-user +and +.B \-\-management-client-group +directives can be used 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 +.B IP += "tunnel". Tunnel mode will cause the management interface +to listen for a TCP connection on the local VPN address of the +TUN/TAP interface. + +While the management port is designed for programmatic control +of OpenVPN by other applications, it is possible to telnet +to the port, using a telnet client in "raw" mode. Once connected, +type "help" for a list of commands. + +For detailed documentation on the management interface, see +the management-notes.txt file in the +.B management +folder of +the OpenVPN source distribution. + +It is strongly recommended that +.B IP +be set to 127.0.0.1 +(localhost) to restrict accessibility of the management +server to local clients. +.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. +.\"********************************************************* +.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. +.\"********************************************************* +.TP +.B \-\-management-query-proxy +Query management channel for proxy server information for a specific +.B \-\-remote +(client-only). +.\"********************************************************* +.TP +.B \-\-management-query-remote +Allow management interface to override +.B \-\-remote +directives (client-only). +.\"********************************************************* +.B \-\-management-external-key +Allows usage for external private key file instead of +.B \-\-key +option (client-only). +.\"********************************************************* +.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. +.\"********************************************************* +.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. +.\"********************************************************* +.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. +.\"********************************************************* +.TP +.B \-\-management-up-down +Report tunnel up/down events to management interface. +.B +.\"********************************************************* +.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. +.\"********************************************************* +.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. + +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. +.\"********************************************************* +.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 +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: + +.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.254 255.255.255.0 + push "route-gateway 10.8.0.1" +.in -4 +.ft +.fi + +Don't use +.B \-\-server +if you are ethernet bridging. Use +.B \-\-server-bridge +instead. +.\"********************************************************* +.TP +.B \-\-server-bridge gateway netmask pool-start-IP pool-end-IP +.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: + +.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 +.fi + +In another example, +.B \-\-server-bridge +(without parameters) expands as follows: + +.nf +.ft 3 +.in +4 +mode server +tls-server + +push "route-gateway dhcp" +.in -4 +.ft +.fi + +Or +.B \-\-server-bridge nogw +expands as follows: + +.nf +.ft 3 +.in +4 +mode server +tls-server +.in -4 +.ft +.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 \-\-persist-key, \-\-persist-tun, \-\-echo, +.B \-\-comp-lzo, +.B \-\-socket-flags, +.B \-\-sndbuf, \-\-rcvbuf +.\"********************************************************* +.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-peer-info +Push additional information about the client to server. The additional information +consists of the following data: + +IV_VER=<version> -- the client OpenVPN version + +IV_PLAT=[linux|solaris|openbsd|mac|netbsd|freebsd|win] -- the client OS platform + +IV_HWADDR=<mac address> -- the MAC address of clients default gateway + +IV_LZO_STUB=1 -- if client was built with LZO stub capability + +UV_<name>=<value> -- client environment variables whose names start with "UV_" +.\"********************************************************* +.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 +.\"********************************************************* +.TP +.B \-\-ifconfig-pool-linear +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. +.\"********************************************************* +.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. +.\"********************************************************* +.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, \-\-iroute, \-\-ifconfig-push, +and +.B \-\-config. +.\"********************************************************* +.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. +.\"********************************************************* +.TP +.B \-\-bcast-buffers n +Allocate +.B n +buffers for broadcast datagrams (default=256). +.\"********************************************************* +.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. +.\"********************************************************* +.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: + +.nf +.ft 3 +.in +4 + if mode server: + socket-flags TCP_NODELAY + push "socket-flags TCP_NODELAY" +.in -4 +.ft +.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 +.B \-\-tls-auth. +.\"********************************************************* +.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 \-\-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, tun-ipv6, 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 +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. + +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. + +If you don't use this directive, 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. +.\"********************************************************* +.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] +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 behavivour 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 v2.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 v2.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. + +As a backwards compatibility for the removed \-\-no\-name\-remapping feature in +older OpenVPN versions, the +.B no\-remapping +mode flag can be used with the +.B +\-\-compat\-names +option. +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. It ensures +compatibility with the +.B \-\-no\-name\-remapping +option of OpenVPN versions before v2.3. + +.B Please note: +This option will not be around for a long time. It is only implemented +to make the transition to the new formatting less intrusive. It will be +removed either in OpenVPN v2.4 or v2.5. So please make sure you start +the process to support the new formatting 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. +.\"********************************************************* +.TP +.B \-\-client +A helper directive designed to simplify the configuration +of OpenVPN's client mode. This directive is equivalent to: + +.nf +.ft 3 +.in +4 + pull + tls-client +.in -4 +.ft +.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 \-\-auth-user-pass [up] +Authenticate with server using username/password. +.B up +is a file containing username/password on 2 lines (Note: OpenVPN +will only read passwords from a file if it has been built +with the \-\-enable-password-save configure option, or on Windows +by defining ENABLE_PASSWORD_SAVE in win/settings.in). + +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 +.B \-\-server-poll-timeout n +when polling possible remote servers to connect to +in a round-robin fashion, spend no more than +.B n +seconds waiting for a response before trying the next server. +.\"********************************************************* +.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. OpenVPN will not send any exit +notifications unless this option is enabled. +.\"********************************************************* +.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. +.\"********************************************************* +.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 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. + +OpenVPN's usage of HMAC is to first encrypt a packet, then HMAC the resulting ciphertext. + +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 +.\"********************************************************* +.TP +.B \-\-cipher alg +Encrypt packets with cipher algorithm +.B alg. +The default is +.B BF-CBC, +an abbreviation for Blowfish in Cipher Block Chaining mode. +Blowfish has the advantages of being fast, very secure, and allowing key sizes +of up to 448 bits. Blowfish is designed to be used in situations where +keys are changed infrequently. + +For more information on blowfish, see +.I http://www.counterpane.com/blowfish.html + +To see other ciphers that are available with +OpenVPN, use the +.B \-\-show-ciphers +option. + +OpenVPN supports the CBC, CFB, and OFB cipher modes, +however CBC is recommended and CFB and OFB should +be considered advanced modes. + +Set +.B alg=none +to disable encryption. +.\"********************************************************* +.TP +.B \-\-keysize n +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. +.\"********************************************************* +.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 +(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 specifed, 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 +(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. +.\"********************************************************* +.TP +.B \-\-use-prediction-resistance +Enable prediction resistance on PolarSSL'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. + +Note that this option only works with PolarSSL versions greater +than 1.1. +.\"********************************************************* +.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. + +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 distribution contains a set of scripts for +managing RSA certificates & keys, +located in the +.I easy-rsa +subdirectory. + +The easy-rsa package is also rendered in web form here: +.I http://openvpn.net/easyrsa.html +.\"********************************************************* +.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 +.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). +Available with OpenSSL version >= 0.9.7 dev. +Not available with PolarSSL. +.\"********************************************************* +.TP +.B \-\-dh file +File containing Diffie Hellman parameters +in .pem format (required for +.B \-\-tls-server +only). Use + +.B openssl dhparam -out dh1024.pem 1024 + +to generate your own, or use the existing dh1024.pem file +included with the OpenVPN distribution. Diffie Hellman parameters +may be considered public. +.\"********************************************************* +.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 \-\-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 PolarSSL. +.\"********************************************************* +.TP +.B \-\-verify-hash hash +Specify SHA1 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: AD:B0:95:D8:09:C8:36:45:12:A9:89:C8:90:09:CB:13:72:A6:AD:16 +.\"********************************************************* +.TP +.B \-\-pkcs11-cert-private [0|1]... +Set if access to certificate object should be performed after login. +Every provider has its own setting. +.\"********************************************************* +.TP +.B \-\-pkcs11-id name +Specify the serialized certificate id to be used. The id can be gotten +by the standalone +.B \-\-show-pkcs11-ids +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. +.\"********************************************************* +.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 determind 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. + +.\"********************************************************* +.TP +.B \-\-key-method m +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. + +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 +A list +.B l +of allowable TLS ciphers delimited by a colon (":"). +If you require a high level of security, +you may want to set this parameter manually, to prevent a +version rollback attack where a man-in-the-middle attacker tries +to force two peers to negotiate to the lowest level +of security they both support. +Use +.B \-\-show-tls +to see a list of supported TLS ciphers. +.\"********************************************************* +.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). +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. +.\"********************************************************* +.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. +.\"********************************************************* +.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. +.\"********************************************************* +.TP +.B \-\-tls-exit +Exit on TLS negotiation failure. +.\"********************************************************* +.TP +.B \-\-tls-auth file [direction] +Add an additional layer of HMAC authentication on top of the TLS +control channel to protect against DoS attacks. + +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 key file which can be in one of two formats: + +.B (1) +An OpenVPN static key file generated by +.B \-\-genkey +(required if +.B direction +parameter is used). + +.B (2) +A freeform passphrase file. In this case the HMAC key will +be derived by taking a secure hash of this file, similar to +the +.BR md5sum (1) +or +.BR sha1sum (1) +commands. + +OpenVPN will first try format (1), and if the file fails to parse as +a static key file, format (2) will be used. + +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 +passphrase/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. +.\"********************************************************* +.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 (Note: OpenVPN +will only read passwords from a file if it has been built +with the \-\-enable-password-save configure option, or on Windows +by defining ENABLE_PASSWORD_SAVE in win/settings.in). +.\"********************************************************* +.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. + +This directive does not affect the +.B \-\-http-proxy +username/password. It is always cached. +.\"********************************************************* +.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 common name (cn) 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 fieldname +Field in x509 certificate subject to be used as username (default=CN). +.B Fieldname +will be uppercased before matching. When this option is used, the +--tls-remote option will match against the chosen fieldname instead +of the CN. +.\"********************************************************* +.TP +.B \-\-tls-remote name +Accept connections only from a host with X509 name +or common name equal to +.B name. +The remote host must also pass all other tests +of verification. + +.B NOTE: +Because tls-remote may test against a common name prefix, +only use this option when you are using OpenVPN with a custom CA +certificate that is under your control. +Never use this option when your client certificates are signed by +a third party, such as a commercial web CA. + +Name can also be a common name prefix, for example if you +want a client to only accept connections to "Server-1", +"Server-2", etc., you can simply use +.B \-\-tls-remote Server + +Using a common 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 \-\-tls-remote +is a useful replacement for the +.B \-\-tls-verify +option to verify the remote host, because +.B \-\-tls-remote +works in a +.B \-\-chroot +environment too. +.\"********************************************************* +.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. +Not available with PolarSSL. +.\"********************************************************* +.TP +.B \-\-ns-cert-type client|server +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, \-\-tls-remote, +or +.B \-\-tls-verify. +.\"********************************************************* +.TP +.B \-\-remote-cert-ku v... +Require that peer certificate was signed with an explicit +.B key usage. + +This is a useful security option for clients, to ensure that +the host they connect to is a designated server. + +The key usage should be encoded in hex, more than one key +usage can be specified. +.\"********************************************************* +.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. +.\"********************************************************* +.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. + +The +.B \-\-remote-cert-tls client +option is equivalent to +.B +\-\-remote-cert-ku 80 08 88 \-\-remote-cert-eku "TLS Web Client Authentication" + +The key usage is digitalSignature and/or keyAgreement. + +The +.B \-\-remote-cert-tls server +option is equivalent to +.B +\-\-remote-cert-ku a0 88 \-\-remote-cert-eku "TLS Web Server Authentication" + +The key usage is digitalSignature and ( keyEncipherment or keyAgreement ). + +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, \-\-tls-remote, +or +.B \-\-tls-verify. +.\"********************************************************* +.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. + +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. +.\"********************************************************* +.SS SSL Library information: +.\"********************************************************* +.TP +.B \-\-show-ciphers +(Standalone) +Show all cipher algorithms to use with the +.B \-\-cipher +option. +.\"********************************************************* +.TP +.B \-\-show-digests +(Standalone) +Show all message digest algorithms to use with the +.B \-\-auth +option. +.\"********************************************************* +.TP +.B \-\-show-tls +(Standalone) +Show all TLS ciphers (TLS used only as a control channel). The TLS +ciphers will be sorted from highest preference (most secure) to +lowest. +.\"********************************************************* +.TP +.B \-\-show-engines +(Standalone) +Show currently available hardware-based crypto acceleration +engines supported by the OpenSSL library. +.\"********************************************************* +.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) +. +.\"********************************************************* +.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. +.\"********************************************************* +.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. +.\"********************************************************* +.TP +.B \-\-rmtun +(Standalone) +Remove a persistent tunnel. +.\"********************************************************* +.TP +.B \-\-dev tunX | tapX +TUN/TAP device +.\"********************************************************* +.TP +.B \-\-user user +Optional user to be owner of this tunnel. +.\"********************************************************* +.TP +.B \-\-group group +Optional group to be owner of this tunnel. +.\"********************************************************* +.SS Windows-Specific Options: +.\"********************************************************* +.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 0. +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 address. Repeat +this option to set secondary DNS server addresses. + +.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. +.\"********************************************************* +.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. +.\"********************************************************* +.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 +.B \-\-dhcp-release +Ask Windows to release the TAP adapter lease on shutdown. +This option has the same caveats as +.B \-\-dhcp-renew +above. +.\"********************************************************* +.TP +.B \-\-register-dns +Run net stop dnscache, net start dnscache, ipconfig /flushdns +and ipconfig /registerdns on connection initiation. +This is known to kick Windows into +recognizing pushed DNS servers. +.\"********************************************************* +.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 \-\-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. +.\"********************************************************* +.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. +.\"********************************************************* +.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). +.\"********************************************************* +.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. + +.B \-\-verb +option can be used BEFORE this option to produce debugging information. +.\"********************************************************* +.SS IPv6 Related Options +.\"********************************************************* +The following options exist to support IPv6 tunneling in peer-to-peer +and client-server mode. As of now, this is just very basic +documentation of the IPv6-related options. More documentation can be +found on http://www.greenie.net/ipv6/openvpn.html. +.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'' device +.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, --tun-ipv6 +and +.B --push tun-ipv6 +Is only accepted if ``--mode server'' or ``--server'' is set. +.TP +.B --ifconfig-ipv6-pool ipv6addr/bits +Specify an IPv6 address pool for dynamic assignment to clients. The +pool starts at +.B ipv6addr +and increments by +1 for every new client (linear mode). The +.B /bits +setting controls the size of the 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 +.\"********************************************************* +.TP +.B \-\-up +Executed after TCP/UDP socket bind and TUN/TAP open. +.\"********************************************************* +.TP +.B \-\-tls-verify +Executed when we have a still untrusted remote peer. +.\"********************************************************* +.TP +.B \-\-ipchange +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 +Executed right before the routes are removed. +.\"********************************************************* +.TP +.B \-\-client-disconnect +Executed in +.B \-\-mode server +mode on client instance shutdown. +.\"********************************************************* +.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. +.\"********************************************************* +.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 +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, +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 2.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. +.\"********************************************************* +.TP +.B config +Name of first +.B \-\-config +file. +Set on program initiation and reset on SIGHUP. +.\"********************************************************* +.TP +.B daemon +Set to "1" if the +.B \-\-daemon +directive is specified, or "0" otherwise. +Set on program initiation and reset on SIGHUP. +.\"********************************************************* +.TP +.B daemon_log_redirect +Set to "1" if the +.B \-\-log +or +.B \-\-log-append +directives are 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 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. +.\"********************************************************* +.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. +.\"********************************************************* +.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. +.\"********************************************************* +.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 +script execution. +.\"********************************************************* +.TP +.B local +The +.B \-\-local +parameter. +Set on program initiation and reset on SIGHUP. +.\"********************************************************* +.TP +.B local_port +The local port number, 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. +Set on program initiation and reset on SIGHUP. +.\"********************************************************* +.TP +.B remote_{n} +The +.B \-\-remote +parameter. +Set on program initiation and reset on SIGHUP. +.\"********************************************************* +.TP +.B remote_port_{n} +The remote port number, specified by +.B \-\-port +or +.B \-\-rport. +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. +.\"********************************************************* +.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 +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 +The duration (in seconds) of the client session which is now +disconnecting. +Set prior to execution of the +.B \-\-client-disconnect +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_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 hex string like "37AB46E0", which is +suitable for doing serial-based OCSP queries (with OpenSSL, you have +to 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 tun_mtu +The MTU of the TUN/TAP device. +Set prior to +.B \-\-up +or +.B \-\-down +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 +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. + +.nf +.ft 3 +.in +4 +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 +.in -4 +.ft +.fi +.\"********************************************************* +.SH INLINE FILE SUPPORT +OpenVPN allows including files in the main configuration for the +.B \-\-ca, \-\-cert, \-\-dh, \-\-extra-certs, \-\-key, \-\-pkcs12, \-\-secret +and +.B \-\-tls-auth +options. + +Each inline file started by the line +.B <option> +and ended by the line +.B </option> + +Here is an example of an inline file usage + +.nf +.ft 3 +.in +4 +<cert> +-----BEGIN CERTIFICATE----- +[...] +-----END CERTIFICATE----- +</cert> +.in -4 +.ft +.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 + +.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 +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 +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 may.kg +and +.B june.kg. +If you are constructing a VPN over the internet, then replace +.B may.kg +and +.B june.kg +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 may.kg +will be 10.4.0.1 and for june.kg, 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 may.kg and you wish to connect to june.kg +via +.B ssh +without using the VPN (since +.B ssh +has its own built-in security) you would use the command +.B ssh june.kg. +However in the same scenario, you could also use the command +.B telnet 10.4.0.2 +to create a telnet session with june.kg 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 may: +.IP +.B openvpn \-\-remote june.kg \-\-dev tun1 \-\-ifconfig 10.4.0.1 10.4.0.2 \-\-verb 9 +.LP +On june: +.IP +.B openvpn \-\-remote may.kg \-\-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 may: +.IP +.B ping 10.4.0.2 +.LP +On june: +.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 may. +.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 june over a secure medium such as by +using the +.BR scp (1) +program. +.LP +On may: +.IP +.B openvpn \-\-remote june.kg \-\-dev tun1 \-\-ifconfig 10.4.0.1 10.4.0.2 \-\-verb 5 \-\-secret key +.LP +On june: +.IP +.B openvpn \-\-remote may.kg \-\-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 may: +.IP +.B ping 10.4.0.2 +.LP +On june: +.IP +.B ping 10.4.0.1 +.\"********************************************************* +.SS Example 3: A tunnel with full TLS-based security +For this test, we will designate +.B may +as the TLS client and +.B june +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 may and june (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 may: +.IP +.B openvpn \-\-remote june.kg \-\-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 june: +.IP +.B openvpn \-\-remote may.kg \-\-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 may: +.IP +.B ping 10.4.0.2 +.LP +On june: +.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 may and june 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 may's private subnet +is 10.0.0.0/24 and june'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 may: +.IP +.B route add -net 10.0.1.0 netmask 255.255.255.0 gw 10.4.0.2 +.LP +On june: +.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. +.\"********************************************************* +.SH FAQ +.I http://openvpn.net/faq.html +.\"********************************************************* +.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 +.\"********************************************************* +.SH PROTOCOL +For a description of OpenVPN's underlying protocol, +see +.I http://openvpn.net/security.html +.\"********************************************************* +.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. +.\"********************************************************* +.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/ +) + +For more information on the TLS protocol, see +.I http://www.ietf.org/rfc/rfc2246.txt + +For more information on the LZO real-time compression library see +.I http://www.oberhumer.com/opensource/lzo/ +.\"********************************************************* +.SH COPYRIGHT +Copyright (C) 2002-2010 OpenVPN Technologies, 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> |