5 Using VPP as a Home Gateway
6 ===========================
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.
13 At a minimum, install sshd and the isc-dhcp-server. If you prefer, you
19 /etc/vpp/startup.conf::
23 log /var/log/vpp/vpp.log
25 cli-listen /run/vpp/cli.sock
26 startup-config /setup.gate
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 }
49 /etc/dhcp/dhcpd.conf::
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;
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.
60 /etc/default/isc-dhcp-server::
62 # On which interfaces should the DHCP server (dhcpd) serve DHCP requests?
63 # Separate multiple interfaces with spaces, e.g. "eth0 eth1".
67 /etc/ssh/sshd_config::
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
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
79 vpp configuration (/setup.gate)::
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
86 comment { Create a BVI loopback interface}
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
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
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
101 comment { Configure NAT}
102 nat44 add interface address GigabitEthernet3/0/0
103 set interface nat44 in loop0 out GigabitEthernet3/0/0
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
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
117 Systemd configuration
118 ---------------------
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.
125 Configure /etc/systemd/resolved.conf as follows.
127 /etc/systemd/resolved.conf::
139 Netplan configuration
140 ---------------------
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>/...
148 /etc/netplan-01-netcfg.yaml::
150 # This file describes the network interfaces available on your system
151 # For more information, see netplan(5).
158 addresses: [192.168.2.254/24]
159 gateway4: 192.168.2.100
164 /etc/systemd/network-10.enp4s0.network::
173 ConfigureWithoutCarrier=true
174 Address=192.168.2.254/24
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.
180 Installing new vpp software
181 ---------------------------
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.
190 Installing a new vpp image via ssh to 192.168.1.2::
192 # nohup dpkg -i *.deb >/dev/null 2>&1 &
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).
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.
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.
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.
216 You'll need this patch to add the "service restart" command::
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
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>
231 @@ -400,6 +402,63 @@ VLIB_CLI_COMMAND (test_crash_command, static) = {
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)
240 + int rv __attribute__((unused));
241 + /* Wait three seconds... */
242 + vlib_process_suspend (vm, 3.0);
244 + rv = system ("/usr/sbin/service isc-dhcp-server restart");
246 + vlib_cli_output (vm, "Restarted the isc-dhcp-server...");
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,
260 Using the time-based mac filter plugin
261 --------------------------------------
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::
268 bin mactime_enable_disable GigabitEthernet0/14/0
269 bin mactime_enable_disable GigabitEthernet0/14/1
272 Create the required src-mac-address rule database. There are 4 rule
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
280 Here are some examples::
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