v0.4.0
This release adds two ways to connect devices to NATS. Clients can log in with only a TLS certificate, and MQTT v5 clients can make and answer requests with NATS services. NATS monitoring now shows each client by its own name.
Features
-
Authenticate clients by certificate: A listener in auth mode
certsends the client's verified TLS certificate to NATS. Your auth callout service maps it to a NATS user. AMQP clients log in with SASL EXTERNAL. The gateway signs these connections as a trusted proxy of the NATS servers. A callout that setsproxy_requiredmakes the servers refuse the same certificate from any other client. See Authenticate clients by certificate.tls:cert: server.pemkey: server-key.pemca: devices-ca.pemnats:proxy:seed: /etc/mq-gateway/proxy.nkamqp:listeners:- { name: devices, addr: ":5671", auth: { mode: cert, username: cn } } -
Call NATS services from MQTT v5: A client that sets Request Response Information on connect gets a reply prefix of its own under
$MQG/reply/. The gateway refuses every other client a subscription under it. The client sends requests to a NATS service and reads the replies, and no other gateway client sees them. See Call NATS services from MQTT. -
Answer NATS requests from MQTT v5: A core NATS request reaches an MQTT v5 client with the requester's inbox as its Response Topic. The client permissions that
mq-gateway generateprints now carryallow_responses, so the client's reply reaches the requester. A request delivered from a stream still needs a publish grant on its reply subject. See Mapping to NATS.
Improvements
-
Clients named in NATS monitoring: Each client's NATS connection takes the name of its MQTT client ID or AMQP container-id. Connect events and the server's connection list show which client it is. When a client disconnects, its NATS connection stays open for
nats.idle-timeout(20 seconds by default) for the same client to take back.0scloses it with the client. An MQTT v5 client's connection with a delayed will stays open until the will is sent or canceled.nats:idle-timeout: 0s -
Patched dependencies: The release builds with Go 1.27.4 and
klauspost/compress1.20.4. Both fix advisories that container image scans report against the earlier versions.
Considerations
A 0.3.0 config file starts 0.4.0 unchanged, and everything that worked in
0.3.0 keeps working. The new request/reply features need the client
permissions that 0.4.0's generate prints. A few behaviors that clients or
monitoring can see changed.
Does this affect you?
| Area | Affects you if | Where |
|---|---|---|
| Client permissions | Gateway clients will make or answer requests with NATS services | Permissions |
_INBOX/ subscriptions | MQTT clients subscribe to topics under _INBOX/ | Interfaces |
| AMQP login failures | An AMQP client or monitor reads the SASL outcome of a failed login | Interfaces |
| NATS connection counts | Dashboards or alerts count the gateway's NATS connections or connect events | Operations |
Permissions
The 0.3.0 client permissions deny client users every $MQG.> subject and
have no allow_responses. With them, NATS refuses the subscription under
a client's reply prefix, and refuses a client's reply to a core NATS
request. Nothing else changes.
To use either feature, make three edits to each client user's permissions. Keep the grants you narrowed or added:
- Add
$MQG.reply.>to thesubscribeallow list. - Change
$MQG.>to$MQG.alive.>in thepublishandsubscribedeny lists. - Add
allow_responses: true.
mq-gateway generate --config gateway.yaml --format nats-server prints
the client permissions with all three, to compare against yours.
Interfaces
- The gateway refuses subscriptions under
_INBOX/. It accepted these in 0.3.0, but they never received a reply. An MQTT client that picks reply topics there now gets its subscription refused. Use the reply prefix from Response Information instead. - AMQP login failures arrive after the
open. The gateway now connects to NATS after the client'sopen, so a credential that NATS refuses no longer fails the SASL exchange. The SASL exchange succeeds, then the gateway closes the connection with an error. The same applies when the gateway cannot serve the client's account. See Errors for what the client sees.
Operations
- Idle NATS connections close sooner. In 0.3.0, a NATS connection
stayed open for 5 minutes after its client left, for any client with the
same credential. It now stays open for 20 seconds, for the same client
only. The gateway's NATS connection count follows the connected clients
more closely. To keep connections longer, set
nats.idle-timeout.
After you upgrade
nats server report connectionsshows each client's NATS connection by its client ID or container-id.- To roll back, first remove the keys that are new in 0.4.0 from the
config file:
nats.idle-timeout,nats.proxyand thecertauth mode. 0.3.0 refuses to start with them. Then run the 0.3.0 binary. Sessions and retained messages keep the same format, and the 0.4.0 client permissions need no change. Clients lose the reply prefix and certificate login.