========================= 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 not have been
tested as thoroughly.  You can get the source from sourceforge as follows:

	mkdir allnet
	cd allnet
	git clone git://git.code.sf.net/p/allnet/code .

If you plan to contribute to the code, replace the last line with these 4 lines:
	git init
	git remote add origin git://git.code.sf.net/p/allnet/code
	git pull origin master
        git branch --set-upstream-to=origin/master master

Any available binary releases are on https://alnt.org/

The same source is also at   https://github.com/biagioni/allnet.git
iOS source is available at   https://github.com/biagioni/allnet-ios.git
and Android source is at     https://github.com/biagioni/allnet-android.git

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

Before building, you may need to install libtool and autoconf.
On debian/ubuntu and similar systems this requires:
  sudo apt install libtool autoconf autotools-dev libdbus-1-dev pkg-config
You may also need to install git and either libssl-dev, or libssl<version>-dev
(libressl may be better than openssl if you can get it).
On other systems, use the native package manager to install these packages.
On Windows under cygwin, you will need at least automake and pkg-config.

to build this release from source, run these programs:
        ./autogen.sh
        ./configure
        make
optionally, follow this with  "sudo make install".  If you do install,
make sure that /usr/local/lib is in your LD_LIBRARY_PATH, e.g.
export LD_LIBRARY_PATH="/usr/local/lib"

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

you can also set specific CFLAGS with, e.g.:
        ./configure CFLAGS="-Wall -g"
(additional CFLAGS you might want to use include: -Werror -Wextra
-Wuninitialized -Winit-self -Wshadow -Wstrict-overflow)

additional packages you may need to install:
	Java: openjdk-<version>-jre openjdk-<version>-jdk  -- current
              version (February 2021) is 14, but 7, 8, 9, 11 may also work.
        for Voice-over-Allnet (voa): libgstreamer-plugins-base1.0-dev
              gstreamer1.0-plugins-base gstreamer1.0-plugins-bad
              (these bring in many other dependencies)

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

AllNet provides communication services designed to work whenever possible.
If there is no Internet, AllNet attempts to communicate wirelessly, even
in the absence of existing access points.  To use AllNet, you must run the
allnet program, and also a specific allnet app such as xchat.

The instructions that follow assume that allnet is installed in a
subdirectory of the current directory called "bin".  If you have done
"make install" above (instead of just "make"), or in any way installed
the binaries in your path, you should skip the "bin/" part.

    ================ running allnet ================

the first thing to run is
   bin/allnetd

this will start the allnet daemon (previously called astart and 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/allnetd"
(except "trace" doesn't start bin/allnetd).

    ================ ad-hoc wireless ================

Using the wireless in ad-hoc mode requires special privileges.  Giving
AllNet these privileges is optional -- if you are constantly connected
to the Internet, you do not need to do this.  But if you wish to connect
directly to devices near you, you will need to do ONE of the following:

   sudo bin/allnetd
(sudo): runs allnet as the root user.  You probably will have to enter your
password.

   sudo chown root bin/allnetd ; sudo chmod u+s bin/allnetd 
(setuid): this only needs to be done once (you probably will have to
enter your password), and will run AllNet as the root user until you undo
it by removing bin/allnetd and running "make" again.

After "chown" and "chmod", "bin/allnetd" will use the ad-hoc wireless
(if any) even without "sudo".

If your system doesn't have sudo, you will need to figure out how to run
"bin/allnetd" (or the "chown" and "chmod" programs) with root privileges
(typically "su", then enter the commands without "sudo").

    ================ allnet user programs (allnet apps) ================

Current AllNet user programs include the AllNet chat programs xchat and xt,
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 (as long as you have 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) key exchange ========

Before you can chat with somebody, you have to have their key, and they
have to have your key.

To exchange keys, you must have some way to exchange a shared secret
string that identifies your keys to each other.  The best way to do this
is in person or over the phone.

To exchange keys, click on "New Contact", enter your contact's name,
and press "go".  This will give you a "shared secret" string that you
must give to your contact (the string may be entered in UPPER, Mixed,
or lower case).  Your new contact has to enter your shared secret before
pressing "go".

The contact's name can be anything you choose.  It is not used in the
key exchange, and only used to identify the contact to you within xchat
and other allnet programs.

       ======== xt (text-based allnet chat) ========

xt is similar to xchat, but does not have a GUI.  Instead, it has
two menus.  The first, displayed by default when you start, gives
a number of options, all beginning with '.'.  Any line that does
not begin with dot is text which is sent to the default contact shown
in the prompt (caution -- it is easy to send to a contact other than
the one that was intended).  This default contact is the last one to
whom you sent a message, if any.

The only command that is not intuitive is .k, to connect with other
users and manage creating and sending keys.  To create a new contact, try
  .k contact-name 5
xt will print a secret (e.g. ABCDEF) which the other side can use
to connect.  If the other side is also using xt (they could be using one
of the other chat programs as well), they would type
  .k your-name 5 ABCDEF
to connect to you.

Once both sides have completed the key exchange,
  .k - contact-name
will terminate the key exchange.  However, be sure not to do this
until the other side has received your key.  If this is slow, you
may resend the key with
  .k + contact-name

When you just type .k, it will list any pending key exchanges, each
next to a number 1, 2, 3, ...   In the above commands, you may use
the number instead of the contact name if you prefer.

       ======== command-line chat ========

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 terminal windows.

In one terminal window simply run
   bin/xchatr

In another terminal window, run
   bin/xchats contact-name message

where "contact-name" is the name of your contact as specified in the
key exchange (see above and below), and "message" is the message you
want to send to your contact.  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!"

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

Before you can chat with somebody, you must exchange keys.  This can be
done from the GUI, using the "New Contact" tab, or using bin/xchats -k

In order to securely exchange keys, you and your contact must both know
a shared secret string that is provided for you by either the GUI, or
the .k command in xt, or xchats -k.  Only one side needs to enter the
other side's secret string -- as long as one of the two secret strings
is used, it does not matter which of the two.  The string may be entered
in UPPER or Mixed or lower case, and spaces do not matter.

The secret string must be exchanged in an authenticated way between you
and your contact.  That means you must be sure that it is really your
contact 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

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

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 5 or 10 otherwise.

If the exchange is not successful, the contact may have been partially
created.  If that is the case, 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 -- note they are in universal
time, that is, GMT), then, if you really want to remove it, do so using
   mkdir -p ~/.allnet/unused
   mv ~/.allnet/contacts/YYYYMMDDhhmmss ~/.allnet/unused/

            ======== Voice over Allnet (voa) ======== 

The voice over AllNet application provides for real-time secure voice
communications.  It has been tested, but not extensively.

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

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

To identify a sender, you must be in possession of their 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 only needed if the personal phrase includes spaces or
other special characters.

If you decide to create your own ahra, you choose your own personal
phrase -- it can be anything you want.  Unlike an email address, a
personal phrase does not have to be unique, and others may have the same
personal phrase.  Again, upper- and lower-case are treated the same.
(0, O, o, q and Q are treated as the same letter, as are 1, i, I, L, and l)

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
require allnet-generate to run longer before finding a valid 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 have 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 ahra.  For example, AllNet runs an hourly time signal
server with ahra
   allnet_hourly_time_server@for_time.for_game.there_work.from_health

and you can subscribe and listen to this time server by running:
   bin/allnet-subscribe allnet_hourly_time_server@for_time.for_game.there_work

   bin/allnet-radio

The second command will run forever, and once an hour, on the hour,
if you are receiving the time signal broadcasts, will print out a
corresponding message.  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

xtime is the program used to send the allnet time signals.  For a
more generic broadcast program, use bin/broadcast.

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

The trace program is used to find and print a path to a destination.
Each allnet daemon picks a different ID when it is first 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 round-trip time (rtt) is always accurate, whereas the timestamp is
only accurate if the clock on your system is synchronized with the clock
on the system that responded.

The first response is always from the local AllNet daemon, so in this example
we know that 21.cd/16 is our own local address.

If you want to change your ID, remove ~/.allnet/adht/my_id.  If you want
to get a new ID each time you restart allnet, replace the contents of
~/.allnet/adht/my_id with a '-' character.

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.

To simulate conventional ping, run trace with -m -i and the destination,
and either -f (to run forever), or -r x, to repeat x times.  Use -t 1
to get one ping per second (trace by default waits 5s for replies).

bin/trace -f -t 1 -m -i 43
   1:              406.760ms timestamp,     725.329ms rtt,  1 43.c2/16
   2:              428.699ms timestamp,     778.383ms rtt,  1 43.c2/16
   3:              424.119ms timestamp,     758.286ms rtt,  1 43.c2/16

trace supports several options.  Run trace with an invalid option (e.g.
bin/trace -q) to find out more.

            ======== comments and suggestions ========

If you have suggestions for improvement, please let us know at esb@hawaii.edu.