Metrics and Status

Vexillum provides two different ways to expose runtime information:

• The public status interface, intended for users and communities.
• The metrics listener, intended for operators and monitoring systems.

These serve different purposes and should usually have different exposure rules. The public status interface can be safely shown to users when configured appropriately. The metrics listener should normally remain private.

Metrics listener

The metrics listener is intended for monitoring and observability.

Metrics are useful for operators who want to track runtime behavior, service health, traffic patterns, and mode activity over time.

A typical metrics listener default is:

[metrics]
listen = "127.0.0.1:9090"

Binding metrics to localhost keeps them private by default. That is usually the right choice unless you have a dedicated monitoring network, reverse proxy, VPN, or firewall rules protecting access.

Public status versus metrics

The public status interface and metrics listener should not be treated as the same thing.

Surface	Audience	Typical exposure	Purpose
Public status interface	Users and communities	Public or semi-public	Human-readable reflector status
Metrics listener	Operators and monitoring systems	Private	Machine-readable monitoring data
Admin interface	Operators	Private	Management and configuration

The public status interface answers questions like:

• Which modes are available?
• Is the reflector online?
• What services does this deployment provide?
• Where should users connect?

The metrics listener answers questions like:

• Is the process healthy?
• Are mode instances running?
• How much activity is happening?
• Are errors increasing?
• Did traffic suddenly drop?
• Is something behaving strangely?

Recommended exposure model

A safe deployment usually exposes services like this:

Service	Recommended exposure
Protocol listeners	Public if the reflector is intended for public use
Public status interface	Public or community-facing
Admin interface	Private, VPN, SSH tunnel, or reverse proxy protected
Metrics listener	Private or monitoring-only

Avoid exposing the metrics listener directly to the public internet. Metrics can reveal operational details that are useful to operators and occasionally useful to people whose hobbies need better parental supervision.

Example local metrics configuration

For a local-only metrics listener:

[metrics]
listen = "127.0.0.1:9090"

This allows monitoring tools on the same host to scrape metrics without exposing the listener externally.

Example private network metrics configuration

For a private monitoring network:

[metrics]
listen = "10.10.0.25:9090"

Use a specific private interface address when metrics should only be reachable from a monitoring VLAN, VPN, or private management network.

Example public status configuration

The public status interface may be exposed through a reverse proxy such as Caddy, nginx, or Traefik.

A typical deployment might expose the public site on HTTPS:

https://vexillum.example.net/

while keeping the admin and metrics listeners private:

127.0.0.1:8080
127.0.0.1:9090

This gives users a useful status page without handing them the control panel like civilization has learned nothing.

Reverse proxy recommendations

When using a reverse proxy:

• Terminate TLS at the proxy.
• Expose the public status interface publicly.
• Restrict the admin interface by VPN, IP allowlist, authentication, or private network.
• Keep the metrics listener private unless your monitoring system needs proxy access.
• Avoid publishing raw metrics unless you have a specific reason.
• Use clear hostnames for public and admin access.

Example hostname layout:

Hostname	Purpose
vexillum.example.net	Public status interface
admin.vexillum.example.net	Admin interface, restricted
metrics.vexillum.example.net	Metrics, restricted or internal only

Do not put all three surfaces behind the same access policy unless you enjoy solving self-inflicted security puzzles.

Health checks

Operators should configure service health checks where possible.

Health checks can be used by:

• systemd watchdogs
• reverse proxies
• load balancers
• monitoring systems
• external uptime checks
• deployment automation

A health check should answer one basic question:

Is the Vexillum process alive and able to serve requests?

A health check does not necessarily prove that every reflector mode is healthy, reachable, or correctly configured. It only proves that the checked service is responding. Useful, but not magic. Humans keep trying to outsource judgment to endpoints named /health.

What to monitor

Useful things to monitor include:

• Process uptime
• Admin or public web availability
• Metrics scrape success
• Enabled mode instance state
• Listener availability
• Packet or session activity
• Authentication failures
• Error counts
• Unexpected restarts
• Disk usage for storage and logs
• Memory and CPU usage
• Network traffic on protocol ports

For a public reflector, also consider monitoring from outside your network so you know whether users can actually reach the exposed services.

Checking listeners manually

Use ss to confirm which ports Vexillum is listening on:

ss -ltnup | grep vexillum

If the process name does not appear, search by port:

ss -ltnup | grep -E '8080|9090|17000|42000|43000|43001'

This can help confirm whether the configured services actually started and which addresses they are bound to.

Checking the admin or public interface

Use curl to test HTTP listeners:

curl -v http://127.0.0.1:8080/

For metrics:

curl -v http://127.0.0.1:9090/

If a service is bound to 127.0.0.1, it will only be reachable from the same machine unless you use a tunnel or reverse proxy.

Common status problems

The public page is not reachable

Check:

• Is Vexillum running?
• Is the public listener enabled?
• Is the listener bound to the expected address?
• Is the reverse proxy pointing to the correct port?
• Is the firewall allowing inbound traffic?
• Is DNS pointing to the correct host?
• Is TLS configured correctly?

Metrics are not reachable

Check:

• Is the metrics listener enabled?
• Is it bound to 127.0.0.1 or a private address?
• Are you testing from the same host?
• Is a firewall blocking access?
• Is your monitoring system scraping the correct URL?
• Are you accidentally trying to access private metrics from a public network?

Admin works locally but not remotely

This usually means the admin listener is bound to localhost:

[admin]
listen = "127.0.0.1:8080"

That is expected. Use an SSH tunnel, VPN, reverse proxy, or private listener address if remote administration is required.

A mode port is open but clients cannot connect

Check:

• The mode instance is enabled.
• The listener is bound to the expected address.
• The firewall allows the protocol and port.
• NAT forwards the correct protocol, UDP or TCP.
• The client is using the correct reflector address.
• The mode-specific configuration matches what the client expects.
• Logs show whether packets or sessions are arriving.

For UDP modes, remember that a port can appear open from the server side while clients still fail due to NAT, firewall, or routing problems. UDP remains the internet’s way of saying “maybe.”

Suggested monitoring layout

A practical deployment might use:

Tool	Purpose
systemd	Process supervision
journalctl	Runtime logs
Prometheus-compatible scraper	Metrics collection
Grafana	Dashboards
Uptime monitor	Public web availability
Reverse proxy health checks	Web listener health
External UDP checks	Protocol reachability, where practical

The exact tooling matters less than having enough visibility to know whether Vexillum is healthy before users start reporting “it doesn’t work” with the diagnostic precision of a foghorn.

Operational checklist

Before publishing a Vexillum deployment:

• Confirm the public status page loads.
• Confirm admin access is restricted.
• Confirm metrics are private.
• Confirm enabled protocol ports are listening.
• Confirm firewall and NAT rules match enabled modes.
• Confirm monitoring can reach the metrics listener.
• Confirm logs are available after restart.
• Confirm storage is persistent.
• Confirm backup coverage includes configuration and storage.
• Confirm public documentation shows the correct connection details.

Current status

Metrics and status behavior may continue to evolve while Vexillum is under active development. Operators should review the current example configuration and release notes when upgrading.