Serve a site through Cloudflare Tunnel

A Cloudflare Tunnel connects your server to Cloudflare with an outbound connection that the server opens itself. Visitors reach the site through Cloudflare, and the tunnel carries the traffic to the site on your server. Zefily runs the connector (cloudflared) on the server and creates the tunnel and its DNS records in your Cloudflare account, with an API token you provide. Each site has its own tunnel.

What you need#

• A Cloudflare account that holds the zone of the site's domain, and an API token for it. Add it under Settings → DNS accounts (Cloudflare). The token needs these permissions, as Cloudflare names them in its API documentation:
  • Account → Cloudflare Tunnel → Edit (create, configure and delete the tunnel),
  • Zone → DNS → Edit (create and delete the tunnel's CNAME records),
  • Zone → Zone → Read (find the zone of the domain, which the Cloudflare DNS account already uses).
• A server whose agent supports Cloudflare Tunnel (update the agent first if the site page says it is too old).
• Owner or admin rights on the server.

Turn it on#

Open the site, go to DNS, and find Cloudflare Tunnel:

1. Choose the Cloudflare account that holds the domain.
2. If a name of the site already has an A, AAAA or CNAME record, tick Replace them. The records of those names are deleted and replaced with the tunnel's records. Without the tick, Zefily stops and lists the names.
3. Select Serve through Cloudflare Tunnel.

Zefily then does this, in order:

• creates a remotely managed tunnel in the account (its name starts with "zefily" and the domain),
• sets its ingress: each name of the site (the domain and its aliases) goes to the site on this server, and a catch-all answers 404 for anything else,
• creates one proxied CNAME per name, pointing to <tunnel-id>.cfargotunnel.com, the target Cloudflare documents for tunnels,
• fetches the tunnel token from Cloudflare and sends it to the server sealed, the same way as other secrets,
• the server installs the pinned cloudflared release and starts the connector.

If any step fails, Zefily deletes what it created in Cloudflare and shows the reason.

A name is reached on the server's HTTPS port (443) when the site has TLS, and on port 80 when it does not. Visitors see Cloudflare's certificate for the name. The connection between Cloudflare's tunnel and the server stays on the server itself (127.0.0.1), and the server's own certificate is not checked for that loopback connection.

Status#

Once the server runs the connector, the site shows its state and what Cloudflare reports for the tunnel:

• Healthy: the tunnel is connected to Cloudflare's network; the connections and the Cloudflare locations they use are listed.
• Degraded: connected, but Cloudflare sees a problem with some connections.
• Down: no connection to Cloudflare. Check the server: the connector runs as zefily-tunnel-<site id>.service.
• Not connected: the tunnel has never connected.

While the server starts or stops the connector, the page updates by itself. A failure shows the reason the server gave.

Turn it off#

Select Turn off tunnel and confirm. Zefily stops the connector on the server and deletes its service file and its token file. Once the server confirms, Zefily deletes the tunnel's CNAME records and the tunnel in Cloudflare. Cloudflare refuses to delete a tunnel while connections are still open, so Zefily retries each minute until it is gone; the page shows the last error meanwhile.

Turning the tunnel off does not restore the names' address records. Use Point DNS on the site's DNS page afterwards to send the names back to the server. Point DNS is not available while the tunnel exists, because it would replace the tunnel's records.

Limits#

• One tunnel per site. Each name of the site must be in the zone of the Cloudflare account you choose.
• Wildcard names (*.example.com) cannot be served through a tunnel here.
• Removing or moving the site, or deleting the server, is refused while the tunnel runs: turn it off first.
• Editing a tunnel's CNAME record on the DNS page by hand breaks the tunnel until you put it back.
• Zefily does not close ports 80 and 443 on the server. Closing them is up to you; the other sites on the server keep using them.
• The connector is updated only with a new Zefily agent release; it does not update itself.

Security#

The tunnel token is never stored in the Zefily database and never written to a log. It travels sealed to the server and lives in a root-only environment file that only the service's start reads. The service runs as a dynamic user without capabilities, with a read-only system and no home directory, and only over IP and local sockets. The binary is the Cloudflare release checked against its published SHA-256 checksum before it is installed.