========================= GET ===================================

The latest release is available from https://alnt.org or sourceforge.

alnt.org holds releases in .tar format.  A release is made after the code
has been tested and evaluated.

Sourceforge holds the latest version of the code, which may be buggier.
You can get the source from sourceforge as follows:

	mkdir allnet
	cd allnet
	git init
	git remote add origin git://git.code.sf.net/p/allnet/code
	git pull origin master

For a copy that lets you read and compile the code but not update the
repository, you can replace the last three lines with:
	git clone git://git.code.sf.net/p/allnet/code .

At this time there are no official binary releases.

======================== BUILD ==================================

to build this release, run these programs:
        ./autogen.sh
        ./configure --disable-shared
        make

if you either don't have Java installed, or don't plan to use the
Graphical User Interface (GUI) that comes with xchat, replace
the second line with:
        ./configure --disable-shared --disable-gui

you can also set specific CFLAGS with:
        ./configure --disable-shared CFLAGS="-Wreturn-type -g"

Before doing any of this, you may need to install libtool and autoconf.
On debian/ubuntu and derived systems this requires:
        sudo apt-get install libtool autoconf autotools-dev libdbus-1-dev
On other systems, use the native package manager to install these packages.

additional packages you may need to install:
	GIT and SSL: git libssl-dev
	Java: openjdk-7-jre openjdk-7-jdk

======================== RUN ==================================

Running allnet requires running a collection of programs called the
allnet daemon, then running individual user programs.

    ================ allnet daemon ================

the first thing to run is
   bin/astart

this will start the allnet daemon, which is a collection of programs
that run independently of user programs, and helps them communicate over
AllNet.

The allnet daemon is lightweight, and can be left running forever.
Should you wish to stop the allnet daemon, run

   bin/astop

If the allnet daemon is not running when an allnet user program is
started, the allnet user program will automatically call bin/astart.

    ================ allnet user programs ================

Current AllNet user programs include the AllNet chat program xchat,
broadcast/subscribe, and trace.

         ======== xchat (allnet chat) with gui ========

The functionality of chat is provided by the program xchat, which is built
unless "--disable-gui" is given to config (or unless you don't have java
on your system).  The xchat program is designed to be intuitive and easy
to use.

To start the xchat program, type
   bin/xchat

       ======== xchat (allnet chat) without gui ========

It is a good idea to read this whole section before trying anything.

The basic functionality of chat is given by xchats and xchatr.  They
are designed to be run in separate windows.

In one window simply run
   bin/xchatr

In another window, run
   bin/xchats friends-name message

where "friends-name" is the name of your friend as specified in the key
exchange (see below), and message is the message you want to send to
your friend.  The message ends when you press return.  It is generally
best to enclose the message in double quotes, otherwise the shell may
interpret any special characters such as quotes, question marks, etc.

For example,
   bin/xchats john "how are you today?"

john's answer, if any, appears in the xchatr window.  You can then type:
   bin/xchats john "life is wonderful!"

Before you can chat with a friend, you must exchange keys.  This can be
done from the GUI, in the "New Contact" tab, or using bin/xchats -k
(the commands xkeyr and xkeys from previous versions of AllNet are now
obsolete).

In order to securely exchange keys, you and your friend must both know
a shared secret string that is provided for you by either the GUI,
or xchats -k.  The string is conveniently short if you are directly
connected to your contact, and more securely long if you are communicating
over longer distances.  One side needs to enter the other side's secret
string -- it does not matter which of the two is used.

The secret string must be exchanged in an authenticated way between you
and your friend.  That means you must be sure that it is really your
friend that gave you the secret, and not somebody else.  The secret
also really should be a secret, that is, only known to the two of you,
for at least the time needed for the key exchange.  If your exchange is
not secure, an attacker may be able to listen in on your conversations,
or even send fake messages to one or both of you.

Once you have the secret, one of you runs
   bin/xchats -k contact-name number-of-hops secret-string

and the second one runs
   bin/xchats -k contact-name number-of-hops

The equivalent in the bin/xchat program is to enter the contact name,
and select the appropriate button (1st, 4th, or 5th).  One of you also
has to enter the contact's secret.

Again, "contact-name" is any name each of you chooses, to identify
the other person.  Number-of-hops is 1 for a direct connection, and
typically 10 otherwise.

If the exchange is not successful, the contact may have been
partially created.  If so, find it under your home directory's
.allnet/contacts/ directory (i.e. ~/.allnet/contacts/), under
the date and time that you tried to exchange the keys.  Check
the name with
   cat ~/.allnet/contacts/YYYYMMDDhhmmss/name
(where YYYYMMDDhhmmss are the date and time), then, if you really
want to remove it, do so using
   mkdir -p ~/.allnet/unused
   mv ~/.allnet/contacts/YYYYMMDDhhmmss ~/.allnet/unused/

            ======== broadcast/subscribe ======== 

AllNet supports broadcast messages that are authenticated (you can be
confident who sent them), but not confidential (everyone can read them). 

To identify a sender, you must be in possession of an AllNet Human-Readable
Address, usually abbreviated AHRA or ahra.  An ahra a form that may look
somewhat familiar:
  "personal_phrase"@a_b.c_d.e_f

The quotes are needed if the personal phrase includes spaces or other
special characters, but may be omitted otherwise.

If you decide to create your own ahra, you choose your own personal
phrase -- it can be anything you want, and, unlike an email address,
it does not have to be unique, it could be the same as somebody else's
personal phrase.  Again, upper- and lower-case are treated the same.

Assuming your personal phrase is "AllNet is wonderful", you would then
generate a valid ahra by running
   bin/allnet-generate "AllNet_is_wonderful" 3

The number 3 at the end of the command specifies the number of word-pairs
you want after the '@' sign.  More word-pairs make it harder for
somebody else to generate an ahra that matches yours, but they also
will require allnet-generate to run longer before finding an ahra.
Three is a reasonable compromise between security and generation time.
If you do not specify a number, allnet-generate assumes that two word
pairs is enough, and you are more interested in generating ahra's as
quickly as possible, than in security.

While allnet-generate is running, look up the keys it has generated with
   ls ~/.allnet/own_bc_keys

(bc stands for broadcast, and "own" holds the keys that you have generated
and are willing to use).

All the generated keys will have the personal phrase that you specified,
but each will a different set of identifying keywords.  Once you see
an ahra that you like, you can stop allnet-generate, and remove from
~/.allnet/own_bc_keys/ all the keys you do NOT plan to use.

Even if somebody else chooses the same personal phrase as you do, your
ahra is secure as long as the word pairs are different.

This rather long explanation is needed to make it clear that more word
pairs make an ahra more secure -- the personal phrase by itself ("AllNet
is wonderful"@) is a valid ahra, but is not at all secure, since anybody
can claim it and use it.

Finally, if someone gives you an ahra for a broadcast server, you may
subscribe to that.  AllNet runs an hourly time signal server with ahra
   allnet_hourly_time_server@if_wish.think_past.get_future

and you can subscribe and listen to this time server by running:
   bin/allnet-subscribe allnet_hourly_time_server@if_wish.think_past.get_future
   bin/allnet-radio

The second command will run forever, and once an hour, on the hour,
should print out the message from the allnet time server.  It will
also print out messages from any other service(s) that you subscribe to.
To know which services you subscribe to, simply
   ls ~/.allnet/other_bc_keys

To stop subscribing to a service, remove the corresponding key from the
directory ~/.allnet/other_bc_keys

            ======== allnet trace ========

The trace program is used to find and print a path to a destination.
Each allnet daemon picks a different ID every time it is started, and it
is these IDs that trace prints.  If you know the ID of the destination
you are trying to reach, you can specify it as an argument to trace.
Otherwise, trace without arguments will show all the daemons that respond.

bin/trace
 trace to matching destination:
                0.497ms timestamp,      1.966ms rtt,  0 21.cd/16
 trace to matching destination:
                0.497ms timestamp,    114.299ms rtt,  0 21.cd/16
               66.300ms timestamp,    114.299ms rtt,  1 2d.5c/16
 trace to matching destination:
                0.497ms timestamp,    253.747ms rtt,  0 21.cd/16
               66.300ms timestamp,    253.747ms rtt,  1 2d.5c/16
              115.300ms timestamp,    253.747ms rtt,  2 25.e3/16

Here trace with no arguments shows three different destinations, each
with a 16-bit (/16) address: 21.cd, 2d.cd, and 25.e3.  Each of them
matches the trace request, which had no arguments and therefore matched
everything.

The timestamp printed is only accurate if the clock on your system
accurately matches the clock on the system that responded, whereas
the round-trip time (rtt) should always be accurate.

The first response is always from the local AllNet daemon, so we know
that 21.cd/16 is our own local address (until we restart the AllNet daemon).

In this case, all three systems have (at random) chosen the first 4
bits of their address to be the same, namely 0010, usually written 2.
However, the fifth bit is a one for 2d.5c, and a zero for 21.cd and 25.e3
(all numbers are in hex).  If we only wanted to "ping" and trace to these
two systems, we could specify a five-bit destination address:

bin/trace 20/5
 trace to matching destination:
                1.099ms timestamp,      2.382ms rtt,  0 21.cd/16
 forward:      71.927ms timestamp,    114.970ms rtt,  0 21.cd/16  to  1 2d.5c/16
 trace to matching destination:
                1.099ms timestamp,      2.382ms rtt,  0 21.cd/16
               71.927ms timestamp,    114.970ms rtt,  1 2d.5c/16
              116.927ms timestamp,    253.480ms rtt,  2 25.e3/16

Here we see that 2d.5c did not identify with the address being traced,
and so is only listed as a forwarding system, not as a destination.
If we only wanted to trace 2d.5c, we can specify it outright:

bin/trace 2d.5c
 local:         0.498ms timestamp,      1.916ms rtt,  0 21.cd/16
 trace to matching destination:
                0.498ms timestamp,      1.916ms rtt,  0 21.cd/16
               75.097ms timestamp,    113.114ms rtt,  1 2d.5c/16
 forward:     116.097ms timestamp,    251.883ms rtt,  1 2d.5c/16  to  2 25.e3/16

Now, the other two allnet daemons have been identified as local and
forward, respectively.