docs
cairnobs.org Demo Source
Esc

Install · 4 of 8

HTTPS and addresses

Put the web interface on HTTPS: behind your own proxy, with certificate files, or with obs-beacond getting its own from Let's Encrypt or any ACME CA. And the two addresses hosts need to know.

2 min read

obs-beacond has two listeners, and they're set up differently:

Listener Serves HTTPS
listen The web interface, the browser's API, and install.sh for new hosts Plain HTTP unless you set tls, or a proxy in front does it
agent_listen Agents' reports Always TLS, with client certificates from obs-beacond's own CA. Never put a proxy that ends TLS in front of it

Passkeys and secure cookies need HTTPS on the web side, so set it up before anyone but you signs in. Pick one of the three ways below.

Behind your proxy

Keep obs-beacond on a local address and let nginx, HAProxy, Caddy or your load balancer end TLS:

listen: "127.0.0.1:8150"
agent_listen: ":8461"
alerts:
  public_url: https://obs.example.org

The proxy must send X-Forwarded-Proto: https, so obs-beacond knows the browser's connection is encrypted, and X-Forwarded-For. obs-beacond only believes X-Forwarded-For from a proxy on the same machine (a loopback address); from anywhere else it uses the connection's own address, so nobody can dodge the sign-in limits by sending the header themselves.

With the proxy on the same machine, listen can be a unix socket instead of a port: listen: unix:/run/obs-beacon/web.sock. The socket's folder decides who can connect. Agents can't reach a socket, so agent_listen is needed then.

Certificate files

listen: ":8443"
tls:
  cert: /etc/obs-beacon/tls/fullchain.pem
  key: /etc/obs-beacon/tls/privkey.pem

PEM files you renew yourself.

Its own certificate

Give obs-beacond a DNS name whose port 443 reaches it directly, and it gets and renews its own certificate:

listen: ":443"
tls:
  acme:
    hostnames: [obs.example.org]
    email: ops@example.org
    accept_terms: true
    http_listen: ":80"
Key What it's for
hostnames Required. The names on the certificate: real DNS names, not addresses. The first is the public address, and alerts.public_url defaults to it
accept_terms Required. true agrees to the CA's subscriber agreement (for Let's Encrypt, its repository)
email Where the CA sends expiry and problem notices. Optional
directory The ACME directory. Default Let's Encrypt; point it at step-ca, a staging server or any other ACME CA
ca_file PEM roots for a private ACME server's own HTTPS
http_listen For example ":80": answers HTTP-01 challenges and sends everything else to HTTPS
cache The account key and certificates. Default acme/ beside the database. Keep it: a new one means new certificates, and CAs limit how often

The CA checks the name by connecting back: TLS-ALPN-01 on listen, so port 443 of every name must reach obs-beacond with no proxy that ends TLS in between (a CDN's proxy included), and HTTP-01 on http_listen when port 80 reaches it. The packaged unit lets obs-beacond bind ports below 1024. It gets the certificate within seconds of starting, logs tls.acme: certificate for … or why not, and renews about 30 days before expiry.

The addresses hosts use

New hosts need to find both listeners:

Setting What it is Default
alerts.public_url The web address people use. Links in alerts point here, and over https:// it turns on passkeys With tls.acme, https:// its first host name
join.agent_url The agent listener as new hosts reach it, for example https://obs.example.org:8461 public_url's host with agent_listen's port

Set join.agent_url when agents come in another way: through an OpenShift Route on port 443, a load balancer, or a different name inside a VPN.

The agent port's certificate names the machine's host name and addresses. Agents don't check names: each pins the CA's fingerprint, which it learned when it joined. To add names for curl and other tools, list them in agent_tls.names.