From 2d0032042b60071123486eda28bb6de38cc387a6 Mon Sep 17 00:00:00 2001 From: findias Date: Mon, 23 Mar 2026 09:14:30 +0300 Subject: [PATCH] fix(sing-box-playbook): enhance DNS configuration and obfuscation handling - Introduce `singbox_dns_strategy` and `singbox_dns_final` for improved DNS format compliance - Update `config.json.j2` to utilize new variables instead of deprecated formats - Conditional rendering of `obfs` block based on `obfs_enabled` and `obfs_password` settings - Add new role files in tasks/*.yml and defaults/secrets.yml.example --- README.md | 191 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 191 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..4e852e0 --- /dev/null +++ b/README.md @@ -0,0 +1,191 @@ +# Raven Server Install + +Ansible role that installs and configures [Xray-core](https://github.com/XTLS/Xray-core) with [Raven-subscribe](https://github.com/alchemylink/raven-subscribe) on a VPS. + +**What you get:** +- Xray with VLESS + XTLS-Reality and XHTTP inbounds +- Optional VLESS Encryption (post-quantum, mlkem768x25519plus) +- Raven-subscribe — subscription server for client config distribution +- Systemd services with auto-restart and config validation before reload +- Ad/tracker blocking via geosite routing rules +- BBR congestion control and kernel tuning via `srv_prepare` role + +## Requirements + +- Ansible >= 2.14 (ansible-core) +- Target: Debian/Ubuntu VPS with systemd +- `ansible-vault` for secrets management + +## Quick Start + +### 1. Inventory + +Edit `roles/hosts.yml` and point `vm_my_srv` at your server. + +### 2. Secrets + +Create and encrypt the secrets file: + +```bash +cp roles/xray/defaults/secrets.yml.example roles/xray/defaults/secrets.yml +# Fill in the values (see Secrets section below) +ansible-vault encrypt roles/xray/defaults/secrets.yml --vault-password-file vault_password.txt +``` + +To edit later: + +```bash +ansible-vault edit roles/xray/defaults/secrets.yml --vault-password-file vault_password.txt +``` + +### 3. Generate Reality keys + +```bash +# On any machine with Xray installed: +xray x25519 +# Output: PrivateKey + PublicKey — put both into secrets.yml +``` + +### 4. Deploy + +```bash +ansible-playbook roles/role_xray.yml -i roles/hosts.yml --vault-password-file vault_password.txt +``` + +Deploy only a specific component using tags: + +```bash +# Update subscription server config only +ansible-playbook roles/role_xray.yml -i roles/hosts.yml --vault-password-file vault_password.txt --tags raven_subscribe + +# Update inbound configs only +ansible-playbook roles/role_xray.yml -i roles/hosts.yml --vault-password-file vault_password.txt --tags xray_inbounds +``` + +## Secrets (`roles/xray/defaults/secrets.yml`) + +Ansible-vault encrypted. Required fields: + +```yaml +# Reality keys — generate with: xray x25519 +xray_reality: + private_key: "..." + public_key: "..." + spiderX: "/" + short_id: + - "a1b2c3d4e5f67890" # 8-byte hex — generate: openssl rand -hex 8 + +# VLESS users +xray_users: + - id: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" # UUID — generate: uuidgen + flow: "xtls-rprx-vision" + email: "user@example.com" + +# Raven-subscribe +raven_subscribe_admin_token: "" # openssl rand -hex 32 +raven_subscribe_server_host: "your-server.com" +raven_subscribe_base_url: "http://your-server.com:8080" +``` + +## Configuration + +Key variables in `roles/xray/defaults/main.yml`: + +| Variable | Default | Description | +|----------|---------|-------------| +| `xray_vless_port` | `443` | VLESS + Reality listen port | +| `xray_reality_dest` | `askubuntu.com:443` | Reality camouflage destination | +| `xray_reality_server_names` | `["askubuntu.com"]` | SNI names for Reality | +| `xray_xhttp.port` | `2053` | XHTTP inbound port | +| `xray_dns_servers` | `tcp+local://8.8.8.8, ...` | DNS servers (no DoH — see note below) | +| `xray_vless_decryption` | `"none"` | VLESS Encryption (optional, see below) | +| `raven_subscribe_listen_addr` | `:8080` | Raven-subscribe listen address | +| `raven_subscribe_sync_interval_seconds` | `60` | User sync interval | + +> **DNS note:** Do not use `https://` (DoH) in `xray_dns_servers` — DoH queries route through the proxy and fail. Use `tcp+local://` instead. + +## Architecture + +``` +roles/role_xray.yml + └── srv_prepare — system packages, BBR, sysctl tuning + └── xray — Xray + Raven-subscribe + ├── validate.yml (always) — pre-flight assertions + ├── install.yml (xray_install) — download Xray binary + ├── base.yml (xray_base) — log + stats config + ├── api.yml (xray_api) — gRPC API on 127.0.0.1:10085 + ├── inbounds.yml (xray_inbounds) — VLESS+Reality, XHTTP + ├── dns.yml (xray_dns) — DNS config + ├── outbounds.yml (xray_outbounds) — direct + block outbounds + ├── routing.yml (xray_routing) — routing rules + ad blocking + ├── service.yml (xray_service) — systemd unit + ├── grpcurl.yml (grpcurl) — installs grpcurl tool + └── raven_subscribe.yml (raven_subscribe) — subscription server +``` + +Xray config is split across `/etc/xray/config.d/` — files are loaded in numeric order: + +| File | Content | +|------|---------| +| `000-log.json` | Logging | +| `010-stats.json` | Statistics | +| `050-api.json` | gRPC API | +| `100-dns.json` | DNS | +| `200-in-vless-reality.json` | VLESS + XTLS-Reality inbound | +| `210-in-xhttp.json` | VLESS + XHTTP inbound | +| `300-outbounds.json` | Outbounds | +| `400-routing.json` | Routing rules | + +**Handler safety:** `Validate xray` runs before `Restart xray` — invalid config never causes a service restart. + +## VLESS Encryption (optional) + +Xray-core >= 25.x supports post-quantum VLESS Encryption (PR #5067, mlkem768x25519plus). Disabled by default (`"none"`). + +To enable: + +```bash +# Generate key pair on the server +xray vlessenc +# Output: decryption string (private, for server) + encryption string (public, for clients) +``` + +Then in `secrets.yml`: + +```yaml +xray_vless_decryption: "mlkem768x25519plus...." # server private string +xray_vless_client_encryption: "mlkem768x25519plus...." # client public string +``` + +Both must be set together or both left as `"none"`. When enabled, all users are forced to `flow: xtls-rprx-vision`. + +## Testing + +Run the full test suite (Ansible render + `xray -test` via Docker): + +```bash +./tests/run.sh +``` + +Ansible-only (no Docker required): + +```bash +SKIP_XRAY_TEST=1 ./tests/run.sh +``` + +The pipeline: +1. Downloads Xray binary (cached in `tests/.cache/`) +2. Generates test Reality keys +3. Runs `validate.yml` assertions +4. Renders all `templates/conf/*.j2` to `tests/.output/conf.d/` +5. Runs `xray -test -confdir` in Docker + +CI runs automatically via `.github/workflows/xray-config-test.yml`. + +## Related Projects + +- [Raven-subscribe](https://github.com/alchemylink/raven-subscribe) — subscription server (Go) that syncs users via Xray gRPC API and serves client configs + +## License + +[Mozilla Public License 2.0](LICENSE)