diff --git a/nats-server/configuration/leafnodes/README.md b/nats-server/configuration/leafnodes/README.md index ba2a488..b9ace55 100644 --- a/nats-server/configuration/leafnodes/README.md +++ b/nats-server/configuration/leafnodes/README.md @@ -1,14 +1,18 @@ # Leaf Nodes -A _Leaf Node_ extends a cluster or supercluster by bridging security domains. A leaf node proxies local messages to the cluster and cluster messages to the local server through the leaf node's connection client. The leaf node authenticates and authorizes clients using a local policy. Messages are allowed to flow to the cluster or into the leaf node based on the leaf node's connection permissions. +A _Leaf Node_ extends an existing NATS system of any size, optionally bridging both operator and security domains. A leafnode server will transparently route messages as needed from local clients to one or more remote NATS system(s) and vice versa. The leaf node authenticates and authorizes clients using a local policy. Messages are allowed to flow to the cluster or into the leaf node based on leaf node connection permissions of either. -Leaf nodes are useful in IoT and edge scenarios and when the local server traffic should be low RTT and local unless routed to the super cluster. Messages flow in and out of the leaf node using the permissions available to the leaf node connection. +Leaf nodes are useful in IoT and edge scenarios and when the local server traffic should be low RTT and local unless routed to the super cluster. NATS' queue semantics are honored across leaf connections by serving local queue consumer first. -* Leaf nodes clients authenticate locally \(or just connect if authentication is not required\) +* Clients to leaf nodes authenticate locally \(or just connect if authentication is not required\) * Traffic between the leaf node and the cluster assumes the restrictions of the user configuration used to create the leaf connection. * Subjects that the user is allowed to publish are exported to the cluster. * Subjects the user is allowed to subscribe to, are imported into the leaf node. +Unlike [cluster](../clustering/README.md) or [gateway](../gateways/README.md) nodes, leaf nodes do not need to be reachable themselves and can be used to explicitly configure any acyclic graph topologies. + +If a leaf node connects to a cluster, it is recommended to configure it with knowledge of **all** _seed server_ and have **each** _seed server_ accept connections from leaf nodes. Should the remote cluster's configuration change, the discovery protocol will gossip peers capable of accepting leaf connections. A leaf node can have multiple remotes, each connecting to a different cluster. Each URL in a remote needs to point to the same cluster. If one node in a cluster is configured as leaf node, **all** nodes need to. Likewise, if one server in a cluster accepts leaf node connections, **all** server need to. + > Leaf Nodes are an important component as a way to bridge traffic between local NATS servers you control and servers that are managed by a third-party. Synadia's [NATS Global Service \(NGS\)](https://www.synadia.com/) allows accounts to use leaf nodes, but gain accessibility to the global network to inexpensively connect geographically distributed servers or small clusters. [LeafNode Configuration Options](leafnode_conf.md) diff --git a/nats-server/configuration/leafnodes/leafnode_conf.md b/nats-server/configuration/leafnodes/leafnode_conf.md index e20f8bc..a6b93b3 100644 --- a/nats-server/configuration/leafnodes/leafnode_conf.md +++ b/nats-server/configuration/leafnodes/leafnode_conf.md @@ -2,16 +2,19 @@ ## `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 | | :--- | :--- | -| `advertise` | Hostport `:` to advertise to other servers. | -| `authorization` | Authorization block. [**See Authorization Block section below**](leafnode_conf.md#authorization-block). | | `host` | Interface where the server will listen for incoming leafnode connections. | -| `listen` | Combines `host` and `port` as `:` | -| `no_advertise` | if `true` the leafnode shouldn't be advertised. | | `port` | Port where the server will listen for incoming leafnode connections \(default is 7422\). | -| `remotes` | List of `remote` entries specifying servers where leafnode client connection can be made. | -| `tls` | TLS configuration block \(same as other nats-server `tls` configuration\). | +| `listen` | Combines `host` and `port` as `:` | +| `tls` | TLS configuration block \(same as other nats-server [`tls` configuration](../securing_nats/tls.md)\).| +| `advertise` | Hostport `:` 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` | Authorization block. [**See Authorization Block section below**](leafnode_conf.md#authorization-block). | +| `remotes` | List of [`remote`](#leafnode-remotes-entry-block) entries specifying servers where leafnode client connection can be made. | +| `reconnect` | Interval in seconds at which reconnect attempts to a remote server are made. | ## Authorization Block @@ -29,7 +32,7 @@ | :--- | :--- | | `user` | Username for the leaf node connection. | | `password` | Password for the user entry. | -| `account` | Account this leaf node connection should be bound to. | +| `account` | Account this leaf node connection should be bound to. | Here are some examples of using basic user/password authentication for leaf nodes \(note while this is using accounts it is not using JWTs\) @@ -89,9 +92,9 @@ If other form of credentials are used \(jwt, nkey or other\), then the server wi | `urls` | Leafnode URL array. Supports multiple URLs for discovery, e.g., urls: \[ "nats-leaf://host1:7422", "nats-leaf://host2:7422" \] | | `account` | Account public key identifying the leafnode. Account must be defined locally. | | `credentials` | Credential file for connecting to the leafnode server. | -| `tls` | A TLS configuration block. Leafnode client will use specified TLS certificates when connecting/authenticating. | +| `tls` | A [TLS configuration](#tls-configuration-block) block. Leafnode client will use specified TLS certificates when connecting/authenticating. | -## `tls` Configuration Block +### `tls` Configuration Block | Property | Description | | :--- | :--- | @@ -104,4 +107,3 @@ If other form of credentials are used \(jwt, nkey or other\), then the server wi | `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. | -