43ae164d8b
Consumers reached authelia at `127.0.0.1:<port>`, which encoded a
co-location nobody agreed to: the gateway and authelia are not required
to share a host, so the literal is a requirement stated only by being
unwriteable any other way. Moving them to the name is the point of the
issue.
But a name over https is only half of "https and auth". nginx's
`proxy_ssl_verify` is OFF by default and there was no `proxy_ssl_*`
anywhere in the tree, so the obvious repoint would have produced an
encrypted, unauthenticated hop -- which works, and keeps working,
against any certificate at all.
Adds `gateway.lib.verifiedProxyTo <name>` next to the rest of the vhost
kit, so the convention has one definition rather than a copy in each
consuming module, and repoints the four call sites through it.
Each directive was checked against a real nginx with the opposite arm
run as a control:
- the CA *bundle* (root + intermediate) is accepted -- worth checking,
since `hive-ca-trust.nix` warns off consumers that read only one
certificate, and nginx is not one of those
- verification checks the chain: an unrelated CA fails
- and the HOSTNAME: a wrong `proxy_ssl_name` fails even with a good
chain. Chain-only would accept any cert this CA ever signed, which
for an internal CA is every service on the hive
- with verify off, the wrong CA passes -- so the failures above come
from verification, not from the connection
Bind addresses are untouched. This changes what consumers dial, not what
anything listens on.
422 lines
16 KiB
Nix
422 lines
16 KiB
Nix
# Option declarations for `services.hyperhive.gateway.*`. The gateway
|
||
# is always run alongside hyperhive (it's the single nginx in front of
|
||
# every surface and the only thing exposed to the outside); there is
|
||
# no enable flag. An operator who wants their own reverse proxy in
|
||
# front points it at the gateway's `port`.
|
||
{
|
||
lib,
|
||
config,
|
||
...
|
||
}:
|
||
let
|
||
cfg = config.services.hyperhive.gateway;
|
||
in
|
||
{
|
||
imports = [
|
||
(lib.mkRemovedOptionModule [ "services" "hyperhive" "gateway" "selfSignedTls" ] ''
|
||
Self-signed TLS is the implicit default whenever neither
|
||
tls.certDir nor tls.acme is configured, and there is no http-only
|
||
mode. Remove the setting; configure `tls.certDir` or `tls.acme`
|
||
to override the self-signed default.
|
||
'')
|
||
];
|
||
|
||
options.services.hyperhive.gateway = {
|
||
port = lib.mkOption {
|
||
type = lib.types.port;
|
||
default = 80;
|
||
example = 8080;
|
||
description = ''
|
||
TCP port the gateway listens on. Default 80 (canonical web
|
||
port). nginx runs on the host as root, so it can bind <1024;
|
||
if 80 is already taken on the host (existing nginx, traefik,
|
||
etc.) override to an unused port like 8080 or move the
|
||
conflicting service.
|
||
'';
|
||
};
|
||
|
||
upstreamHost = lib.mkOption {
|
||
type = lib.types.str;
|
||
default = "127.0.0.1";
|
||
description = ''
|
||
Host the gateway proxies non-static requests to. Defaults to
|
||
`127.0.0.1` because nginx runs on the host itself, so loopback
|
||
resolves directly to hive-c0re.
|
||
'';
|
||
};
|
||
|
||
upstreamPort = lib.mkOption {
|
||
type = lib.types.port;
|
||
default = 7000;
|
||
description = ''
|
||
TCP port the gateway proxies non-static requests to. Defaults
|
||
to `7000` (hive-c0re's out-of-the-box dashboard port). Operators
|
||
who change `services.hyperhive.c0re.dashboardPort` should set
|
||
`upstreamPort` to match — kept as a hardcoded default rather
|
||
than a cross-reference to keep this module's options eval
|
||
independent of c0re's option tree shape.
|
||
'';
|
||
};
|
||
|
||
openFirewall = lib.mkOption {
|
||
type = lib.types.bool;
|
||
default = false;
|
||
example = true;
|
||
description = ''
|
||
Open `port` in the host firewall. Off by default (secure-by-default).
|
||
Flip to `true` to expose the gateway to
|
||
the operator's browser / external clients — required for any
|
||
out-of-host reach, since the agents themselves talk to
|
||
hive-c0re via the per-agent unix sockets and don't need the
|
||
nginx vhost. Leave off when running behind another reverse
|
||
proxy (e.g. caddy / traefik on the host) that handles TLS
|
||
termination + forwards to `port`.
|
||
|
||
**Note**: this used to default to `true`. Add
|
||
`services.hyperhive.gateway.openFirewall = true;` to your host
|
||
config if external reach stopped working after a recent upgrade.
|
||
'';
|
||
};
|
||
|
||
localHostsEntry = lib.mkOption {
|
||
type = lib.types.bool;
|
||
default = false;
|
||
example = true;
|
||
description = ''
|
||
Add an `/etc/hosts` entry mapping `services.hyperhive.domain`
|
||
to `127.0.0.1` on the host. Useful for local deployments +
|
||
tests where there's no real DNS for `services.hyperhive.domain`
|
||
but the operator (or browser-based tests) want to hit
|
||
`http://''${services.hyperhive.domain}` to exercise the
|
||
gateway shape. Off by default — operators running with real
|
||
DNS shouldn't have a stale `/etc/hosts` entry sticking
|
||
around. Requires `services.hyperhive.domain` to be set.
|
||
|
||
`services.hyperhive.enableAllLocalDefaults` turns this on as
|
||
part of saying "this box is the whole deployment": that mode
|
||
means there is no real DNS for these names and the operator is
|
||
browsing them from the host itself. Set it here explicitly to
|
||
override in either direction.
|
||
'';
|
||
};
|
||
|
||
localNames = lib.mkOption {
|
||
type = lib.types.listOf lib.types.str;
|
||
default = [ ];
|
||
internal = true;
|
||
description = ''
|
||
Extra hostnames the hive's resolver answers with the bridge IP,
|
||
contributed by the modules that own those names.
|
||
|
||
A service module says **which name**; the gateway decides
|
||
**where it points** — the same split as `lib.tlsFor`. A service
|
||
that hardcoded the bridge IP would be one more place to fix when
|
||
the network layout changes, and it has no business knowing it.
|
||
|
||
⚠️ Contribute a name only when THIS host actually serves it. The
|
||
list is not "names the swarm has" —
|
||
`services.hyperhive.swarm.serviceDomains` is that, and it is
|
||
deliberately broader (it drives certificate issuance, so it
|
||
includes names this hive may only be a client of). Publishing an
|
||
address record for a service you do not run points every agent
|
||
on the bridge at a door that isn't there.
|
||
'';
|
||
};
|
||
|
||
lib = {
|
||
listen = lib.mkOption {
|
||
type = lib.types.listOf (lib.types.attrsOf lib.types.raw);
|
||
internal = true;
|
||
readOnly = true;
|
||
description = ''
|
||
Read-only: the `listen` set every vhost in front of this
|
||
gateway shares (plain http on `port`, TLS on `httpsPort`).
|
||
Published so a service module can declare its own vhost
|
||
without restating the port pair — a vhost that binds a
|
||
different set is reachable on a port the gateway does not
|
||
consider its own, which is the kind of drift nobody notices
|
||
until one name behaves differently from the rest.
|
||
'';
|
||
};
|
||
|
||
tlsFor = lib.mkOption {
|
||
type = lib.types.functionTo (lib.types.attrsOf lib.types.raw);
|
||
internal = true;
|
||
readOnly = true;
|
||
description = ''
|
||
Read-only: `host -> ssl attrs` for a vhost of that name.
|
||
|
||
Which issuer covers a name is **gateway** knowledge, not the
|
||
service's: a swarm service's name can sit outside this hive's
|
||
domain, and the hive CA is name-constrained out of it, so that
|
||
vhost must serve the swarm-services leaf while everything else
|
||
keeps the hive leaf. A service module calls this instead of
|
||
deciding — deciding is how the vhost and the cert stop
|
||
agreeing.
|
||
'';
|
||
};
|
||
|
||
errorPages = lib.mkOption {
|
||
type = lib.types.attrsOf lib.types.path;
|
||
internal = true;
|
||
readOnly = true;
|
||
description = ''
|
||
Read-only: the gateway's styled static error pages, by name
|
||
(`notFound`, `unreachable`, `unauthorized`, `ssoUnavailable`).
|
||
|
||
Published so a service module can aim an `error_page` at one
|
||
instead of rendering its own — a service that built its own
|
||
would drift from the rest of the gateway the first time the
|
||
theme changed, and the operator would meet two different
|
||
error styles on one hive.
|
||
'';
|
||
};
|
||
|
||
verifiedProxyTo = lib.mkOption {
|
||
type = lib.types.functionTo lib.types.lines;
|
||
internal = true;
|
||
readOnly = true;
|
||
description = ''
|
||
Read-only: `name -> the proxy_ssl_* lines` for dialling
|
||
another service on this hive **by name over https**, with the
|
||
certificate actually verified against the hive CA bundle.
|
||
|
||
Published rather than written per module because nginx
|
||
verifies nothing by default: `proxy_ssl_verify` is **off**, so
|
||
a `proxy_pass https://…` that omits these is encrypted and
|
||
unauthenticated — which is the half of "https and auth" that
|
||
is easy to believe you already have.
|
||
|
||
Measured, not copied: verification is confirmed to check both
|
||
the chain and the **hostname**, and the CA *bundle* (root +
|
||
intermediate) is confirmed to be accepted — the bundle's own
|
||
doc warns off consumers that read only one certificate, and
|
||
nginx is not one of those.
|
||
'';
|
||
};
|
||
|
||
securityHeaders = lib.mkOption {
|
||
type = lib.types.lines;
|
||
internal = true;
|
||
readOnly = true;
|
||
description = ''
|
||
Read-only: the server-scope security headers every vhost in
|
||
front of this gateway sets.
|
||
|
||
⚠️ nginx does not merge `add_header`: a location that sets one
|
||
of its own inherits **none** of these, so such a location must
|
||
repeat them. That rule is why this is published rather than
|
||
left implicit — a service module writing its own `locations`
|
||
needs the text, not a description of it.
|
||
'';
|
||
};
|
||
};
|
||
|
||
useSelfSigned = lib.mkOption {
|
||
type = lib.types.bool;
|
||
internal = true;
|
||
readOnly = true;
|
||
default = cfg.tls.certDir == null && !cfg.tls.acme.enable;
|
||
defaultText = lib.literalExpression "tls.certDir == null && !tls.acme.enable";
|
||
description = ''
|
||
Read-only derived flag: `true` when the gateway serves the
|
||
self-signed (hive-CA-signed) leaf — i.e. neither `tls.certDir` nor
|
||
`tls.acme.enable` is configured. Single source of truth for the
|
||
self-signed condition; consumed by the `hive-tls` and `hive-ci`
|
||
modules so the derivation isn't duplicated. Internal — not meant to
|
||
be set by operators (use `tls.certDir` / `tls.acme` to override the
|
||
self-signed default).
|
||
'';
|
||
};
|
||
|
||
httpsPort = lib.mkOption {
|
||
type = lib.types.port;
|
||
default = 443;
|
||
example = 8443;
|
||
description = ''
|
||
TCP port for the TLS-terminated vhosts. Default 443. The gateway
|
||
always terminates TLS (self-signed is the implicit floor when no
|
||
`tls.certDir` / ACME is configured), so this port is always active
|
||
alongside the plain-http `port`.
|
||
'';
|
||
};
|
||
|
||
tls = {
|
||
certDir = lib.mkOption {
|
||
type = lib.types.nullOr lib.types.path;
|
||
default = null;
|
||
example = lib.literalExpression ''"/var/lib/acme/example.com"'';
|
||
description = ''
|
||
Path to a host directory containing a TLS certificate and
|
||
private key for nginx. When set, nginx listens on `httpsPort`
|
||
and uses this cert, overriding the self-signed default — the
|
||
auto-generated hive-CA-signed leaf is skipped entirely.
|
||
|
||
nginx reads `<certDir>/<tls.certName>` and
|
||
`<certDir>/<tls.keyName>` directly — it runs on the host, so
|
||
the directory needs no bind mount and no copy.
|
||
Default filenames (`cert.pem` / `key.pem`) match the output
|
||
layout of nixpkgs's `security.acme` module.
|
||
|
||
Typical ACME setup:
|
||
```nix
|
||
security.acme.certs."example.com" = { ... };
|
||
services.hyperhive.gateway.tls.certDir =
|
||
config.security.acme.certs."example.com".directory;
|
||
```
|
||
|
||
Mutual exclusion with `tls.acme.enable` — set one or the other,
|
||
not both.
|
||
'';
|
||
};
|
||
|
||
certName = lib.mkOption {
|
||
type = lib.types.str;
|
||
default = "cert.pem";
|
||
description = ''
|
||
Filename of the TLS certificate within `tls.certDir`. Defaults
|
||
to `cert.pem` which matches nixpkgs's `security.acme` output.
|
||
'';
|
||
};
|
||
|
||
keyName = lib.mkOption {
|
||
type = lib.types.str;
|
||
default = "key.pem";
|
||
description = ''
|
||
Filename of the TLS private key within `tls.certDir`. Defaults
|
||
to `key.pem` which matches nixpkgs's `security.acme` output.
|
||
'';
|
||
};
|
||
|
||
acme = {
|
||
enable = lib.mkOption {
|
||
type = lib.types.bool;
|
||
default = false;
|
||
example = true;
|
||
description = ''
|
||
Let the gateway's nginx obtain and renew TLS certificates
|
||
automatically via ACME (Let's Encrypt). When enabled, each
|
||
vhost calls out to Let's Encrypt using the HTTP-01
|
||
challenge on `port` (default 80) and stores certs in the
|
||
gateway's persistent state dir on the host.
|
||
|
||
Requirements:
|
||
- `services.hyperhive.domain` must be set and publicly
|
||
DNS-resolvable to this host.
|
||
- `services.hyperhive.gateway.openFirewall = true` so
|
||
Let's Encrypt can reach `/.well-known/acme-challenge/`.
|
||
- `tls.acme.email` must be set (ACME account contact).
|
||
|
||
Mutual exclusion: `tls.certDir` set together with
|
||
`tls.acme.enable = true` fails at eval — pick one TLS source.
|
||
|
||
Typical setup:
|
||
```nix
|
||
services.hyperhive.gateway = {
|
||
openFirewall = true;
|
||
tls.acme = {
|
||
enable = true;
|
||
email = "admin@example.com";
|
||
};
|
||
};
|
||
```
|
||
'';
|
||
};
|
||
|
||
email = lib.mkOption {
|
||
type = lib.types.nullOr lib.types.str;
|
||
default = null;
|
||
example = "admin@example.com";
|
||
description = ''
|
||
Email address for the ACME account registration with
|
||
Let's Encrypt. Required when `tls.acme.enable = true`.
|
||
Let's Encrypt sends expiry warnings to this address.
|
||
'';
|
||
};
|
||
};
|
||
};
|
||
|
||
auth = {
|
||
enable = lib.mkEnableOption ''
|
||
HTTP basic auth on the gateway using an htpasswd file. When
|
||
enabled, every request to the gateway's main vhost requires a
|
||
valid username and password. nginx's built-in `auth_basic`
|
||
module validates credentials against
|
||
`/var/lib/hive-gateway/conf/gateway.htpasswd`. Off by default.
|
||
|
||
Manage users with `hivectl gateway create-user`, `delete-user`,
|
||
and `list-users` — see `hivectl gateway --help` for usage.
|
||
The htpasswd file is created automatically when auth is enabled;
|
||
add at least one user before enabling to avoid locking everyone out.
|
||
'';
|
||
|
||
realm = lib.mkOption {
|
||
type = lib.types.strMatching "[^\"$]*";
|
||
default = "hyperhive";
|
||
example = "my-hive";
|
||
description = ''
|
||
HTTP Basic auth `realm` value sent in the `WWW-Authenticate`
|
||
header when credentials are absent or rejected. Must not
|
||
contain `"` or `$` (nginx string metacharacters).
|
||
'';
|
||
};
|
||
};
|
||
|
||
swaggerUiTheme = lib.mkOption {
|
||
type = lib.types.package;
|
||
defaultText = lib.literalExpression "hyperhive.packages.\${system}.swagger-ui-theme";
|
||
description = ''
|
||
Full Swagger UI static dist, hyperhive-themed (see
|
||
`nix/packages/swagger-ui-theme.nix`, built on
|
||
`nix/packages/swagger-ui-dist.nix`). The gateway serves this
|
||
whole tree directly at `/api/docs/` — hive-c0re hosts none of
|
||
it, only the dynamic `/api/openapi.json` route (proxied
|
||
through, unaffected by this option). Override to ship a
|
||
custom theme (or the plain vendored dist) without a gateway
|
||
rebuild.
|
||
'';
|
||
};
|
||
|
||
hsts = {
|
||
enable = lib.mkOption {
|
||
type = lib.types.bool;
|
||
default = false;
|
||
description = ''
|
||
Add `Strict-Transport-Security` to all gateway vhosts.
|
||
|
||
Disabled by default: HSTS pins HTTPS in the browser's HSTS
|
||
preload list; enabling it on a deployment that later loses TLS
|
||
will lock browsers out until the max-age expires. Only enable
|
||
this when you are certain TLS is permanent.
|
||
|
||
The gateway always terminates TLS (self-signed floor), so
|
||
HSTS is always served over https when enabled — but mind the
|
||
warning above: HSTS pins https in the browser, so only enable it
|
||
when TLS is permanent for this deployment.
|
||
'';
|
||
};
|
||
|
||
maxAge = lib.mkOption {
|
||
type = lib.types.ints.positive;
|
||
default = 31536000;
|
||
example = 86400;
|
||
description = ''
|
||
Value for the `max-age` directive in seconds.
|
||
Default: 31536000 (1 year), which is the value required for
|
||
HSTS preload list submission. Use a shorter value (e.g. 86400)
|
||
while testing so browsers forget the pin quickly.
|
||
'';
|
||
};
|
||
|
||
includeSubDomains = lib.mkOption {
|
||
type = lib.types.bool;
|
||
default = true;
|
||
description = ''
|
||
Whether to include `includeSubDomains` in the HSTS header.
|
||
Only disable this if the gateway host has sub-domains that
|
||
intentionally serve plain HTTP.
|
||
'';
|
||
};
|
||
};
|
||
};
|
||
}
|