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