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>

                                                  June 19, 2015                                        FANCTL(8)