Web Interface

The Statusengine Web Interface, or seid (Statusengine Interface Daemon), is what people look at. It reads the monitoring data the worker writes into MySQL, and sends external commands back through the worker so operators can acknowledge a problem, schedule a downtime or force a check without touching a command pipe.

It ships as a single binary with the frontend compiled into it. There is no PHP, no web server to configure around it and no build step: download, configure, run. Every page works on a phone, which is where most people read it at three in the morning.

Dashboard

Availability, unhandled problems, how much moved in the last 24 hours, and what has been broken longest

Services

Every service, sorted by severity, with filters that live in the URL

Service detail

Plugin output, check settings, performance data and the commands you can send

Command log

Every command anybody submitted, refusals included, with the payload as it was sent

Requirements

Nothing else. No PHP, no Composer, no Node.js on the server, no separate web server unless you want one in front for TLS.

Download

Releases are published at github.com/statusengine/interface ↗ . Each one carries an archive per platform and a SHA256SUMS file.

VERSION=4.0.0
ARCH=$(uname -m | sed -e 's/x86_64/amd64/' -e 's/aarch64/arm64/')
BASE=https://github.com/statusengine/interface/releases/download/v$VERSION

wget $BASE/seid_v${VERSION}_linux_${ARCH}.tar.gz
wget $BASE/SHA256SUMS
sha256sum -c SHA256SUMS --ignore-missing

$ sha256sum -c SHA256SUMS --ignore-missing
seid_v4.0.0_linux_amd64.tar.gz: OK

Unpack it and check what you got:

tar xzf seid_v${VERSION}_linux_${ARCH}.tar.gz
cd seid_v${VERSION}_linux_${ARCH}
./seid version

The archive holds three files: the seid binary, seid.example.yaml and the README.

Install

The interface needs a user to run as, a place for its configuration, and nothing else.

sudo useradd --system --no-create-home --shell /usr/sbin/nologin statusengine-interface
sudo install -m 0755 seid /usr/local/bin/seid
sudo mkdir -p /etc/statusengine
sudo install -m 0640 seid.example.yaml /etc/statusengine/seid.yaml
sudo chown root:statusengine-interface /etc/statusengine/seid.yaml

The systemd unit

[Unit]
Description=Statusengine Web Interface
Documentation=https://statusengine.org/docs/interface/
After=network-online.target mysql.service
Wants=network-online.target

[Service]
Type=simple
User=statusengine-interface
Group=statusengine-interface
ExecStart=/usr/local/bin/seid serve -config /etc/statusengine/seid.yaml
Restart=on-failure
RestartSec=5s

# It serves HTTP and talks to MySQL and the worker. Nothing else is needed,
# so nothing else is allowed.
NoNewPrivileges=true
PrivateTmp=true
PrivateDevices=true
ProtectSystem=strict
ProtectHome=true
ProtectKernelTunables=true
ProtectControlGroups=true
RestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX
MemoryDenyWriteExecute=true

[Install]
WantedBy=multi-user.target

Do not enable it yet. It needs a database and an account first.

The database

The interface reads the tables the worker writes (statusengine_*) and owns five small tables of its own, all prefixed sei_: accounts, roles, sessions, the schema version and the command audit. It never writes to the worker’s tables.

Give it its own account rather than reusing the worker’s:

CREATE USER 'statusengine-interface'@'localhost' IDENTIFIED BY 'a long random password';
GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, INDEX, DROP
  ON statusengine.* TO 'statusengine-interface'@'localhost';
FLUSH PRIVILEGES;

The sei_* tables are created on the first start. You can also apply them separately, which is the better choice if your deployment prefers migrations as their own step:

sudo -u statusengine-interface seid migrate -config /etc/statusengine/seid.yaml

Migrations run under a MySQL advisory lock, so two instances starting at the same moment cannot half-apply a schema.

Configure

Every setting can be given four ways, and they resolve in this order:

command line flag  >  environment variable  >  config file  >  built-in default

Environment variables are the key in upper case with an SEI_ prefix, for example SEI_LISTEN_ADDR. /etc/statusengine/seid.yaml is the usual place; the example file that comes with the release documents every setting.

The only required setting is mysql_dsn. A useful minimum adds the two keys the worker expects:

mysql_dsn: statusengine-interface:a long random password@tcp(127.0.0.1:3306)/statusengine?parseTime=true

worker_command_key: "the key from the worker's config"
worker_events_key: "the other key from the worker's config"

What the settings do

The server

The database

The worker

The two keys are different keys on different ports. Take them from the worker’s own configuration:

# Grants reading the event stream -> worker_events_key
api_keys:
  - a-key-for-the-interface

# Grants controlling the monitoring core -> worker_command_key
command_api_keys:
  - a-different-key-for-the-interface

The worker keeps the two lists separate on purpose, with no overlap in either direction: one grants reading events, the other grants controlling the monitoring core.

Performance data

Create the first account

There is no default administrator and no default password. Make the first one by hand:

sudo -u statusengine-interface seid user create \
  -config /etc/statusengine/seid.yaml \
  -username admin -role admin

Omitting -password prompts for one, which keeps it out of your shell history.

What the three roles can do:

Passwords are hashed with argon2id. The session cookie carries a random token and the database stores only its SHA-256, so a dump of sei_sessions is not a set of live credentials.

Start it

sudo systemctl daemon-reload
sudo systemctl enable --now statusengine-interface
sudo systemctl status statusengine-interface

$ curl -s localhost:8090/api/v1/readyz
{"status":"ok","checks":{"mysql":"ok","worker_commands":"configured","worker_events":"configured"}}

/api/v1/healthz answers as soon as the process is up; /api/v1/readyz also says whether the database and the worker are reachable, which is the one to point a health check at.

The log says what is on and what is not:

level=INFO msg="listening" addr=127.0.0.1:8090
level=WARN msg="external commands are disabled: set worker_command_key to enable them"

Put it behind a web server

The interface binds to loopback by default, which means something has to sit in front of it to terminate TLS. Both examples below pass the event stream through unbuffered — without that, live updates arrive in bursts of several minutes.

server {
    listen 443 ssl;
    server_name monitoring.example.org;

    ssl_certificate     /etc/letsencrypt/live/monitoring.example.org/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/monitoring.example.org/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8090;
        proxy_set_header Host              $host;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # The event stream is a long-lived response. Buffering it holds
        # every change until the buffer fills.
        proxy_buffering off;
        proxy_read_timeout 1h;
    }
}

<VirtualHost *:443>
    ServerName monitoring.example.org

    SSLEngine on
    SSLCertificateFile    /etc/letsencrypt/live/monitoring.example.org/fullchain.pem
    SSLCertificateKeyFile /etc/letsencrypt/live/monitoring.example.org/privkey.pem

    ProxyPreserveHost On
    ProxyPass        / http://127.0.0.1:8090/ flushpackets=on timeout=3600
    ProxyPassReverse / http://127.0.0.1:8090/
    RequestHeader set X-Forwarded-Proto "https"
</VirtualHost>

Then tell the interface that the browser is on TLS:

secure_cookies: true

The interface honours X-Forwarded-For only when the request arrives from a loopback or private address, so a header from the open internet cannot forge the address that rate limits are counted against.

Demo mode

Demo mode offers an account on the login page that signs in with one click. It is how demo.statusengine.org ↗ works.

demo_mode: true
demo_user: guest

By default that account can only read, and every command it submits is refused. A deployment that wants visitors to try commands names them one by one:

demo_commands: [acknowledge, downtime, reschedule]
demo_command_rate_limit: 10   # per visitor per minute
demo_max_targets: 25          # objects one command may address

The login page lists exactly what it allows, generated from the same configuration the server enforces. If the two disagree, the configuration is not what you think it is.

Two more settings matter when strangers can reach the interface:

audit_client_ip: false      # keep the command log, without visitors' addresses
audit_retention_days: 30    # 0 keeps every command forever

Upgrading

Replace the binary and restart. Pending migrations are applied at startup.

sudo systemctl stop statusengine-interface
sudo install -m 0755 seid /usr/local/bin/seid
sudo systemctl start statusengine-interface

Sessions survive an upgrade; they live in the database, not in memory. The sei_* schema only ever gains things, and the worker’s tables are never touched by a migration.

When something does not work

level=WARN msg="external commands are disabled: set worker_command_key to enable them"

Uninstall

sudo systemctl disable --now statusengine-interface
sudo rm /etc/systemd/system/statusengine-interface.service /usr/local/bin/seid
sudo rm /etc/statusengine/seid.yaml

The sei_* tables stay behind. Drop them if you are not coming back:

DROP TABLE sei_command_audit, sei_sessions, sei_users, sei_roles, sei_schema_migrations;

Nothing the worker wrote is affected.