docs: revise home gateway use-case documentation

Switch to markdown format.

Update docs to current production configs. Add remote software
installation scripts.

Type: docs

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

3 files changed, 498 insertions, 286 deletions

diff --git a/docs/usecases/hgw.md b/docs/usecases/hgw.md
new file mode 100644
index 00000000000..0b659e9f818
--- /dev/null
+++ b/docs/usecases/hgw.md
@@ -0,0 +1,497 @@
+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 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.
+
+System configuration files
+--------------------------
+
+/etc/vpp/startup.conf:
+
+    unix {
+      nodaemon
+      log /var/log/vpp/vpp.log
+      full-coredump
+      cli-listen /run/vpp/cli.sock
+      startup-config /setup.gate
+      poll-sleep-usec 100
+      gid vpp
+    }
+    api-segment {
+      gid vpp
+    }
+    dpdk {
+         dev 0000:03:00.0
+         dev 0000:14:00.0
+         etc.
+     }
+
+     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 }
+     }
+
+/etc/dhcp/dhcpd.conf:
+
+    subnet 192.168.1.0 netmask 255.255.255.0 {
+      range 192.168.1.10 192.168.1.99;
+      option routers 192.168.1.1;
+      option domain-name-servers 8.8.8.8;
+    }
+
+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
+    Port <REDACTED-high-number-port>
+    # Change to no to disable tunnelled clear text passwords
+    PasswordAuthentication no
+
+For your own comfort and safety, do NOT allow password authentication
+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.
+
+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.
+
+VPP Configuration Files
+-----------------------
+
+Here we see a nice use-case for the vpp debug CLI macro expander:
+
+/setup.gate:
+
+    define HOSTNAME vpp1
+    define TRUNK GigabitEthernet3/0/0
+
+    comment { Specific MAC address yields a constant IP address }
+    define TRUNK_MACADDR 48:f8:b3:00:01:01
+    define BVI_MACADDR 48:f8:b3:01:01:02
+
+    comment { inside subnet 192.168.<inside_subnet>.0/24 }
+    define INSIDE_SUBNET 1
+
+    define INSIDE_PORT1 GigabitEthernet6/0/0
+    define INSIDE_PORT2 GigabitEthernet6/0/1
+    define INSIDE_PORT3 GigabitEthernet8/0/0
+    define INSIDE_PORT4 GigabitEthernet8/0/1
+
+    comment { feature selections }
+    define FEATURE_NAT44 comment
+    define FEATURE_CNAT uncomment
+    define FEATURE_DNS comment
+    define FEATURE_IP6 comment
+    define FEATURE_MACTIME uncomment
+
+    exec /setup.tmpl
+
+/setup.tmpl:
+
+    show macro
+
+    set int mac address $(TRUNK) $(TRUNK_MACADDR)
+    set dhcp client intfc $(TRUNK) hostname $(HOSTNAME)
+    set int state $(TRUNK) up
+
+    bvi create instance 0
+    set int mac address bvi0 $(BVI_MACADDR)
+    set int l2 bridge bvi0 1 bvi
+    set int ip address bvi0 192.168.$(INSIDE_SUBNET).1/24
+    set int state bvi0 up
+
+    set int l2 bridge $(INSIDE_PORT1) 1
+    set int state $(INSIDE_PORT1) up
+    set int l2 bridge $(INSIDE_PORT2) 1
+    set int state $(INSIDE_PORT2) up
+    set int l2 bridge $(INSIDE_PORT3) 1
+    set int state $(INSIDE_PORT3) up
+    set int l2 bridge $(INSIDE_PORT4) 1
+    set int state $(INSIDE_PORT4) up
+
+    comment { dhcp server and host-stack access }
+    create tap host-if-name lstack host-ip4-addr 192.168.$(INSIDE_SUBNET).2/24 host-ip4-gw 192.168.$(INSIDE_SUBNET).1
+    set int l2 bridge tap0 1
+    set int state tap0 up
+
+    service restart isc-dhcp-server
+
+    $(FEATURE_NAT44) { nat44 enable users 50 user-sessions 750 sessions 63000 }
+    $(FEATURE_NAT44) { nat44 add interface address $(TRUNK) }
+    $(FEATURE_NAT44) { set interface nat44 in bvi0 out $(TRUNK) }
+
+    $(FEATURE_NAT44) { nat44 add static mapping local 192.168.$(INSIDE_SUBNET).2 22432 external $(TRUNK) 22432 tcp }
+
+    $(FEATURE_CNAT) { cnat snat with $(TRUNK) }
+    $(FEATURE_CNAT) { set interface feature bvi0 ip4-cnat-snat arc ip4-unicast }
+    $(FEATURE_CNAT) { cnat translation add proto tcp real $(TRUNK) 22432 to -> 192.168.$(INSIDE_SUBNET).2 22432 }
+    $(FEATURE_CNAT) { $(FEATURE_DNS) { cnat translation add proto udp real $(TRUNK) 53053 to -> 192.168.$(INSIDE_SUBNET).1 53053 } }
+
+    $(FEATURE_DNS) { $(FEATURE_NAT44) { nat44 add identity mapping external $(TRUNK) udp 53053 } }
+    $(FEATURE_DNS) { bin dns_name_server_add_del 8.8.8.8 }
+    $(FEATURE_DNS) { bin dns_enable_disable }
+
+    comment { set ct6 inside $(TRUNK) }
+    comment { set ct6 outside $(TRUNK) }
+
+    $(FEATURE_IP6) { set int ip6 table $(TRUNK) 0 }
+    $(FEATURE_IP6) { ip6 nd address autoconfig $(TRUNK) default-route }
+    $(FEATURE_IP6) { dhcp6 client $(TRUNK) }
+    $(FEATURE_IP6) { dhcp6 pd client $(TRUNK) prefix group hgw }
+    $(FEATURE_IP6) { set ip6 address bvi0 prefix group hgw ::1/64 }
+    $(FEATURE_IP6) { ip6 nd address autoconfig bvi0 default-route }
+    comment { iPhones seem to need lots of RA messages... }
+    $(FEATURE_IP6) { ip6 nd bvi0 ra-managed-config-flag ra-other-config-flag ra-interval 5 3 ra-lifetime 180 }
+    comment { ip6 nd bvi0 prefix 0::0/0  ra-lifetime 100000 }
+
+
+    $(FEATURE_MACTIME) { bin mactime_add_del_range name cisco-vpn mac a8:b4:56:e1:b8:3e allow-static }
+    $(FEATURE_MACTIME) { bin mactime_add_del_range name old-mac mac <redacted> allow-static }
+    $(FEATURE_MACTIME) { bin mactime_add_del_range name roku mac <redacted> allow-static }
+    $(FEATURE_MACTIME) { bin mactime_enable_disable $(INSIDE_PORT1) }
+    $(FEATURE_MACTIME) { bin mactime_enable_disable $(INSIDE_PORT2) }
+    $(FEATURE_MACTIME) { bin mactime_enable_disable $(INSIDE_PORT3) }
+    $(FEATURE_MACTIME) { bin mactime_enable_disable $(INSIDE_PORT4) }
+
+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).
+
+Reasonably Robust Remote Software Installation
+----------------------------------------------
+
+Here are a couple of scripts which yield a reasonably robust software
+installation scheme.
+
+### Build-host script
+
+    #!/bin/bash
+
+    buildroot=/scratch/vpp-workspace/build-root
+    if [ $1x = "testx" ] ; then
+        subdir="test"
+        ipaddr="192.168.2.48"
+    elif [ $1x = "foox" ] ; then
+        subdir="foo"
+        ipaddr="foo.some.net"
+    elif [ $1x = "barx" ] ; then
+        subdir="bar"
+        ipaddr="bar.some.net"
+    else
+        subdir="test"
+        ipaddr="192.168.2.48"
+    fi
+
+    echo Save current software...
+    ssh -p 22432 $ipaddr "rm -rf /gate_debians.prev"
+    ssh -p 22432 $ipaddr "mv /gate_debians /gate_debians.prev"
+    ssh -p 22432 $ipaddr "mkdir /gate_debians"
+    echo Copy new software to the gateway...
+    scp -P 22432 $buildroot/*.deb $ipaddr:/gate_debians
+    echo Install new software...
+    ssh -p 22432 $ipaddr "nohup /usr/local/bin/vpp-swupdate > /dev/null 2>&1 &"
+
+    for i in 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1
+    do
+        echo Wait for $i seconds...
+        sleep 1
+    done
+
+    echo Try to access the device...
+
+    ssh -p 22432 -o ConnectTimeout=10 $ipaddr "tail -20 /var/log/syslog | grep Ping"
+    if [ $? == 0 ] ; then
+        echo Access test OK...
+    else
+        echo Access failed, wait for configuration restoration...
+        for i in 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1
+        do
+            echo Wait for $i seconds...
+            sleep 1
+        done
+        echo Retry access test
+        ssh -p 22432 -o ConnectTimeout=10 $ipaddr "tail -20 /var/log/syslog | grep Ping"
+        if [ $? == 0 ] ; then
+            echo Access test OK, check syslog on the device
+            exit 1
+        else
+            echo Access test still fails, manual intervention required.
+            exit 2
+        fi
+    fi
+
+    exit 0
+
+### Target script
+
+    #!/bin/bash
+
+    logger "About to update vpp software..."
+    cd /gate_debians
+    service vpp stop
+    sudo dpkg -i *.deb >/dev/null 2>&1 &
+    sleep 20
+    logger "Ping connectivity test..."
+    for i in 1 2 3 4 5 6 7 8 9 10
+    do
+        ping -4 -c 1 yahoo.com
+        if [ $? == 0 ] ; then
+            logger "Ping test OK..."
+            exit 0
+        fi
+    done
+
+    logger "Ping test NOT OK, restore old software..."
+    rm -rf /gate_debians
+    mv /gate_debians.prev /gate_debians
+    cd /gate_debians
+    nohup sudo dpkg -i *.deb >/dev/null 2>&1 &
+    sleep 20
+    logger "Repeat connectivity test..."
+    for i in 1 2 3 4 5 6 7 8 9 10
+    do
+        ping -4 -c 1 yahoo.com
+        if [ $? == 0 ] ; then
+            logger "Ping test OK after restoring old software..."
+            exit 0
+        fi
+    done
+
+    logger "Ping test FAIL after restoring software, manual intervention required"
+    exit 2
+
+Note that the target script **requires** that the userid which invokes
+it will manage to "sudo dpkg ..." without further authentication. If
+you're uncomfortable with the security implications of that
+requirement, you'll need to solve the problem a different
+way. Strongly suggest configuring sshd as described above to minimize
+risk.
+
+
+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
+-------
+
+You\'ll want this addition to src/vpp/vnet/main.c to add the \"service
+restart isc-dhcp-server" and \"service restart vpp\" commands:
+
+    #include <sys/types.h>
+    #include <sys/wait.h>
+
+    static int
+    mysystem (char *cmd)
+    {
+      int rv = 0;
+
+      if (fork())
+        wait (&rv);
+      else
+        execl("/bin/sh", "sh", "-c", cmd);
+
+      if (rv != 0)
+        clib_unix_warning ("('%s') child process returned %d", cmd, rv);
+      return rv;
+    }
+
+    static clib_error_t *
+    restart_isc_dhcp_server_command_fn (vlib_main_t * vm,
+                                        unformat_input_t * input,
+                                        vlib_cli_command_t * cmd)
+    {
+      int rv;
+
+      /* Wait a while... */
+      vlib_process_suspend (vm, 2.0);
+
+      rv = mysystem("/usr/sbin/service isc-dhcp-server restart");
+
+      vlib_cli_output (vm, "Restarted the isc-dhcp-server, status %d...", rv);
+      return 0;
+    }
+
+    /* *INDENT-OFF* */
+    VLIB_CLI_COMMAND (restart_isc_dhcp_server_command, static) =
+    {
+      .path = "service restart isc-dhcp-server",
+      .short_help = "restarts the isc-dhcp-server",
+      .function = restart_isc_dhcp_server_command_fn,
+    };
+    /* *INDENT-ON* */
+
+    static clib_error_t *
+    restart_dora_tunnels_command_fn (vlib_main_t * vm,
+                                     unformat_input_t * input,
+                                     vlib_cli_command_t * cmd)
+    {
+      int rv;
+
+      /* Wait three seconds... */
+      vlib_process_suspend (vm, 3.0);
+
+      rv = mysystem ("/usr/sbin/service dora restart");
+
+      vlib_cli_output (vm, "Restarted the dora tunnel service, status %d...", rv);
+      return 0;
+    }
+
+    /* *INDENT-OFF* */
+    VLIB_CLI_COMMAND (restart_dora_tunnels_command, static) =
+    {
+      .path = "service restart dora",
+      .short_help = "restarts the dora tunnel service",
+      .function = restart_dora_tunnels_command_fn,
+    };
+    /* *INDENT-ON* */
+
+    static clib_error_t *
+    restart_vpp_service_command_fn (vlib_main_t * vm,
+                                    unformat_input_t * input,
+                                    vlib_cli_command_t * cmd)
+    {
+      (void) mysystem ("/usr/sbin/service vpp restart");
+      return 0;
+    }
+
+    /* *INDENT-OFF* */
+    VLIB_CLI_COMMAND (restart_vpp_service_command, static) =
+    {
+      .path = "service restart vpp",
+      .short_help = "restarts the vpp service, be careful what you wish for",
+      .function = restart_vpp_service_command_fn,
+    };
+    /* *INDENT-ON* */
+
+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. 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
+    bin mactime_enable_disable GigabitEthernet0/14/1
+    ...
+
+Create the required src-mac-address rule database. There are 4 rule
+entry types:
+
+-   allow-static - pass traffic from this mac address
+-   drop-static - drop traffic from this mac address
+-   allow-range - pass traffic from this mac address at specific times
+-   drop-range - drop traffic from this mac address at specific times
+
+Here are some examples:
+
+    bin mactime_add_del_range name alarm-system mac 00:de:ad:be:ef:00 allow-static
+    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
diff --git a/docs/usecases/homegateway.rst b/docs/usecases/homegateway.rst
deleted file mode 100644
index f419c4ecb29..00000000000
--- a/docs/usecases/homegateway.rst
+++ /dev/null
@@ -1,285 +0,0 @@
-.. _homegateway:
-
-.. toctree::
-
-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.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.
-
-Configuration files
--------------------
-
-/etc/vpp/startup.conf::
-
- unix {
-   nodaemon
-   log /var/log/vpp/vpp.log
-   full-coredump
-   cli-listen /run/vpp/cli.sock
-   startup-config /setup.gate
-   poll-sleep-usec 100
-   gid vpp
- }
- api-segment {
-   gid vpp
- }
- dpdk {
-      dev 0000:03:00.0
-      dev 0000:14:00.0
-      etc.
-  }
-
-  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 }
-  }
-
-/etc/dhcp/dhcpd.conf::
-
- subnet 192.168.1.0 netmask 255.255.255.0 {
-   range 192.168.1.10 192.168.1.99;
-   option routers 192.168.1.1;
-   option domain-name-servers 8.8.8.8;
- }
-
-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
- Port <REDACTED-high-number-port>
- # Change to no to disable tunnelled clear text passwords
- PasswordAuthentication no
-
-For your own comfort and safety, do NOT allow password authentication
-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 (/setup.gate)::
-
-  comment { This is the WAN interface }
-  set int state GigabitEthernet3/0/0 up
-  comment { set int mac address GigabitEthernet3/0/0 mac-to-clone-if-needed }
-  set dhcp client intfc GigabitEthernet3/0/0 hostname vppgate
-
-  comment { Create a BVI loopback interface}
-  loop create
-  set int l2 bridge loop0 1 bvi
-  set int ip address loop0 192.168.1.1/24
-  set int state loop0 up
-
-  comment { Add more inside interfaces as needed ... }
-  set int l2 bridge GigabitEthernet0/14/0 1
-  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
-  set int l2 bridge tap0 1
-  set int state tap0 up
-
-  comment { Configure NAT}
-  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 { if you want to use the vpp DNS server, add the following }
-  comment { Remember to adjust the isc-dhcp-server configuration appropriately }
-  comment { nat44 add identity mapping external GigabitEthernet3/0/0 udp 53053  }
-  comment { bin dns_name_server_add_del 8.8.8.8 }
-  comment { bin dns_name_server_add_del 68.87.74.166 }
-  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
--------
-
-You'll need this patch to add the "service restart" command::
-
-  diff --git a/src/vpp/vnet/main.c b/src/vpp/vnet/main.c
-  index 6e136e19..69189c93 100644
-  --- a/src/vpp/vnet/main.c
-  +++ b/src/vpp/vnet/main.c
-  @@ -18,6 +18,8 @@
-   #include <vlib/unix/unix.h>
-   #include <vnet/plugin/plugin.h>
-   #include <vnet/ethernet/ethernet.h>
-  +#include <vnet/ip/ip4_packet.h>
-  +#include <vnet/ip/format.h>
-   #include <vpp/app/version.h>
-   #include <vpp/api/vpe_msg_enum.h>
-   #include <limits.h>
-  @@ -400,6 +402,63 @@ VLIB_CLI_COMMAND (test_crash_command, static) = {
-
-   #endif
-
-  +static clib_error_t *
-  +restart_isc_dhcp_server_command_fn (vlib_main_t * vm,
-  +                                    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;
-  +}
-  +
-  +/* *INDENT-OFF* */
-  +VLIB_CLI_COMMAND (restart_isc_dhcp_server_command, static) = {
-  +  .path = "service restart isc-dhcp-server",
-  +  .short_help = "restarts the isc-dhcp-server",
-  +  .function = restart_isc_dhcp_server_command_fn,
-  +};
-  +/* *INDENT-ON* */
-  +
-
-
-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. 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
-  bin mactime_enable_disable GigabitEthernet0/14/1
-  ...
-
-Create the required src-mac-address rule database. There are 4 rule
-entry types:
-
-* allow-static - pass traffic from this mac address
-* drop-static - drop traffic from this mac address
-* allow-range - pass traffic from this mac address at specific times
-* drop-range - drop traffic from this mac address at specific times
-
-Here are some examples::
-
-  bin mactime_add_del_range name alarm-system mac 00:de:ad:be:ef:00 allow-static
-  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
diff --git a/docs/usecases/index.rst b/docs/usecases/index.rst
index 062b225732b..21f5b140fe7 100644
--- a/docs/usecases/index.rst
+++ b/docs/usecases/index.rst
@@ -15,7 +15,7 @@ extensive list, but should give a sampling of the many features contained in FD.
    vmxnet3
    acls
    vppcloud
-   homegateway
+   hgw
    contiv/index.rst
    networksim
    webapp