Implement customizable torrc configuration (#141)

.gitleaksignore

@@ -0,0 +1 @@
+/github/workspace/tor/torrc.template:generic-api-key:59

README.md

@@ -8,6 +8,8 @@ Run TOR conveniently from a docker container.
 [![Docker Pulls](https://img.shields.io/docker/pulls/leplusorg/tor)](https://hub.docker.com/r/leplusorg/tor)
 [![Docker Version](https://img.shields.io/docker/v/leplusorg/tor?sort=semver)](https://hub.docker.com/r/leplusorg/tor)
 
+## Usage
+
 The simplest way to launch a TOR proxy using this container is to use the following command:
 
 ```bash
@@ -26,6 +28,46 @@ Once the docker container has finished starting, you can test it with the follow
 curl --socks5 localhost:9050 --socks5-hostname localhost:9050 https://check.torproject.org/api/ip
 ```
 
+## 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         |
+
+Note that the defaults are the same as Tor's default if the
+configuration option is not set.
+
+You can use the `-m` option of Docker to mount a custom template the
+inmage 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`.
+
+Of course you can also build an image on top of this one with a custom `torrc.template`.
+
+For troubleshooting, you can enable verbose logging by setting the
+value of environment variable `DEBUG` to `true`.
+
 ## Request configuration change
 
-Please use [this link](https://github.com/leplusorg/docker-tor/issues/new?assignees=thomasleplus&labels=enhancement&template=feature_request.md&title=%5BFEAT%5D) (GitHub account required) to suggest a change in this image configuration.
+Please use [this link](https://github.com/leplusorg/docker-tor/issues/new?assignees=thomasleplus&labels=enhancement&template=feature_request.md&title=%5BFEAT%5D) (GitHub account required) to suggest a change in this image configuration or to expose a new Tor configuration option.

tor/Dockerfile

@@ -3,15 +3,17 @@ FROM alpine:3.20.3@sha256:beefdbd8a1da6d2915566fde36db9db0b524eb737fc57cd1367eff
 HEALTHCHECK CMD ["/usr/bin/curl", "--socks5", "localhost:9050", "--socks5-hostname", "localhost:9050", "https://check.torproject.org/api/ip"]
 
 # hadolint ignore=DL3018
-RUN apk --update --no-cache add tor \
-    && rm -rf /var/cache/apk/*
-
-COPY torrc /etc/torrc
+RUN apk --update --no-cache add bash gettext tor \
+    && rm -rf /var/cache/apk/* \
+    && chmod o+rwx /etc/tor
 
 USER "tor"
 
+COPY torrc.template tor-wrapper.sh /etc/tor/
+
 WORKDIR "/var/lib/tor"
 
 EXPOSE 9050
 
-ENTRYPOINT ["/usr/bin/tor", "-f", "/etc/torrc"]
+CMD ["/etc/tor/tor-wrapper.sh"]
+ENTRYPOINT []

tor/docker-compose.test.yml

@@ -12,3 +12,5 @@ services:
     build:
       context: .
       dockerfile: Dockerfile
+    environment:
+      - SOCKS_HOSTNAME=0.0.0.0

tor/tor-wrapper.sh

@@ -0,0 +1,61 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+# debug mode is off by default
+if [ -z "${DEBUG+x}" ]; then
+	DEBUG=false
+fi
+
+# Honoring GitHub runner debug mode
+if [ -n "${RUNNER_DEBUG+x}" ] && [ "${RUNNER_DEBUG}" = 1 ]; then
+	DEBUG=false
+fi
+
+if [ "${DEBUG}" = true ]; then
+	set -o xtrace
+	LOG_LEVEL=debug
+fi
+
+if [ -f '/etc/torrc' ]; then
+	if [ "${DEBUG}" = true ]; then
+		\echo 'DEBUG: Found existing /etc/torrc, overwritting /etc/tor/torrc.'
+	fi
+	\cp -f '/etc/torrc' '/etc/tor/torrc'
+else
+	if [ -n "${SHELL_FORMAT+x}" ]; then
+		if [ "${DEBUG}" = true ]; then
+			\echo "DEBUG: Found custom Shell Format for envsubst: ${SHELL_FORMAT}"
+		fi
+	elif [ -n "${SHELL_FORMAT_EXTRA+x}" ]; then
+		if [ "${DEBUG}" = true ]; then
+			\echo "DEBUG: Found extra Shell Format for envsubst: ${SHELL_FORMAT_EXTRA}"
+		fi
+		# Escaping predefined variables names except
+		# SHELL_FORMAT_EXTRA, as we don't want them to be
+		# expanded.
+		SHELL_FORMAT="\${DATA_DIRECTORY},\${LOG_LEVEL},\${LOG_FILE},\${SOCKS_HOSTNAME},\${SOCKS_PORT},${SHELL_FORMAT_EXTRA}"
+	else
+		# Using single quotes here on purpose, we don't want the
+		# variables names to be expanded.
+		# shellcheck disable=SC2016
+		SHELL_FORMAT='${DATA_DIRECTORY},${LOG_LEVEL},${LOG_FILE},${SOCKS_HOSTNAME},${SOCKS_PORT}'
+	fi
+	DATA_DIRECTORY="${DATA_DIRECTORY:-/var/lib/tor}" \
+		LOG_LEVEL="${LOG_LEVEL:-notice}" \
+		LOG_FILE="${LOG_FILE:-stdout}" \
+		SOCKS_HOSTNAME="${SOCKS_HOSTNAME:-127.0.0.1}" \
+		SOCKS_PORT="${SOCKS_PORT:-9050}" \
+		envsubst "${SHELL_FORMAT}" </etc/tor/torrc.template >/etc/tor/torrc
+fi
+
+if [ "${DEBUG}" = true ]; then
+	\echo 'DEBUG: Content of /etc/tor/torrc:'
+	\echo 'DEBUG: =========================='
+	\sed -e 's/^/DEBUG: /' /etc/tor/torrc
+	\echo 'DEBUG: =========================='
+fi
+
+cmd=$(\which tor)
+
+"${cmd}" -f /etc/tor/torrc "$@"