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.

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.

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

Users Block

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 need 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

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)

And example of how to use it can be found here

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.

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

tls Configuration Block