Provided by: ubuntu-fan_0.9.0_all bug

NAME

       fanctl - fan bridge administration

SYNOPSIS

       fanctl up [<options>...]
       fanctl down [<options>...]
       fanctl up -a
       fanctl 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
       250.0.0.0/8 Fan to an IP address of 172.16.3.4, the hosts's Fan overlay addresses will  be
       in  the  250.3.4.0/24  subnet,  where 250 is derived from the user defined overlay network
       prefix.

COMMAND SYNTAX

       fanctl up -u <underlay> -o <overlay> [<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-250
              based on the overlay and underlay addresses specified (see ADDRESSING below).   The
              options are described in the OPTIONS section below.

       fanctl down -u <underlay> -o <overlay>
              Tears  down a previously-configured Fan bridge and associated mapping.  This action
              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; for instance:

              # fanctl show
              Bridge       Underlay        Overlay       Flags
              fan-250      172.16.3.4/16   250.0.0.0/8   dhcp host-reserve 1

       fanctl config set -u <underlay> -o <overlay> [<options>...]
              Stores  additional  configuration  options  for  the  underlay/overlay  combination
              specified.

       fanctl config show -u <underlay> -o <overlay>
              Displays any additional configuration options for the underlay/overlay  combination
              specified.

       fanctl config list
              Displays all underlay/overlay combinations which have additional configuration.

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 -u 172.16.3.4/16 -o 250.0.0.0/8

       This example defines an overlay of 250.0.0.0/8 and an  underlay  of  172.16.3.4/16.   When
       mapping  an  address in the 250.0.0.0/8 subnet, we 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 250.3.4.15 will trigger the packet to be sent to 172.16.3.4
       for delivery.

       It is not always possible to know the local underlay address at the time the configuration
       is  generated  (such  as  when a common configuration is desired on all systems).  In this
       case we can specify the underlay address using only the underlay prefix, or  by  reference
       to an interface.

       For  example, to bring up a Fan bridge slice for each address in the 172.16.0.0/16 subnet,
       the following example examines each interface as it is currently configured and configures
       a matching slice at that time:

              # fanctl up -u 172.16.0.0/16 -o 250.0.0.0/8

       To  bring  up  Fan  slices  corresponding  to the addresses on a specific interface we can
       substitute the interface name:

              # fanctl up -u ens3/16 -o 250.0.0.0/8

       To bring up Fan slices corresponding to the addresses on  the  primary  network  interfane
       (the inteface with the default route), the keyword default can be substituted:

              # fanctl up -u default/16 -o 250.0.0.0/8

LIMITATIONS

       Currently  Fan  can  only  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

       -u <underlay>|--underlay=<underlay>
              Specify the underlay network address and mask.

       -o <overlay>|--overlay=<overlay>
              Specify the overlay network address and mask.

       --type=<type>
              Sets the encapsulation type for this Fan bridge.  May be ipip  or  vxlan  (default)
              only.  You should not normally need to specify this.

       --mode=<mode>
              Sets  the bridge mode.  May be compact (default) or sliced only.  In compact mode a
              single Fan bridge per overlay network is created.  In sliced mode a Fan  bridge  is
              created  for  each  local Fan slice.  sliced mode is considered legacy.  You should
              not normally need to specify this.

       --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,  enabling  it
              to  communicate  with  entities  on the Fan bridge. This option reserves additional
              addresses for host applications to use. 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). This option overrides the name to one you specify.

       --enable
              This option marks the Fan bridge to be automatically configured when the underlying
              interface   comes  up.   This  is  primarily  used  in  the  local  Fan  persistent
              configuration to enable centrally configured Fan mappings on a specific host.  (See
              PERSISTENT CONFIGURATION below).

PERSISTENT CONFIGURATION

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

              # underlay      overlay      flags
              # fan 250
              172.16.3.4/16  250.0.0.0/8   --dhcp
              172.16.3.5/16  250.0.0.0/8   --dhcp
              # fan 251
              ens3/16        251.0.0.0/8
              # fan 252
              172.16.0.0/16  252.0.0.0/8

       Note  that  comments  are  introduced  via  a  hash (#), and blank lines are ignored.  Any
       overlay/underlay  format  supported  by  fanctl  up  is  supported   in   the   persistent
       configuration (see ADDRESSING above).

       It  is  expected that the /etc/network/fan configuration is globally managed ensuring that
       all hosts have consistent overlay to underlay mappings.  Local deviation  is  managed  via
       the  fanctl config subcommand.  This allow a local host to record additional flags against
       a specific overlay/underlay combination.  For example:

              # fanctl config set -u 172.16.0.0/16 -o 250.0.0.0/8 --enable

       will add the --enable opttion to the local host configuration, triggering this Fan  to  be
       configured when the host interface is configured.

FAN BRIDGES

       By  default each Fan bridge represents a Fan overlay network which is expressed locally on
       the machine.  The Fan bridge will have the various slice addresses mapped to it.

       In legacy sliced mode 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, enabling 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 it  carries  traffic.
       For  our  250.0.0.0/8  on  172.16.3.4 example, the bridge would be named fan-250 and would
       carry all traffic for 250.3.4.0/24.

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.   The  fanatic(8)
       script can be used to automatically generate an appropriate configuration.

       To configure LXC manually, configure the bridge and MTU as below:

              lxc.network.link = fan-250
              lxc.network.mtu = 1450

       Typically  a  Fan-bridge-specific configuration is created using the default configuration
       as a template modified as above. 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), the docker configuration must
       be modified to direct containers to the new bridge.  The fanatic(8) script can be used  to
       automatically generate an appropriate configuration.

       To configure Docker manually, edit /etc/default/docker.io, adding:

              DOCKER_OPTS="-d -b fan-250 --mtu=1450 --iptables=false --fixed-cidr=250.x.y.0/24"

       (You will need to select x.y to match your local subnet.) You can then
       restart docker:

              # service docker 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

       fanatic(8) /usr/share/doc/ubuntu-fan/README
       http://www.ubuntu.com/fan

AUTHOR

       Andy Whitcroft <apw@canonical.com>

                                          June 19, 2015                                 FANCTL(8)