How torproject/chutney works
Project Type and Purpose
• Chutney is a command‐line orchestration tool (an open-source Python “framework”)
for configuring, launching, monitoring, and verifying *test* Tor networks.
• It is not a web or mobile app; it’s a CLI tool that drives Tor binaries and test scripts.
File Structure
Top‐level components:
• chutney (CLI entry point)
• lib/chutney/… (core Python modules: Debug, Host, Templating, TorNet, Traffic, Util)
• networks/ (network‐flavor configuration files)
• torrc_templates/ (Tor configuration templates)
• tools/ (bash scripts to bootstrap, test, diagnose)
• scripts/chutney_tests/ (Python test scripts for custom verify logic)
• net/ (runtime working directory where Tor instances and logs live)
• tests/ (shell‐based smoke/unit tests)
README for Insights
• Chutney commands (configure, start, status, verify, etc.) map to core modules.
• External dependencies: Python 3, Tor (tor, tor-gencert).
• Data flow:
– read a network config under networks/
– feed into Templating to produce per‐node torrc files
– spawn Tor processes via TorNet
– run connection tests via Traffic and test scripts
– collect logs, reports in net/
Main Components & Relationships
a. Components:
1. CLI Front End (chutney entry script)
2. Core Engine (lib/chutney/* modules):
– Templating: renders torrc_templates + networks/* → per-node torrc
– TorNet: manages lifecycle (spawn, stop, hup) of Tor processes
– Host & Util: filesystem, environment, process abstractions
– Debug & Traffic: logging, bootstrap monitoring, test traffic generation
3. Network Definitions (networks/)
4. Tor‐configuration Templates (torrc_templates/)
5. Working Directory (net/): generated torrc, data dirs, logs
6. External Binaries: tor, tor-gencert
7. Test Harness:
– Built-in verify logic calls Traffic and Debug
– Custom test scripts (scripts/chutney_tests/) that override/extend verify
8. Orchestrator Scripts (tools/test-network.sh): glue that invokes chutney and CI flags
b. Interactions:
• User invokes chutney <command> or tools/test-network.sh.
• CLI Front End dispatches to Core Engine.
• Core Engine reads network definition and template, writes torrc into net/.
• TorNet module launches multiple Tor processes (tor binary) using those torrcs.
• Tor processes form an isolated test network bound to localhost (v4/v6).
• After launch, Debug & Traffic modules (or custom scripts) connect through the network, measure bootstrap status and bandwidth.
• Results and logs are written under net/.
• Test harness or scripts analyze outputs and report pass/fail.
c. Architectural Patterns and Principles:
– Modular CLI ⇒ clear separation between entry point and core logic
– Plugin-style test scripts: custom behavior via scripts/chutney_tests/
– Templating engine decouples static network definitions from generated configs
– Process manager abstraction around external Tor binaries
– Configuration-as-code: network flavors in networks/ as inputs
d. Key Technologies & Libraries:
– Python 3 standard libs (subprocess, os, tempfile)
– Jinja-style or custom templating (Templating.py)
– Shell scripts (bash) for higher‐level orchestration
– External Tor binaries (tor, tor-gencert)
[ ] Show Templating output (per-node torrc files in net/) feeding into TorNet