Provided by: ubuntu-fan_0.12.16_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)