# Reverse proxy and DNS

> How FeatherQuilld routes WebSpace domains through Caddy, nginx or Traefik, issues Let's Encrypt certificates, and hosts DNS zones on PowerDNS.

Source: https://featherpanel.com/docs/quilld/proxy-and-dns/

Each WebSpace container listens on a loopback port. A reverse proxy on the node answers on ports 80 and 443 and sends
each domain to the right port. FeatherQuilld writes the proxy configuration and reloads the proxy whenever a WebSpace
or its domains change.

## Choosing a proxy

Install one web server from the web node's **Package manager** tab: Caddy, nginx or Traefik. Only one can be active;
remove the current one before installing another. Then set the provider on the **Network** tab.

| Setting (Network tab) | Config key | Default |
|------------------------|------------|---------|
| Site reverse proxy | `system.proxy.enabled` | enabled |
| Proxy provider | `system.proxy.provider` | `caddy` |
| ACME email | `system.proxy.acme_email` | empty |
| ACME staging | `system.proxy.acme_staging` | off |
| Backend Port Min and Max | `system.proxy.backend_port_min`, `backend_port_max` | `20000` to `29999` |
| Proxy upstream host | `system.proxy.backend_host` | `127.0.0.1` |
| Backend bind host | `system.proxy.backend_bind_host` | `127.0.0.1` |

The generated file lives in `/var/lib/featherquilld/proxy/` unless you set `system.proxy.config_path`:

| Provider | File | Reload |
|----------|------|--------|
| Caddy | `Caddyfile` | `caddy reload --config <file>` |
| nginx | `nginx.conf`, included from `/etc/nginx/conf.d/featherquilld.conf` | `nginx -s reload` |
| Traefik | `traefik-dynamic.yml` | none, Traefik watches the file |

With Traefik you provide the static configuration: entry points named `web` and `websecure`, a file provider that
watches the generated file, and optionally a certificate resolver named `featherquilld` for Let's Encrypt.

## Domains

A WebSpace has one primary domain and any number of aliases, which serve the same site, and redirects, which send
visitors to another URL. The WWW preference (apex, www or none) adds the matching redirect between `example.com` and
`www.example.com`.

Point each domain's A (and AAAA) record at the web node. The WebSpace domains page can check the records, and when
the zone is hosted on the node's PowerDNS it can create them for you.

## Certificates

Each WebSpace has SSL on or off and an SSL mode:

- **acme** (default). Let's Encrypt over HTTP. With Caddy, Caddy requests and renews the certificate itself. With nginx,
  Quilld runs the ACME client, serves the challenge from `/var/lib/featherquilld/acme/www` and stores certificates in
  `/etc/featherquilld/certs/<domain>.crt` and `.key`. Port 80 must be reachable from the internet.
- **dns01**. A certificate for the domain and `*.domain` via a DNS TXT record. The panel writes the record, so the
  WebSpace needs a linked DNS zone on PowerDNS.
- **custom**. Upload your own certificate and key on the admin WebSpace edit page. Removing it returns the WebSpace to
  automatic ACME.

The certificate uses the owner's account email, and falls back to the node's ACME email. Quilld checks once a day
(Caddy and nginx) and renews certificates that expire within 30 days. With SSL off, the Caddy config uses
`tls internal`, a certificate from Caddy's own local authority.

## Web application firewall and logs

When the WAF is enabled for a WebSpace, the generated config adds security headers, a request body limit and the
WebSpace's denied IPs. On nginx it also turns on ModSecurity with the OWASP Core Rule Set, which you install from the
Package manager.

Access and error logs are written to `/var/lib/featherquilld/proxy/logs/<webspace uuid>/<domain>.access.log` and
`.error.log`, and daily summaries are kept for the WebSpace analytics page.

## DNS hosting with PowerDNS

A web node can be the authoritative DNS server for your customers' domains.

1. On the web node, open **Package manager** and install PowerDNS. Quilld installs `pdns-server` with the SQLite
   backend, enables the HTTP API on `127.0.0.1:8081` with a random key and starts the service. The key is saved in
   `/var/lib/featherquilld/dns/powerdns-api-key`.
2. Open port `53` TCP and UDP on the node's firewall.
3. In the admin area go to **DNS hosts**, add a host and pick the web node. **Test connection** lists the zones it finds.
4. Delegate the domain at the registrar. The DNS hosts page shows an example: nameserver `ns1.example.com` with a glue
   record pointing at the node IP.

WebSpace owners then manage zones and records from the WebSpace, and only on a DNS host that belongs to the same web
node as the WebSpace. The connection settings are `system.dns.powerdns_api_url` and `system.dns.powerdns_api_key`.

## Frequently asked questions

### Every domain shows the "Welcome to nginx" page. What is wrong?

nginx is not loading the file Quilld generates. Quilld adds /etc/nginx/conf.d/featherquilld.conf with an include line, but only on a stock layout and only if that file does not already exist with other content. Include the generated nginx.conf yourself if your nginx uses another layout.

### Can I run a reverse proxy on a different machine?

Yes. Set Proxy upstream host to the node IP and Backend bind host to 0.0.0.0 or the node IP, so the proxy can reach the WebSpace ports. By default both are 127.0.0.1.