diff options
Diffstat (limited to 'docs/usecases/homegateway.rst')
| -rw-r--r-- | docs/usecases/homegateway.rst | 149 |
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 - |