summaryrefslogtreecommitdiffstats
path: root/docs/usecases/hgw.md
diff options
context:
space:
mode:
Diffstat (limited to 'docs/usecases/hgw.md')
-rw-r--r--docs/usecases/hgw.md497
1 files changed, 0 insertions, 497 deletions
diff --git a/docs/usecases/hgw.md b/docs/usecases/hgw.md
deleted file mode 100644
index 0b659e9f818..00000000000
--- a/docs/usecases/hgw.md
+++ /dev/null
@@ -1,497 +0,0 @@
-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