FANCTL(8)

NAME
fanctl - fan bridge administration

SYNOPSIS
fanctl up|down <overlay> <underlay> [<options>...]
fanctl up|down -a
fanctl down -e
fanctl show

DESCRIPTION
fanctl is used to set up, tear down, and inspect Fan bridge mappings and devices in the linux kernel.

A network fan is a mechanism for expanding the range of IP addresses available to a system. It is most useful for containers such as Docker and LXC/LXD, but it can be used in other contexts as well. Fan works by creating a bridge that uses a mathematical mapping between the host's (or underlay's) /16 address and the fan's (or overlay's) /8 address. By mapping addresses in this way, a 253-fold increase in address space can be achieved. For example, if the host machine uses a subnet of 172.16.0.0/16 and assigns a fan to an IP address of 172.16.3.4, the fan's overlay addresses will be in the 10.3.4.0/24, where 10 is derived from the user defined overlay network prefix.

COMMAND SYNTAX

fanctl up <overlay> <underlay> [<options>]
    sets up a new Fan bridge mapping overlay addresses to the corresponding underlay addresses on the local network. Using the example, the new bridge is named fan-10-3-4 based on the overlay and underlay addresses specified (see ADDRESSING below). The options are described in the OPTIONS section below.

fanctl down <overlay> <underlay>
    tears down a previous set up Fan bridge and associated mapping. This will fail if the bridge is still in use.

fanctl up -a
    sets up all Fans defined in /etc/network/fan if present.

fanctl down -a
    tears down all automatically defined Fan bridges on the system. These may be identified in the fanctl show output via the auto flag.

fanctl down -e
    tears down all defined Fan bridges on the system.

fanctl show
    lists all currently defined Fan bridges in the system:

    $ fanctl show
    Bridge       Overlay      Underlay       Flags
    fan-10-3-4   10.0.0.0/8   172.16.3.4/16  dhcp host-reserve 1
    $

ADDRESSING
The Fan mapping is defined by a combination of the underlay and overlay addresses. Each is defined as a CIDR network address. For example:

    $ fanctl up 10.0.0.0/8 172.16.3.4/16

This defines an overlay of 10.0.0.0/8 and an underlay of 172.16.3.4. When mapping an address in the 10.0.0.0/8 subnet, we will take the 16 bits of destination address starting at bit 8 and replace the bottom 16 bits of the underlay address with it. For example attempting to talk to 10.3.4.15 will trigger the packet to be sent to 172.16.3.4 for delivery.

LIMITATIONS
Currently we are only able to apply overlay addresses with a /8 network mask, and underlay addresses with a /16 network mask. We expect to relax this limitation in a later update.

OPTIONS

dhcp
    turns on automatic address allocation for the Fan bridge. A dnsmasq instance is started attached to the bridge allocating the unreserved addresses to entities attached to the Fan bridge.

host-reserve <count>
    by default the .1 address on the Fan bridge is allocated to the host allowing it to communicate with entities on the Fan bridge. This option allows further addresses to be reserved for host applications to bind to. A host-reserve 4 reserves .1 through .4 in the Fan bridge for host use.

bridge <name>
    by default the bridge name is based on the overlay and underlay addresses specified (see ADDRESSING above), override to a specific name.

off this option prevents the Fan bridge from being configured. This is primarily used to allow Fan mappings to be defined but disabled in /etc/network/fan (See PERSISTANT CONFIGURATION below).

FAN BRIDGES
Each Fan bridge represents a slice of a Fan overlay network which is expressed locally on the machine. The Fan bridge will have the overlay addresses representing one local IP address mapped to it. A machine may have more than one local address on the underlay network allowing it to have more than one such slice mapped. It may also have more than one overlay range defined for each local IP address.

Each fan bridge is a separate broadcast domain, with routing between the bridges both locally and globally within the Fan.

Each fan bridge appears as a bridge on the system, named for the overlay subnet hosted by that particular fan bridge and the underlay address prefix for which is carries traffic. For our 10.0.0.0/8 on 172.16.3.4 example the bridge would be named fan-10-3-4 and would carry all traffic for 10.3.4.0/24 .

PERSISTANT CONFIGURATION
There are two main ways to configure Fan bridges. Firstly via /etc/network/interfaces and secondly via /etc/network/fan .

Fan bridges are configured in /etc/network/interfaces using the up and down command callouts:

    iface eth0 dhcp
            up fanctl up 10.0.0.0/8 eth0/16 dhcp
            down fanctl down 10.0.0.0/8 eth0/16

Fan bridges are configured in /etc/network/fan by listing overlay, underlay,
and flag combinations.  For example:

    # fan 10
    10.0.0.0/8 172.16.3.4/16 dhcp
    10.0.0.0/8 172.16.3.5/16 dhcp off
    # fan 241
    241.0.0.0/8 172.16.3.4/16 dhcp
    241.0.0.0/8 172.16.3.5/16 dhcp

Note that comments are introduced via a hash (#) in the first column, and blank
lines are ignored.

USE WITH LXC/LXD
Once the Fan bridges are configured, LXC/LXD is typically configured to use a specific fan device by either creating a new configuration template with the appropriate bridge specifiers, or by modifying the default configuration template similarly. Configure the bridge and MTU as below:

    lxc.network.link = fan-10-3-4
    lxc.network.mtu = 1480

To change the default template apply these changes to /etc/lxc/default.conf.

USE WITH DOCKER
Once the Fan bridges are configured (and docker installed), edit /etc/default/docker.io, adding:

    DOCKER_OPTS="-d -b fan-10-3-4 --mtu=1480 --iptables=false"

And then restart docker.io:

    sudo service docker.io restart

Docker instances will now use the specified fan.  Note that currently
only one Fan bridge and subnet may be used at a time with a running
docker instance.

SEE ALSO
/usr/share/doc/ubuntu-fan/README
http://www.ubuntu.com/fan

AUTHOR
Andy Whitcroft <apw@canonical.com>