README.md

adtnUSev platform

The adtnUSev platform is a software service that enables computers to act as nodes of the communication network developed by the SeNDA research group in the context of the Ubiquitous Secure Electronic Voting (u-SEV).

This platform is based on the aDTN communication platform developed at SeNDA that is a Delay and Disruption Tolerant Networking following the ActiveDTN principles that allow routing software code to be propagated by the messages all over the network.

This document covers the system requirements, installation, an installation example, usage, update and uninstallation of the platform.

System requirements

The platform is available only for PC Machines 64 bits with debian-like Linux operating system and with at least a network interface available.

Installation instructions are only provided for Ubuntu trusty (14.04), Ubuntu utopic (14.10) and Debian wheezy (7.*). For information about how to install the platform in other unix-like systems, contact developers@senda.uab.cat.

Installation

Root privileges are necessary during the whole installation. Internet connection and apt-get application are also required during installation.

Download the public key of adtnusev deb report and add it to your apt-key manager

sudo sh -c 'wget -O - http://tao.uab.es/adtn/usev/conf/adtn.gpg.key | apt-key add -'

Update the sources.list files.

sudo wget -P /etc/apt/sources.list.d/ http://tao.uab.es/adtn/usev/conf/wheezy/adtn.list

Update the apt-get repository.

sudo apt-get update

Three different installation options are provided for nodes with different needs:

  • adtnusev: For basic nodes and observer nodes only.
  • adtnusev-lib: For nodes running applications.
  • adtnusev-tools: For nodes running applications with network connection checking tools.

Execute the line that fits better the needs of your node (ONLY ONE OF THE FOLLOWING):

sudo apt-get install adtnusev
sudo apt-get install adtnusev-lib
sudo apt-get install adtnusev-tools

During installation, you will be asked to enter the following information to properly configure your node:

  1. Set the adtn identifier (default is <hostname>). The adtn identifier must be unique.
  2. Set the IP (default is <available_network_interface_ip>). IP address is crucial for lower layer communication. All adtn nodes must have a unique IP address and must be in the same local network.
  3. Set the adtn port (default is 4556). The default port must be ok if you are running a single adtn platform instance per machine and there is no other application using it.

Observer nodes

The main difference between a DTN node and an adtnUSev node is the capability to set the node as observer. This makes the node able to sign any single message that passes over it, including bundles sent from this node.

To enable the observer functionality in a node, move to a random path and:

Generate the private key

openssl genrsa -out private.pem 2048

Generate the public key

openssl rsa -in private.pem -pubout -out public.pem

Edit the adtn config file (/etc/adtn/adtn.ini by default) to add the following lines:

[smeb]
private_key = <absolute_path_to_private_key>
public_key = <absolute_path_to_public_key>

Note: The signer id that will identify the signing observer is the SHA256 hash of the public key in format PKCS#1 DER. The signer id can be generated with the following command:

openssl rsa -in private.pem -pubout | openssl asn1parse -offset 24 -out private.der && cat private.der | sha256sum

Usage

Network management requires root privileges. Therefore, sudo is required to start, get status, supervise (start stopped processes), and stop the platform.

sudo service adtn start
sudo service adtn status
sudo service adtn supervise
sudo service adtn stop

Network usage, even to check connectivity, does not require root privileges (sudo). The available tools are:

  • adtn-ping: Sends a bundle to network nodes. For more info, execute adtn-ping -h.
  • adtn-neighbours: Shows the list of neighbour nodes. For more info, execute adtn-neighbours -h.
  • adtn-traceroute: Prints the route bundles take to network host. For more info, execute adtn-traceroute -h.

Example of installation and usage

This example shows how Alice (alice) installs a single adtnusev platform in her machine using adtnusev-tools.
# Download the public key of adtnusev deb report and add it to your apt-key manager
sudo sh -c 'wget -O - http://tao.uab.es/adtn/usev/conf/adtn.gpg.key | apt-key add -'
# Update the sources.list files.
sudo wget -P /etc/apt/sources.list.d/ http://tao.uab.es/adtn/usev/conf/wheezy/adtn.list
# Update the apt-get repository.
sudo apt-get update
# Install platform + development library + ping + traceroute
sudo apt-get install adtnusev-tools
# Set platform name as alice
# Accept default IP
# Accept default node
cd /home/alice/
mkdir .adtnUSev
cd .adtnUSev/
openssl genrsa -out private.pem 2048
openssl rsa -in private.pem -pubout -out public.pem
# Edit /etc/adtn/adtn.ini for smeb configuration to look like the following lines:
vi /etc/adtn/adtn.ini
[smeb]
private_key = /home/alice/.adtnUSev/private.pem
public_key = /home/alice/.adtnUSev/public.pem
# Run the platform
sudo service adtn start
# Run ping to your own machine
adtn-ping alice

Update

Update the apt-get repository in order to look for available updates:

sudo apt-get update

Repeat the installation:

sudo apt-get install adtnusev
sudo apt-get install adtnusev-lib
sudo apt-get install adtnusev-tools

Uninstall

Uninstalling the platform requires executing the following line.

sudo apt-get remove --purge adtnusev

Notice that --purge flag removes all adtnUSev configuration files.

If you also want to remove the public key of the adtnUSev deb repo from the apt-key manager, execute the following lines:

sudo apt-key del  `apt-key list | grep -i -1 developers@senda.uab.cat | grep pub | cut -d '/' -f2- | cut -d ' ' -f1`
sudo rm /etc/apt/sources.list.d/adtn.list

Troubleshooting

The following issues have been detected and documented in order to facilitate its fix by the platform users.

You don't see any neighbour

Perhaps your platform is the unique platform running in your local network. Check that the other platforms are running and belong to the same local network. It is a common mistake to think that two machines with Internet connection are by default in the same local network. Even if they are in the same room, that will depend on the router that they use for TCP/IP connection.

Most personal computers use DHCP to get a dynamic IP. If this is your case, perhaps the platform configuration is not valid anymore because of a change in your local IP address. Check the platform current ip typing sudo service adtn status. If it is not your current local IP address, then edit the platform configuration file (/etc/adtn/adtn.ini by default) and set the IP value to the current local IP of your machine. Take into account that changing the platform configuration file requires the platform to be stopped and started again in order to apply those changes.

You see neighbours but messages don't arrive to its destination

You can check that messages don't arrive to a particular neighbour platform executing adtn-ping <neighbour_id>. If no successful response arrives, then you may be in a different sub-network. In this case, contact your network administrator to fix it for you. Notice that if this is the case, sometimes traditional ping <neighbour_ip> works even when adtn-ping doesn't.

Other troubles

In general, we recommend you to to execute sudo service adtn status in order to ensure that all processes are currently running. If there's any stopped process, stop and start the platform again. If the processes persist stopped, contact developers@deic.uab.cat.

Example of installation and usage of multiple platforms per machine

This example shows how Alice installs a new platform in her machine. In the following, we assume that a platform installation has already been executed following the steps included in the previous example.

Every single platform needs a different id, TCP/IP port, data path and configuration file. The platform id, TCP/IP port and data path values are included into the platform configuration file. By default, this values are set during platform installation from apt-get repository and stored in the default configuration file at /etc/adtn/adtn.ini. In order to install more platforms, follow the steps bellow:

# Create a new data directory for <new_platform>.
sudo mkdir /var/lib/adtn_<new_platform>
# Change the owner of the data directory
sudo chown adtn:adtn /var/lib/adtn_<new_platform>
# Create a copy of the adtn.ini file
sudo cp /etc/adtn/adtn.ini /etc/adtn/adtn_<new_platform>.ini
# Edit the content of the configuration file in order to set a new TCP/IP port and the platform id and the data path:
nano /etc/adtn/adtn_<new_platform>.ini
[global]
id = <new_platform>
port = <new_port>
data = /var/lib/adtn_<new_platform>
# Create a new key directory
cd /home/alice/
mkdir .adtnUSev_<new_platform>
cd .adtnUSev_<new_platform>
openssl genrsa -out private.pem 2048
openssl rsa -in private.pem -pubout -out public.pem
# Edit the new platform configuration file for smeb configuration to look like the following lines:
nano /etc/adtn/adtn_<new_platform>.ini
[smeb]
private_key = /home/alice/.adtnUSev_<new_platform>/private.pem
public_key = /home/alice/.adtnUSev_<new_platform>/public.pem
# Run the new platform
sudo service adtn start /etc/adtn/adtn_<new_platform>.ini
# Check the new platform status
sudo service adtn status /etc/adtn/adtn_<new_platform>.ini
# Run neighbours from the new platform, the default platform must be also visible
adtn-neighbours --conf_file /etc/adtn/adtn_<new_platform>.ini
# Run ping from alice to the new platform at your machine. Both options are equivalent
adtn-ping <new_platform>
adtn-ping --conf_file /etc/adtn/adtn.ini <new_platform>
# Run a ping to alice from the new platform
adtn-ping --conf_file /etc/adtn/adtn_<new_platform>.ini alice
# Stop all platforms (stopping a single platform is not available)
sudo service adtn stop