Edge
Edge
Edge manages your public entry points: the hostnames your own machines answer on, what sits behind each, and their TLS certificates. It installs the terminator (a Caddy configuration) on a machine in your fleet. It then proves that the certificate and the pages are right by reading them over the wire, instead of trusting what the terminator says about itself.
In the sidebar under Domains & network → Edge.
The machines come from Devices. A site names the enrolled machine that holds its public address.
The Edge screen
One list, one row per hostname:
- Hostname, with the public address it must resolve to.
- Behind it: the addresses traffic is sent to, or "nothing".
- Config: the install state, such as
PLANNED,DNS_VERIFIED,INSTALLING,INSTALLEDorFAILED, with the machine's last complaint. - Served: what a client was last actually served: as promised, headers only, unproven, wrong, not re-read or not read.
- Certificate: days left (a warning when expiring), expired, unconfirmed when the reading is too old, or never read.
- Last read: when the certificate was last read.
A stale or never-read verdict means nobody has looked recently, not that all is well. With nothing recorded, the page says "Nothing is published". Recording a hostname changes nothing until it is installed.
Record a hostname
- Click New hostname.
- Enter the Hostname and the Machine that will hold its public address.
- Leave Public address empty to use the address the machine enrolled with. A machine with no known address is refused.
- Optionally give an ACME contact address, then save.
Put it on the internet
The rest is done by an agent, or through the API, in this order:
- Add what is behind it. One upstream address. A second one is refused until the shared state behind it is declared (database, uploads, object cache, a single cron holder) and a health path is recorded.
- Check DNS. Public resolvers must all answer with the recorded address before any certificate is asked for.
- Read the plan. The exact configuration and commands an install would run, and anything that would refuse it today, without running anything.
- Install. The configuration is rendered, installed on the machine and reloaded. DNS is checked again first.
- Verify. Read the certificate a client is served, and check the responses: one redirect to the canonical HTTPS name, the
wwwhop, a page carrying the expected text, the security headers, and a 404 on paths a shop must never serve.
HSTS starts at 300 seconds. Raise it once HTTPS has been proven.
Roll back a bad node
Take the node's address out of rotation (or remove it), then install again. A disabled address is kept, so putting it back is one switch.
Take a name off the internet
Uninstall the site. The record and the certificate stay, so putting it back is one install.
Force a renewal
A forced renewal deletes the certificate, restarts the terminator, and checks a new one was issued. Certificate authorities limit duplicates to five a week, so use it sparingly.
Who can do what
| Permission | Label | Lets you |
|---|---|---|
edge:read | View public entry points, and read a certificate back over the wire | See sites, machines and plans; check DNS; verify certificates and responses |
edge:write | Record hostnames, upstreams and what is shared between them | Record hostnames; add, disable and remove upstreams; set policy; declare shared state |
edge:admin | Install a terminator, ask for a certificate, take a name off the internet | Install, uninstall and force a renewal |
What happens on its own
| Job | When | What it does |
|---|---|---|
certs | Every hour at minute 23 | Re-reads, from a fleet machine, the certificate of each installed site last read more than six hours ago. It tells the person who recorded the site when a certificate is expiring (inside 21 days), expired or unconfirmed, or the site serves the wrong thing. Each alert repeats at most once every 20 hours. |
Alerts arrive as notifications. See Notifications and alerts.
Needs
Nothing else needs to be switched on. To install anything you need at least one machine enrolled in Devices.
What agents can do
Reads and checks run straight away. Other tools ask a person first unless a standing rule allows them. See Agents and approvals.
Look (read-only)
edge.sites,edge.site,edge.machines,edge.expiring(sites whose certificate is not demonstrably fine).edge.plan: the exact configuration and commands an install would run, without running them.
Check (runs straight away; the result is recorded)
edge.checkDns: compares public resolvers with the recorded address.edge.verify: reads the certificate a client is actually served.edge.checkResponses: reads what a client is actually served now.
Record (asks first; nothing changes on a machine until install)
edge.createSite,edge.addUpstream,edge.setUpstreamEnabled,edge.setPolicy,edge.declareSharedState.edge.removeUpstream(destructive).
Act on the machine (asks first; needs edge:admin)
edge.install: renders, installs and reloads the configuration, then reads the answers back.edge.uninstall: stops the machine answering for the hostname.edge.renew: forces a renewal and proves it.
Over MCP the same tools are named edge__sites and so on. See API keys and MCP access.