# TLS

> Wildcard certificates for the public server via ACME DNS-01, or your own cert.

The public server always serves HTTPS; there is no plaintext mode. You have two
ways to provide certificates.

## acme mode (default)

The server obtains and renews wildcard certificates automatically through Let's
Encrypt, using the **ACME DNS-01** challenge driven by
[certmagic](https://github.com/caddyserver/certmagic) with the Cloudflare DNS
provider.

```bash
export CLOUDFLARE_API_TOKEN="your-cloudflare-api-token"
routeup server --domain tunnel.example.com --tls-mode acme
```

Why DNS-01 rather than HTTP-01:

- It can issue **wildcards** (`*.tunnel.example.com`), which is exactly the shape
  routeup needs, one certificate per namespace base covers every label under it.
- It does not depend on inbound port 80.

The server manages `*.<domain>` and the optional public-namespace wildcard at
startup. It also pre-warms wildcards for token namespaces found in its database
and ensures the relevant namespace wildcard again when a claim is made.
certmagic handles issuance, renewal, storage, and locking.

## cert mode

Provide one certificate and private key:

```bash
routeup server --domain tunnel.example.com --tls-mode cert \
  --tls-cert /path/fullchain.pem \
  --tls-key /path/key.pem \
  --reserved edge
```

In static `cert` mode, routeup does not obtain additional namespace
certificates. The supplied certificate must cover every hostname tier you serve,
for example:

```txt
*.tunnel.example.com
*.try.tunnel.example.com
*.alice.tunnel.example.com
```

The root wildcard covers the control host `edge.tunnel.example.com`. Add SANs
for the public namespace and every token namespace in use. Certificate renewal
and replacement are your responsibility.

## Failure modes

- **Bad or missing DNS API token**: issuance fails; the server cannot get a
  certificate. Check `CLOUDFLARE_API_TOKEN` scope.
- **Rate limits**: per-namespace wildcards (rather than per-host certs) keep the
  certificate count low and Let's Encrypt rate limits comfortable.