FANATIC(8)

📦 version 0.12.17, in ubuntu jammy, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 FANATIC 💖 — the fanatic(8) manual, but make it make sense

okay bestie, sit down, hydrate, because we're learning fanatic(8) and honestly? it's giving main character energy. this is the section-8 manual page, so it's system admin territory, but i promise we'll get through it together 🫶

✨ NAME ✨

fanatic — the fan bridge configuration and test wizard 💅

✨ SYNOPSIS ✨

fanatic [<cmd> [<arg> ...]]
fanatic configure
fanatic deconfigure
fanatic test

✨ DESCRIPTION ✨

so fanatic is the configuration and test wizard for Fan networking. it exists to make configuring persistent Fan bridges so much less of a whole thing. like, it was literally designed to simplify that process. it'll also set up both LXD and Docker to use those bridges when they need to. slay ✨

it can ALSO configure Fan networking with zero user interaction — no vibes required, no clicking, no nothing. (peep NON-INTERACTIVE USAGE down below 👇)

and what even IS a Fan network, you ask? it's a mechanism for expanding the range of IP addresses available to a system. it's most useful for container systems like Docker and LXC/LXD, but ngl it can be used in other contexts too. versatile icon 🌈

🌸 TERMINOLOGY 🌸

okay this is the part where we lock in, because the words matter.

the Fan mapping is defined by a combination of an underlay and an overlay address. each one 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.

that slice identifier gets concatenated with the overlay prefix to calculate the overlay slice, which is the range of the Fan network assigned to a specific single address within the underlay network.

so, say 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)

therefore 8 (32-24) address bits will equate to 254 additional addresses for each address mapped from the underlay network. and yes, bestie, the math is mathing — 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 is in a separate subnet (192.168.13.0/24). since all three will share the same overlay network (250.0.0.0/8), we'd 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 (and honestly, which overlay prefix you use does not matter). so if we really only cared about joining 192.168.12/13.0/24, we could use an underlay of 192.168.12.0/23 — that would maximize the number of addresses per slice, but the CIDR network addresses of the slices would be less obvious to read. trade-offs, bestie, trade-offs 💅

                         +-------------+
                 ... ----+    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. obsessed with readability 🎀

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? each interface of the host that's 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 it would act as the gateway address of any container that runs within the overlay slice. periodt. 👑

✨ COMMAND SYNTAX ✨

running fanatic with no arguments is equivalent to running fanatic configure. no notes, that's just how it is 🦋

  • 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. and finally, it'll offer to test the configuration as applied — both locally and with an optional remote host. it's a whole journey, bestie, and it holds your hand the entire time 💖
  • fanatic deconfigure — reverses the interactive configuration above. it will deconfigure both LXD and Docker (if configured) and then deconfigure the Fan. ⚠️ important: these steps are only performed if the configuration was generated by fanatic. so if you did it by hand, it's not gonna clean up your mess, no cap.
  • fanatic test — runs the testing phase of the interactive setup. this action enables retesting of a previously configured system. only those pieces that were configured will be tested. lowkey the most satisfying command 🧚
  • fanatic help — shows basic help including usage information and pointers to further help on use of fanatic. when in doubt, ask for help. iconic behaviour honestly.

🦋 NON-INTERACTIVE USAGE 🦋

here's the tea: it's possible to run any sub-phase of the configure, deconfigure or test phases — the ones fanatic does in interactive mode — individually and without any user interaction. script girlies, this is your moment 🔥

  • 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. both sides or it doesn't count, bestie.
  • 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 — yes, both, you need both), LXC/LXD can be configured to use a specific Fan bridge for the network device of containers.

you can do this either by:

  • modifying the default template, or
  • creating a separate template which can be used when creating containers.

the latter is what fanatic enable-lxd does internally. the same thing 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 is 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. it's giving math that finally makes sense ✨

💀 LIMITATIONS 💀

okay, we have to be real for a second. since docker (at the time of writing) does not support allowing an external DHCP service to be used, there is no way to safely mix docker and LXD containers in the same Fan overlay slice. no cap, that's just a hard limitation. 😭

however — both types of containers can be mixed in the same Fan overlay, as long as they use their individual slice. so like, same party, different rooms. 🎀

🌸 EXAMPLES 🌸

okay bestie, real talk — let's actually do the thing 💅 Say you want a Fan network bolted onto your host's primary interface and you want zero user interaction. Step one is figuring out which interface is even the default one:

# ip route show | awk '$1 == "default"{print $NF}'
ens3

boom, it's ens3 ✨ next up we gotta find out what IPv4 address that interface is rockin':

# ip address show ens3 | awk '$1 == "inet"{print $2}'
192.168.2.120/24

so if literally every host chillin' in your Fan network lives inside 192.168.2.0/24, you can use a /24 underlay and get a whole 65535 addresses per slice — versus the measly 254 you'd be stuck with if you had to drag hosts from the 192.168.0.0/16 range into it. the math is mathing 🧮💖

for every command below in this example, we're using the interface's address with a prefix of 20, which assumes we only care about hosts in 192.168.[0-15].0/24 and lands us at 4095 addresses per slice. using the interface address is also the way you tell fanatic to configure only that single interface. no cap.

# 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

and now the moment of truth, the vibe check itself 😭🔥

# 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)

PASS after PASS after PASS — she ATE and left absolutely no crumbs 👑✨ (yes the eth0 waiting lines repeat three times, that's just her being patient, bestie 🫶)

🔎 SEE ALSO 🔎

go read those too, iykyk 📚💜

💌 AUTHOR(s) 💌

  • Andy Whitcroft <apw@canonical.com>
  • Stefan Bader <stefan.bader@canonical.com>

the icons who built this fr fr 🎀

and that's a wrap on FANATIC(8) bestie 🌈 this page is from the ubuntu-fan fam and it's dated July 25, 2017 — old but iconic, main character energy forever. go configure something cute, and remember: read the flags, respect the underlay, and always, always run your tests. mwah 💅💖🦋

📦 where this page comes from