summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/Makefile.in51
-rw-r--r--doc/management-notes.txt46
-rw-r--r--doc/openvpn.8922
3 files changed, 659 insertions, 360 deletions
diff --git a/doc/Makefile.in b/doc/Makefile.in
index cb2e2c2..8e37bca 100644
--- a/doc/Makefile.in
+++ b/doc/Makefile.in
@@ -1,7 +1,7 @@
-# Makefile.in generated by automake 1.15 from Makefile.am.
+# Makefile.in generated by automake 1.13.4 from Makefile.am.
# @configure_input@
-# Copyright (C) 1994-2014 Free Software Foundation, Inc.
+# Copyright (C) 1994-2013 Free Software Foundation, Inc.
# This Makefile.in is free software; the Free Software Foundation
# gives unlimited permission to copy and/or distribute it,
@@ -26,17 +26,7 @@
#
VPATH = @srcdir@
-am__is_gnu_make = { \
- if test -z '$(MAKELEVEL)'; then \
- false; \
- elif test -n '$(MAKE_HOST)'; then \
- true; \
- elif test -n '$(MAKE_VERSION)' && test -n '$(CURDIR)'; then \
- true; \
- else \
- false; \
- fi; \
-}
+am__is_gnu_make = test -n '$(MAKEFILE_LIST)' && test -n '$(MAKELEVEL)'
am__make_running_with_option = \
case $${target_option-} in \
?) ;; \
@@ -101,6 +91,8 @@ build_triplet = @build@
host_triplet = @host@
@WIN32_TRUE@am__append_1 = openvpn.8
subdir = doc
+DIST_COMMON = $(srcdir)/Makefile.in $(srcdir)/Makefile.am \
+ $(dist_man_MANS) $(dist_doc_DATA) $(am__dist_noinst_DATA_DIST)
ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
am__aclocal_m4_deps = $(top_srcdir)/m4/ax_emptyarray.m4 \
$(top_srcdir)/m4/ax_socklen_t.m4 \
@@ -111,10 +103,9 @@ am__aclocal_m4_deps = $(top_srcdir)/m4/ax_emptyarray.m4 \
$(top_srcdir)/compat.m4 $(top_srcdir)/configure.ac
am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \
$(ACLOCAL_M4)
-DIST_COMMON = $(srcdir)/Makefile.am $(dist_doc_DATA) \
- $(am__dist_noinst_DATA_DIST) $(am__DIST_COMMON)
mkinstalldirs = $(install_sh) -d
-CONFIG_HEADER = $(top_builddir)/config.h
+CONFIG_HEADER = $(top_builddir)/config.h \
+ $(top_builddir)/include/openvpn-plugin.h
CONFIG_CLEAN_FILES =
CONFIG_CLEAN_VPATH_FILES =
AM_V_P = $(am__v_P_@AM_V@)
@@ -171,7 +162,6 @@ MANS = $(dist_man_MANS)
am__dist_noinst_DATA_DIST = README.plugins openvpn.8
DATA = $(dist_doc_DATA) $(dist_noinst_DATA) $(nodist_html_DATA)
am__tagged_files = $(HEADERS) $(SOURCES) $(TAGS_FILES) $(LISP)
-am__DIST_COMMON = $(dist_man_MANS) $(srcdir)/Makefile.in
DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST)
ACLOCAL = @ACLOCAL@
AMTAR = @AMTAR@
@@ -185,6 +175,7 @@ AWK = @AWK@
CC = @CC@
CCDEPMODE = @CCDEPMODE@
CFLAGS = @CFLAGS@
+CMAKE = @CMAKE@
CPP = @CPP@
CPPFLAGS = @CPPFLAGS@
CYGPATH_W = @CYGPATH_W@
@@ -219,25 +210,31 @@ LIBTOOL = @LIBTOOL@
LIPO = @LIPO@
LN_S = @LN_S@
LTLIBOBJS = @LTLIBOBJS@
-LT_SYS_LIBRARY_PATH = @LT_SYS_LIBRARY_PATH@
+LZ4_CFLAGS = @LZ4_CFLAGS@
+LZ4_LIBS = @LZ4_LIBS@
LZO_CFLAGS = @LZO_CFLAGS@
LZO_LIBS = @LZO_LIBS@
MAKEINFO = @MAKEINFO@
MAN2HTML = @MAN2HTML@
MANIFEST_TOOL = @MANIFEST_TOOL@
+MBEDTLS_CFLAGS = @MBEDTLS_CFLAGS@
+MBEDTLS_LIBS = @MBEDTLS_LIBS@
MKDIR_P = @MKDIR_P@
NETSTAT = @NETSTAT@
NM = @NM@
NMEDIT = @NMEDIT@
OBJDUMP = @OBJDUMP@
OBJEXT = @OBJEXT@
-OPENSSL_CRYPTO_CFLAGS = @OPENSSL_CRYPTO_CFLAGS@
-OPENSSL_CRYPTO_LIBS = @OPENSSL_CRYPTO_LIBS@
-OPENSSL_SSL_CFLAGS = @OPENSSL_SSL_CFLAGS@
-OPENSSL_SSL_LIBS = @OPENSSL_SSL_LIBS@
+OPENSSL_CFLAGS = @OPENSSL_CFLAGS@
+OPENSSL_LIBS = @OPENSSL_LIBS@
+OPENVPN_VERSION_MAJOR = @OPENVPN_VERSION_MAJOR@
+OPENVPN_VERSION_MINOR = @OPENVPN_VERSION_MINOR@
+OPENVPN_VERSION_PATCH = @OPENVPN_VERSION_PATCH@
OPTIONAL_CRYPTO_CFLAGS = @OPTIONAL_CRYPTO_CFLAGS@
OPTIONAL_CRYPTO_LIBS = @OPTIONAL_CRYPTO_LIBS@
OPTIONAL_DL_LIBS = @OPTIONAL_DL_LIBS@
+OPTIONAL_LZ4_CFLAGS = @OPTIONAL_LZ4_CFLAGS@
+OPTIONAL_LZ4_LIBS = @OPTIONAL_LZ4_LIBS@
OPTIONAL_LZO_CFLAGS = @OPTIONAL_LZO_CFLAGS@
OPTIONAL_LZO_LIBS = @OPTIONAL_LZO_LIBS@
OPTIONAL_PKCS11_HELPER_CFLAGS = @OPTIONAL_PKCS11_HELPER_CFLAGS@
@@ -263,8 +260,6 @@ 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@
@@ -279,6 +274,11 @@ TAP_CFLAGS = @TAP_CFLAGS@
TAP_WIN_COMPONENT_ID = @TAP_WIN_COMPONENT_ID@
TAP_WIN_MIN_MAJOR = @TAP_WIN_MIN_MAJOR@
TAP_WIN_MIN_MINOR = @TAP_WIN_MIN_MINOR@
+TEST_CFLAGS = @TEST_CFLAGS@
+TEST_LDFLAGS = @TEST_LDFLAGS@
+VENDOR_BUILD_ROOT = @VENDOR_BUILD_ROOT@
+VENDOR_DIST_ROOT = @VENDOR_DIST_ROOT@
+VENDOR_SRC_ROOT = @VENDOR_SRC_ROOT@
VERSION = @VERSION@
abs_builddir = @abs_builddir@
abs_srcdir = @abs_srcdir@
@@ -361,6 +361,7 @@ $(srcdir)/Makefile.in: $(srcdir)/Makefile.am $(am__configure_deps)
echo ' cd $(top_srcdir) && $(AUTOMAKE) --foreign doc/Makefile'; \
$(am__cd) $(top_srcdir) && \
$(AUTOMAKE) --foreign doc/Makefile
+.PRECIOUS: Makefile
Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status
@case '$?' in \
*config.status*) \
@@ -631,8 +632,6 @@ uninstall-man: uninstall-man8
ps ps-am tags-am uninstall uninstall-am uninstall-dist_docDATA \
uninstall-man uninstall-man8 uninstall-nodist_htmlDATA
-.PRECIOUS: Makefile
-
@WIN32_TRUE@openvpn.8.html: $(srcdir)/openvpn.8
@WIN32_TRUE@ $(MAN2HTML) < $(srcdir)/openvpn.8 > openvpn.8.html
diff --git a/doc/management-notes.txt b/doc/management-notes.txt
index ef39b85..dd870eb 100644
--- a/doc/management-notes.txt
+++ b/doc/management-notes.txt
@@ -168,9 +168,12 @@ be reset by restarts.
OpenVPN will indicate that it is in a hold state by
sending a real-time notification to the management
-client:
+client, the parameter indicates how long OpenVPN would
+wait without UI (as influenced by connect-retry exponential
+backoff). The UI needs to wait for releasing the hold if it
+wants similar behavior:
- >HOLD:Waiting for hold release
+ >HOLD:Waiting for hold release:10
Command examples:
@@ -366,14 +369,23 @@ Command examples:
same time enable real-time state notification
of future state transitions.
-The output format consists of 4 comma-separated parameters:
+The output format consists of up to 9 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).
+ (d) optional TUN/TAP local IPv4 address
+ (e) optional address of remote server,
+ (f) optional port of remote server,
+ (g) optional local address,
+ (h) optional local port, and
+ (i) optional TUN/TAP local IPv6 address.
+
+Fields (e)-(h) are shown for CONNECTED state,
+(d) and (i) are shown for ASSIGN_IP and CONNECTED states.
+
+(e) is available starting from OpenVPN 2.1
+(f)-(i) are available starting from OpenVPN 2.4
Real-time state notifications will have a ">STATE:" prefix
prepended to them.
@@ -777,6 +789,28 @@ correct signature.
This capability is intended to allow the use of arbitrary cryptographic
service providers with OpenVPN via the management interface.
+COMMAND -- certificate (OpenVPN 2.4 or higher)
+----------------------------------------------
+Provides support for external storage of the certificate. Requires the
+--management-external-cert option. This option can be used instead of "cert"
+in client mode. On SSL protocol initialization a notification will be sent
+to the management interface with a hint as follows:
+
+>NEED-CERTIFICATE:macosx-keychain:subject:o=OpenVPN-TEST
+
+The management interface client should use the hint to obtain the specific
+SSL certificate and then return base64 encoded certificate as follows:
+
+certificate
+[BASE64_CERT_LINE]
+.
+.
+.
+END
+
+This capability is intended to allow the use of certificates
+stored outside of the filesystem (e.g. in Mac OS X Keychain)
+with OpenVPN via the management interface.
OUTPUT FORMAT
-------------
diff --git a/doc/openvpn.8 b/doc/openvpn.8
index 1cad9be..e997b09 100644
--- a/doc/openvpn.8
+++ b/doc/openvpn.8
@@ -21,13 +21,13 @@
.\" 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
@@ -37,7 +37,7 @@
.TH openvpn 8 "17 November 2008"
.\"*********************************************************
.SH NAME
-openvpn - secure IP tunnel daemon.
+openvpn \- secure IP tunnel daemon.
.\"*********************************************************
.SH SYNOPSIS
.ft 3
@@ -221,6 +221,9 @@ options.
indicates the protocol to use when connecting with the
remote, and may be "tcp" or "udp".
+For forcing IPv4 or IPv6 connection suffix tcp or udp
+with 4/6 like udp4/udp6/tcp4/tcp6.
+
The client will move on to the next host in the list,
in the event of connection failure.
Note that at any given time, the OpenVPN client
@@ -265,9 +268,11 @@ not match
If
.B host
is a DNS name which resolves to multiple IP addresses,
-the first address returned by the system getaddrinfo() function
-will be used (no DNS randomization inside OpenVPN 2.3.x, and
-it will not try multiple addresses).
+OpenVPN will try them in the order that the system getaddrinfo()
+presents them, so priorization and DNS randomization is done
+by the system library. Unless an IP version is forced by the
+protocol specification (4/6 suffix), OpenVPN will try both IPv4
+and IPv6 addresses, in the order getaddrinfo() returns them.
.\"*********************************************************
.TP
.B \-\-remote\-random\-hostname
@@ -311,20 +316,18 @@ remote 198.19.34.56 443 tcp
<connection>
remote 198.19.34.56 443 tcp
-http-proxy 192.168.0.8 8080
-http-proxy-retry
+http\-proxy 192.168.0.8 8080
</connection>
<connection>
remote 198.19.36.99 443 tcp
-http-proxy 192.168.0.8 8080
-http-proxy-retry
+http\-proxy 192.168.0.8 8080
</connection>
-persist-key
-persist-tun
+persist\-key
+persist\-tun
pkcs12 client.p12
-ns-cert-type server
+ns\-cert\-type server
verb 3
.in -4
.ft
@@ -343,30 +346,27 @@ a
block:
.B bind,
-.B connect-retry,
-.B connect-retry-max,
-.B connect-timeout,
-.B explicit-exit-notify,
+.B connect\-retry,
+.B connect\-retry\-max,
+.B connect\-timeout,
+.B explicit\-exit\-notify,
.B float,
.B fragment,
-.B http-proxy,
-.B http-proxy-option,
-.B http-proxy-retry,
-.B http-proxy-timeout,
-.B link-mtu,
+.B http\-proxy,
+.B http\-proxy\-option,
+.B link\-mtu,
.B local,
.B lport,
.B mssfix,
-.B mtu-disc,
+.B mtu\-disc,
.B nobind,
.B port,
.B proto,
.B remote,
.B rport,
-.B socks-proxy,
-.B socks-proxy-retry,
-.B tun-mtu and
-.B tun-mtu-extra.
+.B socks\-proxy,
+.B tun\-mtu and
+.B tun\-mtu\-extra.
A defaulting mechanism exists for specifying options to apply to
all
@@ -415,9 +415,9 @@ for communicating with remote host.
.B p
can be
.B udp,
-.B tcp-client,
+.B tcp\-client,
or
-.B tcp-server.
+.B tcp\-server.
The default protocol is
.B udp
@@ -434,7 +434,7 @@ For TCP operation, one peer must use
and the other must use
.B \-\-proto tcp\-client.
A peer started with
-.B tcp-server
+.B tcp\-server
will wait indefinitely for an incoming connection. A peer
started with
.B tcp\-client
@@ -462,31 +462,27 @@ 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 \-\-connect\-retry n [max]
+Wait
.B n
-seconds (default=10).
+seconds between connection attempts (default=5). Repeated reconnection
+attempts are slowed down after 5 retries per remote by doubling the wait
+time after each unsuccessful attempt. The optional argument
+.B max
+specifies the maximum value of wait time in seconds at which it gets
+capped (default=300).
.\"*********************************************************
.TP
.B \-\-connect\-retry\-max n
-For
-.B \-\-proto tcp\-client,
-take
.B n
-as the
-number of retries of connection attempt (default=infinite).
+specifies the number of times each
+.B \-\-remote
+or
+.B <connection>
+entry is tried. Specifying
+.B n
+as one would try each entry exactly once. A successful connection
+resets the counter. (default=unlimited).
.\"*********************************************************
.TP
.B \-\-show\-proxy\-settings
@@ -502,9 +498,12 @@ and 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.
+"stdin" to prompt from console. Its content can also be specified
+in the config file with the
+.B \-\-http\-proxy\-user\-pass
+option. (See section on inline files)
-.B auth-method
+.B auth\-method
should be one of "none", "basic", or "ntlm".
HTTP Digest authentication is supported as well, but only via
@@ -517,7 +516,7 @@ flags (below).
The
.B auto
flag causes OpenVPN to automatically determine the
-.B auth-method
+.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.
@@ -529,17 +528,6 @@ 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.
@@ -552,6 +540,13 @@ Set HTTP version number to
.B AGENT user-agent --
Set HTTP "User-Agent" string to
.B user-agent.
+
+.B CUSTOM\-HEADER name content --
+Adds the custom Header with
+.B name
+as name and
+.B content
+as the content of the custom HTTP header.
.\"*********************************************************
.TP
.B \-\-socks\-proxy server [port] [authfile]
@@ -565,11 +560,6 @@ and port
"stdin" to prompt from console.
.\"*********************************************************
.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,
@@ -582,7 +572,7 @@ Set
to "infinite" to retry indefinitely.
By default,
-.B \-\-resolv-retry infinite
+.B \-\-resolv\-retry infinite
is enabled. You can disable by setting n=0.
.\"*********************************************************
.TP
@@ -685,7 +675,7 @@ option. The port can also be set directly using the
option.
.\"*********************************************************
.TP
-.B \-\-bind
+.B \-\-bind [ipv6only]
Bind to local address and port. This is the default unless any of
.B \-\-proto tcp\-client
,
@@ -693,6 +683,12 @@ Bind to local address and port. This is the default unless any of
or
.B \-\-socks\-proxy
are used.
+
+If the
+.B ipv6only
+keyword is present OpenVPN will bind only to IPv6 (as oposed
+to IPv6 and IPv4) when a IPv6 socket is opened.
+
.\"*********************************************************
.TP
.B \-\-nobind
@@ -760,13 +756,13 @@ directive, this directive must always be compatible between client and server.
.B mode
can be one of:
-.B net30 --
+.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 --
+.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.
@@ -776,7 +772,7 @@ is functionally equivalent to the
.B \-\-ifconfig\-pool\-linear
directive which is available in OpenVPN 2.0 and is now deprecated.
-.B subnet --
+.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
@@ -801,18 +797,6 @@ changes the interpretation of the arguments of
to mean "address netmask", no longer "local remote".
.\"*********************************************************
.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
@@ -892,7 +876,7 @@ you will be pinging across the VPN.
For TAP devices, which provide
the ability to create virtual
ethernet segments, or TUN devices in
-.B \-\-topology subnet
+.B --topology subnet
mode (which create virtual "multipoint networks"),
.B \-\-ifconfig
is used to set an IP address and
@@ -984,7 +968,7 @@ when
is specified.
.B metric
-default \-\- taken from
+default -- taken from
.B \-\-route\-metric
otherwise 0.
@@ -1019,13 +1003,6 @@ table (not supported on all OSes).
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
@@ -1193,7 +1170,7 @@ that the original default route is restored.
Option flags:
-.B local --
+.B local \-\-
Add the
.B local
flag if both OpenVPN servers are directly connected via a common subnet,
@@ -1203,7 +1180,7 @@ flag will cause step
.B 1
above to be omitted.
-.B autolocal --
+.B autolocal \-\-
Try to automatically determine whether to enable
.B local
flag above.
@@ -1230,6 +1207,17 @@ on non-Windows clients).
Block access to local LAN when the tunnel is active, except for
the LAN gateway itself. This is accomplished by routing the local
LAN (except for the LAN gateway address) into the tunnel.
+
+.B ipv6 --
+Redirect IPv6 routing into the tunnel. This works similar to the
+.B def1
+flag, that is, more specific IPv6 routes are added (2000::/4, 3000::/4),
+covering the whole IPv6 unicast space.
+
+.B !ipv4 --
+Do not redirect IPv4 traffic - typically used in the flag pair
+.B "ipv6 !ipv4"
+to redirect IPv6-only.
.\"*********************************************************
.TP
.B \-\-link\-mtu n
@@ -1626,16 +1614,25 @@ and
are mutually exclusive and cannot be used together.
.\"*********************************************************
.TP
-.B \-\-keepalive n m
+.B \-\-keepalive interval timeout
A helper directive designed to simplify the expression of
.B \-\-ping
and
+.B \-\-ping\-restart.
+
+This option can be used on both client and server side, but it is
+in enough to add this on the server side as it will push appropriate
+.B \-\-ping
+and
.B \-\-ping\-restart
-in server mode configurations.
+options to the client. If used on both server and client,
+the values pushed from server will override the client local values.
-The server timeout is set twice the value of the second argument.
-This ensures that a timeout is detected on client side
-before the server side drops the connection.
+The
+.B timeout
+argument will be twice as long on the server side. This ensures that
+a timeout is detected on client side before the server side drops
+the connection.
For example,
.B \-\-keepalive 10 60
@@ -1645,13 +1642,13 @@ expands as follows:
.ft 3
.in +4
if mode server:
- ping 10
- ping-restart 120
- push "ping 10"
- push "ping-restart 60"
+ ping 10 # Argument: interval
+ ping\-restart 120 # Argument: timeout*2
+ push "ping 10" # Argument: interval
+ push "ping\-restart 60" # Argument: timeout
else
- ping 10
- ping-restart 60
+ ping 10 # Argument: interval
+ ping\-restart 60 # Argument: timeout
.in -4
.ft
.fi
@@ -1979,16 +1976,16 @@ and scripts. Lower
values are more restrictive, higher values are more permissive. Settings for
.B level:
-.B 0 --
+.B 0 \-\-
Strictly no calling of external programs.
.br
-.B 1 --
+.B 1 \-\-
(Default) Only call built-in executables such as ifconfig, ip, route, or netsh.
.br
-.B 2 --
+.B 2 \-\-
Allow calling of built-in executables and user-defined scripts.
.br
-.B 3 --
+.B 3 \-\-
Allow passwords to be passed to scripts via environmental variables (potentially unsafe).
OpenVPN releases before v2.3 also supported a
@@ -2320,6 +2317,12 @@ otherwise would be prepended. In particular, this applies to
log messages sent to stdout.
.\"*********************************************************
.TP
+.B \-\-machine\-readable\-output
+Always write timestamps and message flags to log messages, even when they
+otherwise would not be prefixed. In particular, this applies to
+log messages sent to stdout.
+.\"*********************************************************
+.TP
.B \-\-writepid file
Write OpenVPN's main process ID to
.B file.
@@ -2420,13 +2423,13 @@ Set output verbosity to
Level 3 is recommended if you want a good summary
of what's happening without being swamped by output.
-.B 0 --
+.B 0 \-\-
No output except fatal errors.
.br
-.B 1 to 4 --
+.B 1 to 4 \-\-
Normal usage range.
.br
-.B 5 --
+.B 5 \-\-
Output
.B R
and
@@ -2434,7 +2437,7 @@ and
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 --
+.B 6 to 11 \-\-
Debug info range (see errlevel.h for additional
information on debug levels).
.\"*********************************************************
@@ -2464,12 +2467,34 @@ consecutive messages in the same category. This is useful to
limit repetitive logging of similar message types.
.\"*********************************************************
.TP
+.B \-\-compress [algorithm]
+Enable a compression algorithm.
+
+The
+.B algorithm
+parameter may be "lzo", "lz4", or empty. LZO and LZ4
+are different compression algorithms, with LZ4 generally
+offering the best performance with least CPU usage.
+For backwards compatibility with OpenVPN versions before 2.4, use "lzo"
+(which is identical to the older option "\-\-comp\-lzo yes").
+
+If the
+.B algorithm
+parameter is empty, compression will be turned off, but the packet
+framing for compression will still be enabled, allowing a different
+setting to be pushed later.
+.\"*********************************************************
+.TP
.B \-\-comp\-lzo [mode]
-Use fast LZO compression -- may add up to 1 byte per
+Use LZO compression -- may add up to 1 byte per
packet for incompressible data.
.B mode
may be "yes", "no", or "adaptive" (default).
+This option is deprecated in favor of the newer
+.B --compress
+option.
+
In a server mode setup, it is possible to selectively turn
compression on or off for individual clients.
@@ -2491,14 +2516,14 @@ for example:
.nf
.ft 3
.in +4
-comp-lzo yes
+comp\-lzo yes
push "comp\-lzo yes"
.in -4
.ft
.fi
The first line sets the
-.B comp-lzo
+.B comp\-lzo
setting for the server
side of the link, the second sets the client side.
.\"*********************************************************
@@ -2558,7 +2583,7 @@ 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
+the management\-notes.txt file in the
.B management
folder of
the OpenVPN source distribution.
@@ -2599,12 +2624,23 @@ Allow management interface to override
.B \-\-remote
directives (client-only).
.\"*********************************************************
+.TP
.B \-\-management\-external\-key
Allows usage for external private key file instead of
.B \-\-key
option (client-only).
.\"*********************************************************
.TP
+.B \-\-management\-external\-cert certificate-hint
+Allows usage for external certificate instead of
+.B \-\-cert
+option (client-only).
+.B certificate-hint
+is an arbitrary string which is passed to a management
+interface client as an argument of NEED-CERTIFICATE notification.
+Requires \-\-management\-external\-key.
+.\"*********************************************************
+.TP
.B \-\-management\-forget\-disconnect
Make OpenVPN forget passwords when management session
disconnects.
@@ -2650,7 +2686,7 @@ 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
+filter file for each connecting client. See management\-notes.txt
in OpenVPN distribution for detailed notes.
.\"*********************************************************
.TP
@@ -2694,11 +2730,23 @@ 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
+function (such as tls\-verify, auth\-user\-pass\-verify, or
+client\-connect), then
every module and script must return success (0) in order for
the connection to be authenticated.
.\"*********************************************************
+.TP
+.B \-\-keying-material-exporter label len
+Save Exported Keying Material [RFC5705] of len bytes (must be
+between 16 and 4095 bytes) using label in environment
+(exported_keying_material) for use by plugins in
+OPENVPN_PLUGIN_TLS_FINAL callback.
+
+Note that exporter labels have the potential to collide with existing PRF
+labels. In order to prevent this, labels MUST begin with "EXPORTER".
+
+This option requires OpenSSL 1.0.1 or newer.
+.\"*********************************************************
.SS Server Mode
Starting with OpenVPN 2.0, a multi-client TCP/UDP server mode
is supported, and can be enabled with the
@@ -2729,15 +2777,15 @@ expands as follows:
.ft 3
.in +4
mode server
- tls-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
+ ifconfig\-pool 10.8.0.4 10.8.0.251
route 10.8.0.0 255.255.255.0
- if client-to-client:
+ if client\-to\-client:
push "route 10.8.0.0 255.255.255.0"
else if topology == net30:
push "route 10.8.0.1"
@@ -2745,10 +2793,10 @@ expands as follows:
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"
- if route-gateway unset:
- route-gateway 10.8.0.2
+ ifconfig\-pool 10.8.0.2 10.8.0.254 255.255.255.0
+ push "route\-gateway 10.8.0.1"
+ if route\-gateway unset:
+ route\-gateway 10.8.0.2
.in -4
.ft
@@ -2815,17 +2863,17 @@ 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
+.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
+tls\-server
-ifconfig-pool 10.8.0.128 10.8.0.254 255.255.255.0
-push "route-gateway 10.8.0.4"
+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
@@ -2838,9 +2886,9 @@ In another example,
.ft 3
.in +4
mode server
-tls-server
+tls\-server
-push "route-gateway dhcp"
+push "route\-gateway dhcp"
.in -4
.ft
.fi
@@ -2853,7 +2901,7 @@ expands as follows:
.ft 3
.in +4
mode server
-tls-server
+tls\-server
.in -4
.ft
.fi
@@ -2894,18 +2942,76 @@ as with a
configuration file. This option will ignore
.B \-\-push
options at the global config file level.
+.\"*********************************************************
+.TP
+.B \-\-push\-remove opt
+selectively remove all
+.B \-\-push
+options matching "opt" from the option list for a client. "opt" is matched
+as a substring against the whole option string to-be-pushed to the client, so
+.B \-\-push\-remove route
+would remove all
+.B \-\-push route ...
+and
+.B \-\-push route-ipv6 ...
+statements, while
+.B \-\-push\-remove 'route-ipv6 2001:'
+would only remove IPv6 routes for 2001:... networks.
+
+.B \-\-push\-remove
+can only be used in a client-specific context, like in a
+.B \-\-client\-config\-dir
+file, or
+.B \-\-client\-connect
+script or plugin -- similar to
+.B \-\-push\-reset,
+just more selective.
+
+NOTE: to
+.I change
+an option,
+.B \-\-push\-remove
+can be used to first remove the old value, and then add a new
+.B \-\-push
+option with the new value.
+.\"*********************************************************
.TP
.B \-\-push\-peer\-info
-Push additional information about the client to server. The additional information
-consists of the following data:
+Push additional information about the client to server.
+The following data is always pushed to the server:
IV_VER=<version> -- the client OpenVPN version
IV_PLAT=[linux|solaris|openbsd|mac|netbsd|freebsd|win] -- the client OS platform
+IV_LZO_STUB=1 -- if client was built with LZO stub capability
+
+IV_LZ4=1 -- if the client supports LZ4 compressions.
+
+IV_RGI6=1 -- if the client supports
+.B \-\-redirect\-gateway
+for ipv6
+
+IV_PROTO=2 -- if the client supports peer-id floating mechansim
+
+IV_NCP=2 -- negotiable ciphers, client supports
+.B \-\-cipher
+pushed by the server, a value of 2 or greater indicates client
+supports AES-GCM-128 and AES-GCM-256.
+
+IV_UI_VER=<gui_id> <version> -- the UI version of a UI if one is
+running, for example "de.blinkt.openvpn 0.5.47" for the
+Android app.
+
+When
+.B \-\-push\-peer\-info
+is enabled the additional information consists of the following data:
+
IV_HWADDR=<mac address> -- the MAC address of clients default gateway
-IV_LZO_STUB=1 -- if client was built with LZO stub capability
+IV_SSL=<version string> -- the ssl version used by the client, e.g. "OpenSSL 1.0.2f 28 Jan 2016".
+
+IV_PLAT_VER=x.y - the version of the operating system, e.g. 6.1 for Windows 7.
UV_<name>=<value> -- client environment variables whose names start with "UV_"
.\"*********************************************************
@@ -2941,7 +3047,7 @@ parameter will also be pushed to clients.
.\"*********************************************************
.TP
.B \-\-ifconfig\-pool\-persist file [seconds]
-Persist/unpersist ifconfig-pool
+Persist/unpersist ifconfig\-pool
data to
.B file,
at
@@ -2992,14 +3098,14 @@ This option is deprecated, and should be replaced with
which is functionally equivalent.
.\"*********************************************************
.TP
-.B \-\-ifconfig\-push local remote-netmask [alias]
+.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
+.B remote\-netmask
are set according to the
.B \-\-ifconfig
directive which you want to execute on the client machine to
@@ -3015,9 +3121,9 @@ 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
+.B local/remote\-netmask
will refer to the server view while
-.B alias/remote-netmask
+.B alias/remote\-netmask
will refer to the client view.
This option must be associated with a specific client instance,
@@ -3218,7 +3324,7 @@ without needing to restart the server.
The following
options are legal in a client-specific context:
-.B \-\-push, \-\-push\-reset, \-\-iroute, \-\-ifconfig\-push,
+.B \-\-push, \-\-push\-reset, \-\-push\-remove, \-\-iroute, \-\-ifconfig\-push,
and
.B \-\-config.
.\"*********************************************************
@@ -3298,8 +3404,8 @@ The macro expands as follows:
.ft 3
.in +4
if mode server:
- socket-flags TCP_NODELAY
- push "socket-flags TCP_NODELAY"
+ socket\-flags TCP_NODELAY
+ push "socket\-flags TCP_NODELAY"
.in -4
.ft
.fi
@@ -3365,8 +3471,10 @@ 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.
+and either
+.B \-\-tls\-auth
+or
+.B \-\-tls\-crypt\fR.
.\"*********************************************************
.TP
.B \-\-learn\-address cmd
@@ -3383,19 +3491,19 @@ Three arguments will be appended to any arguments in
.B cmd
as follows:
-.B [1] operation --
+.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 --
+.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 --
+.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".
@@ -3431,7 +3539,7 @@ 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
+is set to "via\-env", OpenVPN will call
.B script
with the environmental variables
.B username
@@ -3444,7 +3552,7 @@ unprivileged processes.
If
.B method
-is set to "via-file", OpenVPN will write the username and
+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,
@@ -3482,18 +3590,40 @@ 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
+.B sample\-scripts/auth\-pam.pl
in the OpenVPN source distribution.
.\"*********************************************************
.TP
+.B \-\-auth\-gen\-token [lifetime]
+After successful user/password authentication, the OpenVPN
+server will with this option generate a temporary
+authentication token and push that to client. On the following
+renegotiations, the OpenVPN client will pass this token instead
+of the users password. On the server side the server will do
+the token authentication internally and it will NOT do any
+additional authentications against configured external
+user/password authentication mechanisms.
+
+The
+.B lifetime
+argument defines how long the generated token is valid. The
+lifetime is defined in seconds. If lifetime is not set
+or it is set to 0, the token will never expire.
+
+This feature is useful for environments which is configured
+to use One Time Passwords (OTP) as part of the user/password
+authentications and that authentication mechanism does not
+implement any auth-token support.
+.\"*********************************************************
+.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.
+dev\-type, link\-mtu, tun\-mtu, proto, ifconfig,
+comp\-lzo, fragment, keydir, cipher, auth, keysize, secret,
+no\-replay, no\-iv, tls\-auth, key\-method, tls\-server, and tls\-client.
This option requires that
.B \-\-disable\-occ
@@ -3518,18 +3648,63 @@ to empty strings (""). The authentication module/script MUST have logic
to detect this condition and respond accordingly.
.\"*********************************************************
.TP
-.B \-\-client\-cert\-not\-required
+.B \-\-client\-cert\-not\-required (DEPRECATED)
Don't require client certificate, client will authenticate
using username/password only. Be aware that using this directive
is less secure than requiring certificates from all clients.
+
+.B Please note:
+This option is now deprecated and will be removed in OpenVPN v2.5.
+It is replaced by
+.B \-\-verify\-client\-cert
+which allows for more flexibility. The option
+.B \-\-verify\-client\-cert none
+is functionally equivalent to
+.B \-\-client\-cert\-not\-required
+.
+
+.\"*********************************************************
+.TP
+.B \-\-verify\-client\-cert none|optional|require
+Specify whether the client is required to supply a valid certificate.
+
+Possible options are
+
+.B none
+: a client certificate is not required. the client need to authenticate
+using username/password only. Be aware that using this directive
+is less secure than requiring certificates from all clients.
+
If you use this directive, the
entire responsibility of authentication will rest on your
.B \-\-auth\-user\-pass\-verify
script, so keep in mind that bugs in your script
could potentially compromise the security of your VPN.
-If you don't use this directive, but you also specify an
+.B \-\-verify\-client\-cert none
+is functionally equivalent to
+.B \-\-client\-cert\-not\-required.
+
+.B optional
+: a client may present a certificate but it is not required to do so.
+When using this directive, you should also use a
+.B \-\-auth\-user\-pass\-verify
+script to ensure that clients are authenticated using a
+certificate, a username and password, or possibly even both.
+
+Again, the entire responsibility of authentication will rest on your
+.B \-\-auth\-user\-pass\-verify
+script, so keep in mind that bugs in your script
+could potentially compromise the security of your VPN.
+
+.B require
+: this is the default option. A client is required to present a
+certificate, otherwise VPN access is refused.
+
+If you don't use this directive (or use
+.B \-\-verify\-client\-cert require
+) but you also specify an
.B \-\-auth\-user\-pass\-verify
script, then OpenVPN will perform double authentication. The
client certificate verification AND the
@@ -3591,11 +3766,7 @@ carriage-return. no-remapping is only available on the server side.
.B Please note:
This option is immediately deprecated. It is only implemented
to make the transition to the new formatting less intrusive. It will be
-removed either in OpenVPN v2.4 or v2.5. So please make sure you use the
-.B \-\-verify\-x509\-name
-option instead of
-.B \-\-tls\-remote
-as soon as possible and update your scripts where necessary.
+removed in OpenVPN v2.5. So please update your scripts/plug-ins where necessary.
.\"*********************************************************
.TP
.B \-\-no\-name\-remapping (DEPRECATED)
@@ -3608,8 +3779,8 @@ It ensures compatibility with server configurations using the
option.
.B Please note:
-This option is now deprecated. It will be removed either in OpenVPN v2.4
-or v2.5. So please make sure you support the new X.509 name formatting
+This option is now deprecated. It will be removed in OpenVPN v2.5.
+So please make sure you support the new X.509 name formatting
described with the
.B \-\-compat\-names
option as soon as possible.
@@ -3654,7 +3825,7 @@ of OpenVPN's client mode. This directive is equivalent to:
.ft 3
.in +4
pull
- tls-client
+ tls\-client
.in -4
.ft
.fi
@@ -3681,6 +3852,57 @@ in situations where you don't trust the server to have control
over the client's routing table.
.\"*********************************************************
.TP
+.B \-\-pull\-filter accept|ignore|reject \fItext\fR
+Filter options received from the server if the option starts with
+\fItext\fR. Runs on client. The action flag
+.B accept
+allows the option,
+.B ignore
+removes it and
+.B reject
+flags an error and triggers a SIGUSR1 restart.
+The filters may be specified multiple times, and each filter is
+applied in the order it is specified. The filtering of each
+option stops as soon as a match is found. Unmatched options are accepted
+by default.
+
+Prefix comparison is used to match \fItext\fR against the
+received option so that
+
+.nf
+.ft 3
+.in +4
+\-\-pull\-filter ignore "route"
+.in -4
+.ft
+.fi
+
+would remove all pushed options starting with
+.B route
+which would include, for example,
+.B route\-gateway.
+Enclose \fItext\fR in quotes to embed spaces.
+
+.nf
+.ft 3
+.in +4
+\-\-pull\-filter accept "route 192.168.1."
+\-\-pull\-filter ignore "route "
+.in -4
+.ft
+.fi
+
+would remove all routes that do not start with 192.168.1.
+
+This option may be used only on clients.
+Note that
+.B reject
+may result in a repeated cycle of failure and reconnect,
+unless multiple remotes are specified and connection to the next remote
+succeeds. To silently ignore an option pushed by the server, use
+.B ignore.
+.\"*********************************************************
+.TP
.B \-\-auth\-user\-pass [up]
Authenticate with server using username/password.
.B up
@@ -3718,15 +3940,15 @@ tries to connect.
.B type
can be one of:
-.B none --
+.B none \-\-
Client will exit with a fatal error (this is the default).
.br
-.B nointeract --
+.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 --
+.B interact \-\-
Client will requery for an
.B \-\-auth\-user\-pass
username/password and/or private key password before attempting a reconnection.
@@ -3751,14 +3973,12 @@ 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 \-\-connect\-timeout n
+when connecting to a remote server do not wait for more than
.B n
seconds waiting for a response before trying the next server.
-As this only makes sense in client-to-server setups, it cannot
-be used in point-to-point setups using
-.B \-\-secret
-symmetrical key mode.
+The default value is 120s. This timeout includes proxy and TCP
+connect timeouts.
.\"*********************************************************
.TP
.B \-\-explicit\-exit\-notify [n]
@@ -3769,8 +3989,23 @@ 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
+will try to resend the exit notification message.
+
+In UDP server mode, send RESTART control channel command to connected clients. The
+.B n
+parameter (default=1) controls client behavior. With
+.B n
+= 1 client will attempt to reconnect
+to the same server, with
+.B n
+= 2 client will advance to the next server.
+
+OpenVPN will not send any exit
notifications unless this option is enabled.
+.TP
+.B \-\-allow\-recursive\-routing
+When this option is set, OpenVPN will not drop incoming tun packets
+with same destination as host.
.\"*********************************************************
.SS Data Channel Encryption Options:
These options are meaningful for both Static & TLS-negotiated key modes
@@ -3852,8 +4087,9 @@ options. Useful when using inline files (See section on inline files).
.\"*********************************************************
.TP
.B \-\-auth alg
-Authenticate packets with HMAC using message
-digest algorithm
+Authenticate data channel packets and (if enabled)
+.B tls-auth
+control channel packets with HMAC using message digest algorithm
.B alg.
(The default is
.B SHA1
@@ -3862,7 +4098,17 @@ 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.
+The OpenVPN data channel protocol uses encrypt-then-mac (i.e. first encrypt a
+packet, then HMAC the resulting ciphertext), which prevents padding oracle
+attacks.
+
+If an AEAD cipher mode (e.g. GCM) is chosen, the specified
+.B \-\-auth
+algorithm is ignored for the data channel, and the authentication method of the
+AEAD cipher is used instead. Note that
+.B alg
+still specifies the digest used for
+.B tls-auth\fR.
In static-key encryption mode, the HMAC key
is included in the key file generated by
@@ -3885,25 +4131,57 @@ Encrypt data channel packets with cipher algorithm
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
+Using BF-CBC is no longer recommended, because of it's 64-bit block size. This
+small block size allows attacks based on collisions, as demonstrated by SWEET32.
+See https://community.openvpn.net/openvpn/wiki/SWEET32 for details.
-To see other ciphers that are available with
-OpenVPN, use the
+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.
+
+As of OpenVPN 2.4, cipher negotiation (NCP) can override the cipher specified by
+.B \-\-cipher\fR.
+See
+.B \-\-ncp-ciphers
+and
+.B \-\-ncp-disable
+for more on NCP.
+
+.\"*********************************************************
+.TP
+.B \-\-ncp\-ciphers cipher_list
+Restrict the allowed ciphers to be negotiated to the ciphers in
+.B cipher_list\fR.
+.B cipher_list
+is a colon-separated list of ciphers, and defaults to
+"AES-256-GCM:AES-128-GCM".
+
+For servers, the first cipher from
+.B cipher_list
+will be pushed to clients that support cipher negotiation.
+
+Cipher negotiation is enabled in client-server mode only. I.e. if
+.B \-\-mode
+is set to 'server' (server-side, implied by setting
+.B \-\-server
+), or if
+.B \-\-pull
+is specified (client-side, implied by setting \-\-client).
+
+If both peers support and do not disable NCP, the negotiated cipher will
+override the cipher specified by
+.B \-\-cipher\fR.
+
+.\"*********************************************************
+.TP
+.B \-\-ncp\-disable
+Disable "negotiable crypto parameters". This completely disables cipher
+negotiation.
.\"*********************************************************
.TP
.B \-\-keysize n
@@ -4006,7 +4284,7 @@ is 15 seconds.
This option is only relevant in UDP mode, i.e.
when either
.B \-\-proto udp
-is specifed, or no
+is specified, or no
.B \-\-proto
option is specified.
@@ -4202,14 +4480,9 @@ 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
+The OpenVPN project provides a set of scripts for
+managing RSA certificates & keys:
+.I https://github.com/OpenVPN/easy-rsa
.\"*********************************************************
.TP
.B \-\-tls\-server
@@ -4247,7 +4520,6 @@ 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.
When using the
@@ -4271,13 +4543,25 @@ for more information.
File containing Diffie Hellman parameters
in .pem format (required for
.B \-\-tls\-server
-only). Use
+only).
-.B openssl dhparam \-out dh1024.pem 1024
+Set
+.B file=none
+to disable Diffie Hellman key exchange (and use ECDH only). Note that this
+requires peers to be using an SSL library that supports ECDH TLS cipher suites
+(e.g. OpenSSL 1.0.1+, or PolarSSL 1.3+).
-to generate your own, or use the existing dh1024.pem file
-included with the OpenVPN distribution. Diffie Hellman parameters
-may be considered public.
+Use
+.B openssl dhparam \-out dh2048.pem 2048
+to generate 2048-bit DH parameters. Diffie Hellman parameters may be considered
+public.
+.\"*********************************************************
+.TP
+.B \-\-ecdh\-curve name
+Specify the curve to use for elliptic curve Diffie Hellman. Available
+curves can be listed with
+.B \-\-show\-curves
+. The specified curve will only be used for ECDH TLS-ciphers.
.\"*********************************************************
.TP
.B \-\-cert file
@@ -4348,26 +4632,17 @@ above).
.\"*********************************************************
.TP
.B \-\-tls\-version\-min version ['or\-highest']
-Enable TLS version negotiation, and set the minimum
+Sets the minimum
TLS version we will accept from the peer (default is "1.0").
Examples for version
include "1.0", "1.1", or "1.2". If 'or-highest' is specified
and version is not recognized, we will only accept the highest TLS
version supported by the local SSL implementation.
-
-Also see
-.B \-\-tls\-version\-max
-below, for information on compatibility.
.\"*********************************************************
.TP
.B \-\-tls\-version\-max version
Set the maximum TLS version we will use (default is the highest version
supported). Examples for version include "1.0", "1.1", or "1.2".
-
-If and only if this is set to 1.0, and OpenSSL is used (not PolarSSL),
-then OpenVPN will set up OpenSSL to use a fixed TLSv1 handshake. All
-other configurations will autonegotiate in the given limits, and the
-choice of handshake versions is left to the SSL implementation.
.\"*********************************************************
.TP
.B \-\-pkcs12 file
@@ -4429,7 +4704,7 @@ and
.B \-\-pkcs12.
If p11-kit is present on the system, its
-.B p11-kit-proxy.so
+.B p11\-kit\-proxy.so
module will be loaded by default if either the
.B \-\-pkcs11\-id
or
@@ -4505,7 +4780,10 @@ 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.
+the other host over the TLS channel. Method 1 is
+.B deprecated in OpenVPN 2.4
+, and
+.B will be removed in OpenVPN 2.5\fR.
In method 2, (the default for OpenVPN 2.0)
the client generates a random key. Both client
@@ -4556,7 +4834,8 @@ your VPN connection. But it is also easy to unwittingly use it to carefully
align a gun with your foot, or just break your connection. Use with care!
The default for \-\-tls\-cipher is to use PolarSSL's default cipher list
-when using PolarSSL or "DEFAULT:!EXP:!LOW:!MEDIUM:!PSK:!SRP:!kRSA" when using
+when using PolarSSL or
+"DEFAULT:!EXP:!LOW:!MEDIUM:!kDH:!kECDH:!DSS:!PSK:!SRP:!kRSA" when using
OpenSSL.
.\"*********************************************************
.TP
@@ -4657,8 +4936,8 @@ 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.
+Add an additional layer of HMAC authentication on top of the TLS control channel
+to mitigate DoS attacks and attacks on the TLS stack.
In a nutshell,
.B \-\-tls\-auth
@@ -4668,27 +4947,11 @@ 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
+(required) is a file in OpenVPN static key format which can be generated by
.B \-\-genkey
-(required if
-.B direction
-parameter is used).
-.B (2) DEPRECATED
-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. This option is deprecated and will stop working in OpenVPN 2.4 and
-newer releases.
-
-OpenVPN will first try format (1), and if the file fails to parse as
-a static key file, format (2) will be used.
+Older versions (up to 2.3) supported a freeform passphrase file.
+This is no longer supported in newer versions (2.4+).
See the
.B \-\-secret
@@ -4745,12 +5008,39 @@ 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
+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 \-\-tls\-crypt keyfile
+
+Encrypt and authenticate all control channel packets with the key from
+.B keyfile.
+(See
+.B \-\-tls\-auth
+for more background.)
+
+Encrypting (and authenticating) control channel packets:
+.RS
+.IP \[bu] 2
+provides more privacy by hiding the certificate used for the TLS connection,
+.IP \[bu]
+makes it harder to identify OpenVPN traffic as such,
+.IP \[bu]
+provides "poor-man's" post-quantum security, against attackers who will never
+know the pre-shared key (i.e. no forward secrecy).
+.RE
+
+.IP
+In contrast to
+.B \-\-tls\-auth\fR,
+.B \-\-tls\-crypt
+does *not* require the user to set
+.B \-\-key\-direction\fR.
+.\"*********************************************************
+.TP
.B \-\-askpass [file]
Get certificate password from console or
.B file
@@ -4837,7 +5127,7 @@ 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
+.B verify\-cn
in the OpenVPN distribution.
See the "Environmental Variables" section below for
@@ -4848,7 +5138,7 @@ additional parameters passed as environmental variables.
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
+the tls\-verify script returns. The file name used for the certificate
is available via the peer_cert environment variable.
.\"*********************************************************
.TP
@@ -4892,49 +5182,6 @@ prefix will be left as-is. This automatic upcasing feature
is deprecated and will be removed in a future release.
.\"*********************************************************
.TP
-.B \-\-tls\-remote name (DEPRECATED)
-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.
-
-.B Please also note:
-This option is now deprecated. It will be removed either in OpenVPN v2.4
-or v2.5. So please make sure you support the new X.509 name formatting
-described with the
-.B \-\-compat\-names
-option as soon as possible by updating your configurations to use
-.B \-\-verify\-x509\-name
-instead.
-.\"*********************************************************
-.TP
.B \-\-verify\-x509\-name name type
Accept connections only if a host's X.509 name is equal to
.B name.
@@ -4951,11 +5198,11 @@ Which RDN is verified as name depends on the
option. But it defaults to the common name (CN), e.g. a certificate with a
subject DN "C=KG, ST=NA, L=Bishkek, CN=Server-1" would be matched by:
-.B \-\-verify\-x509\-name 'C=KG, ST=NA, L=Bishkek, CN=Server-1'
+.B \-\-verify\-x509\-name 'C=KG, ST=NA, L=Bishkek, CN=Server\-1'
and
-.B \-\-verify\-x509\-name Server-1 name
+.B \-\-verify\-x509\-name Server\-1 name
or you could use
-.B \-\-verify\-x509\-name Server- name-prefix
+.B \-\-verify\-x509\-name Server -name-prefix
if you want a client to only accept connections to "Server-1", "Server-2", etc.
.B \-\-verify\-x509\-name
@@ -4989,7 +5236,6 @@ 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
@@ -5000,7 +5246,7 @@ 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
+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".
@@ -5143,6 +5389,13 @@ an ECDSA cipher suite will not work if you are using an RSA certificate, etc.).
Show currently available hardware-based crypto acceleration
engines supported by the OpenSSL library.
.\"*********************************************************
+.TP
+.B \-\-show\-curves
+(Standalone)
+Show all available elliptic curves to use with the
+.B \-\-ecdh\-curve
+option.
+.\"*********************************************************
.SS Generate a random key:
Used only for non-TLS static key encryption mode.
.\"*********************************************************
@@ -5253,7 +5506,7 @@ IP address and netmask using
Don't use this option unless you are also using
.B \-\-ifconfig.
-.B manual --
+.B manual \-\-
Don't set the IP address or netmask automatically.
Instead output a message
to the console telling the user to configure the
@@ -5279,7 +5532,7 @@ 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.
+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
@@ -5298,13 +5551,13 @@ 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 --
+.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 --
+.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
@@ -5313,7 +5566,7 @@ 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 --
+.B adaptive \-\-
(Default) Try
.B dynamic
method initially and fail over to
@@ -5370,28 +5623,28 @@ 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 --
+.B DOMAIN name \-\-
Set Connection-specific DNS Suffix.
-.B DNS addr --
+.B DNS addr \-\-
Set primary domain name server address. Repeat
this option to set secondary DNS server addresses.
-.B WINS addr --
+.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 --
+.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 --
+.B NTP addr \-\-
Set primary NTP server address (Network Time Protocol).
Repeat this option
to set secondary NTP server addresses.
-.B NBT type --
+.B NBT type \-\-
Set NetBIOS over TCP/IP Node type. Possible options:
.B 1
= b-node (broadcasts),
@@ -5498,7 +5751,7 @@ Windows explorer when OpenVPN is run on a configuration
file using the right-click explorer menu.
.\"*********************************************************
.TP
-.B \-\-service exit\-event [0|1]
+.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
@@ -5540,7 +5793,7 @@ option. On non-Windows systems, the
command provides similar functionality.
.\"*********************************************************
.TP
-.B \-\-allow\-nonadmin [TAP-adapter]
+.B \-\-allow\-nonadmin [TAP\-adapter]
(Standalone)
Set
.B TAP-adapter
@@ -5584,12 +5837,21 @@ if certificates are stored as private objects.
If p11-kit is present on the system, the
.B provider
argument is optional; if omitted the default
-.B p11-kit-proxy.so
+.B p11\-kit\-proxy.so
module will be queried.
.B \-\-verb
option can be used BEFORE this option to produce debugging information.
.\"*********************************************************
+.SS Standalone Debug Options:
+.\"*********************************************************
+.TP
+.B \-\-show\-gateway [v6target]
+(Standalone)
+Show current IPv4 and IPv6 default gateway and interface towards the
+gateway (if the protocol in question is enabled). If an IPv6 address
+is passed as argument, the IPv6 route for this host is reported.
+.\"*********************************************************
.SS IPv6 Related Options
.\"*********************************************************
The following options exist to support IPv6 tunneling in peer-to-peer
@@ -5608,24 +5870,28 @@ 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
+into OpenVPN's ``tun''. The gateway parameter is only used for
+IPv6 routes across ``tap'' devices, and if missing, the ``ipv6remote''
+field from
+.B \-\-ifconfig\-ipv6
+is used.
.TP
.B \-\-server\-ipv6 ipv6addr/bits
convenience-function to enable a number of IPv6 related options at
once, namely
-.B \-\-ifconfig\-ipv6, \-\-ifconfig\-ipv6\-pool, \-\-tun\-ipv6
+.B \-\-ifconfig\-ipv6, \-\-ifconfig\-ipv6\-pool
and
.B \-\-push tun\-ipv6
-Is only accepted if ``\-\-mode server'' or ``\-\-server'' is set.
+Is only accepted if ``\-\-mode server'' or ``\-\-server'' is set. Pushing of the
+.B \-\-tun\-ipv6
+directive is done for older clients which require an explicit
+``\-\-tun\-ipv6'' in their configuration.
.TP
.B \-\-ifconfig\-ipv6\-pool ipv6addr/bits
Specify an IPv6 address pool for dynamic assignment to clients. The
pool starts at
.B ipv6addr
-and increments by +1 for every new client (linear mode). The
-.B /bits
-setting controls the size of the pool. Due to implementation details,
-the pool size must be between /64 and /112.
+and matches the offset determined from the start of the IPv4 pool.
.TP
.B \-\-ifconfig\-ipv6\-push ipv6addr/bits ipv6remote
for ccd/ per-client static IPv6 interface configuration, see
@@ -6035,7 +6301,7 @@ Set on program initiation and reset on SIGHUP.
.\"*********************************************************
.TP
.B local_port
-The local port number, specified by
+The local port number or name, specified by
.B \-\-port
or
.B \-\-lport.
@@ -6047,7 +6313,7 @@ The password provided by a connecting client.
Set prior to
.B \-\-auth\-user\-pass\-verify
script execution only when the
-.B via-env
+.B via\-env
modifier is specified, and deleted from the environment
after the script returns.
.\"*********************************************************
@@ -6150,10 +6416,10 @@ documentation for
.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,
+.B up, down, ipchange, route\-up, tls\-verify, auth\-user\-pass\-verify,
+.B client\-connect, client\-disconnect,
or
-.B learn-address.
+.B learn\-address.
Set prior to execution of any script.
.\"*********************************************************
.TP
@@ -6163,15 +6429,15 @@ The reason for exit or restart. Can be one of
(controlled by
.B \-\-inactive
option),
-.B ping-exit
+.B ping\-exit
(controlled by
.B \-\-ping\-exit
option),
-.B ping-restart
+.B ping\-restart
(controlled by
.B \-\-ping\-restart
option),
-.B connection-reset
+.B connection\-reset
(triggered on TCP connection reset),
.B error,
or
@@ -6203,9 +6469,8 @@ Set prior to execution of the
script.
.\"*********************************************************
.TP
-.B tls_digest_{n}
-Contains the certificate SHA1 fingerprint/digest hash value,
-where
+.B tls_digest_{n} / tls_digest_sha256_{n}
+Contains the certificate SHA1 / SHA256 fingerprint, where
.B n
is the verification level. Only set for TLS connections. Set prior
to execution of
@@ -6306,7 +6571,7 @@ The username provided by a connecting client.
Set prior to
.B \-\-auth\-user\-pass\-verify
script execution only when the
-.B via-env
+.B via\-env
modifier is specified.
.\"*********************************************************
.TP
@@ -6324,7 +6589,7 @@ 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).
+in sample\-keys (client.crt).
Note that the verification level is 0 for the client certificate
and 1 for the CA certificate.
@@ -6347,7 +6612,8 @@ X509_1_C=KG
.\"*********************************************************
.SH INLINE FILE SUPPORT
OpenVPN allows including files in the main configuration for the
-.B \-\-ca, \-\-cert, \-\-dh, \-\-extra\-certs, \-\-key, \-\-pkcs12, \-\-secret
+.B \-\-ca, \-\-cert, \-\-dh, \-\-extra\-certs, \-\-key, \-\-pkcs12, \-\-secret,
+.B \-\-crl\-verify, \-\-http\-proxy\-user\-pass
and
.B \-\-tls\-auth
options.
generated by cgit v1.2.3 (git 2.25.1) at 2024-11-11 10:17:20 +0000