diff options
Diffstat (limited to 'doc/openvpn.8.html')
| -rw-r--r-- | doc/openvpn.8.html | 227 |
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> </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> </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=<gui_id> <version></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=<mac address></code></dt> -<dd>The MAC address of clients default gateway</dd> +<dt><code>IV_HWADDR=<string></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=<version string></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 > /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), |