Cloudflare Tunnel and Access¶
Beta
New in 2.4.0-beta.1, and a beta feature: it works end to end, but it has
been tried on one Cloudflare account and its details may still change. To
get it, tick Also offer beta versions on the Updates page, or use the
:2.4.0-beta.1 image. Reports are welcome on
GitHub.
Optional, and off until switched on. A
Cloudflare Tunnel
makes a service reachable from the internet without an open port:
cloudflared runs on every node and holds an outbound connection to
Cloudflare, visitors reach Cloudflare, and Cloudflare hands their requests
down that connection to HAProxy. It suits a node behind a router or a
carrier-grade NAT it does not control. Cloudflare Access, its sign-in, can
stand in front of a service and decide who gets that far.
haproxy-manager does the Cloudflare side for you. Given one API token it makes the tunnel, and at every Apply keeps three things in step for each service ticked Publish through Cloudflare: the tunnel's route for the host name, the DNS record that points the name at the tunnel, and the Access application with its policy.
- What you need
- Connecting
- Publishing a service
- What Apply does
- The visitor's address
- cloudflared on each node
- What it looks like on disk
- Disconnecting
- Limits
What you need¶
- A domain on your Cloudflare account, with Cloudflare as its DNS.
- Zero Trust opened once in the Cloudflare dashboard, for services that ask for a sign-in. The Free plan is enough, and so is its default login method, a one-time PIN by email.
-
An API token: My Profile › API Tokens › Create Token › Custom token, with
Scope Permission Level Account Cloudflare Tunnel Edit Account Access: Apps and Policies Edit Zone DNS Edit Zone Zone Read Limit Zone Resources to the zones your services are in. A token that sees more zones works too; only the host names of published services are ever touched.
Connecting¶
Access › Cloudflare. The header carries a beta pill and a pill for
saved: on or saved: off; below it, a line for this node (is cloudflared
installed and running) and one for the tunnel (connected, and which host names
are published). The fields, in order:
| Field | Notes |
|---|---|
| API token | Never shown again once saved; leave empty to keep the stored one |
| Account ID | Optional when the token sees one account. It is on the right of a zone's Overview page |
| Tunnel name | haproxy-manager unless changed. The tunnel made in your account, or joined when one of that name is already there |
| First loopback port | 7811 unless changed. Where cloudflared reaches HAProxy; see what Apply does |
| Enable Cloudflare | Takes effect at the next Apply |
Test the token asks Cloudflare what the token can see: whether it can manage tunnels, the zones it sees, whether Access answers, and, once connected, how the tunnel is doing.
Save with Enable Cloudflare ticked makes the tunnel, a remotely managed one, and keeps its token. Nothing is published yet. In a cluster the settings and the tunnel's token are shared, so every node connects to the same tunnel and Cloudflare spreads visitors over the nodes that are connected. It does not depend on the virtual IP.
Sync now tells Cloudflare again whether or not anything changed here, for a record or an application somebody removed in the dashboard.
Publishing a service¶
In the service form, the Cloudflare (beta) section, on HTTP and HTTPS services:
| Field | Notes |
|---|---|
| Publish through Cloudflare | Apply adds the route, the DNS record and, when asked for, the Access application |
| Who may reach it | anyone -- no sign-in, or a Cloudflare Access sign-in, for the identities below |
| Allowed identities | For the sign-in. One per line: an email, a whole domain as @example.com, or * for anyone your Cloudflare identity provider signs in |
| Through Cloudflare only | Refuse every request that did not come through the tunnel |
A service published only this way needs no certificate and no open port here:
publish it as http://app.example.com, and Cloudflare serves it to visitors
over HTTPS. A service that already has a certificate and a port keeps them,
and is then reachable both ways.
Through Cloudflare only matters with a sign-in. Without it, anybody who can reach the node's own port, on the LAN say, gets the service with no sign-in at all. With it, HAProxy answers such a request 403:
backend be_app
http-request deny deny_status 403 unless { dst_port 7811 }
Ticked while Cloudflare is not connected, the service refuses every request, and saving it says so.
The Services page shows it beside the address: through Cloudflare — sign-in for …, or no sign-in, and and only through it.
What Apply does¶
On every node, HAProxy's listener that carries a published service gains a
loopback port, the first loopback port plus the listener's place in the list,
and cloudflared is started:
frontend fe_http-80
bind 0.0.0.0:80
bind 127.0.0.1:7811
acl cf_tunnel dst_port 7811
http-request set-src req.hdr(CF-Connecting-IP) if cf_tunnel { req.hdr(CF-Connecting-IP) -m found }
http-request set-header X-Forwarded-Proto https if cf_tunnel
The tunnel sends each host to that port, not to the servers, so health checks, rules, rate limits, allow-lists and CrowdSec all still apply. A listener that sends plain HTTP on to HTTPS leaves the tunnel's visitors out of that, since they are on HTTPS already.
Then, on the node the change was made on, Cloudflare is told, in this order:
- Access. An application per host that asks for a sign-in, named after
the service, with one policy named
haproxy-manager. First, so a service is never reachable for a moment without its sign-in. - The tunnel's routes, one per host name, and a 404 for everything else.
- DNS. A proxied
CNAMEfrom the host name to the tunnel.
Unticking a service, or switching Cloudflare off, takes them away again at the next Apply, the route before the sign-in. An Apply that changes nothing Cloudflare holds asks nothing of it.
Only what was made here is changed or removed:
- A host name that already has a DNS record keeps it, and Apply warns that visitors still go there. Delete the record in Cloudflare and Apply again.
- A host that already has an Access application made in the dashboard keeps it as it is; that application decides who gets in.
- A host name in no zone the token can see gets its route but no record, and Apply says so.
Cloudflare not answering does not fail the Apply. It is a warning, the page shows Cloudflare is behind, and the next Apply or Sync now catches up.
The visitor's address¶
Everything that comes down the tunnel arrives from cloudflared on the
loopback. On the loopback port, and only there, HAProxy takes the visitor's
address from Cloudflare's CF-Connecting-IP header, before anything else
looks at it. The log, X-Forwarded-For and X-Real-IP, allow-lists, rate
limits and CrowdSec then all see the visitor. Nobody but a process on the node
can connect to that port, so nobody else can claim an address; the same header
sent to the node's public port is ignored.
cloudflared on each node¶
cloudflared comes from Cloudflare's own package repository
(pkg.cloudflare.com), whose signing key is held to its fingerprint. The
container image carries it. A node installed from install.sh or a package
fetches it at the first Apply after Cloudflare is switched on, or from
Install on this node on the page; a failed install is not retried for six
hours.
Under systemd it runs as ham-cloudflared.service, written by haproxy-manager,
as a dynamic unprivileged user. In the container supervisord runs it, as
nobody. It is given the tunnel's token through its environment, never on its
command line. It is stopped when Cloudflare is switched off.
A node where it is missing or stopped simply carries none of the tunnel's traffic; Apply says so, and the other nodes carry on.
What it looks like on disk¶
| Path | What |
|---|---|
/var/lib/haproxy-manager/cloudflared.env |
the tunnel's token, mode 0600, written on Apply and removed when Cloudflare is switched off |
/etc/systemd/system/ham-cloudflared.service |
the unit, under systemd |
/var/lib/haproxy-manager/cloudflare-state.json |
what this node last told Cloudflare, so an unchanged Apply asks nothing |
/etc/apt/sources.list.d/cloudflared.list |
Cloudflare's repository, once cloudflared has been installed |
Disconnecting¶
Disconnect, on the page, removes every route, DNS record and Access
application made here, stops cloudflared on this node, deletes the tunnel
and forgets it. The API token stays, for connecting again. Services keep their
ticks, and are published again when a tunnel is.
Limits¶
- HTTP and HTTPS services only. A
tcp://service is not offered the section; raw TCP through a tunnel needs Cloudflare's client on the visitor's side as well. - One policy per service: a list of emails and domains, or everyone who signs in. Anything richer (groups, countries, device posture) is made in the Cloudflare dashboard; an application made there is left alone.
- Access is not verified again by HAProxy. Through Cloudflare only refuses what did not come down the tunnel, which is what keeps the sign-in from being bypassed; the Access token itself is not checked on the node.
- HSTS set on a service is sent on the node's own HTTPS port only. For visitors through the tunnel, set it in Cloudflare.
- A node's own web UI service is not published this way.