TOR

Run TOR conveniently from a docker container.

Usage

To use the containerized TOR proxy from your host machine

The simplest way to launch a TOR proxy using this container accessible from your host machine only is to use the following command:

docker run --rm -p 127.0.0.1:9050:9050 -e SOCKS_HOSTNAME=0.0.0.0 leplusorg/tor

If you want the TOR proxy to be reachable from other machines on your network (i.e. share it), you can run:

docker run --rm -p 0.0.0.0:9050:9050 -e SOCKS_HOSTNAME=0.0.0.0 leplusorg/tor

Then make sure that your firewall rules allow remote connection to your port 9050.

Once the docker container has finished starting, you can test it with the following command:

curl --socks5 localhost:9050 --socks5-hostname localhost:9050 https://check.torproject.org/api/ip

To use the containerized TOR proxy from other containers

In that use case, you can use docker compose with a compose file similar to this (where bar's definition should be replaced by the container that you actually want to run using TOR):

---
version: "3.8"

services:
  tor:
    image: leplusorg/tor:latest
    environment:
      - SOCKS_HOSTNAME=0.0.0.0
  bar:
    image: foo/bar:latest
    links:
      - tor
    environment:
      - ALL_PROXY=socks5://tor:9050

Note that ALL_PROXY is not always honored by applications so depending on the container that you are running, you should read its documentation to figure out the proper way to tell it to use tor:9050 as a proxy. If this is misconfigured, everything might look like it's working but the TOR proxy is not actually being used!

Configuration

The configuration file used by Tor in this container is /et/tor/torrc but it is generated on startup by the script tor-wrapper.sh using the torrc.template file. The file is based on the torrc.sample configuration that comes with Tor. But some configuration options have been made configurable using OS environment variables. You can set a custom value for these variables for example using the -e option of Docker. Below are the variables currently available:

Variable name	Usage	Default
DATA_DIRECTORY	The data directory.	/var/lib/tor
LOG_LEVEL	The logging level.	notice
LOG_FILE	The log file or device.	stdout
SOCKS_HOSTNAME	The SOCKS hostname.	127.0.0.0.1
SOCKS_PORT	The SOCKS port.	9150
TORRC_APPEND	A block of configuration appended at the end of the torrc file.

Note that the defaults are the same as Tor's default if the configuration option is not set.

If you set the SKIP_TEMPLATE variable to any value, the whole templating logic will be disabled and the configuration file /etc/tor/torrc will be used as is (either the default one provided by Tor or yours if you mount one in the container).

You can use the -m option of Docker to mount a custom template in the image at /etc/tor/torrc.template. The templating engine (envsubst) will only replace specific environment variables in the template. These are controlled by the environment variable SHELL_FORMAT (the default list is ${DATA_DIRECTORY},${LOG_LEVEL},${LOG_FILE},${SOCKS_HOSTNAME},${SOCKS_PORT}). If you create a custom template with extra variables in it, you can set your own list using the environment variable SHELL_FORMAT or you can just append the extra variables to the existing list using the environment variable SHELL_FORMAT_EXTRA. Be careful to escape the $ characters since you don't want them to be interpolated when defining SHELL_FORMAT or SHELL_FORMAT_EXTRA.

The out-of-the-box torrc.template also loads any file in the /etc/tor/torrc.d/ directory with the .conf extension so you can mount your custom torrc configuration file(s) there. This is similar to the TORRC_APPEND environment variable but using files instead.

For troubleshooting, you can enable verbose logging by setting the value of environment variable DEBUG to true.

Request configuration change

Please use this link (GitHub account required) to suggest a change in this image configuration or to expose a new Tor configuration option.