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)