Installation¶
System dependencies¶
The following software must be installed:
[tor] (last stable version is recommended, see [CoreTorReleases]) To use only exits that implement congestion control, tor >= 0.4.7.4-alpha-dev
[Python3] (>= 3.7)
Additionally, a PostgreSQL database is needed (see Create the database) and a system user with HOME to store the configuration, logs and other data.
There are example scripts to install and run onbrisca
at
./deploy_onbrisca.
Python dependencies¶
The version of the following dependencies might be unupdated. The list of updated versions is in the [setup.cfg] file.
[aiohttp] >= 3.7, only in the case of installing
onbrisca
[aiohttp-socks] >= 0.5, only in the case of installing
onbrisca
[colorlog] >= 4.7
[Django3] or [Django_4.1] only in the case of installing
onbrisca
[gunicorn] >= 2.1, only in the case of installing
onbrisca
[Psycopg2] >= 2.8
[stem] >= 1.8.0
[requests] (with [socks] support) >= 2.10.0
[toml] >= 0.10
It is recommend to install the dependencies from your system package manager.
As of February 2023, the following dependencies can be install from Debian bullseye by an user with root permissions:
apt install python3-stem python3-aiohttp-socks python3-psycopg2 \
python3-requests python3-toml python3-virtualenv
[Django_4.1] is not available in Debian stable, as well as the versions of
two of its dependencies: asigref
and python-socks
.
For onbrisca
see also the script at
./deploy_onbrisca/install_root.sh .
Installation from source¶
At the moment, there’re no system packages for onbasca
and it must be
install from source.
A system user with HOME can install onbasca
with the following steps:
Clone onbasca
:
git clone https://gitlab.torproject.org/tpo/network-health/onbasca.git
git checkout $(git describe --abbrev=0 --tags)
(git describe --abbrev=0 --tags
provides the latest stable version which
should be used in production)
If you’re installing onbasca
for development or testing, it’s recommend to
install all the dependencies and packages in a [virtualenv].
To create a virtualenv using the already installed system packages:
virtualenv --system-site-packages <virtualenvpath>
source <virtualenvpath>
After creating and activating the virtualenv you can install the dependencies with the command:
cd onbasca
pip install .
If the virtualenv was created with --system-site-packages
option, only
[Django_4.1], python-socks
and asgiref
(>=3.6) should be install
from [PyPI].
Note
In Debian, python3-python-sock
is a different package than
python3-socks
.
See also the script at ./deploy_onbrisca/install_onbrisca.sh .
Create the database¶
In a Debian system with root permissions:
su postgres
psql
create user <username> with password '<password>';
create database <dbname>;
grant all privileges on database <dbname> to <username>;
See also the script at ./deploy_onbrisca/install_root.sh .
Database configuration and initialization¶
After having a database for onbasca
, set the credentials in either
onbascapr/settings/local.py
(if installing the relay bandwidth scanner) or
onbriscapr/settings/local.py
(if installing the bridge bandwidth scanner).
There’s an example file that you can copy and customize at ./deploy_onbrisca/local.py.
After that, create the database schema for onbasca
running:
./manage.py makemigrations onbasca
Or for onbrisca
running:
./manage_onbrisca.py makemigrations onbasca
./manage_onbrisca.py makemigrations onbrisca
Then create the tables:
./manage.py migrate
See also the script at ./deploy_onbrisca/install_onbrisca.sh .
Configuration¶
A config.toml
is needed.
In the case of onbasca
place it in $HOME/.onbasca/.
In the case of onbrisca
place it in $HOME/.onbrisca/.
For onbrisca
, there is an example file at
./deploy_onbrisca/config.toml .
When onbrisca
is configured to use specific middle relays (the default),
it is also needed to place a file call middles.txt
in $HOME/.onbrisca/
.
This file will have a middle relay fingerprint by line.
For onbasca
, see Deployment.
Run the scanner and the generator for development¶
To run the scanner and the generator:
./manage.py scan
./manage.py generate
or:
./scan.py
./generate.py
Run the bridge scanner for development¶
To run the bridge scanner:
./manage_onbrisca bridgescan
or:
./bridgescan.py
To run the development Web API server:
./manage_onbrisca runserver
Run the scanner and the generator for production¶
See DEPLOY.rst (in the local directory or Tor Project Gitlab) or DEPLOY.html (local build).
Run the bridge scanner for production¶
It’s recommended to create systemd units to run both the scanner and the Web API server. There’re example systemd files at ./deploy_onbrisca/systemd/user and how to launch them at ./deploy_onbrisca/start.sh .