✨ feat(v1.1.7): Happy Family support (Tor 0.4.9+ FamilyId)

🔧 New tool: gen-family - generate/view Happy Family keys - Supports --force flag to overwrite existing keys without backup prompt 🐳 Dockerfiles: gen-family in both Dockerfile and Dockerfile.edge 🔧 Entrypoint: - Phase 2: detect *.secret_family_key, log found keys (informational only) - Guard/exit config gen: append FamilyId + MyFamily from ENV vars - Bridge intentionally excluded 📊 Status tool: show family key count + Happy Family config state 📚 Docs: - README: Happy Family section (generate / import), persistence table, flowchart - ARCHITECTURE: all mermaid diagrams updated (Phase 2, config gen, tools, dirs) - TOOLS: full gen-family reference with examples and exit codes - DEPLOYMENT, MIGRATION, MIGRATION-V1.1.X, TROUBLESHOOTING: 5 -> 6 tools - FAQ, example configs: version bump + FamilyId/MyFamily placeholders - Directory authority voting: how 9 dirauths vote on relay flags (5/9 consensus) - CIISS v2 ContactInfo: field reference, generator link, proof:uri-rsa verification - All TOR_CONTACT_INFO examples updated to CIISS v2 format across templates and docs 📋 Templates: - Guard/exit/multi-relay compose: TOR_FAMILY_ID + TOR_MY_FAMILY env vars - All cosmos-compose + docker-compose versions -> 1.1.7 👷 CI: validate.yml gen-family in 8 spots (threshold 6), security tests, quick-test 🛡️ SECURITY.md: 1.1.7 active, 1.1.6 maintenance, gen-family in tools list 🔖 Version bump 1.1.6 -> 1.1.7 across 30+ files, tool count 5 -> 6, CHANGELOG entry No breaking changes. TOR_FAMILY_ID and TOR_MY_FAMILY are optional.
2026-04-06 00:32:04 +02:00 · 2026-03-02 16:23:10 +08:00
parent e861ecb623
commit be4f2bc125
39 changed files with 804 additions and 117 deletions
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -58,12 +58,14 @@ flowchart TD
    DiagTools -->|fingerprint| FingerprintTool[🆔 tools/fingerprint]
    DiagTools -->|bridge-line| BridgeTool[🌉 tools/bridge-line]
    DiagTools -->|gen-auth| GenAuthTool[🔑 tools/gen-auth]
+    DiagTools -->|gen-family| GenFamilyTool[👨‍👩‍👧 tools/gen-family]

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

    Trap --> StopTail[🧽 Kill tail -F PID]
    StopTail --> StopTor[📨 Send SIGTERM to Tor]
@@ -94,6 +96,7 @@ flowchart TD

    subgraph P2["🔐 Phase 2: Permission Hardening"]
        P2_1[🔒 chmod 700 data dir] --> P2_2[📁 chmod 755 log dir]
+        P2_2 --> P2_3[👨‍👩‍👧 Detect family keys]
    end

    subgraph P3["⚙️ Phase 3: Configuration Setup"]
@@ -136,7 +139,7 @@ flowchart TD
 | Phase | Purpose | Key Operations | Error Handling |
 |-------|---------|----------------|----------------|
 | **1** | Directory Setup | `mkdir -p` data/log/run, show disk space | Fail if mkdir fails |
-| **2** | Permissions | `chmod 700` data, `chmod 755` log | Warn on failure (read-only mount) |
+| **2** | Permissions | `chmod 700` data, `chmod 755` log, detect family keys | Warn on failure (read-only mount) |
 | **3** | Configuration | Priority: mounted > ENV > error | Die if no config source |
 | **4** | Validation | `tor --verify-config` syntax check | Die if invalid config |
 | **5** | Build Info | Show version/arch/mode/source | Warn if missing |
@@ -351,8 +354,14 @@ flowchart TD
        G4 -->|Not set| G6
        G5 --> G6{TOR_BANDWIDTH_BURST?}
        G6 -->|Set| G7[Add RelayBandwidthBurst]
-        G6 -->|Not set| GuardDone
-        G7 --> GuardDone([Guard Config Done])
+        G6 -->|Not set| G8
+        G7 --> G8{TOR_FAMILY_ID?}
+        G8 -->|Set| G9[Add FamilyId]
+        G8 -->|Not set| G10
+        G9 --> G10{TOR_MY_FAMILY?}
+        G10 -->|Set| G11[Add MyFamily entries]
+        G10 -->|Not set| GuardDone
+        G11 --> GuardDone([🛡️ Guard Config Done])
    end

    subgraph ExitConfig["🚪 Exit Config (lines 260-273)"]
@@ -364,8 +373,14 @@ flowchart TD
        E5 -->|Not set| E7
        E6 --> E7{TOR_BANDWIDTH_BURST?}
        E7 -->|Set| E8[Add RelayBandwidthBurst]
-        E7 -->|Not set| ExitDone
-        E8 --> ExitDone([Exit Config Done])
+        E7 -->|Not set| E9
+        E8 --> E9{TOR_FAMILY_ID?}
+        E9 -->|Set| E10[Add FamilyId]
+        E9 -->|Not set| E11
+        E10 --> E11{TOR_MY_FAMILY?}
+        E11 -->|Set| E12[Add MyFamily entries]
+        E11 -->|Not set| ExitDone
+        E12 --> ExitDone([🚪 Exit Config Done])
    end

    subgraph BridgeConfig["🌉 Bridge Config (lines 276-343)"]
@@ -402,6 +417,7 @@ flowchart TD
 ```

 **Base Config Includes:** Nickname, ContactInfo, ORPort, SocksPort 0, DataDirectory, Logging
+**Family Config (guard/exit):** Optional FamilyId (Tor 0.4.9+) and MyFamily (legacy, comma-separated fingerprints via TOR_MY_FAMILY)

 **Code Reference:** `docker-entrypoint.sh` lines 222-350 (generate_config_from_env)

@@ -456,7 +472,7 @@ flowchart TD
    style Enable fill:#e3f2fd
 ```

-**Security Features (fixed in v1.1.1, improved through v1.1.6):**
+**Security Features (fixed in v1.1.1, improved through v1.1.7):**
 - **Newline detection:** `wc -l` instead of busybox-incompatible `grep -qE '[\x00\n\r]'`
 - **Control char detection:** `tr -d '[ -~]'` removes printable chars, leaves control chars
 - **Whitelist enforcement:** Only known-safe torrc options allowed
@@ -468,7 +484,7 @@ flowchart TD

 ## Diagnostic Tools

-Five busybox-only diagnostic tools provide observability:
+Six busybox-only diagnostic tools provide observability:

 ```mermaid
 flowchart TD
@@ -478,6 +494,7 @@ flowchart TD
    Choice -->|health| HealthFlow
    Choice -->|fingerprint| FingerprintFlow
    Choice -->|bridge-line| BridgeFlow
+    Choice -->|gen-family| FamilyFlow

    subgraph StatusFlow["📊 tools/status - Full Health Report"]
        S1[🔍 Check Tor process running] --> S2[📈 Read bootstrap %]
@@ -518,10 +535,25 @@ flowchart TD
    FingerprintFlow --> Output3([🟢 Fingerprint + URL])
    BridgeFlow --> Output4([🟢 Bridge line or error])

+    subgraph FamilyFlow["👨‍👩‍👧 tools/gen-family - Happy Family Management"]
+        FM1{Which action?}
+        FM1 -->|gen-family Name| FM2[🔑 Check Tor version]
+        FM2 --> FM3{Key already exists?}
+        FM3 -->|Yes| FM4[⚠️ Warn: key exists]
+        FM3 -->|No| FM5[🔐 tor --keygen-family Name]
+        FM5 --> FM6[📤 Output FamilyId + instructions]
+        FM1 -->|gen-family --show| FM7[🔍 Scan keys dir for .secret_family_key]
+        FM7 --> FM8[📝 Show FamilyId from torrc]
+        FM8 --> FM9[ℹ️ Show MyFamily status]
+    end
+
+    FamilyFlow --> Output5([🟢 Key + FamilyId or status])
+
    style Output1 fill:#b2fab4
    style Output2 fill:#b2fab4
    style Output3 fill:#b2fab4
    style Output4 fill:#b2fab4
+    style Output5 fill:#b2fab4
 ```

 **JSON Output Fields:** status, pid, uptime, bootstrap, reachable, errors, fingerprint, nickname
@@ -535,6 +567,7 @@ flowchart TD
 | **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 |
+| **gen-family** | Happy Family key mgmt | Text (Key + FamilyId) | busybox: tor --keygen-family, grep, basename |

 **All tools:**
 - Use `#!/bin/sh` (POSIX sh, not bash)
@@ -576,11 +609,13 @@ graph TD
        Lib["📁 /var/lib"]
        TorData["📦 /var/lib/tor VOLUME"]
        Keys["🔑 keys/"]
+        FamilyKey["👨‍👩‍👧 *.secret_family_key"]
        FingerprintFile["🆔 fingerprint"]
        PTState["🌀 pt_state/"]
        
        Lib --> TorData
        TorData --> Keys
+        Keys --> FamilyKey
        TorData --> FingerprintFile
        TorData --> PTState
    end
@@ -620,6 +655,7 @@ graph TD
        Fingerprint["🧬 fingerprint"]
        BridgeLine["🌉 bridge-line"]
        GenAuth["🔑 gen-auth"]
+        GenFamily["👨‍👩‍👧 gen-family"]
        
        UsrLocal --> Bin
        Bin --> Entrypoint
@@ -628,6 +664,8 @@ graph TD
        Bin --> Health
        Bin --> Fingerprint
        Bin --> BridgeLine
+        Bin --> GenAuth
+        Bin --> GenFamily
    end
    Usr --> UsrLocal

@@ -661,7 +699,7 @@ graph TD

    class TorData,TorLog volumeStyle
    class TorRC configStyle
-    class Entrypoint,Healthcheck,Status,Health,Fingerprint,BridgeLine scriptStyle
+    class Entrypoint,Healthcheck,Status,Health,Fingerprint,BridgeLine,GenAuth,GenFamily scriptStyle
    class TorBin,Lyrebird,Tini binaryStyle
    class TorPID runtimeStyle
    class TorRCSample deletedStyle
@@ -831,7 +869,7 @@ flowchart LR
 ```

 **Weekly Rebuild Strategy:**
- Rebuilds use the **same version tag** as the last release (e.g., `1.1.6`)
+- Rebuilds use the **same version tag** as the last release (e.g., `1.1.7`)
 - Overwrites existing image with fresh Alpine packages (security updates)
 - No `-weekly` suffix needed - just updated packages
 - `:latest` always points to most recent release version
@@ -902,6 +940,7 @@ flowchart TD
 | `tools/fingerprint` | Show relay identity | ~50 |
 | `tools/bridge-line` | Generate bridge line | ~80 |
 | `tools/gen-auth` | Generate Control Port auth | ~30 |
+| `tools/gen-family` | Happy Family key management | ~180 |

 ### External Documentation

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

-**Document Version:** 1.0.5 • **Last Updated:** 2026-02-08 • **Container Version:** v1.1.6
+**Document Version:** 1.1.0 • **Last Updated:** 2026-03-02 • **Container Version:** v1.1.7

 </div>
--- a/docs/DEPLOYMENT.md
+++ b/docs/DEPLOYMENT.md
@@ -54,7 +54,7 @@ nano relay-guard.conf

 **Minimum required edits:**
 - `Nickname` - Your relay name
- `ContactInfo` - Your email
+- `ContactInfo` - Your contact info ([CIISS v2](https://nusenu.github.io/ContactInfo-Information-Sharing-Specification/) format recommended)
 - `ORPort` - Usually 9001 or 443
 - `RelayBandwidthRate` - Your bandwidth limit

@@ -91,7 +91,7 @@ docker ps | grep tor-relay
 # Check logs and bootstrap progress
 docker logs -f tor-relay

-# Run diagnostics (5 tools available)
+# Run diagnostics (6 tools available)
 docker exec tor-relay status         # Full health report with emojis
 docker exec tor-relay health         # JSON health data
 docker exec tor-relay fingerprint    # Show fingerprint + Tor Metrics URL
@@ -128,7 +128,7 @@ nano relay.conf

 Edit at minimum:
 - `Nickname`
- `ContactInfo`
+- `ContactInfo` ([CIISS v2](https://nusenu.github.io/ContactInfo-Information-Sharing-Specification/) format recommended)
 - `RelayBandwidthRate`

 ### Step 4: Deploy
@@ -194,7 +194,7 @@ Paste your relay configuration (see [example config](../examples/relay-guard.con

 **Important**: Edit at minimum:
 - `Nickname` - Your relay name
- `ContactInfo` - Your email
+- `ContactInfo` - Your contact info ([CIISS v2](https://nusenu.github.io/ContactInfo-Information-Sharing-Specification/) format recommended)
 - `RelayBandwidthRate` - Your bandwidth limit

 Save and set permissions:
@@ -347,7 +347,7 @@ docker run -d \
  --network host \
  -e TOR_RELAY_MODE=guard \
  -e TOR_NICKNAME=MyGuardRelay \
-  -e TOR_CONTACT_INFO=tor@example.com \
+  -e TOR_CONTACT_INFO="email:tor[]example.com ciissversion:2" \
  -e TOR_ORPORT=9001 \
  -v tor-data:/var/lib/tor \
  r3bo0tbx1/onion-relay:latest
@@ -370,7 +370,7 @@ docker run -d \
  --network host \
  -e TOR_RELAY_MODE=exit \
  -e TOR_NICKNAME=MyExitRelay \
-  -e TOR_CONTACT_INFO=tor@example.com \
+  -e TOR_CONTACT_INFO="email:tor[]example.com ciissversion:2" \
  -e TOR_ORPORT=9001 \
  -e TOR_EXIT_POLICY="accept *:80,accept *:443,reject *:*" \
  -v tor-data:/var/lib/tor \
@@ -394,7 +394,7 @@ docker run -d \
  --network host \
  -e TOR_RELAY_MODE=bridge \
  -e TOR_NICKNAME=MyBridge \
-  -e TOR_CONTACT_INFO=tor@example.com \
+  -e TOR_CONTACT_INFO="email:tor[]example.com ciissversion:2" \
  -e TOR_ORPORT=9001 \
  -e TOR_OBFS4_PORT=9002 \
  -v tor-data:/var/lib/tor \
@@ -420,7 +420,7 @@ Full configuration via environment variables is supported (no config file needed
 #### Core Configuration
 - `TOR_RELAY_MODE` - guard, exit, or bridge (default: guard)
 - `TOR_NICKNAME` - Relay nickname (required for ENV config)
- `TOR_CONTACT_INFO` - Contact email (required for ENV config)
+- `TOR_CONTACT_INFO` - Contact info ([CIISS v2](https://nusenu.github.io/ContactInfo-Information-Sharing-Specification/) format recommended, required for ENV config)
 - `TOR_ORPORT` - ORPort (default: 9001)
 - `TOR_DIRPORT` - DirPort for guard/exit (default: 0 - disabled)
 - `TOR_OBFS4_PORT` - obfs4 port for bridge mode (default: 9002)
@@ -453,7 +453,7 @@ services:
    environment:
      TOR_RELAY_MODE: guard
      TOR_NICKNAME: MyRelay
-      TOR_CONTACT_INFO: tor@example.com
+      TOR_CONTACT_INFO: "email:tor[]example.com ciissversion:2"
      TOR_ORPORT: 9001
      TOR_BANDWIDTH_RATE: 50 MBytes
      TOR_BANDWIDTH_BURST: 100 MBytes
@@ -510,7 +510,7 @@ abc123def456   r3bo0tbx1/onion-relay:latest    Up 5 minutes (healthy)

 ### 2. Run Diagnostics

-The image provides **5 diagnostic tools**:
+The image provides **6 diagnostic tools**:

 ```bash
 # Full health report with emojis
@@ -562,6 +562,8 @@ docker exec tor-relay health
 - **24-48 hours**: Full statistics available
 - **8+ days**: Eligible for Guard flag (guard relays only)

+> 🗳️ **How flags are assigned:** Tor's **9 Directory Authorities** vote every hour on relay flags (Guard, Stable, Fast, HSDir, etc.). Your relay only receives a flag when **at least 5 of 9** authorities reach consensus. New relays start as unmeasured middle relays and earn flags over time as authorities observe stable uptime and sufficient bandwidth.
+
 Search for your relay:
 - **Clearnet**: https://metrics.torproject.org/rs.html
 - **Tor Browser**: http://hctxrvjzfpvmzh2jllqhgvvkoepxb4kfzdjm6h7egcwlumggtktiftid.onion/rs.html
@@ -964,7 +966,7 @@ After successful deployment:
 ## Support

 - 📖 [Main README](../README.md)
- 🔧 [Tools Documentation](TOOLS.md) - Complete guide to the 5 diagnostic tools
+- 🔧 [Tools Documentation](TOOLS.md) - Complete guide to the 6 diagnostic tools
 - 📊 [Monitoring Guide](MONITORING.md) - External monitoring integration
 - 🐛 [Report Issues](https://github.com/r3bo0tbx1/tor-guard-relay/issues)
 - 💬 [Tor Project Forum](https://forum.torproject.net/)
--- a/docs/FAQ.md
+++ b/docs/FAQ.md
@@ -32,7 +32,7 @@ Built on Alpine Linux 3.23.0 with a minimal 20MB image size, busybox-only tools,
 |---------|--------------|-----------------|
 | **Image size** | ~16.8 MB | ~100+ MB |
 | **Base** | Alpine 3.23.0 | Debian |
-| **Diagnostics** | 5 busybox tools + JSON API | None |
+| **Diagnostics** | 6 busybox tools + JSON API | None |
 | **Multi-mode** | Guard/Exit/Bridge in one image | Separate images |
 | **Weekly rebuilds** | ✅ Automated | ❌ Manual |
 | **ENV configuration** | ✅ Full support | Limited |
@@ -72,7 +72,7 @@ docker run -d \
  --network host \
  -e TOR_RELAY_MODE=guard \
  -e TOR_NICKNAME=MyGuardRelay \
-  -e TOR_CONTACT_INFO="admin@example.com" \
+  -e TOR_CONTACT_INFO="email:admin[]example.com ciissversion:2" \
  -e TOR_ORPORT=9001 \
  -e TOR_DIRPORT=9030 \
  -v tor-data:/var/lib/tor \
@@ -89,6 +89,37 @@ docker run -d \
  ghcr.io/r3bo0tbx1/onion-relay:latest
 ```

+### What is the ContactInfo Information Sharing Specification (CIISS)?
+
+The [CIISS v2](https://nusenu.github.io/ContactInfo-Information-Sharing-Specification/) is a machine-readable format for the Tor relay `ContactInfo` field. Instead of a plain email, it uses structured `key:value` pairs that tools can parse and verify automatically.
+
+**Format:**
+```
+email:your-email[]example.com url:https://example.com proof:uri-rsa ciissversion:2
+```
+
+**Key fields:**
+| Field | Purpose | Example |
+|-------|---------|---------|
+| `email:` | Contact email (`@` → `[]`) | `email:tor[]example.com` |
+| `url:` | Operator website | `url:https://example.com` |
+| `proof:` | URL ownership verification | `proof:uri-rsa` |
+| `pgp:` | 40-char PGP fingerprint | `pgp:EF6E286DDA85EA2A4BA7DE684E2C6E8793298290` |
+| `abuse:` | Abuse contact (exits) | `abuse:abuse[]example.com` |
+| `hoster:` | Hosting provider domain | `hoster:www.example-hoster.com` |
+| `uplinkbw:` | Uplink bandwidth (Mbit/s) | `uplinkbw:1000` |
+| `ciissversion:` | Spec version (**mandatory**) | `ciissversion:2` |
+
+**Why use it?**
+- Tools like [Tor Metrics](https://metrics.torproject.org/) can parse your info automatically
+- `proof:uri-rsa` lets anyone verify you own the URL (place relay fingerprints at `https://your-domain/.well-known/tor-relay/rsa-fingerprint.txt`)
+- Helps detect impersonation - operators can't fake verified URLs
+- Improves trust and visibility in the Tor network
+
+**Generate your string:** Use the [CIISS Generator](https://torcontactinfogenerator.netlify.app/) - fill in the fields and copy the result into your `ContactInfo` line or `TOR_CONTACT_INFO` env var.
+
+> 📖 **Full spec:** [nusenu.github.io/ContactInfo-Information-Sharing-Specification](https://nusenu.github.io/ContactInfo-Information-Sharing-Specification/)
+
 ### What's the difference between TOR_* and official bridge naming?

 Both work identically - we support two naming conventions for compatibility:
@@ -97,7 +128,7 @@ Both work identically - we support two naming conventions for compatibility:
 ```bash
 TOR_RELAY_MODE=bridge
 TOR_NICKNAME=MyBridge
-TOR_CONTACT_INFO=admin@example.com
+TOR_CONTACT_INFO=email:admin[]example.com ciissversion:2
 TOR_ORPORT=9001
 TOR_OBFS4_PORT=9002
 ```
@@ -195,6 +226,8 @@ sudo ufw allow 9002/tcp
 | First statistics | 24-48 hours | Bandwidth graphs appear |
 | Guard flag | 8+ days | Relay trusted for entry connections |

+> 🗳️ **Directory Authority Voting:** Tor has **9 Directory Authorities** that vote hourly on relay flags. A relay only earns a flag (Guard, Stable, Fast, HSDir, etc.) when **at least 5 of 9** authorities agree in the consensus. This is why flags aren't instant - your relay must prove itself to a majority of independent authorities.
+
 **Troubleshooting:**
 1. **Check bootstrap:** `docker exec tor-relay status`
   - Must show "Bootstrapped 100%"
@@ -247,7 +280,7 @@ docker logs tor-bridge | grep "bridge line"
 **Factors affecting bandwidth:**
 1. **Relay age** - New relays are untrusted
 2. **Uptime percentage** - Must maintain 99%+ for Guard flag
-3. **Relay flags** - Guard, Fast, Stable flags increase usage
+3. **Relay flags** - Guard, Fast, Stable flags increase usage (assigned by directory authority consensus - at least 5 of 9 authorities must vote for each flag)
 4. **Configured bandwidth** - Tor won't exceed your limits
 5. **Exit policy** - Exit relays typically get more traffic

@@ -426,7 +459,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.6
+# Should show: Version: 1.1.7

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

 ---

-**Last Updated:** Feburary 2026 (v1.1.6)
+**Last Updated:** March 2026 (v1.1.7)
 **Maintained by:** [@r3bo0tbx1](https://github.com/r3bo0tbx1)
--- a/docs/MIGRATION-V1.1.X.md
+++ b/docs/MIGRATION-V1.1.X.md
@@ -436,7 +436,7 @@ docker rm obfs4-bridge
 - [ ] Fingerprint matches backup
 - [ ] Container starts without errors
 - [ ] Bootstrap reaches 100%
- [ ] Diagnostic tools work (status, health, fingerprint)
+- [ ] Diagnostic tools work (status, health, fingerprint, gen-family)
 - [ ] Monitoring updated (if applicable)

 ---
--- a/docs/MIGRATION.md
+++ b/docs/MIGRATION.md
@@ -178,6 +178,7 @@ After any migration:
  - `docker exec <container> status`
  - `docker exec <container> health`
  - `docker exec <container> fingerprint`
+  - `docker exec <container> gen-family --show` (if using Happy Family)
 - [ ] Tor Metrics shows relay (after 1-2 hours)

 ---
--- a/docs/MULTI-MODE.md
+++ b/docs/MULTI-MODE.md
@@ -49,7 +49,7 @@ The Tor Guard Relay container now supports **three relay modes**:
 **Best for:**
 - Operators who want to contribute without legal complexity
 - Stable, high-bandwidth connections
- Long-term operation (8+ days to earn Guard flag)
+- Long-term operation (8+ days to earn Guard flag - requires at least 5 of 9 directory authorities to vote in consensus)

 **Requirements:**
 - Public IP with ports 9001, 9030 accessible
@@ -491,7 +491,7 @@ nc -zv <your-ip> 9001
 **Normal for:**
 - New relays (2-8 weeks to build reputation)
 - Bridges (intentionally low visibility)
- Guards without Guard flag (need 8+ days uptime)
+- Guards without Guard flag (need 8+ days uptime - at least 5 of 9 directory authorities must agree in consensus)

 **Check:**
 1. Verify relay is reachable: `docker exec <container> status`
--- a/docs/TOOLS.md
+++ b/docs/TOOLS.md
@@ -1,6 +1,6 @@
 # 🛠️ Tools Reference Guide

-**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.
+**Tor Guard Relay 1.1.3** includes 6 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.

 ---

@@ -13,6 +13,7 @@
 | **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 |
+| gen-family | Generate/view Happy Family key | Text | Tor 0.4.9+ only |

 ---

@@ -224,6 +225,53 @@ When to use:

 ---

+### `gen-family`
+
+**Purpose:** Generate or view a Tor Happy Family key (Tor 0.4.9+). This replaces the old `MyFamily` fingerprint-exchange workflow with a single shared `FamilyId`.
+
+**Usage:**
+```bash
+# Generate a new family key
+docker exec tor-relay gen-family MyRelays
+
+# View existing family key and FamilyId
+docker exec tor-relay gen-family --show
+
+# Show help
+docker exec tor-relay gen-family --help
+```
+
+**Output Example (generate):**
+```
+════════════════════════════════════════════════════════════
+Tor Happy Family Key Generator (Tor 0.4.9+)
+════════════════════════════════════════════════════════════
+
+✓ Generated family key: MyRelays
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Your FamilyId (add to torrc or TOR_FAMILY_ID env var):
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+   FamilyId wweKJrJxUDs1EdtFFHCDtvVgTKftOC/crUl1mYJv830
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+💡 Copy the secret key file to all relays in this family.
+   Then set TOR_FAMILY_ID in each relay's environment.
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**Exit Codes:**
+- `0` - Key generated or displayed successfully
+- `1` - Error (key already exists, Tor not found, etc.)
+
+**When to use:**
+- When linking multiple relays (guard, exit, middle) into a family
+- Run once to generate, then copy the key file to all family members
+- Replaces the old manual fingerprint exchange (`MyFamily`)
+
+---
+
 ## 🚀 Common Workflows

 ### 1. Quick Health Check
@@ -270,7 +318,21 @@ docker exec tor-bridge bridge-line
 # Share ONLY with trusted users, NOT publicly
 ```

-### 5. Automated Monitoring
+### 5. Set Up Happy Family (Tor 0.4.9+)
+```bash
+# Generate a family key on one relay
+docker exec tor-relay gen-family MyRelays
+
+# Copy the key file to all other family members
+docker cp tor-relay:/var/lib/tor/keys/MyRelays.secret_family_key ./
+docker cp ./MyRelays.secret_family_key tor-relay-2:/var/lib/tor/keys/
+docker exec -u 0 tor-relay-2 chown 100:101 /var/lib/tor/keys/MyRelays.secret_family_key
+
+# Set TOR_FAMILY_ID on each relay and restart
+# (use the FamilyId from gen-family --show output)
+```
+
+### 6. Automated Monitoring
 ```bash
 # Simple monitoring script
 while true; do
@@ -288,7 +350,7 @@ while true; do
 done
 ```

-### 6. Check Logs
+### 7. Check Logs
 ```bash
 # View recent logs
 docker logs --tail 100 tor-relay
@@ -322,7 +384,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, gen-auth
+# Should show: status, health, fingerprint, bridge-line, gen-auth, gen-family

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

 ## ❓ FAQ

-**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: Why only 6 tools instead of 9?**
+
+A: The v1.1.3 build remains ultra-light (~16.8 MB). These 6 tools cover all essential operations including health checks, identity, authentication setup, and Happy Family key management.

 **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! 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:** December 2025 | **Version:** 1.1.3
+**Last Updated:** March 2026 | **Version:** 1.1.7
--- a/docs/TROUBLESHOOTING-BRIDGE-MIGRATION.md
+++ b/docs/TROUBLESHOOTING-BRIDGE-MIGRATION.md
@@ -501,7 +501,7 @@ After migration:
 - ✨ Official Tor Project ENV variable compatibility
 - ✨ Bootstrap progress logs in terminal
 - ✨ Enhanced emoji logging (v1.1.0 style)
- ✨ 5 diagnostic tools (status, health, fingerprint, bridge-line, gen-auth)
+- ✨ 6 diagnostic tools (status, health, fingerprint, bridge-line, gen-auth, gen-family)
 - ✨ Auto-detection of bridge mode from PT_PORT
 - ✨ OBFS4V_* variable processing