diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/man-sections/advanced-options.rst | 7 | ||||
| -rw-r--r-- | doc/man-sections/client-options.rst | 60 | ||||
| -rw-r--r-- | doc/man-sections/generic-options.rst | 7 | ||||
| -rw-r--r-- | doc/man-sections/script-options.rst | 13 | ||||
| -rw-r--r-- | doc/man-sections/server-options.rst | 36 | ||||
| -rw-r--r-- | doc/man-sections/vpn-network-options.rst | 4 | ||||
| -rw-r--r-- | doc/openvpn.8 | 141 | ||||
| -rw-r--r-- | doc/openvpn.8.html | 134 |
8 files changed, 283 insertions, 119 deletions
diff --git a/doc/man-sections/advanced-options.rst b/doc/man-sections/advanced-options.rst index 9b96e40..bedc884 100644 --- a/doc/man-sections/advanced-options.rst +++ b/doc/man-sections/advanced-options.rst @@ -11,8 +11,11 @@ Standalone Debug Options --show-gateway --show-gateway IPv6-target - If an IPv6 target address is passed as argument, the IPv6 route for this - host is reported. + For IPv6 this queries the route towards ::/128, or the specified IPv6 + target address if passed as argument. + For IPv4 on Linux, Windows, MacOS and BSD it looks for a 0.0.0.0/0 route. + If there are more specific routes, the result will not always be matching + the route of the IPv4 packets to the VPN gateway. Advanced Expert Options diff --git a/doc/man-sections/client-options.rst b/doc/man-sections/client-options.rst index ec1e3b1..af21fbc 100644 --- a/doc/man-sections/client-options.rst +++ b/doc/man-sections/client-options.rst @@ -244,43 +244,51 @@ configuration. use :code:`ignore`. --remote args - Remote host name or IP address. It supports two additional optional - arguments: ``port`` and ``proto``. On the client, multiple ``--remote`` - options may be specified for redundancy, each referring to a different - OpenVPN server. Specifying multiple ``--remote`` options for this - purpose is a special case of the more general connection-profile - feature. See the ``<connection>`` documentation below. + Remote host name or IP address, port and protocol. - The OpenVPN client will try to connect to a server at ``host:port`` in - the order specified by the list of ``--remote`` options. - - Examples: + Valid syntaxes: :: - remote server.example.net - remote server.example.net 1194 - remote server.example.net tcp + remote host + remote host port + remote host port proto - ``proto`` indicates the protocol to use when connecting with the remote, - and may be :code:`tcp` or :code:`udp`. + The ``port`` and ``proto`` arguments are optional. The OpenVPN client + will try to connect to a server at ``host:port``. The ``proto`` argument + indicates the protocol to use when connecting with the remote, and may be + :code:`tcp` or :code:`udp`. To enforce IPv4 or IPv6 connections add a + :code:`4` or :code:`6` suffix; like :code:`udp4` / :code:`udp6` + / :code:`tcp4` / :code:`tcp6`. - For forcing IPv4 or IPv6 connection suffix tcp or udp with 4/6 like - udp4/udp6/tcp4/tcp6. + On the client, multiple ``--remote`` options may be specified for + redundancy, each referring to a different OpenVPN server, in the order + specified by the list of ``--remote`` options. Specifying multiple + ``--remote`` options for this purpose is a special case of the more + general connection-profile feature. See the ``<connection>`` + documentation below. The client will move on to the next host in the list, in the event of connection failure. Note that at any given time, the OpenVPN client will at most be connected to one server. - Note that since UDP is connectionless, connection failure is defined by - the ``--ping`` and ``--ping-restart`` options. + Examples: + :: - Note the following corner case: If you use multiple ``--remote`` - options, AND you are dropping root privileges on the client with - ``--user`` and/or ``--group`` AND the client is running a non-Windows - OS, if the client needs to switch to a different server, and that server - pushes back different TUN/TAP or route settings, the client may lack the - necessary privileges to close and reopen the TUN/TAP interface. This - could cause the client to exit with a fatal error. + remote server1.example.net + remote server1.example.net 1194 + remote server2.example.net 1194 tcp + + *Note:* + Since UDP is connectionless, connection failure is defined by + the ``--ping`` and ``--ping-restart`` options. + + Also, if you use multiple ``--remote`` options, AND you are dropping + root privileges on the client with ``--user`` and/or ``--group`` AND + the client is running a non-Windows OS, if the client needs to switch + to a different server, and that server pushes back different TUN/TAP + or route settings, the client may lack the necessary privileges to + close and reopen the TUN/TAP interface. This could cause the client + to exit with a fatal error. If ``--remote`` is unspecified, OpenVPN will listen for packets from any IP address, but will not act on those packets unless they pass all diff --git a/doc/man-sections/generic-options.rst b/doc/man-sections/generic-options.rst index a07fe7e..d5f0883 100644 --- a/doc/man-sections/generic-options.rst +++ b/doc/man-sections/generic-options.rst @@ -230,6 +230,13 @@ which mode OpenVPN is configured as. The downside of using ``--mlock`` is that it will reduce the amount of physical memory available to other applications. + The limit on how much memory can be locked and how that limit + is enforced are OS-dependent. On Linux the default limit that an + unprivileged process may lock (RLIMIT_MEMLOCK) is low, and if + privileges are dropped later, future memory allocations will very + likely fail. The limit can be increased using ulimit or systemd + directives depending on how OpenVPN is started. + --nice n Change process priority after initialization (``n`` greater than 0 is lower priority, ``n`` less than zero is higher priority). diff --git a/doc/man-sections/script-options.rst b/doc/man-sections/script-options.rst index b4bbf52..03b3dd7 100644 --- a/doc/man-sections/script-options.rst +++ b/doc/man-sections/script-options.rst @@ -157,9 +157,8 @@ SCRIPT HOOKS where some of the related client-connect functions returned an error status. - The ``--client-disconnect`` command is passed the same pathname as the - corresponding ``--client-connect`` command as its last argument (after - any arguments specified in ``cmd``). + The ``--client-disconnect`` command is not passed any extra arguments + (only those arguments specified in cmd, if any). --down cmd Run command ``cmd`` after TUN/TAP device close (post ``--user`` UID @@ -710,10 +709,10 @@ instances. A set of variables which define each IPv6 route to be added, and are set prior to **--up** script execution. - ``parm`` will be one of :code:`network` or :code:`gateway` - (:code:`netmask` is contained as :code:`/nnn` in the - ``route_ipv6_network_{n}``, unlike IPv4 where it is passed in a - separate environment variable). + ``parm`` will be one of :code:`network`, :code:`gateway` or + :code:`metric`. ``route_ipv6_network_{n}`` contains :code:`netmask` + as :code:`/nnn`, unlike IPv4 where it is passed in a separate environment + variable. ``n`` is the OpenVPN route number, starting from 1. diff --git a/doc/man-sections/server-options.rst b/doc/man-sections/server-options.rst index f1f0667..5a68945 100644 --- a/doc/man-sections/server-options.rst +++ b/doc/man-sections/server-options.rst @@ -204,7 +204,8 @@ fast hardware. SSL/TLS authentication must be used in this mode. ifconfig-ipv6-pool ipv6addr/bits The pool starts at ``ipv6addr`` and matches the offset determined from - the start of the IPv4 pool. + the start of the IPv4 pool. If the host part of the given IPv6 + address is ``0``, the pool starts at ``ipv6addr`` +1. --ifconfig-pool-persist args Persist/unpersist ifconfig-pool data to ``file``, at ``seconds`` @@ -530,6 +531,14 @@ fast hardware. SSL/TLS authentication must be used in this mode. ``--client-config-dir`` configuration file. This option will ignore ``--push`` options at the global config file level. + *NOTE*: ``--push-reset`` is very thorough: it will remove almost + all options from the list of to-be-pushed options. In many cases, + some of these options will need to be re-configured afterwards - + specifically, ``--topology subnet`` and ``--route-gateway`` will get + lost and this will break client configs in many cases. Thus, for most + purposes, ``--push-remove`` is better suited to selectively remove + push options for individual clients. + --server args A helper directive designed to simplify the configuration of OpenVPN's server mode. This directive will set up an OpenVPN server which will @@ -631,6 +640,19 @@ fast hardware. SSL/TLS authentication must be used in this mode. mode server tls-server +--server-ipv6 args + Convenience-function to enable a number of IPv6 related options at once, + namely ``--ifconfig-ipv6``, ``--ifconfig-ipv6-pool`` and + ``--push tun-ipv6``. + + Valid syntax: + :: + + server-ipv6 ipv6addr/bits + + Pushing of the ``--tun-ipv6`` directive is done for older clients which + require an explicit ``--tun-ipv6`` in their configuration. + --stale-routes-check args Remove routes which haven't had activity for ``n`` seconds (i.e. the ageing time). This check is run every ``t`` seconds (i.e. check interval). @@ -646,9 +668,15 @@ fast hardware. SSL/TLS authentication must be used in this mode. ``--max-routes-per-client`` --username-as-common-name - For ``--auth-user-pass-verify`` authentication, use the authenticated - username as the common name, rather than the common name from the client - cert. + Use the authenticated username as the common-name, rather than the + common-name from the client certificate. Requires that some form of + ``--auth-user-pass`` verification is in effect. As the replacement happens + after ``--auth-user-pass`` verification, the verification script or + plugin will still receive the common-name from the certificate. + + The common_name environment variable passed to scripts and plugins invoked + after authentication (e.g, client-connect script) and file names parsed in + client-config directory will match the username. --verify-client-cert mode Specify whether the client is required to supply a valid certificate. diff --git a/doc/man-sections/vpn-network-options.rst b/doc/man-sections/vpn-network-options.rst index 825dd1c..2668278 100644 --- a/doc/man-sections/vpn-network-options.rst +++ b/doc/man-sections/vpn-network-options.rst @@ -114,6 +114,10 @@ routing. :code:`DOMAIN` ``name`` Set Connection-specific DNS Suffix to :code:`name`. + :code:`ADAPTER_DOMAIN_SUFFIX` ``name`` + Alias to :code:`DOMAIN`. This is a compatibility option, it + should not be used in new deployments. + :code:`DOMAIN-SEARCH` ``name`` Add :code:`name` to the domain search list. Repeat this option to add more entries. Up to diff --git a/doc/openvpn.8 b/doc/openvpn.8 index b914f32..a504ce9 100644 --- a/doc/openvpn.8 +++ b/doc/openvpn.8 @@ -343,6 +343,13 @@ below), then are discarded. .sp The downside of using \fB\-\-mlock\fP is that it will reduce the amount of physical memory available to other applications. +.sp +The limit on how much memory can be locked and how that limit +is enforced are OS\-dependent. On Linux the default limit that an +unprivileged process may lock (RLIMIT_MEMLOCK) is low, and if +privileges are dropped later, future memory allocations will very +likely fail. The limit can be increased using ulimit or systemd +directives depending on how OpenVPN is started. .TP .BI \-\-nice \ n Change process priority after initialization (\fBn\fP greater than 0 is @@ -1268,50 +1275,67 @@ next remote succeeds. To silently ignore an option pushed by the server, use \fBignore\fP\&. .TP .BI \-\-remote \ args -Remote host name or IP address. It supports two additional optional -arguments: \fBport\fP and \fBproto\fP\&. On the client, multiple \fB\-\-remote\fP -options may be specified for redundancy, each referring to a different -OpenVPN server. Specifying multiple \fB\-\-remote\fP options for this -purpose is a special case of the more general connection\-profile -feature. See the \fB<connection>\fP documentation below. -.sp -The OpenVPN client will try to connect to a server at \fBhost:port\fP in -the order specified by the list of \fB\-\-remote\fP options. +Remote host name or IP address, port and protocol. .sp -Examples: +Valid syntaxes: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C -remote server.example.net -remote server.example.net 1194 -remote server.example.net tcp +remote host +remote host port +remote host port proto .ft P .fi .UNINDENT .UNINDENT .sp -\fBproto\fP indicates the protocol to use when connecting with the remote, -and may be \fBtcp\fP or \fBudp\fP\&. +The \fBport\fP and \fBproto\fP arguments are optional. The OpenVPN client +will try to connect to a server at \fBhost:port\fP\&. The \fBproto\fP argument +indicates the protocol to use when connecting with the remote, and may be +\fBtcp\fP or \fBudp\fP\&. To enforce IPv4 or IPv6 connections add a +\fB4\fP or \fB6\fP suffix; like \fBudp4\fP / \fBudp6\fP +/ \fBtcp4\fP / \fBtcp6\fP\&. .sp -For forcing IPv4 or IPv6 connection suffix tcp or udp with 4/6 like -udp4/udp6/tcp4/tcp6. +On the client, multiple \fB\-\-remote\fP options may be specified for +redundancy, each referring to a different OpenVPN server, in the order +specified by the list of \fB\-\-remote\fP options. Specifying multiple +\fB\-\-remote\fP options for this purpose is a special case of the more +general connection\-profile feature. See the \fB<connection>\fP +documentation below. .sp The client will move on to the next host in the list, in the event of connection failure. Note that at any given time, the OpenVPN client will at most be connected to one server. .sp -Note that since UDP is connectionless, connection failure is defined by +Examples: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +remote server1.example.net +remote server1.example.net 1194 +remote server2.example.net 1194 tcp +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 7.0 +.TP +.B \fINote:\fP +Since UDP is connectionless, connection failure is defined by the \fB\-\-ping\fP and \fB\-\-ping\-restart\fP options. .sp -Note the following corner case: If you use multiple \fB\-\-remote\fP -options, AND you are dropping root privileges on the client with -\fB\-\-user\fP and/or \fB\-\-group\fP AND the client is running a non\-Windows -OS, if the client needs to switch to a different server, and that server -pushes back different TUN/TAP or route settings, the client may lack the -necessary privileges to close and reopen the TUN/TAP interface. This -could cause the client to exit with a fatal error. +Also, if you use multiple \fB\-\-remote\fP options, AND you are dropping +root privileges on the client with \fB\-\-user\fP and/or \fB\-\-group\fP AND +the client is running a non\-Windows OS, if the client needs to switch +to a different server, and that server pushes back different TUN/TAP +or route settings, the client may lack the necessary privileges to +close and reopen the TUN/TAP interface. This could cause the client +to exit with a fatal error. +.UNINDENT .sp If \fB\-\-remote\fP is unspecified, OpenVPN will listen for packets from any IP address, but will not act on those packets unless they pass all @@ -1709,7 +1733,8 @@ ifconfig\-ipv6\-pool ipv6addr/bits .UNINDENT .sp The pool starts at \fBipv6addr\fP and matches the offset determined from -the start of the IPv4 pool. +the start of the IPv4 pool. If the host part of the given IPv6 +address is \fB0\fP, the pool starts at \fBipv6addr\fP +1. .TP .BI \-\-ifconfig\-pool\-persist \ args Persist/unpersist ifconfig\-pool data to \fBfile\fP, at \fBseconds\fP @@ -2098,6 +2123,14 @@ Don\(aqt inherit the global push list for a specific client instance. Specify this option in a client\-specific context such as with a \fB\-\-client\-config\-dir\fP configuration file. This option will ignore \fB\-\-push\fP options at the global config file level. +.sp +\fINOTE\fP: \fB\-\-push\-reset\fP is very thorough: it will remove almost +all options from the list of to\-be\-pushed options. In many cases, +some of these options will need to be re\-configured afterwards \- +specifically, \fB\-\-topology subnet\fP and \fB\-\-route\-gateway\fP will get +lost and this will break client configs in many cases. Thus, for most +purposes, \fB\-\-push\-remove\fP is better suited to selectively remove +push options for individual clients. .TP .BI \-\-server \ args A helper directive designed to simplify the configuration of OpenVPN\(aqs @@ -2242,6 +2275,26 @@ tls\-server .UNINDENT .UNINDENT .TP +.BI \-\-server\-ipv6 \ args +Convenience\-function to enable a number of IPv6 related options at once, +namely \fB\-\-ifconfig\-ipv6\fP, \fB\-\-ifconfig\-ipv6\-pool\fP and +\fB\-\-push tun\-ipv6\fP\&. +.sp +Valid syntax: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +server\-ipv6 ipv6addr/bits +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Pushing of the \fB\-\-tun\-ipv6\fP directive is done for older clients which +require an explicit \fB\-\-tun\-ipv6\fP in their configuration. +.TP .BI \-\-stale\-routes\-check \ args Remove routes which haven\(aqt had activity for \fBn\fP seconds (i.e. the ageing time). This check is run every \fBt\fP seconds (i.e. check interval). @@ -2264,9 +2317,15 @@ This option helps to keep the dynamic routing table small. See also \fB\-\-max\-routes\-per\-client\fP .TP .B \-\-username\-as\-common\-name -For \fB\-\-auth\-user\-pass\-verify\fP authentication, use the authenticated -username as the common name, rather than the common name from the client -cert. +Use the authenticated username as the common\-name, rather than the +common\-name from the client certificate. Requires that some form of +\fB\-\-auth\-user\-pass\fP verification is in effect. As the replacement happens +after \fB\-\-auth\-user\-pass\fP verification, the verification script or +plugin will still receive the common\-name from the certificate. +.sp +The common_name environment variable passed to scripts and plugins invoked +after authentication (e.g, client\-connect script) and file names parsed in +client\-config directory will match the username. .TP .BI \-\-verify\-client\-cert \ mode Specify whether the client is required to supply a valid certificate. @@ -4271,6 +4330,10 @@ dhcp\-options type [parm] .B \fBDOMAIN\fP \fBname\fP Set Connection\-specific DNS Suffix to \fBname\fP\&. .TP +.B \fBADAPTER_DOMAIN_SUFFIX\fP \fBname\fP +Alias to \fBDOMAIN\fP\&. This is a compatibility option, it +should not be used in new deployments. +.TP .B \fBDOMAIN\-SEARCH\fP \fBname\fP Add \fBname\fP to the domain search list. Repeat this option to add more entries. Up to @@ -5020,9 +5083,8 @@ plugins will be called on client instance object deletion, even in cases where some of the related client\-connect functions returned an error status. .sp -The \fB\-\-client\-disconnect\fP command is passed the same pathname as the -corresponding \fB\-\-client\-connect\fP command as its last argument (after -any arguments specified in \fBcmd\fP). +The \fB\-\-client\-disconnect\fP command is not passed any extra arguments +(only those arguments specified in cmd, if any). .TP .BI \-\-down \ cmd Run command \fBcmd\fP after TUN/TAP device close (post \fB\-\-user\fP UID @@ -5632,10 +5694,10 @@ command line or configuration file. A set of variables which define each IPv6 route to be added, and are set prior to \fB\-\-up\fP script execution. .sp -\fBparm\fP will be one of \fBnetwork\fP or \fBgateway\fP -(\fBnetmask\fP is contained as \fB/nnn\fP in the -\fBroute_ipv6_network_{n}\fP, unlike IPv4 where it is passed in a -separate environment variable). +\fBparm\fP will be one of \fBnetwork\fP, \fBgateway\fP or +\fBmetric\fP\&. \fBroute_ipv6_network_{n}\fP contains \fBnetmask\fP +as \fB/nnn\fP, unlike IPv4 where it is passed in a separate environment +variable. .sp \fBn\fP is the OpenVPN route number, starting from 1. .sp @@ -6283,8 +6345,11 @@ Valid syntax: .UNINDENT .UNINDENT .sp -If an IPv6 target address is passed as argument, the IPv6 route for this -host is reported. +For IPv6 this queries the route towards ::/128, or the specified IPv6 +target address if passed as argument. +For IPv4 on Linux, Windows, MacOS and BSD it looks for a 0.0.0.0/0 route. +If there are more specific routes, the result will not always be matching +the route of the IPv4 packets to the VPN gateway. .UNINDENT .SS Advanced Expert Options .sp diff --git a/doc/openvpn.8.html b/doc/openvpn.8.html index d6b2719..b941476 100644 --- a/doc/openvpn.8.html +++ b/doc/openvpn.8.html @@ -3,7 +3,7 @@ <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> -<meta name="generator" content="Docutils 0.14: http://docutils.sourceforge.net/" /> +<meta name="generator" content="Docutils 0.15.2: http://docutils.sourceforge.net/" /> <title>openvpn</title> <style type="text/css"> @@ -634,8 +634,14 @@ was able to crack the box running OpenVPN, he would not be able to scan the system swap file to recover previously used ephemeral keys, which are used for a period of time governed by the <tt class="docutils literal"><span class="pre">--reneg</span></tt> options (see below), then are discarded.</p> -<p class="last">The downside of using <tt class="docutils literal"><span class="pre">--mlock</span></tt> is that it will reduce the amount of +<p>The downside of using <tt class="docutils literal"><span class="pre">--mlock</span></tt> is that it will reduce the amount of physical memory available to other applications.</p> +<p class="last">The limit on how much memory can be locked and how that limit +is enforced are OS-dependent. On Linux the default limit that an +unprivileged process may lock (RLIMIT_MEMLOCK) is low, and if +privileges are dropped later, future memory allocations will very +likely fail. The limit can be increased using ulimit or systemd +directives depending on how OpenVPN is started.</p> </td></tr> <tr><td class="option-group"> <kbd><span class="option">--nice <var>n</var></span></kbd></td> @@ -1423,36 +1429,47 @@ use <code>ignore</code>.</p> </td></tr> <tr><td class="option-group"> <kbd><span class="option">--remote <var>args</var></span></kbd></td> -<td><p class="first">Remote host name or IP address. It supports two additional optional -arguments: <tt class="docutils literal">port</tt> and <tt class="docutils literal">proto</tt>. On the client, multiple <tt class="docutils literal"><span class="pre">--remote</span></tt> -options may be specified for redundancy, each referring to a different -OpenVPN server. Specifying multiple <tt class="docutils literal"><span class="pre">--remote</span></tt> options for this -purpose is a special case of the more general connection-profile -feature. See the <tt class="docutils literal"><connection></tt> documentation below.</p> -<p>The OpenVPN client will try to connect to a server at <tt class="docutils literal">host:port</tt> in -the order specified by the list of <tt class="docutils literal"><span class="pre">--remote</span></tt> options.</p> -<p>Examples:</p> +<td><p class="first">Remote host name or IP address, port and protocol.</p> +<p>Valid syntaxes:</p> <pre class="literal-block"> -remote server.example.net -remote server.example.net 1194 -remote server.example.net tcp -</pre> -<p><tt class="docutils literal">proto</tt> indicates the protocol to use when connecting with the remote, -and may be <code>tcp</code> or <code>udp</code>.</p> -<p>For forcing IPv4 or IPv6 connection suffix tcp or udp with 4/6 like -udp4/udp6/tcp4/tcp6.</p> +remote host +remote host port +remote host port proto +</pre> +<p>The <tt class="docutils literal">port</tt> and <tt class="docutils literal">proto</tt> arguments are optional. The OpenVPN client +will try to connect to a server at <tt class="docutils literal">host:port</tt>. The <tt class="docutils literal">proto</tt> argument +indicates the protocol to use when connecting with the remote, and may be +<code>tcp</code> or <code>udp</code>. To enforce IPv4 or IPv6 connections add a +<code>4</code> or <code>6</code> suffix; like <code>udp4</code> / <code>udp6</code> +/ <code>tcp4</code> / <code>tcp6</code>.</p> +<p>On the client, multiple <tt class="docutils literal"><span class="pre">--remote</span></tt> options may be specified for +redundancy, each referring to a different OpenVPN server, in the order +specified by the list of <tt class="docutils literal"><span class="pre">--remote</span></tt> options. Specifying multiple +<tt class="docutils literal"><span class="pre">--remote</span></tt> options for this purpose is a special case of the more +general connection-profile feature. See the <tt class="docutils literal"><connection></tt> +documentation below.</p> <p>The client will move on to the next host in the list, in the event of connection failure. Note that at any given time, the OpenVPN client will at most be connected to one server.</p> -<p>Note that since UDP is connectionless, connection failure is defined by +<p>Examples:</p> +<pre class="literal-block"> +remote server1.example.net +remote server1.example.net 1194 +remote server2.example.net 1194 tcp +</pre> +<dl class="docutils"> +<dt><em>Note:</em></dt> +<dd><p class="first">Since UDP is connectionless, connection failure is defined by the <tt class="docutils literal"><span class="pre">--ping</span></tt> and <tt class="docutils literal"><span class="pre">--ping-restart</span></tt> options.</p> -<p>Note the following corner case: If you use multiple <tt class="docutils literal"><span class="pre">--remote</span></tt> -options, AND you are dropping root privileges on the client with -<tt class="docutils literal"><span class="pre">--user</span></tt> and/or <tt class="docutils literal"><span class="pre">--group</span></tt> AND the client is running a non-Windows -OS, if the client needs to switch to a different server, and that server -pushes back different TUN/TAP or route settings, the client may lack the -necessary privileges to close and reopen the TUN/TAP interface. This -could cause the client to exit with a fatal error.</p> +<p class="last">Also, if you use multiple <tt class="docutils literal"><span class="pre">--remote</span></tt> options, AND you are dropping +root privileges on the client with <tt class="docutils literal"><span class="pre">--user</span></tt> and/or <tt class="docutils literal"><span class="pre">--group</span></tt> AND +the client is running a non-Windows OS, if the client needs to switch +to a different server, and that server pushes back different TUN/TAP +or route settings, the client may lack the necessary privileges to +close and reopen the TUN/TAP interface. This could cause the client +to exit with a fatal error.</p> +</dd> +</dl> <p>If <tt class="docutils literal"><span class="pre">--remote</span></tt> is unspecified, OpenVPN will listen for packets from any IP address, but will not act on those packets unless they pass all authentication tests. This requirement for authentication is binding on @@ -1794,7 +1811,8 @@ optional <tt class="docutils literal">netmask</tt> parameter will also be pushed ifconfig-ipv6-pool ipv6addr/bits </pre> <p class="last">The pool starts at <tt class="docutils literal">ipv6addr</tt> and matches the offset determined from -the start of the IPv4 pool.</p> +the start of the IPv4 pool. If the host part of the given IPv6 +address is <tt class="docutils literal">0</tt>, the pool starts at <tt class="docutils literal">ipv6addr</tt> +1.</p> </td></tr> <tr><td class="option-group" colspan="2"> <kbd><span class="option">--ifconfig-pool-persist <var>args</var></span></kbd></td> @@ -2102,10 +2120,18 @@ the IPv4/IPv6 address argument is possible.</p> </td></tr> <tr><td class="option-group"> <kbd><span class="option">--push-reset</span></kbd></td> -<td>Don't inherit the global push list for a specific client instance. +<td><p class="first">Don't inherit the global push list for a specific client instance. Specify this option in a client-specific context such as with a <tt class="docutils literal"><span class="pre">--client-config-dir</span></tt> configuration file. This option will ignore -<tt class="docutils literal"><span class="pre">--push</span></tt> options at the global config file level.</td></tr> +<tt class="docutils literal"><span class="pre">--push</span></tt> options at the global config file level.</p> +<p class="last"><em>NOTE</em>: <tt class="docutils literal"><span class="pre">--push-reset</span></tt> is very thorough: it will remove almost +all options from the list of to-be-pushed options. In many cases, +some of these options will need to be re-configured afterwards - +specifically, <tt class="docutils literal"><span class="pre">--topology</span> subnet</tt> and <tt class="docutils literal"><span class="pre">--route-gateway</span></tt> will get +lost and this will break client configs in many cases. Thus, for most +purposes, <tt class="docutils literal"><span class="pre">--push-remove</span></tt> is better suited to selectively remove +push options for individual clients.</p> +</td></tr> <tr><td class="option-group"> <kbd><span class="option">--server <var>args</var></span></kbd></td> <td><p class="first">A helper directive designed to simplify the configuration of OpenVPN's @@ -2200,6 +2226,19 @@ tls-server </pre> </td></tr> <tr><td class="option-group" colspan="2"> +<kbd><span class="option">--server-ipv6 <var>args</var></span></kbd></td> +</tr> +<tr><td> </td><td><p class="first">Convenience-function to enable a number of IPv6 related options at once, +namely <tt class="docutils literal"><span class="pre">--ifconfig-ipv6</span></tt>, <tt class="docutils literal"><span class="pre">--ifconfig-ipv6-pool</span></tt> and +<tt class="docutils literal"><span class="pre">--push</span> <span class="pre">tun-ipv6</span></tt>.</p> +<p>Valid syntax:</p> +<pre class="literal-block"> +server-ipv6 ipv6addr/bits +</pre> +<p class="last">Pushing of the <tt class="docutils literal"><span class="pre">--tun-ipv6</span></tt> directive is done for older clients which +require an explicit <tt class="docutils literal"><span class="pre">--tun-ipv6</span></tt> in their configuration.</p> +</td></tr> +<tr><td class="option-group" colspan="2"> <kbd><span class="option">--stale-routes-check <var>args</var></span></kbd></td> </tr> <tr><td> </td><td><p class="first">Remove routes which haven't had activity for <tt class="docutils literal">n</tt> seconds (i.e. the ageing @@ -2215,9 +2254,15 @@ stale-routes-check n [t] <tr><td class="option-group" colspan="2"> <kbd><span class="option">--username-as-common-name</span></kbd></td> </tr> -<tr><td> </td><td>For <tt class="docutils literal"><span class="pre">--auth-user-pass-verify</span></tt> authentication, use the authenticated -username as the common name, rather than the common name from the client -cert.</td></tr> +<tr><td> </td><td><p class="first">Use the authenticated username as the common-name, rather than the +common-name from the client certificate. Requires that some form of +<tt class="docutils literal"><span class="pre">--auth-user-pass</span></tt> verification is in effect. As the replacement happens +after <tt class="docutils literal"><span class="pre">--auth-user-pass</span></tt> verification, the verification script or +plugin will still receive the common-name from the certificate.</p> +<p class="last">The common_name environment variable passed to scripts and plugins invoked +after authentication (e.g, client-connect script) and file names parsed in +client-config directory will match the username.</p> +</td></tr> <tr><td class="option-group" colspan="2"> <kbd><span class="option">--verify-client-cert <var>mode</var></span></kbd></td> </tr> @@ -3830,6 +3875,9 @@ dhcp-options type [parm] <dl class="last docutils"> <dt><code>DOMAIN</code> <tt class="docutils literal">name</tt></dt> <dd>Set Connection-specific DNS Suffix to <code>name</code>.</dd> +<dt><code>ADAPTER_DOMAIN_SUFFIX</code> <tt class="docutils literal">name</tt></dt> +<dd>Alias to <code>DOMAIN</code>. This is a compatibility option, it +should not be used in new deployments.</dd> <dt><code>DOMAIN-SEARCH</code> <tt class="docutils literal">name</tt></dt> <dd>Add <code>name</code> to the domain search list. Repeat this option to add more entries. Up to @@ -4449,9 +4497,8 @@ succeeded, then ALL of the client-disconnect functions for scripts and plugins will be called on client instance object deletion, even in cases where some of the related client-connect functions returned an error status.</p> -<p class="last">The <tt class="docutils literal"><span class="pre">--client-disconnect</span></tt> command is passed the same pathname as the -corresponding <tt class="docutils literal"><span class="pre">--client-connect</span></tt> command as its last argument (after -any arguments specified in <tt class="docutils literal">cmd</tt>).</p> +<p class="last">The <tt class="docutils literal"><span class="pre">--client-disconnect</span></tt> command is not passed any extra arguments +(only those arguments specified in cmd, if any).</p> </td></tr> <tr><td class="option-group"> <kbd><span class="option">--down <var>cmd</var></span></kbd></td> @@ -4927,10 +4974,10 @@ command line or configuration file.</p> <dt><code>route_ipv6_{parm}_{n}</code></dt> <dd><p class="first">A set of variables which define each IPv6 route to be added, and are set prior to <strong>--up</strong> script execution.</p> -<p><tt class="docutils literal">parm</tt> will be one of <code>network</code> or <code>gateway</code> -(<code>netmask</code> is contained as <code>/nnn</code> in the -<tt class="docutils literal">route_ipv6_network_{n}</tt>, unlike IPv4 where it is passed in a -separate environment variable).</p> +<p><tt class="docutils literal">parm</tt> will be one of <code>network</code>, <code>gateway</code> or +<code>metric</code>. <tt class="docutils literal">route_ipv6_network_{n}</tt> contains <code>netmask</code> +as <code>/nnn</code>, unlike IPv4 where it is passed in a separate environment +variable.</p> <p><tt class="docutils literal">n</tt> is the OpenVPN route number, starting from 1.</p> <p class="last">If the network or gateway are resolvable DNS names, their IP address translations will be recorded rather than their names as denoted on the @@ -5508,8 +5555,11 @@ towards the gateway (if the protocol in question is enabled).</p> --show-gateway --show-gateway IPv6-target </pre> -<p class="last">If an IPv6 target address is passed as argument, the IPv6 route for this -host is reported.</p> +<p class="last">For IPv6 this queries the route towards ::/128, or the specified IPv6 +target address if passed as argument. +For IPv4 on Linux, Windows, MacOS and BSD it looks for a 0.0.0.0/0 route. +If there are more specific routes, the result will not always be matching +the route of the IPv4 packets to the VPN gateway.</p> </td></tr> </tbody> </table> |