summaryrefslogtreecommitdiffstats
path: root/docs/usecases/homegateway.rst
diff options
context:
space:
mode:
Diffstat (limited to 'docs/usecases/homegateway.rst')
-rw-r--r--docs/usecases/homegateway.rst285
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