From f2b3dda12a731c2e0971cb7889728edaf23f6cb0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?J=C3=B6rg=20Frings-F=C3=BCrst?= <debian@jff.email>
Date: Mon, 29 Nov 2021 20:46:00 +0100
Subject: New upstream version 2.5.4

---
 doc/openvpn.8.html | 227 ++++++-----------------------------------------------
 1 file changed, 23 insertions(+), 204 deletions(-)

(limited to 'doc/openvpn.8.html')
diff --git a/doc/openvpn.8.html b/doc/openvpn.8.html
index 6ca509d..1c0c65e 100644
--- a/doc/openvpn.8.html
+++ b/doc/openvpn.8.html
@@ -3,7 +3,7 @@
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
 <head>
 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<meta name="generator" content="Docutils 0.15.2: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.16: http://docutils.sourceforge.net/" />
 <title>openvpn</title>
 <style type="text/css">
 
@@ -1244,6 +1244,15 @@ after a failed auth. Older clients will keep using the token value and
 react according to <tt class="docutils literal"><span class="pre">--auth-retry</span></tt></p>
 </td></tr>
 <tr><td class="option-group" colspan="2">
+<kbd><span class="option">--auth-token-user <var>base64username</var></span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td><p class="first">Companion option to <tt class="docutils literal"><span class="pre">--auth-token</span></tt>. This options allows to override
+the username used by the client when reauthenticating with the <tt class="docutils literal"><span class="pre">auth-token</span></tt>.
+It also allows to use <tt class="docutils literal"><span class="pre">--auth-token</span></tt> in setups that normally do not use
+username and password.</p>
+<p class="last">The username has to be base64 encoded.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
 <kbd><span class="option">--auth-user-pass</span></kbd></td>
 </tr>
 <tr><td>&nbsp;</td><td><p class="first">Authenticate with server using username/password.</p>
@@ -2082,12 +2091,21 @@ the server, a value of 2 or greater indicates client supports
 <dt><code>IV_GUI_VER=&lt;gui_id&gt; &lt;version&gt;</code></dt>
 <dd>The UI version of a UI if one is running, for example
 <code>de.blinkt.openvpn 0.5.47</code> for the Android app.</dd>
+<dt><code>IV_SSO=[crtext,][openurl,][proxy_url]</code></dt>
+<dd>Additional authentication methods supported by the client.
+This may be set by the client UI/GUI using <tt class="docutils literal"><span class="pre">--setenv</span></tt></dd>
 </dl>
 <p>When <tt class="docutils literal"><span class="pre">--push-peer-info</span></tt> is enabled the additional information consists
 of the following data:</p>
 <dl class="last docutils">
-<dt><code>IV_HWADDR=&lt;mac address&gt;</code></dt>
-<dd>The MAC address of clients default gateway</dd>
+<dt><code>IV_HWADDR=&lt;string&gt;</code></dt>
+<dd>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's 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.</dd>
 <dt><code>IV_SSL=&lt;version string&gt;</code></dt>
 <dd>The ssl version used by the client, e.g.
 <code>OpenSSL 1.0.2f 28 Jan 2016</code>.</dd>
@@ -5821,206 +5839,6 @@ See <tt class="docutils literal"><span class="pre">--ipchange</span></tt> for mo
 <dd>Causes OpenVPN to exit gracefully.</dd>
 </dl>
 </div>
-<div class="section" id="examples">
-<h1>EXAMPLES</h1>
-<p>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.</p>
-<div class="section" id="firewall-setup">
-<h2>Firewall Setup:</h2>
-<p>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 <tt class="docutils literal"><span class="pre">--ping</span> 15</tt> to each of the <tt class="docutils literal">openvpn</tt> 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).</p>
-<p>Please see your operating system guides for how to configure the firewall
-on your systems.</p>
-</div>
-<div class="section" id="vpn-address-setup">
-<h2>VPN Address Setup:</h2>
-<p>For purposes of our example, our two machines will be called
-<tt class="docutils literal">bob.example.com</tt> and <tt class="docutils literal">alice.example.com</tt>. If you are constructing a
-VPN over the internet, then replace <tt class="docutils literal">bob.example.com</tt> and
-<tt class="docutils literal">alice.example.com</tt> with the internet hostname or IP address that each
-machine will use to contact the other over the internet.</p>
-<p>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.</p>
-<p>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 <tt class="docutils literal">alice.example.com</tt> via
-<tt class="docutils literal">ssh</tt> without using the VPN (since <strong>ssh</strong> has its own built-in security)
-you would use the command <tt class="docutils literal">ssh alice.example.com</tt>. However in the same
-scenario, you could also use the command <tt class="docutils literal">telnet 10.4.0.2</tt> to create a
-telnet session with alice.example.com over the VPN, that would use the
-VPN to secure the session rather than <tt class="docutils literal">ssh</tt>.</p>
-<p>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.</p>
-</div>
-<div class="section" id="example-1-a-simple-tunnel-without-security">
-<h2>Example 1: A simple tunnel without security</h2>
-<p>On bob:</p>
-<pre class="literal-block">
-openvpn --remote alice.example.com --dev tun1 \
-         --ifconfig 10.4.0.1 10.4.0.2 --verb 9
-</pre>
-<p>On alice:</p>
-<pre class="literal-block">
-openvpn --remote bob.example.com --dev tun1 \
-         --ifconfig 10.4.0.2 10.4.0.1 --verb 9
-</pre>
-<p>Now verify the tunnel is working by pinging across the tunnel.</p>
-<p>On bob:</p>
-<pre class="literal-block">
-ping 10.4.0.2
-</pre>
-<p>On alice:</p>
-<pre class="literal-block">
-ping 10.4.0.1
-</pre>
-<p>The <tt class="docutils literal"><span class="pre">--verb</span> 9</tt> option will produce verbose output, similar to the
-<tt class="docutils literal">tcpdump</tt>(8) program. Omit the <tt class="docutils literal"><span class="pre">--verb</span> 9</tt> option to have OpenVPN run
-quietly.</p>
-</div>
-<div class="section" id="example-2-a-tunnel-with-static-key-security-i-e-using-a-pre-shared-secret">
-<h2>Example 2: A tunnel with static-key security (i.e. using a pre-shared secret)</h2>
-<p>First build a static key on bob.</p>
-<pre class="literal-block">
-openvpn --genkey --secret key
-</pre>
-<p>This command will build a key file called <tt class="docutils literal">key</tt> (in ascii format). Now
-copy <tt class="docutils literal">key</tt> to <tt class="docutils literal">alice.example.com</tt> over a secure medium such as by using
-the <tt class="docutils literal">scp</tt>(1) program.</p>
-<p>On bob:</p>
-<pre class="literal-block">
-openvpn --remote alice.example.com --dev tun1  \
-         --ifconfig 10.4.0.1 10.4.0.2 --verb 5 \
-         --secret key
-</pre>
-<p>On alice:</p>
-<pre class="literal-block">
-openvpn --remote bob.example.com --dev tun1   \
-        --ifconfig 10.4.0.2 10.4.0.1 --verb 5 \
-        --secret key
-</pre>
-<p>Now verify the tunnel is working by pinging across the tunnel.</p>
-<p>On bob:</p>
-<pre class="literal-block">
-ping 10.4.0.2
-</pre>
-<p>On alice:</p>
-<pre class="literal-block">
-ping 10.4.0.1
-</pre>
-</div>
-<div class="section" id="example-3-a-tunnel-with-full-tls-based-security">
-<h2>Example 3: A tunnel with full TLS-based security</h2>
-<p>For this test, we will designate <tt class="docutils literal">bob</tt> as the TLS client and <tt class="docutils literal">alice</tt>
-as the TLS server.</p>
-<dl class="docutils">
-<dt><em>Note:</em></dt>
-<dd>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.*</dd>
-</dl>
-<p>First, build a separate certificate/key pair for both bob and alice (see
-above where <tt class="docutils literal"><span class="pre">--cert</span></tt> is discussed for more info). Then construct
-Diffie Hellman parameters (see above where <tt class="docutils literal"><span class="pre">--dh</span></tt> is discussed for
-more info). You can also use the included test files <code>client.crt</code>,
-<code>client.key</code>, <code>server.crt</code>, <code>server.key</code> and
-<code>ca.crt</code>. The <tt class="docutils literal">.crt</tt> files are certificates/public-keys, the
-<tt class="docutils literal">.key</tt> files are private keys, and <code>ca.crt</code> is a certification
-authority who has signed both <code>client.crt</code> and <code>server.crt</code>.
-For Diffie Hellman parameters you can use the included file
-<code>dh2048.pem</code>.</p>
-<dl class="docutils">
-<dt><em>WARNING:</em></dt>
-<dd>All client, server, and certificate authority certificates
-and keys included in the OpenVPN distribution are totally
-insecure and should be used for testing only.</dd>
-</dl>
-<p>On bob:</p>
-<pre class="literal-block">
-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
-</pre>
-<p>On alice:</p>
-<pre class="literal-block">
-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
-</pre>
-<p>Now verify the tunnel is working by pinging across the tunnel.</p>
-<p>On bob:</p>
-<pre class="literal-block">
-ping 10.4.0.2
-</pre>
-<p>On alice:</p>
-<pre class="literal-block">
-ping 10.4.0.1
-</pre>
-<p>Notice the <tt class="docutils literal"><span class="pre">--reneg-sec</span> 60</tt> option we used above. That tells OpenVPN
-to renegotiate the data channel keys every minute. Since we used
-<tt class="docutils literal"><span class="pre">--verb</span> 5</tt> above, you will see status information on each new key
-negotiation.</p>
-<p>For production operations, a key renegotiation interval of 60 seconds is
-probably too frequent. Omit the <tt class="docutils literal"><span class="pre">--reneg-sec</span> 60</tt> option to use
-OpenVPN's default key renegotiation interval of one hour.</p>
-</div>
-<div class="section" id="routing">
-<h2>Routing:</h2>
-<p>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 <em>10.0.0.0/24</em> and
-alice's is <em>10.0.1.0/24</em>.</p>
-<p>First, ensure that IP forwarding is enabled on both peers. On Linux,
-enable routing:</p>
-<pre class="literal-block">
-echo 1 &gt; /proc/sys/net/ipv4/ip_forward
-</pre>
-<p>This setting is not persistent.  Please see your operating systems
-documentation how to properly configure IP forwarding, which is also
-persistent through system boots.</p>
-<p>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.</p>
-<p>On bob:</p>
-<pre class="literal-block">
-route add -net 10.0.1.0 netmask 255.255.255.0 gw 10.4.0.2
-</pre>
-<p>On alice:</p>
-<pre class="literal-block">
-route add -net 10.0.0.0 netmask 255.255.255.0 gw 10.4.0.1
-</pre>
-<p>Now any machine on the <em>10.0.0.0/24</em> subnet can access any machine on the
-<em>10.0.1.0/24</em> subnet over the secure tunnel (or vice versa).</p>
-<p>In a production environment, you could put the route command(s) in a
-script and execute with the <tt class="docutils literal"><span class="pre">--up</span></tt> option.</p>
-</div>
-</div>
 <div class="section" id="faq">
 <h1>FAQ</h1>
 <p><a class="reference external" href="https://community.openvpn.net/openvpn/wiki/FAQ">https://community.openvpn.net/openvpn/wiki/FAQ</a></p>
@@ -6049,7 +5867,8 @@ repository.</p>
 </div>
 <div class="section" id="see-also">
 <h1>SEE ALSO</h1>
-<p><tt class="docutils literal">dhcpcd</tt>(8),
+<p><tt class="docutils literal"><span class="pre">openvpn-examples</span></tt>(5),
+<tt class="docutils literal">dhcpcd</tt>(8),
 <tt class="docutils literal">ifconfig</tt>(8),
 <tt class="docutils literal">openssl</tt>(1),
 <tt class="docutils literal">route</tt>(8),
-- 
cgit v1.2.3

