diff options
Diffstat (limited to 'doc/openvpn.8')
| -rw-r--r-- | doc/openvpn.8 | 212 |
1 files changed, 150 insertions, 62 deletions
diff --git a/doc/openvpn.8 b/doc/openvpn.8 index 0b3e1ad..7801701 100644 --- a/doc/openvpn.8 +++ b/doc/openvpn.8 @@ -4,7 +4,7 @@ .\" packet encryption, packet authentication, and .\" packet compression. .\" -.\" Copyright (C) 2002-2017 OpenVPN Technologies, Inc. <sales@openvpn.net> +.\" Copyright (C) 2002-2018 OpenVPN Inc <sales@openvpn.net> .\" .\" This program is free software; you can redistribute it and/or modify .\" it under the terms of the GNU General Public License version 2 @@ -33,7 +33,15 @@ .\" .ft -- normal face .\" .in +|-{n} -- indent .\" -.TH openvpn 8 "25 August 2016" +.\" Support macros - this is not present on all platforms +.\" Continuation line for .TP header. +.de TQ +. br +. ns +. TP \\$1\" no doublequotes around argument! +.. +.\" End of TQ macro +.TH openvpn 8 "28 February 2018" .\"********************************************************* .SH NAME openvpn \- secure IP tunnel daemon. @@ -1173,7 +1181,7 @@ Option flags: .B local \-\- Add the .B local -flag if both OpenVPN servers are directly connected via a common subnet, +flag if both OpenVPN peers are directly connected via a common subnet, such as with wireless. The .B local flag will cause step @@ -1621,7 +1629,7 @@ and .B \-\-ping\-restart. This option can be used on both client and server side, but it is -in enough to add this on the server side as it will push appropriate +enough to add this on the server side as it will push appropriate .B \-\-ping and .B \-\-ping\-restart @@ -2452,12 +2460,37 @@ seconds. Status can also be written to the syslog by sending a .B 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 +.B \-\-status\-version +option in that case. + +For clients or instances running in point\-to\-point mode, it will contain the +traffic statistics. .\"********************************************************* .TP .B \-\-status\-version [n] -Choose the status file format version number. Currently -.B n -can be 1, 2, or 3 and defaults to 1. +Set the status file format version number to +.B n\fR. + +This only affects the status file on servers with multi\-client capability +enabled. + +.B 1 +\-\- traditional format (default). The client list contains the following +fields comma\-separated: Common Name, Real Address, Bytes Received, Bytes Sent, +Connected Since. +.br +.B 2 +\-\- a more reliable format for external processing. Compared to version 1, the +client list contains some additional fields: Virtual Address, Virtual IPv6 +Address, Username, Client ID, Peer ID. +Future versions may extend the number of fields. +.br +.B 3 +\-\- identical to 2, but fields are tab\-separated. + .\"********************************************************* .TP .B \-\-mute n @@ -2483,6 +2516,16 @@ If the 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. + +.B 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. + .\"********************************************************* .TP .B \-\-comp\-lzo [mode] @@ -2547,54 +2590,52 @@ the compression efficiency will be very low, triggering openvpn to disable compression for a period of time until the next re\-sample test. .\"********************************************************* .TP +.B \-\-management socket\-name unix [pw\-file] \ \ \ \ \ (recommended) +.TQ .B \-\-management IP port [pw\-file] -Enable a TCP server on -.B IP:port -to handle daemon management functions. -.B pw\-file, -if specified, -is a password file (password on first line) -or "stdin" to prompt from standard input. The password -provided will set the password which TCP clients will need -to provide in order to access management functions. - -The management interface can also listen on a unix domain socket, -for those platforms that support it. To use a unix domain socket, specify -the unix socket pathname in place of -.B IP -and set -.B port -to 'unix'. While the default behavior is to create a unix domain socket -that may be connected to by any process, the +Enable a management server on a +.B socket\-name +Unix socket on those platforms supporting it, or on +a designated TCP port. + +.B 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 .B \-\-management\-client\-user and .B \-\-management\-client\-group -directives can be used 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 -.B IP -= "tunnel". Tunnel mode will cause the management interface -to listen for a TCP connection on the local VPN address of the -TUN/TAP interface. +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 +.B tunnel. +Tunnel mode will cause the management interface to listen for a +TCP connection on the local VPN address of the TUN/TAP interface. + +.B BEWARE +of enabling the management interface over TCP. In these cases you should +.I ALWAYS +make use of +.B pw\-file +to password protect the management interface. Any user who can connect to this +TCP +.B 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 "help" for a list of commands. +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 "help" for a list of commands. -For detailed documentation on the management interface, see -the management\-notes.txt file in the -.B management -folder of -the OpenVPN source distribution. +For detailed documentation on the management interface, see the +.I management\-notes.txt +file in the management folder of the OpenVPN source distribution. -It is strongly recommended that -.B IP -be set to 127.0.0.1 -(localhost) to restrict accessibility of the management -server to local clients. .TP .B \-\-management\-client Management interface will connect as a TCP/unix domain client to @@ -3026,7 +3067,7 @@ IV_NCP=2 \-\- negotiable ciphers, client supports pushed by the server, a value of 2 or greater indicates client supports AES\-GCM\-128 and AES\-GCM\-256. -IV_UI_VER=<gui_id> <version> \-\- the UI version of a UI if one is +IV_GUI_VER=<gui_id> <version> \-\- the UI version of a UI if one is running, for example "de.blinkt.openvpn 0.5.47" for the Android app. @@ -4889,11 +4930,13 @@ determines the derivation of the tunnel session keys. .\"********************************************************* .TP .B \-\-tls\-cipher l +.TQ +.B \-\-tls\-ciphersuites l A list .B l of allowable TLS ciphers delimited by a colon (":"). -This setting can be used to ensure that certain cipher suites are used (or +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. @@ -4902,20 +4945,63 @@ 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 +.B \-\-tls-cipher +is used for TLS 1.2 and below. For TLS 1.3 and up, the +.B \-\-tls\-ciphersuites +setting is used. mbed TLS has no TLS 1.3 support yet and only the +.B \-\-tls-cipher +setting is used. + Use .B \-\-show\-tls to see a list of TLS ciphers supported by your crypto library. Warning! .B \-\-tls\-cipher -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 +and +.B \-\-tls\-ciphersuites +are expert features, which \- if used correcly \- 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! The default for \-\-tls\-cipher is to use mbed TLS's default cipher list when using mbed TLS or "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. +.\"********************************************************* +.TP +.B \-\-tls\-cert\-profile profile +Set the allowed cryptographic algorithms for certificates according to +.B profile\fN. + +The following profiles are supported: + +.B legacy +(default): SHA1 and newer, RSA 2048-bit+, any elliptic curve. + +.B preferred +: SHA2 and newer, RSA 2048-bit+, any elliptic curve. + +.B 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: + +.B legacy +(default): sets "security level 1" + +.B preferred +: sets "security level 2" + +.B 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. .\"********************************************************* .TP .B \-\-tls\-timeout n @@ -5252,6 +5338,12 @@ 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 acording to +.B \-\-auth-retry +. .\"********************************************************* .TP .B \-\-tls\-verify cmd @@ -5806,17 +5898,13 @@ across the VPN. Set Connection\-specific DNS Suffix. .B DNS addr \-\- -Set primary domain name server IPv4 address. Repeat +Set primary domain name server IPv4 or IPv6 address. Repeat this option to set secondary DNS server addresses. -.B DNS6 addr \-\- -Set primary domain name server IPv6 address. Repeat -this option to set secondary DNS server IPv6 addresses. - -Note: currently this is handled 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 +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 .B \-\-up script could act upon it if needed. @@ -7238,7 +7326,7 @@ For more information on the LZO real\-time compression library see .I http://www.oberhumer.com/opensource/lzo/ .\"********************************************************* .SH COPYRIGHT -Copyright (C) 2002\-2017 OpenVPN Technologies, Inc. This program is free software; +Copyright (C) 2002\-2018 OpenVPN Inc This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License version 2 as published by the Free Software Foundation. |