Guides

HTTPS

How hostnames are routed to apps, and where TLS is terminated.

[proxy.http] in config.toml defines the host's single HTTP listener. It routes each request, by the hostname in the request, to the httpPort of the app that declares that hostname:

"hostnames": [{ "hostname": "app-1.example.com", "kind": "platform" }]

kind is platform or custom. It is a label for whatever writes desired.json; both kinds are routed the same way. An app that nothing needs to reach by name has an empty hostnames.

A request for a sleeping app wakes it. If desired.json names a hostname on a host with no [proxy.http] section, the instance is reported failed with that reason. The reference lists every key under [proxy].

An app's allocated HTTP host port is internal: only connections to it over loopback reach the guest. External HTTP requests must use the hostname proxy. Explicitly exposed raw ports are separate and do not pass through the HTTP proxy.

To require a signed token before an HTTP request can reach or wake the app, add an access policy.

Behind an edge

The installer writes plain HTTP. Use this when something in front of the host terminates TLS: Cloudflare, a load balancer, your own reverse proxy.

[proxy.http]
listen_address = "0.0.0.0"
port = 80

Fallback hostname

Reserve a hostname for a redirect with [proxy.http.fallback]:

[proxy.http.fallback]
origin_host = "fallback.apps.example.com"
redirect = "https://www.example.com/"

Requests for origin_host receive a 307 temporary redirect to redirect, without reaching or waking an app. The target is the exact configured URL; incoming paths and queries are not appended. It must be an absolute HTTP or HTTPS URL without credentials, on a different hostname to avoid a redirect loop.

The hostname is reserved even if an app declares it. Other platform and custom hostnames keep their normal routing. With Cloudflare for SaaS, customer requests retain their own Host header, so this redirect handles direct visits to the fallback name.

Omit the section to keep unknown hostnames returning 404. After changing it, run nibrunnerd start to apply the new configuration.

TLS on the host

Add [proxy.http.tls] with a PEM certificate and key:

[proxy.http]
listen_address = "0.0.0.0"
port = 443

[proxy.http.tls]
certificate = "/etc/nibrunner/tls/origin.crt"
key = "/etc/nibrunner/tls/origin.key"
  • One certificate for the whole host. There is no SNI selection. The certificate must cover every hostname of every app. In practice that means a wildcard, which matches one label: app.example.com but not a.b.example.com.
  • The daemon does not obtain certificates. Use certbot or the edge for ACME and renewal. The files are read once, at startup. After renewing, run systemctl restart nibrunnerd. This does not stop any app.
  • One listener only. You cannot run plain HTTP and TLS side by side. Nothing redirects between them, so two listeners would serve every app both ways.

Client certificates

Add [proxy.http.tls.client_ca] to require a client certificate on every TLS handshake. Use this when the origin's IP is discoverable and it must be reachable only through the edge:

[proxy.http.tls.client_ca]
certificate = "/etc/nibrunner/tls/origin-pull-ca.pem"

certificate is a PEM file holding every CA certificate to trust. Once enabled, you cannot reach the host yourself without a client certificate, so enable it after the plain setup works.

Note

If the TLS handshake names one app (SNI) and the HTTP request names another (Host), the proxy answers 421. This keeps apps that share a certificate separate.

On this page