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
  • leafnodes Configuration Block
  • TLS Block
  • Accepting side
  • Remote side
  • Authorization Block
  • Users Block
  • LeafNode remotes Entry Block
  • Signature Handler
  • Connecting using WebSocket protocol
  • tls Configuration Block

Was this helpful?

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

Configuration

leafnodes Configuration Block

The leaf node configuration block is used to configure incoming as well as outgoing leaf node connections. Most properties are for the configuration of incoming connections. The properties remotes and reconnect are for outgoing connections.

Property
Description

host

Interface where the server will listen for incoming leafnode connections.

port

Port where the server will listen for incoming leafnode connections (default is 7422).

listen

Combines host and port as <host>:<port>

tls

advertise

Hostport <host>:<port> to advertise how this server can be contacted by leaf nodes. This is useful in cluster setups with NAT.

no_advertise

if true the server shouldn't be advertised to leaf nodes.

authorization

remotes

reconnect

Interval in seconds at which reconnect attempts to a remote server are made.

compression

TLS Block

As of NATS v2.10.0

The tls block for leafnodes configuration has an additional field enabling a TLS-first handshake between the remote and the accepting server.

Property
Description

handshake_first

If true on the accepting side, remote leafnodes are required to also have this setting configured in the remotes section.

Accepting side

Since Leafnodes can connect to a variety of servers, the ability to indicate if the TLS handshake should be done first is configured in 2 places. The accepting side is in the tls block of the leafnodes block.

leafnodes {
  port: 7422
  tls {
    handshake_first: true
    # other TLS fields...
  }
}

With the above configuration, an older server, or a server that does not have the remote configuration also configured with handshake_first: true, will fail to create a leafnode connection because the accepting-side server will initiate the TLS handshake while the soliciting side will wait for the INFO protocol to be received.

Remote side

To indicate that a leafnode connection should perform the TLS handshake first, it needs to be configured in the remote configuration:

leafnodes {
  remotes [
    {
      urls: ["tls://example:7422"]
      tls: {
         handshake_first: true
         # other TLS fields...
      }
    }
  ]
}

If the remote is configured as such but the server it is connecting to does not have handshake_first: true configured, the connection will fail since the solicit side is performing a TLS handshake but will receive an INFO protocol in clear.

Authorization Block

A leaf node can authenticate against any user account on the hub (the incoming side of the connection), including those defined in the accounts themselves. This authorization block is therefore optional if appropriate account users already exist.

Whether configuring users in the account or in this dedicated authorization block is more convenient will depend on your deployment style.

Property
Description

user

Username for the leaf node connection.

password

Password for the user entry.

account

timeout

Maximum number of seconds to wait for leaf node authentication.

users

Users Block

Property
Description

user

Username for the leaf node connection.

password

Password for the user entry.

account

Here are some examples of using basic user/password authentication for leaf nodes (note while this is using accounts it is not using JWTs)

Singleton mode:

leafnodes {
  port: ...
  authorization {
    user: leaf
    password: secret
    account: TheAccount
  }
}

With above configuration, if a soliciting server creates a Leafnode connection with url: nats://leaf:secret@host:port, then the accepting server will bind the leafnode connection to the account "TheAccount". This account needs to exist otherwise the connection will be rejected.

Multi-users mode:

leafnodes {
  port: ...
  authorization {
    users = [
      {user: leaf1, password: secret, account: account1}
      {user: leaf2, password: secret, account: account2}
    ]
  }
}

With the above, if a server connects using leaf1:secret@host:port, then the accepting server will bind the connection to account account1. If using leaf2 user, then the accepting server will bind to connection to account2.

If username/password (either singleton or multi-users) is defined, then the connecting server MUST provide the proper credentials otherwise the connection will be rejected.

If no username/password is provided, it is still possible to provide the account the connection should be associated with:

leafnodes {
  port: ...
  authorization {
    account: TheAccount
  }
}

With the above, a connection without credentials will be bound to the account "TheAccount".

If other form of credentials are used (jwt, nkey or other), then the server will attempt to authenticate and if successful associate to the account for that specific user. If the user authentication fails (wrong password, no such user, etc..) the connection will be also rejected.

LeafNode remotes Entry Block

Property
Description

url

Leafnode URL (URL protocol should be nats-leaf).

urls

Leafnode URL array. Supports multiple URLs for discovery, e.g., urls: [ "nats-leaf://host1:7422", "nats-leaf://host2:7422" ]

no_randomize

IF true, always try connecting in sequence on the URLs in the list. Default behavior if to shuffle the URLs and start connection attempts with a random URL

account

deny_imports

List of subjects which will not be imported over this leaf node connection. Subscriptions to those subjects will not be propagated to the hub.

deny_exports

List of subjects which will not be exported over this leaf node connection. Subscriptions to those subjects will not be propagated into the leaf node.

credentials

Credential file for connecting to the leafnode server.

nkey

Nkey used for connecting to the leafnode server.

tls

ws_compression

ws_no_masking

compression

hub

Default is false. If set to true the roles of leaf node and hub will be reversed. This allows the hub to initiate a leaf node connection to the leaf.

first_info_timeout

Default 1s. The first information sent back by the hub (incoming side) will be the server metadata. The client will only wait first_info_timeout before giving up. This is useful if there is the change that the port on the other side is not a NATS server or not a port accepting leaf node connection. In this case the client would wait forever for the metadata.

Signature Handler

As of NATS Server v.2.9.0, for users embedding the NATS Server, it is possible to replace the use of the credentials file by a signature callback which will sign the nonce and provide the JWT in the CONNECT protocol. The RemoteLeafOpts has a new field:

SignatureCB  SignatureHandler

The callback definition is:

// SignatureHandler is used to sign a nonce from the server while
// authenticating with Nkeys. The callback should sign the nonce and
// return the JWT and the raw signature.
type SignatureHandler func([]byte) (string, []byte, error)

Connecting using WebSocket protocol

Since NATS 2.2.0, Leaf nodes support outbound WebSocket connections by specifying ws as the scheme component of the remote server URLs:

leafnodes {
  remotes [
    {urls: ["ws://hostname1:443", "ws://hostname2:443"]}
  ]
}

Note that if a URL has the ws scheme, all URLs the list must be ws. You cannot mix and match. Therefore this would be considered an invalid configuration:

  remotes [
    # Invalid configuration that will prevent the server from starting
    {urls: ["ws://hostname1:443", "nats://hostname2:7422"]}
  ]

Note that the decision to make a TLS connection is not based on wss:// (as opposed to ws://) but instead in the presence of a TLS configuration in the leafnodes{} or the specific remote configuration block.

tls Configuration Block

Property
Description

cert_file

TLS certificate file.

key_file

TLS certificate key file.

ca_file

TLS certificate authority file.

insecure

Skip certificate verification.

verify

If true, require and verify client certificates.

verify_and_map

If true, require and verify client certificates and use values map certificate values for authentication purposes.

cipher_suites

When set, only the specified TLS cipher suites will be allowed. Values must match golang version used to build the server.

curve_preferences

List of TLS cypher curves to use in order.

timeout

TLS handshake timeout in fractional seconds.

PreviousLeaf NodesNextJetStream on Leaf Nodes

Last updated 7 months ago

Was this helpful?

TLS configuration block (same as other nats-server ).

Authorization block. .

List of entries specifying servers where leafnode client connection can be made.

Configures compression of leafnode connections similar to . Defaults to s2_auto. See details .

this leaf node connection should be bound to.

List of credentials and account to bind to leaf node connections. .

this leaf node connection should be bound to.

name or JWT public key identifying the local account to bind to this remote server. Any traffic locally on this account will be forwarded to the remote server.

A block. Leafnode client will use specified TLS certificates when connecting/authenticating.

If connecting with protocol, this boolean (true or false) indicates to the remote server that it wishes to use compression. The default is false.

If connecting with protocol, this boolean indicates to the remote server that it wishes not to mask outbound WebSocket frames. The default is false, which means that outbound frames will be masked.

Configures compression of leafnode connections similar to . Defaults to s2_auto. See details .

And example of how to use it can be found

To configure Websocket in the remote server, check the section.

here
Websocket
tls configuration
Account
Account
Account
See Authorization Block section below
remote
See User Block section below
TLS configuration
Websocket
Websocket
cluster routes
cluster routes
here
here