docs/usecases/homegateway.rst

   1 .. _homegateway:
   2
   3 .. toctree::
   4
   5 Using VPP as a Home Gateway
   6 ===========================
   7
   8 Vpp running on a small system (with appropriate NICs) makes a fine
   9 home gateway. The resulting system performs far in excess of
  10 requirements: a TAG=vpp_debug image runs at a vector size of ~1.2
  11 terminating a 150-mbit down / 10-mbit up cable modem connection.
  12
  13 At a minimum, install sshd and the isc-dhcp-server. If you prefer, you
  14 can use dnsmasq.
  15
  16 Configuration files
  17 -------------------
  18
  19 /etc/vpp/startup.conf::
  20
  21  unix {
  22    nodaemon
  23    log /var/log/vpp/vpp.log
  24    full-coredump
  25    cli-listen /run/vpp/cli.sock
  26    startup-config /setup.gate
  27    poll-sleep-usec 100
  28    gid vpp
  29  }
  30  api-segment {
  31    gid vpp
  32  }
  33  dpdk {
  34       dev 0000:03:00.0
  35       dev 0000:14:00.0
  36       etc.
  37   }
  38
  39   plugins {
  40         ## Disable all plugins, selectively enable specific plugins
  41         ## YMMV, you may wish to enable other plugins (acl, etc.)
  42         plugin default { disable }
  43         plugin dpdk_plugin.so { enable }
  44         plugin nat_plugin.so { enable }
  45         ## if you plan to use the time-based MAC filter
  46         plugin mactime_plugin.so { enable }
  47   }
  48
  49 /etc/dhcp/dhcpd.conf::
  50
  51  subnet 192.168.1.0 netmask 255.255.255.0 {
  52    range 192.168.1.10 192.168.1.99;
  53    option routers 192.168.1.1;
  54    option domain-name-servers 8.8.8.8;
  55  }
  56
  57 If you decide to enable the vpp dns name resolver, substitute
  58 192.168.1.2 for 8.8.8.8 in the dhcp server configuration.
  59
  60 /etc/default/isc-dhcp-server::
  61
  62   # On which interfaces should the DHCP server (dhcpd) serve DHCP requests?
  63   #     Separate multiple interfaces with spaces, e.g. "eth0 eth1".
  64   INTERFACESv4="lstack"
  65   INTERFACESv6=""
  66
  67 /etc/ssh/sshd_config::
  68
  69  # What ports, IPs and protocols we listen for
  70  Port <REDACTED-high-number-port>
  71  # Change to no to disable tunnelled clear text passwords
  72  PasswordAuthentication no
  73
  74 For your own comfort and safety, do NOT allow password authentication
  75 and do not answer ssh requests on port 22. Experience shows several
  76 hack attempts per hour on port 22, but none (ever) on random
  77 high-number ports.
  78
  79 vpp configuration (/setup.gate)::
  80
  81   comment { This is the WAN interface }
  82   set int state GigabitEthernet3/0/0 up
  83   comment { set int mac address GigabitEthernet3/0/0 mac-to-clone-if-needed }
  84   set dhcp client intfc GigabitEthernet3/0/0 hostname vppgate
  85
  86   comment { Create a BVI loopback interface}
  87   loop create
  88   set int l2 bridge loop0 1 bvi
  89   set int ip address loop0 192.168.1.1/24
  90   set int state loop0 up
  91
  92   comment { Add more inside interfaces as needed ... }
  93   set int l2 bridge GigabitEthernet0/14/0 1
  94   set int state GigabitEthernet0/14/0 up
  95
  96   comment { dhcp server and host-stack access }
  97   create tap host-if-name lstack host-ip4-addr 192.168.1.2/24 host-ip4-gw 192.168.1.1
  98   set int l2 bridge tap0 1
  99   set int state tap0 up
 100
 101   comment { Configure NAT}
 102   nat44 add interface address GigabitEthernet3/0/0
 103   set interface nat44 in loop0 out GigabitEthernet3/0/0
 104
 105   comment { allow inbound ssh to the <REDACTED-high-number-port> }
 106   nat44 add static mapping local 192.168.1.2 <REDACTED> external GigabitEthernet3/0/0 <REDACTED> tcp
 107
 108   comment { if you want to use the vpp DNS server, add the following }
 109   comment { Remember to adjust the isc-dhcp-server configuration appropriately }
 110   comment { nat44 add identity mapping external GigabitEthernet3/0/0 udp 53053  }
 111   comment { bin dns_name_server_add_del 8.8.8.8 }
 112   comment { bin dns_name_server_add_del 68.87.74.166 }
 113   comment { bin dns_enable_disable }
 114   comment { see patch below, which adds these commands }
 115   service restart isc-dhcp-server
 116
 117 Systemd configuration
 118 ---------------------
 119
 120 In a typical home-gateway use-case, vpp owns the one-and-only WAN link
 121 with a prayer of reaching the public internet. Simple things like
 122 updating distro software requires use of the "lstack" interface
 123 created above, and configuring a plausible upstream DNS name resolver.
 124
 125 Configure /etc/systemd/resolved.conf as follows.
 126
 127 /etc/systemd/resolved.conf::
 128
 129   [Resolve]
 130   DNS=8.8.8.8
 131   #FallbackDNS=
 132   #Domains=
 133   #LLMNR=no
 134   #MulticastDNS=no
 135   #DNSSEC=no
 136   #Cache=yes
 137   #DNSStubListener=yes
 138
 139 Netplan configuration
 140 ---------------------
 141
 142 If you want to configure a static IP address on one of your
 143 home-gateway Ethernet ports on Ubuntu 18.04, you'll need to configure
 144 netplan. Netplan is relatively new. It and the network manager GUI and
 145 can be cranky. In the configuration shown below,
 146 s/enp4s0/<your-interface>/...
 147
 148 /etc/netplan-01-netcfg.yaml::
 149
 150   # This file describes the network interfaces available on your system
 151   # For more information, see netplan(5).
 152   network:
 153     version: 2
 154     renderer: networkd
 155     ethernets:
 156       enp4s0:
 157         dhcp4: no
 158         addresses: [192.168.2.254/24]
 159         gateway4: 192.168.2.100
 160         nameservers:
 161           search: [my.local]
 162           addresses: [8.8.8.8]
 163
 164 /etc/systemd/network-10.enp4s0.network::
 165
 166   [Match]
 167   Name=enp4s0
 168
 169   [Link]
 170   RequiredForOnline=no
 171
 172   [Network]
 173   ConfigureWithoutCarrier=true
 174   Address=192.168.2.254/24
 175
 176 Note that we've picked an IP address for the home gateway which is on
 177 an independent unrouteable subnet. This is handy for installing (and
 178 possibly reverting) new vpp software.
 179
 180 Installing new vpp software
 181 ---------------------------
 182
 183 If you're **sure** that a given set of vpp Debian packages will
 184 install and work properly, you can install them while logged into the
 185 gateway via the lstack / nat path. This procedure is a bit like
 186 standing on a rug and yanking it. If all goes well, a perfect
 187 back-flip occurs.  If not, you may wish that you'd configured a static
 188 IP address on a reserved Ethernet interface as described above.
 189
 190 Installing a new vpp image via ssh to 192.168.1.2::
 191
 192   # nohup dpkg -i *.deb >/dev/null 2>&1 &
 193
 194 Within a few seconds, the inbound ssh connection SHOULD begin to respond
 195 again. If it does not, you'll have to debug the issue(s).
 196
 197 Testing new software
 198 --------------------
 199
 200 If you frequently test new home gateway software, it may be handy to
 201 set up a test gateway behind your production gateway. This testing
 202 methodology reduces complaints from family members, to name one benefit.
 203
 204 Change the inside network (dhcp) subnet from 192.168.1.0/24 to
 205 192.168.3.0/24, change the (dhcp) advertised router to 192.168.3.1,
 206 reconfigure the vpp tap interface addresses onto the 192.168.3.0/24
 207 subnet, and you should be all set.
 208
 209 This scenario nats traffic twice: first, from the 192.168.3.0/24
 210 network onto the 192.168.1.0/24 network. Next, from the 192.168.1.0/24
 211 network onto the public internet.
 212
 213 Patches
 214 -------
 215
 216 You'll need this patch to add the "service restart" command::
 217
 218   diff --git a/src/vpp/vnet/main.c b/src/vpp/vnet/main.c
 219   index 6e136e19..69189c93 100644
 220   --- a/src/vpp/vnet/main.c
 221   +++ b/src/vpp/vnet/main.c
 222   @@ -18,6 +18,8 @@
 223    #include <vlib/unix/unix.h>
 224    #include <vnet/plugin/plugin.h>
 225    #include <vnet/ethernet/ethernet.h>
 226   +#include <vnet/ip/ip4_packet.h>
 227   +#include <vnet/ip/format.h>
 228    #include <vpp/app/version.h>
 229    #include <vpp/api/vpe_msg_enum.h>
 230    #include <limits.h>
 231   @@ -400,6 +402,63 @@ VLIB_CLI_COMMAND (test_crash_command, static) = {
 232
 233    #endif
 234
 235   +static clib_error_t *
 236   +restart_isc_dhcp_server_command_fn (vlib_main_t * vm,
 237   +                                    unformat_input_t * input,
 238   +                                    vlib_cli_command_t * cmd)
 239   +{
 240   +  int rv __attribute__((unused));
 241   +  /* Wait three seconds... */
 242   +  vlib_process_suspend (vm, 3.0);
 243   +
 244   +  rv = system ("/usr/sbin/service isc-dhcp-server restart");
 245   +
 246   +  vlib_cli_output (vm, "Restarted the isc-dhcp-server...");
 247   +  return 0;
 248   +}
 249   +
 250   +/* *INDENT-OFF* */
 251   +VLIB_CLI_COMMAND (restart_isc_dhcp_server_command, static) = {
 252   +  .path = "service restart isc-dhcp-server",
 253   +  .short_help = "restarts the isc-dhcp-server",
 254   +  .function = restart_isc_dhcp_server_command_fn,
 255   +};
 256   +/* *INDENT-ON* */
 257   +
 258
 259
 260 Using the time-based mac filter plugin
 261 --------------------------------------
 262
 263 If you need to restrict network access for certain devices to specific
 264 daily time ranges, configure the "mactime" plugin. Add it to the list
 265 of enabled plugins in /etc/vpp/startup.conf, then enable the feature
 266 on the NAT "inside" interfaces::
 267
 268   bin mactime_enable_disable GigabitEthernet0/14/0
 269   bin mactime_enable_disable GigabitEthernet0/14/1
 270   ...
 271
 272 Create the required src-mac-address rule database. There are 4 rule
 273 entry types:
 274
 275 * allow-static - pass traffic from this mac address
 276 * drop-static - drop traffic from this mac address
 277 * allow-range - pass traffic from this mac address at specific times
 278 * drop-range - drop traffic from this mac address at specific times
 279
 280 Here are some examples::
 281
 282   bin mactime_add_del_range name alarm-system mac 00:de:ad:be:ef:00 allow-static
 283   bin mactime_add_del_range name unwelcome mac 00:de:ad:be:ef:01 drop-static
 284   bin mactime_add_del_range name not-during-business-hours mac <mac> drop-range Mon - Fri 7:59 - 18:01
 285   bin mactime_add_del_range name monday-busines-hours mac <mac> allow-range Mon 7:59 - 18:01