ansible-proxy-chain/openspec/changes/archive/2026-04-22-auto-generate-surge-config/design.md

Context

Currently SS port (8388), Trojan port (443), and passwords are manually configured in group_vars and Ansible Vault. The Surge client config at docs/surge-client.conf is a static reference with placeholders users must replace manually. This change automates credential generation and produces a ready-to-use Surge config.

Goals / Non-Goals

Goals:

• Auto-generate random ports (within high-port range) and strong passwords on first deploy
• Persist generated credentials so subsequent playbook runs don't regenerate them
• Render a complete Surge client config with actual parameters after deployment
• Keep manual override possible for users who prefer to set their own values

Non-Goals:

• Key rotation automation (out of scope)
• Distributing the generated config to client devices

Decisions

1. Credential generation: Ansible password lookup with file persistence

Use Ansible's lookup('password', ...) to generate credentials. This generates a random value on first run and persists it to a file on the Ansible controller, so subsequent runs reuse the same value.

ss_password: "{{ lookup('password', 'credentials/ss_password length=32 chars=ascii_letters,digits') }}"
ss_port: "{{ lookup('password', 'credentials/ss_port chars=digits length=5') | int % 40000 + 10000 }}"

Credentials stored in credentials/ directory (gitignored). Users can still override by setting variables in group_vars or via --extra-vars.

Why over Ansible Vault with manual entry: Zero-touch setup. New users don't need to manually create passwords or encrypt vault files.

2. Port ranges

• SS port: random in 10000–49999 range
• Trojan port: fixed at 443 (required for TLS camouflage — Trojan must listen on 443 to look like HTTPS)

Trojan port stays 443 because changing it defeats the purpose of HTTPS camouflage.

3. Surge config generation: local Jinja2 template rendered by Ansible

Create a new playbook task that runs on localhost (Ansible controller) after server deployment. It renders templates/surge-client.conf.j2 using the actual deployed variables (relay IP, landing domain, ports, passwords) and writes to output/surge-client.conf.

The old static docs/surge-client.conf is removed. The template preserves the same rule structure (Sukka's rulesets, China direct, etc.).

4. Credential directory gitignored

Add credentials/ and output/ to .gitignore to prevent secrets and generated configs from being committed.

Risks / Trade-offs

• [Credential loss] → If credentials/ directory is deleted, new credentials are generated and servers must be re-provisioned. Mitigation: document backup instructions in README.
• [Trojan port fixed at 443] → Cannot randomize without breaking HTTPS camouflage. This is by design.
• [Controller-local files] → Credentials and output depend on the Ansible controller's filesystem. Mitigation: users can back up the credentials/ directory.