                HOW TO DEPLOY SERVERS FOR THE NAT CHECK


To respond to the NAT checking requests is, as of now, the only useful
function of the fedaserv program.  It is planned to make this program
do much more, actually FEDAnet is going to consist of running copies of
fedaserv, but plans are plans, and the present is present.


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

Each running fedaserv needs its own point, so it is useful to have your own
node.  You can use a node key of any rank though, unless you're going to
cooperate with servers being run by other people (but in this case perhaps
you can ask them for points).

Besides that, you need to have a permanent IP address for each of the
running servers.  All a server needs is a single UDP port; usually it is
the port 65242 (0xFEDA).  Technically server can run on any UDP port, but a
non-default port is a thing that needs to be declared, and users will have
to specify it explicitly.

No root access is needed to run a server; if someone gracefully provides
you with a remote access to his/her rented server or a unix machine of
other kind, you might want to ask them to add to their startup scripts
something to launch your server on a reboot, but that's all.  If the
machine you've got access to is reliable enough, you may even go without
that, bringing your server up after every reboot manually.


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

So you have a node master key of a desired rank (for the testing period, 16
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 16

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.

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

Now it's time to create points for your servers.  Let them be 201, 202 and
203:

    fedakeys -p zcrpoint 201
    fedakeys -p zcrpoint 202
    fedakeys -p zcrpoint 203

As the result, you now have three point key files:

    49feb618794a8e1e4439_p201.key
    49feb618794a8e1e4439_p202.key
    49feb618794a8e1e4439_p203.key

Besides their own keys, the servers will need to know PUBLIC keys of each
other; as of now, servers are unable to exchange credentials.  So, we'd
better have the public keys handy from the very beginning.  Let's generate
them:

    fedakeys -p key2pub 49feb618794a8e1e4439_p201.key
    fedakeys -p key2pub 49feb618794a8e1e4439_p202.key
    fedakeys -p key2pub 49feb618794a8e1e4439_p203.key

As the result, we'll have yet another three files:

    49feb618794a8e1e4439_p201.pub
    49feb618794a8e1e4439_p202.pub
    49feb618794a8e1e4439_p203.pub

On each of your servers, you'll need its private file and the public files
of the two other servers.  Then, on the first server (presumably using the
point 201) do the following:

    fedakeys -p deploy 49feb618794a8e1e4439_p201.key
    fedakeys -p import 49feb618794a8e1e4439_p202.pub
    fedakeys -p import 49feb618794a8e1e4439_p203.pub

On the second server, do the similar thing:

    fedakeys -p deploy 49feb618794a8e1e4439_p202.key
    fedakeys -p import 49feb618794a8e1e4439_p201.pub
    fedakeys -p import 49feb618794a8e1e4439_p203.pub

And on the third server:

    fedakeys -p deploy 49feb618794a8e1e4439_p203.key
    fedakeys -p import 49feb618794a8e1e4439_p201.pub
    fedakeys -p import 49feb618794a8e1e4439_p202.pub

That's it: your key infrastructure is fully deployed and ready to work.



***************************
* SERVER CONFIGURATION FILE

By default, your server 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 src/serv.conf, which is
self-documented.  It is safe to leave everything at default values; the
only mandatory thing is to configure your peers, that is, the other
instances of the server, which will help your server handle the NAT check
requests.  Peers are configured like this:

peer venus
type natcheck
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 recommended
one for public servers of FEDAnet (it is very possible we'll have to change
this one day, if THEY start to filter us off using port numbers; servers
are able to work on any ports, but using other port numbers we'll make all
users specify ports explicitly).  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.

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 



**********************
* LAUNCHING THE SERVER

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

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

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!!!
