docs: improve home gateway use-case documentation

Add plugin config, systemd config, netplan config, software
installation via ssh, and a quick HowTo for setting up a double-nat
test gateway.

Fix a minor doc bug which caused a complaint on vpp-dev@lists.fd.io:
/etc/vpp/startup.conf -> /setup.gate, but the vpp configuration file
wasn't explicitly tagged with the name /setup.gate.

Type: docs

Change-Id: Ib219040d7c3c8b50ed66f8e9d3afd3dcf51b6b7b
Signed-off-by: Dave Barach <dave@barachs.net>

1 files changed, 131 insertions, 18 deletions

diff --git a/docs/usecases/homegateway.rst b/docs/usecases/homegateway.rst
index 077d5a2a961..f419c4ecb29 100644
--- a/docs/usecases/homegateway.rst
+++ b/docs/usecases/homegateway.rst
@@ -7,8 +7,8 @@ Using VPP as a Home Gateway
 
 Vpp running on a small system (with appropriate NICs) makes a fine
 home gateway. The resulting system performs far in excess of
-requirements: a TAG=vpp_debug image runs at a vector size of ~1.1
-terminating a 90-mbit down / 10-mbit up cable modem connection.
+requirements: a TAG=vpp_debug image runs at a vector size of ~1.2
+terminating a 150-mbit down / 10-mbit up cable modem connection.
 
 At a minimum, install sshd and the isc-dhcp-server. If you prefer, you
 can use dnsmasq.
@@ -24,6 +24,7 @@ Configuration files
    full-coredump
    cli-listen /run/vpp/cli.sock
    startup-config /setup.gate
+   poll-sleep-usec 100
    gid vpp
  }
  api-segment {
@@ -33,10 +34,19 @@ Configuration files
       dev 0000:03:00.0
       dev 0000:14:00.0
       etc.
-      poll-sleep 10
- }
+  }
+
+  plugins {
+	## Disable all plugins, selectively enable specific plugins
+        ## YMMV, you may wish to enable other plugins (acl, etc.)
+	plugin default { disable }
+	plugin dpdk_plugin.so { enable }
+	plugin nat_plugin.so { enable }
+        ## if you plan to use the time-based MAC filter
+	plugin mactime_plugin.so { enable }
+  }
 
-isc-dhcp-server configuration::
+/etc/dhcp/dhcpd.conf::
 
  subnet 192.168.1.0 netmask 255.255.255.0 {
    range 192.168.1.10 192.168.1.99;
@@ -47,6 +57,13 @@ isc-dhcp-server configuration::
 If you decide to enable the vpp dns name resolver, substitute
 192.168.1.2 for 8.8.8.8 in the dhcp server configuration.
 
+/etc/default/isc-dhcp-server::
+
+  # On which interfaces should the DHCP server (dhcpd) serve DHCP requests?
+  #	Separate multiple interfaces with spaces, e.g. "eth0 eth1".
+  INTERFACESv4="lstack"
+  INTERFACESv6=""
+
 /etc/ssh/sshd_config::
 
  # What ports, IPs and protocols we listen for
@@ -59,7 +76,7 @@ and do not answer ssh requests on port 22. Experience shows several
 hack attempts per hour on port 22, but none (ever) on random
 high-number ports.
 
-vpp configuration::
+vpp configuration (/setup.gate)::
 
   comment { This is the WAN interface }
   set int state GigabitEthernet3/0/0 up
@@ -74,10 +91,10 @@ vpp configuration::
 
   comment { Add more inside interfaces as needed ... }
   set int l2 bridge GigabitEthernet0/14/0 1
-  set int state GigabitEthernet0/14/0 up 
+  set int state GigabitEthernet0/14/0 up
 
   comment { dhcp server and host-stack access }
-  create tap host-if-name lstack host-ip4-addr 192.168.1.2/24 host-ip4-gw 192.168.1.1 
+  create tap host-if-name lstack host-ip4-addr 192.168.1.2/24 host-ip4-gw 192.168.1.1
   set int l2 bridge tap0 1
   set int state tap0 up
 
@@ -85,8 +102,8 @@ vpp configuration::
   nat44 add interface address GigabitEthernet3/0/0
   set interface nat44 in loop0 out GigabitEthernet3/0/0
 
-  comment { allow inbound ssh to the <REDACTED-high-number-port>
-  nat44 add static mapping local 192.168.1.2 <REDACTED> external GigabitEthernet3/0/0 <REDACTED> tcp 
+  comment { allow inbound ssh to the <REDACTED-high-number-port> }
+  nat44 add static mapping local 192.168.1.2 <REDACTED> external GigabitEthernet3/0/0 <REDACTED> tcp
 
   comment { if you want to use the vpp DNS server, add the following }
   comment { Remember to adjust the isc-dhcp-server configuration appropriately }
@@ -96,7 +113,103 @@ vpp configuration::
   comment { bin dns_enable_disable }
   comment { see patch below, which adds these commands }
   service restart isc-dhcp-server
- 
+
+Systemd configuration
+---------------------
+
+In a typical home-gateway use-case, vpp owns the one-and-only WAN link
+with a prayer of reaching the public internet. Simple things like
+updating distro software requires use of the "lstack" interface
+created above, and configuring a plausible upstream DNS name resolver.
+
+Configure /etc/systemd/resolved.conf as follows.
+
+/etc/systemd/resolved.conf::
+
+  [Resolve]
+  DNS=8.8.8.8
+  #FallbackDNS=
+  #Domains=
+  #LLMNR=no
+  #MulticastDNS=no
+  #DNSSEC=no
+  #Cache=yes
+  #DNSStubListener=yes
+
+Netplan configuration
+---------------------
+
+If you want to configure a static IP address on one of your
+home-gateway Ethernet ports on Ubuntu 18.04, you'll need to configure
+netplan. Netplan is relatively new. It and the network manager GUI and
+can be cranky. In the configuration shown below,
+s/enp4s0/<your-interface>/...
+
+/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:
+      enp4s0:
+        dhcp4: no
+        addresses: [192.168.2.254/24]
+        gateway4: 192.168.2.100
+        nameservers:
+          search: [my.local]
+          addresses: [8.8.8.8]
+
+/etc/systemd/network-10.enp4s0.network::
+
+  [Match]
+  Name=enp4s0
+
+  [Link]
+  RequiredForOnline=no
+
+  [Network]
+  ConfigureWithoutCarrier=true
+  Address=192.168.2.254/24
+
+Note that we've picked an IP address for the home gateway which is on
+an independent unrouteable subnet. This is handy for installing (and
+possibly reverting) new vpp software.
+
+Installing new vpp software
+---------------------------
+
+If you're **sure** that a given set of vpp Debian packages will
+install and work properly, you can install them while logged into the
+gateway via the lstack / nat path. This procedure is a bit like
+standing on a rug and yanking it. If all goes well, a perfect
+back-flip occurs.  If not, you may wish that you'd configured a static
+IP address on a reserved Ethernet interface as described above.
+
+Installing a new vpp image via ssh to 192.168.1.2::
+
+  # nohup dpkg -i *.deb >/dev/null 2>&1 &
+
+Within a few seconds, the inbound ssh connection SHOULD begin to respond
+again. If it does not, you'll have to debug the issue(s).
+
+Testing new software
+--------------------
+
+If you frequently test new home gateway software, it may be handy to
+set up a test gateway behind your production gateway. This testing
+methodology reduces complaints from family members, to name one benefit.
+
+Change the inside network (dhcp) subnet from 192.168.1.0/24 to
+192.168.3.0/24, change the (dhcp) advertised router to 192.168.3.1,
+reconfigure the vpp tap interface addresses onto the 192.168.3.0/24
+subnet, and you should be all set.
+
+This scenario nats traffic twice: first, from the 192.168.3.0/24
+network onto the 192.168.1.0/24 network. Next, from the 192.168.1.0/24
+network onto the public internet.
+
 Patches
 -------
 
@@ -121,15 +234,15 @@ You'll need this patch to add the "service restart" command::
 
   +static clib_error_t *
   +restart_isc_dhcp_server_command_fn (vlib_main_t * vm,
-  +                                    unformat_input_t * input, 
+  +                                    unformat_input_t * input,
   +                                    vlib_cli_command_t * cmd)
   +{
   +  int rv __attribute__((unused));
   +  /* Wait three seconds... */
   +  vlib_process_suspend (vm, 3.0);
-  +  
+  +
   +  rv = system ("/usr/sbin/service isc-dhcp-server restart");
-  +  
+  +
   +  vlib_cli_output (vm, "Restarted the isc-dhcp-server...");
   +  return 0;
   +}
@@ -144,11 +257,12 @@ You'll need this patch to add the "service restart" command::
   +
 
 
-Using the temporal mac filter plugin
-------------------------------------
+Using the time-based mac filter plugin
+--------------------------------------
 
 If you need to restrict network access for certain devices to specific
-daily time ranges, configure the "mactime" plugin. Enable the feature
+daily time ranges, configure the "mactime" plugin. Add it to the list
+of enabled plugins in /etc/vpp/startup.conf, then enable the feature
 on the NAT "inside" interfaces::
 
   bin mactime_enable_disable GigabitEthernet0/14/0
@@ -169,4 +283,3 @@ Here are some examples::
   bin mactime_add_del_range name unwelcome mac 00:de:ad:be:ef:01 drop-static
   bin mactime_add_del_range name not-during-business-hours mac <mac> drop-range Mon - Fri 7:59 - 18:01
   bin mactime_add_del_range name monday-busines-hours mac <mac> allow-range Mon 7:59 - 18:01
-