Merge lp:~powersj/serverguide/update-vpn-bionic into lp:serverguide/trunk

[Joshua Powers]

vpn: update advanced config with netplan

With the release of Ubuntu Bionic LTS, ifupdown was replaced with
netplan and as such any /etc/network/interfaces configuration needs
to take place via netplan. This updates the example to use netplan
and a networkd-dispatcher hook.

drive-by: white space found by editor

Fixes LP: #1772514

[Steve Langasek (vorlon)]

A few things found for fixing.

Have you tested that following these instructions gives a working setup?

review: Needs Fixing

[Joshua Powers (powersj)]

> Have you tested that following these instructions gives a working setup?

No, I took what was in your askubuntu question and added it to the guide. I was told to wait with this review until the previous networkd-dispatcher bug which appeared resolved: https://bugs.launchpad.net/ubuntu/+source/networkd-dispatcher/+bug/1772137

[Steve Langasek (vorlon)]

On Thu, Aug 16, 2018 at 11:15:45PM -0000, Joshua Powers wrote:
> No, I took what was in your askubuntu question and added it to the guide.
> I was told to wait with this review until the previous networkd-dispatcher
> bug which appeared resolved:
> https://bugs.launchpad.net/ubuntu/+source/networkd-dispatcher/+bug/1772137

Ok, the fact that I wrote anything at all about dormant.d in that askubuntu
answer had flown my mind ;) I would say it still warrants end-to-end test
of what's currently written there to make sure nothing has been missed.

[lp:~powersj/serverguide/update-vpn-bionic]

360. By Joshua Powers on 2018-08-17

typos fixes from stevew

[Joshua Powers (powersj)]

Steve can you take another look?

If you didn't see my previous comment, I setup a system with a bridge and configured networkd-dispatcher as above and confirmed the nic entered promiscuous mode: https://paste.ubuntu.com/p/BR4cMRYBr7/

[Steve Langasek (vorlon)]

Looks good now. Thanks!

review: Approve

[Doug Smythies (dsmythies)]

Thanks very much. It'll be a few days until the published serverguide is updated.

review: Approve

=== modified file 'serverguide/C/vpn.xml'
--- serverguide/C/vpn.xml	2017-10-29 16:47:30 +0000
+++ serverguide/C/vpn.xml	2018-08-17 17:24:40 +0000
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" 
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
 	"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
 <!ENTITY % globalent SYSTEM "../../libs/global.ent">
 %globalent;
@@ -11,7 +11,7 @@
   <title>VPN</title>
 
   <para>
-OpenVPN is a Virtual Private Networking (VPN) solution provided in the Ubuntu Repositories. It is flexible, reliable and secure. It belongs to the family of SSL/TLS VPN stacks (different from IPSec VPNs). This chapter will cover 
+OpenVPN is a Virtual Private Networking (VPN) solution provided in the Ubuntu Repositories. It is flexible, reliable and secure. It belongs to the family of SSL/TLS VPN stacks (different from IPSec VPNs). This chapter will cover
 installing and configuring <application>OpenVPN</application> to create a VPN.
   </para>
 
@@ -22,7 +22,7 @@
     If you want more than just pre-shared keys <application>OpenVPN</application>  makes it easy to setup and use a Public Key Infrastructure (PKI)
     to use SSL/TLS certificates for authentication and key exchange
     between the VPN server and clients.
-    <application>OpenVPN</application> can be used in a routed or bridged VPN mode and can be configured to use either UDP or TCP. The port number can be configured as well, but port 1194 is the official one. And it is only using that single port for all communication. VPN client implementations are available for almost anything including all Linux distributions, OS X, Windows and OpenWRT based WLAN routers. 
+    <application>OpenVPN</application> can be used in a routed or bridged VPN mode and can be configured to use either UDP or TCP. The port number can be configured as well, but port 1194 is the official one. And it is only using that single port for all communication. VPN client implementations are available for almost anything including all Linux distributions, OS X, Windows and OpenWRT based WLAN routers.
     </para>
 
     <sect2 id="openvpn-server-installation" status="review">
@@ -65,8 +65,8 @@
 
       <para>
 To setup your own Certificate Authority (CA) and generating certificates and keys for an OpenVPN server and multiple clients
-        first copy the <filename>easy-rsa</filename> directory to <filename>/etc/openvpn</filename>.  This will ensure that any 
-        changes to the scripts will not be lost when the package is updated. 
+        first copy the <filename>easy-rsa</filename> directory to <filename>/etc/openvpn</filename>.  This will ensure that any
+        changes to the scripts will not be lost when the package is updated.
         From a terminal change to user root and:
         </para>
 
@@ -141,7 +141,7 @@
         <title>Client Certificates</title>
 
         <para>
-        The VPN client will also need a certificate to authenticate itself to the server. Usually you create a different certificate for each client. To create the 
+        The VPN client will also need a certificate to authenticate itself to the server. Usually you create a different certificate for each client. To create the
         certificate, enter the following in a terminal while being user root:
         </para>
 
@@ -381,7 +381,7 @@
 
 <programlisting>
 root@client:/etc/openvpn# ifconfig tun0
-tun0      Link encap:UNSPEC  HWaddr 00-00-00-00-00-00-00-00-00-00-00-00-00-00-00-00  
+tun0      Link encap:UNSPEC  HWaddr 00-00-00-00-00-00-00-00-00-00-00-00-00-00-00-00
           inet addr:10.8.0.6  P-t-P:10.8.0.5  Mask:255.255.255.255
           UP POINTOPOINT RUNNING NOARP MULTICAST  MTU:1500  Metric:1
 </programlisting>
@@ -585,100 +585,72 @@
       <sect4 id="openvpn-bridged-server-configuration-interface" status="review">
 <title>Prepare interface config for bridging on server</title>
 
-      <para>
-      Make sure you have the bridge-utils package installed:
-      </para>
-<screen>
-<command>sudo apt install bridge-utils</command>
-</screen>
-
-        <para>
-Before you setup OpenVPN in bridged mode you need to change your interface configuration. Let's assume your server has an interface eth0 connected to the internet and an interface eth1 connected to the LAN you want to bridge. Your /etc/network/interfaces would like this:
-        </para>
-
-<programlisting>
-auto eth0
-iface eth0 inet static
-  address 1.2.3.4
-  netmask 255.255.255.248
-  default 1.2.3.1
-
-auto eth1
-iface eth1 inet static
-  address 10.0.0.4
-  netmask 255.255.255.0
-</programlisting>
-
-        <para>
-This straight forward interface config needs to be changed into a bridged mode like where the config of interface eth1 moves to the new br0 interface. Plus we configure that br0 should bridge interface eth1. We also need to make sure that interface eth1 is always in promiscuous mode - this tells the interface to forward all ethernet frames to the IP stack.
-        </para>
-
-<programlisting>
-auto eth0
-iface eth0 inet static
-  address 1.2.3.4
-  netmask 255.255.255.248
-  default 1.2.3.1
-
-auto eth1
-iface eth1 inet manual
-  up ip link set $IFACE up promisc on
-
-auto br0
-iface br0 inet static
-  address 10.0.0.4
-  netmask 255.255.255.0
-  bridge_ports eth1
-</programlisting>
-
-        <para>
-At this point you need to bring up the bridge. Be prepared that this might not work as expected and that you will lose remote connectivity. Make sure you can solve problems having local access.
-        </para>
-<screen>
-<command>sudo ifdown eth1 &amp;&amp; sudo ifup -a</command>
-</screen>
+<para>First, use netplan to configure a bridge device using the desired ethernet
+device.</para>
+
+<programlisting>
+$ cat /etc/netplan/01-netcfg.yaml
+# This file describes the network interfaces available on your system
+# For more information, see netplan(5).
+
+network:
+    version: 2
+    renderer: networkd
+    ethernets:
+        enp0s31f6:
+            dhcp4: no
+    bridges:
+        br0:
+            interfaces: [enp0s31f6]
+            dhcp4: no
+            addresses: [10.0.1.100/24]
+            gateway4: 10.0.1.1
+            nameservers:
+                addresses: [10.0.1.1]
+</programlisting>
+
+<para>Static IP addressing is highly suggested. DHCP addressing can also work,
+but you will still have to encode a static address in the OpenVPN configuration file.</para>
+
+<para>The next step on the server is to configure the ethernet device for
+promiscuous mode on boot. To do this, ensure the
+<application>networkd-dispatcher</application> package is installed and create
+the following configuration script.</para>
+
+<screen>
+<command>sudo apt update</command>
+<command>sudo apt install networkd-dispatcher</command>
+<command>sudo touch /usr/lib/networkd-dispatcher/dormant.d/promisc_bridge</command>
+<command>sudo chmod +x /usr/lib/networkd-dispatcher/dormant.d/promisc_bridge</command>
+</screen>
+
+<para>Then add the following contents.</para>
+
+<programlisting>
+#!/bin/sh
+set -e
+if [ "$IFACE" = br0 ]; then
+    # no networkd-dispatcher event for 'carrier' on the physical interface
+    ip link set eth0 up promisc on
+fi
+</programlisting>
 
 </sect4>
       <sect4 id="openvpn-bridged-server-configuration-server" status="review">
 <title>Prepare server config for bridging</title>
 
         <para>
-        Edit <filename>/etc/openvpn/server.conf</filename> changing the following options to:
+        Edit <filename>/etc/openvpn/server.conf</filename> to use tap rather than tun and set the server to use the server-bridge directive:
         </para>
 
 <programlisting>
 ;dev tun
 dev tap
-up "/etc/openvpn/up.sh br0 eth1"
 ;server 10.8.0.0 255.255.255.0
 server-bridge 10.0.0.4 255.255.255.0 10.0.0.128 10.0.0.254
 </programlisting>
 
         <para>
-        Next, create a helper script to add the <emphasis>tap</emphasis> interface to the bridge and to ensure that eth1 is promiscuous mode. Create <filename>/etc/openvpn/up.sh</filename>:
-        </para>
-
-<programlisting>
-#!/bin/sh
-
-BR=$1
-ETHDEV=$2
-TAPDEV=$3
-
-/sbin/ip link set "$TAPDEV" up
-/sbin/ip link set "$ETHDEV" promisc on
-/sbin/brctl addif $BR $TAPDEV
-</programlisting>
-
-        <para>
-        Then make it executable:
-        </para>
-
-<screen>
-<command>sudo chmod 755 /etc/openvpn/up.sh</command>
-</screen>
-
-        <para>
         After configuring the server, restart <application>openvpn</application> by entering:
         </para>
 
@@ -699,7 +671,7 @@
 </screen>
 
         <para>
-        Then with the server configured and the client certificates copied to the <filename>/etc/openvpn/</filename> directory, create a client configuration file by 
+        Then with the server configured and the client certificates copied to the <filename>/etc/openvpn/</filename> directory, create a client configuration file by
         copying the example.  In a terminal on the client machine enter:
         </para>
 
@@ -743,7 +715,7 @@
 
     <para>
 Many Linux distributions including Ubuntu desktop variants come with Network Manager,
-a nice GUI to configure your network settings. It also can manage your VPN connections. Make sure you have package network-manager-openvpn installed. Here you see that the installation installs all other required packages as well: 
+a nice GUI to configure your network settings. It also can manage your VPN connections. Make sure you have package network-manager-openvpn installed. Here you see that the installation installs all other required packages as well:
     </para>
 
 <programlisting>
@@ -927,12 +899,12 @@
         </listitem>
         <listitem>
           <para>
-          <ulink url="http://openvpn.net/index.php/open-source/documentation/howto.html#security">OpenVPN hardening security guide</ulink> 
+          <ulink url="http://openvpn.net/index.php/open-source/documentation/howto.html#security">OpenVPN hardening security guide</ulink>
           </para>
         </listitem>
         <listitem>
           <para>
-          Also, Pakt's <ulink url="http://www.packtpub.com/openvpn/book">OpenVPN: Building and Integrating Virtual Private Networks</ulink> 
+          Also, Pakt's <ulink url="http://www.packtpub.com/openvpn/book">OpenVPN: Building and Integrating Virtual Private Networks</ulink>
           is a good resource.
           </para>
         </listitem>