diff options
Diffstat (limited to 'docs/usecases/homegateway.rst')
| -rw-r--r-- | docs/usecases/homegateway.rst | 285 |
1 files changed, 0 insertions, 285 deletions
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 |