Provided by: ubuntu-fan_0.12.10_all 
NAME
fanatic - fan bridge configuration and test wizard
SYNOPSIS
fanatic [<cmd> [<arg> ...]]
fanatic configure
fanatic deconfigure
fanatic test
DESCRIPTION
fanatic is the configuration and test wizard for Fan networking. It is designed to simplify the process
of configuring persistent Fan bridges. It will also configure both LXD and Docker to use those bridges
as required.
It also can be used to configure Fan networking without any user interaction (see NON-INTERACTIVE USAGE
below).
A Fan network is a mechanism for expanding the range of IP addresses available to a system. It is most
useful for containers systems such as Docker and LXC/LXD, but it can be used in other contexts as well.
TERMINOLOGY
The Fan mapping is defined by a combination of an underlay and an overlay address. Each of these is
defined in CIDR network address form. The overlay prefix defines the overall network prefix for the
overlay slice. The underlay prefix defines the prefix bits to strip to obtain the slice identifier.
This is concatenated with the overlay prefix to calculate the overlay slice which is the range of the Fan
network that is assigned to a specific single address within the underlay network. This way each address
within a 192.168.0.0/16 underlay, mapped to a 250.0.0.0/8 overlay would cover the range:
250.x.y.0/(8 + (32-16) = 24)
Thus 8 (32-24) address bits will equate to 254 additional addresses for each address mapped from the
underlay network (you cannot use the first and last address within an IPv4 subnet).
The following diagram shows a more advanced example with three hosts which will be joined in a single Fan
network. Two of the hosts are in the same subnet (192.168.12.0/24) and the other in a separate subnet
(192.168.13.0/24). Since all three will share the same overlay network (250.0.0.0/8) we would use an
underlay of 192.168.0.0/16. The choice of the underlay prefix depends on the network layout which is
mapped into an overlay network (which overlay prefix is used does not matter). So, if we really only
were interested in joining 192.168.12/13.0/24, we could use an underlay of 192.168.12.0/23 which would
maximize the number of addresses per slice but the CIDR network addresses of the slices would be less
obvious to read.
+-------------+
... ----+ Router +---------------------+
+------+------+ |
| |
+------+------+ |
| | |
+-------------+----+ +----+-------------+ +----+-------------+
| 192.168.12.13/24 | | 192.168.12.14/24 | | 192.168.13.13/24 |
+------------------+ +------------------+ +------------------+
. . .
. . .
+----------------+ +----------------+ +----------------+
| 250.12.13.1/24 | | 250.12.14.1/24 | | 250.13.13.1/24 |
+----------------+ +----------------+ +----------------+
| 250.0.0.0/8 |
+------------------------------------------------------+
For the example above, a /16 over /8 layout was chosen because that moves numbers in the dotted decimal
notation in a way that is simpler to read.
The overlay prefix is 8 bits. The underlay prefix takes the lower 16 bits of each host’s physical
interface and shifts those left until hitting the least significant bit of the overlay (32-16-8=8). The
result is, each interface of the host that is part of the Fan overlay gets a /24 (=8+16) slice of the Fan
network. The 250.x.y.1 address is assigned to the fan-250 bridge on each host and would act as the
gateway address of any container that runs within the overlay slice.
COMMAND SYNTAX
Running fanatic with no arguments is equivalent to running fanatic configure.
fanatic [configure]
Interactively configure the local system for Fan. This action will identify the interface to be
used and offer to configure an appropriate Fan over the addresses on that interface. It will
further offer to configure LXD and/or Docker to use this interface. Finally, it will offer to
test the configuration as applied both locally and with an optional remote host.
fanatic deconfigure
Reverses the interactive configuration above. It will deconfigure both LXD and Docker (if
configured) and then deconfigure the Fan. These steps are only performed if the configuration was
generated by fanatic.
fanatic test
Runs the testing phase of the interactive setup. This action enables retesting of a previously
configured system. Only those pieces configured will be tested.
fanatic help
Shows basic help including usage information and pointers to further help on use of fanatic.
NON-INTERACTIVE USAGE
It is possible to run any sub-phase of the configure, deconfigure or test phases, which are done by
fanatic in interactive mode, individually and without user interaction:
fanatic enable-fan -u <underlay> -o <overlay>
Configure a Fan over the specified interface.
fanatic disable-fan -u <underlay> -o <overlay>
Deconfigure a Fan over the specified interface.
fanatic enable-lxd -u <underlay> -o <overlay>
Configure LXD for use on the Fan over the specified interface.
fanatic disable-lxd -u <underlay> -o <overlay>
Deconfigure LXD for use on the Fan over the specified interface.
fanatic enable-docker -u <underlay> -o <overlay>
Configure docker for use on the Fan over the specified interface.
fanatic disable-docker -u <underlay> -o <overlay>
Deconfigure docker for use on the Fan over the specified interface.
test-host -u <underlay> -o <overlay> -r <remote host IP>
Test host-to-host Fan functionality. This requires you to be running the same test script on both
hosts in the test.
test-local-lxd -u <underlay> -o <overlay>
Test the local LXD configuration by creating a container and running host-to-host testing against
that container.
test-local-docker -u <underlay> -o <overlay>
Test the local Docker configuration by creating a container and running host-to-host testing
against that container.
USE WITH LXC/LXD
Once the Fan bridges are configured (and LXD is installed), LXC/LXD can be configured to use a specific
Fan bridge for the network device of containers. This can be done by either modifying the default
template or by creating a separate template which can be used when creating containers. The latter is
what fanatic enable-lxd does internally. The same could be done manually by setting link and MTU as shown
below:
lxc.network.link = <Fan bridge name>
lxc.network.mtu = 1450
USE WITH DOCKER
Once the Fan bridges are configured (and docker installed), a docker network must be configured (similar
to the LXD template). New containers can then be configured to use the Fan network. This is how the
fanatic enable-docker call internally works. The new network will be a bridge network type named after
the name of the Fan bridge which is to be used. If this were done manually, the docker command would look
like:
# sudo docker network create --driver bridge \
-o "com.docker.network.bridge.name=<bridge name>" \
-o "com.docker.network.driver.mtu=1450" \
--subnet <overlay> --ip-range <slice subnet> \
--gateway <slice host> \
--aux-address "reserved0=<slice host>" \
<bridge name>
This defines the complete Fan overlay network to be accessed through the Fan bridge given and limits the
scope of addresses used for containers to a given slice subnet (which is the CIDR notation of the Fan
overlay slice that is assigned to the given Fan bridge). All addresses, within that range, which are not
to be used need to be declared individually. Usually this is the slice host which is the address of the
host within the overlay slice (and assigned to the Fan bridge). For example, if the overlay network were
a 250.0.0.0/8 and the address of the host in the underlay address space were u.u.x.y/16 the Fan bridge
would be called fan-250 and have a 250.x.y.1/24 assigned to it which would be declared as the gateway for
the 250.x.y.0/24 overlay slice.
LIMITATIONS
Since docker (at the time of writing) does not support to allow an external DHCP service to be used,
there is no way to safely mix docker and LXD containers in the same Fan overlay slice. Both types of
containers can be mixed though in the same Fan overlay, as long as they use their individual slice.
EXAMPLES
Assuming that a Fan network should be attached to the primary interface of the host without any user
interaction, the first step is to figure out which is the default interface:
# ip route show | awk '$1 == "default"{print $NF}'
ens3
Next we need to find out what IPv4 address this interface is configured to:
# ip address show ens3 | awk '$1 == "inet"{print $2}'
192.168.2.120/24
If all hosts which participate in the Fan network are located in 192.168.2.0/24, then we can use a /24
underlay address and get 65535 addresses per slice instead of the 254 if we had to include hosts from the
192.168.0.0/16 range.
For all of the following commands of this example we use the address of the interface with a prefix of 20
which assumes we only care for hosts in 192.168.[0-15].0/24 and results in 4095 addresses per slice.
Using the interface address tells fanatic to only configure this single interface.
# sudo fanatic enable-fan -u 192.168.2.120/20 -o 250.0.0.0/8
configuring fan underlay:192.168.2.120/20 overlay:250.0.0.0/8
# sudo fanatic enable-lxd -u 192.168.2.120/20 -o 250.0.0.0/8
configuring LXD for underlay:192.168.2.120/20 \
overlay:250.0.0.0/8 (fan-250)
Profile fan-250 created
# sudo fanatic test-local-lxd -u 192.168.2.120/20 -o 250.0.0.0/8
local lxd test: creating test container (Ubuntu:lts) ...
Creating fanatic-test
Starting fanatic-test
lxd test: Waiting for addresses on eth0 ...
lxd test: Waiting for addresses on eth0 ...
lxd test: Waiting for addresses on eth0 ...
test master: ping test (250.39.132.96) ...
test slave: ping test (250.39.128.1) ...
test master: ping test ... PASS
test master: short data test (250.39.128.1 -> 250.39.132.96) ...
test slave: ping test ... PASS
test slave: short data test (250.39.132.96 -> 250.39.128.1) ...
test slave: short data ... PASS
test master: short data ... PASS
test master: long data test (250.39.128.1 -> 250.39.132.96) ...
test slave: long data test (250.39.132.96 -> 250.39.128.1) ...
test master: long data ... PASS
test slave: long data ... PASS
local lxd test: destroying test container ...
local lxd test: test complete PASS (master=0 slave=0)
SEE ALSO
fanctl(8), /usr/share/doc/ubuntu-fan/README
AUTHOR(s)
Andy Whitcroft <apw@canonical.com>,
Stefan Bader <stefan.bader@canonical.com>
July 25, 2017 FANATIC(8)