Skip to main content
A proxied record works like Cloudflare’s orange cloud. DNS answers its name with the address of a proxy, and the proxy sends the visit on to your servers, which visitors never see. A record can go through several proxies. DNS then answers with all of their addresses, so visitors spread over them and one proxy going down doesn’t take the name with it. What each proxy serves is set up in DNZ the way Traefik sees it: routers pick hostnames from DNZ’s zones and send them to a service (your servers), through middlewares. See Routers, services and middlewares.
Proxying is off by default. Setting it up, and everything on the Proxy page, needs a superadmin.

​
Three kinds of proxy

Each proxy is run by one of three kinds, picked when you add it. All of them serve the same routers, services and middlewares, set up in DNZ. Pick Traefik when you already run it, or want its providers (Docker, Kubernetes) to feed DNS. Pick dnz-proxy when you want DNZ to run the whole path, from certificates to analytics. Pick Caddy when you’d rather run Caddy and let it get its own certificates. Kinds can be mixed. A record can go through a Traefik and a dnz-proxy proxy at once, and DNS answers with all of their addresses.

​
Turning proxying on

Settings → Proxy has one switch: proxying on or off. Below it, Proxies lists the proxies. Add proxy first asks what runs the proxy: Traefik, dnz-proxy or Caddy. Then it asks for the name and the addresses visitors reach it at, and shows that kind’s setup, ready to copy. A proxy’s kind can’t be changed once it is added. The Proxy page shows up in the menu, next to DNS, while proxying is on and a proxy is listed (detected ones included). Below the proxies, Caddy sites in DNS keeps DNS records for the sites in a Caddyfile, without proxying through that Caddy. See Caddy sites in DNS. Division owners (with integrations.manage) can open Settings → Proxy and see only that section. Everything else there needs a superadmin.

​
From the environment

You can also turn proxying on or off when DNZ starts. The switch in the UI is then read-only. Proxies of every kind are still managed in the UI.
The older values traefik and dnz still mean on. See Configuration for where DNZ reads its settings from.

​
Upgrading from the backend picker

Earlier versions had one backend (Off, Traefik or dnz-proxy) that ran every proxy. When you upgrade:
  • every existing proxy gets the kind of the backend that was in use: dnz if it was dnz-proxy, else traefik;
  • with proxying off, proxies that have dnz-proxy nodes become dnz;
  • the switch stays on if a backend was on.

​
Using it

1

Turn on proxying

Under Settings → Proxy, turn on Proxying.
2

Add a proxy

Add proxy, pick its kind and follow its setup: connect a Traefik (Connecting Traefik) or a Caddy (Connecting Caddy), or run dnz-proxy nodes (dnz-proxy). The proxy then shows up on the Proxy page.
3

Add a route

On the proxy’s page, Add route does it in one step. See Adding a route below.
4

Proxy the record

If the route didn’t already do it, edit the record in its zone and pick the proxies. See Proxying a record from the zone.

​
Adding a route

Add route takes a hostname and its upstreams. You choose HTTPS (with a redirect from http://) and middlewares. DNZ then:
  • adds the service and the router,
  • adds a second router on the HTTP entry point with a Redirect to HTTPS middleware, when you chose HTTPS with a redirect,
  • proxies the name’s DNS record, and makes an A record pointing at the proxy when there is none.
The Services, Middlewares and Routers tabs are there to fine-tune afterwards. As you type the hostname, the field offers:
  • names that already have A, AAAA or CNAME records, tagged with their types;
  • under each of DNZ’s zones, the name you are typing, tagged new: a new DNS record is added for it;
  • a name outside every zone is tagged no zone, and one the proxy already routes has router.
The routers go on the proxy’s entry points on port 80 and 443. Under dnz-proxy these are its own entry points. Under Traefik they are the ones its API lists (when the proxy has Traefik API set), else web and websecure. Under Caddy they are web (:80) and websecure (:443). The dialog says where they came from. A record without a router links straight to this dialog, with its name filled in.
Proxy → open the proxy → Add route.

​
Proxying a record from the zone

In the zone, edit the record and pick the proxies. With only one proxy this is a switch. With several, tick one or more of them; none means DNS only. A proxy can only be picked when one of its routers has the record’s name. Otherwise it is greyed out and the form points to Proxy. The form shows the whole path: what the visitor opens, the proxies DNS points to (with every address in the answer), and each proxy’s router and service that take it from there.
DNS → Zones → the zone → edit the record → pick the proxies.
While a record is proxied, its own value is not used: the router’s service decides where visits go. The value is used again as soon as the record goes back to DNS only, or proxying is turned off.

​
Several proxies per name

Adding a route for the same hostname on a second proxy adds that proxy to the name’s records. A name is spread over more proxies just by routing it there.
While proxying is on, the request flow on the Overview gets a Proxy tab: visitors, each proxy, its routers and middlewares, services and upstreams.

​
What DNS answers

While proxying is on, every name with proxied records answers A and AAAA queries with the addresses of every proxy its records go through, whatever their kinds. One proxy gives its address, two give both, and so on. An address two proxies share is answered once.
  • A Traefik or Caddy proxy gives its own addresses.
  • A dnz-proxy proxy gives the public addresses of its healthy nodes, or its own addresses while it has none.
  • The record’s own value is never handed out, and a proxied CNAME is not answered as a CNAME.
  • Other record types at the name (TXT, MX, and so on) are answered as usual.
  • The answer uses the lowest TTL of the name’s proxied records and, with dnz-proxy, the lowest DNS TTL cap among its proxies.
While proxying is off, proxied records answer with their own value. Every Traefik gets an empty route list and every Caddy a configuration with no sites, so they drop the routes they had. The proxy choice is kept for when proxying comes back on. Changing proxying, or a proxy’s addresses, bumps the SOA serial of the zones involved, so secondaries pick up the new answers. Zone transfers carry the proxy’s addresses, not the origins.

​
Rules

  • Only A, AAAA and CNAME records can be proxied.
  • All A, AAAA and CNAME records of one name go through the same proxies, or none. Otherwise DNS would hand out the origin next to a proxy, or answer differently per record type. Change them together: the record form does it per record, dnz record edit … --proxy and the bulk API’s set_proxies move a name’s records at once.
  • Records in a view can’t be proxied. A proxy serves every client the same.
  • A record can only be proxied through approved proxies that each have a router for its name.
  • Router hostnames must be in one of DNZ’s local zones.
  • Wildcards (*.apps.example.com) work. They match one label, and exact names win over them unless you set priorities.
  • Automatic PTR skips proxied names.
  • A router that proxied records rely on can’t be deleted, turned off, or have that hostname taken out.
  • A proxy can’t be deleted while records use it. Take it off them first; they may keep their other proxies.
Objects that other objects use are protected too. See What can’t be deleted.

​
Next steps

Connecting Traefik

Point Traefik’s HTTP provider at DNZ.

Connecting Caddy

Let DNZ configure a Caddy through its config loader.

dnz-proxy

Run DNZ’s own proxy on any number of servers.

Routers, services and middlewares

What a proxy serves, and how to check it works.

Proxy API

Proxies, routes and records over HTTP.