Differences

This shows you the differences between two versions of the page.

--- openvpn:options [2020/04/20 09:33] – peter
+++ openvpn:options [2020/07/15 09:30] (current) – external edit 127.0.0.1
@@ Line 4: / Line 4: @@
 |allow-pull-fqdn|Allow client to pull DNS names from server (rather than being limited to IP address) for **--ifconfig**, **--route**, and **--route-gateway**.|
-|mssfix 1450|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 **1450**.|
+|comp-lzo [mode]|Use fast LZO compression -- may add up to 1 byte per packet for incompressible data.  **mode** may be "yes", "no", or "adaptive" (default).|
-|:::|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.|
+|:::|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 on/off/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.|
+|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.|
+|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.|
+|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 **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.|
@@ Line 11: / Line 28: @@
 |:::|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:|
+|:::|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**|
-|:::|**--tun-mtu 1500 --fragment 1300 --mssfix**|
+|persist-key|Don't re-read key files across SIGUSR1 or --ping-restart.|
+|:::|This option can be combined with **--user nobody** to allow restarts triggered by the **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 **SIGUSR1** resets, so they don't need to be re-read.|
+|persist-tun|Don't close and reopen TUN/TAP device or run up/down scripts across **SIGUSR1** or **--ping-restart** restarts.|
+|:::|**SIGUSR1** is a restart signal similar to **SIGHUP**, but which offers finer-grained control over reset options.|
+|rcvbuf size|Set the TCP/UDP socket receive buffer size. Defaults to operation system default.|
+|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:|
+|:::|**local** -- Add the local flag if both OpenVPN servers are directly connected via a common subnet, such as with wireless.  The local flag will cause step 1 above to be omitted.|
+|:::|**autolocal** -- Try to automatically determine whether to enable local flag above.|
+|:::|**def1** -- Use this flag to override the default gateway by using 0.0.0.0/1 and 128.0.0.0/1 rather than 0.0.0.0/0.  This has the benefit of overriding but not wiping out the original default gateway.|
+|:::|**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).|
+|:::|**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).|
+|:::|**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.|
 |remote-random|Used to initially "scramble" the connection list.|
 |:::|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.|
+|route-delay [n] [w]|Delay **n** seconds (default=0) after connection establishment, before adding routes.|
+|:::|If **n** is 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 (w=30 by default) for the TAP-Win32 adapter to come up before adding routes.|
 |route-gateway gw<nowiki>|</nowiki>'dhcp'|Specify a default gateway **gw** for use with **--route**.|
 |:::|If **dhcp** is specified as the parameter, the gateway address will be extracted from a DHCP negotiation with the OpenVPN server-side LAN.|
 |route network/IP [netmask] [gateway] [metric]|Add route to routing table after connection is established. Multiple routes can be specified. Routes will be automatically torn down in reverse order prior to TUN/TAP device close.|
 |:::|**netmask** default -- 255.255.255.255|
-|:::|**gateway** default -- taken from --route-gateway or the second parameter to --ifconfig when --dev tun is specified.|
+|:::|**gateway** default -- taken from **--route-gateway** or the second parameter to **--ifconfig** when **--dev tun** is specified.|
-|:::|**metric** default -- taken from --route-metric otherwise 0.|
+|:::|**metric** default -- taken from **--route-metric** otherwise 0.|
 |:::|The default can be specified by leaving an option blank or setting it to "default".|
 |:::|The **network** and **gateway** parameters can also be specified as a DNS or /etc/hosts file resolvable name, or as one of three special keywords:|
@@ Line 26: / Line 65: @@
 |:::|**net_gateway** -- The pre-existing IP default gateway, read from the routing table (not supported on all OSes).|
 |:::|**remote_host** -- The **--remote** address if OpenVPN is being run in client mode, and is undefined in server mode.|
+|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.|
+|sndbuf size|Set the TCP/UDP socket send buffer size. Defaults to operation system default.|
+|tun-mtu n|Take the TUN device MTU to be n and derive the link MTU from it (default=1500).  In most cases, you will probably want to leave this parameter set to its default value.|
+|:::|The MTU (Maximum Transmission Units) is the maximum datagram size in bytes that can be sent unfragmented over a particular network path.  OpenVPN requires that packets on the control or data channels be sent unfragmented.|
+|:::|MTU problems often manifest themselves as connections which hang during periods of active usage.|
+|:::|It's best to use the **--fragment** and/or **--mssfix** options to deal with MTU sizing issues.|
+|verb n|Set output verbosity to **n** (default=1).  Each level shows all info from the previous levels.  Level 3 is recommended if you want a good summary of what's happening without being swamped by output.|
+|:::|**0** -- No output except fatal errors.|
+|:::|**1 to 4** -- Normal usage range.|
+|:::|**5** -- Output **R** and **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.|
+|:::|**6 to 11** -- Debug info range (see errlevel.h for additional information on debug levels).|
+----
+===== Server Mode =====
+|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.|
 ----
+===== Client Mode =====
-|comp-lzo [mode]|Use fast LZO compression -- may add up to 1 byte per packet for incompressible data.  **mode** may be "yes", "no", or "adaptive" (default).|
+|client|A helper directive designed to simplify the configuration of OpenVPN's client mode. This directive is equivalent to:|
-|:::|In a server mode setup, it is possible to selectively turn compression on or off for individual clients.|
+|:::|**pull**|
-|:::|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 on/off/adaptive setting.|
+|:::|**tls-client**|
-|:::|Next in a **--client-config-dir** file, specify the compression setting for the client, for example:|
+|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.|
-|:::|**comp-lzo yes**|
+|:::|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.|
-|:::|**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.|
-|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.|
-|fragment 1300|
-|key-direction 1|
-|persist-key|Don't re-read key files across SIGUSR1 or --ping-restart.|
-|:::|This option can be combined with **--user nobody** to allow restarts triggered by the **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 **SIGUSR1** resets, so they don't need to be re-read.|
-|persist-tun|Don't close and reopen TUN/TAP device or run up/down scripts across **SIGUSR1** or **--ping-restart** restarts.|
+===== Data Channel Encryption Options =====
-|:::|**SIGUSR1** is a restart signal similar to **SIGHUP**, but which offers finer-grained control over reset options.|
-|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.|
+|key-direction 1|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).|
-|:::|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.|
-|rcvbuf 524288|Set the TCP/UDP socket receive buffer size. Defaults to operation system default.|
+----
-|remote-cert-tls server|
-|route-delay 2|
+===== TLS Mode Options =====
-|route-method exe|
-|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.|
+|auth-nocache|Don't cache **--askpass** or **--auth-user-pass** username/passwords in virtual memory.|
-|:::|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.|
+|:::|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.|
-|sndbuf 524288|Set the TCP/UDP socket send buffer size. Defaults to operation system default.|
+|:::|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.|
+|remote-cert-tls client<nowiki>|</nowiki>server|Require that peer certificate was signed with an explicit key usage and extended key usage based on RFC3280 TLS rules.|
+|:::|This is a useful security option for clients, to ensure that the host they connect to is a designated server.|
+|:::|The **--remote-cert-tls client** option is equivalent to **--remote-cert-ku 80 08 88 --remote-cert-eku "TLS Web Client Authentication"**|
+|:::|The key usage is digitalSignature and/or keyAgreement.|
+|:::|The **--remote-cert-tls server** option is equivalent to **--remote-cert-ku a0 88 --remote-cert-eku "TLS Web Server Authentication"**|
+|:::|The key usage is digitalSignature and ( keyEncipherment or keyAgreement ).|
+|:::|This is an important security precaution to protect against a man-in-the-middle attack where an authorized client attempts to connect to another client by impersonating the server.  The attack is easily prevented by having clients verify the server certificate using any one of **--remote-cert-tls**, **--verify-x509-name**, or **--tls-verify**.|
 |tls-client|Enable TLS and assume client role during TLS handshake.|
-|tun-mtu 1500|
+|verify-x509-name Server name-prefix|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.|
-|verb 3|Set output verbosity to n (default=1). Each level shows all info from the previous levels.  Level 3 is recommended if you want a good summary of what's happening without being swamped by output.|
+|:::|Which X.509 name is compared to **name** depends on the setting of type. **type** can be "subject" to match the complete subject DN (default), "name" to match a subject RDN or "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:|
-|:::|**0** -- No output except fatal errors.|
+|:::|**--verify-x509-name 'C=KG, ST=NA, L=Bishkek, CN=Server-1'** and **--verify-x509-name Server-1 name** or you could use **--verify-x509-name Server- name-prefix** if you want a client to only accept connections to "Server-1", "Server-2", etc.|
-|:::|**1 to 4** -- Normal usage range.|
+|:::|**--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.|
-|:::|**5** -- Output **R** and **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.|
+|:::|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.|
-|:::|**6 to 11** -- Debug info range (see errlevel.h for additional information on debug levels).|
+|:::|**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 "name-prefix" when your client certificates are signed by a third party, such as a commercial web CA.|
-|verify-x509-name Server name-prefix|
+----
+===== Windows-Specific Options =====
+|route-method m|Which method **m** to use for adding routes on Windows?|
+|:::|**adaptive** (default) -- Try IP helper API first. If that fails, fall back to the route.exe shell command.|
+|:::|**ipapi** -- Use IP helper API.|
+|:::|**exe** -- Call the route.exe shell command.|
+----