{"id":13550146,"url":"https://github.com/ralphwetzel/theonionbox","last_synced_at":"2025-04-02T23:32:03.940Z","repository":{"id":57475098,"uuid":"48622560","full_name":"ralphwetzel/theonionbox","owner":"ralphwetzel","description":"Dashboard to monitor Tor node operations","archived":false,"fork":false,"pushed_at":"2023-07-26T06:51:04.000Z","size":16444,"stargazers_count":120,"open_issues_count":21,"forks_count":17,"subscribers_count":11,"default_branch":"master","last_synced_at":"2024-04-23T19:20:42.198Z","etag":null,"topics":["exit","monitor","onionbox","onionoo","relay","the-onion-box","theonionbox","tor"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ralphwetzel.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":"support/osxtemp/libsmc/LICENSE","governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2015-12-26T20:20:52.000Z","updated_at":"2024-04-20T12:40:11.000Z","dependencies_parsed_at":"2024-04-23T19:06:20.271Z","dependency_job_id":"ce7b6172-da38-4d0b-a87f-b4ea38a26bfa","html_url":"https://github.com/ralphwetzel/theonionbox","commit_stats":{"total_commits":232,"total_committers":5,"mean_commits":46.4,"dds":0.09051724137931039,"last_synced_commit":"9812fce48153955e179755ea7a58413c3bee182f"},"previous_names":[],"tags_count":42,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ralphwetzel%2Ftheonionbox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ralphwetzel%2Ftheonionbox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ralphwetzel%2Ftheonionbox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ralphwetzel%2Ftheonionbox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ralphwetzel","download_url":"https://codeload.github.com/ralphwetzel/theonionbox/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246911262,"owners_count":20853653,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["exit","monitor","onionbox","onionoo","relay","the-onion-box","theonionbox","tor"],"created_at":"2024-08-01T12:01:29.446Z","updated_at":"2025-04-02T23:32:02.298Z","avatar_url":"https://github.com/ralphwetzel.png","language":"JavaScript","funding_links":[],"categories":["JavaScript","\u003ca id=\"6e80463404d46f0493cf6e84597e4b5c\"\u003e\u003c/a\u003e工具"],"sub_categories":["\u003ca id=\"e99ba5f3de02f68412b13ca718a0afb6\"\u003e\u003c/a\u003eTor\u0026\u0026\u0026Onion\u0026\u0026洋葱"],"readme":"# The Onion Box\n[![GitHub tag](https://img.shields.io/github/tag/ralphwetzel/theonionbox.svg?style=flat-square\u0026label=GitHub)](https://github.com/ralphwetzel/theonionbox/releases/latest)\n![Github commits (since latest release)](https://img.shields.io/github/commits-since/ralphwetzel/theonionbox/latest.svg?style=flat-square)\n[![License](https://img.shields.io/pypi/l/theonionbox.svg?style=flat-square)](https://github.com/ralphwetzel/theonionbox/blob/master/LICENSE)\n\n[![Latest PyPi](https://img.shields.io/pypi/v/theonionbox.svg?style=flat-square)](https://pypi.org/project/theonionbox)\n![Supported Python versions](https://img.shields.io/pypi/pyversions/theonionbox.svg?style=flat-square)\n![Status](https://img.shields.io/pypi/status/theonionbox.svg?style=flat-square)\n\n---\n### The Onion Box v19: Preliminary documentation\n## The ControlCenter\n\nThis latest version of The Onion Box introduces three changes of relevance:\n* The current versioning scheme was dropped in preference for [Calendar Versioning](www.calver.org). Thus v19.2 will become the successor of v4.3.1.\n* The Onion Box v19.2 and later requires Python 3.6 or Python 3.7. If you need to operate with Python2, you have to stay with The Onion Box v4.3.1.\n* In addition to the well known (legacy) dashboard, suitable to monitor just a single Tor instance, The Onion Box now provides a ControlCenter mode to monitor a(ny) number of Tor nodes in parallel. That's how it looks like:\n\n![image](docs/images/cc.png)\n\nThis is the shorttrack way to enable the ControlCenter mode:\n\n1) Setup your Onion Box as you did before - and you'll get the legacy dashboard (as before).\n2) Create a configuration file, that shall be used to store the configuration data of the ControlCenter. The easiest way to do this on a *nix-type system:\n    ```\n    (theonionbox) ~/theonionbox $ touch cc.cfg\n    ```\n    Please ensure write privileges for that file to the user running your Onion Box.\n3) Tell your Onion Box where to find this configuration file - via the command line parameter `--controlcenter` or `-x`:\n\n```\n(theonionbox) ~/theonionbox $ theonionbox -x cc.cfg\n```\n\n4) Use the + - button in the upper right corner of the ControlCenter to add additional Tor nodes to be monitored.\n\n5) The legacy dashboard with detail data for each node will show up if you follow the dedicated 'Show Details' link of each node.\n\n6) To re-arrange the nodes in your ControlCenter, just Drag \u0026 Drop them around.\n\nEnjoy!\n\n\n---\n\n_The Onion Box_ provides a web interface to monitor the operation of\na [Tor](https://www.torproject.org) node. It is able to monitor any Tor node operated as relay, as bridge and even as client - as long as it can establish a connection to the node and authenticate successfully.\n\nThe connection to the Tor node to be monitored may be established via a local `ControlSocket` or a `ControlPort` (local or remote). Advanced users may establish a connection via the Tor network to a node proving access to it's `ControlPort` by means of a Hidden Service - supporting on demand as well [Hidden Service Client Authorization](https://www.torproject.org/docs/tor-manual.html.en#HiddenServiceAuthorizeClient).\n\n_The Onion Box_ supports whatever authentication method the Tor node provides.\n\nA single instance of _The Onion Box_ is able to provide monitoring functionality for as many nodes as you like.\n\nAbove that, _The Onion Box_ is able to display Tor network status protocol data for any Tor node known by [Onionoo](https://metrics.torproject.org/onionoo.html).\n\n[TOC levels=3 markdown bullet formatted hierarchy]: # \"## Table of Contents\"\n\n## Table of Contents\n- [The Web Interface](#the-web-interface)\n    - [Header](#header)\n    - [General Information](#general-information)\n    - [Configuration](#configuration)\n    - [Hidden Services](#hidden-services)\n    - [Local Status](#local-status)\n    - [Network Status](#network-status)\n    - [Control Center](#control-center)\n    - [Messages](#messages)\n- [Getting Started](#getting-started)\n    - [Scenario Assumption](#scenario-assumption)\n    - [Supported environment](#supported-environment)\n    - [System Preparation](#system-preparation)\n    - [Installation](#installation)\n    - [Verification of the installation](#verification-of-the-installation)\n    - [First Flight](#first-flight)\n    - [If it doesn't fly...](#if-it-doesnt-fly)\n- [Dependencies](#dependencies)\n- [Configuration by file](#configuration-by-file)\n    - [Location](#location)\n    - [Structure](#structure)\n- [Command line parameters](#command-line-parameters)\n    - [Deprecated parameters](#deprecated-parameters)\n- [Advanced Operations: Authentication](#advanced-operations-authentication)\n    - [Cookie Authentication](#cookie-authentication)\n    - [Password Authentication](#password-authentication)\n    - [No Authentication](#no-authentication)\n- [Advanced Operations: Control Interface](#advanced-operations-control-interface)\n    - [Caution](#caution)\n    - [ControlSocket](#controlsocket)\n    - [ControlPort](#controlport)\n    - [ControlPort via Proxy](#controlport-via-proxy)\n- [Hidden Service Operations](#hidden-service-operations)\n    - [Basic configuration](#basic-configuration)\n    - [Access control](#access-control)\n- [_The Onion Box_ as system service (aka daemon)](#the-onion-box-as-system-service-aka-daemon)\n    - [Logging to syslog](#logging-to-syslog)\n    - [Optional syslog configuration](#optional-syslog-configuration)\n    - [Prepared launcher scripts](#prepared-launcher-scripts)\n    - [... on FreeBSD](#-on-freebsd)\n    - [... using init.d](#-using-initd)\n    - [... using systemd](#-using-systemd)\n- [*The Onion Box* behind Apache's mod_proxy](#the-onion-box-behind-apaches-mod_proxy)\n- [*The Onion Box* Docker support](#the-onion-box-docker-support)\n- [Usage Monitoring](#usage-monitoring)\n- [Q\u0026A](#qa)\n    - [I receive a _Not supported proxy scheme socks5h_ warning. What shall I do?](#i-receive-a-not-supported-proxy-scheme-socks5h-warning-what-shall-i-do)\n    - [I get a _Memory Error_ when trying to install via pip](#i-get-a-memory-error-when-trying-to-install-via-pip)\n- [Shorttrack](#shorttrack)\n- [Acknowledgments](#acknowledgments)\n\n\n\n## The Web Interface\n_The Onion Box_ generates a 'web page' that displays information regarding your Tor node. This information is split up into a number of sections. If a section is displayed and how the section looks like, depends on the data your box received from the Tor node monitored or knows about it from the Tor network status protocol. The web interface is generated on demand based on the latest data available.\n\n\u003e Tip: If a dedicated section is not displayed, just reload the page. Press `F5` or `command + R` to re-run the page creation process.\n\nThe following chapters introduce each available section and provide some further details to explain the content displayed:\n\n---\n\n### Header\nThe Header of the page shows some basic information about the Tor node monitored.\n\n![image](docs/images/header.png)\n\nIf you connected to this node via [password authentication](#password-authentication), you'll find a Logout Button in the upper right corner.\n\nIf your box discovers that there is an update of it's code available, a button in the upper left corner is displayed, providing access to some further information - and a link to GitHub.\n\n------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------\n\n### General Information\nThe section _Host | General Information_ displays information regarding the host system.\n\n![image](docs/images/generalinfo.png)\n\nThis section is only available if the box is running at the same physical device as the Tor node monitored.\n\n_Latest Reboot_ as well as _Temperature_ are only available on supported operating systems.\n\nIf the host provides several CPU cores, you may click on the _CPU Usage_ chart to get a popup window displaying a seperate usage chart for each core.\n\n---\n\n### Configuration\nThe section _Tor | Configuration_ displays the configuration parameters of the Tor node monitored:\n\n![image](docs/images/configuration.png)\n\n_Commandline_ lists the command line parameters used when launching the Tor node.\n\n_Configuration Files_: A Tor node is configured by several sets of parameters. Those are Tor internal default settings, default settings defined in a configuration file referenced as _torrc.default_ (usually given by the Tor developers), user defined parameters (usually in a configuration file referenced as _torrc_) and finally parameters defined via the command line. The path to the two configuration files is indicated here.\n\nThe rest of this section displays all parameters that differ from the Tor internal default settings - except Hidden Service configuration settings (which are displayed in their own section).\n\nIf the curser hovers over the name of a configuration parameter, a hashtag is displayed providing a link to the Tor documentation. On mobile devices, you have to click on the name to make the hashtag appear.\n\nThere are some parameters that can be defined (e.g. via the command line), despite Tor doesn't signal back that those are set. The following table lists those parameters:\n\n| Non-displayable Parameters |\n|---|\n| __OwningControllerProcess |\n\n---\n\n### Hidden Services\nThe section _Tor | Hidden Services_ displays the configuration parameters for the hidden service(s) of the Tor node monitored:\n\n![image](docs/images/hidden.png)\n\nThis section is only available if at least one hidden service is configured on this Tor node.\n\n---\n\n### Local Status\nThe section _Tor | Local Status_ displays information that the Tor node monitored knows about itself and its hosting environment.\n\n![image](docs/images/local.png)\n\n ---\n\n### Network Status\nThe section _Tor | Network Status_ displays information provided by [Onionoo](http://onionoo.torproject.org), the Tor network status protocol, concerning the Tor node monitored.\n\n![image](docs/images/network.png)\n\nThose information are fetched regularly from Onionoo. If not available (which could happen when you connect to a node for the first time or when operating via slow connections), you will be asked to reload the page.\n\nOnly portions of this section are available if the Tor node monitored is operated as a bridge.\n\n_Location_ by default provides the information Onionoo knows about the location of the Tor node \u0026 shows the location on a map.\n\n![image](docs/images/location.png)\n\nBy special configuration you can advise the box to query the location of the IP address of the Tor node monitored from a user provided GeoIP City DB.\n\n_Bandwidth_ displays the bandwidth history data as known to Onionoo.\n\n![image](docs/images/bandwidth.png)\n\nThe number of available charts depends on the age of the Tor node monitored. You may switch the chart displayed via the _History Charts_ buttons.\n\n_Weights_ displays the weights history data as known to Onionoo.\n\n![image](docs/images/weights.png)\n\nThe number of available charts depends on the age of the Tor node monitored. You may switch the chart displayed via the _History Charts_ buttons.\n\n---\n### Control Center\n~~Do you intend to monitor more than one Tor node? Are you interested in the Oninooo data of other Tor nodes? The section _Box | Control Center_ provides that functionality.~~\n\n![image](docs/images/control.png)\n\n#### Search\n~~Enter a search phrase - which should be a (part of a) nickname of a Tor node or a (portion of a) fingerprint - into the _Search_ field and press enter. This search phrase will be used to query Onionoo - and the result presented in a popup bubble. If the search was successful, you may click on the links provided to display the Tor network status protocol data of that Tor node.~~\n\n#### Controlled Hosts\n~~If you provided access control information for additional Tor nodes in the configuration file of your box, those nodes are listed under _Controlled Hosts_. Click on the fingerprint and you will be connected to that Tor node.~~\n\n---\n\n### Messages\nThe section _Box | Messages_ displays the messages received from the Tor node(s) monitored and from your box.\n\n![image](docs/images/messages.png)\n\nYou can alter the noisiness of the Tor node monitored by mean of the _Level_ selector buttons. Be advised that it takes some seconds to forward a message level change to the node.\n\u003e By default, _INFO_ and _DEBUG_ level messages are not forwarded to the monitoring application. _INFO_ is babblative - and _DEBUG_ even more. Both levels create a lot of traffic. Use those settings with caution!\n\nThis section is only available for controlled nodes.\n\n\u003e The message system of _The Onion Box_ cannot be manipulated via the web interface. If you are interested in receiving _DEBUG_ or _TRACE_ message from your box, you have to set the appropriate [command line](#command-line-parameters) parameter.\n\n---\n\n## Getting Started\nThis chapter leads you through the installation procedure of you own _Onion Box_.  \nThe level of detail provided here should allow everyone, being a Novice or an Expert in the world of Tor, to successfully set up his personal box. If you encountered any issues - due to whichever reason - drop me a line and I will try to improve this description to meet your demands.\n\n### Scenario Assumption\nFor the following tutorial I will assume a quite common scenario, the intension to install _The Onion Box_ on a Raspberry Pi with Raspbian running a Tor node. This makes it easier to explain the procedures given a precise use case rather than elaborating through all potentional\nshoulds and coulds.\n\u003e If you encounter a situation that is significantly different from this scenario, let's discuss how to amend the description to cover those specialities.\n\nSo we assume that you're logged in as user **pi**, operating on the **PIXEL** desktop (which is the default Raspbian desktop). Your starting point should look like this:\n\n\u003cp  align=\"center\"\u003e\u003cimg src='docs/images/raspbian.png' width='50%'\u003e\u003c/p\u003e\n\n### Supported environment\n_The Onion Box_ is a Python application, developed with v2.7 and v3.6.\n\nBy default, it should operate successfully on every platform providing Python support. Confirmation can be given that it works properly in following environments:\n- Bananian | [Jessie](https://github.com/ralphwetzel/theonionbox/issues/7#issuecomment-346902660)\n- Debian | Jessie\n- FreeBSD\n- macOS | Darwin\n- Raspbian | Jessie, Stretch\n- Ubuntu 16.04\n- Windows 10\n\nThe Python version you are operating with (per default), can be verifyed via a terminal / command line by the issuing `python --version`:\n```\n~ $ python --version\npython 2.7.9\n```\nAs said, this displays the version of the _default_ Python interpreter. Explicitely you may use as well `python2 --version` or `python3 --version` to ask for the version numbers of the dedicated releases.\n\n_The Onion Box_ is designed to run with either Python \u003e 2.7.9 or Python \u003e 3.6. If _none_ of your Python versions fit these reqirements, check [the Python page](http://www.python.org) for procedures how to upgrade your installation. On a Linux system, you could e.g. run `apt-get` like\n```\n~ $ sudo apt-get install --upgrade python\n~ $ sudo apt-get install --upgrade python3\n```\nto install the latest versions available in the repositories.\n\n### System Preparation\n#### sudo\nThere is a prerequisite you should check prior to anything else: Is your `sudo` setup working? Is `sudo` installed and has your account adequate `sudo` privileges?\n\nTo verify those aspects, open a terminal and just type `sudo`:\n```\n~ $ sudo\nusage: sudo -h | -K | -k | -V\nusage: sudo -v [-AknS] [-g group] [-h host] [-p prompt] [-u user]\nusage: sudo -l [-AknS] [-g group] [-h host] [-p prompt] [-U user] [-u user]\n            [command]\nusage: sudo [-AbEHknPS] [-r role] [-t type] [-C num] [-g group] [-h host] [-p\n            prompt] [-u user] [VAR=value] [-i|-s] [\u003ccommand\u003e]\nusage: sudo -e [-AknS] [-r role] [-t type] [-C num] [-g group] [-h host] [-p\n            prompt] [-u user] file ...\n~ $ \n```\nIf `sudo` is installed, it should answer with it's help message.  \nIf not, you need an **account with root privileges** to install it:\n```\nroot@raspberrypi:/# apt-get install sudo\n```\nThe `sudo` system grants `sudo` rights to the members of the group `sudo`. To verify this for your current account, use the `getent` command. Working with user `pi`, you would issue a\n```\n~ $ getent group | grep pi\n[...]\ncdrom:x:24:pi\nsudo:x:27:pi\naudio:x:29:pi\nvideo:x:44:pi\n[...]\n```\nThe line\n```\nsudo:x:27:pi\n```\ntells you that `pi` is member of the `sudo` group.  \nIf you don't get such a feedback, you have to grant your account membership of this group. Again, you need an **account with root privileges**:\n```\nroot@raspberrypi:/# usermod -g sudo pi\n```\n\u003e Alternatively you could log in with another account who already has sudo privileges to issue a `sudo usermod -g sudo pi`.\n\nFor verification, use again the `getent` command!\n```\n~ $ getent group | grep pi\n[...]\ncdrom:x:24:pi\nsudo:x:27:pi\naudio:x:29:pi\nvideo:x:44:pi\n[...]\n```\n\n#### virtualenv\nI strongly recommend to run _The Onion Box_ in a [Python Virtual Environment](https://docs.python.org/3/tutorial/venv.html) . The additional effort is (almost) zero - yet you gain certainty that the environment is and stays perfect for operating your box:\n\nOpen a terminal and start your system preparation by installing the Python _virtualenv_ package:\n```\n~ $ sudo pip install virtualenv\nCollecting virtualenv\n  Using cached virtualenv-15.1.0-py2.py3-none-any.whl\nInstalling collected packages: virtualenv\nSuccessfully installed virtualenv-15.1.0\n```\nAfter this successfully completed, create the virtual environment for your box in a dedicated directory, e.g. `./theonionbox`:\n\u003e There is no need to exactly use `theonionbox` as the name for the directory to create the virtual environment in; thus choose whatever you like yet ensure that it is a valid directory name and not pre-occupied.\n```\n~ $ virtualenv theonionbox\nNew python executable in /home/pi/theonionbox/bin/python\nInstalling setuptools, pip, wheel...done.\n```\nTo verify the installation, change into the directory created (`cd theonionbox`) and list its content with `ls -l`:\n```\n~ $ cd theonionbox\n~/theonionbox $ ls -l\ntotal 20\ndrwxr-xr-x 2 pi pi 4096 Jan 18 19:21 bin\ndrwxr-xr-x 2 pi pi 4096 Jan 18 19:21 include\ndrwxr-xr-x 3 pi pi 4096 Jan 18 19:21 lib\n-rw-r--r-- 1 pi pi   60 Jan 18 19:21 pip-selfcheck.json\n~/theonionbox $\n```\nIf your's looks equivalent, you've successfully created this virtual environment.\n\u003e There might be an additional folder named `local` if you operate your virtual environment with Python 2.7.\n\nAs final step, activate the environment now:\n```\n~/theonionbox $ source bin/activate\n(theonionbox) ~/theonionbox $ \n```\n\u003e On a Windows system, use `Scripts\\activate` to activate the virtual environment. You may as well refer to the [documentation of _virtualenv_](https://virtualenv.pypa.io/en/stable/userguide/) if you encounter any issues, e.g. if using _Powershell_.\n\n\u003e The fact that the virtual environment is activated is indicated by the name of the virtualenv in parentheses preceding the path info, e.g. here via `(theonionbox)`.\n\n\u003e If you're working with the `csh` or `fish` shell, you have to use a dedicated file / command to activate the virtual environment:  \nFor `csh`, use `source bin/activate.csh`  \nFor `fish`, use `source bin/activate.fish`\n\nTo **later** close the Virtual Environment, issue a `deactivate` command:\n```\n(theonionbox) ~/theonionbox $ deactivate\n~/theonionbox $ \n```\n\n### Installation\nThe latest release package of [_The Onion Box_](https://testpypi.python.org/pypi/theonionbox/) is always available in [PyPi](https://testpypi.python.org), the Python Package Index. You can download and install it with `pip install theonionbox`. Please ensure, that you're doing this within the virtual environment created for your box; (re-)activate it if necessary with:\n```\n~/theonionbox $ source bin/activate\n(theonionbox) ~/theonionbox $ pip install theonionbox\n```\nAlong with the files for _The Onion Box_, all additional [dependencies](#dependencies) will be installed into the virtual environment you created. No changes will be made to _The World Outside_ and there is no need to operate this `pip` command as `root`.\n\u003e Be aware that it might need some minutes to download and compile the requested packages and all their dependencies.\n\nPlease ensure that the installation process is performed without any error. You should read a line like\n```\n[...]\nSuccessfully installed PySocks-1.6.8 apscheduler-2.1.2 bottle-0.12.13 certifi-2017.11.5 [...]\n(theonionbox) ~/theonionbox $\n```\nas the final message.\n\n### Verification of the installation\nTo verify this `pip`ed installation, list (`ls -l`) the files in the directory of your virtual environment again, now:\n```\n(theonionbox) ~/theonionbox $ ls -l\ntotal 668\ndrwxr-xr-x 2 pi pi   4096 Jan 18 19:37 bin\ndrwxr-xr-x 2 pi pi   4096 Jan 18 19:37 config\ndrwxr-xr-x 3 pi pi   4096 Jan 18 19:37 docs\ndrwxr-xr-x 2 pi pi   4096 Jan 18 19:21 include\ndrwxr-xr-x 3 pi pi   4096 Jan 18 19:21 lib\n-rw-r--r-- 1 pi pi     60 Jan 18 19:21 pip-selfcheck.json\n-rw-r--r-- 1 pi pi 650924 Jan 18 19:37 README.html\ndrwxr-xr-x 5 pi pi   4096 Jan 18 19:37 service\n(theonionbox) ~/theonionbox $ \n```\n\u003e As already mentioned, there might be an additional folder named `local` if you operate your virtual environment with Python 2.7.\n\nFirst finding: This file, `README.html`, was placed into the root of your virtual environment - to always be at your hand if necessary.\n\nSecond finding! There were three additional subdirectories created:\n* `config`, where to place a [configuration file](#configuration-by-file) - if you need one. You'll find there as well an example for such a configuration file.\n* `docs`, that holds the images used in this document.\n* `service`, to provide the launchers if you intend to run your box as a [system service / daemon](#the-onion-box-as-system-service-aka-daemon) and the files to support the [Docker](#the-onion-box-docker-support) image setup.\n\nThe Python packages - for the box and all it's dependencies - are located in `lib/python2.7/site-packages/`. Be aware, that the `python` path segment might be different (e.g. `lib/python3.6/site-packages/`) if your virtual environment operates with another version of Python!\n_The Box Launcher_ (named as well `theonionbox`) is located in `bin/`, next to the executables of the Python version used in your virtual environment.\n\nIf the structure of your installation looks equivalent, your box is now cleared for takeoff!\n\n### First Flight\nType `theonionbox` to launch your box for the first time:\n```\n(theonionbox) ~/theonionbox $ theonionbox\n```\nYour box will perform some steps to initialize and then wait for connections at `http://127.0.0.1:8080`. A typical startup sequence of a fresh installation of _The Onion Box_ looks like this:\n\n```\n16:09:07.688 The Onion Box: WebInterface to monitor Tor node operations.\n16:09:07.692 Version v4.x (stamp 2018....|15....)\n16:09:07.693 Running on a Linux host.\n16:09:07.695 Running with permissions of user 'pi'.\n16:09:07.696 Python version is 2.7.13 (/home/pi/theonionbox/bin/python).\n16:09:07.697 This seems to be a Python VirtualEnv.\n16:09:07.728 No (valid) configuration file found; operating with default settings.\n16:09:11.471 Temperature sensor information located in file system. Expect to get a chart!\n16:09:11.473 Uptime information located. Expect to get a readout!\n16:09:12.077 Ready to listen on http://127.0.0.1:8080/\n16:09:12.153 Press Ctrl-C to quit!\n```\n\nAt that stage, open a webbrowser from the PIXEL desktop and connect to your box at the given address (here: `http://127.0.0.1:8080`).  \n\nIt is yet very likely, that you'll receive an error message like this one:\n\u003cp  align=\"center\"\u003e\u003cimg src='docs/images/connectionerror.png' width='80%'\u003e\u003c/p\u003e\n\nDon't be disappointed! As your box explained during it's launch procedure, it is\n```\n16:09:07.695 Running with permissions of user 'pi'.\n```\nVery likely your Tor node yet was (e.g. by default) configured to guard the access to it's `ControlPort` by `CookieAuthentication`. As user `pi` (in common scenarios) has no permission to read this cookie, your box fails to authenticate against your Tor node - and has to issue a Connection Error.\nTo compensate for that error and to comply with the Tor configuration setting, just launch your box with the same user that owns \u0026 controls your Tor node - which on Debian like systems usually is `debian-tor`:\n\n\u003e Remember: To stop the operation of your box, press `Ctrl-C`!\n```\n(theonionbox) ~/theonionbox $ sudo -u debian-tor ./bin/theonionbox\n```\n\u003e Please note that you now have to state the full path - either relative or absolute - to [_The Box Launcher_](#verification-of-the-installation) script (`theonionbox`) to run the box! For our scenario, I've chosen to use the relative path of `./bin/theonionbox`!\n\n```\n[...]\n16:33:16.543 Running on a Linux host.\n16:33:16.544 Running with permissions of user 'debian-tor'.\n16:33:16.544 Python version is 2.7.13 (/home/pi/theonionbox/bin/python).\n16:33:16.566 No (valid) configuration file found; operating with default settings.\n16:33:20.314 Temperature sensor information located in file system. Expect to get a chart!\n16:33:20.315 Uptime information located. Expect to get a readout!\n[...]\n```\n\u003e You might notice as well, that _The Onion Box_ is now unable to detect that it's running inside a virtual environment! This is technically correct, as issueing the `sudo -u` command breaks those boundaries. Be assured, that this is ok!\n\nAs before, browse now to `http://127.0.0.1:8080` ... and enjoy monitoring your Tor node!\n\n### If it doesn't fly...\nThere have been issues reported that the box is unable to connect to the [ControlPort](#controlport) of your Tor node even when started using the `sudo -u` command. The reasons for this might be obscure - the solution is straight forward: Add the user you're operating with to the same group that owns the Tor node process.\n\nStart this procedure by querying for the Tor node process with `ps -aux | grep tor`:\n```\n~ $ ps -aux | grep tor\nroot       112  0.0  0.0      0     0 ?        S    Jan28   0:38 [usb-storage]\ndebian-+   692 21.7 18.0 216520 171668 ?       Ssl  Jan28 1240:02 /usr/bin/tor --defaults-torrc /usr/share/tor/tor-service-defaults-torrc -f /etc/tor/torrc --RunAsDaemon 0\npi         697  0.0  1.1  74696 10684 ?        Ssl  Jan28   0:00 /usr/lib/gvfs/gvfs-udisks2-volume-monitor\n[...]\n~ $\n```\nThe line\n```\ndebian-+   692 21.7 18.0 216520 171668 ?       Ssl  Jan28 1240:02 /usr/bin/tor --defaults-torrc /usr/share/tor/tor-service-defaults-torrc -f /etc/tor/torrc --RunAsDaemon 0\n```\ntells you that the process ID (PID) of the Tor node (`/usr/bin/tor`) is _692_ and that the user owning it starts with `debian-` - yet, as the `+` indicates, the name is truncated.\n\nIf necessary - to get the full name - issue then a `ps -o user= -p \u003cPIDHERE\u003e`:\n```\n~ $ ps -o user= -p 692\ndebian-tor\n~ $\n```\nNext - check which group this user belongs to:\n```\n~ $ groups debian-tor\ndebian-tor : debian-tor\n~ $\n```\nAs a final step, add now your current user (which is `pi` in our scenario) to that group (indicated as `debian-tor`):\n```\n~ $ sudo usermod -a -G debian-tor pi\n~ $\n```\nVerification:\n```\n~ $ groups pi\npi : pi [...] debian-tor\n~ $\n```\nThat achieved, you should be able to smoothly [run your box](#first-flight) now - and get no Connection Error.\n\n## Dependencies\n_The Onion Box_ depends on some libraries developed and provided by third parties. If you follow the [installation procedure](#installation) , `pip` will care to install all necessary packages for you.  \nIf you perform a non-`pip` (manual) installation (e.g. directly from the GitHub repository), you have to ensure that those dependencies are installed accordingly:\n\n* [psutil](https://pypi.python.org/pypi/psutil)\n* [stem](https://pypi.python.org/pypi/stem)\n* [bottle](https://pypi.python.org/pypi/bottle)\n* [APScheduler](https://pypi.python.org/pypi/apscheduler)\n* [PySocks](https://pypi.python.org/pypi/PySocks)\n* [tzlocal](https://pypi.python.org/pypi/tzlocal)\n\nTo operate a box in an Python 2.7 environment, you need as well the [futures](https://pypi.python.org/pypi/futures/) module.\n\nIf you intend to use the advanced GeoIP2 functionality, you have to install as well the module [geoip2](https://pypi.python.org/pypi/geoip2).\n\nIf you intend to operate _The Onion Box_ in SSL mode, you have to install as well the module [ssl](https://pypi.python.org/pypi/ssl).\n\n\nThese modules are usually installed using `pip`, e.g.: `pip install psutil`\n\nPlease use always the ~~latest~~ version ~~available~~ demanded for your Python release. Remember that you (usually) need to have root privileges to operate `pip`, e.g. `sudo -u pip install psutil`.  \nMy advice is yet to always operate within a [Python Virtual Environment](#system-preparation) - which eliminates the demand to run `pip` with root privileges.\n\n\u003e Check this [Q\u0026A](#i-receive-a-not-supported-proxy-scheme-socks5h-warning-what-shall-i-do) if your `pip` installation is broken or if you receive a `socks5h proxy not supported` warning.\n\n## Configuration by file\n\nBy design, _The Onion Box_ is able to detect a typical local Tor node installation and will connect without further preparation.\n\nTherefore no configuration be necessary - if you are operating your node at `ControlPort 9051` (which is the default for a relay) or `ControlPort 9151` (the default for TorBrowser).\n\nFor all other situations, you may configure the way of operation of your box via a configuration file.\n\n### Location\nIf you do not provide a dedicated `--config=\u003cpath\u003e` to define the path to a configuration file via the [command line](#command-line-parameters), _The Onion Box_ checks for availability of a file named `theonionbox.cfg` at one of the following locations (in the given order):\n* if launched from a Python Virtual Environment, in a directory named `config` below the root directory of the virtual environment: `$VIRTUAL_ENV/config/theonionbox.cfg`\n* in the same directory as `theonionbox.py`: `./theonionbox.cfg`\n* in a directory named `config` below the directory of `theonionbox.py`: `./config/theonionbox.cfg`\n\nIf you've saved your configuration file at one of those locations, yet your box still states `No (valid) configuration file found.`, you might use the [-d command line parameter](#command-line-parameters) to enable the _Debug_ mode. This will trigger _The Onion Box_ to emit the absolute search paths it's checking for the configuration files:\n\n```\n(theonionbox) ~/theonionbox $ theonionbox -d\n        17:57:10.551 The Onion Box: WebInterface to monitor Tor node operations.\n[...]\n[DEBUG] 17:57:10.590 theonionbox.py[391]: No configuration file found at '/home/pi/theonionbox/config/theonionbox.cfg'\n[DEBUG] 17:57:10.594 theonionbox.py[391]: No configuration file found at '/home/pi/theonionbox/lib/python2.7/site-packages/theonionbox/theonionbox.cfg'\n[DEBUG] 17:57:10.596 theonionbox.py[391]: No configuration file found at '/home/pi/theonionbox/lib/python2.7/site-packages/theonionbox/config/theonionbox.cfg'\n```\n\n### Structure\nThe configuration file of _The Onion Box_ is a simple text file \"ini-style\". A template of that file is available as [`./config/theonionbox.example`](./theonionbox/config/theonionbox.example) in the directory of `theonionbox.py`.\n\n#### Section `[config]`\n```\n[config]\n## v4.0 will only support version = 2\nprotocol = 2\n```\n_The Onion Box_ as of version 4 only supports configuration file protocol `2`.\n\n#### Section `[TheOnionBox]`\n```\n[TheOnionBox]\n## Address of your Onion Box:\n## This defaults to 127.0.0.1 to listen *only* on the local loopback interface.\n# host = 127.0.0.1\n## If 'localhost', connections are limited to the local system.\n# host = localhost\n## Of course you may define a dedicated IP4 address as well.\n# host = your.IP.4.address\n\n## Port for the Web Server\n## Defaults to 8080, which should be fine in most cases!\n# port = 8080\n\n## To define the lower threshold for the notification system:\n## Messages (of the Box) with at least this level will be forwarded to the attached clients.\n## Possible setting are DEBUG, INFO, NOTICE, WARNING, ERROR\n## Defaults to NOTICE, case insensitive\n## To 'DEBUG' or 'TRACE' the box you have to set the respective commandline parameters!\n# message_level = NOTICE\n\n## Per default, the Box operates at the root level of a domain e.g. http://localhost:8080/.\n## If you intend to operate it (behind a proxy!) at a deeper level (e.g. @ http://my.server.com/theonionbox/)\n## you have to define that base path here. You are not limited to a single path element.\n## Please assure that this is an absolute filepath yet without the domain:port, beginning with a leading slash,\n## no trailing slash, no quotation marks:\n# base_path = /theonionbox\n\n## The acceptable duration in seconds between two communication events of a client to the Box.\n## If this duration is exceeded, the Box will expire the session. Default is 300 (seconds).\n# session_ttl = 300\n## Note: This is applicable for login procedures as well as monitoring activities.\n## Note: The minimum duration accepted == 30, max == 3600. Values will be forced into that range.\n\n## Shall we operate with SSL?\n## Note: To actually make this running, you have to create a valid ssl certificate first:\n## So run e.g.\n## openssl req -new -x509 -keyout server.pem -out server.pem -days 365 -nodes\n##\n## DON'T distribute this combined private/public key to clients!\n## (see http://www.piware.de/2011/01/creating-an-https-server-in-python/#comment-11380)\n##\n## ssl = yes    # deprecated 20170218\n## Just set ssl_certificate \u0026 ssl_key to enable ssl mode!\n## The file that holds the Certificate!\n# ssl_certificate = server.pem\n## The file that holds the Key!\n# ssl_key = private_key.pem\n\n## When a NTP server is provided\n## we use it's time signal to compensate for the server's clock deviations\n# ntp_server = pool.ntp.org\n# ntp_server = fritz.box\n\n## Path to store the database file for persistance of e.g. bandwidth data.\n## Defaults to a system defined temporary directory.\n# persistance_dir = /home/pi/theonionbox\n## Be aware, that you have to assure write privileges to this directory for the user running your box.\n\n## Tor ships with the GeoIPLight2 Country DB\n## If you're interested in a more precise indication, you should install the GeoIP City DB\n## e.g. from http://dev.maxmind.com/geoip/geoip2/geolite2/ and define here the path to the db file.\n## Both flavours (Full or Light) are supported.\n# geoip2_city = path/to/geoip2/city/db.mmdb\n## Be aware that you need to install python module 'geoip2' as well to access those information.\n```\n\n#### Section `[Tor]`\nThese are the parameters to connect and authenticate to your \"primary\" (or first or main) Tor node to be monitored.\n```\n[Tor]\n## How shall we establish the connection to your primary (controlled) Tor node?\n## =\u003e via a ControlSocket (define additionally 'socket' parameter):\n# control = socket\n## =\u003e via a ControlPort (define additionally 'host' \u0026 'port' parameter):\n# control = port\n## =\u003e via a Proxy (define a proxy via the [Proxy] section and set 'host' to an address reachable through this proxy):\n# control = proxy\n## Note: This defaults to control = port if not defined!\n\n## Address of this Tor instance\n## Do NOT use 'localhost' but 127.0.0.1 to connect locally\n## Defaults to 127.0.0.1\n# host = 127.0.0.1\n\n## ControlPort of this Tor instance\n## Default for a Relay (or Bridge)\n# port = 9051\n## Default for a TorBrowser\n# port = 9151\n## You may use 'default' (port = default) to test for 9051 (relay default) and 9151 (browser default)\n# port = default\n## Note: This defaults to port = default if not defined!\n\n## ControlSocket of this Tor instance\n# socket = /var/run/tor/control\n\n## Timeout when connecting to Tor.\n## Usually the connection should be established very quick;\n## you may increase this if connecting to very remote systems.\n# timeout = 5\n\n## The Number of Seconds we keep the connection to\n## Tor open after the last user disconnected.\n## Hint: The minimum reasonable TTL is \u003e 30(s)\n## Defaults to 30 (seconds)\n## eg. 1 day\n# ttl = 86400\n## eg. 1 hour\n# ttl = 3600\n## eg. forever\n# ttl = -1\n\n## Switches to preserve the messages of the Relay\n## Up to 400 messages (total) will be preserved\n## The severity of these messages can be defined here\n## There's one switch for ERR, WARN \u0026 NOTICE\n## The default setting is 'on' for all of these\n## There's NO switch for INFO \u0026 DEBUG (as this would flood the memory without true value)\n## Live - transmission of messages can be switched on/off in the client\n# tor_preserve_ERR = no\n# tor_preserve_WARN = no\n# tor_preserve_NOTICE = no\n```\n\n#### Section `[TorProxy]`\n```\n[TorProxy]\n## Note: Operation via a proxy given by a unix domain socket is (as of 04/2017) not supported!\n\n## If you establish connection cookies for hosts to be controlled via the control center, there is the need\n## to verify that those cookies are defined. To perform the verification, we need valid control port\n## settings of the node acting as proxy:\n## How shall we establish the connection to the node?\n## =\u003e via a ControlSocket (define additionally 'socket' parameter):\n# control = socket\n## =\u003e via a ControlPort (define additionally 'port' parameter):\n# control = port\n## You may use control = default to operate with [Tor]control\n## Note: This defaults to control = default if not defined!\n\n## Address of the proxy to use\n## Do NOT use 'localhost' but 127.0.0.1 to connect locally\n## You may use 'default' (host = default) to use [Tor]host\n# host = default\n# host = 127.0.0.1\n## Note: This defaults to host = default if not defined!\n\n## Port for the proxy\n## Default for a Relay (or Bridge)\n# proxy = 9050\n## Default for a Tor Browser\n# proxy = 9150\n## You may use 'default' (proxy = default) to test for 9050 (relay default) and 9150 (browser default)\n# proxy = default\n## Note: This defaults to proxy = default if not defined!\n\n## ControlPort of the proxy Tor node\n## Default for a Relay (or Bridge)\n# port = 9051\n## Default for a Tor Browser\n# port = 9151\n## You may use 'default' (port = default) to test for 9050 (relay default) and 9150 (browser default)\n# port = default\n## Note: This defaults to port = default if not defined!\n\n## ControlSocket of the proxy Tor node\n# socket = /var/run/tor/control\n## You may use 'default' (socket = default) to use [Tor]socket\n# socket = default\n## Note: This defaults to socket = default if not defined!\n```\n\n#### One dedicated section for each additional _Controlled Host_\nFor each Tor node you intend to monitor - **but not** for the  \"primary\" node configured already in section `[Tor]` - you have to add a dedicated section proving the access data for its `ControlPort`.\n\n\u003e You must not name any of the following sections 'config', 'TheOnionBox', 'Tor' or 'TorProxy'.\n\n```\n#####\n## Those are the Tor nodes to be controlled with the control center\n## Note: You must not name any of the following sections 'config', 'TheOnionBox', 'Tor' or 'TorProxy'.\n\n\n## Define one section per node:\n# [myControlledNode]\n\n## Alternatively: Beginning the section identifier with '#' indicates a nickname;\n## if you later omit the 'nick' parameter, the nickname will be derived from the section identifier.\n# [#myControlledNode]\n## If you intend to define several ways to connect to this node,\n## add whatever you like after a ':' to distinguish the sections:\n# [#myControlledNode:2]\n\n## Alternatively: You can use the fingerprint (with preceding '$') as section identifier.\n## Ensure a length of 41 characters: '$' + fingerprint[40];\n## if you later omit the 'fp' parameter, the fingerprint will be derived from the section identifier.\n# [$5COOL5C30AXX4B3DE460815323967087ZZ53D947]\n## If you intend to define several ways to connect to this node,\n## add whatever you like after a ':' to distinguish the sections:\n# [$5COOL5C30AXX4B3DE460815323967087ZZ53D947:2]\n\n\n## How shall we establish the connection to this node?\n## =\u003e via a ControlSocket (define additionally 'socket' parameter):\n# control = socket\n## =\u003e via a ControlPort (define additionally 'host' \u0026 'port' parameter):\n# control = port\n## =\u003e via a Proxy (define a proxy via the [Proxy] section and set 'host' to an address reachable through this proxy):\n# control = proxy\n## Note: There is no default setting. If not defined, this section (and thus the node) will be ignored.\n\n## IP Address of this Tor node\n# host = 127.0.0.1\n## You may as well define an onion or http address\n# host = takeonionaddress.onion\n## Note: There is no default setting.\n\n## ControlPort of this Tor node\n## Default for a Relay (or Bridge)\n# port = 9051\n## Note: There is no default setting.\n\n## This is only relevant for very rare setups - yet if you like, you may use it!\n## ControlSocket of this Tor node\n# socket = /var/run/tor/control\n## Note: There is no default setting.\n\n## Hidden Service connections my be secured by definition of a authorization cookie.\n## To operate via those connections, you may define this cookie here.\n## For further details refer to 'HiddenServiceAuthorizeClient' on https://www.torproject.org/docs/tor-manual.html\n# cookie = xuseyourcookieherexTOB\n## The Box will ensure that the cookie is registered before establishing the connection.\n## Note: There is no default setting.\n\n## The nickname of this node\n# nick = myControlledNode\n## Defining a nickname here overrides a nickname defined as the name of the section.\n## Note: The Box is able to retrieve the nickname itself,\n##       yet defining nickname (and fingerprint) parameters saves onionoo queries.\n## Note: There is no default setting.\n\n## The fingerprint of this node\n# fp = $5COOL5C30AXX4B3DE460815323967087ZZ53D947\n## Defining a fingerprint here overrides a fingerprint defined as the name of the section.\n## Note: The Box is able to retrieve the fingerprint itself,\n##       yet defining fingerprint (and nickname) parameters saves onionoo queries.\n## Note: There is no default setting.\n```\n\n## Command line parameters\n_The Onion Box_ may be configured by a small number of commandline parameters:\n\n```\n-c \u003cpath\u003e | --config=\u003cpath\u003e: Provide path \u0026 name of configuration file.\n                             Note: This is only necessary when NOT using\n                             './theonionbox.cfg' or './config/theonionbox.cfg'.\n-d | --debug: Switch on DEBUG mode.\n-t | --trace: Switch on TRACE mode (which is more verbose than DEBUG mode).\n-h | --help: Prints this information.\n-l \u003cdirectory\u003e | --log=\u003cdirectory\u003e: Define directory to additionally\n                                    emit log messages to. Please assure\n                                    correct access privileges!\n\n```\n\n`DEBUG` mode only affects the _Box_' core code. It forwards the debug messages of _The Onion Box_ to the console or the log file. If you encounter any problems, you may enable `DEBUG` mode to check what's happing.\n\n`TRACE` additionally forwards debug level messages of `bottle` (the WSGI micro web-framework used by the _Box_) and trace level messages of `stem` (the Tor controller library). This mode is really noisy ... and the ultimate lever to follow the operation of _The Onion Box_ in case of problems.\n\n### Deprecated parameters\nPrior to version 4.1.3 you had to define the command line parameter\n```\n-m \u003cmode\u003e | --mode=\u003cmode\u003e\n```\nto `Configure The Box to run as 'service'`. This parameter meanwhile is obsolete. Using `-m` or `--mode` will trigger a `DeprecationWarning`.\n\n\n## Advanced Operations: Authentication\nMonitoring a Tor node in the end just demands two prerequisites: Access to an interface to control the node and a way to authenticate against the node. Therefore _Advanced Operations_ is all about the different ways to provide a [control interface](#advanced-operations-control-interface) and the different ways of **authentication**.\n\nTo clarify one topic upfront: You don't need to tell your box the way of authentication it shall use. This topic will transparently be negotiated between the Tor node and the _Box_.\n\n### Cookie Authentication\nBy default (defined in the configuration file [`torrc.default`](#configuration)) a Tor node offers _Cookie Authentication_ as standard authentication method.  \n\nAccording to the Tor manual, when using _Cookie Authentication_, the Tor node allows \"connections on the control port when the connecting process knows the contents of a file named `control_auth_cookie`, which Tor will create in its data directory\".  \nThis implies that _Cookie Authentication_ can only be used locally - which means that this authentication method is only suitable if you have installed _The Onion Box_ on the same system that hosts the Tor node you intend to monitor.  \nTo access `control_auth_cookie`, your box needs to have the correct privileges. This can be achieved most easily by running it as the same user as the Tor node (which e.g. is _debian-tor_ on Debian systems):\n```\nsudo -u debian-tor python theonionbox.py\n```\n\n### Password Authentication\nBy definition of the `HashedControlPassword` parameter in the `torrc` configuration file of your Tor node, you can advise Tor to operate with _Password Authentication_.\n\n\u003e To create a password hash of _mypassword_ issue a `sudo tor --hash-password mypassword`.\n\n_Password Authentication_ provides a way of access control to your Tor node even if you monitor a remote node.\n\nIf your box discovers that _Password Authentication_ is required, it will ask for that password providing a Login Screen:\n\n![Login Screen](docs/images/login.png)\n\n\n### No Authentication\nThere might be situations, where access control to the ControlPort is not demanded or even obstructive.\nIn that case it may be necessary to explicitely turn off _Cookie Authentication_ in your `torrc` - as it might be enabled by default:\n```\nCookieAuthentication 0\n```\n\n## Advanced Operations: Control Interface\nMonitoring a Tor node in the end just demands two prerequisites: Access to an interface to control the node and a way to authenticate against the node. Therefore _Advanced Operations_ is all about the different ways to provide a **control interface** and the different ways of [authentication](#advanced-operations-authentication) .\n\n### Caution\nOn Unix or Unix-like systems it is preferred to use a `ControlSocket` rather than a `ControlPort` as interface to the control port of a local Tor node.\n\nProviding a socket ensures that only a process local to the system is able to connect.\n\nIf you mis-configure a `ControlPort`, you might endanger the security of your system; if you mis-configure a `ControlSocket`, you just cannot connect.\n\n### ControlSocket\nBy default (defined in the configuration file [`torrc.default`](#configuration)) a Tor node offers a `ControlSocket` as standard controlling interface (at least on Unix and Unix-like systems). This default socket is e.g. defined as `/var/run/tor/control`.\n\nA `ControlSocket` can only been accessed locally; therefore you need to install _The Onion Box_ on the same system that hosts the Tor node you intend to monitor.\nTo access a `ControlSocket` the process trying to connect needs to have the correct privileges. This can be achieved most easily by running your box as the same user as the Tor node (which e.g. is _debian-tor_ on Debian systems): `sudo -u debian-tor python theonionbox.py`\n\nTo instruct your box to connect to a local ControlSocket define the following parameters:\n```\n[Tor]\ncontrol = socket\nsocket = /var/run/tor/control\n```\n\nYou can use the same parameter language - if applicable - in `[TorProxy]` or when defining the connection settings of a _Controlled Host_.\n\n### ControlPort\nConfiguring a `ControlPort` as controlling interface for a Tor node is as simple as defining\n```\nControlPort 9051\n```\ninto the node's `torrc` file - and restarting Tor. Almost every _Beginner's guide to setup a Tor relay_ explains how to achieve this.\n\nTo instruct _The Onion Box_ to connect to a `ControlPort` interface, you have to define two parameters, the `host` and the `port`.\n\n\u003e A `ControlPort` - in the sense of this documentation - is **not** a `unix://path` unix domain socket definition yet only a port number according to internet protocol specification. If you intend to operate with an unix domain socket interface, follow the instructions in the chapter [ControlSocket](#controlsocket) - even if you've defined that socket in `torrc` with parameter `ControlPort`.\n\n`host` can be either an IP4-address or a hostname.\n\u003e `host` definition via IP6 address currently is not supported.\n\n`port` has to be a number in the standard range of port numbers between 0 and 65535.\n\nThus use the following language in your box' configuration file to instruct it to connect to a ControlPort:\n```\n[Tor]\ncontrol = port\nhost = 127.0.0.1\nport = 9051\n```\n\nYou may use `control=port` to connect to local (`host=127.0.0.1`) or remote (`host=www.my.torserver.com`) Tor nodes.\n\nYou can use the same parameter language - if applicable - in `[TheOnionBox]`, `[TorProxy]` or when defining the connection settings of a _Controlled Host_.\n\n### ControlPort via Proxy\nYou can instruct your box to connect to a remote host via the Tor network. Prerequisite for such an operation is the definition and availability of a Tor node as proxy server:\n\n\u003e You can enable a Tor node's `socks` proxy capabilities by defining a `SocksPort` in `torrc` - and restarting Tor.\n\nUse the following language in your box' configuration file to instruct it to connect to the ControlPort of a Tor node via the Tor network:\n```\n[Tor]\ncontrol = proxy\nhost = www.my.torserver.com\nport = 9051\n```\n\nBe aware that this kind of setup is only limited useful, as the monitoring traffic exits the Tor network at an exit node and circulates into the open internet until it reaches the Tor node to be monitored.\n\nYou yet can unfold the full potential of this feature if you use it with a Tor node providing access to it's controlling interface by a [hidden service](#hidden-service-operations).\n\n\n## Hidden Service Operations\n_The Onion Box_ supports remote monitoring of a Tor node via the Tor notwork services. While it might be a bit more effort to set up such a connection, it provides the advantage that the whole traffic circulates only within the Tor eco system; there is no footprint of the monitoring activity in the open internet, adding a further layer of security to your operations.\n\n### Basic configuration\nTo create that kind of connection, you have to prepare a hidden service that allows connection to the ControlPort of the Tor node to be monitored - by adding\n```\nHiddenServiceDir /var/lib/tor/theonionbox/\nHiddenServicePort 9876 /var/run/tor/control\n```\nto this node's `torrc`.  \nThe first parameter of `HiddenServicePort` is the virtual ControlPort we'll connect to later.  \nThe second parameter of `HiddenServicePort` is the local controlling interface of the node - which might be a `ControlSocket` (as in the example shown) or a `ControlPort` (like `127.0.0.1:9051`).\n\nAfter a restart of the Tor node by `sudo service tor restart`, you will find the onion address of your Hidden Service in `\u003cHiddenServiceDir\u003e/hostname`. The address usually is a 16 character string followed by `.onion`, e.g. _7an5onionad2res2.onion_.\n\nTo monitor this Tor node, add a dedicated section to the configuration file of your box.\n```\n[MyProxyNode]\ncontrol=proxy\nhost=7an5onionad2res2.onion\nport=9876\n```\nProvide as `host` parameter the onion address of your hidden service, as `port` the virtual ControlPort number you defined in the node's `torrc`.\n\nThis node will then be listed as a _Controlled Host_ in the [Control Center](#control-center) section of the web interface.\n\n### Access control\n\nAs this Hidden Service configuration exposes the ControlPort of your Tor node to everyone who is able to connect to a Hidden Service, you have to consider a way to control the access to prevent misuse.\n\nThe first option is to enable [_Password Authentication_](#password-authentication) on the Tor node monitored.\n\nAlternatively you could take advantage of Tor's _Hidden Service Client Authorization_ feature. In short, it restricts access to the Hidden Service to those clients that are able to provide the correct _Authorization Cookie_.\n\nTo enable this feature, edit again your Tor node's `torrc`. Alter the Hidden Service section to\n```\nHiddenServiceDir /var/lib/tor/theonionbox/\nHiddenServicePort 9876 /var/run/tor/control\nHiddenServiceAuthorizeClient stealth myBoxConnector\n```\nThe second parameter of `HiddenServiceAuthorizeClient` is the **unique** username you intend to use to operate this connection.\n\u003e Please do **not** use _myBoxConnector_ as in the example above; this term definitely is no more _unique_ and therefore quite unsuitable to secure your connection!\n\nAfter another restart of Tor via `sudo service tor restart`, you will find the authorization cookie for the given username in `\u003cHiddenServiceDir\u003e/hostname`.  \nTake this cookie - a 22 character string, e.g. _xa3NyourCookY6herexTOB_ - and add it to the settings you defined for this connection in the configuration file of your box:\n```\n[MyProxyNode]\ncontrol=proxy\nhost=7an5onionad2res2.onion\nport=9876\ncookie=xa3NyourCookY6herexTOB\n```\nYour box will ensure that the configuration cookie will be registered prior to a connection attempt.\n\nAs this procedure limits the use of the Hidden Service - and thus the access to the control port of the node - to only those (trusted) users that are able to provide the right authorization cookie, you might consider switching off the standard authentication functionality of the node's control port via it's `torrc`:\n```\nCoookieAuthentication 0\n# HashedControlPassword\n```\n\n## _The Onion Box_ as system service (aka daemon)\nAfter you've ensured that your box operates without issues, you can set it up to operate as a background application, which is the same as a system service or daemon. The steps to perform this differ depending on the technology used by your operating system derivate.\n\n### Logging to syslog\nWhen operating as a service, The Onion Box emits messages per default to [syslog](https://en.wikipedia.org/wiki/Syslog). To read those messages, which are usually saved to `/var/log/syslog`, use e.g. `tail`:\n```\n~ $ tail -n 100 /var/log/syslog | grep theonionbox\nFeb 12 17:54:49 raspberrypi theonionbox[15716]: The Onion Box: WebInterface to monitor Tor node operations.\nFeb 12 17:54:49 raspberrypi theonionbox[15716]: Version v4.2.xx (stamp 201802dd|hhmmss)\nFeb 12 17:54:49 raspberrypi theonionbox[15716]: Running on a Linux host.\nFeb 12 17:54:49 raspberrypi theonionbox[15716]: Running with permissions of user 'debian-tor'.\nFeb 12 17:54:49 raspberrypi theonionbox[15716]: Python version is 2.7.13 (/home/pi/theonionbox/bin/python).\nFeb 12 17:54:49 raspberrypi theonionbox[15716]: No (valid) configuration file found; operating with default settings.\nFeb 12 17:54:53 raspberrypi theonionbox[15716]: Temperature sensor information located in file system. Expect to get a chart!\nFeb 12 17:54:53 raspberrypi theonionbox[15716]: Uptime information located. Expect to get a readout!\nFeb 12 17:54:58 raspberrypi theonionbox[15716]: Ready to listen on http://127.0.0.1:8080/\n~ $\n```\n\u003e Piping the `tail` output to `grep` allows you to get just the lines you're interested in, in our scenario those mentioning `theonionbox`.\n\u003e The `-n` command line parameter of `tail` limits the output to the number of lines defined.\n\nIf you are interested in your box sending the same messages additionally to a dedicated log file, you may enable this feature via a [command line parameter](#command-line-parameters).\n\n### Optional syslog configuration\nAs stated above, the messages your box emits are (always) saved to `/var/log/syslog` - and mingled there with a multitude of messages from other programs running. You yet can easily configure syslog to put them as well in a seperate file (e.g. `/var/log/theonionbox.log`) and advise to rotate this file continously (which allows you e.g. to keep the size of the file(s) under control):\n\nAppend the following line at the end of the syslog configuration file `/etc/rsyslog.conf`:\n```\n:programname,isequal,\"theonionbox\"         /var/log/theonionbox.log\n```\nand restart the syslog daemon:\n```\n(theonionbox) ~/theonionbox $ sudo systemctl restart rsyslog\n(theonionbox) ~/theonionbox $\n```\nTo establish the rotation of `/var/log/theonionbox.log`, create a configuration file with the following content as `/etc/logrotate.d/theonionbox`:\n\n```\n/var/log/theonionbox.log { \n    daily\n    rotate 5\n    compress\n    delaycompress\n    missingok\n    postrotate\n        systemctl restart rsyslog \u003e /dev/null\n        # invoke-rc.d rsyslog reload \u003e /dev/null  \n    endscript    \n}\n```\nThis will rotate the files daily (at midnight), keep five (5) files and compress them as necessary.\n\n\u003e The `postrotate` command has to be adapted to the way your operating system uses to restart a background process (aka daemon). `systemctl ...` is for _systemd_ operations, `invoke-rc.d` to be used with _init.d_ / _SysVInit_ systems. Check [this site](https://unix.stackexchange.com/questions/18209/detect-init-system-using-the-shell) if unsure...\n\nIf a quick test of your setup ...\n```\n(theonionbox) ~/theonionbox $ logrotate -d /etc/logrotate.d/theonionbox\nreading config file /etc/logrotate.d/theonionbox\nReading state from file: /var/lib/logrotate/status\nAllocating hash table for state file, size 64 entries\nCreating new state\n[...]\n\nHandling 1 logs\n\nrotating pattern: /var/log/theonionbox.log  after 1 days (5 rotations)\nempty log files are rotated, old logs are removed\nconsidering log /var/log/theonionbox.log\nCreating new state\n  Now: 2018-02-14 09:30\n  Last rotated at 2018-02-14 09:00\n  log does not need rotating (log has been already rotated)\n(theonionbox) ~/theonionbox $\n```\n... shows no errors, you may force `logrotate` once to run the rotation...\n```\n(theonionbox) ~/theonionbox $ sudo logrotate --force /etc/logrotate.d/theonionbox\n(theonionbox) ~/theonionbox $\n```\n... to assure everything works as intended - and you're done.\n\n### Prepared launcher scripts\nIf you followed the [installation procedure](#installation), the following directory structure was created in your virtual environment:\n```\n(theonionbox) ~/theonionbox $ ls -l\ntotal 668\ndrwxr-xr-x 2 pi pi   4096 Jan 18 19:37 bin\ndrwxr-xr-x 2 pi pi   4096 Jan 18 19:37 config\ndrwxr-xr-x 3 pi pi   4096 Jan 18 19:37 docs\ndrwxr-xr-x 2 pi pi   4096 Jan 18 19:21 include\ndrwxr-xr-x 3 pi pi   4096 Jan 18 19:21 lib\n-rw-r--r-- 1 pi pi     60 Jan 18 19:21 pip-selfcheck.json\n-rw-r--r-- 1 pi pi 650924 Jan 18 19:37 README.html\ndrwxr-xr-x 5 pi pi   4096 Jan 18 19:37 service\n(theonionbox) ~/theonionbox $ \n```\nAs already mentioned, the scripts prepared to run a box as system service are provided in `service`:\n```\n(theonionbox) ~/theonionbox $ cd service/\n(theonionbox) ~/theonionbox/service $ ls -l\ninsgesamt 12\ndrwxr-xr-x 2 pi pi 4096 Feb 12 08:23 FreeBSD\ndrwxr-xr-x 2 pi pi 4096 Feb 12 08:23 init.d\ndrwxr-xr-x 2 pi pi 4096 Feb 12 08:23 systemd\n```\nThe next steps differ based on your operating system:\n* For FreeBSD, continue with the [next chapter](#-on-freebsd) .\n* For systems using _SystemV_, jump forward to the section detailing [init.d](#-using-initd).\n* For systems using _systemd_, go to the [systemd](#-using-systemd) section.\n* If you're using another operating system: There's currently _no support_ to run The Onion Box as a service. This yet _does not mean it's impossible_. If you managed to setup such a configuration, drop me a line to implement a procedure here!\n\n\u003e Some hints:  \n\u003e A) Your system is operating with _systemd_, if the directory `/run/systemd/system` exists.  \n\u003e B) If you're really unsure: [This site](https://unix.stackexchange.com/questions/18209/detect-init-system-using-the-shell) provides some means to detect (or identify) the initialisation method used by your system.\n\n\n### ... on FreeBSD\nLet's assume, you've created the virtual environment for your _Onion Box_ at `/usr/home/pi/theonionbox`.\n\n* Change to that directory: `cd /usr/home/pi/theonionbox`\n* Change to the `FreeBSD` directory within `service`: `cd service/FreeBSD`\n* Within this directory you'll find the script [`theonionbox.sh`](https://github.com/ralphwetzel/theonionbox/blob/master/FreeBSD/theonionbox.sh) prepared to launch your OnionBox as a background service.\n* Ensure that you set the path to the OnionBox files and the user to run the service as intended. Therefore open the file with an editor (here we use _nano_): `nano theonionbox.sh`\n* According to our assumptions above, set line 31 to `: ${theonionbox_dir=\"/usr/home/pi/theonionbox\"}`.\n* If necessary, you may define commandline arguments via `${theonionbox_start_args}` (as shown in the examples around line 35)\n* Close _nano_ and save the changes to `theonionbox.sh`. (Press _Strg+X_ then follow the instructions given!)\n* Copy the altered init script to `/usr/local/etc/rc.d`: `sudo cp ./theonionbox.sh /usr/local/etc/rc.d/theonionbox`\n* Change to `/usr/local/etc/rc.d`: `cd /usr/local/etc/rc.d`\n* Make sure the script you've copied before to `/usr/local/etc/rc.d` is executable: `sudo chmod 755 ./theonionbox`\n* Register this service to the system: `sudo echo 'theonionbox_enable=\"YES\"' \u003e\u003e/etc/rc.conf`\n* Alternatively - e.g. if the former command failed - you may alter `/etc/rc.conf` directly: `sudo nano /etc/rc.conf`, append `theonionbox_enable=\"YES\"` at the end of the file and save the changes: Press _Strg+X_ then follow the instructions given!\n* Check that everything works so far: Launch your Onion Box for the first time as a service `sudo service theonionbox start`. This should give you no error messages.\n* Check that your Onion Box is active: `sudo service theonionbox status` should tell you `theonionbox is running as pid xxx.`\n* That's it! Next time you reboot your system, your _Onion Box_ will be relaunched as well.\n\n**Troubleshooting**\n* Please ensure that `/usr/sbin/daemon` is a valid path. If not either edit `/usr/local/etc/rc.d/theonionbox` line 49 or create a symbolic link to your installation's path to `daemon` as `/usr/sbin/daemon`.\n* `command_interpreter` shall point to the python executable within your virtual environment.\n\n\n### ... using init.d\nChange to the `init.d` directory within `service`:\n```\n(theonionbox) ~/theonionbox/service $ cd init.d/\n(theonionbox) ~/theonionbox/service/init.d $ ls\ntheonionbox.sh\n```\nThe launcher script is `theonionbox.sh`. Open it with a text editor to adapt it to your installation. We're using `nano` here:\n```\n(theonionbox) ~/theonionbox/service/init.d $ nano theonionbox.sh\n```\nThese are the first lines of `theonionbox.sh` - those relevant for configuration:\n\n```bash\n#!/bin/bash\n\n#####\n# This script is based on a great tutorial of SC Phillips\n# http://blog.scphillips.com/posts/2013/07/getting-a-python-script-to-run-in-the-background-as-a-service-on-boot/\n#\n\n\n### BEGIN INIT INFO\n# Provides:          theonionbox\n# Required-Start:    $remote_fs $syslog\n# Required-Stop:     $remote_fs $syslog\n# Default-Start:     2 3 4 5\n# Default-Stop:      0 1 6\n# Short-Description: The Onion Box: WebInterface to monitor Tor node operations\n# Description:       http://www.theonionbox.com\n### END INIT INFO\n\n# Adapt this to provide the path to the root directory of the virtual environment you created for your box\nDIR=/the/path/to/your/virtual_env\n# usually no need to change the next two lines!\nDAEMON=$DIR/bin/theonionbox\nDAEMON_NAME=theonionbox\n\n# This next line determines what user the script runs as.\nDAEMON_USER=debian-tor\n\n# Add any command line options for your daemon here:\n# If you e.g. want your box to create additional log files, enable this here!\n# DAEMON_OPTS=\"--log=$DIR\"\n# HeadsUp! You then have to ensure that DAEMON_USER has write privileges to $DIR!\nDAEMON_OPTS=\"\"\n\n#####\n# *** No need to change anything below this line! ***\n#\n[...]\n```\nAlter the line starting with `DIR=` to provide the path to the root directory of the virtual environment you created for your box. For our scenario, this is `/home/pi/theonionbox`:\n```bash\n[...]\n# Adapt this to provide the path to the root directory of the virtual environment you created for your box\nDIR=/home/pi/theonionbox\n# usually no need to change the next lines!\n[...]\n```\nNext you should verify that `DAEMON_USER=` is naming the _correct_ user to run your Onion Box. On Debian, this is usually `debian-tor` and thus already set accordingly.\n```bash\n[...]\n# This next line determines what user the script runs as.\nDAEMON_USER=debian-tor\n[...]\n```\n\u003e Refer to the chapter [First Flight](#first-flight) if you're unsure what to use here.\n\nFinally there is `DAEMON_OPTS=` to provide command line parameters to the launching script - if you need those.\n```bash\n[...]\n# Add any command line options for your daemon here:\n# If you e.g. want your box to create additional log files, enable this here!\n# DAEMON_OPTS=\"--log=$DIR\"\n# HeadsUp! You then have to ensure that DAEMON_USER has write privileges to $DIR!\nDAEMON_OPTS=\"\"\n[...]\n```\nRefer to the chapter discussing the [command line parameters](#command-line-parameters) for details.\n\nThat completed, close `nano` and save the changes to `theonionbox.sh`: Press _Strg+X_, then follow the instructions given!\n\nThe next steps are straight forward:\n* Copy the altered init script to `/etc/init.d`: `sudo cp ./theonionbox.sh /etc/init.d`\n* Change to `/etc/init.d`: `cd /etc/init.d`\n* Make sure the script you've copied before to `/etc/init.d` is executable: `sudo chmod 755 ./theonionbox.sh`\n* Register this service to the system: `sudo systemctl daemon-reload`\n* Check that everything works so far: Launch your Onion Box for the first time as a service `sudo ./theonionbox.sh start`. This should give you no error messages but feedback a nice \\[OK\\].\n* Check that your Onion Box is active: `sudo ./theonionbox.sh status` should tell you `active (running)`.\n* Finally run `sudo update-rc.d theonionbox.sh defaults` to link `theonionbox.sh` into `init.d`'s default launch sequence.\n\nDone.\n\n\n### ... using systemd\nChange to the `systemd` directory within `service`:\n```\n(theonionbox) ~/theonionbox/service $ cd systemd/\n(theonionbox) ~/theonionbox/service/systemd $ ls\ntheonionbox.service\n```\nThe launcher script is `theonionbox.service`. Open it with a text editor to adapt it to your installation. We're using `nano` here:\n```\n(theonionbox) ~/theonionbox/service/systemd $ nano theonionbox.service\n```\nThis is `theonionbox.service` - in full length:\n``` bash\n# Based on a contribution by svengo\n# https://github.com/ralphwetzel/theonionbox/issues/24\n\n# Run The Onion Box as background service\n# https://github.com/ralphwetzel/theonionbox/\n\n[Unit]\nDescription=The Onion Box\nDocumentation=https://github.com/ralphwetzel/theonionbox\nAfter=network.target\n\n[Service]\nType=simple\nWorkingDirectory=/home/pi/theonionbox\nExecStart=/home/pi/theonionbox/bin/theonionbox\nUser=debian-tor\nSyslogIdentifier=theonionbox\nStandardOutput=syslog\nStandardError=syslog\nRestart=on-failure\nRestartSec=10\n\n[Install]\nWantedBy=multi-user.target\n```\nAlter the line starting with `WorkingDirectory=` to provide the absolute path to the root directory of the virtual environment you created for your box. For our scenario, this is `/home/pi/theonionbox`:\n```bash\n[...]\nWorkingDirectory=/home/pi/theonionbox\n[...]\n```\nNext provide the (absolute) path to [_The Box Launcher_](#verification-of-the-installation) to parameter `ExecStart=`. This path usually is a concatenation of the path already defined for `WorkingDirectory=` (which names the root directory of the virtual environment of your box) and `bin/theonionbox`:\n```bash\n[...]\nExecStart=/home/pi/theonionbox/bin/theonionbox\n[...]\n```\nIf you need to define [command line parameters](#command-line-parameters), append those as well to `ExecStart=`; e.g. to enable the Debug mode, add a `-d`:\n```bash\n[...]\nExecStart=/home/pi/theonionbox/bin/theonionbox -d\n[...]\n```\nFinally you should verify that `User=` is naming the _correct_ user to run your Onion Box. On Debian, this is usually `debian-tor` and thus already set accordingly.\n```bash\n[...]\nUser=debian-tor\n[...]\n```\n\u003e Refer to the chapter [First Flight](#first-flight) if you're unsure what to use here.\n\nThat completed, close `nano` and save the changes to `theonionbox.service`: Press _Strg+X_, then follow the instructions given!\n\nThe next steps are straight forward:\n* Copy the altered script to `/etc/systemd/system`: `sudo cp ./theonionbox.service /etc/systemd/system`\n* Start the new service with `sudo systemctl start theonionbox`\n* Check that your Onion Box is active: `systemctl status theonionbox` should tell you `active (running)`.\n* If everything is okay, link `theonionbox.service` into `systemd`'s start sequence to auto-launch it when booting the system: `sudo systemctl enable theonionbox`.\n\nDone.\n\n## *The Onion Box* behind Apache's mod_proxy\n\nIf you intend to operate your *Box* behind Apache's *mod_proxy*, you need to adapt the configuration of both, the proxy as well as your *Box*:\n\nFor the following example lets assume that your *Onion Box* is at `192.168.178.46:8080` in your local (home) network.\nYou're logged into the server acting as the proxy. Apache is already installed on this server.\n\nTo configure *mod_proxy* edit the configuration file `httpd.conf` and uncomment the following lines:\n```\nLoadModule proxy_module modules/mod_proxy.so \nLoadModule proxy_ajp_module modules/mod_proxy_ajp.so \nLoadModule proxy_http_module modules/mod_proxy_http.so\n```\n\nAt the end of `httpd.conf` add the following line to define the proxy operation:\n\n```\nProxyPass \u003cproxyname\u003e \u003cendpointURL\u003e\n```\n\nRegarding our example you would define\n```\nProxyPass \"/theonionbox\" \"http://192.168.178.46:8080\"\n```\n\nAfter a restart of Apache, browsing to `localhost/theonionbox` on your proxy server should then redirect to `http://192.168.178.46:8080`.\nDoing so should open your *Box* page - yet it looks scrumbled and doesn't operate as it should.\n\nTo solve that issue you have to set the parameter `base_path` in your `theonionbox.cfg` configuration file to match the `\u003cproxyname\u003e` you defined earlier:\n\n```\n# Per default, the Box operates at the root level of a domain e.g. http://localhost:8080/.\n# If you intend to operate it (behind a proxy!) at a deeper level (e.g. @ http://my.server.com/theonionbox/)\n# you have to define that base path here. You are not limited to a single path element.\n# Please assure that this is an absolute filepath yet without the domain:port, beginning with a leading slash,\n# no trailing slash, no quotation marks:\nbase_path = /theonionbox\n```\nNow everything should work as expected.\n\n## *The Onion Box* Docker support\nThe [Docker](Docker) directory holds a [Dockerfile](https://docs.docker.com/engine/reference/builder/) and a dedicated configuration file (`theonionbox.cfg`) to support the operation of *The Onion Box* from a [Docker](http://www.docker.com) image. Please be aware, that this Docker image for *The Onion Box* only supports [password authentication](#password-authentication).\n\nTo build the image, change to the Docker directory and run `sudo docker build -t theonionbox .`.\n\u003e If you've run `pip` to perform the [installation](#installation) of your Onion Box, you'll find the Docker directory within the [`service`](#verification-of-the-installation) directory.\n\nTo then launch *The Onion Box* within the created Docker image, run `sudo docker run --network host -p 8080:8080 theonionbox`.\n\n\n## Usage Monitoring\nTo create a small survey of its usage, _The Onion Box_ sends the following information to `t527moy64zwxsfhb.onion`, the hidden service acting as _The Onion Box Update Service_ when requesting the latest version information of Tor and _The Onion Box_:\n\n- An UUID created newly each time during launch of the box.\n- The stamp of your _Box_ release\n- The name of the operating system hosting your box\n- The release information of the operating system hosting your box\n\nBy intension these information are not at all sufficient to identify you (as a person) or the system hosting your box. They just allow to estimate the number of concurrently running instances of _The Onion Box_ and the diversity of the underlying operating systems.\n\nPlease refer to [version.py](theonionbox/tob/version.py) to review the code:\n```python\n[...]\n\nproxies = {\n    'http': 'socks5h://' + proxy_address,\n    'https': 'socks5h://' + proxy_address\n}\npayload = {\n    'protocol': __VERSION_PROTOCOL__,\n    'version': self.version,\n    'system': self.system,\n    'release': self.release\n}\n\naddress = 'http://t527moy64zwxsfhb.onion/{}/check.html'.format(self.id)\n\nr = None\n\ntry:\n    r = requests.get(address, proxies=proxies, params=payload, timeout=10)\nexcept Exception as exc:\n    pass\n\n[...]\n\n```\n\n## Q\u0026A\n### I receive a _Not supported proxy scheme socks5h_ warning. What shall I do?\nIf you receive this message, your `requests` module installation most probably is outdated - and not supporting _socks5h_ proxy operations.\n\nIf you do the obvious thing and try to `pip install requests --upgrade`, you risk to destroy your `pip` functionality.\n\nTherefore you should first  \n`sudo easy_install -U pip` (Python 2.x)  \nor  \n`sudo easy_install3 -U pip` (Python 3.x)\nto install the latest `pip` version **together with a very recent version of `requests`**.\n\n\u003e This works even if your `pip` installation is already broken and issuing e.g. an _IncompleteRead_ error.\n\nAfter that, you could `pip install requests --upgrade` if you like, yet usually it shouldn't be necessary any more.\n\n### I get a _Memory Error_ when trying to install via pip\n\nIf your system answers a `pip install theonionbox` command with a lengthy error message ending like\n```\n[...]\nFile \"/usr/local/lib/python2.7/dist-packages/pip/_vendor/cachecontrol/controller.py\", line 205, in cache_response\nself.serializer.dumps(request, response, body=body),\nFile \"/usr/local/lib/python2.7/dist-packages/pip/_vendor/cachecontrol/serialize.py\", line 81, in dumps\n).encode(\"utf8\"),\nMemoryError\"\n```\nit is time to reboot your system.  \nIf the problem still persists after the reboot, you could try to perform the installation process via\n```\npip --no-cache-dir install theonionbox\n```\nto reduce the memory demand of `pip` when installing _The Onion Box_.\n\n## Shorttrack\nThe straightest procedure to run _The Onion Box_, if the `sudo` system is installed and the Tor node is owned by user `debian-tor`:\n\n- `sudo useradd -m user1`\n- `sudo passwd user1`; enter password\n- `sudo usermod -s /bin/bash user1`\n- to be safe: `sudo usermod -g users user1`\n- `sudo usermod -g sudo user1` grants `sudo` rights\n- `su - user1`; enter password\n- `virtualenv -p python3 theonionbox`\n- `cd theonionbox`\n- `source bin/activate`\n- `pip install theonionbox`\n- `sudo -u debian-tor bin/theonionbox`; enter password\n\nEnjoy!\n\n## Acknowledgments\nDay by day it is a repetitive pleasure to learn from uncountable people who share their knowledge, their time and their work with the world. This section shall express my gratefulness to those who supported me solving issues I encountered during the last years. **Thank You!**\n\nŁukasz Dziedzic (and his friends) - for creating and publishing the great [Lato](https://latofonts.com) font family.\n\n[SC. Phillips](http://www.scphillips.com) - whose [Blog](http://blog.scphillips.com/posts/2013/07/getting-a-python-script-to-run-in-the-background-as-a-service-on-boot/) gave a perfect starting point when I tried to operate _The Onion Box_ as a background service.\n\nAll the people contributing to [StackOverflow](https://stackoverflow.com/) - who taught me Python by example.\n\n[svengo](https://github.com/svengo) - who [contributed](https://github.com/ralphwetzel/theonionbox/issues/24) the [procedure](#-using-systemd) to operate _The Onion Box_ as a daemon with systemd.\n\n\u003ctable\u003e\n  \u003ctbody\u003e\n    \u003ctr \u003e\n    \u003ctd width = \"100px\"\u003e\n    \u003cimg src=\"docs/images/pclogo.svg\" align = \"center\" alt=\"PyCharm\"/\u003e\n    \u003c/td\u003e\n    \u003ctd\u003e\n\nThe [JetBrains](http://www.jetbrains.com) team - for their support to _The Onion Box_ providing an Open Source license of their gorgeous PyCharm IDE. If you run your own personal Open Source project, you may as well apply for a license [here](https://www.jetbrains.com/buy/opensource/?product=pycharm) (non affiliated link).\n\u003c/td\u003e\n\u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\nOlaf - who provided great support and endless patience while testing the `pip` installation system and its dedicated documentation.\n\n[Rupert Edwards](https://github.com/ruped24) - who contributed the Docker support setup.\n\n\u003e I apologize sincerely being convinced it is impossible to mention everyone who gave me the opportunity to participate from his or her experience.  \nPlease raise your hand if you think someone should be added to this list!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fralphwetzel%2Ftheonionbox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fralphwetzel%2Ftheonionbox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fralphwetzel%2Ftheonionbox/lists"}