WhiteDNS Wizard: provisioning a proxied VPN stack over SSH

Thirteen records, and only two are proxied

The DNS design is the clearest statement of the project's priorities, and it is a deliberate split rather than a uniform pattern. Thirteen address records are created for the chosen domain. Exactly two are proxied through Cloudflare, serving WebSocket-over-TLS traffic on the standard and the alternative port. The other eleven are DNS-only, and they exist for two separate reasons. Some carry protocols that a Cloudflare proxy simply cannot pass, so exposing them through the proxy would break them. The rest are the Tor-routed variants of the same profiles. The practical consequence is that most of your deployment does not sit behind Cloudflare at all, which matters for anyone reasoning about what Cloudflare can see, and also means the proxy's benefit is limited to the subset of traffic it can actually carry. A single extra hostname is dedicated to the management dashboard and is DNS-only for the same reason.

Two certificate paths, because the local path often fails

Certificate handling is where this tool shows its experience, because it solves for a failure that is extremely common and badly diagnosed. There are two certificate types. Proxied profiles get an Origin CA certificate, which is what Cloudflare expects when it terminates the connection for a proxied hostname. DNS-only profiles that need ordinary TLS get a public certificate from a public authority, and the tool requests a wildcard covering the whole domain so that a single challenge record satisfies every hostname that needs one. The fallback is the interesting part. If the machine running the wizard cannot complete a TLS connection to the public authority, the tool retries the issuance from the VPS itself over SSH, using a locally installed certificate client if one is present or otherwise spinning up a short-lived container for that purpose. So the failure mode that strands most people, a network that blocks the certificate authority, has a documented path through it.

The permission list maps one-to-one onto the error table

The documentation pairs a required-permission list with a troubleshooting table, and the correspondence is exact enough to be useful rather than decorative. Four permissions are required: reading and editing DNS records, reading the zone, editing zone settings, and editing the SSL and certificates setting. The troubleshooting table then names the symptom each missing permission produces. Zone lookup failures point at missing zone read or a token scoped to the wrong domain. Failures setting strict mode point at missing zone settings edit. Failures creating the origin certificate point at the missing certificate permission. Token validation failures are called out separately as the wrong token, the wrong account identifier, an expired or disabled token, or simply an incompatible token type. Two details are worth noting. Cloudflare's own documentation sometimes labels the edit permissions as write, which sends people looking for the wrong name. And the account identifier you are asked for is used to call the token verification endpoint directly, which is why a mismatched pair fails as a validation error rather than something confusing.

Nameserver delegation is the one failure DNS cannot fix

One row in that troubleshooting table deserves to be read twice, because it names a failure that no amount of work inside the tool will resolve. If the domain's nameservers at the registrar do not point at Cloudflare, nothing you do in the DNS records table will help. The documentation is explicit that this is not fixed by deleting rows or adding rows in Cloudflare's own interface, which is exactly the wrong thing someone will try first. This is the single most common reason a Cloudflare-based deployment appears broken while every visible configuration looks correct, and it lives entirely outside the tool's reach, at the registrar. It is also the reason the wizard asks for a domain name rather than discovering one, and the reason scoping the token to the owning zone matters, since a subdomain project still resolves against whatever zone actually holds the delegation.

Tor is server-side egress, not a published proxy

The Tor variants are easy to misread, so the documentation draws the path explicitly:

client -> VPS -> Tor -> destination

The important property is what each party sees. The server still sees the client's address, because Tor is used for outbound traffic only and the inbound connection terminates on the VPS as normal. The destination sees the Tor exit address rather than the client's. And the proxy service inside the container is deliberately not published, so this is not an open relay sitting on your port for anyone to use. That design is the honest one for this use case: it hides the client's address from the destination without pretending to hide the client from the operator of the machine. The documented limitation follows from the transport. Tor is TCP-oriented, so UDP destination traffic on the Tor-routed Hysteria2 and Shadowsocks profiles may fail instead of routing, which is a real caveat rather than a theoretical one given how commonly UDP paths break.

Reality profiles borrow someone else's name as SNI

There is a detail in the profile table that explains a lot about how the Reality profiles work. They currently use either a well-known commercial domain or a well-known container registry domain as the saved server name and Reality target. That is the point of the protocol, which is designed to blend into ordinary encrypted traffic, and it is also why those profiles are listed separately from the ordinary TLS ones. The comparison with the rest of the table is the instructive part. Normal TLS profiles keep their own hostnames as the server name, because public certificate validation depends on it. The Reality profiles cannot do that, since they are not presenting your certificate at all. So two different naming strategies coexist in one configuration, and the reason a Reality profile will not validate like the others is by design rather than a misconfiguration.

It only replaces the rules it manages

The initial setup sequence is long and ordered, and one step in it carries the safety property that matters most. After validating the token and detecting the zone, the flow creates or updates the DNS records, sets the zone's SSL mode to strict, creates the origin certificate for proxied profiles, issues the wildcard certificate for the DNS-only profiles, installs or repairs the containerised management stack and its database, adds the Tor sidecar, and finally replaces the inbound and outbound rules. That last step is qualified in the documentation: it replaces only the rules the tool manages, and only after confirmation. In a system where a panel may already hold hand-made entries someone depends on, that is the difference between a provisioning tool and a destructive one. The code structure supports the same story, with a command entry point, internal and package directories, and a terminal interface built on a well-known Go component set, alongside two different major versions of the Cloudflare client library present in the dependency tree.

The whole tool is one binary with a menu

There is no installer, no service, and nothing to deploy, which is unusual for a tool that ends up managing a server. Building it produces a single executable:

go build -o whitedns ./cmd/whitedns

Running that binary with no arguments opens the interactive menu, where the initial setup is the first entry. From there the wizard asks for five things: a Cloudflare account identifier, a Cloudflare API token, the domain name, the IPv4 address of the server, and SSH access details, which can be a host and user with a key and its passphrase, or a password instead. The dependency list explains the shape of the program. A terminal interface component set provides the menu, a command framework provides the subcommands, and a Cloudflare client, an ACME client, and a DNS library do the network work, on a pinned recent Go release. The consequence for the reader is that everything this tool knows how to do has to be discovered by exploring the menu rather than by reading a subcommand list, which makes the menu itself the primary documentation.

Editorial conclusion

WhiteDNS Wizard suits someone who has a VPS and a Cloudflare zone and wants the boring parts of a working VPN deployment done correctly rather than by hand, since the DNS, certificate, and client-import details are the parts people get wrong. It is a poor fit if you want a fully managed service, because the whole tool presumes you keep the machine, and a poor fit if you are on a network that cannot reach certificate authorities, since the documented fallback exists precisely because that is common. Before running the initial setup, confirm your domain's nameservers already point at Cloudflare, because that one problem cannot be fixed from inside the tool, and read the permissions list so the token is created correctly the first time.

Frequently asked questions

Official sources

1. Issues
2. README
3. Releases
4. WhiteDNS/WhiteDNS-Wizard on GitHub