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.
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.