New upstream version 2.5.4upstream/2.5.4

1 files changed, 21 insertions, 339 deletions

diff --git a/doc/openvpn.8 b/doc/openvpn.8
index 57d94ea..ceb6348 100644
--- a/doc/openvpn.8
+++ b/doc/openvpn.8
@@ -1031,6 +1031,14 @@ 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 \fB\-\-auth\-retry\fP
 .TP
+.BI \-\-auth\-token\-user \ base64username
+Companion option to \fB\-\-auth\-token\fP\&. This options allows to override
+the username used by the client when reauthenticating with the \fBauth\-token\fP\&.
+It also allows to use \fB\-\-auth\-token\fP in setups that normally do not use
+username and password.
+.sp
+The username has to be base64 encoded.
+.TP
 .B \-\-auth\-user\-pass
 Authenticate with server using username/password.
 .sp
@@ -2076,14 +2084,24 @@ The client announces the list of supported ciphers configured with the
 .B \fBIV_GUI_VER=<gui_id> <version>\fP
 The UI version of a UI if one is running, for example
 \fBde.blinkt.openvpn 0.5.47\fP for the Android app.
+.TP
+.B \fBIV_SSO=[crtext,][openurl,][proxy_url]\fP
+Additional authentication methods supported by the client.
+This may be set by the client UI/GUI using \fB\-\-setenv\fP
 .UNINDENT
 .sp
 When \fB\-\-push\-peer\-info\fP is enabled the additional information consists
 of the following data:
 .INDENT 7.0
 .TP
-.B \fBIV_HWADDR=<mac address>\fP
-The MAC address of clients default gateway
+.B \fBIV_HWADDR=<string>\fP
+This is intended to be a unique and persistent ID of the client.
+The string value can be any readable ASCII string up to 64 bytes.
+OpenVPN 2.x and some other implementations use the MAC address of
+the client\(aqs interface used to reach the default gateway. If this
+string is generated by the client, it should be consistent and
+preserved across independent session and preferably
+re\-installations and upgrades.
 .TP
 .B \fBIV_SSL=<version string>\fP
 The ssl version used by the client, e.g.
@@ -6637,343 +6655,6 @@ Causes OpenVPN to display its current statistics (to the syslog file if
 .B \fBSIGINT\fP, \fBSIGTERM\fP
 Causes OpenVPN to exit gracefully.
 .UNINDENT
-.SH EXAMPLES
-.sp
-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.
-.SS Firewall Setup:
-.sp
-If firewalls exist between the two machines, they should be set to
-forward the port OpenVPN is configured to use, in both directions.
-The default for OpenVPN is 1194/udp.  If you do not have control
-over the firewalls between the two machines, you may still be able to
-use OpenVPN by adding \fB\-\-ping 15\fP to each of the \fBopenvpn\fP 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).
-.sp
-Please see your operating system guides for how to configure the firewall
-on your systems.
-.SS VPN Address Setup:
-.sp
-For purposes of our example, our two machines will be called
-\fBbob.example.com\fP and \fBalice.example.com\fP\&. If you are constructing a
-VPN over the internet, then replace \fBbob.example.com\fP and
-\fBalice.example.com\fP with the internet hostname or IP address that each
-machine will use to contact the other over the internet.
-.sp
-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.
-.sp
-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 \fBalice.example.com\fP via
-\fBssh\fP without using the VPN (since \fBssh\fP has its own built\-in security)
-you would use the command \fBssh alice.example.com\fP\&. However in the same
-scenario, you could also use the command \fBtelnet 10.4.0.2\fP to create a
-telnet session with alice.example.com over the VPN, that would use the
-VPN to secure the session rather than \fBssh\fP\&.
-.sp
-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.
-.SS Example 1: A simple tunnel without security
-.sp
-On bob:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-openvpn \-\-remote alice.example.com \-\-dev tun1 \e
-         \-\-ifconfig 10.4.0.1 10.4.0.2 \-\-verb 9
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-On alice:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-openvpn \-\-remote bob.example.com \-\-dev tun1 \e
-         \-\-ifconfig 10.4.0.2 10.4.0.1 \-\-verb 9
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-Now verify the tunnel is working by pinging across the tunnel.
-.sp
-On bob:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-ping 10.4.0.2
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-On alice:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-ping 10.4.0.1
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-The \fB\-\-verb 9\fP option will produce verbose output, similar to the
-\fBtcpdump\fP(8) program. Omit the \fB\-\-verb 9\fP option to have OpenVPN run
-quietly.
-.SS Example 2: A tunnel with static\-key security (i.e. using a pre\-shared secret)
-.sp
-First build a static key on bob.
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-openvpn \-\-genkey \-\-secret key
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-This command will build a key file called \fBkey\fP (in ascii format). Now
-copy \fBkey\fP to \fBalice.example.com\fP over a secure medium such as by using
-the \fBscp\fP(1) program.
-.sp
-On bob:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-openvpn \-\-remote alice.example.com \-\-dev tun1  \e
-         \-\-ifconfig 10.4.0.1 10.4.0.2 \-\-verb 5 \e
-         \-\-secret key
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-On alice:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-openvpn \-\-remote bob.example.com \-\-dev tun1   \e
-        \-\-ifconfig 10.4.0.2 10.4.0.1 \-\-verb 5 \e
-        \-\-secret key
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-Now verify the tunnel is working by pinging across the tunnel.
-.sp
-On bob:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-ping 10.4.0.2
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-On alice:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-ping 10.4.0.1
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.SS Example 3: A tunnel with full TLS\-based security
-.sp
-For this test, we will designate \fBbob\fP as the TLS client and \fBalice\fP
-as the TLS server.
-.INDENT 0.0
-.TP
-.B \fINote:\fP
-The client or server designation only has
-meaning for the TLS subsystem. It has no bearing on OpenVPN\(aqs
-peer\-to\-peer, UDP\-based communication model.*
-.UNINDENT
-.sp
-First, build a separate certificate/key pair for both bob and alice (see
-above where \fB\-\-cert\fP is discussed for more info). Then construct
-Diffie Hellman parameters (see above where \fB\-\-dh\fP is discussed for
-more info). You can also use the included test files \fBclient.crt\fP,
-\fBclient.key\fP, \fBserver.crt\fP, \fBserver.key\fP and
-\fBca.crt\fP\&. The \fB\&.crt\fP files are certificates/public\-keys, the
-\fB\&.key\fP files are private keys, and \fBca.crt\fP is a certification
-authority who has signed both \fBclient.crt\fP and \fBserver.crt\fP\&.
-For Diffie Hellman parameters you can use the included file
-\fBdh2048.pem\fP\&.
-.INDENT 0.0
-.TP
-.B \fIWARNING:\fP
-All client, server, and certificate authority certificates
-and keys included in the OpenVPN distribution are totally
-insecure and should be used for testing only.
-.UNINDENT
-.sp
-On bob:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-openvpn \-\-remote alice.example.com \-\-dev tun1    \e
-        \-\-ifconfig 10.4.0.1 10.4.0.2             \e
-        \-\-tls\-client \-\-ca ca.crt                 \e
-        \-\-cert client.crt \-\-key client.key       \e
-        \-\-reneg\-sec 60 \-\-verb 5
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-On alice:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-openvpn \-\-remote bob.example.com \-\-dev tun1      \e
-        \-\-ifconfig 10.4.0.2 10.4.0.1             \e
-        \-\-tls\-server \-\-dh dh1024.pem \-\-ca ca.crt \e
-        \-\-cert server.crt \-\-key server.key       \e
-        \-\-reneg\-sec 60 \-\-verb 5
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-Now verify the tunnel is working by pinging across the tunnel.
-.sp
-On bob:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-ping 10.4.0.2
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-On alice:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-ping 10.4.0.1
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-Notice the \fB\-\-reneg\-sec 60\fP option we used above. That tells OpenVPN
-to renegotiate the data channel keys every minute. Since we used
-\fB\-\-verb 5\fP above, you will see status information on each new key
-negotiation.
-.sp
-For production operations, a key renegotiation interval of 60 seconds is
-probably too frequent. Omit the \fB\-\-reneg\-sec 60\fP option to use
-OpenVPN\(aqs default key renegotiation interval of one hour.
-.SS Routing:
-.sp
-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\(aqs private subnet is \fI10.0.0.0/24\fP and
-alice\(aqs is \fI10.0.1.0/24\fP\&.
-.sp
-First, ensure that IP forwarding is enabled on both peers. On Linux,
-enable routing:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-echo 1 > /proc/sys/net/ipv4/ip_forward
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-This setting is not persistent.  Please see your operating systems
-documentation how to properly configure IP forwarding, which is also
-persistent through system boots.
-.sp
-If your system is configured with a firewall.  Please see your operating
-systems guide on how to configure the firewall.  You typically want to
-allow traffic coming from and going to the tun/tap adapter OpenVPN is
-configured to use.
-.sp
-On bob:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-route add \-net 10.0.1.0 netmask 255.255.255.0 gw 10.4.0.2
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-On alice:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-route add \-net 10.0.0.0 netmask 255.255.255.0 gw 10.4.0.1
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-Now any machine on the \fI10.0.0.0/24\fP subnet can access any machine on the
-\fI10.0.1.0/24\fP subnet over the secure tunnel (or vice versa).
-.sp
-In a production environment, you could put the route command(s) in a
-script and execute with the \fB\-\-up\fP option.
 .SH FAQ
 .sp
 \fI\%https://community.openvpn.net/openvpn/wiki/FAQ\fP
@@ -6998,6 +6679,7 @@ repository.
 Report all bugs to the OpenVPN team \fI\%info@openvpn.net\fP
 .SH SEE ALSO
 .sp
+\fBopenvpn\-examples\fP(5),
 \fBdhcpcd\fP(8),
 \fBifconfig\fP(8),
 \fBopenssl\fP(1),