✨ feat: add gen-auth tool and refactor compose templates

Major refactor of Docker Compose configurations and tooling enhancements. - ✨ Add `gen-auth` script for generating Tor Control Port credentials - 🐳 Refactor Docker Compose templates: - Add native healthcheck configurations to all relay/bridge files - Standardize security capabilities (drop ALL, add SETUID/SETGID) - Remove verbose comments to streamline template usage - Update volume definitions for better data persistence - 🔧 Update base dependencies: - Alpine Linux -> 3.23.0 - Golang -> 1.25.5-alpine - 🧹 Standardize ENV variable names across all configurations
2026-04-06 00:32:04 +02:00 · 2025-12-05 04:37:19 +08:00
parent 1907745fff
commit a28ce0a4e6
30 changed files with 698 additions and 900 deletions
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -57,11 +57,13 @@ flowchart TD
    DiagTools -->|health| HealthTool[📊 tools/health]
    DiagTools -->|fingerprint| FingerprintTool[🆔 tools/fingerprint]
    DiagTools -->|bridge-line| BridgeTool[🌉 tools/bridge-line]
+    DiagTools -->|gen-auth| GenAuthTool[🔑 tools/gen-auth]

    StatusTool --> Running
    HealthTool --> Running
    FingerprintTool --> Running
    BridgeTool --> Running
+    GenAuthTool --> Running

    Trap --> StopTail[🧽 Kill tail -F PID]
    StopTail --> StopTor[📨 Send SIGTERM to Tor]
@@ -532,6 +534,7 @@ flowchart TD
 | **health** | Monitoring integration | JSON | busybox: pgrep, grep, awk |
 | **fingerprint** | Relay identity | Text + URL | busybox: cat, awk |
 | **bridge-line** | Bridge sharing | obfs4 bridge line | busybox: grep, sed, awk, wget |
+| **gen-auth** | Credential generation | Text (Pass + Hash) | busybox: head, tr, tor |

 **All tools:**
 - Use `#!/bin/sh` (POSIX sh, not bash)
@@ -616,6 +619,7 @@ graph TD
        Health["💚 health"]
        Fingerprint["🧬 fingerprint"]
        BridgeLine["🌉 bridge-line"]
+        GenAuth["🔑 gen-auth"]
        
        UsrLocal --> Bin
        Bin --> Entrypoint
@@ -796,7 +800,7 @@ flowchart LR
    end

    subgraph Build["🏗️ Docker Build"]
-        Alpine[🐧 Alpine 3.22.2]
+        Alpine[🐧 Alpine 3.23.0]
        Install[📦 apk add packages]
        Copy[📥 Copy scripts and tools]
        Perms[🔒 Set permissions]
@@ -897,6 +901,7 @@ flowchart TD
 | `tools/health` | JSON health API | ~100 |
 | `tools/fingerprint` | Show relay identity | ~50 |
 | `tools/bridge-line` | Generate bridge line | ~80 |
+| `tools/gen-auth` | Generate Control Port auth | ~30 |

 ### External Documentation

@@ -908,6 +913,6 @@ flowchart TD
 ---
 <div align="center">

-**Document Version:** 1.0.3 • **Last Updated:** 2025-11-14 • **Container Version:** v1.1.1
+**Document Version:** 1.0.4 • **Last Updated:** 2025-12-05 • **Container Version:** v1.1.3

 </div>
--- a/docs/CONTROL-PORT.md
+++ b/docs/CONTROL-PORT.md
@@ -0,0 +1,234 @@
+# Control Port Configuration & Advanced Monitoring
+
+This guide covers secure configuration of the Tor Control Port for advanced monitoring tools like **Nyx** (command-line monitor) and **Prometheus exporters**.
+
+> **⚠️ Security Note:** The Control Port provides administrative access to your relay. Always use authentication and follow the security guidelines below.
+
+## Table of Contents
+
+* [Authentication Setup](#authentication-setup)
+* [Configuration Methods](#configuration-methods)
+* [Connecting to Your Relay](#connecting-to-your-relay)
+* [Monitoring with Nyx](#monitoring-with-nyx)
+* [Troubleshooting](#troubleshooting)
+
+---
+
+## Authentication Setup
+
+Tor requires a hashed password to access the Control Port. We recommend using the built-in helper tool to generate this securely.
+
+### Option A: Use the Helper Tool (Recommended)
+
+The container includes a built-in utility called `gen-auth` that generates a secure 32-character password and the required configuration hash in one step.
+
+Run the tool inside your container:
+
+```bash
+docker exec tor-relay gen-auth
+````
+
+**Example Output:**
+
+```bash
+╔════════════════════════════════════════════════════════════╗
+║  Tor Control Port Authentication Generator                 ║
+╚════════════════════════════════════════════════════════════╝
+
+✓ Generated secure 32-character password
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+1. Save this password (use for Nyx authentication):
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+   4xK8mP2qR9vL3nT6wY5sD1gH7jF0bN8c...
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+2. Add this line to your torrc:
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+   HashedControlPassword 16:A1B2C3D4E5F6...
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📝 Next steps:
+   1. Edit your relay.conf and add the HashedControlPassword line above
+   2. Restart your container: docker restart tor-relay
+   3. Connect with Nyx using the password shown above
+
+💡 Tip: Save the password in a secure password manager!
+```
+
+**Next Steps:**
+
+1.  **Copy the Password**: Store this in a password manager. You will need it to log in to Nyx.
+2.  **Copy the Hash**: Add the `HashedControlPassword ...` line to your `relay.conf` (or `torrc`).
+
+### Option B: Manual Generation
+
+If you prefer to generate credentials manually on your host machine:
+
+```bash
+# 1. Generate a 32-byte secure password
+PASS=$(openssl rand -base64 32)
+echo "Password: $PASS"
+
+# 2. Generate the hash inside the container
+docker exec tor-relay tor --hash-password "$PASS"
+```
+
+-----
+
+## Configuration Methods
+
+Choose **one** method based on your use case.
+
+### Method A: Unix Domain Socket (Recommended)
+
+**Best for:** Running Nyx or monitoring tools on the same host.
+**Security:** Uses file system permissions; impossible to expose to the internet.
+
+Add to your `relay.conf`:
+
+```ini
+# Disable TCP Control Port
+ControlPort 0
+
+# Enable Unix Domain Socket
+ControlSocket /var/lib/tor/control_socket
+ControlSocketsGroupWritable 1
+
+# Add your generated hash
+HashedControlPassword 16:YOUR_FULL_HASH_STRING_HERE
+```
+
+**Volume Configuration:**
+Ensure your data volume is mounted so the host can access the socket file. If you are using standard docker volume names:
+
+  * **Docker Volume Path:** `/var/lib/docker/volumes/tor-guard-data/_data/control_socket`
+  * **Bind Mount Path:** If you mapped a host folder (e.g., `-v ./data:/var/lib/tor`), the socket will be in `./data/control_socket`.
+
+### Method B: TCP Localhost
+
+**Best for:** External monitoring tools (e.g., Prometheus) that cannot read Unix sockets.
+**Requirement:** Works best with `--network host` mode.
+
+Add to your `relay.conf`:
+
+```ini
+# Bind strictly to localhost
+ControlPort 127.0.0.1:9051
+
+# Add your generated hash
+HashedControlPassword 16:YOUR_FULL_HASH_STRING_HERE
+```
+
+> **⚠️ CRITICAL SECURITY WARNING**
+> Never use `ControlPort 0.0.0.0:9051` or `ControlPort 9051` in host network mode.
+> This exposes your control interface to the public internet, allowing anyone to attack your relay.
+> **Always bind to 127.0.0.1.**
+
+-----
+
+## Connecting to Your Relay
+
+After updating your configuration, restart the container to apply changes:
+
+```bash
+docker restart tor-relay
+```
+
+Verify the port or socket is active:
+
+```bash
+docker logs tor-relay | grep -i "Opened Control listener"
+```
+
+-----
+
+## Monitoring with Nyx
+
+[Nyx](https://nyx.torproject.org/) provides real-time bandwidth graphs, connection tracking, and log monitoring.
+
+### 1. Installation
+
+Install Nyx on your **host machine**:
+
+```bash
+sudo apt install nyx
+```
+
+### 2. Connect
+
+**If using Unix Socket (Method A):**
+
+```bash
+# Locate your volume mount point (example for standard docker volume)
+nyx -s /var/lib/docker/volumes/tor-guard-data/_data/control_socket
+```
+
+**If using TCP (Method B):**
+
+```bash
+nyx -i 127.0.0.1:9051
+```
+
+*When prompted, enter the **plaintext password** generated by `gen-auth`.*
+
+-----
+
+## Advanced Integration
+
+### Prometheus Exporter
+
+If using **Method B (TCP)**, you can scrape metrics using the Prometheus Tor Exporter:
+
+```bash
+docker run -d \
+  --name tor-exporter \
+  --network host \
+  atx/prometheus-tor_exporter \
+  --tor.control-address=127.0.0.1:9051 \
+  --tor.control-password="YOUR_PASSWORD_HERE"
+```
+
+### Automated Health Checks
+
+You can check relay status via script using `nc` (Netcat):
+
+```bash
+echo -e 'AUTHENTICATE "YOUR_PASSWORD"\r\nGETINFO status/circuit-established\r\nQUIT' | nc 127.0.0.1 9051
+```
+
+Expected output:
+```bash
+250 OK
+250-status/circuit-established=1
+250 OK
+250 closing connection
+```
+
+-----
+
+## Troubleshooting
+
+### "Authentication failed"
+
+1.  **Wrong String**: Ensure you are using the *plaintext* password in Nyx, not the *hash*.
+2.  **Config Mismatch**: Check that `HashedControlPassword` in `relay.conf` matches the hash generated by the tool.
+3.  **Restart**: Did you `docker restart tor-relay` after editing the config?
+
+### "Connection refused" or "No such file"
+
+  * **Unix Socket**: Check permissions. The socket must be readable by the user running Nyx.
+    ```bash
+    sudo ls -la /var/lib/docker/volumes/tor-guard-data/_data/control_socket
+    ```
+  * **TCP**: Ensure the container is running and port 9051 is bound locally.
+    ```bash
+    netstat -tuln | grep 9051
+    ```
+
+### "Socket Permission Denied"
+
+The socket file is created by the `root` or `tor` user inside the container. You may need to run Nyx with `sudo` or adjust your user groups to read the Docker volume directory.
--- a/docs/DEPLOYMENT.md
+++ b/docs/DEPLOYMENT.md
@@ -74,6 +74,7 @@ docker pull r3bo0tbx1/onion-relay:latest
 docker run -d \
  --name tor-relay \
  --network host \
+  --security-opt no-new-privileges:true \
  -v ~/tor-relay/relay-guard.conf:/etc/tor/torrc:ro \
  -v tor-data:/var/lib/tor \
  -v tor-logs:/var/log/tor \
--- a/docs/FAQ.md
+++ b/docs/FAQ.md
@@ -24,15 +24,15 @@ Common questions about Tor Guard Relay deployment, configuration, and troublesho
 - **Exit relay** - Last hop (requires legal preparation)
 - **Bridge relay** - Helps users bypass censorship (obfs4 support)

-Built on Alpine Linux 3.22.2 with a minimal 20MB image size, busybox-only tools, and weekly automated security rebuilds.
+Built on Alpine Linux 3.23.0 with a minimal 20MB image size, busybox-only tools, and weekly automated security rebuilds.

 ### What makes this different from the official Tor images?

 | Feature | This Project | Official Images |
 |---------|--------------|-----------------|
 | **Image size** | ~16.8 MB | ~100+ MB |
-| **Base** | Alpine 3.22.2 | Debian |
-| **Diagnostics** | 4 busybox tools + JSON API | None |
+| **Base** | Alpine 3.23.0 | Debian |
+| **Diagnostics** | 5 busybox tools + JSON API | None |
 | **Multi-mode** | Guard/Exit/Bridge in one image | Separate images |
 | **Weekly rebuilds** | ✅ Automated | ❌ Manual |
 | **ENV configuration** | ✅ Full support | Limited |
@@ -40,8 +40,8 @@ Built on Alpine Linux 3.22.2 with a minimal 20MB image size, busybox-only tools,

 ### Is this production-ready?

-**Yes.** Current version is v1.1.1 (Active/Stable). Used in production with:
- ✅ Security-hardened (32 vulnerabilities fixed in v1.1.1)
+**Yes.** Current version is v1.1.3 (Active/Stable). Used in production with:
+- ✅ Security-hardened (32 vulnerabilities fixed in >=v1.1.1)
 - ✅ Non-root execution (tor user, UID 100)
 - ✅ Weekly automated rebuilds with latest Tor + Alpine patches
 - ✅ Multi-architecture support (AMD64, ARM64)
@@ -409,7 +409,7 @@ docker exec obfs4-bridge fingerprint

 **See:** [MIGRATION.md](MIGRATION.md) for complete guide

-### How do I upgrade from v1.1.0 to v1.1.1?
+### How do I upgrade from v1.1.0 to >=v1.1.1?

 **Guard/Exit relays (no changes required):**
 ```bash
@@ -427,7 +427,7 @@ docker run -d --name tor-relay ...  # Same config
 **Verify upgrade:**
 ```bash
 docker exec tor-relay cat /build-info.txt
-# Should show: Version: 1.1.1
+# Should show: Version: 1.1.3

 docker exec tor-relay fingerprint
 # Verify fingerprint unchanged
@@ -538,5 +538,5 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md) for guidelines.

 ---

-**Last Updated:** November 2025 (v1.1.1)
+**Last Updated:** December 2025 (v1.1.3)
 **Maintained by:** [@r3bo0tbx1](https://github.com/r3bo0tbx1)
--- a/docs/MIGRATION-V1.1.X.md
+++ b/docs/MIGRATION-V1.1.X.md
@@ -1,4 +1,4 @@
-# Migration Guide: v1.1.0 → v1.1.1
+# Migration Guide: v1.1.0 → >=v1.1.1

 This guide documents **two successful real-world migration paths** validated in production:
 1. **Guard/Middle Relay** (mounted torrc) - Zero issues
@@ -470,5 +470,5 @@ docker rm obfs4-bridge

 ---

-*Last Updated: 2025-11-13*
+*Last Updated: 2025-12-05*
 *Validated with production deployments*
--- a/docs/MIGRATION.md
+++ b/docs/MIGRATION.md
@@ -2,7 +2,7 @@

 This document provides general migration guidance for Tor Guard Relay deployments.

-For **specific v1.1.0 → v1.1.1 migration**, see [`MIGRATION-V1.1.X.md`](MIGRATION-V1.1.X.md).
+For **specific v1.1.0 → >=v1.1.1 migration**, see [`MIGRATION-V1.1.X.md`](MIGRATION-V1.1.X.md).

 ---

@@ -362,10 +362,10 @@ docker exec <container> status

 | From | To | Guide |
 |------|-----|-------|
-| v1.1.0 | v1.1.1 | [MIGRATION-V1.1.X.md](MIGRATION-V1.1.X.md) |
+| v1.1.0 | >=v1.1.1 | [MIGRATION-V1.1.X.md](MIGRATION-V1.1.X.md) |
 | Official bridge | v1.1.1 | [MIGRATION-V1.1.X.md](MIGRATION-V1.1.X.md) - Path 2 |
 | Future | Future | This document + version-specific guide |

 ---

-*Last Updated: 2025-11-13*
+*Last Updated: 2025-12-05*
--- a/docs/MONITORING.md
+++ b/docs/MONITORING.md
@@ -1,6 +1,6 @@
 # 📊 Monitoring Guide

-Guide to monitoring your Tor Guard Relay with external tools. The v1.1.1 ultra-optimized build (~20 MB) does not include built-in Prometheus metrics endpoints, but provides multiple alternatives for monitoring.
+Guide to monitoring your Tor Guard Relay with external tools. The >=v1.1.1 ultra-optimized build (~20 MB) does not include built-in Prometheus metrics endpoints, but provides multiple alternatives for monitoring.

 ---

@@ -453,4 +453,4 @@ A:

 ---

-**Last Updated:** November 2025 | **Version:** 1.1.1
+**Last Updated:** December 2025 | **Version:** 1.1.3
--- a/docs/PERFORMANCE.md
+++ b/docs/PERFORMANCE.md
@@ -346,7 +346,7 @@ time docker exec guard-relay tor --resolve example.com

 ## Monitoring & Metrics

-v1.1.1 uses **external monitoring** with the `health` JSON API for minimal image size and maximum security.
+>=v1.1.1 uses **external monitoring** with the `health` JSON API for minimal image size and maximum security.

 ### 1. JSON Health API

--- a/docs/TOOLS.md
+++ b/docs/TOOLS.md
@@ -1,6 +1,6 @@
 # 🛠️ Tools Reference Guide

-**Tor Guard Relay v1.1.1** includes 4 essential diagnostic tools built directly into the ultra-optimized ~20 MB container. All tools are busybox-compatible, executable without file extensions, and designed for production use.
+**Tor Guard Relay 1.1.3** includes 5 essential diagnostic tools built directly into the ultra-optimized ~20 MB container. All tools are busybox-compatible, executable without file extensions, and designed for production use.

 ---

@@ -12,6 +12,7 @@
 | **health** | JSON health diagnostics | JSON | Machine-readable for monitoring |
 | **fingerprint** | Display relay fingerprint | Text | With Tor Metrics link |
 | **bridge-line** | Get obfs4 bridge line | Text | Bridge mode only |
+| gen-auth | Generate Control Port auth | Text | Password + Hash |

 ---

@@ -180,6 +181,49 @@ Bridge obfs4 203.0.113.42:9002 ABCD...WXYZ cert=abc123...xyz789 iat-mode=0

 ---

+### `gen-auth`
+
+**Purpose**: Generate a secure, random 32-character password and its associated hash for configuring the Tor Control Port (required for tools like Nyx).
+
+Usage:
+```bash
+docker exec tor-relay gen-auth
+```
+
+Output Example:
+```bash
+╔════════════════════════════════════════════════════════════╗
+║  Tor Control Port Authentication Generator                 ║
+╚════════════════════════════════════════════════════════════╝
+
+✓ Generated secure 32-character password
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+1. Save this password (use for Nyx authentication):
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+   4xK8mP2qR9vL3nT6wY5sD1gH7jF0bN8c...
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+2. Add this line to your torrc:
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+   HashedControlPassword 16:A1B2C3D4E5F6...
+
+```
+
+Exit Codes:
+
+* `0` - Success
+* `1` - Error generating hash
+
+When to use:
+
+* When setting up external monitoring tools (Nyx, Prometheus).
+* Run once, copy the values, then update your relay.conf or torrc.
+
+---
+
 ## 🚀 Common Workflows

 ### 1. Quick Health Check
@@ -194,7 +238,21 @@ docker exec tor-relay health | jq .status
 docker exec tor-relay health | jq .bootstrap
 ```

-### 2. Find Your Relay on Tor Metrics
+### 2. Configure Nyx / Control Port
+
+```bash
+# Generate credentials
+docker exec tor-relay gen-auth
+
+# Add HashedControlPassword to your config
+# Restart relay
+docker restart tor-relay
+
+# Connect with Nyx
+nyx -i 127.0.0.1:9051
+```
+
+### 3. Find Your Relay on Tor Metrics
 ```bash
 # Get fingerprint and metrics link
 docker exec tor-relay fingerprint
@@ -203,7 +261,7 @@ docker exec tor-relay fingerprint
 # Click the Tor Metrics link or search manually
 ```

-### 3. Share Your Bridge
+### 4. Share Your Bridge
 ```bash
 # Get bridge line (bridge mode only)
 docker exec tor-bridge bridge-line
@@ -212,7 +270,7 @@ docker exec tor-bridge bridge-line
 # Share ONLY with trusted users, NOT publicly
 ```

-### 4. Automated Monitoring
+### 5. Automated Monitoring
 ```bash
 # Simple monitoring script
 while true; do
@@ -230,7 +288,7 @@ while true; do
 done
 ```

-### 5. Check Logs
+### 6. Check Logs
 ```bash
 # View recent logs
 docker logs --tail 100 tor-relay
@@ -264,7 +322,7 @@ docker logs tor-relay 2>&1 | grep -i warn
 # Verify tools exist
 docker exec tor-relay ls -la /usr/local/bin/

-# Should show: status, health, fingerprint, bridge-line
+# Should show: status, health, fingerprint, bridge-line, gen-auth

 # Check PATH
 docker exec tor-relay echo $PATH
@@ -343,18 +401,18 @@ docker logs tor-relay | grep -i obfs4

 ## ❓ FAQ

-**Q: Why only 4 tools instead of 9?**
-A: The v1.1.1 build prioritizes size optimization (~20 MB vs 45+ MB). These 4 tools cover all essential operations. For advanced monitoring, use external tools like Prometheus.
+**Q: Why only 5 tools instead of 9?**
+A: The v1.1.3 build remains ultra-light (~16.8 MB). These 5 tools cover all essential operations including health checks, identity, and authentication setup.

 **Q: Where are metrics/monitoring endpoints?**
 A: Removed to achieve ultra-small image size. Use `health` tool with external monitoring systems or check `/var/log/tor/notices.log` directly.

 **Q: Can I still use Prometheus?**
-A: Yes! Export logs or use `health` JSON output with a Prometheus exporter. See [MONITORING.md](./MONITORING.md) for alternatives.
+A: Yes! Use `gen-auth` to configure the Control Port, then run a separate `prometheus-tor-exporter` container alongside this one.

 **Q: What happened to the dashboard?**
 A: Removed (required Python/Flask). Use `status` tool for visual output or build your own dashboard using `health` JSON.

 ---

-**Last Updated:** November 2025 | **Version:** 1.1.1
+**Last Updated:** December 2025 | **Version:** 1.1.3
--- a/docs/TROUBLESHOOTING-BRIDGE-MIGRATION.md
+++ b/docs/TROUBLESHOOTING-BRIDGE-MIGRATION.md
@@ -1,4 +1,4 @@
-# Troubleshooting Bridge Migration to v1.1.1
+# Troubleshooting Bridge Migration to >=v1.1.1

 This guide addresses the specific issue where migrating from `thetorproject/obfs4-bridge` to `r3bo0tbx1/onion-relay:1.1.1` results in configuration validation failures and changing fingerprints.