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