Changes between Version 14 and Version 15 of Openvpn23ManPage

Timestamp:

06/08/15 06:56:30 (9 years ago)

Author:

Samuli Seppänen

Comment:

Man-page update (OpenVPN 2.3.6 -> 2.3.7)

Openvpn23ManPage

@@ -277 +277 @@
 
 is a DNS name which resolves to multiple IP addresses,
-one will be randomly
-chosen, providing a sort of basic load-balancing and
-failover capability.
+the first address returned by the system getaddrinfo() function
+will be used (no DNS randomization inside OpenVPN 2.3.x, and
+it will not try multiple addresses).
 
 <DT><B>--remote-random-hostname</B>
@@ -789 +789 @@
 
 <DD>
-TCP/UDP port number for both local and remote.  The current
+TCP/UDP port number or port name for both local and remote (sets both
+<B>--lport</B>
+
+and
+<B>--rport</B>
+
+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.
@@ -797 +803 @@
 
 <DD>
-TCP/UDP port number for bind.
+Set local TCP/UDP port number or name.  Cannot be used together with
+<B>--nobind</B>
+
+option.
 
 <DT><B>--rport port</B>
 
 <DD>
-TCP/UDP port number for remote.
+Set TCP/UDP port number or name used by the
+<B>--remote</B>
+
+option. The port can also be set directly using the
+<B>--remote</B>
+
+option.
 
 <DT><B>--bind</B>
@@ -945 +960 @@
 <P>
 This option exists in OpenVPN 2.1 or higher.
+<P>
+Note: Using
+<B>--topology subnet</B>
+
+changes the interpretation of the arguments of
+<B>--ifconfig</B>
+
+to mean &quot;address netmask&quot;, no longer &quot;local remote&quot;.
 
 <DT><B>--tun-ipv6</B>
@@ -1025 +1048 @@
 
 is the IP address of the local VPN endpoint.
-For TUN devices,
+For TUN devices in point-to-point mode,
 <B>rn</B>
 
 is the IP address of the remote VPN endpoint.
-For TAP devices,
+For TAP devices, or TUN devices used with
+<B>--topology subnet,</B>
+
 <B>rn</B>
 
-is the subnet mask of the virtual ethernet segment
+is the subnet mask of the virtual network segment
 which is being created or connected to.
 <P>
 For TUN devices, which facilitate virtual
-point-to-point IP connections,
+point-to-point IP connections (when used in
+<B>--topology net30</B>
+
+or
+<B>p2p</B>
+
+mode),
 the proper usage of
 <B>--ifconfig</B>
@@ -1053 +1084 @@
 For TAP devices, which provide
 the ability to create virtual
-ethernet segments,
+ethernet segments, or TUN devices in
+<B>--topology subnet</B>
+
+mode (which create virtual &quot;multipoint networks&quot;),
 <B>--ifconfig</B>
 
@@ -2195 +2229 @@
 as the last parameter.
 <P>
+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).
+<P>
 The following standalone example shows how the
 <B>--up</B>
@@ -2428 +2468 @@
 As of OpenVPN v2.3, this flag is no longer accepted.  In most *nix environments the execve()
 approach has been used without any issues.
+<P>
+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.
 <P>
 To run scripts in Windows in earlier OpenVPN
@@ -4526 +4571 @@
 
 seconds waiting for a response before trying the next server.
+As this only makes sense in client-to-server setups, it cannot
+be used in point-to-point setups using
+<B>--secret</B>
+
+symmetrical key mode.
 
 <DT><B>--explicit-exit-notify [n]</B>
@@ -4674 +4724 @@
 
 <DD>
-Encrypt packets with cipher algorithm
+Encrypt data channel packets with cipher algorithm
 <B>alg.</B>
 
@@ -5107 +5157 @@
 Available with OpenSSL version &gt;= 0.9.7 dev.
 Not available with PolarSSL.
+<P>
+When using the
+<B>--capath</B>
+
+option, you are required to supply valid CRLs for the CAs too.  CAs in the
+capath directory are expected to be named &lt;hash&gt;.&lt;n&gt;.  CRLs are expected to
+be named &lt;hash&gt;.r&lt;n&gt;.  See the
+<B>-CApath</B>
+
+option of
+<B>openssl verify</B>
+
+, and the
+<B>-hash</B>
+
+option of
+<B>openssl x509</B>
+
+and
+<B>openssl crl</B>
+
+for more information.
 
 <DT><B>--dh file</B>
@@ -5201 +5273 @@
 Local peer's private key in .pem format.  Use the private key which was generated
 when you built your peer's certificate (see
-<B>-cert file</B>
+<B>--cert file</B>
 
 above).
@@ -5215 +5287 @@
 version supported by the local SSL implementation.
 <P>
-If this options is not set, the code in OpenVPN 2.3.4 will default
-to using TLS 1.0 only, without any version negotiation.  This reverts
-the beaviour to what OpenVPN versions up to 2.3.2 did, as it turned
-out that TLS version negotiation can lead to handshake problems due
-to new signature algorithms in TLS 1.2.
+Also see
+<B>--tls-version-max</B>
+
+below, for information on compatibility.
 
 <DT><B>--tls-version-max version</B>
@@ -5226 +5297 @@
 Set the maximum TLS version we will use (default is the highest version
 supported).  Examples for version include &quot;1.0&quot;, &quot;1.1&quot;, or &quot;1.2&quot;.
+<P>
+If and only if this is set to 1.0, and OpenSSL is used (not PolarSSL),
+then OpenVPN will set up OpenSSL to use a fixed TLSv1 handshake. All
+other configurations will autonegotiate in the given limits, and the
+choice of handshake versions is left to the SSL implementation.
 
 <DT><B>--pkcs12 file</B>
@@ -5299 +5375 @@
 <B>--pkcs12.</B>
 
+<P>
+If p11-kit is present on the system, its
+<B>p11-kit-proxy.so</B>
+
+module will be loaded by default if either the
+<B>--pkcs11-id</B>
+
+or
+<B>--pkcs11-id-management</B>
+
+options are specified without
+<B>--pkcs11-provider</B>
+
+being given.
 
 <DT><B>--pkcs11-private-mode mode...</B>
@@ -5419 +5509 @@
 
 of allowable TLS ciphers delimited by a colon (&quot;:&quot;).
-If you require a high level of security,
-you may want to set this parameter manually, to prevent a
-version rollback attack where a man-in-the-middle attacker tries
-to force two peers to negotiate to the lowest level
-of security they both support.
+<P>
+This 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.
+<P>
+The supplied list of ciphers is (after potential OpenSSL/IANA name translation)
+simply supplied to the crypto library.  Please see the OpenSSL and/or PolarSSL
+documentation for details on the cipher list interpretation.
+<P>
 Use
 <B>--show-tls</B>
 
-to see a list of supported TLS ciphers.
+to see a list of TLS ciphers supported by your crypto library.
+<P>
+Warning!
+<B>--tls-cipher</B>
+
+is an expert feature, which - if used correcly - can improve the security of
+your VPN connection.  But it is also easy to unwittingly use it to carefully
+align a gun with your foot, or just break your connection.  Use with care!
+<P>
+The default for --tls-cipher is to use PolarSSL's default cipher list
+when using PolarSSL or &quot;DEFAULT:!EXP:!PSK:!SRP:!kRSA&quot; when using OpenSSL.
 
 <DT><B>--tls-timeout n</B>
@@ -5573 +5678 @@
 parameter is used).
 <P>
-<B>(2)</B>
+<B>(2) DEPRECATED</B>
 
 A freeform passphrase file.  In this case the HMAC key will
@@ -5583 +5688 @@
 <B><A HREF="/cgi-bin/man/man2html?1+sha1sum">sha1sum</A></B>(1)
 
-commands.
+commands. This option is deprecated and will stop working in OpenVPN 2.4 and
+newer releases.
 <P>
 OpenVPN will first try format (1), and if the file fails to parse as
@@ -5712 +5818 @@
 OpenVPN session.
 <P>
+When using --auth-nocache in combination with a user/password file
+and --chroot or --daemon, make sure to use an absolute path.
+<P>
 This directive does not affect the
 <B>--http-proxy</B>
@@ -6096 +6205 @@
 (decimal string) is the name of a file present in the directory,
 it will be rejected.
+<P>
+Note: As the crl file (or directory) is read every time a peer connects,
+if you are dropping root privileges with
+<B>--user,</B>
+
+make sure that this user has sufficient privileges to read the file.
 
 </DL>
@@ -6125 +6240 @@
 <DD>
 (Standalone)
-Show all TLS ciphers (TLS used only as a control channel).  The TLS
-ciphers will be sorted from highest preference (most secure) to
-lowest.
+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.
+<P>
+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.).
 
 <DT><B>--show-engines</B>
@@ -6660 +6780 @@
 
 <DL COMPACT>
-<DT><B>--show-pkcs11-ids provider [cert_private]</B>
+<DT><B>--show-pkcs11-ids [provider] [cert_private]</B>
 
 <DD>
@@ -6666 +6786 @@
 Show PKCS#11 token object list. Specify cert_private as 1
 if certificates are stored as private objects.
+<P>
+If p11-kit is present on the system, the
+<B>provider</B>
+
+argument is optional; if omitted the default
+<B>p11-kit-proxy.so</B>
+
+module will be queried.
 <P>
 <B>--verb</B>
@@ -8364 +8492 @@
 <A HREF="/cgi-bin/man/man2html">man2html</A>,
 using the manual pages.<BR>
-Time: 07:44:25 GMT, December 01, 2014
+Time: 06:53:40 GMT, June 08, 2015
 }}}