Skip to main content
Version: 0.4

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 cert sends 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 sets proxy_required makes the servers refuse the same certificate from any other client. See Authenticate clients by certificate.

    tls:
    cert: server.pem
    key: server-key.pem
    ca: devices-ca.pem
    nats:
    proxy:
    seed: /etc/mq-gateway/proxy.nk
    amqp:
    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 generate prints now carry allow_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. 0s closes 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/compress 1.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?​

AreaAffects you ifWhere
Client permissionsGateway clients will make or answer requests with NATS servicesPermissions
_INBOX/ subscriptionsMQTT clients subscribe to topics under _INBOX/Interfaces
AMQP login failuresAn AMQP client or monitor reads the SASL outcome of a failed loginInterfaces
NATS connection countsDashboards or alerts count the gateway's NATS connections or connect eventsOperations

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:

  1. Add $MQG.reply.> to the subscribe allow list.
  2. Change $MQG.> to $MQG.alive.> in the publish and subscribe deny lists.
  3. 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's open, 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 connections shows 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.proxy and the cert auth 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.