CNCF and Synadia Align on Securing the Future of the NATS.io Project. Read the joint press release.
NATS Docs
NATS.ioNATS by ExampleGitHubSlackTwitter
  • Welcome
  • Release Notes
    • What's New!
      • NATS 2.11
      • NATS 2.10
      • NATS 2.2
      • NATS 2.0
  • NATS Concepts
    • Overview
      • Compare NATS
    • What is NATS
      • Walkthrough Setup
    • Subject-Based Messaging
    • Core NATS
      • Publish-Subscribe
        • Pub/Sub Walkthrough
      • Request-Reply
        • Request-Reply Walkthrough
      • Queue Groups
        • Queueing Walkthrough
    • JetStream
      • Streams
      • Source and Mirror Streams
        • Example
      • Consumers
        • Example
      • JetStream Walkthrough
      • Key/Value Store
        • Key/Value Store Walkthrough
      • Object Store
        • Object Store Walkthrough
      • Headers
    • Subject Mapping and Partitioning
    • NATS Service Infrastructure
      • NATS Adaptive Deployment Architectures
    • Security
    • Connectivity
  • Using NATS
    • NATS Tools
      • nats
        • nats bench
      • nk
      • nsc
        • Basics
        • Streams
        • Services
        • Signing Keys
        • Revocation
        • Managed Operators
      • nats-top
        • Tutorial
    • Developing With NATS
      • Anatomy of a NATS application
      • Connecting
        • Connecting to the Default Server
        • Connecting to a Specific Server
        • Connecting to a Cluster
        • Connection Name
        • Authenticating with a User and Password
        • Authenticating with a Token
        • Authenticating with an NKey
        • Authenticating with a Credentials File
        • Encrypting Connections with TLS
        • Setting a Connect Timeout
        • Ping/Pong Protocol
        • Turning Off Echo'd Messages
        • Miscellaneous functionalities
        • Automatic Reconnections
          • Disabling Reconnect
          • Set the Number of Reconnect Attempts
          • Avoiding the Thundering Herd
          • Pausing Between Reconnect Attempts
          • Listening for Reconnect Events
          • Buffering Messages During Reconnect Attempts
        • Monitoring the Connection
          • Listen for Connection Events
          • Slow Consumers
      • Receiving Messages
        • Synchronous Subscriptions
        • Asynchronous Subscriptions
        • Unsubscribing
        • Unsubscribing After N Messages
        • Replying to a Message
        • Wildcard Subscriptions
        • Queue Subscriptions
        • Draining Messages Before Disconnect
        • Receiving Structured Data
      • Sending Messages
        • Including a Reply Subject
        • Request-Reply Semantics
        • Caches, Flush and Ping
        • Sending Structured Data
      • Building Services
      • JetStream
        • JetStream Model Deep Dive
        • Managing Streams and consumers
        • Consumer Details
        • Publishing to Streams
        • Using the Key/Value Store
        • Using the Object Store
      • Tutorials
        • Advanced Connect and Custom Dialer in Go
    • Running Workloads on NATS
      • Getting Started
        • Installing Nex
        • Building a Service
        • Starting a Node
        • Deploying Services
        • Building a Function
        • Deploying Functions
      • Host Services
        • Javascript | V8
      • Nex Internals
        • Architecture Overview
        • Node Process
        • Nex Agent
        • No Sandbox Mode
        • Root File System
        • Control Interface
      • FAQ
  • Running a NATS service
    • Installing, running and deploying a NATS Server
      • Installing a NATS Server
      • Running and deploying a NATS Server
      • Windows Service
      • Flags
    • Environmental considerations
    • NATS and Docker
      • Tutorial
      • Docker Swarm
      • Python and NGS Running in Docker
      • JetStream
      • NGS Leaf Nodes
    • NATS and Kubernetes
    • NATS Server Clients
    • Configuring NATS Server
      • Configuring JetStream
        • Configuration Management
          • NATS Admin CLI
          • Terraform
          • GitHub Actions
          • Kubernetes Controller
      • Clustering
        • Clustering Configuration
        • v2 Routes
        • JetStream Clustering
          • Administration
          • Troubleshooting
      • Super-cluster with Gateways
        • Configuration
      • Leaf Nodes
        • Configuration
        • JetStream on Leaf Nodes
      • Securing NATS
        • Enabling TLS
        • Authentication
          • Tokens
          • Username/Password
          • TLS Authentication
            • TLS Authentication in clusters
          • NKeys
          • Authentication Timeout
          • Decentralized JWT Authentication/Authorization
            • Account lookup using Resolver
            • Memory Resolver Tutorial
            • Mixed Authentication/Authorization Setup
        • Authorization
        • Multi Tenancy using Accounts
        • OCSP Stapling
        • Auth Callout
      • Logging
      • Enabling Monitoring
      • MQTT
        • Configuration
      • Configuring Subject Mapping
      • System Events
        • System Events & Decentralized JWT Tutorial
      • WebSocket
        • Configuration
    • Managing and Monitoring your NATS Server Infrastructure
      • Monitoring
        • Monitoring JetStream
      • Managing JetStream
        • Account Information
        • Naming Streams, Consumers, and Accounts
        • Streams
        • Consumers
        • Data Replication
        • Disaster Recovery
        • Encryption at Rest
      • Managing JWT Security
        • In Depth JWT Guide
      • Upgrading a Cluster
      • Slow Consumers
      • Signals
      • Lame Duck Mode
      • Profiling
  • Reference
    • FAQ
    • NATS Protocols
      • Protocol Demo
      • Client Protocol
        • Developing a Client
      • NATS Cluster Protocol
      • JetStream wire API Reference
    • Roadmap
    • Contributing
  • Legacy
    • nats-account-server
Powered by GitBook
On this page
  • Available Events and Services
  • System Account
  • Local Configuration

Was this helpful?

Edit on GitHub
Export as PDF
  1. Running a NATS service
  2. Configuring NATS Server

System Events

PreviousConfiguring Subject MappingNextSystem Events & Decentralized JWT Tutorial

Last updated 7 months ago

Was this helpful?

NATS servers leverage support and generate events such as:

  • account connect/disconnect

  • authentication errors

  • server shutdown

  • server stat summary

In addition the server supports a limited number of requests that can be used to query for account connections, server stat summaries, and pinging servers in the cluster.

These events are enabled by configuring system_account and using a system account user.

are used so that subscriptions from your applications, say >, do not receive system events and vice versa. Using accounts requires either:

  • and listing one of the accounts in system_account

  • Or by using decentralized authentication and authorization via as shown in this . In this case system_account contains the account public key.

N.B. The default global account $G does not publish advisories.

Available Events and Services

System Account

The system account publishes messages under well known subject patterns.

Server initiated events:

  • $SYS.ACCOUNT.<id>.CONNECT (client connects)

  • $SYS.ACCOUNT.<id>.DISCONNECT (client disconnects)

  • $SYS.ACCOUNT.<id>.SERVER.CONNS (connections for an account changed)

  • $SYS.SERVER.<id>.CLIENT.AUTH.ERR (authentication error)

  • $SYS.SERVER.<id>.STATSZ (stats summary)

  • $SYS.REQ.SERVER.<id>.STATSZ (request server stat summary)

  • $SYS.REQ.SERVER.PING (discover servers - will return multiple messages)

  • $SYS.REQ.SERVER.<id>.<endpoint-name> (request server monitoring endpoint corresponding to endpoint name.)

  • $SYS.REQ.SERVER.PING.<endpoint-name> (from all server, request server monitoring endpoint corresponding to endpoint name - will return multiple messages)

Endpoint
Endpoint Name

VARZ

CONNZ

ROUTEZ

GATEWAYZ

LEAFZ

SUBSZ

JSZ

ACCOUNTZ

HEALTHZ

  • "$SYS.REQ.ACCOUNT.<account-id>.<endpoint-name>(from all server, request account specific monitoring endpoint corresponding to account id and endpoint name - will return multiple messages)

Endpoint
Endpoint Name

CONNZ

LEAFZ

SUBSZ

JSZ

INFO

Servers like nats-account-server publish system account messages when a claim is updated, the nats-server listens for them, and updates its account information accordingly:

  • $SYS.ACCOUNT.<id>.CLAIMS.UPDATE

With these few messages you can build useful monitoring tools:

  • health/load of your servers

  • client connects/disconnects

  • account connections

  • authentication errors

Local Configuration

To make use of System events, just using accounts, your configuration can look like this:

accounts: {
    USERS: {
        users: [
            {user: a, password: a}
        ]
    },
    SYS: { 
        users: [
            {user: admin, password: changeit}
           ]
    },
}
system_account: SYS

In addition other tools with system account privileges, can initiate requests (Examples can be found ):

as listed in the table below are accessible as system services using the following subject pattern:

Please note that applications now have to authenticate such that a connection can be associated with an account. In this example username and password were chosen for simplicity of the demonstration. Subscribe to all system events like this nats sub -s nats://admin:changeit@localhost:4222 ">" and observe what happens when you do something like nats pub -s "nats://a:a@localhost:4222" foo bar. Examples on how to use system services can be found .

Monitoring endpoints
Accounts
Accounts
jwt
Tutorial
subscribing/requesting
Configuring authentication locally
Health
here
here
General Server Information
Connections
Routing
Gateways
Leaf Nodes
Subscription Routing
JetStream
Accounts
Connections
Leaf Nodes
Subscription Routing
JetStream
Account