AllNet project (http://alnt.org/)
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
doc
m4
script
src
.gitignore
AUTHORS
ChangeLog
LICENSE
Makefile.am
NEWS
README
autogen.sh
clean.sh
configure.ac

README

========================= 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 3 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-get 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 (September 2018) is 11, but 7, 8 and 9 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/allnet default

this will start the allnet daemon (previously called astart).  It will
also print the interfaces allnet is trying to use to communicate (see below
under "ad-hoc wireless").  AllNet will also communicate over the Internet
if available.

If you omit the word "default", AllNet will only communicate over
the Internet.

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/allnet default".

    ================ 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/allnet default
(sudo): runs allnet as the root user.  You probably will have to enter your
password.

   sudo chown root bin/allnet ; sudo chmod u+s bin/allnet 
(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/allnet and running "make" again.

After "chown" and "chmod", "bin/allnet default" will use the ad-hoc
wireless even without "sudo".

If your system doesn't have sudo, you will need to figure out how to run
"bin/allnet default" (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 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 (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.

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

In one terminal window simply run
   bin/xchatr

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

where "friends-name" is the name of your friend as specified in the
key exchange (see above and 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!"

         ======== 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 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.  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.

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

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