Operations¶

This page covers running the broker day to day: how it is secured, monitoring, service management, logs, backups, updates and support.

Security model¶

Loopback and TLS. Clients connect to tls://127.0.0.1:4222. The monitoring endpoint listens on 127.0.0.1:8222.
No anonymous access. Every client needs a user name and password, and each user may use only the subjects it is allowed. Anything else is denied.
Per-instance secrets. The CA, server certificate and passwords are created on first boot. The image contains none of them.
File permissions. The plaintext passwords in /etc/nats/credentials/ are readable by root only; the server itself reads only bcrypt hashes. The ubuntu user cannot read the configuration or the private keys. Clients use the public CA copy in /usr/local/share/sushi/nats/ca.pem.
Service sandbox. The nats-server service runs as the nats user, can write only to /var/lib/nats, and cannot change its certificates or keys.

Monitoring¶

The monitoring endpoint answers on the instance:

curl -s http://127.0.0.1:8222/healthz
curl -s http://127.0.0.1:8222/varz

/healthz returns {"status":"ok"} when the server is healthy. /varz reports the version, connections and message counts. See the NATS documentation for the other endpoints.

Manage the service¶

sudo systemctl status nats-server
sudo systemctl restart nats-server

The first-boot service, sushi-nats-core-firstboot, runs before nats-server on every boot. On later boots it checks that the configuration, certificates and password files are all present and valid; it never replaces part of an existing identity.

Logs¶

NATS logs to the systemd journal:

sudo journalctl -u nats-server -n 100 --no-pager

Backups¶

Core NATS does not store application messages, so there is no message data to back up. To keep this instance's identity, back up /etc/nats/ and /var/lib/nats/ together. They hold the configuration, bcrypt hashes, plaintext passwords and TLS material.

To move to a replacement instance, launch it, copy those directories with their root ownership and permissions preserved, then point clients at the new host. Practise the restore once before you depend on it.

Updates¶

Ubuntu packages receive unattended security updates.
NATS Server and the nats CLI are pinned binaries and are not updated by apt. A new release comes as a new version of the image. Running instances are not migrated: launch the new version, copy your configuration and identity as above, and switch clients over.

Support¶

Software Sushi supports the packaging, first-boot setup and this documentation. Email info@softwaresushi.com with your NATS version (nats-server -v), what you ran and the error. Never include passwords or private keys. Support coverage beyond installation questions requires a separate agreement. Synadia and the NATS project do not provide support for this image.