diff options
Diffstat (limited to 'doc/man-sections')
| -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 |
6 files changed, 88 insertions, 39 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 |