WhiteDNS 3X-UI Wizard

Telegram: @whitedns

WhiteDNS is a Cloudflare-first provisioning wizard for setting up a managed 3x-ui/Xray VPN stack on a VPS. It runs locally, connects to the VPS over SSH, manages Cloudflare DNS and certificates, installs or repairs a Docker-based 3x-ui stack, and generates copyable client import strings.

The wizard focuses on a practical default setup:

• Cloudflare-proxied WebSocket TLS profiles.
• DNS-only direct profiles for protocols Cloudflare proxy cannot handle.
• Server-side Tor exit variants users can import separately.
• A managed 3x-ui Docker stack with PostgreSQL.
• Encrypted local project secrets and repeatable reset/repair flows.

Quick Start

1. Build the binary

go build -o whitedns ./cmd/whitedns

2. Run the interactive wizard

./whitedns

The root command opens the menu. Select:

0) Init setup

The wizard will ask for:

• Cloudflare account ID.
• Cloudflare API token.
• Domain name.
• VPS IPv4 address.
• SSH host, user, key/passphrase, or password.

3. Cloudflare token permissions

Create an Account API token in Cloudflare:

1. Go to Manage Account > Account API Tokens > Create Token.
2. Choose the Edit zone DNS template.

3. Scope it to the owning Cloudflare zone when possible. For subdomain projects such as team.example.com, this may be the parent zone example.com. Use all domains only when needed.
4. Keep DNS: Read + Edit.
5. In DNS & Zones, add Zone: Read and Zone Settings: Edit.

6. In Cache & Performance, add Zone SSL & Certificates: Edit.

The final required permissions are:

DNS & Zones / DNS: Read + Edit
DNS & Zones / Zone: Read
DNS & Zones / Zone Settings: Edit
Cache & Performance / Zone SSL & Certificates: Edit

Cloudflare API docs may call Edit permissions Write. WhiteDNS uses the account ID you enter for:

GET /client/v4/accounts/<account-id>/tokens/verify

Troubleshooting:

4. What the init flow does

The setup flow:

• Validates the Cloudflare token.
• Detects the Cloudflare zone.
• Creates or updates DNS records.
• Sets Cloudflare SSL mode to strict.
• Creates a Cloudflare Origin CA certificate for proxied profiles.
• Issues a public ACME wildcard certificate for DNS-only TLS profiles.
• Installs or repairs managed Docker 3x-ui and PostgreSQL.
• Adds a private Tor sidecar for Tor-profile outbound routing.
• Replaces only WhiteDNS-managed inbounds/outbounds after confirmation.
• Prints and saves client import strings.

DNS Records

WhiteDNS creates these A records for the selected domain. Replace <domain> and <vps-ip> with your real values.

ACME also creates temporary TXT records during public certificate issuance:

_acme-challenge.<domain>

The app requests a wildcard certificate for *.<domain>, so one challenge covers the DNS-only TLS hostnames.

If the local machine cannot complete the TLS connection to Let's Encrypt, WhiteDNS falls back to issuing the same DNS-01 certificate from the VPS over SSH. The fallback uses an installed lego binary when available, or a short-lived goacme/lego:v4.24.0 Docker container.

Generated Client Profiles

WhiteDNS creates import strings for:

Reality profiles currently use either apple.com or docker.com as the saved SNI and Reality target. Normal TLS profiles keep their own hostnames as SNI so public certificate validation continues to work.

Tor profiles mean:

client -> VPS -> Tor -> destination

The VPS still sees the client IP. Destination sites see the Tor exit IP. The Tor SOCKS service is internal to Docker and is not published as a public proxy.

Tor is TCP-oriented. UDP destination traffic from Tor Hysteria2 or Tor Shadowsocks profiles may fail rather than route through Tor.

Menu Items

Run:

./whitedns

The interactive menu provides:

Navigation:

• esc or b returns from submenus to the main menu.
• q exits.
• Destructive actions require typed confirmation.

CLI Commands

The interactive menu is the preferred workflow, but the CLI also exposes subcommands:

./whitedns cloudflare check --domain example.com
./whitedns cloudflare apply --domain example.com --ip 1.2.3.4
./whitedns plan show example.com
./whitedns xui check --domain example.com --ssh-host 1.2.3.4
./whitedns xui plan --domain example.com --ssh-host 1.2.3.4
./whitedns xui apply --domain example.com --ssh-host 1.2.3.4 --yes

Useful XUI flags:

--ssh-user root
--ssh-port 22
--ssh-key ~/.ssh/id_ed25519
--ssh-key-passphrase <passphrase>
--ssh-password <password>
--panel-username <username>
--panel-password <password>
--panel-base-path /tp-example/
--acme-email admin@example.com

Output Files

Local project files are written under:

~/.wdns-wizard/projects/<domain>/

Important files:

config.yaml
secrets.enc.yaml
cloudflare-state.json
xui-state.json
client-links.yaml
origin/origin.pem
origin/origin.key
certs/public.pem
certs/public.key
plans/dns-plan.yaml
plans/protocol-plan.yaml
plans/xui-plan.yaml
logs/provision-*.log
logs/xui-provision-*.log

Remote managed files are kept under:

/var/lib/whitedns/3x-ui/

Older managed installs under /opt/wdns-wizard/3x-ui/ are migrated to this path automatically when possible.

Privacy Policy

WhiteDNS is a local CLI/TUI tool. It does not include telemetry, analytics, tracking pixels, remote reporting, or a WhiteDNS-hosted backend.

What WhiteDNS stores locally

WhiteDNS stores project data on the machine where you run the tool:

~/.wdns-wizard/projects/<domain>/

This can include:

• Domain, VPS IP, DNS/protocol plans, state files, logs, and generated client import strings.
• Cloudflare Origin CA certificate material.
• Public ACME certificate material.
• Encrypted secrets in secrets.enc.yaml.

Secrets are encrypted locally using a key stored under the WhiteDNS root or provided through:

WDNS_WIZARD_SECRETS_KEY

The 3x-ui panel password, Cloudflare token, generated client IDs/passwords, and protocol secrets are not intentionally written in plaintext logs. The Origin CA private key and public ACME private key are written as key files because the server needs them for TLS.

What WhiteDNS sends to third parties

WhiteDNS communicates only with services needed for provisioning:

• Cloudflare API: token validation, zone lookup, DNS records, SSL mode, Origin CA, and ACME DNS-01 TXT records.
• Let's Encrypt ACME: public certificate issuance for *.<domain>.
• Your VPS over SSH: Docker installation, 3x-ui setup, certificates, inbounds, outbounds, diagnostics, backups, and support bundles.
• Docker/GitHub package endpoints when installing Docker Compose plugin fallback binaries.

When local ACME connectivity fails, WhiteDNS temporarily uploads the Cloudflare token to the VPS as a 0600 environment file so the VPS can complete the DNS-01 challenge. The temporary file and remote ACME working directory are removed after the attempt.

WhiteDNS does not sell, share, or upload your project data to a WhiteDNS service.

User responsibility

You control the Cloudflare account, VPS, generated clients, and local project files. Anyone with access to your local machine, project directory, VPS, 3x-ui dashboard, or client import strings may be able to access sensitive configuration.

Keep these private:

• Cloudflare API token and account ID.
• ~/.wdns-wizard project directory.
• WDNS_WIZARD_SECRETS_KEY or .secrets.key.
• 3x-ui dashboard credentials.
• Client import strings and private keys.

Build And Develop

Requirements

• Go 1.24.2 or newer compatible toolchain.
• SSH access to the VPS for live provisioning.
• Docker-capable Linux VPS for the managed 3x-ui stack. If Docker exists but the Compose plugin is missing, WhiteDNS tries distro packages first, then falls back to the official Docker Compose v2 CLI plugin binary.
• Cloudflare zone and API token.

Run tests

go test ./...

When using a local project cache:

env GOCACHE="$PWD/.cache/go-build" go test ./...

Build

go build -o whitedns ./cmd/whitedns

Release builds

GitHub Release builds are handled by:

.github/workflows/release.yml
scripts/build-release.sh
scripts/release-targets.txt

When a GitHub release is published, the workflow runs tests, builds archives for every target in scripts/release-targets.txt, writes SHA-256 checksums, stores the files as a workflow artifact, and uploads the same files to the GitHub release.

Run the release builder locally with:

VERSION=v0.1.0 ./scripts/build-release.sh

Artifacts are written to:

dist/

The default targets include Linux, macOS, Windows, FreeBSD, OpenBSD, NetBSD, and Termux-compatible Android ARM64. The Termux build uses Go's android target and is named like:

whitedns_<version>_termux-android-arm64.tar.gz

Format

find cmd internal pkg -name '*.go' -print0 | xargs -0 gofmt -w

Development notes

• Keep local state paths stable: ~/.wdns-wizard/....
• Keep remote state paths stable: /var/lib/whitedns/3x-ui/....
• Use the interactive menu for end-to-end testing.
• Use xui plan before xui apply when testing conflict detection.
• reset preserves local secrets and client identities.
• delete removes only WhiteDNS-managed remote resources; local project files are kept.