aniondev/torrelay repository overview
TorRelay
General
TorRelay is a docker-image for simply running a tor-relay in a docker-container.
The currently used Tor-version is 0.4.9.12-0+deb13u2.
Configuration
The relay is configured exclusively by environment-variables. Each environment-variable corresponds to the configuration-directive of tor with the same name, written in lowercase. The exceptions are lognotice and logdebug, which both control the directive Log. The documentation of the directives themselves is the manual of tor.
On every start of the container the configuration-file is generated from the template, so changed environment-variables always take effect on the next start.
A complete example is docker-compose.yml.
Volumes
| Container-path | Content |
|---|---|
/Workspace/Data | The data-directory of tor. This volume must be persistent, otherwise the relay loses its identity-keys and starts as a new relay after every recreation of the container. |
/var/log/tor | The log-files, if logging to a file is enabled. |
Required environment-variables
| Environment-variable | Tor-directive | Description |
|---|---|---|
nickname | Nickname | The name under which the relay appears in the relay-list. |
orport | ORPort | The port on which the relay accepts connections of other tor-nodes. |
exitrelay | ExitRelay | Whether the relay is used as exit-relay. |
socksport | SocksPort | The socks-port for local clients. 0 disables it. |
controlsocket | ControlSocket | The control-socket. 0 disables it. |
contactinfo | ContactInfo | The contact-address of the relay-operator. |
relaybandwidthrate | RelayBandwidthRate | The average bandwidth which the relay uses for relayed traffic, for example 2000 KBytes. |
maxmeminqueues | MaxMemInQueues | The amount of memory tor is allowed to use for queues before it starts to close circuits, for example 128 MB. |
lognotice | Log | If the value is true then notice-messages are written to /var/log/tor/notices.log. |
logdebug | Log | If the value is true then the messages of the level debug are written to /var/log/tor/debug.log. This log-level can contain sensitive information, see the section about security and privacy. |
Optional environment-variables
These variables restrict the resource-usage of the relay. If such a variable is not set or empty then the corresponding directive is not written into the configuration-file and the default of tor applies.
| Environment-variable | Tor-directive | Description |
|---|---|---|
relaybandwidthburst | RelayBandwidthBurst | The maximum bandwidth which the relay is allowed to use in short peaks. Without this variable the default of tor applies, which is considerably higher than a typical value of relaybandwidthrate. The value must not be lower than the value of relaybandwidthrate. |
maxadvertisedbandwidth | MaxAdvertisedBandwidth | The bandwidth which the relay reports to the network. The directory-authorities use this value to decide how much traffic is directed to the relay, so a lower value results in less load. |
numcpus | NumCPUs | The number of worker-threads which process the circuit-creation-requests. In a container tor determines this number from the host and not from the cpu-limit of the container, so this value should match the cpus which are actually assigned to the container. |
connlimit | ConnLimit | The number of file-descriptors which must be available for tor. Tor refuses to start if this number is not reachable. |
accountingmax | AccountingMax | The maximum amount of traffic which the relay transfers per accounting-period, for example 500 GBytes. When the amount is reached, the relay hibernates until the next period begins, which means it is offline during that time. |
accountingstart | AccountingStart | The beginning and the length of the accounting-period, for example month 1 00:00. |
metricsport | MetricsPort | The address and the port on which tor provides its metrics in the prometheus-format, for example 0.0.0.0:9035. The metrics contain the values which lead to the overload-state, for example the number of dropped onionskins. This variable must only be set together with metricsportpolicy, see the section about security and privacy. |
metricsportpolicy | MetricsPortPolicy | The addresses which are allowed to read the metrics, for example accept 10.0.0.0/8. This variable must only be set together with metricsport. |
Security and privacy
The image provides no function which is not configured explicitly. In particular the relay provides no metrics unless they are configured, and no configuration-directive is written into the configuration-file for an environment-variable which is not set.
The metrics of tor allow conclusions about the traffic of the relay and therefore about its users. The manual of tor states that exposing the metrics publicly is dangerous for the users of the tor-network. Therefore the following applies:
- Without
metricsportno metrics-port is opened at all. - If
metricsportis set butmetricsportpolicyis not, then the container refuses to start instead of opening a port whose readers are not restricted. - If
metricsportpolicyis set butmetricsportis not, then the container refuses to start as well, because the restriction would have no effect and the configuration would suggest a function which does not exist. - The port of the metrics must not be published to the internet. It should only be reachable in a network which is under the control of the relay-operator, so it must not be listed in the
ports-section of the compose-file unless the published address is restricted accordingly.
Tor does not run as root in the container. It binds its ports as root and then drops its privileges to the user debian-tor, which owns the data-directory and the log-directory.
The manual of tor advises to use the log-level notice, because more verbose levels can provide sensitive information to an attacker who obtains the log-files. Therefore logdebug should only be set to true for a limited analysis and the volume with the log-files has to be protected accordingly.
The data-directory contains the identity-keys of the relay. The volume which contains it has to be protected accordingly, because anybody who has these keys can operate a relay under the identity of this relay.
Overload-state of a relay
A relay is marked as overloaded in the relay-list when one of the following states occurred. The state is shown for 72 hours after the last occurrence, so a change of the configuration is not visible in the relay-list immediately.
| State | Options which restrict the relay accordingly |
|---|---|
| Tor had to release memory because the memory-limit for the queues was reached. | Increase maxmeminqueues if the host has free memory. If it does not, reduce the traffic with maxadvertisedbandwidth, relaybandwidthrate and relaybandwidthburst, because less traffic also means smaller queues. |
| Ntor-onionskins were dropped, which means the relay could not process all circuit-creation-requests. | Set numcpus to the number of cpus which are assigned to the container and reduce maxadvertisedbandwidth, so that the network directs fewer circuits to the relay. |
| The system ran out of tcp-ports or file-descriptors. | Set connlimit and reduce the traffic with maxadvertisedbandwidth. The port-range itself is a setting of the host-system and cannot be configured in the container. |
The exact reason can be read at the relay itself via metricsport, which is the only way to determine which of the states actually occurred.
The details of the overload-report are described by the tor-project in My relay or bridge is overloaded what does this mean?.
Example of a restricted relay
The following environment-variables restrict the relay so that it stays within defined limits. The value of numcpus matches the cpus which are assigned to the container, so the entry cpus: 2 has to be added to the service as well.
cpus: 2
environment:
- relaybandwidthrate=2000 KBytes
- relaybandwidthburst=4000 KBytes
- maxadvertisedbandwidth=2000 KBytes
- maxmeminqueues=512 MB
- numcpus=2
- connlimit=8192
Development
Branching-system
This repository applies the GitFlowSimplified-branching-system.
Repository-structure
This repository applies the CommonProjectStructure-repository-structure.
License
See License.txt for license-information.
Tag summary
Content type
Image
Digest
sha256:9c2d19efb…
Size
81 MB
Last updated
7 days ago
docker pull aniondev/torrelay