Deployment¶

Warning: Lightnion is an alpha-stage software which is not fit for production at this point.

Prerequisites¶

Test on local machine¶

Any modern hardware should have enough resources to run Lightnion. Chutney can be used to simulate a Tor network to which Lichtnion can connect.

Test on real environment¶

To test the Lightnion proxy in a real environment, a server with at least 1 GB of memory and a reasonnable amount of bandwidth is needed. In the mode where the Tor circuit is computed in the proxy 2 GB of memory are necessary.

To function properly, the Lightnion proxy needs to interact with a Tor relay, which will act as the guard of all Tor circuits build with Lightnion. To install a Tor relay on your system, please refers to the documentation from the Tor project <https://trac.torproject.org/projects/tor/wiki/TorRelayGuide>, or the documentation of your distribution.

Also, to serve the Javascript client, encrypt, and redirect the proxy ports, a web server like Nginx is recommended. Please refer to the documentation of your distribution to install one.

Installation¶

At this stage of the development, there still hasn’t any distribution package for Lightnion. This software needs to be deployed from sources. It is constituted of two parts, a JavaScript client and a proxy between the client and the Tor network, which can be run either on the same server or on different machines. It is also advised to run a hidden Tor entry point on the server to act as the guard relay for the proxy.

Installation of the Proxy¶

The proxy requires Python 3.7 or superior and the libraries listed in the files requirements.txt and requirements-proxy.txt, which can be installed with pip. The proxy was tested on Debian Buster, it likely also work on other Linux distributions providing Python 3.7, but was not tested on them.

It is advised to use git to retrieve the sources.::: $ git clone –recurse-submodules https://github.com/spring-epfl/lightnion.git $ cd lightnion
It is strongly advised to install the Lightnion proxy in a virtual environment.::: $ virtualenv –python=python3 venv $ . venv/bin/activate
The dependances can be installed with pip.::: $ pip install -r requirements.txt -r requirements-proxy.txt

To work, the proxy needs to interact with a tor relay, which will be the entry point in the tor network. Therefore it is adviseable to install a hidden Tor relay on the machine. To do so, refer to the Tor documentation <https://2019.www.torproject.org/docs/debian.html.en>.

Installing Chutney (for testing locally)¶

Building the JavaScript Client¶

The minified bundle of the Javacript client needs to be build. A Makefile exists to simplify its building process:

$ cd js-client
$ make

The resulting file lightnion.bundle.js is a bundle containing Lightnion and all its dependancies. It can be served by a web server, and linked in a web page as any other JS library.

Testing Lightnion Locally¶

To Test Lightnion locally, it is necessary to run a local web server to dispatch the Lightnion Javascript client. This can be done easilly with Python’s HTTP server.:

$ cd js-client/demo
$ python -m http.server

then the proxy can be started with:::: $ source env/bin/activate (venv)$ python -m lightnion.proxy -vvv -s 127.0.0.1:9050 -c 8000 -d 9051

Web Server configuration¶

For a test on a real environment, a proper web server like Nginx or Apache is required, and the demo files copied to the root directory of the web server along with the Lightnion bundle.

By default, the connection between the client and proxy server is in clear. Ideally, this connection should be secure, and this will probably change in the near future.

A Typical Nginx configuration for a proxy server will look like this:

server {
	root /var/www/lightnion;
	index index.html;
	server_name lightnion.spring-lab.ch;

	location /lightnion/api/v0.1/channel/ {
		proxy_pass http://localhost:8765;
		proxy_http_version 1.1;
		proxy_set_header Upgrade $http_upgrade;
		proxy_set_header Connection "Upgrade";	
	}

	location /lightnion/ {
		proxy_pass http://localhost:4990;
	}

	location /guard {
		proxy_pass http://localhost:4990;
	}

	location /channels {
		proxy_pass http://localhost:4990;
	}

	location /consensus {
		proxy_pass http://localhost:4990;
	}

	location /descriptors {
		proxy_pass http://localhost:4990;
	}

	location /signing-keys {
		proxy_pass http://localhost:4990;
	}


	location / {
		try_files $uri $uri/ =404;
	}

	listen 443 default_server ssl;

	ssl_certificate /etc/letsencrypt/live/lightnion.spring-lab.ch/fullchain.pem;
	ssl_certificate_key /etc/letsencrypt/live/lightnion.spring-lab.ch/privkey.pem;
	ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;

	ssl_session_cache shared:SSL:10m;
	ssl_session_timeout 10m;

	ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
	ssl_prefer_server_ciphers on;

	ssl_ciphers "ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA:ECDHE-RSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-RSA-AES256-SHA256:DHE-RSA-AES256-SHA:ECDHE-ECDSA-DES-CBC3-SHA:ECDHE-RSA-DES-CBC3-SHA:EDH-RSA-DES-CBC3-SHA:AES128-GCM-SHA256:AES256-GCM-SHA384:AES128-SHA256:AES256-SHA256:AES128-SHA:AES256-SHA:DES-CBC3-SHA:!DSS";
}


server {
	listen 80;
	server_name lightnion.spring-lab.ch;
	rewrite ^ https://$server_name$request_uri? permanent;
}

Automatic Startup and Process Monitoring¶

To ensure Lightnion is running, systemd or an other init system can be used to notify the administrator and restart the process if necessary.

[Unit]
Description=Lightnion proxy
After=network.target

[Service]
TimeoutStopSec=2
Restart=on-failure
RestartSec=60
User=lightnion
Group=www-data
WorkingDirectory=/home/lightnion/lightnion
ExecStart=/home/lightnion/lightnion/venv/bin/python -m lightnion.proxy -vvv -s 127.0.0.1:9050 -c 8000 -d 9051
OnFailure=lightnion-fail.service

[Install]
WantedBy=multi-user.target

[Unit]
Description=Lightnion proxy failure notification

[Service]
Type=oneshot
ExecStart=/bin/echo 'Lightnion process failed' | /usr/bin/mailx -s "Lightnion process failed" lightnion@lightning-test