FAN README
==========

A Fan network 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 context as well.  See fanatic(8)
for more details of Fan networks and their use.

Address Notation
----------------

The Fan mapping is defined by a combination of the underlay and overlay
addresses.  Each is defined as a CIDR network address.  For the underlay
address, the network/prefix bits are stripped away and the remaining
address bits are used to extend the prefix of the overlay address to
calculate the overlay slice which is the range of the Fan overlay
network that is assigned to an address within the underlay network.

overlay address:
  This specifies a network range to be used for the overall Fan network.
  Any mapping that uses the same overlay address will share the same
  address space range. Using a smaller prefix will increase the number
  of available addresses for each Fan network slice at the cost of losing
  the ability to route to whole ranges of class A networks.

underlay address:
  This defines the network scope from which addresses map into the
  overlay network. This does not necessarily mean the subnet an inter-
  face is in but the routing scope of participating hosts. If for
  example one host adds a mapping for an interface on 172.16.x.0/24
  but can route to any address in 172.16.0.0/16 and that larger scope
  has other hosts which should be part of the Fan network, then the
  underlay address is that of the larger 172.16.0.0/16 scope.

Overlay and underlay addresses are used to calculate which range of
addresses in the overlay network space any single address in the
underlay network can map to. This is done the following way:

  From the overlay address <prefix> bits are taken away from the
  left and form the start of the range.

  From the address of the interface that matches the underlay
  address <prefix> bits are stripped away and the remaining bits
  are appended to the bits taken from the overlay.

  Additional 0 bits are added until again forming a 32bit address.
  The prefix for the slice is:

    <overlay prefix> + (32 - <underlay prefix>)

  For example:
         250.       0.       0.       0 /8  overlay address
    11111010.00000000.00000000.00000000
    PPPPPPPP.--------.--------.--------
         172.      16.       0.       0 /12 underlay address
    10101100.00010000.00000000.00000000
    PPPPPPPP.PPPPSSSS.SSSSSSSS.SSSSSSSS
         172.      16.      10.       2 /12 address of interface
    10101100.00010000.00001010.00000010
    PPPPPPPP.PPPPSSSS.SSSSSSSS.SSSSSSSS


    11111010.                               prefix bits from overlay
                 0000.00001010.00000010     underlay with prefix taken away
    11111010.00000000.10100000.00100000     appended and filled (or shifted)
    PPPPPPPP.SSSSSSSS.SSSSSSSS.SSSS----     prefix 8+(32-12) = 28
         250.       0.     160.      32 /28

That means the 172.16.10.2 would map into the 250.0.160.32/28 slice of
the 250.0.0.0/8 Fan network. Which leaves 4 bits for fanout. Though
practically (0, 1 (gateway), and 15 (broadcast) would not be used).

Using Fan
---------

All creation, configuration, and tear-down should be done using
fanatic, which will make necessary adjustments to configuration files.
Once created, fanatic will be called from an ifupdown hook (until
this part of startup is swallowed by systemd minions) to bring up
the Fan network when its related interface becomes ready.

	sudo fanatic configure
	sudo fanatic deconfigure

Those two calls are interactive and will guide one through the process
of setting up a Fan network. For programatic use, there are some
advanced commands for fanatic:

        sudo fanatic enable-fan -o 250.0.0.0/8 -u 172.16.3.4/16
	  sudo fanatic enable-lxd -o 250.0.0.0/8 -u 172.16.3.4/16
          (either lxd or docker but not both for the same segment)
	  sudo fanatic enable-docker -o 250.0.0.0/8 -u 172.16.3.4/16
        sudo fanatic disable-fan -o 250.0.0.0/8 -u 172.16.3.4/16

For the above Fan overlay, a bridge device named "fan-250" is created to
host the Fan subnet for the specified portion of the Fan overlay network.
The reason for docker and lxd being unable to share the same Fan bridge
is that LXD will use the DHCP service associated with the Fan bridge but
docker does not support external address management. So address usage
would clash sooner than later.

Using Fan with Docker
---------------------

The docker.io package has to be installed prior the call to enable-docker
above. The call will create a bridge network named the same as the
corresponding Fan bridge.  To start a docker instance using the Fan network
one simply does a:

	docker run -it ubuntu:latest --network <fan-network>

Using Fan with LXD
------------------

The lxd package has to be installed (and initialized) prior to the
enable-lxd call. This will create a profile named the same as the
corresponding the Fan bridge which can be used when creating a container:

	lxc launch "ubuntu:lts" <name> --storage default -p <profile>

Picking Your Address Ranges
---------------------------

Of course, in order for this system to work, you must have an overlay address
range you're willing to sacrifice. The 10.0.0.0/8 address range can be used
in this way if and only if you don't need it for anything else; or you can pick
another range you're willing to sacrifice from the list maintained by the IANA:

  http://www.iana.org/assignments/ipv4-address-space/ipv4-address-space.xhtml

Note that the 0.0.0.0/8, 127.0.0.0/8 and 224.0.0.0/4 (IP multicast)
address ranges will not function as Fan overlay networks.

The 240.0.0.0/8 through 254.0.0.0/8 ranges are excellent candidates,
as they're currently defined as reserved and therefore unused by anything else.

For more information
--------------------

More information on the Fan, including more detailed configuration
information, can be found at http://www.ubuntu.com/fan.
