summaryrefslogtreecommitdiff
path: root/doc/openvpn.8.html
diff options
context:
space:
mode:
authorJörg Frings-Fürst <debian@jff.email>2021-11-29 20:46:00 +0100
committerJörg Frings-Fürst <debian@jff.email>2021-11-29 20:46:00 +0100
commitf2b3dda12a731c2e0971cb7889728edaf23f6cb0 (patch)
treefdf8833416567ca3842f347b2126cdbb13c746bd /doc/openvpn.8.html
parent4ee98f284a93c3b855092d35ac21371d9dcad65b (diff)
New upstream version 2.5.4upstream/2.5.4
Diffstat (limited to 'doc/openvpn.8.html')
-rw-r--r--doc/openvpn.8.html227
1 files changed, 23 insertions, 204 deletions
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),