diff --git a/doc/openvpn.8.rst b/doc/openvpn.8.rst index 713cd309..4a7ca3aa 100644 --- a/doc/openvpn.8.rst +++ b/doc/openvpn.8.rst @@ -69,5603 +69,23 @@ a configuration file. Though all command line options are preceded by a double-leading-dash ("--"), this prefix can be removed when an option is placed in a configuration file. ---help - - Show options. - ---config file - Load additional config options from ``file`` where each line corresponds - to one command line option, but with the leading '--' removed. - - If ``--config file`` is the only option to the openvpn command, the - ``--config`` can be removed, and the command can be given as ``openvpn - file`` - - Note that configuration files can be nested to a reasonable depth. - - Double quotation or single quotation characters ("", '') can be used to - enclose single parameters containing whitespace, and "#" or ";" - characters in the first column can be used to denote comments. - - Note that OpenVPN 2.0 and higher performs backslash-based shell escaping - for characters not in single quotations, so the following mappings - should be observed: - :: - - \\ Maps to a single backslash character (\). - \" Pass a literal doublequote character ("), don't - interpret it as enclosing a parameter. - \[SPACE] Pass a literal space or tab character, don't - interpret it as a parameter delimiter. - - For example on Windows, use double backslashes to represent pathnames: - :: - - secret "c:\\OpenVPN\\secret.key" - - - For examples of configuration files, see - https://openvpn.net/community-resources/how-to/ - - Here is an example configuration file: - :: - - # - # Sample OpenVPN configuration file for - # using a pre-shared static key. - # - # '#' or ';' may be used to delimit comments. - - # Use a dynamic tun device. - dev tun - - # Our remote peer - remote mypeer.mydomain - - # 10.1.0.1 is our local VPN endpoint - # 10.1.0.2 is our remote VPN endpoint - ifconfig 10.1.0.1 10.1.0.2 - - # Our pre-shared static key - secret static.key - - -Tunnel Options: ---------------- - ---mode m - Set OpenVPN major mode. By default, OpenVPN runs in point-to-point mode - (:code:`p2p`). OpenVPN 2.0 introduces a new mode (:code:`server`) which - implements a multi-client server capability. - ---local host - Local host name or IP address for bind. If specified, OpenVPN will bind - to this address only. If unspecified, OpenVPN will bind to all - interfaces. - ---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 ```` documentation below. - - The OpenVPN client will try to connect to a server at ``host:port`` in - the order specified by the list of ``--remote`` options. - - Examples: - :: - - remote server.example.net - remote server.example.net 1194 - remote server.example.net tcp - - ``proto`` indicates the protocol to use when connecting with the remote, - and may be :code:`tcp` or :code:`udp`. - - For forcing IPv4 or IPv6 connection suffix tcp or udp with 4/6 like - udp4/udp6/tcp4/tcp6. - - The client will move on to the next host in the list, in the event of - connection failure. Note that at any given time, the OpenVPN client will - at most be connected to one server. - - Note that since UDP is connectionless, connection failure is defined by - the ``--ping`` and ``--ping-restart`` options. - - 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. - - If ``--remote`` is unspecified, OpenVPN will listen for packets from any - IP address, but will not act on those packets unless they pass all - authentication tests. This requirement for authentication is binding on - all potential peers, even those from known and supposedly trusted IP - addresses (it is very easy to forge a source IP address on a UDP - packet). - - When used in TCP mode, ``--remote`` will act as a filter, rejecting - connections from any host which does not match ``host``. - - If ``host`` is a DNS name which resolves to multiple IP addresses, - OpenVPN will try them in the order that the system getaddrinfo() - presents them, so priorization and DNS randomization is done by the - system library. Unless an IP version is forced by the protocol - specification (4/6 suffix), OpenVPN will try both IPv4 and IPv6 - addresses, in the order getaddrinfo() returns them. - ---remote-random-hostname - Prepend a random string (6 bytes, 12 hex characters) to hostname to - prevent DNS caching. For example, "foo.bar.gov" would be modified to - ".foo.bar.gov". - ---proto-force p - When iterating through connection profiles, only consider profiles using - protocol ``p`` (:code:`tcp` \| :code:`udp`). - ---remote-random - When multiple ``--remote`` address/ports are specified, or if connection - profiles are being used, initially randomize the order of the list as a - kind of basic load-balancing measure. - ---proto p - Use protocol ``p`` for communicating with remote host. ``p`` can be - :code:`udp`, :code:`tcp-client`, or :code:`tcp-server`. - - The default protocol is :code:`udp` when ``--proto`` is not specified. - - For UDP operation, ``--proto udp`` should be specified on both peers. - - For TCP operation, one peer must use ``--proto tcp-server`` and the - other must use ``--proto tcp-client``. A peer started with - :code:`tcp-server` will wait indefinitely for an incoming connection. A peer - started with :code:`tcp-client` will attempt to connect, and if that fails, - will sleep for 5 seconds (adjustable via the ``--connect-retry`` option) - and try again infinite or up to N retries (adjustable via the - ``--connect-retry-max`` option). Both TCP client and server will - simulate a SIGUSR1 restart signal if either side resets the connection. - - OpenVPN is designed to operate optimally over UDP, but TCP capability is - provided for situations where UDP cannot be used. In comparison with - UDP, TCP will usually be somewhat less efficient and less robust when - used over unreliable or congested networks. - - This article outlines some of problems with tunneling IP over TCP: - http://sites.inka.de/sites/bigred/devel/tcp-tcp.html - - There are certain cases, however, where using TCP may be advantageous - from a security and robustness perspective, such as tunneling non-IP or - application-level UDP protocols, or tunneling protocols which don't - possess a built-in reliability layer. - ---connect-retry args - Wait ``n`` seconds between connection attempts (default :code:`5`). - Repeated reconnection attempts are slowed down after 5 retries per - remote by doubling the wait time after each unsuccessful attempt. An - optional argument ``max`` specifies the maximum value of wait time in - seconds at which it gets capped (default :code:`300`). - ---connect-retry-max n - ``n`` specifies the number of times each ``--remote`` or - ```` entry is tried. Specifying ``n`` as one would try each - entry exactly once. A successful connection resets the counter. - (default *unlimited*). - ---show-proxy-settings - Show sensed HTTP or SOCKS proxy settings. Currently, only Windows - clients support this option. - ---http-proxy args - Connect to remote host through an HTTP proxy. This requires at least an - address ``server`` and ``port`` argument. If HTTP Proxy-Authenticate - is required, a file name to an ``authfile`` file containing a username - and password on 2 lines can be given, or :code:`stdin` to prompt from - console. Its content can also be specified in the config file with the - ``--http-proxy-user-pass`` option. (See section on inline files) - - The last optional argument is an ``auth-method`` which should be one - of :code:`none`, :code:`basic`, or :code:`ntlm`. - - HTTP Digest authentication is supported as well, but only via the - :code:`auto` or :code:`auto-nct` flags (below). This must replace - the ``authfile`` argument. - - The :code:`auto` flag causes OpenVPN to automatically determine the - ``auth-method`` and query stdin or the management interface for - username/password credentials, if required. This flag exists on OpenVPN - 2.1 or higher. - - The ``auto-nct`` flag (no clear-text auth) instructs OpenVPN to - automatically determine the authentication method, but to reject weak - authentication protocols such as HTTP Basic Authentication. - - Examples: - :: - - http-proxy proxy.example.net 3128 - http-proxy proxy.example.net 3128 authfile.txt - http-proxy proxy.example.net 3128 stdin - http-proxy proxy.example.net 3128 auto basic - http-proxy proxy.example.net 3128 auto-nct ntlm - ---http-proxy-option args - Set extended HTTP proxy options. Requires an option ``type`` as argument - and an optional ``parameter`` to the type. Repeat to set multiple - options. - - :code:`VERSION` ``version`` - Set HTTP version number to ``version`` (default :code:`1.0`). - - :code:`AGENT` ``user-agent`` - Set HTTP "User-Agent" string to ``user-agent``. - - :code:`CUSTOM-HEADER` ``name`` ``content`` - Adds the custom Header with ``name`` as name and ``content`` as - the content of the custom HTTP header. - - Examples: - :: - - http-proxy-option VERSION 1.1 - http-proxy-option AGENT OpenVPN/2.4 - http-proxy-option X-Proxy-Flag some-flags - ---socks-proxy args - Connect to remote host through a Socks5 proxy. A required ``server`` - argument is needed. Optionally a ``port`` (default :code:`1080`) and - ``authfile`` can be given. The ``authfile`` is a file containing a - username and password on 2 lines, or :code:`stdin` can be used to - prompt from console. - ---resolv-retry n - If hostname resolve fails for ``--remote``, retry resolve for ``n`` - seconds before failing. - - Set ``n`` to "infinite" to retry indefinitely. - - By default, ``--resolv-retry infinite`` is enabled. You can disable by - setting n=0. - ---float - Allow remote peer to change its IP address and/or port number, such as - due to DHCP (this is the default if ``--remote`` is not used). - ``--float`` when specified with ``--remote`` allows an OpenVPN session - to initially connect to a peer at a known address, however if packets - arrive from a new address and pass all authentication tests, the new - address will take control of the session. This is useful when you are - connecting to a peer which holds a dynamic address such as a dial-in - user or DHCP client. - - Essentially, ``--float`` tells OpenVPN to accept authenticated packets - from any address, not only the address which was specified in the - ``--remote`` option. - ---ipchange cmd - Run command ``cmd`` when our remote ip-address is initially - authenticated or changes. - - ``cmd`` consists of a path to script (or executable program), optionally - followed by arguments. The path and arguments may be single- or - double-quoted and/or escaped using a backslash, and should be separated - by one or more spaces. - - When ``cmd`` is executed two arguments are appended after any arguments - specified in ``cmd`` , as follows: - :: - - cmd ip address port number - - Don't use ``--ipchange`` in ``--mode server`` mode. Use a - ``--client-connect`` script instead. - - See the `Environmental Variables`_ section below for additional - parameters passed as environmental variables. - - If you are running in a dynamic IP address environment where the IP - addresses of either peer could change without notice, you can use this - script, for example, to edit the :code:`/etc/hosts` file with the current - address of the peer. The script will be run every time the remote peer - changes its IP address. - - Similarly if *our* IP address changes due to DHCP, we should configure - our IP address change script (see man page for ``dhcpcd``\(8)) to - deliver a ``SIGHUP`` or ``SIGUSR1`` signal to OpenVPN. OpenVPN will - then reestablish a connection with its most recently authenticated - peer on its new IP address. - ---port port - TCP/UDP port number or port name for both local and remote (sets both - ``--lport`` and ``--rport`` options to given port). The current default - of 1194 represents the official IANA port number assignment for OpenVPN - and has been used since version 2.0-beta17. Previous versions used port - 5000 as the default. - ---lport port - Set local TCP/UDP port number or name. Cannot be used together with - ``--nobind`` option. - ---rport port - Set TCP/UDP port number or name used by the ``--remote`` option. The - port can also be set directly using the ``--remote`` option. - ---bind keywords - Bind to local address and port. This is the default unless any of - ``--proto tcp-client`` , ``--http-proxy`` or ``--socks-proxy`` are used. - - If the optional :code:`ipv6only` keyword is present OpenVPN will bind only - to IPv6 (as opposed to IPv6 and IPv4) when a IPv6 socket is opened. - ---nobind - Do not bind to local address and port. The IP stack will allocate a - dynamic port for returning packets. Since the value of the dynamic port - could not be known in advance by a peer, this option is only suitable - for peers which will be initiating connections by using the --remote - option. - ---dev device - TUN/TAP virtual network device which can be :code:`tunX`, :code:`tapX`, - :code:`null` or an arbitrary name string (:code:`X` can be omitted for - a dynamic device.) - - See examples section below for an example on setting up a TUN device. - - You must use either tun devices on both ends of the connection or tap - devices on both ends. You cannot mix them, as they represent different - underlying network layers: - - :code:`tun` - devices encapsulate IPv4 or IPv6 (OSI Layer 3) - - :code:`tap` - devices encapsulate Ethernet 802.3 (OSI Layer 2). - ---dev-type device-type - Which device type are we using? ``device-type`` should be :code:`tun` - (OSI Layer 3) or :code:`tap` (OSI Layer 2). Use this option only if - the TUN/TAP device used with ``--dev`` does not begin with :code:`tun` - or :code:`tap`. - ---topology mode - Configure virtual addressing topology when running in ``--dev tun`` - mode. This directive has no meaning in ``--dev tap`` mode, which always - uses a :code:`subnet` topology. - - If you set this directive on the server, the ``--server`` and - ``--server-bridge`` directives will automatically push your chosen - topology setting to clients as well. This directive can also be manually - pushed to clients. Like the ``--dev`` directive, this directive must - always be compatible between client and server. - - ``mode`` can be one of: - - :code:`net30` - Use a point-to-point topology, by allocating one /30 subnet - per client. This is designed to allow point-to-point semantics when some - or all of the connecting clients might be Windows systems. This is the - default on OpenVPN 2.0. - - :code:`p2p` - Use a point-to-point topology where the remote endpoint of - the client's tun interface always points to the local endpoint of the - server's tun interface. This mode allocates a single IP address per - connecting client. Only use when none of the connecting clients are - Windows systems. - - :code:`subnet` - Use a subnet rather than a point-to-point topology by - configuring the tun interface with a local IP address and subnet mask, - similar to the topology used in ``--dev tap`` and ethernet bridging - mode. This mode allocates a single IP address per connecting client and - works on Windows as well. Only available when server and clients are - OpenVPN 2.1 or higher, or OpenVPN 2.0.x which has been manually patched - with the ``--topology`` directive code. When used on Windows, requires - version 8.2 or higher of the TAP-Win32 driver. When used on \*nix, - requires that the tun driver supports an - ```ifconfig `__``\ (8) command which sets a - subnet instead of a remote endpoint IP address. - - This option exists in OpenVPN 2.1 or higher. - - *Note:* Using ``--topology subnet`` changes the interpretation of the - arguments of ``--ifconfig`` to mean "address netmask", no longer "local - remote". - ---dev-node node - Explicitly set the device node rather than using :code:`/dev/net/tun`, - :code:`/dev/tun`, :code:`/dev/tap`, etc. If OpenVPN cannot figure out - whether ``node`` is a TUN or TAP device based on the name, you should - also specify ``--dev-type tun`` or ``--dev-type tap``. - - Under Mac OS X this option can be used to specify the default tun - implementation. Using ``--dev-node utun`` forces usage of the native - Darwin tun kernel support. Use ``--dev-node utunN`` to select a specific - utun instance. To force using the :code:`tun.kext` (:code:`/dev/tunX`) - use ``--dev-node tun``. When not specifying a ``--dev-node`` option - openvpn will first try to open utun, and fall back to tun.kext. - - On Windows systems, select the TAP-Win32 adapter which is named ``node`` - in the Network Connections Control Panel or the raw GUID of the adapter - enclosed by braces. The ``--show-adapters`` option under Windows can - also be used to enumerate all available TAP-Win32 adapters and will show - both the network connections control panel name and the GUID for each - TAP-Win32 adapter. - ---lladdr address - Specify the link layer address, more commonly known as the MAC address. - Only applied to TAP devices. - ---iproute cmd - Set alternate command to execute instead of default ``iproute2`` command. - May be used in order to execute OpenVPN in unprivileged environment. - ---ifconfig args - Set TUN/TAP adapter parameters. It requires the *IP address* of the local - VPN endpoint. For TUN devices in point-to-point mode, the next argument - must be the VPN IP address of the remote VPN endpoint. For TAP devices, - or TUN devices used with ``--topology subnet``, the second argument - is the subnet mask of the virtual network segment which is being created - or connected to. - - For TUN devices, which facilitate virtual point-to-point IP connections - (when used in ``--topology net30`` or ``p2p`` mode), the proper usage of - ``--ifconfig`` is to use two private IP addresses which are not a member - of any existing subnet which is in use. The IP addresses may be - consecutive and should have their order reversed on the remote peer. - After the VPN is established, by pinging ``rn``, you will be pinging - across the VPN. - - For TAP devices, which provide the ability to create virtual ethernet - segments, or TUN devices in ``--topology subnet`` mode (which create - virtual "multipoint networks"), ``--ifconfig`` is used to set an IP - address and subnet mask just as a physical ethernet adapter would be - similarly configured. If you are attempting to connect to a remote - ethernet bridge, the IP address and subnet should be set to values which - would be valid on the the bridged ethernet segment (note also that DHCP - can be used for the same purpose). - - This option, while primarily a proxy for the ``ifconfig``\(8) command, - is designed to simplify TUN/TAP tunnel configuration by providing a - standard interface to the different ifconfig implementations on - different platforms. - - ``--ifconfig`` parameters which are IP addresses can also be specified - as a DNS or /etc/hosts file resolvable name. - - For TAP devices, ``--ifconfig`` should not be used if the TAP interface - will be getting an IP address lease from a DHCP server. - - Examples: - :: - - # tun device in net30/p2p mode - ifconfig 10.8.0.2 10.8.0.1 - - # tun/tap device in subnet mode - ifconfig 10.8.0.2 255.255.255.0 - ---ifconfig-noexec - Don't actually execute ifconfig/netsh commands, instead pass - ``--ifconfig`` parameters to scripts using environmental variables. - ---ifconfig-nowarn - Don't output an options consistency check warning if the ``--ifconfig`` - option on this side of the connection doesn't match the remote side. - This is useful when you want to retain the overall benefits of the - options consistency check (also see ``--disable-occ`` option) while only - disabling the ifconfig component of the check. - - For example, if you have a configuration where the local host uses - ``--ifconfig`` but the remote host does not, use ``--ifconfig-nowarn`` - on the local host. - - This option will also silence warnings about potential address conflicts - which occasionally annoy more experienced users by triggering "false - positive" warnings. - ---route args - Add route to routing table after connection is established. Multiple - routes can be specified. Routes will be automatically torn down in - reverse order prior to TUN/TAP device close. - - Valid syntaxes: - :: - - route network/IP - route network/IP netmask - route network/IP netmask gateway - route network/IP netmask gateway metric - - This option is intended as a convenience proxy for the ``route``\(8) - shell command, while at the same time providing portable semantics - across OpenVPN's platform space. - - ``netmask`` - defaults to :code:`255.255.255.255` when not given - - ``gateway`` - default taken from ``--route-gateway`` or the second - parameter to ``--ifconfig`` when ``--dev tun`` is specified. - - ``metric`` - default taken from ``--route-metric`` if set, otherwise :code:`0`. - - The default can be specified by leaving an option blank or setting it to - :code:`default`. - - The ``network`` and ``gateway`` parameters can also be specified as a - DNS or :code:`/etc/hosts` file resolvable name, or as one of three special - keywords: - - :code:`vpn_gateway` - The remote VPN endpoint address (derived either from - ``--route-gateway`` or the second parameter to ``--ifconfig`` - when ``--dev tun`` is specified). - - :code:`net_gateway` - The pre-existing IP default gateway, read from the - routing table (not supported on all OSes). - - :code:`remote_host` - The ``--remote`` address if OpenVPN is being run in - client mode, and is undefined in server mode. - ---route-gateway arg - Specify a default *gateway* for use with ``--route``. - - If :code:`dhcp` is specified as the parameter, the gateway address will - be extracted from a DHCP negotiation with the OpenVPN server-side LAN. - - Valid syntaxes: - :: - - route-gateway gateway - route-gateway dhcp - - ---route-metric m - Specify a default metric ``m`` for use with ``--route``. - ---route-delay args - Valid syntaxes: - :: - - route-delay - route-delay n - route-delay n m - - Delay ``n`` seconds (default :code:`0`) after connection establishment, - before adding routes. If ``n`` is :code:`0`, routes will be added - immediately upon connection establishment. If ``--route-delay`` is - omitted, routes will be added immediately after TUN/TAP device open and - ``--up`` script execution, before any ``--user`` or ``--group`` privilege - downgrade (or ``--chroot`` execution.) - - This option is designed to be useful in scenarios where DHCP is used to - set tap adapter addresses. The delay will give the DHCP handshake time - to complete before routes are added. - - On Windows, ``--route-delay`` tries to be more intelligent by waiting - ``w`` seconds (default :code:`30` by default) for the TAP-Win32 adapter - to come up before adding routes. - ---route-up cmd - Run command ``cmd`` after routes are added, subject to ``--route-delay``. - - ``cmd`` consists of a path to script (or executable program), optionally - followed by arguments. The path and arguments may be single- or - double-quoted and/or escaped using a backslash, and should be separated - by one or more spaces. - - See the `Environmental Variables`_ section below for additional - parameters passed as environmental variables. - ---route-pre-down cmd - Run command ``cmd`` before routes are removed upon disconnection. - - ``cmd`` consists of a path to script (or executable program), optionally - followed by arguments. The path and arguments may be single- or - double-quoted and/or escaped using a backslash, and should be separated - by one or more spaces. - - See the `Environmental Variables`_ section below for additional - parameters passed as environmental variables. - ---route-noexec - Don't add or remove routes automatically. Instead pass routes to - ``--route-up`` script using environmental variables. - ---route-nopull - When used with ``--client`` or ``--pull``, accept options pushed by - server EXCEPT for routes, block-outside-dns and dhcp options like DNS - servers. - - When used on the client, this option effectively bars the server from - adding routes to the client's routing table, however note that this - option still allows the server to set the TCP/IP properties of the - client's TUN/TAP interface. - ---allow-pull-fqdn - Allow client to pull DNS names from server (rather than being limited to - IP address) for ``--ifconfig``, ``--route``, and ``--route-gateway``. - ---client-nat args - This pushable client option sets up a stateless one-to-one NAT rule on - packet addresses (not ports), and is useful in cases where routes or - ifconfig settings pushed to the client would create an IP numbering - conflict. - - Examples: - :: - - client-nat snat 192.168.0.0/255.255.0.0 - client-nat dnat 10.64.0.0/255.255.0.0 - - ``network/netmask`` (for example :code:`192.168.0.0/255.255.0.0`) defines - the local view of a resource from the client perspective, while - ``alias/netmask`` (for example :code:`10.64.0.0/255.255.0.0`) defines the - remote view from the server perspective. - - Use :code:`snat` (source NAT) for resources owned by the client and - :code:`dnat` (destination NAT) for remote resources. - - Set ``--verb 6`` for debugging info showing the transformation of - src/dest addresses in packets. - ---redirect-gateway flags - Automatically execute routing commands to cause all outgoing IP traffic - to be redirected over the VPN. This is a client-side option. - - This option performs three steps: - - (1) Create a static route for the ``--remote`` address which - forwards to the pre-existing default gateway. This is done so that - ``(3)`` will not create a routing loop. - - (2) Delete the default gateway route. - - (3) Set the new default gateway to be the VPN endpoint address - (derived either from ``--route-gateway`` or the second parameter to - ``--ifconfig`` when ``--dev tun`` is specified). - - When the tunnel is torn down, all of the above steps are reversed so - that the original default route is restored. - - Option flags: - - :code:`local` - Add the :code:`local` flag if both OpenVPN peers are directly - connected via a common subnet, such as with wireless. The - :code:`local` flag will cause step ``(1)`` above to be omitted. - - :code:`autolocal` - Try to automatically determine whether to enable :code:`local` - flag above. - - :code:`def1` - Use this flag to override the default gateway by using - :code:`0.0.0.0/1` and :code:`128.0.0.0/1` rather than - :code:`0.0.0.0/0`. This has the benefit of overriding but not - wiping out the original default gateway. - - :code:`bypass-dhcp` - Add a direct route to the DHCP server (if it is non-local) which - bypasses the tunnel (Available on Windows clients, may not be - available on non-Windows clients). - - :code:`bypass-dns` - Add a direct route to the DNS server(s) (if they are non-local) - which bypasses the tunnel (Available on Windows clients, may - not be available on non-Windows clients). - - :code:`block-local` - Block access to local LAN when the tunnel is active, except for - the LAN gateway itself. This is accomplished by routing the local - LAN (except for the LAN gateway address) into the tunnel. - - :code:`ipv6` - Redirect IPv6 routing into the tunnel. This works similar to - the :code:`def1` flag, that is, more specific IPv6 routes are added - (:code:`2000::/4`, :code:`3000::/4`), covering the whole IPv6 - unicast space. - - :code:`!ipv4` - Do not redirect IPv4 traffic - typically used in the flag pair - :code:`ipv6 !ipv4` to redirect IPv6-only. - ---link-mtu n - Sets an upper bound on the size of UDP packets which are sent between - OpenVPN peers. *It's best not to set this parameter unless you know what - you're doing.* - ---redirect-private flags - Like ``--redirect-gateway``, but omit actually changing the default gateway. - Useful when pushing private subnets. - ---block-ipv6 - On the client, instead of sending IPv6 packets over the VPN tunnel, all - IPv6 packets are answered with an ICMPv6 no route host message. On the - server, all IPv6 packets from clients are answered with an ICMPv6 no - route to host message. This options is intended for cases when IPv6 - should be blocked and other options are not available. ``--block-ipv6`` - will use the remote IPv6 as source address of the ICMPv6 packets if set, - otherwise will use :code:`fe80::7` as source address. - - For this option to make sense you actually have to route traffic to the - tun interface. The following example config block would send all IPv6 - traffic to OpenVPN and answer all requests with no route to host, - effectively blocking IPv6. - - **Client config** - :: - - --ifconfig-ipv6 fd15:53b6:dead::2/64 fd15:53b6:dead::1 - --redirect-gateway ipv6 - --block-ipv6 - - **Server config** - Push a "valid" ipv6 config to the client and block on the server - :: - - --push "ifconfig-ipv6 fd15:53b6:dead::2/64 fd15:53b6:dead::1" - --push "redirect-gateway ipv6" - --block-ipv6 - ---tun-mtu n - Take the TUN device MTU to be **n** and derive the link MTU from it - (default :code:`1500`). In most cases, you will probably want to leave - this parameter set to its default value. - - The MTU (Maximum Transmission Units) is the maximum datagram size in - bytes that can be sent unfragmented over a particular network path. - OpenVPN requires that packets on the control or data channels be sent - unfragmented. - - MTU problems often manifest themselves as connections which hang during - periods of active usage. - - It's best to use the ``--fragment`` and/or ``--mssfix`` options to deal - with MTU sizing issues. - ---tun-mtu-extra n - Assume that the TUN/TAP device might return as many as ``n`` bytes more - than the ``--tun-mtu`` size on read. This parameter defaults to 0, which - is sufficient for most TUN devices. TAP devices may introduce additional - overhead in excess of the MTU size, and a setting of 32 is the default - when TAP devices are used. This parameter only controls internal OpenVPN - buffer sizing, so there is no transmission overhead associated with - using a larger value. - ---mtu-disc type - Should we do Path MTU discovery on TCP/UDP channel? Only supported on - OSes such as Linux that supports the necessary system call to set. - - Valid types: - - :code:`no` Never send DF (Don't Fragment) frames - - :code:`maybe` Use per-route hints - - :code:`yes` Always DF (Don't Fragment) - ---mtu-test - To empirically measure MTU on connection startup, add the ``--mtu-test`` - option to your configuration. OpenVPN will send ping packets of various - sizes to the remote peer and measure the largest packets which were - successfully received. The ``--mtu-test`` process normally takes about 3 - minutes to complete. - ---fragment max - Enable internal datagram fragmentation so that no UDP datagrams are sent - which are larger than ``max`` bytes. - - The ``max`` parameter is interpreted in the same way as the - ``--link-mtu`` parameter, i.e. the UDP packet size after encapsulation - overhead has been added in, but not including the UDP header itself. - - The ``--fragment`` option only makes sense when you are using the UDP - protocol (``--proto udp``). - - ``--fragment`` adds 4 bytes of overhead per datagram. - - See the ``--mssfix`` option below for an important related option to - ``--fragment``. - - It should also be noted that this option is not meant to replace UDP - fragmentation at the IP stack level. It is only meant as a last resort - when path MTU discovery is broken. Using this option is less efficient - than fixing path MTU discovery for your IP link and using native IP - fragmentation instead. - - Having said that, there are circumstances where using OpenVPN's internal - fragmentation capability may be your only option, such as tunneling a - UDP multicast stream which requires fragmentation. - ---mssfix max - Announce to TCP sessions running over the tunnel that they should limit - their send packet sizes such that after OpenVPN has encapsulated them, - the resulting UDP packet size that OpenVPN sends to its peer will not - exceed ``max`` bytes. The default value is :code:`1450`. - - The ``max`` parameter is interpreted in the same way as the - ``--link-mtu`` parameter, i.e. the UDP packet size after encapsulation - overhead has been added in, but not including the UDP header itself. - Resulting packet would be at most 28 bytes larger for IPv4 and 48 bytes - for IPv6 (20/40 bytes for IP header and 8 bytes for UDP header). Default - value of 1450 allows IPv4 packets to be transmitted over a link with MTU - 1473 or higher without IP level fragmentation. - - The ``--mssfix`` option only makes sense when you are using the UDP - protocol for OpenVPN peer-to-peer communication, i.e. ``--proto udp``. - - ``--mssfix`` and ``--fragment`` can be ideally used together, where - ``--mssfix`` will try to keep TCP from needing packet fragmentation in - the first place, and if big packets come through anyhow (from protocols - other than TCP), ``--fragment`` will internally fragment them. - - Both ``--fragment`` and ``--mssfix`` are designed to work around cases - where Path MTU discovery is broken on the network path between OpenVPN - peers. - - The usual symptom of such a breakdown is an OpenVPN connection which - successfully starts, but then stalls during active usage. - - If ``--fragment`` and ``--mssfix`` are used together, ``--mssfix`` will - take its default ``max`` parameter from the ``--fragment max`` option. - - Therefore, one could lower the maximum UDP packet size to 1300 (a good - first try for solving MTU-related connection problems) with the - following options: - :: - - --tun-mtu 1500 --fragment 1300 --mssfix - ---sndbuf size - Set the TCP/UDP socket send buffer size. Defaults to operation system - default. - ---rcvbuf size - Set the TCP/UDP socket receive buffer size. Defaults to operation system - default. - ---mark value - Mark encrypted packets being sent with value. The mark value can be - matched in policy routing and packetfilter rules. This option is only - supported in Linux and does nothing on other operating systems. - ---socket-flags flags - Apply the given flags to the OpenVPN transport socket. Currently, only - :code:`TCP_NODELAY` is supported. - - The :code:`TCP_NODELAY` socket flag is useful in TCP mode, and causes the - kernel to send tunnel packets immediately over the TCP connection without - trying to group several smaller packets into a larger packet. This can - result in a considerably improvement in latency. - - This option is pushable from server to client, and should be used on - both client and server for maximum effect. - ---txqueuelen n - *(Linux only)* Set the TX queue length on the TUN/TAP interface. - Currently defaults to 100. - ---shaper n - Limit bandwidth of outgoing tunnel data to ``n`` bytes per second on the - TCP/UDP port. Note that this will only work if mode is set to - :code:`p2p`. If you want to limit the bandwidth in both directions, use - this option on both peers. - - OpenVPN uses the following algorithm to implement traffic shaping: Given - a shaper rate of ``n`` bytes per second, after a datagram write of ``b`` - bytes is queued on the TCP/UDP port, wait a minimum of ``(b / n)`` - seconds before queuing the next write. - - It should be noted that OpenVPN supports multiple tunnels between the - same two peers, allowing you to construct full-speed and reduced - bandwidth tunnels at the same time, routing low-priority data such as - off-site backups over the reduced bandwidth tunnel, and other data over - the full-speed tunnel. - - Also note that for low bandwidth tunnels (under 1000 bytes per second), - you should probably use lower MTU values as well (see above), otherwise - the packet latency will grow so large as to trigger timeouts in the TLS - layer and TCP connections running over the tunnel. - - OpenVPN allows ``n`` to be between 100 bytes/sec and 100 Mbytes/sec. - ---inactive args - Causes OpenVPN to exit after ``n`` seconds of inactivity on the TUN/TAP - device. The time length of inactivity is measured since the last - incoming or outgoing tunnel packet. The default value is 0 seconds, - which disables this feature. - - Valid syntaxes: - :: - - inactive n - inactive n bytes - - If the optional ``bytes`` parameter is included, exit if less than - ``bytes`` of combined in/out traffic are produced on the tun/tap device - in ``n`` seconds. - - In any case, OpenVPN's internal ping packets (which are just keepalives) - and TLS control packets are not considered "activity", nor are they - counted as traffic, as they are used internally by OpenVPN and are not - an indication of actual user activity. - ---ping n - Ping remote over the TCP/UDP control channel if no packets have been - sent for at least ``n`` seconds (specify ``--ping`` on both peers to - cause ping packets to be sent in both directions since OpenVPN ping - packets are not echoed like IP ping packets). When used in one of - OpenVPN's secure modes (where ``--secret``, ``--tls-server`` or - ``--tls-client`` is specified), the ping packet will be - cryptographically secure. - - This option has two intended uses: - - (1) Compatibility with stateful firewalls. The periodic ping will ensure - that a stateful firewall rule which allows OpenVPN UDP packets to - pass will not time out. - - (2) To provide a basis for the remote to test the existence of its peer - using the ``--ping-exit`` option. - ---ping-exit n - Causes OpenVPN to exit after ``n`` seconds pass without reception of a - ping or other packet from remote. This option can be combined with - ``--inactive``, ``--ping`` and ``--ping-exit`` to create a two-tiered - inactivity disconnect. - - For example, - :: - - openvpn [options...] --inactive 3600 --ping 10 --ping-exit 60 - - when used on both peers will cause OpenVPN to exit within 60 seconds if - its peer disconnects, but will exit after one hour if no actual tunnel - data is exchanged. - ---ping-restart n - Similar to ``--ping-exit``, but trigger a :code:`SIGUSR1` restart after - ``n`` seconds pass without reception of a ping or other packet from - remote. - - This option is useful in cases where the remote peer has a dynamic IP - address and a low-TTL DNS name is used to track the IP address using a - service such as http://dyndns.org/ + a dynamic DNS client such as - ``ddclient``. - - If the peer cannot be reached, a restart will be triggered, causing the - hostname used with ``--remote`` to be re-resolved (if ``--resolv-retry`` - is also specified). - - In server mode, ``--ping-restart``, ``--inactive`` or any other type of - internally generated signal will always be applied to individual client - instance objects, never to whole server itself. Note also in server mode - that any internally generated signal which would normally cause a - restart, will cause the deletion of the client instance object instead. - - In client mode, the ``--ping-restart`` parameter is set to 120 seconds - by default. This default will hold until the client pulls a replacement - value from the server, based on the ``--keepalive`` setting in the - server configuration. To disable the 120 second default, set - ``--ping-restart 0`` on the client. - - See the signals section below for more information on :code:`SIGUSR1`. - - Note that the behavior of ``SIGUSR1`` can be modified by the - ``--persist-tun``, ``--persist-key``, ``--persist-local-ip`` and - ``--persist-remote-ip`` options. - - Also note that ``--ping-exit`` and ``--ping-restart`` are mutually - exclusive and cannot be used together. - ---keepalive args - A helper directive designed to simplify the expression of ``--ping`` and - ``--ping-restart``. - - Valid syntax: - :: - - keepalive interval timeout - - This option can be used on both client and server side, but it is enough - to add this on the server side as it will push appropriate ``--ping`` - and ``--ping-restart`` options to the client. If used on both server and - client, the values pushed from server will override the client local - values. - - The ``timeout`` argument will be twice as long on the server side. This - ensures that a timeout is detected on client side before the server side - drops the connection. - - For example, ``--keepalive 10 60`` expands as follows: - :: - - if mode server: - ping 10 # Argument: interval - ping-restart 120 # Argument: timeout*2 - push "ping 10" # Argument: interval - push "ping-restart 60" # Argument: timeout - else - ping 10 # Argument: interval - ping-restart 60 # Argument: timeout - ---ping-timer-rem - Run the ``--ping-exit`` / ``--ping-restart`` timer only if we have a - remote address. Use this option if you are starting the daemon in listen - mode (i.e. without an explicit ``--remote`` peer), and you don't want to - start clocking timeouts until a remote peer connects. - ---persist-tun - Don't close and reopen TUN/TAP device or run up/down scripts across - :code:`SIGUSR1` or ``--ping-restart`` restarts. - - :code:`SIGUSR1` is a restart signal similar to :code:`SIGHUP`, but which - offers finer-grained control over reset options. - ---persist-key - Don't re-read key files across :code:`SIGUSR1` or ``--ping-restart``. - - This option can be combined with ``--user nobody`` to allow restarts - triggered by the :code:`SIGUSR1` signal. Normally if you drop root - privileges in OpenVPN, the daemon cannot be restarted since it will now - be unable to re-read protected key files. - - This option solves the problem by persisting keys across :code:`SIGUSR1` - resets, so they don't need to be re-read. - ---persist-local-ip - Preserve initially resolved local IP address and port number across - ``SIGUSR1`` or ``--ping-restart`` restarts. - ---persist-remote-ip - Preserve most recently authenticated remote IP address and port number - across :code:`SIGUSR1` or ``--ping-restart`` restarts. - ---mlock - Disable paging by calling the POSIX mlockall function. Requires that - OpenVPN be initially run as root (though OpenVPN can subsequently - downgrade its UID using the ``--user`` option). - - Using this option ensures that key material and tunnel data are never - written to disk due to virtual memory paging operations which occur - under most modern operating systems. It ensures that even if an attacker - was able to crack the box running OpenVPN, he would not be able to scan - the system swap file to recover previously used ephemeral keys, which - are used for a period of time governed by the ``--reneg`` options (see - below), then are discarded. - - The downside of using ``--mlock`` is that it will reduce the amount of - physical memory available to other applications. - ---up cmd - Run command ``cmd`` after successful TUN/TAP device open (pre ``--user`` - UID change). - - ``cmd`` consists of a path to script (or executable program), optionally - followed by arguments. The path and arguments may be single- or - double-quoted and/or escaped using a backslash, and should be separated - by one or more spaces. - - The up command is useful for specifying route commands which route IP - traffic destined for private subnets which exist at the other end of the - VPN connection into the tunnel. - - For ``--dev tun`` execute as: - :: - - cmd tun_dev tun_mtu link_mtu ifconfig_local_ip ifconfig_remote_ip [init | restart] - - For ``--dev tap`` execute as: - :: - - cmd tap_dev tap_mtu link_mtu ifconfig_local_ip ifconfig_netmask [init | restart] - - See the `Environmental Variables`_ section below for additional - parameters passed as environmental variables. - - Note that if ``cmd`` includes arguments, all OpenVPN-generated arguments - will be appended to them to build an argument list with which the - executable will be called. - - Typically, ``cmd`` will run a script to add routes to the tunnel. - - Normally the up script is called after the TUN/TAP device is opened. In - this context, the last command line parameter passed to the script will - be *init.* If the ``--up-restart`` option is also used, the up script - will be called for restarts as well. A restart is considered to be a - partial reinitialization of OpenVPN where the TUN/TAP instance is - preserved (the ``--persist-tun`` option will enable such preservation). - A restart can be generated by a SIGUSR1 signal, a ``--ping-restart`` - timeout, or a connection reset when the TCP protocol is enabled with the - ``--proto`` option. If a restart occurs, and ``--up-restart`` has been - specified, the up script will be called with *restart* as the last - parameter. - - *NOTE:* - On restart, OpenVPN will not pass the full set of environment - variables to the script. Namely, everything related to routing and - gateways will not be passed, as nothing needs to be done anyway - all - the routing setup is already in place. Additionally, the up-restart - script will run with the downgraded UID/GID settings (if configured). - - The following standalone example shows how the ``--up`` script can be - called in both an initialization and restart context. (*NOTE:* for - security reasons, don't run the following example unless UDP port 9999 - is blocked by your firewall. Also, the example will run indefinitely, so - you should abort with control-c). - - :: - - openvpn --dev tun --port 9999 --verb 4 --ping-restart 10 \ - --up 'echo up' --down 'echo down' --persist-tun \ - --up-restart - - Note that OpenVPN also provides the ``--ifconfig`` option to - automatically ifconfig the TUN device, eliminating the need to define an - ``--up`` script, unless you also want to configure routes in the - ``--up`` script. - - If ``--ifconfig`` is also specified, OpenVPN will pass the ifconfig - local and remote endpoints on the command line to the ``--up`` script so - that they can be used to configure routes such as: - - :: - - route add -net 10.0.0.0 netmask 255.255.255.0 gw $5 - ---up-delay - Delay TUN/TAP open and possible ``--up`` script execution until after - TCP/UDP connection establishment with peer. - - In ``--proto udp`` mode, this option normally requires the use of - ``--ping`` to allow connection initiation to be sensed in the absence of - tunnel data, since UDP is a "connectionless" protocol. - - On Windows, this option will delay the TAP-Win32 media state - transitioning to "connected" until connection establishment, i.e. the - receipt of the first authenticated packet from the peer. - ---down cmd - Run command ``cmd`` after TUN/TAP device close (post ``--user`` UID - change and/or ``--chroot`` ). ``cmd`` consists of a path to script (or - executable program), optionally followed by arguments. The path and - arguments may be single- or double-quoted and/or escaped using a - backslash, and should be separated by one or more spaces. - - Called with the same parameters and environmental variables as the - ``--up`` option above. - - Note that if you reduce privileges by using ``--user`` and/or - ``--group``, your ``--down`` script will also run at reduced privilege. - ---down-pre - Call ``--down`` cmd/script before, rather than after, TUN/TAP close. - ---up-restart - Enable the ``--up`` and ``--down`` scripts to be called for restarts as - well as initial program start. This option is described more fully above - in the ``--up`` option documentation. - ---setenv args - Set a custom environmental variable :code:`name=value` to pass to script. - - Valid syntaxes: - :: - - setenv name value - setenv FORWARD_COMPATIBLE 1 - setenv opt config_option - - By setting :code:`FORWARD_COMPATIBLE` to :code:`1`, the config file - syntax checking is relaxed so that unknown directives will trigger a - warning but not a fatal error, on the assumption that a given unknown - directive might be valid in future OpenVPN versions. - - This option should be used with caution, as there are good security - reasons for having OpenVPN fail if it detects problems in a config file. - Having said that, there are valid reasons for wanting new software - features to gracefully degrade when encountered by older software - versions. - - It is also possible to tag a single directive so as not to trigger a - fatal error if the directive isn't recognized. To do this, prepend the - following before the directive: ``setenv opt`` - - Versions prior to OpenVPN 2.3.3 will always ignore options set with the - ``setenv opt`` directive. - - See also ``--ignore-unknown-option`` - ---setenv-safe args - Set a custom environmental variable :code:`OPENVPN_name` to :code:`value` - to pass to scripts. - - Valid syntaxes: - :: - - setenv-safe name value - - This directive is designed to be pushed by the server to clients, and - the prepending of :code:`OPENVPN_` to the environmental variable is a - safety precaution to prevent a :code:`LD_PRELOAD` style attack from a - malicious or compromised server. - ---ignore-unknown-option args - Valid syntax: - :: - - ignore-unknown-options opt1 opt2 opt3 ... optN - - When one of options ``opt1 ... optN`` is encountered in the configuration - file the configuration file parsing does not fail if this OpenVPN version - does not support the option. Multiple ``--ignore-unknown-option`` options - can be given to support a larger number of options to ignore. - - This option should be used with caution, as there are good security - reasons for having OpenVPN fail if it detects problems in a config file. - Having said that, there are valid reasons for wanting new software - features to gracefully degrade when encountered by older software - versions. - - ``--ignore-unknown-option`` is available since OpenVPN 2.3.3. - ---script-security level - This directive offers policy-level control over OpenVPN's usage of - external programs and scripts. Lower ``level`` values are more - restrictive, higher values are more permissive. Settings for ``level``: - - :code:`0` - Strictly no calling of external programs. - - :code:`1` - (Default) Only call built-in executables such as ifconfig, - ip, route, or netsh. - - :code:`2` - Allow calling of built-in executables and user-defined - scripts. - - :code:`3` - Allow passwords to be passed to scripts via environmental - variables (potentially unsafe). - - OpenVPN releases before v2.3 also supported a ``method`` flag which - indicated how OpenVPN should call external commands and scripts. This - could be either :code:`execve` or :code:`system`. As of OpenVPN 2.3, this - flag is no longer accepted. In most \*nix environments the execve() - approach has been used without any issues. - - Some directives such as ``--up`` allow options to be passed to the - external script. In these cases make sure the script name does not - contain any spaces or the configuration parser will choke because it - can't determine where the script name ends and script options start. - - To run scripts in Windows in earlier OpenVPN versions you needed to - either add a full path to the script interpreter which can parse the - script or use the ``system`` flag to run these scripts. As of OpenVPN - 2.3 it is now a strict requirement to have full path to the script - interpreter when running non-executables files. This is not needed for - executable files, such as .exe, .com, .bat or .cmd files. For example, - if you have a Visual Basic script, you must use this syntax now: - - :: - - --up 'C:\\Windows\\System32\\wscript.exe C:\\Program\ Files\\OpenVPN\\config\\my-up-script.vbs' - - Please note the single quote marks and the escaping of the backslashes - (\\) and the space character. - - The reason the support for the :code:`system` flag was removed is due to - the security implications with shell expansions when executing scripts - via the :code:`system()` call. - ---disable-occ - Don't output a warning message if option inconsistencies are detected - between peers. An example of an option inconsistency would be where one - peer uses ``--dev tun`` while the other peer uses ``--dev tap``. - - Use of this option is discouraged, but is provided as a temporary fix in - situations where a recent version of OpenVPN must connect to an old - version. - ---user user - Change the user ID of the OpenVPN process to ``user`` after - initialization, dropping privileges in the process. This option is - useful to protect the system in the event that some hostile party was - able to gain control of an OpenVPN session. Though OpenVPN's security - features make this unlikely, it is provided as a second line of defense. - - By setting ``user`` to :code:`nobody` or somebody similarly unprivileged, - the hostile party would be limited in what damage they could cause. Of - course once you take away privileges, you cannot return them to an - OpenVPN session. This means, for example, that if you want to reset an - OpenVPN daemon with a :code:`SIGUSR1` signal (for example in response to - a DHCP reset), you should make use of one or more of the ``--persist`` - options to ensure that OpenVPN doesn't need to execute any privileged - operations in order to restart (such as re-reading key files or running - ``ifconfig`` on the TUN device). - ---group group - Similar to the ``--user`` option, this option changes the group ID of - the OpenVPN process to ``group`` after initialization. - ---cd dir - Change directory to ``dir`` prior to reading any files such as - configuration files, key files, scripts, etc. ``dir`` should be an - absolute path, with a leading "/", and without any references to the - current directory such as :code:`.` or :code:`..`. - - This option is useful when you are running OpenVPN in ``--daemon`` mode, - and you want to consolidate all of your OpenVPN control files in one - location. - ---chroot dir - Chroot to ``dir`` after initialization. ``--chroot`` essentially - redefines ``dir`` as being the top level directory tree (/). OpenVPN - will therefore be unable to access any files outside this tree. This can - be desirable from a security standpoint. - - Since the chroot operation is delayed until after initialization, most - OpenVPN options that reference files will operate in a pre-chroot - context. - - In many cases, the ``dir`` parameter can point to an empty directory, - however complications can result when scripts or restarts are executed - after the chroot operation. - - Note: The SSL library will probably need /dev/urandom to be available - inside the chroot directory ``dir``. This is because SSL libraries - occasionally need to collect fresh random. Newer linux kernels and some - BSDs implement a getrandom() or getentropy() syscall that removes the - need for /dev/urandom to be available. - ---setcon context - Apply SELinux ``context`` after initialization. This essentially - provides the ability to restrict OpenVPN's rights to only network I/O - operations, thanks to SELinux. This goes further than ``--user`` and - ``--chroot`` in that those two, while being great security features, - unfortunately do not protect against privilege escalation by - exploitation of a vulnerable system call. You can of course combine all - three, but please note that since setcon requires access to /proc you - will have to provide it inside the chroot directory (e.g. with mount - --bind). - - Since the setcon operation is delayed until after initialization, - OpenVPN can be restricted to just network-related system calls, whereas - by applying the context before startup (such as the OpenVPN one provided - in the SELinux Reference Policies) you will have to allow many things - required only during initialization. - - Like with chroot, complications can result when scripts or restarts are - executed after the setcon operation, which is why you should really - consider using the ``--persist-key`` and ``--persist-tun`` options. - ---daemon progname - Become a daemon after all initialization functions are completed. This - option will cause all message and error output to be sent to the syslog - file (such as :code:`/var/log/messages`), except for the output of - scripts and ifconfig commands, which will go to :code:`/dev/null` unless - otherwise redirected. The syslog redirection occurs immediately at the - point that ``--daemon`` is parsed on the command line even though the - daemonization point occurs later. If one of the ``--log`` options is - present, it will supersede syslog redirection. - - The optional ``progname`` parameter will cause OpenVPN to report its - program name to the system logger as ``progname``. This can be useful in - linking OpenVPN messages in the syslog file with specific tunnels. When - unspecified, ``progname`` defaults to "openvpn". - - When OpenVPN is run with the ``--daemon`` option, it will try to delay - daemonization until the majority of initialization functions which are - capable of generating fatal errors are complete. This means that - initialization scripts can test the return status of the openvpn command - for a fairly reliable indication of whether the command has correctly - initialized and entered the packet forwarding event loop. - - In OpenVPN, the vast majority of errors which occur after initialization - are non-fatal. - - Note: as soon as OpenVPN has daemonized, it can not ask for usernames, - passwords, or key pass phrases anymore. This has certain consequences, - namely that using a password-protected private key will fail unless the - ``--askpass`` option is used to tell OpenVPN to ask for the pass phrase - (this requirement is new in v2.3.7, and is a consequence of calling - daemon() before initializing the crypto layer). - - Further, using ``--daemon`` together with ``--auth-user-pass`` (entered - on console) and ``--auth-nocache`` will fail as soon as key - renegotiation (and reauthentication) occurs. - ---syslog progname - Direct log output to system logger, but do not become a daemon. See - ``--daemon`` directive above for description of ``progname`` parameter. - ---errors-to-stderr - Output errors to stderr instead of stdout unless log output is - redirected by one of the ``--log`` options. - ---passtos - Set the TOS field of the tunnel packet to what the payload's TOS is. - ---inetd args - Valid syntaxes: - :: - - inetd - inetd wait - inetd nowait - inetd wait progname - - Use this option when OpenVPN is being run from the inetd or ``xinetd``\(8) - server. - - The :code:`wait` and :code:`nowait` option must match what is specified - in the inetd/xinetd config file. The :code:`nowait` mode can only be used - with ``--proto tcp-server`` The default is :code:`wait`. The - :code:`nowait` mode can be used to instantiate the OpenVPN daemon as a - classic TCP server, where client connection requests are serviced on a - single port number. For additional information on this kind of - configuration, see the OpenVPN FAQ: - https://community.openvpn.net/openvpn/wiki/325-openvpn-as-a--forking-tcp-server-which-can-service-multiple-clients-over-a-single-tcp-port - - This option precludes the use of ``--daemon``, ``--local`` or - ``--remote``. Note that this option causes message and error output to - be handled in the same way as the ``--daemon`` option. The optional - ``progname`` parameter is also handled exactly as in ``--daemon``. - - Also note that in ``wait`` mode, each OpenVPN tunnel requires a separate - TCP/UDP port and a separate inetd or xinetd entry. See the OpenVPN 1.x - HOWTO for an example on using OpenVPN with xinetd: - https://openvpn.net/community-resources/1xhowto/ - ---log file - Output logging messages to ``file``, including output to stdout/stderr - which is generated by called scripts. If ``file`` already exists it will - be truncated. This option takes effect immediately when it is parsed in - the command line and will supersede syslog output if ``--daemon`` or - ``--inetd`` is also specified. This option is persistent over the entire - course of an OpenVPN instantiation and will not be reset by - :code:`SIGHUP`, :code:`SIGUSR1`, or ``--ping-restart``. - - Note that on Windows, when OpenVPN is started as a service, logging - occurs by default without the need to specify this option. - ---log-append file - Append logging messages to ``file``. If ``file`` does not exist, it will - be created. This option behaves exactly like ``--log`` except that it - appends to rather than truncating the log file. - ---suppress-timestamps - Avoid writing timestamps to log messages, even when they otherwise would - be prepended. In particular, this applies to log messages sent to - stdout. - ---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. - ---writepid file - Write OpenVPN's main process ID to ``file``. - ---nice n - Change process priority after initialization (``n`` greater than 0 is - lower priority, ``n`` less than zero is higher priority). - ---fast-io - (Experimental) Optimize TUN/TAP/UDP I/O writes by avoiding a call to - poll/epoll/select prior to the write operation. The purpose of such a - call would normally be to block until the device or socket is ready to - accept the write. Such blocking is unnecessary on some platforms which - don't support write blocking on UDP sockets or TUN/TAP devices. In such - cases, one can optimize the event loop by avoiding the poll/epoll/select - call, improving CPU efficiency by 5% to 10%. - - This option can only be used on non-Windows systems, when ``--proto - udp`` is specified, and when ``--shaper`` is NOT specified. - ---multihome - Configure a multi-homed UDP server. This option needs to be used when a - server has more than one IP address (e.g. multiple interfaces, or - secondary IP addresses), and is not using ``--local`` to force binding - to one specific address only. This option will add some extra lookups to - the packet path to ensure that the UDP reply packets are always sent - from the address that the client is talking to. This is not supported on - all platforms, and it adds more processing, so it's not enabled by - default. - - *Notes:* - - This option is only relevant for UDP servers. - - If you do an IPv6+IPv4 dual-stack bind on a Linux machine with - multiple IPv4 address, connections to IPv4 addresses will not - work right on kernels before 3.15, due to missing kernel - support for the IPv4-mapped case (some distributions have - ported this to earlier kernel versions, though). - ---echo parms - Echo ``parms`` to log output. - - Designed to be used to send messages to a controlling application which - is receiving the OpenVPN log output. - ---remap-usr1 signal - Control whether internally or externally generated :code:`SIGUSR1` signals - are remapped to :code:`SIGHUP` (restart without persisting state) or - SIGTERM (exit). - - ``signal`` can be set to :code:`SIGHUP` or :code:`SIGTERM`. By default, - no remapping occurs. - ---verb n - Set output verbosity to ``n`` (default :code:`1`). Each level shows all - info from the previous levels. Level :code:`3` is recommended if you want - a good summary of what's happening without being swamped by output. - - :code:`0` - No output except fatal errors. - - :code:`1` to :code:`4` - Normal usage range. - - :code:`5` - Outputs :code:`R` and :code:`W` characters to the console for - each packet read and write, uppercase is used for TCP/UDP - packets and lowercase is used for TUN/TAP packets. - - :code:`6` to :code:`11` - Debug info range (see :code:`errlevel.h` in the source code for - additional information on debug levels). - ---status args - Write operational status to ``file`` every ``n`` seconds. - - Valid syntaxes: - :: - - status file - status file n - - Status can also be written to the syslog by sending a :code:`SIGUSR2` - signal. - - With multi-client capability enabled on a server, the status file - includes a list of clients and a routing table. The output format can be - controlled by the ``--status-version`` option in that case. - - For clients or instances running in point-to-point mode, it will contain - the traffic statistics. - ---status-version n - Set the status file format version number to ``n``. - - This only affects the status file on servers with multi-client - capability enabled. Valid status version values: - - :code:`1` - Traditional format (default). The client list contains the - following fields comma-separated: Common Name, Real Address, Bytes - Received, Bytes Sent, Connected Since. - - :code:`2` - A more reliable format for external processing. Compared to - version :code:`1`, the client list contains some additional fields: - Virtual Address, Virtual IPv6 Address, Username, Client ID, Peer ID, - Data Channel Cipher. Future versions may extend the number of fields. - - :code:`3` - Identical to :code:`2`, but fields are tab-separated. - ---mute n - Log at most ``n`` consecutive messages in the same category. This is - useful to limit repetitive logging of similar message types. - ---compress algorithm - Enable a compression algorithm. - - The ``algorithm`` parameter may be :code:`lzo`, :code:`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 v2.4, use :code:`lzo` (which - is identical to the older option ``--comp-lzo yes``). - - If the ``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. - - ***Security Considerations*** - - Compression and encryption is a tricky combination. If an attacker knows - or is able to control (parts of) the plaintext of packets that contain - secrets, the attacker might be able to extract the secret if compression - is enabled. See e.g. the CRIME and BREACH attacks on TLS which also - leverage compression to break encryption. If you are not entirely sure - that the above does not apply to your traffic, you are advised to - *not* enable compression. - ---comp-lzo mode - *DEPRECATED* This option will be removed in a future OpenVPN release. - Use the newer ``--compress`` instead. - - Use LZO compression -- may add up to 1 byte per packet for incompressible - data. ``mode`` may be :code:`yes`, :code:`no`, or :code:`adaptive` - (default). - - In a server mode setup, it is possible to selectively turn compression - on or off for individual clients. - - First, make sure the client-side config file enables selective - compression by having at least one ``--comp-lzo`` directive, such as - ``--comp-lzo no``. This will turn off compression by default, but allow - a future directive push from the server to dynamically change the - :code:`on`/:code:`off`/:code:`adaptive` setting. - - Next in a ``--client-config-dir`` file, specify the compression setting - for the client, for example: - :: - - comp-lzo yes - push "comp-lzo yes" - - The first line sets the ``comp-lzo`` setting for the server side of the - link, the second sets the client side. - ---comp-noadapt - When used in conjunction with ``--comp-lzo``, this option will disable - OpenVPN's adaptive compression algorithm. Normally, adaptive compression - is enabled with ``--comp-lzo``. - - Adaptive compression tries to optimize the case where you have - compression enabled, but you are sending predominantly incompressible - (or pre-compressed) packets over the tunnel, such as an FTP or rsync - transfer of a large, compressed file. With adaptive compression, OpenVPN - will periodically sample the compression process to measure its - efficiency. If the data being sent over the tunnel is already - compressed, the compression efficiency will be very low, triggering - openvpn to disable compression for a period of time until the next - re-sample test. - ---management args - Enable a management server on a ``socket-name`` Unix socket on those - platforms supporting it, or on a designated TCP port. - - Valid syntaxes: - :: - - management socket-name unix # - management socket-name unix pw-file # (recommended) - management IP port # (INSECURE) - management IP port pw-file # - - ``pw-file``, if specified, is a password file where the password must - be on first line. Instead of a filename it can use the keyword stdin - which will prompt the user for a password to use when OpenVPN is - starting. - - For unix sockets, the default behaviour is to create a unix domain - socket that may be connected to by any process. Use the - ``--management-client-user`` and ``--management-client-group`` - directives to restrict access. - - The management interface provides a special mode where the TCP - management link can operate over the tunnel itself. To enable this mode, - set IP to ``tunnel``. Tunnel mode will cause the management interface to - listen for a TCP connection on the local VPN address of the TUN/TAP - interface. - - ***BEWARE*** of enabling the management interface over TCP. In these cases - you should *ALWAYS* make use of ``pw-file`` to password protect the - management interface. Any user who can connect to this TCP ``IP:port`` - will be able to manage and control (and interfere with) the OpenVPN - process. It is also strongly recommended to set IP to 127.0.0.1 - (localhost) to restrict accessibility of the management server to local - clients. - - While the management port is designed for programmatic control of - OpenVPN by other applications, it is possible to telnet to the port, - using a telnet client in "raw" mode. Once connected, type :code:`help` - for a list of commands. - - For detailed documentation on the management interface, see the - *management-notes.txt* file in the management folder of the OpenVPN - source distribution. - ---management-client - Management interface will connect as a TCP/unix domain client to - ``IP:port`` specified by ``--management`` rather than listen as a TCP - server or on a unix domain socket. - - If the client connection fails to connect or is disconnected, a SIGTERM - signal will be generated causing OpenVPN to quit. - ---management-query-passwords - Query management channel for private key password and - ``--auth-user-pass`` username/password. Only query the management - channel for inputs which ordinarily would have been queried from the - console. - ---management-query-proxy - Query management channel for proxy server information for a specific - ``--remote`` (client-only). - ---management-query-remote - Allow management interface to override ``--remote`` directives - (client-only). - ---management-external-key args - Allows usage for external private key file instead of ``--key`` option - (client-only). - - Valid syntaxes: - :: - - management-external-key - management-external-key nopadding - management-external-key pkcs1 - management-external-key nopadding pkcs1 - - The optional parameters :code:`nopadding` and :code:`pkcs1` signal - support for different padding algorithms. See - :code:`doc/mangement-notes.txt` for a complete description of this - feature. - ---management-external-cert certificate-hint - Allows usage for external certificate instead of ``--cert`` option - (client-only). ``certificate-hint`` is an arbitrary string which is - passed to a management interface client as an argument of - *NEED-CERTIFICATE* notification. Requires ``--management-external-key``. - ---management-forget-disconnect - Make OpenVPN forget passwords when management session disconnects. - - This directive does not affect the ``--http-proxy`` username/password. - It is always cached. - ---management-hold - Start OpenVPN in a hibernating state, until a client of the management - interface explicitly starts it with the :code:`hold release` command. - ---management-signal - Send SIGUSR1 signal to OpenVPN if management session disconnects. This - is useful when you wish to disconnect an OpenVPN session on user logoff. - For ``--management-client`` this option is not needed since a disconnect - will always generate a :code:`SIGTERM`. - ---management-log-cache n - Cache the most recent ``n`` lines of log file history for usage by the - management channel. - ---management-up-down - Report tunnel up/down events to management interface. - ---management-client-auth - Gives management interface client the responsibility to authenticate - clients after their client certificate has been verified. See - :code:`management-notes.txt` in OpenVPN distribution for detailed notes. - ---management-client-pf - Management interface clients must specify a packet filter file for each - connecting client. See :code:`management-notes.txt` in OpenVPN - distribution for detailed notes. - ---management-client-user u - When the management interface is listening on a unix domain socket, only - allow connections from user ``u``. - ---management-client-group g - When the management interface is listening on a unix domain socket, only - allow connections from group ``g``. - ---plugin args - Loads a given plug-in module. The ``module-name`` need to be the first - argument, indicating the plug-in to load. The second argument is an - optional init string which will be passed directly to the plug-in. - If the init consists of multiple arguments it must be enclosed in - double-quotes (\"). Multiple plugin modules may be loaded into one - OpenVPN process. - - The ``module-name`` argument can be just a filename or a filename - with a relative or absolute path. The format of the filename and path - defines if the plug-in will be loaded from a default plug-in directory - or outside this directory. - :: - - --plugin path Effective directory used - ===================== ============================= - myplug.so DEFAULT_DIR/myplug.so - subdir/myplug.so DEFAULT_DIR/subdir/myplug.so - ./subdir/myplug.so CWD/subdir/myplug.so - /usr/lib/my/plug.so /usr/lib/my/plug.so - - - DEFAULT\_DIR is replaced by the default plug-in directory, which is - configured at the build time of OpenVPN. CWD is the current directory - where OpenVPN was started or the directory OpenVPN have switched into - via the ``--cd`` option before the ``--plugin`` option. - - For more information and examples on how to build OpenVPN plug-in - modules, see the README file in the ``plugin`` folder of the OpenVPN - source distribution. - - If you are using an RPM install of OpenVPN, see - :code:`/usr/share/openvpn/plugin`. The documentation is in ``doc`` and - the actual plugin modules are in ``lib``. - - Multiple plugin modules can be cascaded, and modules can be used in - tandem with scripts. The modules will be called by OpenVPN in the order - that they are declared in the config file. If both a plugin and script - are configured for the same callback, the script will be called last. If - the return code of the module/script controls an authentication function - (such as tls-verify, auth-user-pass-verify, or client-connect), then - every module and script must return success (:code:`0`) in order for the - connection to be authenticated. - ---keying-material-exporter args - Save Exported Keying Material [RFC5705] of len bytes (must be between 16 - and 4095 bytes) using ``label`` in environment - (:code:`exported_keying_material`) for use by plugins in - :code:`OPENVPN_PLUGIN_TLS_FINAL` callback. - - Valid syntax: - :: - - keying-material-exporter label len - - Note that exporter ``labels`` have the potential to collide with existing - PRF labels. In order to prevent this, labels *MUST* begin with - :code:`EXPORTER`. - - -Server Mode ------------ - -Starting with OpenVPN 2.0, a multi-client TCP/UDP server mode is -supported, and can be enabled with the ``--mode server`` option. In -server mode, OpenVPN will listen on a single port for incoming client -connections. All client connections will be routed through a single tun -or tap interface. This mode is designed for scalability and should be -able to support hundreds or even thousands of clients on sufficiently -fast hardware. SSL/TLS authentication must be used in this mode. - ---server args - A helper directive designed to simplify the configuration of OpenVPN's - server mode. This directive will set up an OpenVPN server which will - allocate addresses to clients out of the given network/netmask. The - server itself will take the :code:`.1` address of the given network for - use as the server-side endpoint of the local TUN/TAP interface. If the - optional :code:`nopool` flag is given, no dynamic IP address pool will - prepared for VPN clients. - - Valid syntax: - :: - - server network netmask [nopool] - - For example, ``--server 10.8.0.0 255.255.255.0`` expands as follows: - :: - - mode server - tls-server - push "topology [topology]" - - if dev tun AND (topology == net30 OR topology == p2p): - ifconfig 10.8.0.1 10.8.0.2 - if !nopool: - ifconfig-pool 10.8.0.4 10.8.0.251 - route 10.8.0.0 255.255.255.0 - if client-to-client: - push "route 10.8.0.0 255.255.255.0" - else if topology == net30: - push "route 10.8.0.1" - - if dev tap OR (dev tun AND topology == subnet): - ifconfig 10.8.0.1 255.255.255.0 - if !nopool: - ifconfig-pool 10.8.0.2 10.8.0.253 255.255.255.0 - push "route-gateway 10.8.0.1" - if route-gateway unset: - route-gateway 10.8.0.2 - - Don't use ``--server`` if you are ethernet bridging. Use - ``--server-bridge`` instead. - ---server-bridge args - A helper directive similar to ``--server`` which is designed to simplify - the configuration of OpenVPN's server mode in ethernet bridging - configurations. - - Valid syntaxes: - :: - - server-bridge gateway netmask pool-start-IP pool-end-IP - server-bridge [nogw] - - If ``--server-bridge`` is used without any parameters, it will enable a - DHCP-proxy mode, where connecting OpenVPN clients will receive an IP - address for their TAP adapter from the DHCP server running on the - OpenVPN server-side LAN. Note that only clients that support the binding - of a DHCP client with the TAP adapter (such as Windows) can support this - mode. The optional :code:`nogw` flag (advanced) indicates that gateway - information should not be pushed to the client. - - To configure ethernet bridging, you must first use your OS's bridging - capability to bridge the TAP interface with the ethernet NIC interface. - For example, on Linux this is done with the :code:`brctl` tool, and with - Windows XP it is done in the Network Connections Panel by selecting the - ethernet and TAP adapters and right-clicking on "Bridge Connections". - - Next you you must manually set the IP/netmask on the bridge interface. - The ``gateway`` and ``netmask`` parameters to ``--server-bridge`` can be - set to either the IP/netmask of the bridge interface, or the IP/netmask - of the default gateway/router on the bridged subnet. - - Finally, set aside a IP range in the bridged subnet, denoted by - ``pool-start-IP`` and ``pool-end-IP``, for OpenVPN to allocate to - connecting clients. - - For example, ``server-bridge 10.8.0.4 255.255.255.0 10.8.0.128 - 10.8.0.254`` expands as follows: - :: - - mode server - tls-server - - ifconfig-pool 10.8.0.128 10.8.0.254 255.255.255.0 - push "route-gateway 10.8.0.4" - - In another example, ``--server-bridge`` (without parameters) expands as - follows: - :: - - mode server - tls-server - - push "route-gateway dhcp" - - Or ``--server-bridge nogw`` expands as follows: - :: - - mode server - tls-server - ---push option - Push a config file option back to the client for remote execution. Note - that ``option`` must be enclosed in double quotes (:code:`""`). The - client must specify ``--pull`` in its config file. The set of options - which can be pushed is limited by both feasibility and security. Some - options such as those which would execute scripts are banned, since they - would effectively allow a compromised server to execute arbitrary code - on the client. Other options such as TLS or MTU parameters cannot be - pushed because the client needs to know them before the connection to the - server can be initiated. - - This is a partial list of options which can currently be pushed: - ``--route``, ``--route-gateway``, ``--route-delay``, - ``--redirect-gateway``, ``--ip-win32``, ``--dhcp-option``, - ``--inactive``, ``--ping``, ``--ping-exit``, ``--ping-restart``, - ``--setenv``, ``--auth-token``, ``--persist-key``, ``--persist-tun``, - ``--echo``, ``--comp-lzo``, ``--socket-flags``, ``--sndbuf``, - ``--rcvbuf`` - ---push-reset - Don't inherit the global push list for a specific client instance. - Specify this option in a client-specific context such as with a - ``--client-config-dir`` configuration file. This option will ignore - ``--push`` options at the global config file level. - ---push-remove opt - Selectively remove all ``--push`` options matching "opt" from the option - list for a client. ``opt`` is matched as a substring against the whole - option string to-be-pushed to the client, so ``--push-remove route`` - would remove all ``--push route ...`` and ``--push route-ipv6 ...`` - statements, while ``--push-remove "route-ipv6 2001:"`` would only remove - IPv6 routes for :code:`2001:...` networks. - - ``--push-remove`` can only be used in a client-specific context, like in - a ``--client-config-dir`` file, or ``--client-connect`` script or plugin - -- similar to ``--push-reset``, just more selective. - - *NOTE*: to *change* an option, ``--push-remove`` can be used to first - remove the old value, and then add a new ``--push`` option with the new - value. - - *NOTE 2*: due to implementation details, 'ifconfig' and 'ifconfig-ipv6' - can only be removed with an exact match on the option ( - :code:`push-remove ifconfig`), no substring matching and no matching on - the IPv4/IPv6 address argument is possible. - ---push-peer-info - Push additional information about the client to server. The following - data is always pushed to the server: - - :code:`IV_VER=` - The client OpenVPN version - - :code:`IV_PLAT=[linux|solaris|openbsd|mac|netbsd|freebsd|win]` - The client OS platform - - :code:`IV_LZO_STUB=1` - If client was built with LZO stub capability - - :code:`IV_LZ4=1` - If the client supports LZ4 compressions. - - :code:`IV_PROTO=2` - If the client supports peer-id floating mechanism - - :code:`IV_NCP=2` - Negotiable ciphers, client supports ``--cipher`` pushed by - the server, a value of 2 or greater indicates client supports - *AES-GCM-128* and *AES-GCM-256*. - - :code:`IV_CIPHERS=` - The client pushes the list of configured ciphers with the - ``--ciphers`` option to the server. - - :code:`IV_GUI_VER= ` - The UI version of a UI if one is running, for example - :code:`de.blinkt.openvpn 0.5.47` for the Android app. - - When ``--push-peer-info`` is enabled the additional information consists - of the following data: - - :code:`IV_HWADDR=` - The MAC address of clients default gateway - - :code:`IV_SSL=` - The ssl version used by the client, e.g. - :code:`OpenSSL 1.0.2f 28 Jan 2016`. - - :code:`IV_PLAT_VER=x.y` - The version of the operating system, e.g. 6.1 for Windows 7. - - :code:`UV_=` - Client environment variables whose names start with - :code:`UV_` - ---disable - Disable a particular client (based on the common name) from connecting. - Don't use this option to disable a client due to key or password - compromise. Use a CRL (certificate revocation list) instead (see the - ``--crl-verify`` option). - - This option must be associated with a specific client instance, which - means that it must be specified either in a client instance config file - using ``--client-config-dir`` or dynamically generated using a - ``--client-connect`` script. - ---ifconfig-pool args - Set aside a pool of subnets to be dynamically allocated to connecting - clients, similar to a DHCP server. - - Valid syntax: - :: - - ifconfig-pool start-IP end-IP [netmask] - - For tun-style tunnels, each client - will be given a /30 subnet (for interoperability with Windows clients). - For tap-style tunnels, individual addresses will be allocated, and the - optional ``netmask`` parameter will also be pushed to clients. - ---ifconfig-pool-persist args - Persist/unpersist ifconfig-pool data to ``file``, at ``seconds`` - intervals (default :code:`600`), as well as on program startup and shutdown. - - Valid syntax: - :: - - ifconfig-pool-persist file [seconds] - - The goal of this option is to provide a long-term association between - clients (denoted by their common name) and the virtual IP address - assigned to them from the ifconfig-pool. Maintaining a long-term - association is good for clients because it allows them to effectively - use the ``--persist-tun`` option. - - ``file`` is a comma-delimited ASCII file, formatted as - :code:`,`. - - If ``seconds`` = :code:`0`, ``file`` will be treated as read-only. This - is useful if you would like to treat ``file`` as a configuration file. - - Note that the entries in this file are treated by OpenVPN as - *suggestions* only, based on past associations between a common name and - IP address. They do not guarantee that the given common name will always - receive the given IP address. If you want guaranteed assignment, use - ``--ifconfig-push`` - ---ifconfig-push args - Push virtual IP endpoints for client tunnel, overriding the - ``--ifconfig-pool`` dynamic allocation. - - Valid syntax: - :: - - ifconfig-push local remote-netmask [alias] - - The parameters ``local`` and ``remote-netmask`` are set according to the - ``--ifconfig`` directive which you want to execute on the client machine - to configure the remote end of the tunnel. Note that the parameters - ``local`` and ``remote-netmask`` are from the perspective of the client, - not the server. They may be DNS names rather than IP addresses, in which - case they will be resolved on the server at the time of client - connection. - - The optional ``alias`` parameter may be used in cases where NAT causes - the client view of its local endpoint to differ from the server view. In - this case ``local/remote-netmask`` will refer to the server view while - ``alias/remote-netmask`` will refer to the client view. - - This option must be associated with a specific client instance, which - means that it must be specified either in a client instance config file - using ``--client-config-dir`` or dynamically generated using a - ``--client-connect`` script. - - Remember also to include a ``--route`` directive in the main OpenVPN - config file which encloses ``local``, so that the kernel will know to - route it to the server's TUN/TAP interface. - - OpenVPN's internal client IP address selection algorithm works as - follows: - - 1. Use ``--client-connect script`` generated file for static IP - (first choice). - - 2. Use ``--client-config-dir`` file for static IP (next choice). - - 3. Use ``--ifconfig-pool`` allocation for dynamic IP (last - choice). - ---iroute args - Generate an internal route to a specific client. The ``netmask`` - parameter, if omitted, defaults to :code:`255.255.255.255`. - - Valid syntax: - :: - - iroute network [netmask] - - This directive can be used to route a fixed subnet from the server to a - particular client, regardless of where the client is connecting from. - Remember that you must also add the route to the system routing table as - well (such as by using the ``--route`` directive). The reason why two - routes are needed is that the ``--route`` directive routes the packet - from the kernel to OpenVPN. Once in OpenVPN, the ``--iroute`` directive - routes to the specific client. - - This option must be specified either in a client instance config file - using ``--client-config-dir`` or dynamically generated using a - ``--client-connect`` script. - - The ``--iroute`` directive also has an important interaction with - ``--push "route ..."``. ``--iroute`` essentially defines a subnet which - is owned by a particular client (we will call this client *A*). If you - would like other clients to be able to reach *A*'s subnet, you can use - ``--push "route ..."`` together with ``--client-to-client`` to effect - this. In order for all clients to see *A*'s subnet, OpenVPN must push - this route to all clients EXCEPT for *A*, since the subnet is already - owned by *A*. OpenVPN accomplishes this by not not pushing a route to - a client if it matches one of the client's iroutes. - ---client-to-client - Because the OpenVPN server mode handles multiple clients through a - single tun or tap interface, it is effectively a router. The - ``--client-to-client`` flag tells OpenVPN to internally route - client-to-client traffic rather than pushing all client-originating - traffic to the TUN/TAP interface. - - When this option is used, each client will "see" the other clients which - are currently connected. Otherwise, each client will only see the - server. Don't use this option if you want to firewall tunnel traffic - using custom, per-client rules. - ---duplicate-cn - Allow multiple clients with the same common name to concurrently - connect. In the absence of this option, OpenVPN will disconnect a client - instance upon connection of a new client having the same common name. - ---client-connect cmd - Run command ``cmd`` on client connection. - - ``cmd`` consists of a path to script (or executable program), optionally - followed by arguments. The path and arguments may be single- or - double-quoted and/or escaped using a backslash, and should be separated - by one or more spaces. - - The command is passed the common name and IP address of the - just-authenticated client as environmental variables (see environmental - variable section below). The command is also passed the pathname of a - freshly created temporary file as the last argument (after any arguments - specified in ``cmd`` ), to be used by the command to pass dynamically - generated config file directives back to OpenVPN. - - If the script wants to generate a dynamic config file to be applied on - the server when the client connects, it should write it to the file - named by the last argument. - - See the ``--client-config-dir`` option below for options which can be - legally used in a dynamically generated config file. - - Note that the return value of ``script`` is significant. If ``script`` - returns a non-zero error status, it will cause the client to be - disconnected. - ---client-disconnect cmd - Like ``--client-connect`` but called on client instance shutdown. Will - not be called unless the ``--client-connect`` script and plugins (if - defined) were previously called on this instance with successful (0) - status returns. - - The exception to this rule is if the ``--client-disconnect`` command or - plugins are cascaded, and at least one client-connect function - succeeded, then ALL of the client-disconnect functions for scripts and - plugins will be called on client instance object deletion, even in cases - where some of the related client-connect functions returned an error - status. - - The ``--client-disconnect`` command is passed the same pathname as the - corresponding ``--client-connect`` command as its last argument (after - any arguments specified in ``cmd``). - ---client-config-dir dir - Specify a directory ``dir`` for custom client config files. After a - connecting client has been authenticated, OpenVPN will look in this - directory for a file having the same name as the client's X509 common - name. If a matching file exists, it will be opened and parsed for - client-specific configuration options. If no matching file is found, - OpenVPN will instead try to open and parse a default file called - "DEFAULT", which may be provided but is not required. Note that the - configuration files must be readable by the OpenVPN process after it has - dropped it's root privileges. - - This file can specify a fixed IP address for a given client using - ``--ifconfig-push``, as well as fixed subnets owned by the client using - ``--iroute``. - - One of the useful properties of this option is that it allows client - configuration files to be conveniently created, edited, or removed while - the server is live, without needing to restart the server. - - The following options are legal in a client-specific context: ``--push``, - ``--push-reset``, ``--push-remove``, ``--iroute``, ``--ifconfig-push``, - ``--vlan-pvid`` and ``--config``. - ---ccd-exclusive - Require, as a condition of authentication, that a connecting client has - a ``--client-config-dir`` file. - ---tmp-dir dir - Specify a directory ``dir`` for temporary files. This directory will be - used by openvpn processes and script to communicate temporary data with - openvpn main process. Note that the directory must be writable by the - OpenVPN process after it has dropped it's root privileges. - - This directory will be used by in the following cases: - - * ``--client-connect`` scripts to dynamically generate client-specific - configuration files. - - * :code:`OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY` plugin hook to return - success/failure via ``auth_control_file`` when using deferred auth - method - - * :code:`OPENVPN_PLUGIN_ENABLE_PF` plugin hook to pass filtering rules - via ``pf_file`` - ---hash-size args - Set the size of the real address hash table to ``r`` and the virtual - address table to ``v``. - - Valid syntax: - :: - - hash-size r v - - By default, both tables are sized at 256 buckets. - ---bcast-buffers n - Allocate ``n`` buffers for broadcast datagrams (default :code:`256`). - ---tcp-queue-limit n - Maximum number of output packets queued before TCP (default :code:`64`). - - When OpenVPN is tunneling data from a TUN/TAP device to a remote client - over a TCP connection, it is possible that the TUN/TAP device might - produce data at a faster rate than the TCP connection can support. When - the number of output packets queued before sending to the TCP socket - reaches this limit for a given client connection, OpenVPN will start to - drop outgoing packets directed at this client. - ---tcp-nodelay - This macro sets the :code:`TCP_NODELAY` socket flag on the server as well - as pushes it to connecting clients. The :code:`TCP_NODELAY` flag disables - the Nagle algorithm on TCP sockets causing packets to be transmitted - immediately with low latency, rather than waiting a short period of time - in order to aggregate several packets into a larger containing packet. - In VPN applications over TCP, :code:`TCP_NODELAY` is generally a good - latency optimization. - - The macro expands as follows: - :: - - if mode server: - socket-flags TCP_NODELAY - push "socket-flags TCP_NODELAY" - ---max-clients n - Limit server to a maximum of ``n`` concurrent clients. - ---max-routes-per-client n - Allow a maximum of ``n`` internal routes per client (default - :code:`256`). This is designed to help contain DoS attacks where an - authenticated client floods the server with packets appearing to come - from many unique MAC addresses, forcing the server to deplete virtual - memory as its internal routing table expands. This directive can be used - in a ``--client-config-dir`` file or auto-generated by a - ``--client-connect`` script to override the global value for a particular - client. - - Note that this directive affects OpenVPN's internal routing table, not - the kernel routing table. - ---stale-routes-check args - Remove routes haven't had activity for ``n`` seconds (i.e. the ageing - time). This check is ran every ``t`` seconds (i.e. check interval). - - Valid syntax: - :: - - stale-routes-check n [t] - - If ``t`` is not present it defaults to ``n``. - - This option helps to keep the dynamic routing table small. See also - ``--max-routes-per-client`` - ---connect-freq args - Allow a maximum of ``n`` new connections per ``sec`` seconds from - clients. - - Valid syntax: - :: - - connect-freq n sec - - This is designed to contain DoS attacks which flood the server - with connection requests using certificates which will ultimately fail - to authenticate. - - This is an imperfect solution however, because in a real DoS scenario, - legitimate connections might also be refused. - - For the best protection against DoS attacks in server mode, use - ``--proto udp`` and either ``--tls-auth`` or ``--tls-crypt``. - ---learn-address cmd - Run command ``cmd`` to validate client virtual addresses or routes. - - ``cmd`` consists of a path to script (or executable program), optionally - followed by arguments. The path and arguments may be single- or - double-quoted and/or escaped using a backslash, and should be separated - by one or more spaces. - - Three arguments will be appended to any arguments in ``cmd`` as follows: - - :code:`$1` - [operation] - :code:`"add"`, :code:`"update"`, or :code:`"delete"` based on whether - or not the address is being added to, modified, or deleted from - OpenVPN's internal routing table. - - :code:`$2` - [address] - The address being learned or unlearned. This can be an IPv4 address - such as :code:`"198.162.10.14"`, an IPv4 subnet such as - :code:`"198.162.10.0/24"`, or an ethernet MAC address (when - ``--dev tap`` is being used) such as :code:`"00:FF:01:02:03:04"`. - - :code:`$3` - [common name] - The common name on the certificate associated with the client linked - to this address. Only present for :code:`"add"` or :code:`"update"` - operations, not :code:`"delete"`. - - On :code:`"add"` or :code:`"update"` methods, if the script returns - a failure code (non-zero), OpenVPN will reject the address and will not - modify its internal routing table. - - Normally, the ``cmd`` script will use the information provided above to - set appropriate firewall entries on the VPN TUN/TAP interface. Since - OpenVPN provides the association between virtual IP or MAC address and - the client's authenticated common name, it allows a user-defined script - to configure firewall access policies with regard to the client's - high-level common name, rather than the low level client virtual - addresses. - ---auth-user-pass-verify args - Require the client to provide a username/password (possibly in addition - to a client certificate) for authentication. - - Valid syntax: - :: - - auth-user-pass cmd method - - OpenVPN will run command ``cmd`` to validate the username/password - provided by the client. - - ``cmd`` consists of a path to script (or executable program), optionally - followed by arguments. The path and arguments may be single- or - double-quoted and/or escaped using a backslash, and should be separated - by one or more spaces. - - If ``method`` is set to :code:`via-env`, OpenVPN will call ``script`` - with the environmental variables :code:`username` and :code:`password` - set to the username/password strings provided by the client. *Beware* - that this method is insecure on some platforms which make the environment - of a process publicly visible to other unprivileged processes. - - If ``method`` is set to :code:`via-file`, OpenVPN will write the username - and password to the first two lines of a temporary file. The filename - will be passed as an argument to ``script``, and the file will be - automatically deleted by OpenVPN after the script returns. The location - of the temporary file is controlled by the ``--tmp-dir`` option, and - will default to the current directory if unspecified. For security, - consider setting ``--tmp-dir`` to a volatile storage medium such as - :code:`/dev/shm` (if available) to prevent the username/password file - from touching the hard drive. - - The script should examine the username and password, returning a success - exit code (:code:`0`) if the client's authentication request is to be - accepted, or a failure code (:code:`1`) to reject the client. - - This directive is designed to enable a plugin-style interface for - extending OpenVPN's authentication capabilities. - - To protect against a client passing a maliciously formed username or - password string, the username string must consist only of these - characters: alphanumeric, underbar (':code:`_`'), dash (':code:`-`'), - dot (':code:`.`'), or at (':code:`@`'). The password string can consist - of any printable characters except for CR or LF. Any illegal characters - in either the username or password string will be converted to - underbar (':code:`_`'). - - Care must be taken by any user-defined scripts to avoid creating a - security vulnerability in the way that these strings are handled. Never - use these strings in such a way that they might be escaped or evaluated - by a shell interpreter. - - For a sample script that performs PAM authentication, see - :code:`sample-scripts/auth-pam.pl` in the OpenVPN source distribution. - ---auth-gen-token args - Returns an authentication token to successfully authenticated clients. - - Valid syntax: - :: - - auth-gen-token [lifetime] [external-auth] - - After successful user/password authentication, the OpenVPN server will - with this option generate a temporary authentication token and push that - to client. On the following renegotiations, the OpenVPN client will pass - this token instead of the users password. On the server side the server - will do the token authentication internally and it will NOT do any - additional authentications against configured external user/password - authentication mechanisms. - - The tokens implemented by this mechanism include a initial timestamp and - a renew timestamp and are secured by HMAC. - - The ``lifetime`` argument defines how long the generated token is valid. - The lifetime is defined in seconds. If lifetime is not set or it is set - to :code:`0`, the token will never expire. - - The token will expire either after the configured ``lifetime`` of the - token is reached or after not being renewed for more than 2 \* - ``reneg-sec`` seconds. Clients will be sent renewed tokens on every TLS - renogiation to keep the client's token updated. This is done to - invalidate a token if a client is disconnected for a sufficently long - time, while at the same time permitting much longer token lifetimes for - active clients. - - This feature is useful for environments which 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. - - When the :code:`external-auth` keyword is present the normal - authentication method will always be called even if auth-token succeeds. - Normally other authentications method are skipped if auth-token - verification suceeds or fails. - - This option postpones this decision to the external authentication - methods and check the validity of the account and do other checks. - - In this mode the environment will have a session\_id variable that hold - the session id from auth-gen-token. Also a environment variable - session\_state is present. This variable tells whether the auth-token - has succeeded or not. It can have the following values: - - :code:`Initial` - No token from client. - - :code:`Authenticated` - Token is valid and not expired. - - :code:`Expired` - Token is valid but has expired. - - :code:`Invalid` - Token is invalid (failed HMAC or wrong length) - - :code:`AuthenticatedEmptyUser` / :code:`ExpiredEmptyUser` - The token is not valid with the username send from the client but - would be valid (or expired) if we assume an empty username was - used instead. These two cases are a workaround for behaviour in - OpenVPN 3. If this workaround is not needed these two cases should - be handled in the same way as :code:`Invalid`. - - **Warning:** Use this feature only if you want your authentication - method called on every verification. Since the external authentication - is called it needs to also indicate a success or failure of the - authentication. It is strongly recommended to return an authentication - failure in the case of the Invalid/Expired auth-token with the - external-auth option unless the client could authenticate in another - acceptable way (e.g. client certificate), otherwise returning success - will lead to authentication bypass (as does returning success on a wrong - password from a script). - ---auth-gen-token-secret file - Specifies a file that hold a secret for the HMAC used in - ``--auth-gen-token`` If ``file`` is not present OpenVPN will generate a - random secret on startup. This file should be used if auth-token should - valid after restarting a server or if client should be able to roam - between multiple OpenVPN server with their auth-token. - ---opt-verify - Clients that connect with options that are incompatible with those of the - server will be disconnected. - - Options that will be compared for compatibility include ``dev-type``, - ``link-mtu``, ``tun-mtu``, ``proto``, ``ifconfig``, - ``comp-lzo``, ``fragment``, ``keydir``, ``cipher``, - ``auth``, ``keysize``, ``secret``, ``no-replay``, - ``no-iv``, ``tls-auth``, ``key-method``, ``tls-server`` - and ``tls-client``. - - This option requires that ``--disable-occ`` NOT be used. - ---auth-user-pass-optional - Allow connections by clients that do not specify a username/password. - Normally, when ``--auth-user-pass-verify`` or - ``--management-client-auth`` is specified (or an authentication plugin - module), the OpenVPN server daemon will require connecting clients to - specify a username and password. This option makes the submission of a - username/password by clients optional, passing the responsibility to the - user-defined authentication module/script to accept or deny the client - based on other factors (such as the setting of X509 certificate fields). - When this option is used, and a connecting client does not submit a - username/password, the user-defined authentication module/script will - see the username and password as being set to empty strings (""). The - authentication module/script MUST have logic to detect this condition - and respond accordingly. - ---verify-client-cert mode - Specify whether the client is required to supply a valid certificate. - - Possible ``mode`` options are: - - :code:`none` - A client certificate is not required. the client 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 ``--auth-user-pass-verify`` script, so keep in mind - that bugs in your script could potentially compromise the security of - your VPN. - - ``--verify-client-cert none`` is functionally equivalent to - ``--client-cert-not-required``. - - :code:`optional` - A client may present a certificate but it is not required to do so. - When using this directive, you should also use a - ``--auth-user-pass-verify`` script to ensure that clients are - authenticated using a certificate, a username and password, or - possibly even both. - - Again, the entire responsibility of authentication will rest on your - ``--auth-user-pass-verify`` script, so keep in mind that bugs in your - script could potentially compromise the security of your VPN. - - :code:`require` - This is the default option. A client is required topresent a - certificate, otherwise VPN access is refused. - - If you don't use this directive (or use ``--verify-client-cert require``) - but you also specify an ``--auth-user-pass-verify`` script, then OpenVPN - will perform double authentication. The client certificate verification - AND the ``--auth-user-pass-verify`` script will need to succeed in order - for a client to be authenticated and accepted onto the VPN. - ---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. - ---port-share args - Share OpenVPN TCP with another service - - Valid syntax: - :: - - port-share host port [dir] - - When run in TCP server mode, share the OpenVPN port with another - application, such as an HTTPS server. If OpenVPN senses a connection to - its port which is using a non-OpenVPN protocol, it will proxy the - connection to the server at ``host``:``port``. Currently only designed to - work with HTTP/HTTPS, though it would be theoretically possible to - extend to other protocols such as ssh. - - ``dir`` specifies an optional directory where a temporary file with name - N containing content C will be dynamically generated for each proxy - connection, where N is the source IP:port of the client connection and C - is the source IP:port of the connection to the proxy receiver. This - directory can be used as a dictionary by the proxy receiver to determine - the origin of the connection. Each generated file will be automatically - deleted when the proxied connection is torn down. - - Not implemented on Windows. - ---vlan-tagging - Server-only option. Turns the OpenVPN server instance into a switch that - understands VLAN-tagging, based on IEEE 802.1Q. - - The server TAP device and each of the connecting clients is seen as a - port of the switch. All client ports are in untagged mode and the server - TAP device is VLAN-tagged, untagged or accepts both, depending on the - ``--vlan-accept`` setting. - - Ethernet frames with a prepended 802.1Q tag are called "tagged". If the - VLAN Identifier (VID) field in such a tag is non-zero, the frame is - called "VLAN-tagged". If the VID is zero, but the Priority Control Point - (PCP) field is non-zero, the frame is called "prio-tagged". If there is - no 802.1Q tag, the frame is "untagged". - - Using the ``--vlan-pvid v`` option once per client (see - --client-config-dir), each port can be associated with a certain VID. - Packets can only be forwarded between ports having the same VID. - Therefore, clients with differing VIDs are completely separated from - one-another, even if ``--client-to-client`` is activated. - - The packet filtering takes place in the OpenVPN server. Clients should - not have any VLAN tagging configuration applied. - - The ``--vlan-tagging`` option is off by default. While turned off, - OpenVPN accepts any Ethernet frame and does not perform any special - processing for VLAN-tagged packets. - - The option can only be activated in ``--dev tap mode``. - ---vlan-accept args - Configure the VLAN tagging policy for the server TAP device. - - Valid syntax: - :: - - vlan-accept all|tagged|untagged - - The following modes are available: - - :code:`tagged` - Admit only VLAN-tagged frames. Only VLAN-tagged packets are accepted, - while untagged or priority-tagged packets are dropped when entering - the server TAP device. - - :code:`untagged` - Admit only untagged and prio-tagged frames. VLAN-tagged packets are - not accepted, while untagged or priority-tagged packets entering the - server TAP device are tagged with the value configured for the global - ``--vlan-pvid`` setting. - - :code:`all` (default) - Admit all frames. All packets are admitted and then treated like - untagged or tagged mode respectively. - - *Note*: - Some vendors refer to switch ports running in :code:`tagged` mode - as "trunk ports" and switch ports running in :code:`untagged` mode - as "access ports". - - Packets forwarded from clients to the server are VLAN-tagged with the - originating client's PVID, unless the VID matches the global - ``--vlan-pvid``, in which case the tag is removed. - - If no *PVID* is configured for a given client (see --vlan-pvid) packets - are tagged with 1 by default. - ---vlan-pvid v - Specifies which VLAN identifier a "port" is associated with. Only valid - when ``--vlan-tagging`` is speficied. - - In the client context, the setting specifies which VLAN ID a client is - associated with. In the global context, the VLAN ID of the server TAP - device is set. The latter only makes sense for ``--vlan-accept - untagged`` and ``--vlan-accept all`` modes. - - Valid values for ``v`` go from :code:`1` through to :code:`4094`. The - global value defaults to :code:`1`. If no ``--vlan-pvid`` is specified in - the client context, the global value is inherited. - - In some switch implementations, the *PVID* is also referred to as "Native - VLAN". - - -Client Mode ------------ - -Use client mode when connecting to an OpenVPN server which has -``--server``, ``--server-bridge``, or ``--mode server`` in its -configuration. - ---client - A helper directive designed to simplify the configuration of OpenVPN's - client mode. This directive is equivalent to: - :: - - pull - tls-client - ---pull - This option must be used on a client which is connecting to a - multi-client server. It indicates to OpenVPN that it should accept - options pushed by the server, provided they are part of the legal set of - pushable options (note that the ``--pull`` option is implied by - ``--client`` ). - - In particular, ``--pull`` allows the server to push routes to the - client, so you should not use ``--pull`` or ``--client`` in situations - where you don't trust the server to have control over the client's - routing table. - ---pull-filter args - Filter options on the client pushed by the server to the client. - - Valid syntaxes: - :: - - pull-filter accept text - pull-filter ignore text - pull-filter reject text - - Filter options received from the server if the option starts with - :code:`text`. The action flag :code:`accept` allows the option, - :code:`ignore` removes it and :code:`reject` flags an error and triggers - a :code:`SIGUSR1` restart. The filters may be specified multiple times, - and each filter is applied in the order it is specified. The filtering of - each option stops as soon as a match is found. Unmatched options are accepted - by default. - - Prefix comparison is used to match :code:`text` against the received option so - that - :: - - pull-filter ignore "route" - - would remove all pushed options starting with ``route`` which would - include, for example, ``route-gateway``. Enclose *text* in quotes to - embed spaces. - - :: - - pull-filter accept "route 192.168.1." - pull-filter ignore "route " - - would remove all routes that do not start with ``192.168.1``. - - *Note* that :code:`reject` may result in a repeated cycle of failure and - reconnect, unless multiple remotes are specified and connection to the - next remote succeeds. To silently ignore an option pushed by the server, - use :code:`ignore`. - ---auth-user-pass - Authenticate with server using username/password. - - Valid syntaxes: - :: - - auth-user-pass - auth-user-pass up - - If ``up`` is present, it must be a file containing username/password on 2 - lines. If the password line is missing, OpenVPN will prompt for one. - - If ``up`` is omitted, username/password will be prompted from the - console. - - The server configuration must specify an ``--auth-user-pass-verify`` - script to verify the username/password provided by the client. - ---auth-retry type - Controls how OpenVPN responds to username/password verification errors - such as the client-side response to an AUTH\_FAILED message from the - server or verification failure of the private key password. - - Normally used to prevent auth errors from being fatal on the client - side, and to permit username/password requeries in case of error. - - An AUTH\_FAILED message is generated by the server if the client fails - ``--auth-user-pass`` authentication, or if the server-side - ``--client-connect`` script returns an error status when the client - tries to connect. - - ``type`` can be one of: - - :code:`none` - Client will exit with a fatal error (this is the default). - - :code:`nointeract` - Client will retry the connection without requerying - for an ``--auth-user-pass`` username/password. Use this option for - unattended clients. - - :code:`interact` - Client will requery for an ``--auth-user-pass`` - username/password and/or private key password before attempting a - reconnection. - - Note that while this option cannot be pushed, it can be controlled from - the management interface. - ---static-challenge args - Enable static challenge/response protocol - - Valid syntax: - :: - - static-challenge text echo - - The ``text`` challenge text is presented to the user which describes what - information is requested. The ``echo`` flag indicates if the user's - input should be echoed on the screen. Valid ``echo`` values are - :code:`0` or :code:`1`. - - See management-notes.txt in the OpenVPN distribution for a description of - the OpenVPN challenge/response protocol. - ---server-poll-timeout n - When connecting to a remote server do not wait for more than **n** - seconds waiting for a response before trying the next server. The - default value is 120s. This timeout includes proxy and TCP connect - timeouts. - ---connect-timeout n - See ``--server-poll-timeout``. - ---explicit-exit-notify n - In UDP client mode or point-to-point mode, send server/peer an exit - notification if tunnel is restarted or OpenVPN process is exited. In - client mode, on exit/restart, this option will tell the server to - immediately close its client instance object rather than waiting for a - timeout. - - The **n** parameter (default :code:`1` if not present) controls the - maximum number of attempts that the client will try to resend the exit - notification message. - - In UDP server mode, send :code:`RESTART` control channel command to - connected clients. The ``n`` parameter (default :code:`1` if not present) - controls client behavior. With ``n`` = :code:`1` client will attempt to - reconnect to the same server, with ``n`` = :code:`2` client will advance - to the next server. - - OpenVPN will not send any exit notifications unless this option is - enabled. - ---allow-recursive-routing - When this option is set, OpenVPN will not drop incoming tun packets with - same destination as host. - - -Data Channel Encryption Options -------------------------------- - -These options are meaningful for both Static & TLS-negotiated key modes -(must be compatible between peers). - ---secret args - Enable Static Key encryption mode (non-TLS). Use pre-shared secret - ``file`` which was generated with ``--genkey``. - - Valid syntaxes: - :: - - secret file - secret file direction - - The optional ``direction`` parameter enables the use of 4 distinct keys - (HMAC-send, cipher-encrypt, HMAC-receive, cipher-decrypt), so that each - data flow direction has a different set of HMAC and cipher keys. This - has a number of desirable security properties including eliminating - certain kinds of DoS and message replay attacks. - - When the ``direction`` parameter is omitted, 2 keys are used - bidirectionally, one for HMAC and the other for encryption/decryption. - - The ``direction`` parameter should always be complementary on either - side of the connection, i.e. one side should use :code:`0` and the other - should use :code:`1`, or both sides should omit it altogether. - - The ``direction`` parameter requires that ``file`` contains a 2048 bit - key. While pre-1.5 versions of OpenVPN generate 1024 bit key files, any - version of OpenVPN which supports the ``direction`` parameter, will also - support 2048 bit key file generation using the ``--genkey`` option. - - Static key encryption mode has certain advantages, the primary being - ease of configuration. - - There are no certificates or certificate authorities or complicated - negotiation handshakes and protocols. The only requirement is that you - have a pre-existing secure channel with your peer (such as ``ssh``) to - initially copy the key. This requirement, along with the fact that your - key never changes unless you manually generate a new one, makes it - somewhat less secure than TLS mode (see below). If an attacker manages - to steal your key, everything that was ever encrypted with it is - compromised. Contrast that to the perfect forward secrecy features of - TLS mode (using Diffie Hellman key exchange), where even if an attacker - was able to steal your private key, he would gain no information to help - him decrypt past sessions. - - Another advantageous aspect of Static Key encryption mode is that it is - a handshake-free protocol without any distinguishing signature or - feature (such as a header or protocol handshake sequence) that would - mark the ciphertext packets as being generated by OpenVPN. Anyone - eavesdropping on the wire would see nothing but random-looking data. - ---key-direction - Alternative way of specifying the optional direction parameter for the - ``--tls-auth`` and ``--secret`` options. Useful when using inline files - (See section on inline files). - ---auth alg - Authenticate data channel packets and (if enabled) ``tls-auth`` control - channel packets with HMAC using message digest algorithm ``alg``. (The - default is ``SHA1`` ). HMAC is a commonly used message authentication - algorithm (MAC) that uses a data string, a secure hash algorithm, and a - key, to produce a digital signature. - - The OpenVPN data channel protocol uses encrypt-then-mac (i.e. first - encrypt a packet, then HMAC the resulting ciphertext), which prevents - padding oracle attacks. - - If an AEAD cipher mode (e.g. GCM) is chosen, the specified ``--auth`` - algorithm is ignored for the data channel, and the authentication method - of the AEAD cipher is used instead. Note that ``alg`` still specifies - the digest used for ``tls-auth``. - - In static-key encryption mode, the HMAC key is included in the key file - generated by ``--genkey``. In TLS mode, the HMAC key is dynamically - generated and shared between peers via the TLS control channel. If - OpenVPN receives a packet with a bad HMAC it will drop the packet. HMAC - usually adds 16 or 20 bytes per packet. Set ``alg=none`` to disable - authentication. - - For more information on HMAC see - http://www.cs.ucsd.edu/users/mihir/papers/hmac.html - ---cipher alg - Encrypt data channel packets with cipher algorithm ``alg``. - - The default is :code:`BF-CBC`, an abbreviation for Blowfish in Cipher - Block Chaining mode. When cipher negotiation (NCP) is allowed, - OpenVPN 2.4 and newer on both client and server side will automatically - upgrade to :code:`AES-256-GCM`. See ``--ncp-ciphers`` and - ``--ncp-disable`` for more details on NCP. - - Using :code:`BF-CBC` is no longer recommended, because of its 64-bit - block size. This small block size allows attacks based on collisions, as - demonstrated by SWEET32. See - https://community.openvpn.net/openvpn/wiki/SWEET32 - for details. Due to this, support for :code:`BF-CBC`, :code:`DES`, - :code:`CAST5`, :code:`IDEA` and :code:`RC2` ciphers will be removed in - OpenVPN 2.6. - - To see other ciphers that are available with OpenVPN, use the - ``--show-ciphers`` option. - - Set ``alg`` to :code:`none` to disable encryption. - ---ncp-ciphers cipher-list - Restrict the allowed ciphers to be negotiated to the ciphers in - ``cipher-list``. ``cipher-list`` is a colon-separated list of ciphers, - and defaults to :code:`AES-256-GCM:AES-128-GCM`. - - For servers, the first cipher from ``cipher-list`` that is also - supported by the client will be pushed to clients that support cipher - negotiation. - - Cipher negotiation is enabled in client-server mode only. I.e. if - ``--mode`` is set to 'server' (server-side, implied by setting - ``--server`` ), or if ``--pull`` is specified (client-side, implied by - setting --client). - - If both peers support and do not disable NCP, the negotiated cipher will - override the cipher specified by ``--cipher``. - - Additionally, to allow for more smooth transition, if NCP is enabled, - OpenVPN will inherit the cipher of the peer if that cipher is different - from the local ``--cipher`` setting, but the peer cipher is one of the - ciphers specified in ``--ncp-ciphers``. E.g. a non-NCP client (<=v2.3, - or with --ncp-disabled set) connecting to a NCP server (v2.4+) with - ``--cipher BF-CBC`` and ``--ncp-ciphers AES-256-GCM:AES-256-CBC`` set can - either specify ``--cipher BF-CBC`` or ``--cipher AES-256-CBC`` and both - will work. - - Note, for using NCP with a OpenVPN 2.4 peer this list must include the - :code:`AES-256-GCM` and :code:`AES-128-GCM` ciphers. - - This list is restricted to be 127 chars long after conversion to OpenVPN - ciphers. - ---ncp-disable - Disable "Negotiable Crypto Parameters". This completely disables cipher - negotiation. - ---keysize n - **DEPRECATED** This option will be removed in OpenVPN 2.6. - - Size of cipher key in bits (optional). If unspecified, defaults to - cipher-specific default. The ``--show-ciphers`` option (see below) shows - all available OpenSSL ciphers, their default key sizes, and whether the - key size can be changed. Use care in changing a cipher's default key - size. Many ciphers have not been extensively cryptanalyzed with - non-standard key lengths, and a larger key may offer no real guarantee - of greater security, or may even reduce security. - ---prng args - *(Advanced)* Change the PRNG (Pseudo-random number generator) parameters - - Valid syntaxes: - :: - - prng alg - prng alg nsl - - Changes the PRNG to use digest algorithm **alg** (default :code:`sha1`), - and set ``nsl`` (default :code:`16`) to the size in bytes of the nonce - secret length (between 16 and 64). - - Set ``alg`` to :code:`none` to disable the PRNG and use the OpenSSL - RAND\_bytes function instead for all of OpenVPN's pseudo-random number - needs. - ---engine engine-name - Enable OpenSSL hardware-based crypto engine functionality. - - If ``engine-name`` is specified, use a specific crypto engine. Use the - ``--show-engines`` standalone option to list the crypto engines which - are supported by OpenSSL. - ---replay-window args - Modify the replay protection sliding-window size and time window. - - Valid syntax: - :: - - replay-window n [t] - - Use a replay protection sliding-window of size **n** and a time window - of **t** seconds. - - By default **n** is 64 (the IPSec default) and **t** is 15 seconds. - - This option is only relevant in UDP mode, i.e. when either **--proto - udp** is specified, or no **--proto** option is specified. - - When OpenVPN tunnels IP packets over UDP, there is the possibility that - packets might be dropped or delivered out of order. Because OpenVPN, - like IPSec, is emulating the physical network layer, it will accept an - out-of-order packet sequence, and will deliver such packets in the same - order they were received to the TCP/IP protocol stack, provided they - satisfy several constraints. - - (a) The packet cannot be a replay (unless ``--no-replay`` is - specified, which disables replay protection altogether). - - (b) If a packet arrives out of order, it will only be accepted if - the difference between its sequence number and the highest sequence - number received so far is less than ``n``. - - (c) If a packet arrives out of order, it will only be accepted if it - arrives no later than ``t`` seconds after any packet containing a higher - sequence number. - - If you are using a network link with a large pipeline (meaning that the - product of bandwidth and latency is high), you may want to use a larger - value for ``n``. Satellite links in particular often require this. - - If you run OpenVPN at ``--verb 4``, you will see the message - "Replay-window backtrack occurred [x]" every time the maximum sequence - number backtrack seen thus far increases. This can be used to calibrate - ``n``. - - There is some controversy on the appropriate method of handling packet - reordering at the security layer. - - Namely, to what extent should the security layer protect the - encapsulated protocol from attacks which masquerade as the kinds of - normal packet loss and reordering that occur over IP networks? - - The IPSec and OpenVPN approach is to allow packet reordering within a - certain fixed sequence number window. - - OpenVPN adds to the IPSec model by limiting the window size in time as - well as sequence space. - - OpenVPN also adds TCP transport as an option (not offered by IPSec) in - which case OpenVPN can adopt a very strict attitude towards message - deletion and reordering: Don't allow it. Since TCP guarantees - reliability, any packet loss or reordering event can be assumed to be an - attack. - - In this sense, it could be argued that TCP tunnel transport is preferred - when tunneling non-IP or UDP application protocols which might be - vulnerable to a message deletion or reordering attack which falls within - the normal operational parameters of IP networks. - - So I would make the statement that one should never tunnel a non-IP - protocol or UDP application protocol over UDP, if the protocol might be - vulnerable to a message deletion or reordering attack that falls within - the normal operating parameters of what is to be expected from the - physical IP layer. The problem is easily fixed by simply using TCP as - the VPN transport layer. - ---mute-replay-warnings - Silence the output of replay warnings, which are a common false alarm on - WiFi networks. This option preserves the security of the replay - protection code without the verbosity associated with warnings about - duplicate packets. - ---replay-persist file - Persist replay-protection state across sessions using ``file`` to save - and reload the state. - - This option will strengthen protection against replay attacks, - especially when you are using OpenVPN in a dynamic context (such as with - ``--inetd``) when OpenVPN sessions are frequently started and stopped. - - This option will keep a disk copy of the current replay protection state - (i.e. the most recent packet timestamp and sequence number received from - the remote peer), so that if an OpenVPN session is stopped and - restarted, it will reject any replays of packets which were already - received by the prior session. - - This option only makes sense when replay protection is enabled (the - default) and you are using either ``--secret`` (shared-secret key mode) - or TLS mode with ``--tls-auth``. - ---use-prediction-resistance - Enable prediction resistance on mbed TLS's RNG. - - Enabling prediction resistance causes the RNG to reseed in each call for - random. Reseeding this often can quickly deplete the kernel entropy - pool. - - If you need this option, please consider running a daemon that adds - entropy to the kernel pool. - ---test-crypto - Do a self-test of OpenVPN's crypto options by encrypting and decrypting - test packets using the data channel encryption options specified above. - This option does not require a peer to function, and therefore can be - specified without ``--dev`` or ``--remote``. - - The typical usage of ``--test-crypto`` would be something like this: - :: - - openvpn --test-crypto --secret key - - or - - :: - - openvpn --test-crypto --secret key --verb 9 - - This option is very useful to test OpenVPN after it has been ported to a - new platform, or to isolate problems in the compiler, OpenSSL crypto - library, or OpenVPN's crypto code. Since it is a self-test mode, - problems with encryption and authentication can be debugged - independently of network and tunnel issues. - - -TLS Mode Options ----------------- - -TLS mode is the most powerful crypto mode of OpenVPN in both security -and flexibility. TLS mode works by establishing control and data -channels which are multiplexed over a single TCP/UDP port. OpenVPN -initiates a TLS session over the control channel and uses it to exchange -cipher and HMAC keys to protect the data channel. TLS mode uses a robust -reliability layer over the UDP connection for all control channel -communication, while the data channel, over which encrypted tunnel data -passes, is forwarded without any mediation. The result is the best of -both worlds: a fast data channel that forwards over UDP with only the -overhead of encrypt, decrypt, and HMAC functions, and a control channel -that provides all of the security features of TLS, including -certificate-based authentication and Diffie Hellman forward secrecy. - -To use TLS mode, each peer that runs OpenVPN should have its own local -certificate/key pair (``--cert`` and ``--key``), signed by the root -certificate which is specified in ``--ca``. - -When two OpenVPN peers connect, each presents its local certificate to -the other. Each peer will then check that its partner peer presented a -certificate which was signed by the master root certificate as specified -in ``--ca``. - -If that check on both peers succeeds, then the TLS negotiation will -succeed, both OpenVPN peers will exchange temporary session keys, and -the tunnel will begin passing data. - -The OpenVPN project provides a set of scripts for managing RSA -certificates and keys: https://github.com/OpenVPN/easy-rsa - ---tls-server - Enable TLS and assume server role during TLS handshake. Note that - OpenVPN is designed as a peer-to-peer application. The designation of - client or server is only for the purpose of negotiating the TLS control - channel. - ---tls-client - Enable TLS and assume client role during TLS handshake. - ---ca file - Certificate authority (CA) file in .pem format, also referred to as the - *root* certificate. This file can have multiple certificates in .pem - format, concatenated together. You can construct your own certificate - authority certificate and private key by using a command such as: - :: - - openssl req -nodes -new -x509 -keyout ca.key -out ca.crt - - Then edit your openssl.cnf file and edit the ``certificate`` variable to - point to your new root certificate ``ca.crt``. - - For testing purposes only, the OpenVPN distribution includes a sample CA - certificate (ca.crt). Of course you should never use the test - certificates and test keys distributed with OpenVPN in a production - environment, since by virtue of the fact that they are distributed with - OpenVPN, they are totally insecure. - ---capath dir - Directory containing trusted certificates (CAs and CRLs). Not available - with mbed TLS. - - CAs in the capath directory are expected to be named .. CRLs - are expected to be named .r. See the ``-CApath`` option of - ``openssl verify``, and the ``-hash`` option of ``openssl x509``, - ``openssl crl`` and ``X509_LOOKUP_hash_dir()``\(3) - for more information. - - Similarly to the ``--crl-verify`` option CRLs are not mandatory - - OpenVPN will log the usual warning in the logs if the relevant CRL is - missing, but the connection will be allowed. - ---dh file - File containing Diffie Hellman parameters in .pem format (required for - ``--tls-server`` only). - - Set ``file`` to :code:`none` to disable Diffie Hellman key exchange (and - use ECDH only). Note that this requires peers to be using an SSL library - that supports ECDH TLS cipher suites (e.g. OpenSSL 1.0.1+, or - mbed TLS 2.0+). - - Use ``openssl dhparam -out dh2048.pem 2048`` to generate 2048-bit DH - parameters. Diffie Hellman parameters may be considered public. - ---ecdh-curve name - Specify the curve to use for elliptic curve Diffie Hellman. Available - curves can be listed with ``--show-curves``. The specified curve will - only be used for ECDH TLS-ciphers. - - This option is not supported in mbed TLS builds of OpenVPN. - ---cert file - Local peer's signed certificate in .pem format -- must be signed by a - certificate authority whose certificate is in ``--ca file``. Each peer - in an OpenVPN link running in TLS mode should have its own certificate - and private key file. In addition, each certificate should have been - signed by the key of a certificate authority whose public key resides in - the ``--ca`` certificate authority file. You can easily make your own - certificate authority (see above) or pay money to use a commercial - service such as thawte.com (in which case you will be helping to finance - the world's second space tourist :). To generate a certificate, you can - use a command such as: - :: - - openssl req -nodes -new -keyout mycert.key -out mycert.csr - - If your certificate authority private key lives on another machine, copy - the certificate signing request (mycert.csr) to this other machine (this - can be done over an insecure channel such as email). Now sign the - certificate with a command such as: - :: - - openssl ca -out mycert.crt -in mycert.csr - - Now copy the certificate (mycert.crt) back to the peer which initially - generated the .csr file (this can be over a public medium). Note that - the ``openssl ca`` command reads the location of the certificate - authority key from its configuration file such as - :code:`/usr/share/ssl/openssl.cnf` -- note also that for certificate - authority functions, you must set up the files :code:`index.txt` (may be - empty) and :code:`serial` (initialize to :code:`01`). - ---extra-certs file - Specify a ``file`` containing one or more PEM certs (concatenated - together) that complete the local certificate chain. - - This option is useful for "split" CAs, where the CA for server certs is - different than the CA for client certs. Putting certs in this file - allows them to be used to complete the local certificate chain without - trusting them to verify the peer-submitted certificate, as would be the - case if the certs were placed in the ``ca`` file. - ---key file - Local peer's private key in .pem format. Use the private key which was - generated when you built your peer's certificate (see ``--cert file`` - above). - ---tls-version-min args - Sets the minimum TLS version we will accept from the peer (default is - "1.0"). - - Valid syntax: - :: - - tls-version-min version ['or-highest'] - - Examples for version include :code:`1.0`, :code:`1.1`, or :code:`1.2`. If - :code:`or-highest` is specified and version is not recognized, we will - only accept the highest TLS version supported by the local SSL - implementation. - ---tls-version-max version - Set the maximum TLS version we will use (default is the highest version - supported). Examples for version include :code:`1.0`, :code:`1.1`, or - :code:`1.2`. - ---pkcs12 file - Specify a PKCS #12 file containing local private key, local certificate, - and root CA certificate. This option can be used instead of ``--ca``, - ``--cert``, and ``--key``. Not available with mbed TLS. - ---verify-hash args - Specify SHA1 or SHA256 fingerprint for level-1 cert. - - Valid syntax: - :: - - verify-hash hash [algo] - - The level-1 cert is the CA (or intermediate cert) that signs the leaf - certificate, and is one removed from the leaf certificate in the - direction of the root. When accepting a connection from a peer, the - level-1 cert fingerprint must match ``hash`` or certificate verification - will fail. Hash is specified as XX:XX:... For example: - :: - - AD:B0:95:D8:09:C8:36:45:12:A9:89:C8:90:09:CB:13:72:A6:AD:16 - - The ``algo`` flag can be either :code:`SHA1` or :code:`SHA256`. If not - provided, it defaults to :code:`SHA1`. - ---pkcs11-cert-private args - Set if access to certificate object should be performed after login. - Every provider has its own setting. - - Valid syntaxes: - :: - - pkcs11-cert-private 0 - pkcs11-cert-private 1 - ---pkcs11-id name - Specify the serialized certificate id to be used. The id can be gotten - by the standalone ``--show-pkcs11-ids`` option. - ---pkcs11-id-management - Acquire PKCS#11 id from management interface. In this case a - :code:`NEED-STR 'pkcs11-id-request'` real-time message will be triggered, - application may use pkcs11-id-count command to retrieve available number of - certificates, and pkcs11-id-get command to retrieve certificate id and - certificate body. - ---pkcs11-pin-cache seconds - Specify how many seconds the PIN can be cached, the default is until the - token is removed. - ---pkcs11-protected-authentication args - Use PKCS#11 protected authentication path, useful for biometric and - external keypad devices. Every provider has its own setting. - - Valid syntaxes: - :: - - pkcs11-protected-authentication 0 - pkcs11-protected-authentication 1 - ---pkcs11-providers provider - Specify a RSA Security Inc. PKCS #11 Cryptographic Token Interface - (Cryptoki) providers to load. This option can be used instead of - ``--cert``, ``--key`` and ``--pkcs12``. - - If p11-kit is present on the system, its :code:`p11-kit-proxy.so` module - will be loaded by default if either the ``--pkcs11-id`` or - ``--pkcs11-id-management`` options are specified without - ``--pkcs11-provider`` being given. - ---pkcs11-private-mode mode - Specify which method to use in order to perform private key operations. - A different mode can be specified for each provider. Mode is encoded as - hex number, and can be a mask one of the following: - - :code:`0` (default) Try to determine automatically. - - :code:`1` Use sign. - - :code:`2` Use sign recover. - - :code:`4` Use decrypt. - - :code:`8` Use unwrap. - ---cryptoapicert select-string - *(Windows/OpenSSL Only)* Load the certificate and private key from the - Windows Certificate System Store. - - Use this option instead of ``--cert`` and ``--key``. - - This makes it possible to use any smart card, supported by Windows, but - also any kind of certificate, residing in the Cert Store, where you have - access to the private key. This option has been tested with a couple of - different smart cards (GemSAFE, Cryptoflex, and Swedish Post Office eID) - on the client side, and also an imported PKCS12 software certificate on - the server side. - - To select a certificate, based on a substring search in the - certificate's subject: - :: - - cryptoapicert "SUBJ:Peter Runestig" - - To select a certificate, based on certificate's thumbprint: - :: - - cryptoapicert "THUMB:f6 49 24 41 01 b4 ..." - - The thumbprint hex string can easily be copy-and-pasted from the Windows - Certificate Store GUI. - -*WARNING:* ``--tls-ciphers`` and ``--tls-ciphersuites`` - These options are expert features, which - if used correctly - can - improve the security of your VPN connection. But it is also easy to - unwittingly use them to carefully align a gun with your foot, or just - break your connection. Use with care! - ---tls-cipher l - A list ``l`` of allowable TLS ciphers delimited by a colon (":code:`:`"). - - These setting can be used to ensure that certain cipher suites are used - (or not used) for the TLS connection. OpenVPN uses TLS to secure the - control channel, over which the keys that are used to protect the actual - VPN traffic are exchanged. - - The supplied list of ciphers is (after potential OpenSSL/IANA name - translation) simply supplied to the crypto library. Please see the - OpenSSL and/or mbed TLS documentation for details on the cipher list - interpretation. - - For OpenSSL, the ``--tls-cipher`` is used for TLS 1.2 and below. - - Use ``--show-tls`` to see a list of TLS ciphers supported by your crypto - library. - - The default for ``--tls-cipher`` is to use mbed TLS's default cipher list - when using mbed TLS or - :code:`DEFAULT:!EXP:!LOW:!MEDIUM:!kDH:!kECDH:!DSS:!PSK:!SRP:!kRSA` when - using OpenSSL. - - The default for `--tls-ciphersuites` is to use the crypto library's - default. - ---tls-ciphersuites l - Same as ``--tls-cipher`` but for TLS 1.3 and up. mbed TLS has no - TLS 1.3 support yet and only the ``--tls-cipher`` setting is used. - ---tls-cert-profile profile - Set the allowed cryptographic algorithms for certificates according to - ``profile``. - - The following profiles are supported: - - :code:`legacy` (default) - SHA1 and newer, RSA 2048-bit+, any elliptic curve. - - :code:`preferred` - SHA2 and newer, RSA 2048-bit+, any elliptic curve. - - :code:`suiteb` - SHA256/SHA384, ECDSA with P-256 or P-384. - - This option is only fully supported for mbed TLS builds. OpenSSL builds - use the following approximation: - - :code:`legacy` (default) - sets "security level 1" - - :code:`preferred` - sets "security level 2" - - :code:`suiteb` - sets "security level 3" and ``--tls-cipher "SUITEB128"``. - - OpenVPN will migrate to 'preferred' as default in the future. Please - ensure that your keys already comply. - ---tls-timeout n - Packet retransmit timeout on TLS control channel if no acknowledgment - from remote within ``n`` seconds (default :code:`2`). When OpenVPN sends - a control packet to its peer, it will expect to receive an - acknowledgement within ``n`` seconds or it will retransmit the packet, - subject to a TCP-like exponential backoff algorithm. This parameter only - applies to control channel packets. Data channel packets (which carry - encrypted tunnel data) are never acknowledged, sequenced, or - retransmitted by OpenVPN because the higher level network protocols - running on top of the tunnel such as TCP expect this role to be left to - them. - ---reneg-bytes n - Renegotiate data channel key after ``n`` bytes sent or received - (disabled by default with an exception, see below). OpenVPN allows the - lifetime of a key to be expressed as a number of bytes - encrypted/decrypted, a number of packets, or a number of seconds. A key - renegotiation will be forced if any of these three criteria are met by - either peer. - - If using ciphers with cipher block sizes less than 128-bits, - ``--reneg-bytes`` is set to 64MB by default, unless it is explicitly - disabled by setting the value to :code:`0`, but this is - **HIGHLY DISCOURAGED** as this is designed to add some protection against - the SWEET32 attack vector. For more information see the ``--cipher`` - option. - ---reneg-pkts n - Renegotiate data channel key after **n** packets sent and received - (disabled by default). - ---reneg-sec args - Renegotiate data channel key after at most ``max`` seconds - (default :code:`3600`) and at least ``min`` seconds (default is 90% of - ``max`` for servers, and equal to ``max`` for clients). - :: - - reneg-sec max [min] - - The effective ``--reneg-sec`` value used is per session - pseudo-uniform-randomized between ``min`` and ``max``. - - With the default value of :code:`3600` this results in an effective per - session value in the range of :code:`3240`..:code:`3600` seconds for - servers, or just 3600 for clients. - - When using dual-factor authentication, note that this default value may - cause the end user to be challenged to reauthorize once per hour. - - Also, keep in mind that this option can be used on both the client and - server, and whichever uses the lower value will be the one to trigger - the renegotiation. A common mistake is to set ``--reneg-sec`` to a - higher value on either the client or server, while the other side of the - connection is still using the default value of :code:`3600` seconds, - meaning that the renegotiation will still occur once per :code:`3600` - seconds. The solution is to increase --reneg-sec on both the client and - server, or set it to :code:`0` on one side of the connection (to - disable), and to your chosen value on the other side. - ---hand-window n - Handshake Window -- the TLS-based key exchange must finalize within - ``n`` seconds of handshake initiation by any peer (default :code:`60` - seconds). If the handshake fails we will attempt to reset our connection - with our peer and try again. Even in the event of handshake failure we - will still use our expiring key for up to ``--tran-window`` seconds to - maintain continuity of transmission of tunnel data. - ---tran-window n - Transition window -- our old key can live this many seconds after a new - a key renegotiation begins (default :code:`3600` seconds). This feature - allows for a graceful transition from old to new key, and removes the key - renegotiation sequence from the critical path of tunnel data forwarding. - ---single-session - After initially connecting to a remote peer, disallow any new - connections. Using this option means that a remote peer cannot connect, - disconnect, and then reconnect. - - If the daemon is reset by a signal or ``--ping-restart``, it will allow - one new connection. - - ``--single-session`` can be used with ``--ping-exit`` or ``--inactive`` - to create a single dynamic session that will exit when finished. - ---tls-exit - Exit on TLS negotiation failure. - ---tls-auth args - Add an additional layer of HMAC authentication on top of the TLS control - channel to mitigate DoS attacks and attacks on the TLS stack. - - Valid syntaxes: - :: - - tls-auth file - tls-auth file 0 - tls-auth file 1 - - In a nutshell, ``--tls-auth`` enables a kind of "HMAC firewall" on - OpenVPN's TCP/UDP port, where TLS control channel packets bearing an - incorrect HMAC signature can be dropped immediately without response. - - ``file`` (required) is a file in OpenVPN static key format which can be - generated by ``--genkey``. - - Older versions (up to OpenVPN 2.3) supported a freeform passphrase file. - This is no longer supported in newer versions (v2.4+). - - See the ``--secret`` option for more information on the optional - ``direction`` parameter. - - ``--tls-auth`` is recommended when you are running OpenVPN in a mode - where it is listening for packets from any IP address, such as when - ``--remote`` is not specified, or ``--remote`` is specified with - ``--float``. - - The rationale for this feature is as follows. TLS requires a - multi-packet exchange before it is able to authenticate a peer. During - this time before authentication, OpenVPN is allocating resources (memory - and CPU) to this potential peer. The potential peer is also exposing - many parts of OpenVPN and the OpenSSL library to the packets it is - sending. Most successful network attacks today seek to either exploit - bugs in programs (such as buffer overflow attacks) or force a program to - consume so many resources that it becomes unusable. Of course the first - line of defense is always to produce clean, well-audited code. OpenVPN - has been written with buffer overflow attack prevention as a top - priority. But as history has shown, many of the most widely used network - applications have, from time to time, fallen to buffer overflow attacks. - - So as a second line of defense, OpenVPN offers this special layer of - authentication on top of the TLS control channel so that every packet on - the control channel is authenticated by an HMAC signature and a unique - ID for replay protection. This signature will also help protect against - DoS (Denial of Service) attacks. An important rule of thumb in reducing - vulnerability to DoS attacks is to minimize the amount of resources a - potential, but as yet unauthenticated, client is able to consume. - - ``--tls-auth`` does this by signing every TLS control channel packet - with an HMAC signature, including packets which are sent before the TLS - level has had a chance to authenticate the peer. The result is that - packets without the correct signature can be dropped immediately upon - reception, before they have a chance to consume additional system - resources such as by initiating a TLS handshake. ``--tls-auth`` can be - strengthened by adding the ``--replay-persist`` option which will keep - OpenVPN's replay protection state in a file so that it is not lost - across restarts. - - It should be emphasized that this feature is optional and that the key - file used with ``--tls-auth`` gives a peer nothing more than the power - to initiate a TLS handshake. It is not used to encrypt or authenticate - any tunnel data. - - Use ``--tls-crypt`` instead if you want to use the key file to not only - authenticate, but also encrypt the TLS control channel. - ---tls-crypt keyfile - Encrypt and authenticate all control channel packets with the key from - ``keyfile``. (See ``--tls-auth`` for more background.) - - Encrypting (and authenticating) control channel packets: - - * provides more privacy by hiding the certificate used for the TLS - connection, - - * makes it harder to identify OpenVPN traffic as such, - - * provides "poor-man's" post-quantum security, against attackers who will - never know the pre-shared key (i.e. no forward secrecy). - - In contrast to ``--tls-auth``, ``--tls-crypt`` does *not* require the - user to set ``--key-direction``. - - **Security Considerations** - - All peers use the same ``--tls-crypt`` pre-shared group key to - authenticate and encrypt control channel messages. To ensure that IV - collisions remain unlikely, this key should not be used to encrypt more - than 2^48 client-to-server or 2^48 server-to-client control channel - messages. A typical initial negotiation is about 10 packets in each - direction. Assuming both initial negotiation and renegotiations are at - most 2^16 (65536) packets (to be conservative), and (re)negotiations - happen each minute for each user (24/7), this limits the tls-crypt key - lifetime to 8171 years divided by the number of users. So a setup with - 1000 users should rotate the key at least once each eight years. (And a - setup with 8000 users each year.) - - If IV collisions were to occur, this could result in the security of - ``--tls-crypt`` degrading to the same security as using ``--tls-auth``. - That is, the control channel still benefits from the extra protection - against active man-in-the-middle-attacks and DoS attacks, but may no - longer offer extra privacy and post-quantum security on top of what TLS - itself offers. - - For large setups or setups where clients are not trusted, consider using - ``--tls-crypt-v2`` instead. That uses per-client unique keys, and - thereby improves the bounds to 'rotate a client key at least once per - 8000 years'. - ---tls-crypt-v2 keyfile - Use client-specific tls-crypt keys. - - For clients, ``keyfile`` is a client-specific tls-crypt key. Such a key - can be generated using the :code:`--genkey tls-crypt-v2-client` option. - - For servers, ``keyfile`` is used to unwrap client-specific keys supplied - by the client during connection setup. This key must be the same as the - key used to generate the client-specific key (see :code:`--genkey - tls-crypt-v2-client`). - - On servers, this option can be used together with the ``--tls-auth`` or - ``--tls-crypt`` option. In that case, the server will detect whether the - client is using client-specific keys, and automatically select the right - mode. - ---tls-crypt-v2-verify cmd - Run command ``cmd`` to verify the metadata of the client-specific - tls-crypt-v2 key of a connecting client. This allows server - administrators to reject client connections, before exposing the TLS - stack (including the notoriously dangerous X.509 and ASN.1 stacks) to - the connecting client. - - OpenVPN supplies the following environment variables to the command: - - * :code:`script_type` is set to :code:`tls-crypt-v2-verify` - - * :code:`metadata_type` is set to :code:`0` if the metadata was user - supplied, or :code:`1` if it's a 64-bit unix timestamp representing - the key creation time. - - * :code:`metadata_file` contains the filename of a temporary file that - contains the client metadata. - - The command can reject the connection by exiting with a non-zero exit - code. - ---askpass file - Get certificate password from console or ``file`` before we daemonize. - - Valid syntaxes: - :: - - askpass - askpass file - - For the extremely security conscious, it is possible to protect your - private key with a password. Of course this means that every time the - OpenVPN daemon is started you must be there to type the password. The - ``--askpass`` option allows you to start OpenVPN from the command line. - It will query you for a password before it daemonizes. To protect a - private key with a password you should omit the ``-nodes`` option when - you use the ``openssl`` command line tool to manage certificates and - private keys. - - If ``file`` is specified, read the password from the first line of - ``file``. Keep in mind that storing your password in a file to a certain - extent invalidates the extra security provided by using an encrypted - key. - ---auth-nocache - Don't cache ``--askpass`` or ``--auth-user-pass`` username/passwords in - virtual memory. - - If specified, this directive will cause OpenVPN to immediately forget - username/password inputs after they are used. As a result, when OpenVPN - needs a username/password, it will prompt for input from stdin, which - may be multiple times during the duration of an OpenVPN session. - - When using ``--auth-nocache`` in combination with a user/password file - and ``--chroot`` or ``--daemon``, make sure to use an absolute path. - - This directive does not affect the ``--http-proxy`` username/password. - It is always cached. - ---auth-token token - This is not an option to be used directly in any configuration files, - but rather push this option from a ``--client-connect`` script or a - ``--plugin`` which hooks into the :code:`OPENVPN_PLUGIN_CLIENT_CONNECT` - or :code:`OPENVPN_PLUGIN_CLIENT_CONNECT_V2` calls. This option provides a - possibility to replace the clients password with an authentication token - during the lifetime of the OpenVPN client. - - Whenever the connection is renegotiated and the - ``--auth-user-pass-verify`` script or ``--plugin`` making use of the - :code:`OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY` hook is triggered, it will - pass over this token as the password instead of the password the user - provided. The authentication token can only be reset by a full reconnect - where the server can push new options to the client. The password the - user entered is never preserved once an authentication token have been - set. If the OpenVPN server side rejects the authentication token, the - client will receive an ``AUTH_FAIL`` and disconnect. - - The purpose of this is to enable two factor authentication methods, such - as HOTP or TOTP, to be used without needing to retrieve a new OTP code - each time the connection is renegotiated. Another use case is to cache - authentication data on the client without needing to have the users - password cached in memory during the life time of the session. - - To make use of this feature, the ``--client-connect`` script or - ``--plugin`` needs to put - :: - - push "auth-token UNIQUE_TOKEN_VALUE" - - into the file/buffer for dynamic configuration data. This will then make - the OpenVPN server to push this value to the client, which replaces the - local password with the ``UNIQUE_TOKEN_VALUE``. - - Newer clients (2.4.7+) will fall back to the original password method - after a failed auth. Older clients will keep using the token value and - react according to ``--auth-retry`` - ---tls-verify cmd - Run command ``cmd`` to verify the X509 name of a pending TLS connection - that has otherwise passed all other tests of certification (except for - revocation via ``--crl-verify`` directive; the revocation test occurs - after the ``--tls-verify`` test). - - ``cmd`` should return :code:`0` to allow the TLS handshake to proceed, - or :code:`1` to fail. - - ``cmd`` consists of a path to script (or executable program), optionally - followed by arguments. The path and arguments may be single- or - double-quoted and/or escaped using a backslash, and should be separated - by one or more spaces. - - When ``cmd`` is executed two arguments are appended after any arguments - specified in ``cmd``, as follows: - :: - - cmd certificate_depth subject - - These arguments are, respectively, the current certificate depth and the - X509 subject distinguished name (dn) of the peer. - - This feature is useful if the peer you want to trust has a certificate - which was signed by a certificate authority who also signed many other - certificates, where you don't necessarily want to trust all of them, but - rather be selective about which peer certificate you will accept. This - feature allows you to write a script which will test the X509 name on a - certificate and decide whether or not it should be accepted. For a - simple perl script which will test the common name field on the - certificate, see the file ``verify-cn`` in the OpenVPN distribution. - - See the `Environmental Variables`_ section below for additional - parameters passed as environmental variables. - ---tls-export-cert directory - Store the certificates the clients uses upon connection to this - directory. This will be done before ``--tls-verify`` is called. The - certificates will use a temporary name and will be deleted when the - tls-verify script returns. The file name used for the certificate is - available via the peer\_cert environment variable. - ---x509-username-field args - Field in the X.509 certificate subject to be used as the username - (default :code:`CN`). - - Valid syntax: - :: - - x509-username-field [ext:]fieldname - - Typically, this option is specified with **fieldname** as - either of the following: - :: - - x509-username-field emailAddress - x509-username-field ext:subjectAltName - - The first example uses the value of the :code:`emailAddress` attribute - in the certificate's Subject field as the username. The second example - uses the :code:`ext:` prefix to signify that the X.509 extension - ``fieldname`` :code:`subjectAltName` be searched for an rfc822Name - (email) field to be used as the username. In cases where there are - multiple email addresses in :code:`ext:fieldname`, the last occurrence - is chosen. - - When this option is used, the ``--verify-x509-name`` option will match - against the chosen ``fieldname`` instead of the Common Name. - - Only the :code:`subjectAltName` and :code:`issuerAltName` X.509 - extensions are supported. - - **Please note:** This option has a feature which will convert an - all-lowercase ``fieldname`` to uppercase characters, e.g., - :code:`ou` -> :code:`OU`. A mixed-case ``fieldname`` or one having the - :code:`ext:` prefix will be left as-is. This automatic upcasing feature is - deprecated and will be removed in a future release. - ---verify-x509-name args - Accept connections only if a host's X.509 name is equal to **name.** The - remote host must also pass all other tests of verification. - - Valid syntax: - :: - - verify-x509 name type - - Which X.509 name is compared to ``name`` depends on the setting of type. - ``type`` can be :code:`subject` to match the complete subject DN - (default), :code:`name` to match a subject RDN or :code:`name-prefix` to - match a subject RDN prefix. Which RDN is verified as name depends on the - ``--x509-username-field`` option. But it defaults to the common name - (CN), e.g. a certificate with a subject DN - :: - - C=KG, ST=NA, L=Bishkek, CN=Server-1 - - would be matched by: - :: - - verify-x509-name 'C=KG, ST=NA, L=Bishkek, CN=Server-1' - verify-x509-name Server-1 name - verify-x509-name Server- name-prefix - - The last example is useful if you want a client to only accept - connections to :code:`Server-1`, :code:`Server-2`, etc. - - ``--verify-x509-name`` is a useful replacement for the ``--tls-verify`` - option to verify the remote host, because ``--verify-x509-name`` works - in a ``--chroot`` environment without any dependencies. - - Using a name prefix is a useful alternative to managing a CRL - (Certificate Revocation List) on the client, since it allows the client - to refuse all certificates except for those associated with designated - servers. - - *NOTE:* - Test against a name prefix only when you are using OpenVPN - with a custom CA certificate that is under your control. Never use - this option with type :code:`name-prefix` when your client - certificates are signed by a third party, such as a commercial - web CA. - ---x509-track attribute - Save peer X509 **attribute** value in environment for use by plugins and - management interface. Prepend a :code:`+` to ``attribute`` to save values - from full cert chain. Values will be encoded as - :code:`X509__=`. Multiple ``--x509-track`` - options can be defined to track multiple attributes. - ---remote-cert-ku key-usage - Require that peer certificate was signed with an explicit - ``key-usage``. - - If present in the certificate, the :code:`keyUsage` value is validated by - the TLS library during the TLS handshake. Specifying this option without - arguments requires this extension to be present (so the TLS library will - verify it). - - If ``key-usage`` is a list of usage bits, the :code:`keyUsage` field - must have *at least* the same bits set as the bits in *one of* the values - supplied in the ``key-usage`` list. - - The ``key-usage`` values in the list must be encoded in hex, e.g. - :: - - remote-cert-ku a0 - ---remote-cert-eku oid - Require that peer certificate was signed with an explicit *extended key - usage*. - - This is a useful security option for clients, to ensure that the host - they connect to is a designated server. - - The extended key usage should be encoded in *oid notation*, or *OpenSSL - symbolic representation*. - ---remote-cert-tls type - Require that peer certificate was signed with an explicit *key usage* - and *extended key usage* based on RFC3280 TLS rules. - - Valid syntaxes: - :: - - remote-cert-tls server - remote-cert-tls client - - This is a useful security option for clients, to ensure that the host - they connect to is a designated server. Or the other way around; for a - server to verify that only hosts with a client certificate can connect. - - The ``--remote-cert-tls client`` option is equivalent to - :: - - remote-cert-ku - remote-cert-eku "TLS Web Client Authentication" - - The ``--remote-cert-tls server`` option is equivalent to - :: - - remote-cert-ku - remote-cert-eku "TLS Web Server Authentication" - - This is an important security precaution to protect against a - man-in-the-middle attack where an authorized client attempts to connect - to another client by impersonating the server. The attack is easily - prevented by having clients verify the server certificate using any one - of ``--remote-cert-tls``, ``--verify-x509-name``, or ``--tls-verify``. - ---crl-verify args - Check peer certificate against a Certificate Revocation List. - - Valid syntax: - :: - - crl-verify file/directory flag - - Examples: - :: - - crl-verify crl-file.pem - crl-verify /etc/openvpn/crls dir - - A CRL (certificate revocation list) is used when a particular key is - compromised but when the overall PKI is still intact. - - Suppose you had a PKI consisting of a CA, root certificate, and a number - of client certificates. Suppose a laptop computer containing a client - key and certificate was stolen. By adding the stolen certificate to the - CRL file, you could reject any connection which attempts to use it, - while preserving the overall integrity of the PKI. - - The only time when it would be necessary to rebuild the entire PKI from - scratch would be if the root certificate key itself was compromised. - - The option is not mandatory - if the relevant CRL is missing, OpenVPN - will log a warning in the logs - e.g. - :: - - VERIFY WARNING: depth=0, unable to get certificate CRL - - but the connection will be allowed. If the optional :code:`dir` flag - is specified, enable a different mode where the ``crl-verify`` is - pointed at a directory containing files named as revoked serial numbers - (the files may be empty, the contents are never read). If a client - requests a connection, where the client certificate serial number - (decimal string) is the name of a file present in the directory, it will - be rejected. - - *Note:* - As the crl file (or directory) is read every time a peer - connects, if you are dropping root privileges with - ``--user``, make sure that this user has sufficient - privileges to read the file. - - -SSL Library information ------------------------ - ---show-ciphers - (Standalone) Show all cipher algorithms to use with the ``--cipher`` - option. - ---show-digests - (Standalone) Show all message digest algorithms to use with the - ``--auth`` option. - ---show-tls - (Standalone) Show all TLS ciphers supported by the crypto library. - OpenVPN uses TLS to secure the control channel, over which the keys that - are used to protect the actual VPN traffic are exchanged. The TLS - ciphers will be sorted from highest preference (most secure) to lowest. - - Be aware that whether a cipher suite in this list can actually work - depends on the specific setup of both peers (e.g. both peers must - support the cipher, and an ECDSA cipher suite will not work if you are - using an RSA certificate, etc.). - ---show-engines - (Standalone) Show currently available hardware-based crypto acceleration - engines supported by the OpenSSL library. - ---show-curves - (Standalone) Show all available elliptic curves to use with the - ``--ecdh-curve`` option. - - -Generating key material ------------------------ - ---genkey args - (Standalone) Generate a key to be used of the type keytype. if keyfile - is left out or empty the key will be output on stdout. See the following - sections for the different keytypes. - - Valid syntax: - :: - - --genkey keytype keyfile - - Valid keytype arguments are: - - :code:`secret` Standard OpenVPN shared secret keys - - :code:`tls-crypt` Alias for :code:`secret` - - :code:`tls-auth` Alias for :code:`secret` - - :code:`auth-token` Key used for ``--auth-gen-token-key`` - - :code:`tls-crypt-v2-server` TLS Crypt v2 server key - - :code:`tls-crypt-v2-client` TLS Crypt v2 client key - - - Examples: - :: - - $ openvpn --genkey secret shared.key - $ openvpn --genkey tls-crypt shared.key - $ openvpn --genkey tls-auth shared.key - $ openvpn --genkey tls-crypt-v2-server v2crypt-server.key - $ openvpn --tls-crypt-v2 v2crypt-server.key --genkey tls-crypt-v2-client v2crypt-client-1.key - - * Generating *Shared Secret Keys* - Generate a shared secret, for use with the ``--secret``, ``--tls-auth`` - or ``--tls-crypt`` options. - - Syntax: - :: - - $ openvpn --genkey secret|tls-crypt|tls-auth keyfile - - The key is saved in ``keyfile``. All three variants (``--secret``, - ``tls-crypt`` and ``tls-auth``) generate the same type of key. The - aliases are added for convenience. - - If using this for ``--secret``, this file must be shared with the peer - over a pre-existing secure channel such as ``scp``\(1). - - * Generating *TLS Crypt v2 Server key* - Generate a ``--tls-crypt-v2`` key tp be used by an OpenVPN server. - The key is stored in ``keyfile``. - - Syntax: - :: - - --genkey tls-crypt-v2-server keyfile - - * Generating *TLS Crypt v2 Client key* - Generate a --tls-crypt-v2 key to be used by OpenVPN clients. The - key is stored in ``keyfile``. - - Syntax - :: - - --genkey tls-crypt-v2-client keyfile [metadata] - - If supplied, include the supplied ``metadata`` in the wrapped client - key. This metadata must be supplied in base64-encoded form. The - metadata must be at most 735 bytes long (980 bytes in base64). - - If no metadata is supplied, OpenVPN will use a 64-bit unix timestamp - representing the current time in UTC, encoded in network order, as - metadata for the generated key. - - A tls-crypt-v2 client key is wrapped using a server key. To generate a - client key, the user must therefore supply the server key using the - ``--tls-crypt-v2`` option. - - Servers can use ``--tls-crypt-v2-verify`` to specify a metadata - verification command. - - * Generate *Authentication Token key* - Generate a new secret that can be used with **--auth-gen-token-secret** - - Syntax: - :: - - --genkey auth-token [keyfile] - - *Note:* - This file should be kept secret to the server as anyone that - access to this file will be to generate auth tokens that the OpenVPN - server will accept as valid. - - -TUN/TAP persistent tunnel config mode -------------------------------------- - -Available with Linux 2.4.7+. These options comprise a standalone mode of -OpenVPN which can be used to create and delete persistent tunnels. - ---mktun - (Standalone) Create a persistent tunnel on platforms which support them - such as Linux. Normally TUN/TAP tunnels exist only for the period of - time that an application has them open. This option takes advantage of - the TUN/TAP driver's ability to build persistent tunnels that live - through multiple instantiations of OpenVPN and die only when they are - deleted or the machine is rebooted. - - One of the advantages of persistent tunnels is that they eliminate the - need for separate ``--up`` and ``--down`` scripts to run the appropriate - ``ifconfig``\(8) and ``route``\(8) commands. These commands can be - placed in the the same shell script which starts or terminates an - OpenVPN session. - - Another advantage is that open connections through the TUN/TAP-based - tunnel will not be reset if the OpenVPN peer restarts. This can be - useful to provide uninterrupted connectivity through the tunnel in the - event of a DHCP reset of the peer's public IP address (see the - ``--ipchange`` option above). - - One disadvantage of persistent tunnels is that it is harder to - automatically configure their MTU value (see ``--link-mtu`` and - ``--tun-mtu`` above). - - On some platforms such as Windows, TAP-Win32 tunnels are persistent by - default. - ---rmtun - (Standalone) Remove a persistent tunnel. - ---dev name - Designate the TUN/TAP device name to use - - Valid syntaxes: - :: - - dev tun2 - dev tap4 - dev ovpn - - When the device name starts with :code:`tun` or :code:`tap`, the device - type is extracted automatically. Otherwise the ``--dev-type`` option - needs to be added as well. - ---user user - Optional user to be owner of this tunnel. - ---group group - Optional group to be owner of this tunnel. - - -Windows-Specific Options -------------------------- - ---win-sys path - Set the Windows system directory pathname to use when looking for system - executables such as ``route.exe`` and ``netsh.exe``. By default, if this - directive is not specified, OpenVPN will use the SystemRoot environment - variable. - - This option have changed behaviour in OpenVPN 2.3. Earlier you had to - define ``--win-sys env`` to use the SystemRoot environment variable, - otherwise it defaulted to :code:`C:\\WINDOWS`. It is not needed to use - the ``env`` keyword any more, and it will just be ignored. A warning is - logged when this is found in the configuration file. - ---ip-win32 method - When using ``--ifconfig`` on Windows, set the TAP-Win32 adapter IP - address and netmask using ``method``. Don't use this option unless you - are also using ``--ifconfig``. - - :code:`manual` - Don't set the IP address or netmask automatically. Instead - output a message to the console telling the user to configure the - adapter manually and indicating the IP/netmask which OpenVPN - expects the adapter to be set to. - - :code:`dynamic [offset] [lease-time]` - Automatically set the IP address and netmask by replying to DHCP - query messages generated by the kernel. This mode is probably the - "cleanest" solution for setting the TCP/IP properties since it - uses the well-known DHCP protocol. There are, however, two - prerequisites for using this mode: - - (1) The TCP/IP properties for the TAP-Win32 adapter must be set - to "Obtain an IP address automatically", and - - (2) OpenVPN needs to claim an IP address in the subnet for use - as the virtual DHCP server address. - - By default in ``--dev tap`` mode, OpenVPN will take the normally - unused first address in the subnet. For example, if your subnet is - :code:`192.168.4.0 netmask 255.255.255.0`, then OpenVPN will take - the IP address :code:`192.168.4.0` to use as the virtual DHCP - server address. In ``--dev tun`` mode, OpenVPN will cause the DHCP - server to masquerade as if it were coming from the remote endpoint. - - The optional offset parameter is an integer which is > :code:`-256` - and < :code:`256` and which defaults to -1. If offset is positive, - the DHCP server will masquerade as the IP address at network - address + offset. If offset is negative, the DHCP server will - masquerade as the IP address at broadcast address + offset. - - The Windows :code:`ipconfig /all` command can be used to show what - Windows thinks the DHCP server address is. OpenVPN will "claim" - this address, so make sure to use a free address. Having said that, - different OpenVPN instantiations, including different ends of - the same connection, can share the same virtual DHCP server - address. - - The ``lease-time`` parameter controls the lease time of the DHCP - assignment given to the TAP-Win32 adapter, and is denoted in - seconds. Normally a very long lease time is preferred because it - prevents routes involving the TAP-Win32 adapter from being lost - when the system goes to sleep. The default lease time is one year. - - :code:`netsh` - Automatically set the IP address and netmask using the Windows - command-line "netsh" command. This method appears to work correctly - on Windows XP but not Windows 2000. - - :code:`ipapi` - Automatically set the IP address and netmask using the Windows IP - Helper API. This approach does not have ideal semantics, though - testing has indicated that it works okay in practice. If you use - this option, it is best to leave the TCP/IP properties for the - TAP-Win32 adapter in their default state, i.e. "Obtain an IP - address automatically." - - :code:`adaptive` (Default) - Try :code:`dynamic` method initially and fail over to :code:`netsh` - if the DHCP negotiation with the TAP-Win32 adapter does not succeed - in 20 seconds. Such failures have been known to occur when certain - third-party firewall packages installed on the client machine block - the DHCP negotiation used by the TAP-Win32 adapter. Note that if - the :code:`netsh` failover occurs, the TAP-Win32 adapter TCP/IP - properties will be reset from DHCP to static, and this will cause - future OpenVPN startups using the :code:`adaptive` mode to use - :code:`netsh` immediately, rather than trying :code:`dynamic` first. - - To "unstick" the :code:`adaptive` mode from using :code:`netsh`, - run OpenVPN at least once using the :code:`dynamic` mode to restore - the TAP-Win32 adapter TCP/IP properties to a DHCP configuration. - ---route-method m - Which method ``m`` to use for adding routes on Windows? - - :code:`adaptive` (default) - Try IP helper API first. If that fails, fall back to the route.exe - shell command. - - :code:`ipapi` - Use IP helper API. - - :code:`exe` - Call the route.exe shell command. - ---dhcp-option args - Set extended TAP-Win32 TCP/IP properties, must be used with - :code:`--ip-win32 dynamic` or :code:`--ip-win32 adaptive`. - - Valid syntax: - :: - - dhcp-options type [parm] - - This option can be used to set additional TCP/IP properties on the - TAP-Win32 adapter, and is particularly useful for configuring an OpenVPN - client to access a Samba server across the VPN. - - :code:`DOMAIN` ``name`` - Set Connection-specific DNS Suffix to :code:`name`. - - :code:`DNS` ``address`` - Set primary domain name server IPv4 or IPv6 address. - Repeat this option to set secondary DNS server addresses. - - Note: DNS IPv6 servers are currently set using netsh (the existing - DHCP code can only do IPv4 DHCP, and that protocol only permits - IPv4 addresses anywhere). The option will be put into the - environment, so an ``--up`` script could act upon it if needed. - - :code:`WINS` ``address`` - Set primary WINS server address (NetBIOS over TCP/IP Name Server). - Repeat this option to set secondary WINS server addresses. - - :code:`NBDD` ``address`` - Set primary NBDD server address (NetBIOS over TCP/IP Datagram - Distribution Server). Repeat this option to set secondary NBDD - server addresses. - - :code:`NTP` ``address`` - Set primary NTP server address (Network Time Protocol). - Repeat this option to set secondary NTP server addresses. - - :code:`NBT` ``type`` - Set NetBIOS over TCP/IP Node type. Possible options: - - :code:`1` - b-node (broadcasts) - - :code:`2` - p-node (point-to-point name queries to a WINS server) - - :code:`4` - m-node (broadcast then query name server) - - :code:`8` - h-node (query name server, then broadcast). - - :code:`NBS` ``scope-id`` - Set NetBIOS over TCP/IP Scope. A NetBIOS Scope ID provides an - extended naming service for the NetBIOS over TCP/IP (Known as NBT) - module. The primary purpose of a NetBIOS scope ID is to isolate - NetBIOS traffic on a single network to only those nodes with the - same NetBIOS scope ID. The NetBIOS scope ID is a character string - that is appended to the NetBIOS name. The NetBIOS scope ID on two - hosts must match, or the two hosts will not be able to communicate. - The NetBIOS Scope ID also allows computers to use the same computer - name, as they have different scope IDs. The Scope ID becomes a part - of the NetBIOS name, making the name unique. (This description of - NetBIOS scopes courtesy of NeonSurge@abyss.com) - - :code:`DISABLE-NBT` - Disable Netbios-over-TCP/IP. - - Note that if ``--dhcp-option`` is pushed via ``--push`` to a non-windows - client, the option will be saved in the client's environment before the - up script is called, under the name "foreign\_option\_{n}". - ---tap-sleep n - Cause OpenVPN to sleep for ``n`` seconds immediately after the TAP-Win32 - adapter state is set to "connected". - - This option is intended to be used to troubleshoot problems with the - ``--ifconfig`` and ``--ip-win32`` options, and is used to give the - TAP-Win32 adapter time to come up before Windows IP Helper API - operations are applied to it. - ---show-net-up - Output OpenVPN's view of the system routing table and network adapter - list to the syslog or log file after the TUN/TAP adapter has been - brought up and any routes have been added. - ---block-outside-dns - Block DNS servers on other network adapters to prevent DNS leaks. This - option prevents any application from accessing TCP or UDP port 53 except - one inside the tunnel. It uses Windows Filtering Platform (WFP) and - works on Windows Vista or later. - - This option is considered unknown on non-Windows platforms and - unsupported on Windows XP, resulting in fatal error. You may want to use - ``--setenv opt`` or ``--ignore-unknown-option`` (not suitable for - Windows XP) to ignore said error. Note that pushing unknown options from - server does not trigger fatal errors. - ---windows-driver drv - Specifies which tun driver to use. Values are :code:`tap-windows6` - (default) and :code:`wintun`. This is Windows-only option. - :code:`wintun`" requires ``--dev tun`` and the OpenVPN process to run - elevated, or be invoked using the Interactive Service. - ---dhcp-renew - Ask Windows to renew the TAP adapter lease on startup. This option is - normally unnecessary, as Windows automatically triggers a DHCP - renegotiation on the TAP adapter when it comes up, however if you set - the TAP-Win32 adapter Media Status property to "Always Connected", you - may need this flag. - ---dhcp-release - Ask Windows to release the TAP adapter lease on shutdown. This option - has no effect now, as it is enabled by default starting with - OpenVPN 2.4.1. - ---register-dns - Run :code:`ipconfig /flushdns` and :code:`ipconfig /registerdns` on - connection initiation. This is known to kick Windows into recognizing - pushed DNS servers. - ---pause-exit - Put up a "press any key to continue" message on the console prior to - OpenVPN program exit. This option is automatically used by the Windows - explorer when OpenVPN is run on a configuration file using the - right-click explorer menu. - ---service args - Should be used when OpenVPN is being automatically executed by another - program in such a context that no interaction with the user via display - or keyboard is possible. - - Valid syntax: - :: - - service exit-event [0|1] - - In general, end-users should never need to explicitly use this option, - as it is automatically added by the OpenVPN service wrapper when a given - OpenVPN configuration is being run as a service. - - ``exit-event`` is the name of a Windows global event object, and OpenVPN - will continuously monitor the state of this event object and exit when - it becomes signaled. - - The second parameter indicates the initial state of ``exit-event`` and - normally defaults to 0. - - Multiple OpenVPN processes can be simultaneously executed with the same - ``exit-event`` parameter. In any case, the controlling process can - signal ``exit-event``, causing all such OpenVPN processes to exit. - - When executing an OpenVPN process using the ``--service`` directive, - OpenVPN will probably not have a console window to output status/error - messages, therefore it is useful to use ``--log`` or ``--log-append`` to - write these messages to a file. - ---show-adapters - (Standalone) Show available TAP-Win32 adapters which can be selected - using the ``--dev-node`` option. On non-Windows systems, the - ``ifconfig``\(8) command provides similar functionality. - ---allow-nonadmin TAP-adapter - (Standalone) Set ``TAP-adapter`` to allow access from non-administrative - accounts. If ``TAP-adapter`` is omitted, all TAP adapters on the system - will be configured to allow non-admin access. The non-admin access - setting will only persist for the length of time that the TAP-Win32 - device object and driver remain loaded, and will need to be re-enabled - after a reboot, or if the driver is unloaded and reloaded. This - directive can only be used by an administrator. - ---show-valid-subnets - (Standalone) Show valid subnets for ``--dev tun`` emulation. Since the - TAP-Win32 driver exports an ethernet interface to Windows, and since TUN - devices are point-to-point in nature, it is necessary for the TAP-Win32 - driver to impose certain constraints on TUN endpoint address selection. - - Namely, the point-to-point endpoints used in TUN device emulation must - be the middle two addresses of a /30 subnet (netmask 255.255.255.252). - ---show-net - (Standalone) Show OpenVPN's view of the system routing table and network - adapter list. - - -PKCS#11 Standalone Options --------------------------- - ---show-pkcs11-ids args - (Standalone) Show PKCS#11 token object list. - - Valid syntax: - :: - - show-pkcs11 [provider] [cert_private] - - Specify ``cert_private`` as :code:`1` if certificates are stored as - private objects. - - If *p11-kit* is present on the system, the ``provider`` argument is - optional; if omitted the default :code:`p11-kit-proxy.so` module will be - queried. - - ``--verb`` option can be used BEFORE this option to produce debugging - information. - - -Standalone Debug Options ------------------------- - ---show-gateway args - (Standalone) Show current IPv4 and IPv6 default gateway and interface - towards the gateway (if the protocol in question is enabled). - - Valid syntax: - :: - - --show-gateway - --show-gateway IPv6-target - - If an IPv6 target address is passed as argument, the IPv6 route for this - host is reported. - - -IPv6 Related Options --------------------- - -The following options exist to support IPv6 tunneling in peer-to-peer -and client-server mode. All options are modeled after their IPv4 -counterparts, so more detailed explanations given there apply here as -well (except for **--topology** , which has no effect on IPv6). - ---ifconfig-ipv6 args - Configure an IPv6 address on the *tun* device. - - Valid syntax: - :: - - ifconfig-ipv6 ipv6addr/bits [ipv6remote] - - The ``ipv6addr/bits`` argument is the IPv6 address to use. The - second parameter is used as route target for ``--route-ipv6`` if no - gateway is specified. - ---route-ipv6 args - Setup IPv6 routing in the system to send the specified IPv6 network into - OpenVPN's *tun*. - - Valid syntax: - :: - - route-ipv6 ipv6addr/bits [gateway] [metric] - - The gateway parameter is only used for IPv6 routes across *tap* devices, - and if missing, the ``ipv6remote`` field from ``--ifconfig-ipv6`` or - ``--route-ipv6-gateway`` is used. - ---route-ipv6-gateway gw - Specify a default gateway ``gw`` for use with ``--route-ipv6``. - ---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 - - This is only accepted if ``--mode server`` or ``--server`` is set. - Pushing of the ``--tun-ipv6`` directive is done for older clients which - require an explicit ``--tun-ipv6`` in their configuration. - ---ifconfig-ipv6-pool args - Specify an IPv6 address pool for dynamic assignment to clients. - - Valid args: - :: - - ifconfig-ipv6-pool ipv6addr/bits - - The pool starts at ``ipv6addr`` and matches the offset determined from - the start of the IPv4 pool. - ---ifconfig-ipv6-push args - for ``--client-config-dir`` per-client static IPv6 interface - configuration, see ``--client-config-dir`` and ``--ifconfig-push`` for - more details. - - Valid syntax: - :: - - ifconfig-ipv6-push ipv6addr/bits ipv6remote - ---iroute-ipv6 args - for ``--client-config-dir`` per-client static IPv6 route configuration, - see ``--iroute`` for more details how to setup and use this, and how - ``--iroute`` and ``--route`` interact. - - Valid syntax: - :: - - iroute-ipv6 ipv6addr/bits - - -.. include:: unsupported-options.rst - -SCRIPTING AND ENVIRONMENTAL VARIABLES -===================================== - -OpenVPN exports a series of environmental variables for use by -user-defined scripts. - - -Script Order of Execution -------------------------- - ---up - Executed after TCP/UDP socket bind and TUN/TAP open. - ---tls-verify - Executed when we have a still untrusted remote peer. - ---ipchange - Executed after connection authentication, or remote IP address change. - ---client-connect - Executed in **--mode server** mode immediately after client - authentication. - ---route-up - Executed after connection authentication, either immediately after, or - some number of seconds after as defined by the **--route-delay** option. - ---route-pre-down - Executed right before the routes are removed. - ---client-disconnect - Executed in ``--mode server`` mode on client instance shutdown. - ---down - Executed after TCP/UDP and TUN/TAP close. - ---learn-address - Executed in ``--mode server`` mode whenever an IPv4 address/route or MAC - address is added to OpenVPN's internal routing table. - ---auth-user-pass-verify - Executed in ``--mode server`` mode on new client connections, when the - client is still untrusted. - - -String Types and Remapping --------------------------- - -In certain cases, OpenVPN will perform remapping of characters in -strings. Essentially, any characters outside the set of permitted -characters for each string type will be converted to underbar ('\_'). - -*Q: Why is string remapping necessary?* - It's an important security feature to prevent the malicious - coding of strings from untrusted sources to be passed as parameters to - scripts, saved in the environment, used as a common name, translated to - a filename, etc. - -*Q: Can string remapping be disabled?* - Yes, by using the ``--no-name-remapping`` option, however this - should be considered an advanced option. - -Here is a brief rundown of OpenVPN's current string types and the -permitted character class for each string: - -*X509 Names* - Alphanumeric, underbar ('\_'), dash ('-'), dot ('.'), at - ('@'), colon (':'), slash ('/'), and equal ('='). Alphanumeric is - defined as a character which will cause the C library isalnum() function - to return true. - -*Common Names* - Alphanumeric, underbar ('\_'), dash ('-'), dot ('.'), and at ('@'). - -*--auth-user-pass username* - Same as Common Name, with one exception: - starting with OpenVPN 2.0.1, the username is passed to the - OPENVPN\_PLUGIN\_AUTH\_USER\_PASS\_VERIFY plugin in its raw form, - without string remapping. - -*--auth-user-pass password* - Any "printable" character except CR or LF. Printable is defined to be - a character which will cause the C library isprint() function to - return true. - -*--client-config-dir filename as derived from common name or`username* - Alphanumeric, underbar ('\_'), dash ('-'), and dot ('.') except for "." - or ".." as standalone strings. As of v2.0.1-rc6, the at ('@') character - has been added as well for compatibility with the common name character - class. - -*Environmental variable names* - Alphanumeric or underbar ('\_'). - -*Environmental variable values* - Any printable character. - -For all cases, characters in a string which are not members of the legal -character class for that string type will be remapped to underbar -('\_').   - - -Environmental Variables ------------------------ - -Once set, a variable is persisted indefinitely until it is reset by a -new value or a restart, - -As of OpenVPN 2.0-beta12, in server mode, environmental variables set by -OpenVPN are scoped according to the client objects they are associated -with, so there should not be any issues with scripts having access to -stale, previously set variables which refer to different client -instances. - -:code:`bytes_received` - Total number of bytes received from client during VPN session. Set prior - to execution of the ``--client-disconnect`` script. - -:code:`bytes_sent` - Total number of bytes sent to client during VPN session. Set prior to - execution of the ``--client-disconnect`` script. - -:code:`common_name` - The X509 common name of an authenticated client. Set prior to execution - of ``--client-connect``, ``--client-disconnect`` and - ``--auth-user-pass-verify`` scripts. - -:code:`config` - Name of first ``--config`` file. Set on program initiation and reset on - SIGHUP. - -:code:`daemon` - Set to "1" if the ``--daemon`` directive is specified, or "0" otherwise. - Set on program initiation and reset on SIGHUP. - -:code:`daemon_log_redirect` - Set to "1" if the ``--log`` or ``--log-append`` directives are - specified, or "0" otherwise. Set on program initiation and reset on - SIGHUP. - -:code:`dev` - The actual name of the TUN/TAP device, including a unit number if it - exists. Set prior to ``--up`` or ``--down`` script execution. - -:code:`dev_idx` - On Windows, the device index of the TUN/TAP adapter (to be used in - netsh.exe calls which sometimes just do not work right with interface - names). Set prior to ``--up`` or ``--down`` script execution. - -:code:`foreign_option_{n}` - An option pushed via ``--push`` to a client which does not natively - support it, such as ``--dhcp-option`` on a non-Windows system, will be - recorded to this environmental variable sequence prior to ``--up`` - script execution. - -:code:`ifconfig_broadcast` - The broadcast address for the virtual ethernet segment which is derived - from the ``--ifconfig`` option when ``--dev tap`` is used. Set prior to - OpenVPN calling the :code:`ifconfig` or :code:`netsh` (windows version - of ifconfig) commands which normally occurs prior to ``--up`` script - execution. - -:code:`ifconfig_ipv6_local` - The local VPN endpoint IPv6 address specified in the - ``--ifconfig-ipv6`` option (first parameter). Set prior to OpenVPN - calling the :code:`ifconfig` or code:`netsh` (windows version of - ifconfig) commands which normally occurs prior to ``--up`` script - execution. - -:code:`ifconfig_ipv6_netbits` - The prefix length of the IPv6 network on the VPN interface. Derived - from the /nnn parameter of the IPv6 address in the ``--ifconfig-ipv6`` - option (first parameter). Set prior to OpenVPN calling the - :code:`ifconfig` or :code:`netsh` (windows version of ifconfig) - commands which normally occurs prior to ``--up`` script execution. - -:code:`ifconfig_ipv6_remote` - The remote VPN endpoint IPv6 address specified in the - ``--ifconfig-ipv6`` option (second parameter). Set prior to OpenVPN - calling the :code:`ifconfig` or :code:`netsh` (windows version of - ifconfig) commands which normally occurs prior to ``--up`` script - execution. - -:code:`ifconfig_local` - The local VPN endpoint IP address specified in the ``--ifconfig`` - option (first parameter). Set prior to OpenVPN calling the - :code:`ifconfig` or :code:`netsh` (windows version of ifconfig) - commands which normally occurs prior to ``--up`` script execution. - -:code:`ifconfig_remote` - The remote VPN endpoint IP address specified in the ``--ifconfig`` - option (second parameter) when ``--dev tun`` is used. Set prior to - OpenVPN calling the :code:`ifconfig` or :code:`netsh` (windows version - of ifconfig) commands which normally occurs prior to ``--up`` script - execution. - -:code:`ifconfig_netmask` - The subnet mask of the virtual ethernet segment that is specified as - the second parameter to ``--ifconfig`` when ``--dev tap`` is being - used. Set prior to OpenVPN calling the :code:`ifconfig` or - :code:`netsh` (windows version of ifconfig) commands which normally - occurs prior to ``--up`` script execution. - -:code:`ifconfig_pool_local_ip` - The local virtual IP address for the TUN/TAP tunnel taken from an - ``--ifconfig-push`` directive if specified, or otherwise from the - ifconfig pool (controlled by the ``--ifconfig-pool`` config file - directive). Only set for ``--dev tun`` tunnels. This option is set on - the server prior to execution of the ``--client-connect`` and - ``--client-disconnect`` scripts. - -:code:`ifconfig_pool_netmask` - The virtual IP netmask for the TUN/TAP tunnel taken from an - ``--ifconfig-push`` directive if specified, or otherwise from the - ifconfig pool (controlled by the ``--ifconfig-pool`` config file - directive). Only set for ``--dev tap`` tunnels. This option is set on - the server prior to execution of the ``--client-connect`` and - ``--client-disconnect`` scripts. - -:code:`ifconfig_pool_remote_ip` - The remote virtual IP address for the TUN/TAP tunnel taken from an - ``--ifconfig-push`` directive if specified, or otherwise from the - ifconfig pool (controlled by the ``--ifconfig-pool`` config file - directive). This option is set on the server prior to execution of the - ``--client-connect`` and ``--client-disconnect`` scripts. - -:code:`link_mtu` - The maximum packet size (not including the IP header) of tunnel data in - UDP tunnel transport mode. Set prior to ``--up`` or ``--down`` script - execution. - -:code:`local` - The ``--local`` parameter. Set on program initiation and reset on - SIGHUP. - -:code:`local_port` - The local port number or name, specified by ``--port`` or ``--lport``. - Set on program initiation and reset on SIGHUP. - -:code:`password` - The password provided by a connecting client. Set prior to - ``--auth-user-pass-verify`` script execution only when the ``via-env`` - modifier is specified, and deleted from the environment after the script - returns. - -:code:`proto` - The ``--proto`` parameter. Set on program initiation and reset on - SIGHUP. - -:code:`remote_{n}` - The ``--remote`` parameter. Set on program initiation and reset on - SIGHUP. - -:code:`remote_port_{n}` - The remote port number, specified by ``--port`` or ``--rport``. Set on - program initiation and reset on SIGHUP. - -:code:`route_net_gateway` - The pre-existing default IP gateway in the system routing table. Set - prior to ``--up`` script execution. - -:code:`route_vpn_gateway` - The default gateway used by ``--route`` options, as specified in either - the ``--route-gateway`` option or the second parameter to - ``--ifconfig`` when ``--dev tun`` is specified. Set prior to ``--up`` - script execution. - -:code:`route_{parm}_{n}` - A set of variables which define each route to be added, and are set - prior to ``--up`` script execution. - - ``parm`` will be one of :code:`network`, :code:`netmask"`, - :code:`gateway`, or :code:`metric`. - - ``n`` is the OpenVPN route number, starting from 1. - - If the network or gateway are resolvable DNS names, their IP address - translations will be recorded rather than their names as denoted on the - command line or configuration file. - -:code:`route_ipv6_{parm}_{n}` - A set of variables which define each IPv6 route to be added, and are - set prior to **--up** script execution. - - ``parm`` will be one of :code:`network` 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). - - ``n`` is the OpenVPN route number, starting from 1. - - If the network or gateway are resolvable DNS names, their IP address - translations will be recorded rather than their names as denoted on the - command line or configuration file. - -:code:`peer_cert` - Temporary file name containing the client certificate upon connection. - Useful in conjunction with ``--tls-verify``. - -:code:`script_context` - Set to "init" or "restart" prior to up/down script execution. For more - information, see documentation for ``--up``. - -:code:`script_type` - Prior to execution of any script, this variable is set to the type of - script being run. It can be one of the following: :code:`up`, - :code:`down`, :code:`ipchange`, :code:`route-up`, :code:`tls-verify`, - :code:`auth-user-pass-verify`, :code:`client-connect`, - :code:`client-disconnect` or :code:`learn-address`. Set prior to - execution of any script. - -:code:`signal` - The reason for exit or restart. Can be one of :code:`sigusr1`, - :code:`sighup`, :code:`sigterm`, :code:`sigint`, :code:`inactive` - (controlled by ``--inactive`` option), :code:`ping-exit` (controlled - by ``--ping-exit`` option), :code:`ping-restart` (controlled by - ``--ping-restart`` option), :code:`connection-reset` (triggered on TCP - connection reset), :code:`error` or :code:`unknown` (unknown signal). - This variable is set just prior to down script execution. - -:code:`time_ascii` - Client connection timestamp, formatted as a human-readable time string. - Set prior to execution of the ``--client-connect`` script. - -:code:`time_duration` - The duration (in seconds) of the client session which is now - disconnecting. Set prior to execution of the ``--client-disconnect`` - script. - -:code:`time_unix` - Client connection timestamp, formatted as a unix integer date/time - value. Set prior to execution of the ``--client-connect`` script. - -:code:`tls_digest_{n}` / :code:`tls_digest_sha256_{n}` - Contains the certificate SHA1 / SHA256 fingerprint, where ``n`` is the - verification level. Only set for TLS connections. Set prior to execution - of ``--tls-verify`` script. - -:code:`tls_id_{n}` - A series of certificate fields from the remote peer, where ``n`` is the - verification level. Only set for TLS connections. Set prior to execution - of ``--tls-verify`` script. - -:code:`tls_serial_{n}` - The serial number of the certificate from the remote peer, where ``n`` - is the verification level. Only set for TLS connections. Set prior to - execution of ``--tls-verify`` script. This is in the form of a decimal - string like "933971680", which is suitable for doing serial-based OCSP - queries (with OpenSSL, do not prepend "0x" to the string) If something - goes wrong while reading the value from the certificate it will be an - empty string, so your code should check that. See the - :code:`contrib/OCSP_check/OCSP_check.sh` script for an example. - -:code:`tls_serial_hex_{n}` - Like :code:`tls_serial_{n}`, but in hex form (e.g. - :code:`12:34:56:78:9A`). - -:code:`tun_mtu` - The MTU of the TUN/TAP device. Set prior to ``--up`` or ``--down`` - script execution. - -:code:`trusted_ip` / :code:`trusted_ip6`) - Actual IP address of connecting client or peer which has been - authenticated. Set prior to execution of ``--ipchange``, - ``--client-connect`` and ``--client-disconnect`` scripts. If using ipv6 - endpoints (udp6, tcp6), :code:`trusted_ip6` will be set instead. - -:code:`trusted_port` - Actual port number of connecting client or peer which has been - authenticated. Set prior to execution of ``--ipchange``, - ``--client-connect`` and ``--client-disconnect`` scripts. - -:code:`untrusted_ip` / :code:`untrusted_ip6` - Actual IP address of connecting client or peer which has not been - authenticated yet. Sometimes used to *nmap* the connecting host in a - ``--tls-verify`` script to ensure it is firewalled properly. Set prior - to execution of ``--tls-verify`` and ``--auth-user-pass-verify`` - scripts. If using ipv6 endpoints (udp6, tcp6), :code:`untrusted_ip6` - will be set instead. - -:code:`untrusted_port` - Actual port number of connecting client or peer which has not been - authenticated yet. Set prior to execution of ``--tls-verify`` and - ``--auth-user-pass-verify`` scripts. - -:code:`username` - The username provided by a connecting client. Set prior to - ``--auth-user-pass-verify`` script execution only when the - :code:`via-env` modifier is specified. - -:code:`X509_{n}_{subject_field}` - An X509 subject field from the remote peer certificate, where ``n`` is - the verification level. Only set for TLS connections. Set prior to - execution of ``--tls-verify`` script. This variable is similar to - :code:`tls_id_{n}` except the component X509 subject fields are broken - out, and no string remapping occurs on these field values (except for - remapping of control characters to ":code:`_`"). For example, the - following variables would be set on the OpenVPN server using the sample - client certificate in sample-keys (client.crt). Note that the - verification level is 0 for the client certificate and 1 for the CA - certificate. - - :: - - X509_0_emailAddress=me@myhost.mydomain - X509_0_CN=Test-Client - X509_0_O=OpenVPN-TEST - X509_0_ST=NA - X509_0_C=KG - X509_1_emailAddress=me@myhost.mydomain - X509_1_O=OpenVPN-TEST - X509_1_L=BISHKEK - X509_1_ST=NA - X509_1_C=KG - - - -CONNECTION PROFILES -=================== - -Client configuration files may contain multiple remote servers which -it will attempt to connect against. But there are some configuration -options which are related to specific ``--remote`` options. For these -use cases, connection profiles is the solution. - -By enacpulating the ``--remote`` option and related options within -```` and ````, these options are handled as a -group. - -An OpenVPN client will try each connection profile sequentially until it -achieves a successful connection. - -``--remote-random`` can be used to initially "scramble" the connection -list. - -Here is an example of connection profile usage: -:: - - client - dev tun - - - remote 198.19.34.56 1194 udp - - - - remote 198.19.34.56 443 tcp - - - - remote 198.19.34.56 443 tcp - http-proxy 192.168.0.8 8080 - - - - remote 198.19.36.99 443 tcp - http-proxy 192.168.0.8 8080 - - - persist-key - persist-tun - pkcs12 client.p12 - remote-cert-tls server - verb 3 - -First we try to connect to a server at 198.19.34.56:1194 using UDP. If -that fails, we then try to connect to 198.19.34.56:443 using TCP. If -that also fails, then try connecting through an HTTP proxy at -192.168.0.8:8080 to 198.19.34.56:443 using TCP. Finally, try to connect -through the same proxy to a server at 198.19.36.99:443 using TCP. - -The following OpenVPN options may be used inside of a ```` -block: - -``bind``, ``connect-retry``, ``connect-retry-max``, ``connect-timeout``, -``explicit-exit-notify``, ``float``, ``fragment``, ``http-proxy``, -``http-proxy-option``, ``key-direction``, ``link-mtu``, ``local``, -``lport``, ``mssfix``, ``mtu-disc``, ``nobind``, ``port``, ``proto``, -``remote``, ``rport``, ``socks-proxy``, ``tls-auth``, ``tls-crypt``, -``tun-mtu and``, ``tun-mtu-extra``. - -A defaulting mechanism exists for specifying options to apply to all -```` profiles. If any of the above options (with the -exception of ``remote`` ) appear outside of a ```` block, -but in a configuration file which has one or more ```` -blocks, the option setting will be used as a default for -```` blocks which follow it in the configuration file. - -For example, suppose the ``nobind`` option were placed in the sample -configuration file above, near the top of the file, before the first -```` block. The effect would be as if ``nobind`` were -declared in all ```` blocks below it. - - - -INLINE FILE SUPPORT -=================== - -OpenVPN allows including files in the main configuration for the ``--ca``, -``--cert``, ``--dh``, ``--extra-certs``, ``--key``, ``--pkcs12``, -``--secret``, ``--crl-verify``, ``--http-proxy-user-pass``, ``--tls-auth``, -``--auth-gen-token-secret``, ``--tls-crypt`` and ``--tls-crypt-v2`` -options. - -Each inline file started by the line ```` - -Here is an example of an inline file usage - -:: - - - -----BEGIN CERTIFICATE----- - [...] - -----END CERTIFICATE----- - - -When using the inline file feature with ``--pkcs12`` the inline file has -to be base64 encoded. Encoding of a .p12 file into base64 can be done -for example with OpenSSL by running :code:`openssl base64 -in input.p12` - - - -SIGNALS -======= - -:code:`SIGHUP` - Cause OpenVPN to close all TUN/TAP and network connections, restart, - re-read the configuration file (if any), and reopen TUN/TAP and network - connections. - -:code:`SIGUSR1` - Like :code:`SIGHUP``, except don't re-read configuration file, and - possibly don't close and reopen TUN/TAP device, re-read key files, - preserve local IP address/port, or preserve most recently authenticated - remote IP address/port based on ``--persist-tun``, ``--persist-key``, - ``--persist-local-ip`` and ``--persist-remote-ip`` options respectively - (see above). - - This signal may also be internally generated by a timeout condition, - governed by the ``--ping-restart`` option. - - This signal, when combined with ``--persist-remote-ip``, may be sent - when the underlying parameters of the host's network interface change - such as when the host is a DHCP client and is assigned a new IP address. - See ``--ipchange`` above for more information. - -:code:`SIGUSR2` - Causes OpenVPN to display its current statistics (to the syslog file if - ``--daemon`` is used, or stdout otherwise). - -:code:`SIGINT`, :code:`SIGTERM` - Causes OpenVPN to exit gracefully. - - - -TUN/TAP DRIVER SETUP -==================== - -If you are running Linux 2.4.7 or higher, you probably have the TUN/TAP -driver already installed. If so, there are still a few things you need -to do: - -Make device: :code:`mknod /dev/net/tun c 10 200` - -Load driver: :code:`modprobe tun**` - - - -EXAMPLES -======== - -Prior to running these examples, you should have OpenVPN installed on -two machines with network connectivity between them. If you have not yet -installed OpenVPN, consult the INSTALL file included in the OpenVPN -distribution. - - -TUN/TAP Setup: --------------- - -If you are using Linux 2.4 or higher, make the tun device node and load -the tun module: - -:: - - mknod /dev/net/tun c 10 200 - modprobe tun - -If you installed from RPM, the ``mknod`` step may be omitted, because -the RPM install does that for you. - -Only Linux 2.4 and newer are supported. - -For other platforms, consult the INSTALL file at -https://openvpn.net/community-resources/the-standard-install-file-included-in-the-source-distribution/ -for more information. - - -Firewall Setup: ---------------- - -If firewalls exist between the two machines, they should be set to -forward UDP port 1194 in both directions. If you do not have control -over the firewalls between the two machines, you may still be able to -use OpenVPN by adding ``--ping 15`` to each of the ``openvpn`` commands -used below in the examples (this will cause each peer to send out a UDP -ping to its remote peer once every 15 seconds which will cause many -stateful firewalls to forward packets in both directions without an -explicit firewall rule). - -If you are using a Linux iptables-based firewall, you may need to enter -the following command to allow incoming packets on the TUN device: - -:code:`iptables -A INPUT -i tun+ -j ACCEPT` - -See the firewalls section below for more information on configuring -firewalls for use with OpenVPN. - - -VPN Address Setup: ------------------- - -For purposes of our example, our two machines will be called -``bob.example.com`` and ``alice.example.com``. If you are constructing a -VPN over the internet, then replace ``bob.example.com`` and -``alice.example.com`` with the internet hostname or IP address that each -machine will use to contact the other over the internet. - -Now we will choose the tunnel endpoints. Tunnel endpoints are private IP -addresses that only have meaning in the context of the VPN. Each machine -will use the tunnel endpoint of the other machine to access it over the -VPN. In our example, the tunnel endpoint for bob.example.com will be -10.4.0.1 and for alice.example.com, 10.4.0.2. - -Once the VPN is established, you have essentially created a secure -alternate path between the two hosts which is addressed by using the -tunnel endpoints. You can control which network traffic passes between -the hosts (a) over the VPN or (b) independently of the VPN, by choosing -whether to use (a) the VPN endpoint address or (b) the public internet -address, to access the remote host. For example if you are on -bob.example.com and you wish to connect to ``alice.example.com`` via -``ssh`` without using the VPN (since **ssh** has its own built-in security) -you would use the command ``ssh alice.example.com``. However in the same -scenario, you could also use the command ``telnet 10.4.0.2`` to create a -telnet session with alice.example.com over the VPN, that would use the -VPN to secure the session rather than ``ssh``. - -You can use any address you wish for the tunnel endpoints but make sure -that they are private addresses (such as those that begin with 10 or -192.168) and that they are not part of any existing subnet on the -networks of either peer, unless you are bridging. If you use an address -that is part of your local subnet for either of the tunnel endpoints, -you will get a weird feedback loop. - - -Example 1: A simple tunnel without security -------------------------------------------- - -On bob: -:: - - openvpn --remote alice.example.com --dev tun1 \ - --ifconfig 10.4.0.1 10.4.0.2 --verb 9 - -On alice: -:: - - openvpn --remote bob.example.com --dev tun1 \ - --ifconfig 10.4.0.2 10.4.0.1 --verb 9 - -Now verify the tunnel is working by pinging across the tunnel. - -On bob: -:: - - ping 10.4.0.2 - -On alice: -:: - - ping 10.4.0.1 - -The ``--verb 9`` option will produce verbose output, similar to the -``tcpdump``\(8) program. Omit the ``--verb 9`` option to have OpenVPN run -quietly. - - -Example 2: A tunnel with static-key security (i.e. using a pre-shared secret) ------------------------------------------------------------------------------ - -First build a static key on bob. -:: - - openvpn --genkey --secret key - -This command will build a key file called ``key`` (in ascii format). Now -copy ``key`` to ``alice.example.com`` over a secure medium such as by using -the ``scp``\(1) program. - -On bob: -:: - - openvpn --remote alice.example.com --dev tun1 \ - --ifconfig 10.4.0.1 10.4.0.2 --verb 5 \ - --secret key - -On alice: -:: - - openvpn --remote bob.example.com --dev tun1 \ - --ifconfig 10.4.0.2 10.4.0.1 --verb 5 \ - --secret key - -Now verify the tunnel is working by pinging across the tunnel. - -On bob: -:: - - ping 10.4.0.2 - -On alice: -:: - - ping 10.4.0.1 - - -Example 3: A tunnel with full TLS-based security ------------------------------------------------- - -For this test, we will designate ``bob`` as the TLS client and ``alice`` -as the TLS server. - -*Note:* - The client or server designation only has - meaning for the TLS subsystem. It has no bearing on OpenVPN's - peer-to-peer, UDP-based communication model.* - -First, build a separate certificate/key pair for both bob and alice (see -above where ``--cert`` is discussed for more info). Then construct -Diffie Hellman parameters (see above where ``--dh`` is discussed for -more info). You can also use the included test files :code:`client.crt`, -:code:`client.key`, :code:`server.crt`, :code:`server.key` and -:code:`ca.crt`. The ``.crt`` files are certificates/public-keys, the -``.key`` files are private keys, and :code:`ca.crt` is a certification -authority who has signed both :code:`client.crt` and :code:`server.crt`. -For Diffie Hellman parameters you can use the included file -:code:`dh2048.pem`. - -*WARNING:* - All client, server, and certificate authority certificates - and keys included in the OpenVPN distribution are totally - insecure and should be used for testing only. - -On bob: -:: - - openvpn --remote alice.example.com --dev tun1 \ - --ifconfig 10.4.0.1 10.4.0.2 \ - --tls-client --ca ca.crt \ - --cert client.crt --key client.key \ - --reneg-sec 60 --verb 5 - -On alice: -:: - - openvpn --remote bob.example.com --dev tun1 \ - --ifconfig 10.4.0.2 10.4.0.1 \ - --tls-server --dh dh1024.pem --ca ca.crt \ - --cert server.crt --key server.key \ - --reneg-sec 60 --verb 5 - -Now verify the tunnel is working by pinging across the tunnel. - -On bob: -:: - - ping 10.4.0.2 - -On alice: -:: - - ping 10.4.0.1 - -Notice the ``--reneg-sec 60`` option we used above. That tells OpenVPN -to renegotiate the data channel keys every minute. Since we used -``--verb 5`` above, you will see status information on each new key -negotiation. - -For production operations, a key renegotiation interval of 60 seconds is -probably too frequent. Omit the ``--reneg-sec 60`` option to use -OpenVPN's default key renegotiation interval of one hour. - - -Routing: --------- - -Assuming you can ping across the tunnel, the next step is to route a -real subnet over the secure tunnel. Suppose that bob and alice have two -network interfaces each, one connected to the internet, and the other to -a private network. Our goal is to securely connect both private -networks. We will assume that bob's private subnet is *10.0.0.0/24* and -alice's is *10.0.1.0/24*. - -First, ensure that IP forwarding is enabled on both peers. On Linux, -enable routing: -:: - - echo 1 > /proc/sys/net/ipv4/ip_forward - -and enable TUN packet forwarding through the firewall: -:: - - iptables -A FORWARD -i tun+ -j ACCEPT - -On bob: -:: - - route add -net 10.0.1.0 netmask 255.255.255.0 gw 10.4.0.2 - -On alice: -:: - - route add -net 10.0.0.0 netmask 255.255.255.0 gw 10.4.0.1 - -Now any machine on the *10.0.0.0/24* subnet can access any machine on the -*10.0.1.0/24* subnet over the secure tunnel (or vice versa). - -In a production environment, you could put the route command(s) in a -script and execute with the ``--up`` option. - - -FIREWALLS -========= - -OpenVPN's usage of a single UDP port makes it fairly firewall-friendly. -You should add an entry to your firewall rules to allow incoming OpenVPN -packets. On Linux 2.4+: -:: - - iptables -A INPUT -p udp -s 1.2.3.4 --dport 1194 -j ACCEPT - -This will allow incoming packets on UDP port :code:`1194` (OpenVPN's -default UDP port) from an OpenVPN peer at :code:`1.2.3.4`. - -If you are using HMAC-based packet authentication (the default in any of -OpenVPN's secure modes), having the firewall filter on source address -can be considered optional, since HMAC packet authentication is a much -more secure method of verifying the authenticity of a packet source. In -that case: -:: - - iptables -A INPUT -p udp --dport 1194 -j ACCEPT - -would be adequate and would not render the host inflexible with respect -to its peer having a dynamic IP address. - -OpenVPN also works well on stateful firewalls. In some cases, you may -not need to add any static rules to the firewall list if you are using a -stateful firewall that knows how to track UDP connections. If you -specify ``--ping n``, OpenVPN will be guaranteed to send a packet to its -peer at least once every ``n`` seconds. If ``n`` is less than the -stateful firewall connection timeout, you can maintain an OpenVPN -connection indefinitely without explicit firewall rules. - -You should also add firewall rules to allow incoming IP traffic on TUN -or TAP devices such as: -:: - - iptables -A INPUT -i tun+ -j ACCEPT - -to allow input packets from tun devices, -:: - - iptables -A FORWARD -i tun+ -j ACCEPT - -to allow input packets from tun devices to be forwarded to other hosts -on the local network, -:: - - iptables -A INPUT -i tap+ -j ACCEPT - -to allow input packets from tap devices, and -:: - - iptables -A FORWARD -i tap+ -j ACCEPT - -to allow input packets from tap devices to be forwarded to other hosts -on the local network. - -These rules are secure if you use packet authentication, since no -incoming packets will arrive on a TUN or TAP virtual device unless they -first pass an HMAC authentication test.   - +.. include:: man-sections/generic-options.rst +.. include:: man-sections/log-options.rst +.. include:: man-sections/protocol-options.rst +.. include:: man-sections/client-options.rst +.. include:: man-sections/server-options.rst +.. include:: man-sections/encryption-options.rst +.. include:: man-sections/network-config.rst +.. include:: man-sections/script-options.rst +.. include:: man-sections/management-options.rst +.. include:: man-sections/plugin-options.rst +.. include:: man-sections/windows-options.rst +.. include:: man-sections/advanced-options.rst +.. include:: man-sections/unsupported-options.rst +.. include:: man-sections/connection-profiles.rst +.. include:: man-sections/inline-files.rst +.. include:: man-sections/signals.rst +.. include:: man-sections/examples.rst FAQ