Configuration

This page shows where the broker's configuration lives and how to make the common changes: users and subject permissions, passwords, network access and certificates. Edit the files as root, check the configuration, then restart.

Where things live

Path	What it is
/etc/nats/nats-server.conf	Server configuration, including users and their bcrypt password hashes. Created on first boot.
/etc/nats/credentials/	Plaintext passwords of the example users, one file per user. Root only.
/etc/nats/tls/	CA and server certificates and keys.
/usr/local/share/sushi/nats/ca.pem	Public copy of the CA certificate, for clients.
/var/lib/nats	Server state, such as the PID file.

The server reads only the bcrypt hashes in nats-server.conf. The plaintext password files are there so you, and the helper client, can authenticate.

Apply a change

Check the configuration before you restart, so a typo does not stop the broker:

sudo nats-server -t -c /etc/nats/nats-server.conf
sudo systemctl restart nats-server

Users and permissions

First boot creates three example users. Anything not allowed is denied.

User	May publish	May subscribe
publisher	sushi.pilot.>	_INBOX.>
subscriber	_INBOX.>	sushi.pilot.>
denied	sushi.denied.>	sushi.denied.>

_INBOX.> is what request/reply uses: the requester receives replies on an inbox subject, and the responder publishes to it. The denied user exists to show what a permissions violation looks like.

Add a user

1. Create a password and print its bcrypt hash. The hash is not secret; the password is:

   sudo bash -euo pipefail <<'NEWUSER'
   umask 077
   user=<user-name>
   openssl rand -base64 24 > "/etc/nats/credentials/${user}.password"
   PASSWORD=$(tr -d '\n' < "/etc/nats/credentials/${user}.password") nats server passwd
   NEWUSER
   

2. Add the user to the users list in /etc/nats/nats-server.conf, with the hash and the subjects it needs:

   {
     user: <user-name>
     password: "<bcrypt-hash>"
     permissions: {
       publish: { allow: ["orders.>"] }
       subscribe: { allow: ["orders.>", "_INBOX.>"] }
     }
   }
   

3. Check the configuration and restart, as in Apply a change.

The helper /opt/sushi/bin/nats-as.sh works only with the three example users. For your own users, pass the password to the nats CLI or your client library through the environment or a secret store, not on the command line.

To retire an example user, remove it from nats-server.conf, then check and restart. Keep its password file: the first-boot check expects all three example password files to be present.

Change a password

Write a new password file for the user, print its hash with nats server passwd as above, replace that user's password value in nats-server.conf, then check and restart.

Reach NATS from your VPC

By default the broker listens on 127.0.0.1 only. You have two options:

• Keep it on loopback and put a proxy or port forward in front of it, for example Session Manager port forwarding as shown in Getting started.
• Listen on the private address. Change listen to the instance's private address, allow TCP 4222 in the security group only from your clients' security group, and issue a server certificate that includes that address (see below).

Keep it private

Do not listen on 0.0.0.0 with an open security group. Do not set no_auth_user, and do not turn TLS off.

The monitoring port, 8222, serves plain HTTP. Keep it on 127.0.0.1.

Issue a server certificate for a private address

The certificate created on first boot covers only localhost and 127.0.0.1. This signs a new one with the instance's own CA, with your private address added. Replace <private-ip> before you run it:

sudo bash -euo pipefail <<'CERT'
cd /etc/nats/tls
ip=<private-ip>
umask 077
openssl genrsa -out server.key.new 2048
openssl req -new -key server.key.new -out server.csr -subj '/CN=localhost'
printf 'subjectAltName=DNS:localhost,IP:127.0.0.1,IP:%s\n' "$ip" > san.ext
openssl x509 -req -in server.csr -CA ca.pem -CAkey ca.key -CAcreateserial \
  -days 825 -sha256 -out server.pem.new -extfile san.ext
rm -f server.csr san.ext ca.srl
mv server.key.new server.key
mv server.pem.new server.pem
chown root:nats server.key server.pem
chmod 0640 server.key && chmod 0644 server.pem
CERT
sudo systemctl restart nats-server

The certificates created on first boot are valid for 825 days. You can use the same commands, without the extra address, to renew the server certificate.

Client certificates

The default identity is a user name and password over TLS. Requiring client certificates (verify and verify_and_map in the tls block) is a change you make yourself; see the NATS documentation.

JetStream

JetStream is off, and this image is supported as a Core NATS broker. Turning JetStream on changes what you need to store, size and back up.