minirouter is a simple tool, run in a VM, that orchestrates various router
functions such as DHCP, DNS, IPv4/IPv6 assignments, and, of course, routing.
minirouter tool is interfaced by minimega's
router API, described
below, and the minimega distribution provides a prebuilt
minirouter currently supports several protocols and capabilities including
DHCP, DNS, router advertisements, OSPF, and static routes. It can route in
excess of 40 gigabits per second when running as a container.
minirouter can run on bare metal, as a container, or a KVM image.
A prebuilt, busybox-based, container image is available
This image can be built using the build script in
misc/minirouter in the
minimega repo. The minirouter image is configured to start miniccc and
minirouter at startup.
You can also build a disk image for booting in KVM. First, copy the miniccc and minirouter binaries into the overlay directory:
$ cp bin/minirouter misc/vmbetter_configs/minirouter_overlay $ cp bin/minirouter misc/vmbetter_configs/minirouter_overlay
Then build the image with vmbetter (see the vmbetter tutorial for more information)
$ ./bin/vmbetter -branch stable -level debug misc/vmbetter_configs/minirouter.conf
minirouter is simply a Linux binary that can run on any Linux system. You do not specifically need to build an image to run it, although it is more convenient.
To use minirouter, you must have the miniccc agent running, and
minirouter must be able to access the miniccc tool and files directory
minirouter -h for default paths).
bird, all of which
must be installed but not already running.
minirouter must run as root.
Beyond these few requirements,
minirouter should run on most linux
VMs running the
minirouter tool must have
miniccc running as well (this is
already configured in the prebuilt
minirouter image). Configuring a
minirouter image is similar to describing and launching a VM in minimega. One
first describes the router parameters, and then commits the configuration,
which causes the minirouter tool to set IPs and start other necessary tools on
the router VM.
minirouter VMs must be running before configuring the router,
and configurations can be updated at runtime.
router API requires a VM name or ID when configuring a router. For
example, to set a static IP on a running
minirouter VM named 'foo':
minimega$ router foo interface 0 10.0.0.1/24 minimega$ router foo commit
While the first command above sets the configuration for the router image, the
second line actually commits the configuration by sending commands to
minirouter over the command and control layer in minimega. Multiple
configuration commands can be issued and then later committed with a single
Routers often have statically assigned IP addresses and
supports both IPv4 and IPv6 address specification using the
For example, to add the IP 10.0.0.1/24 to the second interface on a
minimega$ vm config net a b # add an ip to interface b (index 1) minimega$ router foo interface 1 10.0.0.1/24
Multiple addresses can be added to the same interface as well:
minimega$ router foo interface 0 10.0.0.1/24 minimega$ router foo interface 0 2001:1::1/64
We use dnsmasq to provide
DHCP, router advertisements, and DNS capabilities in
minirouter. dnsmasq has
extensive support for various DHCP and DNS options, and
minirouter uses a
subset of common capabilities.
minirouter supports DHCP assignment of connected clients and supports both IP
range and static IP assignment.
minirouter also supports several DHCP
options such as setting the default gateway and nameserver.
For example, to serve the IP range 10.0.0.2 - 10.0.0.254 on a 10.0.0.0/24 network, specify the network prefix and DHCP range:
minimega$ router foo dhcp 10.0.0.0 range 10.0.0.2 10.0.0.254
You can also specify static IP assignments with a MAC/IP address pair:
minimega$ router foo dhcp 10.0.0.0 static 00:11:22:33:44:55 10.0.0.100
Additionally, you can specify the default gateway and nameserver:
minimega$ router foo dhcp 10.0.0.0 router 10.0.0.254 minimega$ router foo dhcp 10.0.0.0 dns 22.214.171.124
All of these DHCP options can be used together in a single DHCP specification,
and multiple DHCP servers can be specified on a single
(for serving DHCP on multiple interfaces/networks).
minirouter supports IPv6 router advertisements using the Neighbor Discovery
Protocol to enable
addressing. To enable route advertisements simply provide the subnet. Only the
subnet prefix is required as SLAAC addressing requires a /64 and is implied.
minimega$ router foo ra 2001:1:2:3::
minirouter provides a simple mechanism to add
AAAA records for
any host/IP (including IPv6) pair. Simply specify the host and IP address of
minimega$ router foo dns 126.96.36.199 foo.com
minirouter uses the bird routing daemon to
provide routing using a variety of protocols. Currently,
supports static and OSPF routes. Support for BGP and others are planned.
Bird is a lightweight routing daemon that scales well. In our tests we were able to scale minirouter with bird to at least 40 gigabit.
minirouter makes possible adding IPv4 or IPv6 static routes by simply
specifying the destination network and net-hop IP. For example, to add a static
IPv4 route for the 188.8.131.52/24 network via 184.108.40.206:
minimega$ router foo route static 220.127.116.11/24 18.104.22.168
Or to specify a default route:
minimega$ router foo route static 0.0.0.0/0 22.214.171.124
IPv6 routes are added in the same way:
minimega$ router foo route static 2001:1:2:3::/64 2001:1:2:3::1
minirouter provides basic support for OSPF and OSPFv3 (IPv6 enabled OSPF) by
specifying the OSPF area and interface to include in the area. OSPF generally
supports specifying networks and many other options, which
minirouter may add
in the future. For now, specifying an interface (and all of the networks on
that interface) is provided. Both OSPF and OSPFv3 are enabled by
Interfaces are identified by the index in which they were added by the
vm config net API. For example, to add the first and third network of the
router VM to area 0 in an OSPF route:
minimega$ vm config net a b c # add interface 'a', index 0 minimega$ router foo route ospf 0 0 # add interface 'c', index 2 minimega$ router foo route ospf 0 2