feda/doc/poormansvpn.txt

             HOW TO DEPLOY A POOR MAN'S IPv6-over-IPv4 VPN


Not too many of the planned features are implemented so far.  The fedaserv
instances can not find each other, can not exchange broadcast announces,
can not act as a rendes-vous assistant for others, there's no database of
known nodes' locations... well, there's almost nothing.  However, primarily
to convince ourselves we can do it, since the version 0.0.30 the running
instances of fedaserv are capable of transferring IPv6 packets to each
other, using IPv4/UDP datagrams as the underlying media.

Well, ... _somehow_.



*********************
* WHAT WORKS, AND HOW

Depending on the point number, fedaserv instances consider themselves
either as serving a single point (all point numbers from 1 to 253), or
as speaking on behalf of the node (the "magic" point number 254, a.k.a.
0xFE).  When a running fedaserv sees an IPv6 packet, the following decision
making process is performed.

  1. All packets with either SRC or DST address outside of the FEDA::0/16
     block are dropped immediately.

  2. The node ID and the point number are extracted from the DST address:
     the node ID is bytes from 2nd to 11th of the address (counting from
     zero), and the point number is the 12th byte.  E.g., for the address

        FEDA:49FE:B618:794A:8E1E:4439:8B00:1EE7

     the node ID is 49feb618794a8e1e4439 and the point number is 0x8B
     (a.k.a. decimal 139).

  3. Existing established cryptographic associations with peers are
     considered for being suitable to be the next hop.  There are three
     possibilities:

        a) if there's a peer with exactly these ID and the number (the
           target point), the packet is sent there;

        b) if there's no such peer, but there's a peer with the same
           node ID and with the peer number 0xFE (that is, the target
           node), the packet is sent there in the hope the node knows
           better where its peers are;

        c) as the very last resort, if our point number is NOT 0xFE, but
           among our active peers there's one with the same node ID as
           we use and with the point number 0xFE (that is, OUR node),
           we sent the packet there hoping the node will serve.

     If neither of those is found, the packet is dropped.


In the present version, all associations between fedaserv instances must be
configured manually, AT LEAST ON ONE OF THE ENDS of the association, and
both ends must know each other's nodes. This may need some further
explanation.

Each instance happily accepts association requests from any other instance
PROVIDED THAT (! this is very important) the accepting instance knows the
public node key of the requesting instance.  It could look more natural to
accept unknown nodes too, provided that they have an appropriate rank, but
this would involve computing yespower hashes each time an unknown node's
point approaches us.  Not every machine is able to do that at all, and even
powerful computers may be easily DoSed if they try doing so.  We're going
to have dedicated servers which check node credentials, collect known nodes
and share this information upon requests, but this infrastructure is yet to
be developed; now that we don't have it, the only option left is to update
every running fedaserv instance's node collection manually.

Having said all this, let's admit in the present version we can only run
nodes on public (permanent) addresses, as the address (the ip:port pair) is
to be set manually for each party who wants to communicate -- both for our
own peers and for other nodes.  Even worse, each point can only communicate
its own node, other points of the same node and points of other nodes, but
only provided that their nodes have established direct cryptographic
association with our node.  Let's admit this is not very useful.  Yet it is
far better than nothing.



***************
* PREREQUISITES

In order to run a node, you (as of now) need two things: a suitable node
master key (rank 20 or higher is strongly recommended), and a permanent
pair of IP address + UDP port on a Linux machine (well... BSD systems will
likely serve as well, but I never tested this).

To run a point, you need a point key provided by the node master.  Well,
yes, you need to have a node master among your friends and relatives.
Besides that, you need a computer running Linux (or may be BSD... no
promises here, sorry).  And one more little thing: actualy you need root
access to the machine if you want FEDAnet IPv6 packets to be originated
from it and targeted to it: without root access, you can't set up the
appropriate virtual network interface and routes.

If the machine where you're going to run a node is yours in the sense you
have root access to it, you can run some servers on your node's addresses,
that is, addresses of the form FEDA:(node-id):PPxx:xxxx, where PP is one of
00, FE and FF, and xx:xxxx are any hexadecimal digits; in particular, the
address FEDA:(node-id):FEDA:FEDA is strongly recommended.  However, this is
not necessary; if you only have non-privileged access to the server, your
node will still be able to forward packets back and forth, between your
points and from/to other nodes; only you'll be unable to use the "node"
address space, only addresses of the points other than 00, FE and FF.



****************
* PREPARING KEYS

So you have a node master key of a desired rank (again, 20 is the
recommended minimum).  In this example we'll assume your node ID is
49feb618794a8e1e4439; this means the file created by the feda-ng program is
named the same.

The first step is to prepare the node master workplace.  If you absolutely
can't have a dedicated machine for that, which never ever connects to
networks, at least do it on a removable media, or, as the VERY minimum,
have a dedicated directory for this job, and once you're done, copy it to
some removable media and delete from your working machine.  We'll assume
the directory for this purpose is named MASTERDIR.  The first step is to
deploy the node master workplace using the master key file:

    fedakeys -c MASTERDIR mdeploy 49feb618794a8e1e4439

If you have to do this on a low-end machine, and you're confident that the
file 49feb618794a8e1e4439 is not corrupt anyhow, you might want to add the
-p flag to avoid recomputing the hash, which is resource-demanding:

    fedakeys -p -c MASTERDIR mdeploy 49feb618794a8e1e4439

You might want to specify the minumum rank at which your node is going to
recognize other nodes.  By default, it is set to the same value as your
node's own rank.  It is impractical to recognize nodes with ranks lower
than 16, so if your own master key has this rank, leave the things as they
are; if, however, you use a node key with a rank higher than that, you
might want to allow other people to use lower ranked node keys for the
period FEDAnet is not used for any real work.  Use a command like this:

    fedakeys -p -c MASTERDIR mdeploy 49feb618794a8e1e4439 20

After that you'll have two files inside MASTERDIR, named feda.conf and
master.key.  The feda.conf file contains nothing secret, so don't worry too
much about it; but the file master.key is THE place where your node's
secret key is stored (and the other such place is the original file,
49feb618794a8e1e4439 in our example).  Keep these files away from
networking as carefully as you can.  As of now, just create the key for
your ZeroPoint, and you can move the master secret key somewhere else and
wipe it off your workstation, which is presumably connected to the
Internet.  Do this:

    fedakeys -p -c MASTERDIR mzero

From now on, you don't need the MASTERDIR any longer, until you decide
to replace your ZeroPoint key.  Once again: move your master credentials
as far away from any computer networks as you can.  Be sure to keep several
copies in different places so that you don't loose your node.

In the current directory you now have a file named

    49feb618794a8e1e4439_p0.key

-- which contains all information needed to deploy your ZeroPoint,
including the secret key for it.  If you work on a machine dedicated as the
node master workplace, take this file to a removable media and transfer to
the machine where you plan to deploy your zero point; if you don't have a
dedicated machine, you can continue right here (but you DID remove the
master credentials, didn't you?).  There's not much sense in placing the
deployed ZeroPoint anywhere else than the default $HOME/.fedanet/keys, so
from now on we won't specify the directory (but, well, YOU can continue
doing it).  So, deploy your ZeroPoint:

    fedakeys -p deploy 49feb618794a8e1e4439_p0.key

While at it, create and add right here your point number 1, which is for
you as the node master, personally -- unlike the ZeroPoint, which
represents your node, not you as a person.  Make a key for it and deploy
the key right at the same place, and then remove the file:

    fedakeys -p zcrpoint 1
    fedakeys -p deploy 49feb618794a8e1e4439_p1.key
    rm 49feb618794a8e1e4439_p1.key


What you need in order to continue with deploying your node, is, first, a
key for the fedaserv instance which will run on behalf of the node (that
point 254 a.k.a. 0xFE); and, second, perhaps a public node credentials'
file, which you'll share with other nodemasters whenever you decide to peer
with them.  The command

    fedakeys -p zcrpoint 254

will do the first thing (creating a file named 49feb618794a8e1e4439_p254.key),
and the command

    fedakeys -p nodecert

will create a file named 49feb618794a8e1e4439.pub, containing the public
information of your node.  The nodecert command can be run in any location
where a point of your node (ANY point of YOUR node) is deployed, as the
necessary information is always available along with any point's keys.



*****************************
* FEDASERV CONFIGURATION FILE

By default, fedaserv tries to load its configuration from the file named
$HOME/.fedanet/serv.conf -- but, as usual, you can supply any other path
using the -c option.

There's a sample configuration file doc/serv.conf, which is
self-documented.  It is safe to leave everything at default values; you
need to configure your peers (usually the node at points' configuration,
other nodes at the node's configuration), enable the packet forwarding,
and (optionally) specify the tun interface.

Peers are configured like this:

peer venus
type persist
ip 198.51.100.12
port 65242

The peer name, which is set at the 'peer' line, must be distinct, but is
not used by the server in any other way.  The port 65242 is the default one
for public servers of FEDAnet (well, decimal 65242 is the same as
hexadecimal 0xFEDA), but you can use any other port as well.  As of the
type, it is a space-separated list of tokens, and as of present, the
software recognizes 'default', 'mynode', 'natcheck' and 'persist'; of
these, 'mynode', 'natcheck' and 'persist' cause the running server to try
connecting the configured peer.  You can replace the 'persist' token with
'mynode' if the peer is the node (a.k.a. point 254) for your point, or with
'natcheck' if you're going to use both running instances as parts of a
server system for NAT type checking (see the file NC_SERVERS for more info
on this), and you can even use them both if appropriate; in most cases,
however, the 'persist' token is exactly what you need.  So, to configure a
peer, just copy this example to your configuration file, replace the IP
address with the address of your peer, then pick a random distinct name and
replace 'venus' with that name; optionally also change the port number.

It may be a good idea to specify explicitly where the server should look
for cryptographic keys, like this:

keys_dir    /home/lizzie/.fedanet/keys 

Enable the packet exchange as such, adding a line like this:

forwarding yes

In case you have the appropriately configured tun interface (e.g. feda0,
see the next section), add the following line as well:

tun_iface feda0

-- this will let the fedaserv instance to deliver locally the packets
destined to it (DST addresses FEDA:(node-id):PPxx:xxxx for all points
except the FE, DST addresses FEDA:(node-id):NNxx:xxxx where NN is 00, FE or
FF, for the node which is effectively a fedaserv running with 254 as the
point number).



****************************
* SETTING UP A TUN INTERFACE

You need to be root to do this.  DON'T RUN fedaserv AS ROOT!!!  The feda-if
command is primitive so we can hope it won't compromise your machine's
security, and the other two commands are shipped with your system.  Even if
you don't have root access to the machine (which is highly likely if you
decide to run your node on someone else's server machine), you may try
asking your good host to execute the commands for you.  This is not
desirable however if the machine runs other instances of FEDA as well,
because there can only be one route for the FEDA::0/16 block.

The four things you need to do are, first, to create the interface (we
prefer the name feda0, but you can use whatever you like), making it
persistent until the machine is rebooted, and granting access to it to the
user who runs the fedaserv instance; second, to bring the interface up;
third, to add an appropriate IPv6 address to the interface; and the last,
to add the FEDA::0/16 route.  For the first task, the command feda-if is
used.  We assume you copied it to your /usr/local/sbin directory, and
you've created a dummy user named fedanet (and a user group of the same
name) to run the fedaserv instance.  Suppose, besides that, that uid/gid
for the dummy user are 2575/2575.  Then, the command

   /usr/local/sbin/feda-if -p -u 2575 -g 2575 feda0

will do the thing.  Now, pick the IPv6 address you'll use as the ``main''
address for this particular instance.  For a node, address
FEDA:(node-id):FEDA:FEDA is recommended; for a point, e.g., 2C (a.k.a. 44
in decimal), use smth. like FEDA:(node-id):2C00:FEDA.  The following
commands will do the rest of what you need (assuming, just like before,
that your node is 49feb618794a8e1e4439): 

    /sbin/ifconfig feda0 up
    /sbin/ifconfig feda0 add feda:49fe:b618:794a:8e1e:4439:2c00:feda/16
    /sbin/route -6 add feda::0/16 dev feda0

It might be not a bad idea to add these four commands somewhere so that
they are executed on each reboot, e.g., to your /etc/rc.local (if you have
it; refer to the documentation on your OS or the distro).        



********************
* LAUNCHING FEDASERV

During the period of debugging, it is recommended to run servers in
foreground, directing all logging to their stderr streams, and making the
diagnostics reasonably verbose.  All this is achieved with a command
line like

    /path/to/fedaserv -v -E -f -c /path/to/your/config/file

You can add another -v or even two of them, but don't leave fedaserv
running with that level of logging verbosity if you're going to do
something "real" through your tunnels.  With more than one "-v", it will
produce a lot of messages on every handled IPv6 packet, and, well, it's a
lot of junk in your logs.

It is better to launch this command inside a virtual terminal created by
the well-known ``screen'' program, so that if you loose your connection to
the server machine, your fedaserv will not get killed by SIGHUP.  The
screen program is available out of package repositories on all Linux
distros I have ever seen.

Once you're confident everything works as desired, you might want to put
the configuration file to its default location ($HOME/.fedanet/serv.conf)
and let your system launch your fedaserv without any extra parameters at
the command line.  Make sure you DON'T RUN THE SERVER AS ROOT!!!



**************************
* PEERING WITH OTHER NODES

First, publish somewhere your nodecert file (that 49feb618794a8e1e4439.pub
thing, where 49feb618794a8e1e4439 is your node ID) together with
the address:port of your running node.  Or, just exchange this information
with someone else who runs a node.

Once you've got someone else's node's information, first check the file for
correctness.  This must be done on a reasonably powerful machine, as it
requires taking the yespower hash.  The command is like this:

   fedakeys nverify f22ff5448c951bb33897.pub

Once the check is passed, you now sure the file is correct.
Copy the file to the location where your node runs, and do the following:

   fedakeys -p nodeimport f22ff5448c951bb33897.pub

After that, add the remote node as a peer to your node's serv.conf and
restart your fedaserv instance.

Once all this is done, all your points should "see" (e.g. should be able to
ping) IPv6 addresses belonging to the remote node's point, and vice versa.




********************************
* CONTROLLING THE RUNNING SERVER

Being signaled with SIGUSR1, the server writes to the logs its list of
active peers.

Since 0.0.35, there's also the local socket which allows to control the
server with the ``fedactl'' program.  Make sure you enabled the socket in
your configuration file with

control_socket		yes

The fedactl program in the present version accepts exactly one optional
parameter, which is the path to the socket.  If you didn't set the path
explicitly, then the socket is created as ~/.fedanet/servctl where the
fedactl program will find it by default.

To have logging messages delivered to you trough the fedactl program, use
commands like ``log info'' or ``log debug''.  Type ``help'' to know what
else you can do.