taigrr/nats.docs
1
0
Fork 0
mirror of https://github.com/taigrr/nats.docs synced 2025-01-18 04:03:23 -08:00
Code Issues Projects Releases Wiki Activity

GitBook: [master] 61 pages modified

Browse Source
This commit is contained in:
Ginger Collison
2020-04-10 14:41:07 +00:00
committed by gitbook-bot
parent ed6c1ba06d
commit de933e912d
61 changed files with 348 additions and 378 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
nats-server/clients.md
View File

@@ -17,7 +17,7 @@ You can install pre-built binaries from the [go-nats-examples repo](https://gith
## Testing your setup
Open a terminal and [start a nats-server](running/README.md):
Open a terminal and [start a nats-server](running/):
```text
> nats-server
@@ -54,7 +54,7 @@ nats-server -V
If you had created a subscriber, you should notice output on the subscriber telling you that it disconnected, and reconnected. The server output above is more interesting. You can see the subscriber send a `CONNECT` protocol message and a `PING` which was responded to by the server with a `PONG`.
> You can learn more about the [NATS protocol here](../nats-protocol/nats-protocol/README.md), but more interesting than the protocol description is [an interactive demo](../nats-protocol/nats-protocol-demo.md).
> You can learn more about the [NATS protocol here](../nats-protocol/nats-protocol/), but more interesting than the protocol description is [an interactive demo](../nats-protocol/nats-protocol-demo.md).
On a third terminal, publish your first message:

60
nats-server/configuration/README.md
View File

@@ -106,18 +106,20 @@ authorization: {
## Configuration Properties
### Connectivity
| Property | Description | Default |
| :--- | :--- | :--- |
| `host` | Host for client connections. | `0.0.0.0` |
| `port` | Port for client connections. | `4222` |
| `listen` | Listen specification `<host>:<port>` for client connections. Either use this or the options `host` and/or `port`. | same as `host`, `port` |
| `client_advertise`| Alternative client listen specification `<host>:<port>` or just `<host>` to advertise to clients and other server. Useful in [cluster](clustering/cluster_config.md) setups with NAT. | Advertise what `host` and `port` specify. |
| [`tls`](securing_nats/tls.md) | Configuration map for tls for client and http monitoring. | |
| [`cluster`](clustering/cluster_config.md) | Configuration map for [cluster](clustering/README.md). | |
| [`gateway`](gateways/gateway.md#Gateway-Configuration-Block) | Configuration map for [gateway](gateways/README.md). | |
| [`leafnode`](leafnodes/leafnode_conf.md) | Configuration map for a [leafnode](leafnodes/README.md). ||
| `listen` | Listen specification `<host>:<port>` for client connections. Either use this or the options `host` and/or `port`. | same as `host`, `port` |
| `client_advertise` | Alternative client listen specification `<host>:<port>` or just `<host>` to advertise to clients and other server. Useful in [cluster](clustering/cluster_config.md) setups with NAT. | Advertise what `host` and `port` specify. |
| [`tls`](securing_nats/tls.md) | Configuration map for tls for client and http monitoring. | |
| [`cluster`](clustering/cluster_config.md) | Configuration map for [cluster](clustering/). | |
| [`gateway`](gateways/gateway.md#Gateway-Configuration-Block) | Configuration map for [gateway](gateways/). | |
| [`leafnode`](leafnodes/leafnode_conf.md) | Configuration map for a [leafnode](leafnodes/). | |
### Connection Timeouts
| Property | Description | Default |
| :--- | :--- | :--- |
| `ping_interval` | Duration at which pings are sent to clients, leaf nodes and routes. In the presence of client traffic, such as messages or client side pings, the server will not send pings. Therefore it is recommended to keep this value bigger than what [clients use](../../developing-with-nats/connecting/pingpong.md). | `"2m"` |
@@ -125,60 +127,65 @@ authorization: {
| `write_deadline` | Maximum number of seconds the server will block when writing. Once this threshold is exceeded the connection will be closed. See [_slow consumer_](../../developing-with-nats/events/slow.md) on how to deal with this on the client. | `"2s"` |
### Limits
| Property | Description | Default |
| :--- | :--- | :--- |
| `max_connections` | Maximum number of active client connections. | `64K` |
| `max_control_line` | Maximum length of a protocol line \(including combined length of subject and queue group\). Increasing this value may require [client changes](../../developing-with-nats/connecting/protocol.md#Set-the-Maximum-Control-Line-Size) to be used. Applies to all traffic. | `4Kb` |
| `max_payload` | Maximum number of bytes in a message payload. Reducing this size may force you to implement [chunking](../../developing-with-nats/connecting/protocol.md#Get-the-Maximum-Payload-Siz) in your clients. Applies to client and leafnode payloads.| `1Mb` |
| `max_pending` | Maximum number of bytes buffered for a connection Applies to client connections.| `64Mb` |
| `max_control_line` | Maximum length of a protocol line \(including combined length of subject and queue group\). Increasing this value may require [client changes](https://github.com/nats-io/nats.docs/tree/542bb62cfd07aef621e53479ed9946f26e514ce6/developing-with-nats/connecting/protocol.md#Set-the-Maximum-Control-Line-Size) to be used. Applies to all traffic. | `4Kb` |
| `max_payload` | Maximum number of bytes in a message payload. Reducing this size may force you to implement [chunking](https://github.com/nats-io/nats.docs/tree/542bb62cfd07aef621e53479ed9946f26e514ce6/developing-with-nats/connecting/protocol.md#Get-the-Maximum-Payload-Siz) in your clients. Applies to client and leafnode payloads. | `1Mb` |
| `max_pending` | Maximum number of bytes buffered for a connection Applies to client connections. | `64Mb` |
| `max_subscriptions` | Maximum numbers of subscriptions per client and leafnode accounts connection. | `0`, unlimited |
### Authentication and Authorization
#### Centralized Authentication and Authorization
| Property | Description |
| :--- | :--- |
| [`authorization`](securing_nats/auth_intro/README.md) | Configuration map for client authentication/authorization. |
| [`authorization`](securing_nats/auth_intro/) | Configuration map for client authentication/authorization. |
| [`accounts`](securing_nats/accounts.md) | Configuration map for multi tenancy via accounts. |
#### Decentralized Authentication and Authorization
The Configuration options here refer to [JWT](./securing_nats/jwt/README.md) based authentication and authorization.
| Property | Description |
| :--- | :--- |
| [`operator`](./securing_nats/jwt/README.md#Decentralized-Authentication-and-Authorization-Configuration) | Path to an operator JWT. |
| [`resolver`](./securing_nats/jwt/README.md#Decentralized-Authentication-and-Authorization-Configuration) | Resolver type [`MEMORY`](securing_nats/jwt/resolver.md#memory) or [`URL(<url>)`](./securing_nats/jwt/resolver.md#url-resolver) for account JWTs. \(When the operator JWT contains an account URL, it will be used as default. In this case `resolver` is only needed to overwrite the default.\)|
| [`resolver_tls`](./securing_nats/jwt/resolver.md#url-resolver) | [`tls` configuration map](securing_nats/tls.md) for tls connections to the resolver. (This is for an outgoing connection and therefore does not use `timeout`, `verify` and `map_and_verify`) |
| [`resolver_preload`](./securing_nats/jwt/resolver.md#memory) | [Map](securing_nats/jwt/resolver.md#memory) to preload account public keys and their corresponding JWT. Keys consist of `<account public nkey>`, value is the `<corresponding jwt>`. Only used when `resolver=MEMORY`. |
The Configuration options here refer to [JWT](securing_nats/jwt/) based authentication and authorization.
| Property | Description |
| :--- | :--- |
| [`operator`](securing_nats/jwt/#Decentralized-Authentication-and-Authorization-Configuration) | Path to an operator JWT. |
| [`resolver`](securing_nats/jwt/#Decentralized-Authentication-and-Authorization-Configuration) | Resolver type [`MEMORY`](securing_nats/jwt/resolver.md#memory) or [`URL(<url>)`](securing_nats/jwt/resolver.md#url-resolver) for account JWTs. \(When the operator JWT contains an account URL, it will be used as default. In this case `resolver` is only needed to overwrite the default.\) |
| [`resolver_tls`](securing_nats/jwt/resolver.md#url-resolver) | [`tls` configuration map](securing_nats/tls.md) for tls connections to the resolver. \(This is for an outgoing connection and therefore does not use `timeout`, `verify` and `map_and_verify`\) |
| [`resolver_preload`](securing_nats/jwt/resolver.md#memory) | [Map](securing_nats/jwt/resolver.md#memory) to preload account public keys and their corresponding JWT. Keys consist of `<account public nkey>`, value is the `<corresponding jwt>`. Only used when `resolver=MEMORY`. |
### Runtime Configuration
| Property | Description | Default |
| :--- | :--- | :--- |
| `disable_sublist_cache` | If `true` disable subscription caches for all accounts. This is saves resources in situations where different subjects are used all the time. | `false`, cache enabled |
| `lame_duck_duration` | In lame duck mode the server rejects new clients and **slowly** closes client connections. After this duration is over the server shuts down. Start lame duck mode with: [`nats-server --signal ldm`](../nats_admin/signals.md). | `"2m"` |
### Monitoring and Tracing
| Property | Description | Default |
| :--- | :--- | :--- |
| `server_name`| The servers name, shows up in logging. Defaults to the server's id. | Generated Server ID |
| `server_name` | The servers name, shows up in logging. Defaults to the server's id. | Generated Server ID |
| `trace` | If `true` enable protocol trace log messages. Excludes the system account. | `false`, disabled |
| `trace_verbose` | If `true` enable protocol trace log messages. Includes the system account. | `false`, disabled |
| `debug` | If `true` enable debug log messages | `false`, disabled |
| `logtime` | If set to `false`, log without timestamps | `true`, include timestamp|
| `logtime` | If set to `false`, log without timestamps | `true`, include timestamp |
| `log_file` | Log file name, relative to... | No log file |
| [`log_size_limit`](logging.md#log-rotation) | Size in bytes after the log file rolls over to a new one | `0`, unlimited |
| `max_traced_msg_len` | Set a limit to the trace of the payload of a message. | `0`, unlimited |
| [`log_size_limit`](logging.md#log-rotation) | Size in bytes after the log file rolls over to a new one | `0`, unlimited |
| `max_traced_msg_len` | Set a limit to the trace of the payload of a message. | `0`, unlimited |
| `syslog` | Log to syslog. | `false`, disabled |
| `remote_syslog` | [Syslog server](logging.md#syslog) address.| |
| `remote_syslog` | [Syslog server](logging.md#syslog) address. | |
| [`http_port`](monitoring.md) | http port for server monitoring. | |
| [`http`](monitoring.md) | Listen specification `<host>:<port>`for server monitoring. | |
| [`https_port`](monitoring.md) | https port for server monitoring. This is influenced by the tls property. | |
| [`https`](monitoring.md) | Listen specification `<host>:<port>`for TLS server monitoring. | |
| `system_account` | Name of the system account. Users of this account can subscribe to system events. See [System Accounts](monitoring/README.md) for more details. | |
| `pid_file` | File containing PID, relative to ... This can serve as input to [nats-server --signal](../nats_admin/signals.md) | |
| `system_account` | Name of the system account. Users of this account can subscribe to system events. See [System Accounts](https://github.com/nats-io/nats.docs/tree/542bb62cfd07aef621e53479ed9946f26e514ce6/nats-server/configuration/monitoring/README.md) for more details. | |
| `pid_file` | File containing PID, relative to ... This can serve as input to [nats-server --signal](../nats_admin/signals.md) | |
| `port_file_dir` | Directory to write a file containing the servers open ports to, relative to ... | |
| `connect_error_reports` | Number of attempts at which a repeated failed route, gateway or leaf node connection is reported. Connect attempts are made once every second.| `3600`, approx every hour |
| `reconnect_error_reports` | Number of failed attempt to reconnect a route, gateway or leaf node connection. Default is to report every attempt. | `1`, every failed attempt|
| `connect_error_reports` | Number of attempts at which a repeated failed route, gateway or leaf node connection is reported. Connect attempts are made once every second. | `3600`, approx every hour |
| `reconnect_error_reports` | Number of failed attempt to reconnect a route, gateway or leaf node connection. Default is to report every attempt. | `1`, every failed attempt |
## Configuration Reloading
@@ -187,3 +194,4 @@ A server can reload most configuration changes without requiring a server restar
```text
> nats-server --signal reload
```

10
nats-server/configuration/clustering/README.md
View File

@@ -2,12 +2,11 @@
## NATS Server Clustering
NATS supports running each server in clustered mode. You can cluster servers together for high volume messaging systems and resiliency and high availability.
NATS supports running each server in clustered mode. You can cluster servers together for high volume messaging systems and resiliency and high availability.
NATS servers achieve this by gossiping about and connecting to, all of the servers they know, thus dynamically forming a full mesh.
Once clients [connect](../../../developing-with-nats/connecting/cluster.md) or [re-connect](../../../developing-with-nats/reconnect/README.md) to a particular server, they are informed about current cluster members. Because of this behavior, a cluster can grow, shrink and self heal. The full mesh does not necessarily have to be explicitly configured either.
NATS servers achieve this by gossiping about and connecting to, all of the servers they know, thus dynamically forming a full mesh. Once clients [connect](../../../developing-with-nats/connecting/cluster.md) or [re-connect](../../../developing-with-nats/reconnect/) to a particular server, they are informed about current cluster members. Because of this behavior, a cluster can grow, shrink and self heal. The full mesh does not necessarily have to be explicitly configured either.
Note that NATS clustered servers have a forwarding limit of one hop. This means that each `nats-server` instance will **only** forward messages that it has received **from a client** to the immediately adjacent `nats-server` instances to which it has routes. Messages received **from** a route will only be distributed to local clients.
Note that NATS clustered servers have a forwarding limit of one hop. This means that each `nats-server` instance will **only** forward messages that it has received **from a client** to the immediately adjacent `nats-server` instances to which it has routes. Messages received **from** a route will only be distributed to local clients.
For the cluster to successfully form a full mesh and NATS to function as intended and described throughout the documentation - temporary errors permitting - it is necessary that servers can connect to each other and that clients can connect to each server in the cluster.
@@ -183,7 +182,7 @@ At this point, there is a full mesh cluster of NATS servers.
### Testing the Cluster
Now, the following should work: make a subscription to the first server (port 4222). Then publish to each server (ports 4222, 5222, 6222). You should be able to receive messages without problems.
Now, the following should work: make a subscription to the first server \(port 4222\). Then publish to each server \(ports 4222, 5222, 6222\). You should be able to receive messages without problems.
```bash
nats-sub -s "nats://127.0.0.1:4222" hello &
@@ -207,3 +206,4 @@ nats-pub -s "nats://127.0.0.1:4222,nats://127.0.0.1:5222,nats://127.0.0.1:6222"
[83330] 2020/02/12 16:22:56.384754 [DBG] 127.0.0.1:63210 - cid:9 - Client connection created
[83330] 2020/02/12 16:22:56.386467 [DBG] 127.0.0.1:63210 - cid:9 - Client connection closed
```

5
nats-server/configuration/clustering/cluster_config.md
View File

@@ -9,10 +9,10 @@ The `cluster` configuration map has the following configuration options:
| `listen` | Combines `host` and `port` as `<host>:<port>`. |
| `tls` | A [`tls` configuration map](../securing_nats/tls.md) for securing the clustering connection. `verify` is always enabled and `cert_file` is used for client and server. [See](../securing_nats/tls.md#Wrong-Key-Usage) for certificate pitfalls. |
| `advertise` | Hostport `<host>:<port>` to advertise how this server can be contacted by other cluster members. This is useful in setups with NAT. |
| `no_advertise` | When set to `true`, do not advertise this server to clients. |
| `no_advertise` | When set to `true`, do not advertise this server to clients. |
| `routes` | A list of other servers \(URLs\) to cluster with. Self-routes are ignored. Should authentication via `token` or `username`/`password` be required, specify them as part of the URL. |
| `connect_retries` | After how many failed connect attempts to give up establishing a connection to a discovered route. Default is `0`, do not retry. When enabled, attempts will be made once a second. This, does not apply to explicitly configured routes. |
| `authorization` | [Authorization](../securing_nats/auth_intro/README.md#Authorization-Map) map for configuring cluster routes. When `token` or a single `username`/`password` are used, they define the authentication mechanism this server expects. What authentication values other server have to provide when connecting. They also specify how this server will authenticate itself when establishing a connection to a discovered route. This will not be used for routes explicitly listed in `routes` and therefore have to be provided as part of the URL. If you use token or password based authentication, either use the same credentials throughout the system or list every route explicitly on every server. If the `tls` configuration map specifies `verify_and_map` only provide the expected `username`. Here different certificates can be used, but they do have to map to the same `username`. The authorization map also allows for `timeout` which is honored but `users` and `permissions` are ignored. |
| `authorization` | [Authorization](../securing_nats/auth_intro/#Authorization-Map) map for configuring cluster routes. When `token` or a single `username`/`password` are used, they define the authentication mechanism this server expects. What authentication values other server have to provide when connecting. They also specify how this server will authenticate itself when establishing a connection to a discovered route. This will not be used for routes explicitly listed in `routes` and therefore have to be provided as part of the URL. If you use token or password based authentication, either use the same credentials throughout the system or list every route explicitly on every server. If the `tls` configuration map specifies `verify_and_map` only provide the expected `username`. Here different certificates can be used, but they do have to map to the same `username`. The authorization map also allows for `timeout` which is honored but `users` and `permissions` are ignored. |
```text
cluster {
@@ -38,3 +38,4 @@ cluster {
]
}
```

3
nats-server/configuration/clustering/cluster_tls.md
View File

@@ -2,7 +2,8 @@
When setting up clusters, all servers in the cluster, if using TLS, will both verify the connecting endpoints and the server responses. So certificates are checked in [both directions](../securing_nats/tls.md#Wrong-Key-Usage). Certificates can be configured only for the server's cluster identity, keeping client and server certificates separate from cluster formation.
TLS Mutual Authentication _is the only way_ of securing routes.
TLS Mutual Authentication _is the only way_ of securing routes.
```text
cluster {
listen: 127.0.0.1:4244

11
nats-server/configuration/gateways/README.md
View File

@@ -1,8 +1,8 @@
# Gateways
# Super-cluster with Gateways
## Gateways
Gateways enable connecting one or more clusters together into a full mesh; they allow the formation of super clusters from smaller clusters. Cluster and Gateway protocols listen on different ports. Clustering is used for adjacent servers; gateways are for joining clusters together.
Gateways enable connecting one or more clusters together into a full mesh; they allow the formation of super clusters from smaller clusters. Cluster and Gateway protocols listen on different ports. Clustering is used for adjacent servers; gateways are for joining clusters together.
Gateway configuration is similar to clustering:
@@ -35,9 +35,9 @@ If the local cluster has three gateway nodes, this means there will be three out
![Gateway Discovered Gateways](../../../.gitbook/assets/three_gw.svg)
> In this second example, again configured connections are shown with solid lines and discovered gateway connections are shown using dotted lines. Gateways _A_ and _C_ were both discovered via gossiping; _B_ discovered _A_ and _A_ discovered _C_.
> In this second example, again configured connections are shown with solid lines and discovered gateway connections are shown using dotted lines. Gateways _A_ and _C_ were both discovered via gossiping; _B_ discovered _A_ and _A_ discovered _C_.
A key point in the description above is that each node in the cluster will make a connection to a single node in every remote cluster — a difference from the clustering protocol, where every node is directly connected to all other nodes.
A key point in the description above is that each node in the cluster will make a connection to a single node in every remote cluster — a difference from the clustering protocol, where every node is directly connected to all other nodes.
For those mathematically inclined, cluster connections are `N(N-1)/2` where _N_ is the number of nodes in the cluster. On gateway configurations, outbound connections are the summation of `Ni(M-1)` where Ni is the number of nodes in a gateway _i_, and _M_ is the total number of gateways. Inbound connections are the summation of `U-Ni` where U is the sum of all gateway nodes in all gateways, and N is the number of nodes in a gateway _i_. It works out that both inbound and outbound connection counts are the same.
@@ -55,6 +55,7 @@ The number of connections required to join clusters using clustering vs. gateway
A cluster section is not needed for gateways, they work with single server as well. Yet, they start to be useful when participating cluster consist of more than one server and they reduce the number of connections.
## Interest Propagation
Messages from clients directly connected to a gateway node will be sent along outgoing gateway connections according to the following three interest propagation mechanisms:
* Optimistic Mode
@@ -62,7 +63,7 @@ Messages from clients directly connected to a gateway node will be sent along ou
* Queue Subscriptions
Local interest permitting, the receiving gateway node sends the messages directly to its subscribing clients as well as server within the cluster.
### Optimistic Mode
When a publisher in _A_ publishes "foo", the _A_ gateway will check if cluster _B_ has registered _no_ interest in "foo". If not, it forwards "foo" to _B_. If upon receiving "foo", _B_ has no subscribers on "foo", _B_ will send a gateway protocol message to _A_ expressing that it has no interest on "foo", preventing future messages on "foo" from being forwarded.

8
nats-server/configuration/gateways/gateway.md
View File

@@ -1,6 +1,6 @@
# Configuration
The `gateway` [configuration block](#gateway-configuration-block) is similar to a [`cluster`](../clustering/cluster_config.md) block:
The `gateway` [configuration block](gateway.md#gateway-configuration-block) is similar to a [`cluster`](../clustering/cluster_config.md) block:
```text
gateway {
@@ -64,14 +64,14 @@ Published [foo] : 'bar'
| :--- | :--- |
| `name` | Name for this cluster, all gateways belonging to the same cluster, should specify the same name. |
| `reject_unknown` | If `true`, gateway will reject connections from gateways that are not configured in `gateways`. |
| `gateways` | List of Gateway [entries](#Gateway-Entry) - see below. |
| `gateways` | List of Gateway [entries](gateway.md#Gateway-Entry) - see below. |
| `host` | Interface where the gateway will listen for incoming gateway connections. |
| `port` | Port where the gateway will listen for incoming gateway connections. |
| `listen` | Combines `host` and `port` as `<host>:<port>` |
| `tls` | A [`tls` configuration map](../securing_nats/tls.md) for securing gateway connections. `verify` is always enabled. Unless otherwise specified in a [`gateway`](#Gateway-Entry), `cert_file` will be the default client certificate. [See](../securing_nats/tls.md#Wrong-Key-Usage) for certificate pitfalls. |
| `tls` | A [`tls` configuration map](../securing_nats/tls.md) for securing gateway connections. `verify` is always enabled. Unless otherwise specified in a [`gateway`](gateway.md#Gateway-Entry), `cert_file` will be the default client certificate. [See](../securing_nats/tls.md#Wrong-Key-Usage) for certificate pitfalls. |
| `advertise` | Hostport `<host>:<port>` to advertise how this server can be contacted by other gateway members. This is useful in setups with NAT. |
| `connect_retries` | After how many failed connect attempts to give up establishing a connection to a discovered gateway. Default is `0`, do not retry. When enabled, attempts will be made once a second. This, does not apply to explicitly configured gateways. |
| `authorization` | [Authorization](../securing_nats/auth_intro/README.md#Authorization-Map) map for gateways. When `token` or a single `username`/`password` are used, they define the authentication mechanism this server expects. What authentication values other server have to provide when connecting. They also specify how this server will authenticate itself when establishing a connection to a discovered gateway. This will not be used for gateways explicitly listed in [`gateways`](#Gateway-Entry) and therefore have to be provided as part of the URL. If you use token or password based authentication, either use the same credentials throughout the system or list every gateway explicitly on every server. If the `tls` configuration map specifies `verify_and_map` only provide the expected `username`. Here different certificates can be used, but they do have to map to the same `username`. The authorization map also allows for `timeout` which is honored but `users` and `permissions` are ignored. |
| `authorization` | [Authorization](../securing_nats/auth_intro/#Authorization-Map) map for gateways. When `token` or a single `username`/`password` are used, they define the authentication mechanism this server expects. What authentication values other server have to provide when connecting. They also specify how this server will authenticate itself when establishing a connection to a discovered gateway. This will not be used for gateways explicitly listed in [`gateways`](gateway.md#Gateway-Entry) and therefore have to be provided as part of the URL. If you use token or password based authentication, either use the same credentials throughout the system or list every gateway explicitly on every server. If the `tls` configuration map specifies `verify_and_map` only provide the expected `username`. Here different certificates can be used, but they do have to map to the same `username`. The authorization map also allows for `timeout` which is honored but `users` and `permissions` are ignored. |
### `Gateway` Entry

6
nats-server/configuration/leafnodes/README.md
View File

@@ -1,15 +1,15 @@
# Leaf Nodes
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.
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. NATS' queue semantics are honored across leaf connections by serving local queue consumer first.
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.
* 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.
Unlike [cluster](../clustering/) or [gateway](../gateways/) 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.

7
nats-server/configuration/leafnodes/leafnode_conf.md
View File

@@ -9,11 +9,11 @@ The leaf node configuration block is used to configure incoming as well as outgo
| `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` | TLS configuration block \(same as other nats-server [`tls` configuration](../securing_nats/tls.md)\).|
| `tls` | TLS configuration block \(same as other nats-server [`tls` configuration](../securing_nats/tls.md)\). |
| `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` | 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. |
| `remotes` | List of [`remote`](leafnode_conf.md#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
@@ -92,7 +92,7 @@ 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](#tls-configuration-block) block. Leafnode client will use specified TLS certificates when connecting/authenticating. |
| `tls` | A [TLS configuration](leafnode_conf.md#tls-configuration-block) block. Leafnode client will use specified TLS certificates when connecting/authenticating. |
### `tls` Configuration Block
@@ -107,3 +107,4 @@ 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. |

2
nats-server/configuration/logging.md
View File

@@ -95,7 +95,7 @@ The first line specifies the location that the subsequent lines will apply to.
The rest of the file specifies that the logs will rotate daily \("daily" option\) and that 30 older copies will be preserved \("rotate" option\). Other options are described in [logrorate documentation](https://linux.die.net/man/8/logrotate).
The "postrotate" section tells NATS server to reload the log files once the rotation is complete. The command ``kill -SIGUSR1 `cat /var/run/nats-server.pid``` does not kill the NATS server process, but instead sends it a signal causing it to reload its log files. This will cause new requests to be logged to the refreshed log file.
The "postrotate" section tells NATS server to reload the log files once the rotation is complete. The command ```kill -SIGUSR1``cat /var/run/nats-server.pid\`\`\` does not kill the NATS server process, but instead sends it a signal causing it to reload its log files. This will cause new requests to be logged to the refreshed log file.
The `/var/run/nats-server.pid` file is where NATS server stores the master process's pid.

11
nats-server/configuration/monitoring.md
View File

@@ -13,17 +13,15 @@ To monitor the NATS messaging system, `nats-server` provides a lightweight HTTP
All endpoints return a JSON object.
The NATS monitoring endpoints support [JSONP](https://en.wikipedia.org/wiki/JSONP) and [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing#How_CORS_works), making it easy to create single page monitoring web applications. Part of the NATS ecosystem is a tool called [nats-top](../../nats-tools/nats_top/README.md) that visualizes data from these endpoints on the command line.
The NATS monitoring endpoints support [JSONP](https://en.wikipedia.org/wiki/JSONP) and [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing#How_CORS_works), making it easy to create single page monitoring web applications. Part of the NATS ecosystem is a tool called [nats-top](../../nats-tools/nats_top/) that visualizes data from these endpoints on the command line.
> Warning: `nats-server` does not have authentication/authorization for the monitoring endpoint.
> When you plan to open your `nats-server` to the internet make sure to not expose the monitoring port as well.
> By default monitoring binds to every interface `0.0.0.0` so consider setting monitoring to `localhost` or have appropriate firewall rules.
> Warning: `nats-server` does not have authentication/authorization for the monitoring endpoint. When you plan to open your `nats-server` to the internet make sure to not expose the monitoring port as well. By default monitoring binds to every interface `0.0.0.0` so consider setting monitoring to `localhost` or have appropriate firewall rules.
>
> In other words don't do what `http://demo.nats.io:8222/` does! It is done on purpose to simplify the examples below.
### Enabling monitoring from the command line
To enable the monitoring server, start the NATS server with the monitoring flag `-m` and the monitoring port, or turn it on in the [configuration file](#Enable-monitoring-from-the-configuration-file).
To enable the monitoring server, start the NATS server with the monitoring flag `-m` and the monitoring port, or turn it on in the [configuration file](monitoring.md#Enable-monitoring-from-the-configuration-file).
```text
-m, --http_port PORT HTTP PORT for monitoring
@@ -60,8 +58,7 @@ For example, to monitor this server locally, the endpoint would be [http://local
## Monitoring endpoints
The following sections describe each supported monitoring endpoint: `varz`, `connz`, `routez`, `subsz`, `gatewayz`, and `leafz`.
There are not any required arguments, however use of arguments can let you tailor monitoring to your environment and tooling.
The following sections describe each supported monitoring endpoint: `varz`, `connz`, `routez`, `subsz`, `gatewayz`, and `leafz`. There are not any required arguments, however use of arguments can let you tailor monitoring to your environment and tooling.
### General Information

3
nats-server/configuration/securing_nats/README.md
View File

@@ -3,5 +3,6 @@
The NATS server provides several forms of security:
* Connections can be [_encrypted_ with TLS](tls.md)
* Client connections can require [_authentication_](auth_intro/README.md)
* Client connections can require [_authentication_](auth_intro/)
* Clients can require [_authorization_](authorization.md) for subjects they publish or subscribe to

33
nats-server/configuration/securing_nats/accounts.md
View File

@@ -1,23 +1,20 @@
# Multi Tenancy
# Multi Tenancy using Accounts
In modern microservice architecture it is common to share infrastructure - such as NATS - between services.
[Accounts](#Accounts) are securely isolated communication contexts that allow multi-tenancy in a NATS deployment.
They allow users to bifurcate technology from business driven use cases, where data silos are created by design, not software limitations.
Furthermore, they facilitate the [controlled exchange](#Exporting-and-Importing) of information between those data silos/Tenants/Accounts.
In modern microservice architecture it is common to share infrastructure - such as NATS - between services. [Accounts](accounts.md#Accounts) are securely isolated communication contexts that allow multi-tenancy in a NATS deployment. They allow users to bifurcate technology from business driven use cases, where data silos are created by design, not software limitations. Furthermore, they facilitate the [controlled exchange](accounts.md#Exporting-and-Importing) of information between those data silos/Tenants/Accounts.
## Accounts
_Accounts_ expand on the authorization foundation. With traditional authorization, all clients can publish and subscribe to anything unless explicitly configured otherwise. To protect clients and information, you have to carve the subject space and permission clients carefully.
_Accounts_ allow the grouping of clients, _isolating_ them from clients in other accounts, thus enabling _multi-tenancy_ in the server. With accounts, the subject space is not globally shared, greatly simplifying the messaging environment. Instead of devising complicated subject name carving patterns, clients can use short subjects without explicit authorization rules. [System Events](../sys_accounts/README.md) are an example of this isolation at work.
_Accounts_ allow the grouping of clients, _isolating_ them from clients in other accounts, thus enabling _multi-tenancy_ in the server. With accounts, the subject space is not globally shared, greatly simplifying the messaging environment. Instead of devising complicated subject name carving patterns, clients can use short subjects without explicit authorization rules. [System Events](../sys_accounts/) are an example of this isolation at work.
Accounts configuration is done in `accounts` map. The contents of an account entry includes:
| Property | Description |
| :--- | :--- |
| `users` | a list of [user configuration maps](auth_intro/README.md#user-configuration-map) |
| `exports` | a list of [export maps](#Export-Configuration-Map) |
| `imports` | a list of [import maps](#Import-Configuration-Map) |
| `users` | a list of [user configuration maps](auth_intro/#user-configuration-map) |
| `exports` | a list of [export maps](accounts.md#Export-Configuration-Map) |
| `imports` | a list of [import maps](accounts.md#Import-Configuration-Map) |
The `accounts` list is a map, where the keys on the map are an account name.
@@ -40,7 +37,7 @@ accounts: {
>
> These two accounts are isolated from each other. Messages published by users in `A` are not visible to users in `B`.
>
> The user configuration map is the same as any other NATS [user configuration map](auth_intro/README.md#user-configuration-map) . You can use:
> The user configuration map is the same as any other NATS [user configuration map](auth_intro/#user-configuration-map) . You can use:
>
> * username/password
> * nkeys
@@ -55,8 +52,7 @@ Messaging exchange between different accounts is enabled by _exporting_ streams
* **Streams** are messages your application publishes. Importing applications won't be able to make requests from your applications but will be able to consume messages you generate.
* **Services** are messages your application can consume and act on, enabling other accounts to make requests that are fulfilled by your account.
The `exports` configuration list enable you to define the services and streams that others can import. Exported services and streams are expressed as an [Export configuration map](#export-configuration-map).
The `imports` configuration lists the services and streams that an Account imports. Imported services and streams are expressed as an [Import configuration map](#import-configuration-map).
The `exports` configuration list enable you to define the services and streams that others can import. Exported services and streams are expressed as an [Export configuration map](accounts.md#export-configuration-map). The `imports` configuration lists the services and streams that an Account imports. Imported services and streams are expressed as an [Import configuration map](accounts.md#import-configuration-map).
### Export Configuration Map
@@ -100,15 +96,12 @@ An import enables an account to consume streams published by another account or
| Property | Description |
| :--- | :--- |
| `stream` | Stream import [source configuration](#source-configuration-map). \(exclusive of `service`\) |
| `service` | Service import [source configuration](#source-configuration-map) \(exclusive of `stream`\) |
| `prefix` | A local subject prefix mapping for the imported stream. \(applicable to `stream`\)|
| `to` | A local subject mapping for imported service. \(applicable to `service`\)|
| `stream` | Stream import [source configuration](accounts.md#source-configuration-map). \(exclusive of `service`\) |
| `service` | Service import [source configuration](accounts.md#source-configuration-map) \(exclusive of `stream`\) |
| `prefix` | A local subject prefix mapping for the imported stream. \(applicable to `stream`\) |
| `to` | A local subject mapping for imported service. \(applicable to `service`\) |
The `prefix` and `to` options are optional and allow you to remap the subject that is used locally to receive stream messages from or publish service requests to.
This way the importing account does not depend on naming conventions picked by another.
Currently, a service import can not make use of wildcards, which is why the import subject can be rewritten.
A stream import may make use of wildcards. To retain information contained in the subject, it can thus only be prefixed with `prefix`...
The `prefix` and `to` options are optional and allow you to remap the subject that is used locally to receive stream messages from or publish service requests to. This way the importing account does not depend on naming conventions picked by another. Currently, a service import can not make use of wildcards, which is why the import subject can be rewritten. A stream import may make use of wildcards. To retain information contained in the subject, it can thus only be prefixed with `prefix`...
#### Source Configuration Map

4
nats-server/configuration/securing_nats/auth_intro/README.md
View File

@@ -6,7 +6,7 @@ The NATS server provides various ways of authenticating clients:
* [Username/Password credentials](username_password.md)
* [TLS Certificate](tls_mutual_auth.md)
* [NKEY with Challenge](nkey_auth.md)
* [Decentralized JWT Authenticatin/Authorization](../jwt/README.md)
* [Decentralized JWT Authenticatin/Authorization](../jwt/)
Authentication deals with allowing a NATS client to connect to the server. Except for JWT authentication, authentication and authorization are configured in the `authorization` section of the configuration.
@@ -19,7 +19,7 @@ The `authorization` block provides _authentication_ configuration as well as _au
| [`token`](tokens.md) | Specifies a global token that can be used to authenticate to the server \(exclusive of user and password\) |
| [`user`](username_password.md) | Specifies a single _global_ user name for clients to the server \(exclusive of token\) |
| [`password`](username_password.md) | Specifies a single _global_ password for clients to the server \(exclusive of `token`\) |
| `users` | A list of [user configuration](#user-configuration-map) maps |
| `users` | A list of [user configuration](./#user-configuration-map) maps |
| [`timeout`](auth_timeout.md) | Maximum number of seconds to wait for client authentication |
For multiple username and password credentials, specify a `users` list.

1
nats-server/configuration/securing_nats/auth_intro/nkey_auth.md
View File

@@ -58,3 +58,4 @@ const nc = NATS.connect({
```
The client provides a function that it uses to parse the seed \(the private key\) and sign the connection challenge.

11
nats-server/configuration/securing_nats/auth_intro/tls_mutual_auth.md
View File

@@ -28,9 +28,7 @@ Or via the command line:
> ./nats-server --tlsverify --tlscert=server-cert.pem --tlskey=server-key.pem --tlscacert=rootCA.pem
```
This option verifies the client's certificate is signed by the CA specified in the `ca_file` option.
When `ca_file` is not present it will default to CAs in the system trust store.
It also makes sure that the client provides a certificate with the extended key usage `TLS Web Client Authentication`.
This option verifies the client's certificate is signed by the CA specified in the `ca_file` option. When `ca_file` is not present it will default to CAs in the system trust store. It also makes sure that the client provides a certificate with the extended key usage `TLS Web Client Authentication`.
## Mapping Client Certificates To A User
@@ -50,9 +48,9 @@ tls {
> Note that `verify` was changed to `verify_and_map`.
When present, the server will check if a Subject Alternative Name \(SAN\) maps to a user. It will search all email addresses first, then all DNS names. If no user could be found, it will try the certificate subject.
When present, the server will check if a Subject Alternative Name \(SAN\) maps to a user. It will search all email addresses first, then all DNS names. If no user could be found, it will try the certificate subject.
> Note: This mechanism will pick the user it finds first. There is no configuration to restrict this.
> Note: This mechanism will pick the user it finds first. There is no configuration to restrict this.
```text
$ openssl x509 -noout -text -in client-cert.pem
@@ -87,8 +85,7 @@ Certificate:
...
```
> Note that for this example to work you will have to modify the user to match what is in your certificates subject.
> In doing so, watch out for the order of attributes!
> Note that for this example to work you will have to modify the user to match what is in your certificates subject. In doing so, watch out for the order of attributes!
The configuration to authorize this user would be as follows:

30
nats-server/configuration/securing_nats/authorization.md
View File

@@ -2,7 +2,7 @@
The NATS server supports authorization using subject-level permissions on a per-user basis. Permission-based authorization is available with multi-user authentication via the `users` list.
Each permission specifies the subjects the user can publish to and subscribe to. The parser is generous at understanding what the intent is, so both arrays and singletons are processed. For more complex configuration, you can specify a `permission` object which explicitly allows or denies subjects. The specified subjects can specify wildcards as well. Permissions can make use of [variables](../README.md#variables).
Each permission specifies the subjects the user can publish to and subscribe to. The parser is generous at understanding what the intent is, so both arrays and singletons are processed. For more complex configuration, you can specify a `permission` object which explicitly allows or denies subjects. The specified subjects can specify wildcards as well. Permissions can make use of [variables](../#variables).
A special field inside the authorization map is `default_permissions`. When present, it contains permissions that apply to users that do not have permissions associated with them.
@@ -12,9 +12,9 @@ The `permissions` map specify subjects that can be subscribed to or published by
| Property | Description |
| :--- | :--- |
| `publish` | subject, list of subjects, or [permission map](#permission-map) the client can publish |
| `subscribe` | subject, list of subjects, or [permission map](#permission-map) the client can subscribe to. In this context it is possible to provide an optional queue name: `<subject> <queue>` to express queue group permissions. These permissions can also use wildcards such as `v2.*` or `>`.|
| `allow_responses` | boolean or [responses map](#allow-responses-map), default is `false` |
| `publish` | subject, list of subjects, or [permission map](authorization.md#permission-map) the client can publish |
| `subscribe` | subject, list of subjects, or [permission map](authorization.md#permission-map) the client can subscribe to. In this context it is possible to provide an optional queue name: `<subject> <queue>` to express queue group permissions. These permissions can also use wildcards such as `v2.*` or `>`. |
| `allow_responses` | boolean or [responses map](authorization.md#allow-responses-map), default is `false` |
## Permission Map
@@ -25,17 +25,16 @@ The `permission` map provides additional properties for configuring a `permissio
| `allow` | List of subject names that are allowed to the client |
| `deny` | List of subjects that are denied to the client |
**Important Note** It is important to not break request/reply patterns. In some cases \(as shown [below](#variables)\) you need to add rules for the `_INBOX.>` pattern. If an unauthorized client publishes or attempts to subscribe to a subject that has not been _allow listed_, the action fails and is logged at the server, and an error message is returned to the client. The [allow responses](#allow-responses-map) option can simplify this.
**Important Note** It is important to not break request/reply patterns. In some cases \(as shown [below](authorization.md#variables)\) you need to add rules for the `_INBOX.>` pattern. If an unauthorized client publishes or attempts to subscribe to a subject that has not been _allow listed_, the action fails and is logged at the server, and an error message is returned to the client. The [allow responses](authorization.md#allow-responses-map) option can simplify this.
## Allow Responses Map
The `allow_responses` option dynamically allows publishing to reply subjects and works well for service responders.
When set to `true`, only one response is allowed, meaning the permission to publish to the reply subject defaults to only once. The `allow_responses` map allows you to configure a maximum number of responses and how long the permission is valid.
The `allow_responses` option dynamically allows publishing to reply subjects and works well for service responders. When set to `true`, only one response is allowed, meaning the permission to publish to the reply subject defaults to only once. The `allow_responses` map allows you to configure a maximum number of responses and how long the permission is valid.
| Property | Description |
| :--- | :--- |
| `max` | The maximum number of response messages that can be published. |
| `expires` | The amount of time the permission is valid. Values such as `1s`, `1m`, `1h` (1 second, minute, hour) etc can be specified. Default doesn't have a time limit. |
| `expires` | The amount of time the permission is valid. Values such as `1s`, `1m`, `1h` \(1 second, minute, hour\) etc can be specified. Default doesn't have a time limit. |
When `allow_responses` is set to `true`, it defaults to the equivalent of `{ max: 1 }` and no time limit.
@@ -74,7 +73,7 @@ authorization {
}
```
> `default_permissions` is a special entry. If defined, it applies to all users that don't have specific permissions set.
> `default_permissions` is a special entry. If defined, it applies to all users that don't have specific permissions set.
* _admin_ has `ADMIN` permissions and can publish/subscribe on any subject. We use the wildcard `>` to match any subject.
* _client_ is a `REQUESTOR` and can publish requests on subjects `req.a` or `req.b`, and subscribe to anything that is a response \(`_INBOX.>`\).
@@ -114,17 +113,17 @@ authorization: {
}
```
### allow_responses
### allow\_responses
Here's an example with `allow_responses`:
```text
authorization: {
users: [
{ user: a, password: a },
{ user: b, password: b, permissions: {subscribe: "q", allow_responses: true } },
{ user: c, password: c, permissions: {subscribe: "q", allow_responses: { max: 5, expires: "1m" } } }
]
users: [
{ user: a, password: a },
{ user: b, password: b, permissions: {subscribe: "q", allow_responses: true } },
{ user: c, password: c, permissions: {subscribe: "q", allow_responses: { max: 5, expires: "1m" } } }
]
}
```
@@ -154,3 +153,4 @@ users = [
}
]
```

30
nats-server/configuration/securing_nats/jwt/README.md
View File

@@ -1,12 +1,10 @@
# Decentralized JWT Authentication and Authorization
# Decentralized JWT Authentication/Authorization
With other authentication mechanisms, configuration for identifying a user and [Account](../accounts.md), is in the server configuration file. JWT authentication leverages [JSON Web Tokens \(JWT\)](https://jwt.io/) to describe the various entities supported. When a client connects, servers verify the authenticity of the request using [NKeys](../auth_intro/nkey_auth.md), download account information and validate a trust chain. Users are not directly tracked by the server, but rather verified as and belonging to an [Account](../accounts.md). This enables the management of users, without requiring server configuration updates.
Effectively, JWTs improve accounts and provide for a **distributed configuration paradigm**. Previously each user \(or client\) needed to be known and authorized a priori in the server’s configuration requiring an administrator to modify and update server configurations. These chores are eliminated. User creation can can even be performed by different entities altogether.
Effectively, JWTs improve accounts and provide for a **distributed configuration paradigm**. Previously each user \(or client\) needed to be known and authorized a priori in the server’s configuration requiring an administrator to modify and update server configurations. These chores are eliminated. User creation can can even be performed by different entities altogether.
> Note: This scheme improves [accounts](../accounts.md). Functionalities like [isolation](../accounts.md) or defining [exports/imports](../accounts.md#exporting-and-importing) between accounts remain!
> It moves configuration of accounts, exports/imports or users and their permissions away from the server into several trusted [JSON Web Token \(JWT\)](https://jwt.io/) that are managed separately, therefore removing the need to configure these entities in each and every server.
> It furthermore adds functionalities like expiration and revocation fore decentralized account management
> Note: This scheme improves [accounts](../accounts.md). Functionalities like [isolation](../accounts.md) or defining [exports/imports](../accounts.md#exporting-and-importing) between accounts remain! It moves configuration of accounts, exports/imports or users and their permissions away from the server into several trusted [JSON Web Token \(JWT\)](https://jwt.io/) that are managed separately, therefore removing the need to configure these entities in each and every server. It furthermore adds functionalities like expiration and revocation fore decentralized account management
## JSON Web Tokens
@@ -56,23 +54,13 @@ Lastly, all NATS JWTs \(Operators, Accounts, Users and others\) are expected to
## Decentralized Authentication and Authorization - Configuration
Configuration is broken up into separate steps.
Depending on organizational needs these are performed by the same or different entities.
Configuration is broken up into separate steps. Depending on organizational needs these are performed by the same or different entities.
JWT configuration is done using the [`nsc` tool](../../../../nats-tools/nsc/README.md).
It can be set up to issue [NKeys](../auth_intro/nkey_auth.md) and corresponding JWTs for all [nkey roles](#nkey-roles): Operator/Account/User \([Example usage](../../../../nats-tools/nsc/nsc.md#creating-an-operator-account-and-user)\).
Despite Account and User creation not happening in server configuration, this model is a centralized authentication and authorization setup.
JWT configuration is done using the [`nsc` tool](../../../../nats-tools/nsc/). It can be set up to issue [NKeys](../auth_intro/nkey_auth.md) and corresponding JWTs for all [nkey roles](./#nkey-roles): Operator/Account/User \([Example usage](../../../../nats-tools/nsc/nsc.md#creating-an-operator-account-and-user)\). Despite Account and User creation not happening in server configuration, this model is a centralized authentication and authorization setup.
Provided institutional trust, it is also possible to use nsc to import account or user public [NKeys](../auth_intro/nkey_auth.md) and issue corresponding JWTs.
This way an operator can issue account JWTs and a separate entity can issue JWTs for user associated with it's account.
Neither entity has to be aware of the other's private Nkey.
This not only allows users to be configured some place other than servers, but also by different organizations altogether.
Say administrators of a NATS installation controlling operators, issuing account JWTs to individual prod/dev teams managing their own user.
This is a fully decentralized authorization setup!
Provided institutional trust, it is also possible to use nsc to import account or user public [NKeys](../auth_intro/nkey_auth.md) and issue corresponding JWTs. This way an operator can issue account JWTs and a separate entity can issue JWTs for user associated with it's account. Neither entity has to be aware of the other's private Nkey. This not only allows users to be configured some place other than servers, but also by different organizations altogether. Say administrators of a NATS installation controlling operators, issuing account JWTs to individual prod/dev teams managing their own user. This is a fully decentralized authorization setup!
With an Operator JWT in place, the server needs to be configured to trust it by specifying `operator`.
Furthermore the server needs a way to obtain account JWTs.
This done by either defaulting to the resolver specified in the operator jwt or by manually specifying the [resolver](resolver.md).
Depending on your configuration an [account server](../../../../nats-tools/nsc/nsc.md#account-server-configuration) needs to be in place
With an Operator JWT in place, the server needs to be configured to trust it by specifying `operator`. Furthermore the server needs a way to obtain account JWTs. This done by either defaulting to the resolver specified in the operator jwt or by manually specifying the [resolver](resolver.md). Depending on your configuration an [account server](../../../../nats-tools/nsc/nsc.md#account-server-configuration) needs to be in place
> It is possible to [mix](jwt_nkey_auth.md) JWT and [NKEY](../auth_intro/nkey_auth.md)/[Account](../accounts.md) based Authentication/Authorization.
> It is possible to [mix](jwt_nkey_auth.md) JWT and [NKEY](../auth_intro/nkey_auth.md)/[Account](../accounts.md) based Authentication/Authorization.

109
nats-server/configuration/securing_nats/jwt/jwt_nkey_auth.md
View File

@@ -1,16 +1,12 @@
# Mixing NKEYS and Decentralized JWT Authentication/Authorization setup
# Mixed Authentication/Authorization Setup
Mixing both [nkeys](../auth_intro/nkey_auth.md) static config and [decentralized JWT Authenticatin/Authorization](README.md)
is possible but needs some preparation in order to be able to do it.
Mixing both [nkeys](../auth_intro/nkey_auth.md) static config and [decentralized JWT Authenticatin/Authorization](./) is possible but needs some preparation in order to be able to do it.
The way this can be done is by **first** preparing a basic trusted operator setup
that could be used in the future, and then base from that configuration to create the
NKEYS static config using the same shared public nkeys for the accounts and then use
clustering routes to bridge the two different auth setups during the transition.
The way this can be done is by **first** preparing a basic trusted operator setup that could be used in the future, and then base from that configuration to create the NKEYS static config using the same shared public nkeys for the accounts and then use clustering routes to bridge the two different auth setups during the transition.
For example, creating the following initial setup using [NSC](../../../../nats-tools/nsc/README.md):
For example, creating the following initial setup using [NSC](../../../../nats-tools/nsc/):
```sh
```bash
nsc add account --name SYS
nsc add user --name sys
nsc add account --name A
@@ -21,7 +17,7 @@ For example, creating the following initial setup using [NSC](../../../../nats-t
This will then generate something like the following:
```sh
```bash
nsc list accounts
╭─────────────────────────────────────────────────────────────────╮
│ Accounts │
@@ -43,15 +39,14 @@ This will then generate something like the following:
╰──────┴──────────────────────────────────────────────────────────╯
```
We could use this configuration as the initial starting configuration for an nkeys config now,
where all the NKEYS users public nkeys are explicitly listed (centralized auth model).
We could use this configuration as the initial starting configuration for an nkeys config now, where all the NKEYS users public nkeys are explicitly listed \(centralized auth model\).
```hcl
```text
port = 4222
cluster {
port = 6222
# We will bridge two different servers with different auth models via routes
# routes [ nats://127.0.0.1:6223 ]
}
@@ -77,16 +72,15 @@ accounts {
}
```
By using `nsc` it is possible to create a mem based resolver for the trusted operator setup:
```
```text
nsc generate config --mem-resolver --sys-account SYS
```
An example configuration from the second node with the trusted operator setup could then be:
```hcl
```text
port = 4223
cluster {
@@ -116,11 +110,11 @@ resolver_preload = {
}
```
Even though they have different authorization mechanisms, these two servers are able to route account messages because they share the same NKEY.
Even though they have different authorization mechanisms, these two servers are able to route account messages because they share the same NKEY.
We have created at least one user, in this case with creds:
```conf
```text
-----BEGIN NATS USER JWT-----
eyJ0eXAiOiJqd3QiLCJhbGciOiJlZDI1NTE5In0.eyJqdGkiOiJNRkM3V1E1N0hKUE9aWUVOTEhVRTZTWFVQTDVKTURWSkxIQzJRTkpYNUVJS0RGR1U1REhRIiwiaWF0IjoxNTc0Mzc1OTE2LCJpc3MiOiJBREZCMkpYWVRYT0pFTDZMTkFYRFJFVUdSWDM1Qk9MWkkzQjRQRkZBQzdJUlBSM09BNFFOS0JOMiIsIm5hbWUiOiJ0ZXN0Iiwic3ViIjoiVUFQT0syUDdFTjNVRkJMN1NCSlBRSzNNM0pNTEFMWVJZS1g1WFdTVk1WWUs2M1pNQkhUT0hWSlIiLCJ0eXBlIjoidXNlciIsIm5hdHMiOnsicHViIjp7ImFsbG93IjpbIl9JTkJPWC5cdTAwM2UiLCJfUl8iLCJfUl8uXHUwMDNlIiwidGVzdCIsInRlc3QuXHUwMDNlIl19LCJzdWIiOnsiYWxsb3ciOlsiX0lOQk9YLlx1MDAzZSIsIl9SXyIsIl9SXy5cdTAwM2UiLCJsYXRlbmN5Lm9uLnRlc3QiLCJ0ZXN0IiwidGVzdC5cdTAwM2UiXX19fQ.MSU2aUIBK1iUsg7h52lLrfEfTwVMF_wB3HDq75ECskxSyyDDMtk9_3957UtQF-3yoGCIhKOkWjzX8C-WXnLADw
------END NATS USER JWT------
@@ -133,7 +127,7 @@ SUANVBWRHHFMGHNIT6UJHPN2TGVBVIILE7VPVNEQ7DGCJ26ZD2V3KAHT4M
*************************************************************
```
And this same user is able to connect to either one of the servers (bound to 4222 and 4223 respectively):
And this same user is able to connect to either one of the servers \(bound to 4222 and 4223 respectively\):
Subscriber Service:
@@ -141,34 +135,34 @@ Subscriber Service:
package main
import (
"log"
"log"
"github.com/nats-io/nats.go"
"github.com/nats-io/nats.go"
)
func main() {
opts := make([]nats.Option, 0)
opts := make([]nats.Option, 0)
// Extract public nkey from seed
//
// Public: UAPOK2P7EN3UFBL7SBJPQK3M3JMLALYRYKX5XWSVMVYK63ZMBHTOHVJR
// Private: SUANVBWRHHFMGHNIT6UJHPN2TGVBVIILE7VPVNEQ7DGCJ26ZD2V3KAHT4M
//
nkey, err := nats.NkeyOptionFromSeed("path/to/seed.nkey")
if err != nil {
log.Fatal(err)
}
opts = append(opts, nkey)
nc, err := nats.Connect("127.0.0.1:4222", opts...)
if err != nil {
log.Fatal(err)
}
nc.Subscribe("test", func(m *nats.Msg){
log.Printf("[Received] %q, replying... \n", string(m.Data))
m.Respond([]byte("pong from nkeys based server"))
})
// Extract public nkey from seed
//
// Public: UAPOK2P7EN3UFBL7SBJPQK3M3JMLALYRYKX5XWSVMVYK63ZMBHTOHVJR
// Private: SUANVBWRHHFMGHNIT6UJHPN2TGVBVIILE7VPVNEQ7DGCJ26ZD2V3KAHT4M
//
nkey, err := nats.NkeyOptionFromSeed("path/to/seed.nkey")
if err != nil {
log.Fatal(err)
}
opts = append(opts, nkey)
nc, err := nats.Connect("127.0.0.1:4222", opts...)
if err != nil {
log.Fatal(err)
}
nc.Subscribe("test", func(m *nats.Msg){
log.Printf("[Received] %q, replying... \n", string(m.Data))
m.Respond([]byte("pong from nkeys based server"))
})
select {}
select {}
}
```
@@ -178,25 +172,26 @@ Requestor:
package main
import (
"log"
"time"
"log"
"time"
"github.com/nats-io/nats.go"
"github.com/nats-io/nats.go"
)
func main() {
nc, err := nats.Connect("127.0.0.1:4223", nats.UserCredentials("path/to/user.creds"))
if err != nil {
log.Fatal(err)
}
nc, err := nats.Connect("127.0.0.1:4223", nats.UserCredentials("path/to/user.creds"))
if err != nil {
log.Fatal(err)
}
for range time.NewTicker(1 * time.Second).C {
resp, err := nc.Request("test", []byte("test"), 1*time.Second)
if err != nil {
log.Println("[Error]", err)
continue
}
log.Println("[Received]", string(resp.Data))
}
for range time.NewTicker(1 * time.Second).C {
resp, err := nc.Request("test", []byte("test"), 1*time.Second)
if err != nil {
log.Println("[Error]", err)
continue
}
log.Println("[Received]", string(resp.Data))
}
}
```

4
nats-server/configuration/securing_nats/jwt/mem_resolver.md
View File

@@ -1,4 +1,4 @@
# Memory Resolver
# Memory Resolver Tutorial
The `MEMORY` resolver is a server built-in resolver for account JWTs. If there are a small number of accounts, or they do not change too often this can be a simpler configuration that does not require an external account resolver. Server configuration reload is supported, meaning the preloads can be updated in the server configuration and reloaded without a server restart.
@@ -60,7 +60,7 @@ Success!! - generated "/tmp/server.conf"
generated "/tmp/memory.jwt"
```
If you require additional settings, you may want to consider using [`include`](../../nats-server/configuration/#include-directive) in your main configuration, to reference the generated files. Otherwise, you can start a server and reference the generated configuration:
If you require additional settings, you may want to consider using [`include`](../../#include-directive) in your main configuration, to reference the generated files. Otherwise, you can start a server and reference the generated configuration:
```text
> nats-server -c /tmp/server.conf

16
nats-server/configuration/securing_nats/jwt/resolver.md
View File

@@ -1,15 +1,15 @@
# resolver
# Account lookup using Resolver
The `resolver` configuration option is used in conjunction with [NATS JWT Authentication](README.md) and [nsc](../../nats-tools/nsc/nsc). The `resolver` option specifies a URL where the nats-server can retrieve an account JWT. There are two built-in resolver implementations:
The `resolver` configuration option is used in conjunction with [NATS JWT Authentication](./) and [nsc](https://github.com/nats-io/nats.docs/tree/aecb86faf9be946a413d1c6200fc0ff5d1b0baef/nats-server/configuration/nats-tools/nsc/nsc/README.md). The `resolver` option specifies a URL where the nats-server can retrieve an account JWT. There are two built-in resolver implementations:
* `URL`
* `MEMORY`
- `URL`
- `MEMORY`
> If the operator JWT specified in `operator` contains an account resolver URL, `resolver` only needs to be specified in order to overwrite that default.
## URL Resolver
The `URL` resolver specifies a URL where the server can append an account public key to retrieve that account's JWT. Convention for [NATS Account JWT Servers](../../nats-tools/nas) is to serve JWTs at: `http://localhost:9090/jwt/v1/accounts/`. For such a configuration you would specify the resolver as follows:
The `URL` resolver specifies a URL where the server can append an account public key to retrieve that account's JWT. Convention for [NATS Account JWT Servers](https://github.com/nats-io/nats.docs/tree/aecb86faf9be946a413d1c6200fc0ff5d1b0baef/nats-server/configuration/nats-tools/nas/README.md) is to serve JWTs at: `http://localhost:9090/jwt/v1/accounts/`. For such a configuration you would specify the resolver as follows:
```yaml
resolver: URL(http://localhost:9090/jwt/v1/accounts/)
@@ -17,8 +17,7 @@ resolver: URL(http://localhost:9090/jwt/v1/accounts/)
> Note that if you are not using a nats-account-server, the URL can be anything as long as by appending the public key for an account, the requested JWT is returned.
If the server used requires client authentication, or you want to specify which CA is trusted for the lookup of account information, specify `resolver_tls`.
This [`tls` configuration map](securing_nats/tls.md) lets you further restrict TLS to the resolver.
If the server used requires client authentication, or you want to specify which CA is trusted for the lookup of account information, specify `resolver_tls`. This [`tls` configuration map](https://github.com/nats-io/nats.docs/tree/aecb86faf9be946a413d1c6200fc0ff5d1b0baef/nats-server/configuration/securing_nats/jwt/securing_nats/tls.md) lets you further restrict TLS to the resolver.
## MEMORY
@@ -34,3 +33,4 @@ ACSU3Q6LTLBVLGAQUONAGXJHVNWGSKKAUA7IY5TB4Z7PLEKSR5O6JTGR: eyJ0eXAiOiJqd3QiLCJhbG
The `MEMORY` resolver is recommended when the server has a small number of accounts that don't change very often.
For more information on how to configure a memory resolver, see [this tutorial](mem_resolver.md).

71
nats-server/configuration/securing_nats/tls.md
View File

@@ -10,7 +10,7 @@ The NATS server uses modern TLS semantics to encrypt client, route, and monitori
| `cipher_suites` | When set, only the specified TLS cipher suites will be allowed. Values must match the golang version used to build the server. |
| `curve_preferences` | List of TLS cipher curves to use in order. |
| `insecure` | Skip certificate verification. **NOT Recommended** |
| `timeout` | TLS handshake [timeout](#TLS-Timeout) in fractional seconds. Default set to `0.5` seconds. |
| `timeout` | TLS handshake [timeout](tls.md#TLS-Timeout) in fractional seconds. Default set to `0.5` seconds. |
| `verify` | If `true`, require and [verify](auth_intro/tls_mutual_auth.md#Validating-a-Client-Certificate) client certificates. To support use by Browser, this option does not apply to monitoring. |
| `verify_and_map` | If `true`, require and verify client certificates and [map](auth_intro/tls_mutual_auth.md#Mapping-Client-Certificates-To-A-User) certificate values for authentication purposes. Does not apply to monitoring either. |
@@ -61,68 +61,53 @@ tls: {
## Self Signed Certificates for Testing
Explaining [Public key infrastructure](https://en.wikipedia.org/wiki/Public_key_infrastructure), [Certificate Authorities (CA)](https://en.wikipedia.org/wiki/Certificate_authority) and [x509](https://tools.ietf.org/html/rfc5280) [certificates](https://en.wikipedia.org/wiki/Public_key_certificate) fall well outside the scope of this document.
So does an explanation on how to obtain a properly trusted certificates.
Explaining [Public key infrastructure](https://en.wikipedia.org/wiki/Public_key_infrastructure), [Certificate Authorities \(CA\)](https://en.wikipedia.org/wiki/Certificate_authority) and [x509](https://tools.ietf.org/html/rfc5280) [certificates](https://en.wikipedia.org/wiki/Public_key_certificate) fall well outside the scope of this document. So does an explanation on how to obtain a properly trusted certificates.
If anybody outside your organization needs to connect, get certs from a public certificate authority.
Think carefully about revocation and cycling times, as well as automation, when picking a CA.
If arbitrary applications inside your organization need to connect, use a cert from your in-house CA.
If only resources inside a specific environment need to connect, that environment might have its own dedicated automatic CA, eg in Kubernetes clusters, so use that.
If anybody outside your organization needs to connect, get certs from a public certificate authority. Think carefully about revocation and cycling times, as well as automation, when picking a CA. If arbitrary applications inside your organization need to connect, use a cert from your in-house CA. If only resources inside a specific environment need to connect, that environment might have its own dedicated automatic CA, eg in Kubernetes clusters, so use that.
**Only** for **testing** purposes does it makes sense to generate self signed certificates, even your own CA.
This is a **short** guide on how to do just that and what to watch out for.
**Only** for **testing** purposes does it makes sense to generate self signed certificates, even your own CA. This is a **short** guide on how to do just that and what to watch out for.
> **DO NOT USE these certificates in production!!!**
### Problems With Self Signed Certificates
#### Missing in Relevant Trust Stores
#### Missing in Relevant Trust Stores
As they should, these are **not trusted** by the system your server or clients are running on.
One option is to specify the CA in every client you are using.
In case you make use of `verify` and `verify_and_map` you need to specify `ca_file` in the server.
If you are having a more complex setup involving cluster, gateways or leaf nodes, `ca_file` needs to be present in `tls` maps used to connect to the server with self signed certificates.
While this works for server and libraries from the NATS eco system, you will experience issues when connecting with other tools such as your Browser.
One option is to specify the CA in every client you are using. In case you make use of `verify` and `verify_and_map` you need to specify `ca_file` in the server. If you are having a more complex setup involving cluster, gateways or leaf nodes, `ca_file` needs to be present in `tls` maps used to connect to the server with self signed certificates. While this works for server and libraries from the NATS eco system, you will experience issues when connecting with other tools such as your Browser.
Another option is to configure your system's trust store to include self signed certificate\(s\). Which trust store needs to be configured depends on what you are testing.
Another option is to configure your system's trust store to include self signed certificate(s).
Which trust store needs to be configured depends on what you are testing.
* This may be your OS for server and certain clients.
* The runtime environment for other clients like Java, Python or Node.js.
* Your browser for monitoring endpoints and websockets.
Please check your system's documentation on how to trust a particular self signed certificate.
#### Missing Subject Alternative Name
#### Missing Subject Alternative Name
Another common problem is failed [identity validation](https://tools.ietf.org/html/rfc6125).
The IP or DNS name to connect to needs to match a [Subject Alternative Name (SAN)](https://tools.ietf.org/html/rfc4985) inside the certificate.
Meaning, if a client/browser/server connect via tls to `127.0.0.1`, the server needs to present a certificate with a SAN containing the IP `127.0.0.1` or the connection will be closed with a handshake error.
Another common problem is failed [identity validation](https://tools.ietf.org/html/rfc6125). The IP or DNS name to connect to needs to match a [Subject Alternative Name \(SAN\)](https://tools.ietf.org/html/rfc4985) inside the certificate. Meaning, if a client/browser/server connect via tls to `127.0.0.1`, the server needs to present a certificate with a SAN containing the IP `127.0.0.1` or the connection will be closed with a handshake error.
#### Wrong Key Usage
When generating your certificate you need to make sure to include the right purpose for which you want to use the certificate.
This is encoded in [key usage](https://tools.ietf.org/html/rfc5280#section-4.2.1.3) and [extended key usage](https://tools.ietf.org/html/rfc5280#section-4.2.1.12).
The necessary values for key usage depend on the ciphers used. `Digital Signature` and `Key Encipherment` are an interoperable choice.
When generating your certificate you need to make sure to include the right purpose for which you want to use the certificate. This is encoded in [key usage](https://tools.ietf.org/html/rfc5280#section-4.2.1.3) and [extended key usage](https://tools.ietf.org/html/rfc5280#section-4.2.1.12). The necessary values for key usage depend on the ciphers used. `Digital Signature` and `Key Encipherment` are an interoperable choice.
With respect to NATS the relevant values for extended key usage are:
* `TLS WWW server authentication` - To authenticate as server for incoming connections. A NATS server will need a certificate containing this.
* `TLS WWW client authentication` - To authenticate as client for outgoing connections. Only needed when connecting to a server where `verify` or `verify_and_map` are specified. In these cases, a NATS client will need a certificate with this value.
* [Leaf node](../leafnodes/README.md) connections can be configured with `verify` as well. Then connecting NATS server will have to present a certificate with this value too. Certificates containing both values are an option.
* [Cluster](../clustering/README.md) connections always have `verify` enabled. Which server acts as client and server comes down to timing and therefore can't be individually configured. Certificates containing both values are a must.
* [Gateway](../gateways/README.md) connections always have `verify` enabled. Unlike cluster outgoing connections can specify a separate cert. Certificates containing both values are an option that reduce configuration.
* [Leaf node](../leafnodes/) connections can be configured with `verify` as well. Then connecting NATS server will have to present a certificate with this value too. Certificates containing both values are an option.
* [Cluster](../clustering/) connections always have `verify` enabled. Which server acts as client and server comes down to timing and therefore can't be individually configured. Certificates containing both values are a must.
* [Gateway](../gateways/) connections always have `verify` enabled. Unlike cluster outgoing connections can specify a separate cert. Certificates containing both values are an option that reduce configuration.
Note that it's common practice for non-web protocols to use the `TLS WWW` authentication fields, as a matter of history those have become embedded as generic options.
### Creating Self Signed Certificates for Testing
The simplest way to generate a CA as well as client and server certificates is [mkcert](https://github.com/FiloSottile/mkcert).
This zero config tool generates and installs the CA into your **local** system trust store(s) and makes providing SAN straight forward.
Check it's [documentation](https://github.com/FiloSottile/mkcert/blob/master/README.md) for installation and your system's trust store.
Here is a simple example:
The simplest way to generate a CA as well as client and server certificates is [mkcert](https://github.com/FiloSottile/mkcert). This zero config tool generates and installs the CA into your **local** system trust store\(s\) and makes providing SAN straight forward. Check it's [documentation](https://github.com/FiloSottile/mkcert/blob/master/README.md) for installation and your system's trust store. Here is a simple example:
Generate a CA as well as a certificate, valid for server authentication by `localhost` and the IP `::1`(`-cert-file` and `-key-file` overwrite default file names).
Then start a nats server using the generated certificate.
Generate a CA as well as a certificate, valid for server authentication by `localhost` and the IP `::1`\(`-cert-file` and `-key-file` overwrite default file names\). Then start a nats server using the generated certificate.
```bash
mkcert -install
@@ -131,36 +116,27 @@ nats-server --tls --tlscert=server-cert.pem --tlskey=server-key.pem -ms 8222
```
Now you should be able to access the monitoring endpoint `https://localhost:8222` with your browser.
`https://127.0.0.1:8222` however should result in an error as `127.0.0.1` is not listed as SAN.
You will not be able to establish a connection from another computer either.
For that to work you have to provide appropriate DNS and/or IP [SAN(s)](#Missing-Subject-Alternative-Name)
`https://127.0.0.1:8222` however should result in an error as `127.0.0.1` is not listed as SAN. You will not be able to establish a connection from another computer either. For that to work you have to provide appropriate DNS and/or IP [SAN\(s\)](tls.md#Missing-Subject-Alternative-Name)
To generate certificates that work with `verify` provide the `-client` option.
This will cause it to add an appropriate key usage for client authentication.
Please note that client refers to connecting process, not necessarily a NATS client.
Also add a SAN email for usage as user name in `verify_and_map`.
To generate certificates that work with `verify` provide the `-client` option. This will cause it to add an appropriate key usage for client authentication. Please note that client refers to connecting process, not necessarily a NATS client. Also add a SAN email for usage as user name in `verify_and_map`.
```bash
mkcert -client -cert-file client-cert.pem -key-file client-key.pem localhost ::1 email@localhost
```
Examples in this document make use of the certificates generated so far.
To simplify examples using the CA certificate, copy `rootCA.pem` into the same folder where the certificates were generated.
To obtain the CA certificate's location use this command:
Examples in this document make use of the certificates generated so far. To simplify examples using the CA certificate, copy `rootCA.pem` into the same folder where the certificates were generated. To obtain the CA certificate's location use this command:
```bash
mkcert -CAROOT
```
Once you are done testing, remove the CA from your **local** system trust store(s).
Once you are done testing, remove the CA from your **local** system trust store\(s\).
```
```text
mkcert -uninstall
```
Alternatively, you can also use [openssl](https://www.openssl.org/) to [generate certificates](https://www.digitalocean.com/community/tutorials/openssl-essentials-working-with-ssl-certificates-private-keys-and-csrs).
This tool allows a lot more customization of the generated certificates.
It is a lot **more complex** and does **not manage** installation into the system trust store(s).
Alternatively, you can also use [openssl](https://www.openssl.org/) to [generate certificates](https://www.digitalocean.com/community/tutorials/openssl-essentials-working-with-ssl-certificates-private-keys-and-csrs). This tool allows a lot more customization of the generated certificates. It is a lot **more complex** and does **not manage** installation into the system trust store\(s\).
However, for inspecting certificates it is quite handy. To inspect the certificates from the above example execute these commands:
@@ -168,3 +144,4 @@ However, for inspecting certificates it is quite handy. To inspect the certifica
openssl x509 -noout -text -in server-cert.pem
openssl x509 -noout -text -in client-cert.pem
```

22
nats-server/configuration/sys_accounts/README.md
View File

@@ -1,6 +1,6 @@
# System Events and Services
# System Events
NATS servers leverage [Accounts](../../configuration/securing_nats/accounts.md) support and generate events such as:
NATS servers leverage [Accounts](../securing_nats/accounts.md) support and generate events such as:
* account connect/disconnect
* authentication errors
@@ -9,12 +9,12 @@ NATS servers leverage [Accounts](../../configuration/securing_nats/accounts.md)
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 [subscribing/requesting](#Available-Events-and-Services) using a _system account_ user.
These events are enabled by configuring `system_account` and [subscribing/requesting](./#Available-Events-and-Services) using a _system account_ user.
[Accounts](../../configuration/securing_nats/accounts.md) are used so that subscriptions from your applications, say `>`, do not receive system events and vice versa.
Using accounts requires either:
* [Configuring authentication locally](#Local-Configuration) and listing one of the accounts in `system_account`
* Or by using decentralized authentication and authorization via [jwt](../../configuration/securing_nats/jwt/README.md) as shown in this [Tutorial](sys_accounts.md). In this case `system_account` contains the account public key.
[Accounts](../securing_nats/accounts.md) are used so that subscriptions from your applications, say `>`, do not receive system events and vice versa. Using accounts requires either:
* [Configuring authentication locally](./#Local-Configuration) and listing one of the accounts in `system_account`
* Or by using decentralized authentication and authorization via [jwt](../securing_nats/jwt/) as shown in this [Tutorial](https://github.com/nats-io/nats.docs/tree/aecb86faf9be946a413d1c6200fc0ff5d1b0baef/nats-server/configuration/sys_accounts/sys_accounts.md). In this case `system_account` contains the account public key.
## Available Events and Services
@@ -30,7 +30,7 @@ Server initiated events:
* `$SYS.ACCOUNT.<id>.LEAFNODE.DISCONNECT` \(leaf node disconnects\)
* `$SYS.SERVER.<id>.STATSZ` \(stats summary\)
In addition other tools with system account privileges, can initiate requests (Examples can be found [here](sys_accounts.md#System-Services)):
In addition other tools with system account privileges, can initiate requests \(Examples can be found [here](https://github.com/nats-io/nats.docs/tree/aecb86faf9be946a413d1c6200fc0ff5d1b0baef/nats-server/configuration/sys_accounts/sys_accounts.md#System-Services)\):
* `$SYS.REQ.SERVER.<id>.STATSZ` \(request server stat summary\)
* `$SYS.REQ.SERVER.PING` \(discover servers - will return multiple messages\)
@@ -66,7 +66,5 @@ accounts: {
system_account: SYS
```
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 [here](sys_accounts.md#System-Services).
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 [here](sys_accounts.md#system-services).

18
nats-server/configuration/sys_accounts/sys_accounts.md
View File

@@ -1,11 +1,13 @@
# Enabling System Events with Decentralized Authentication/Authorization
# System Events & Decentralized JWT Tutorial
## Enabling System Events with Decentralized Authentication/Authorization
To enable and access system events, you'll have to:
* Create an Operator, Account and User
* Run a NATS Account Server \(or Memory Resolver\)
## Create an Operator, Account, User
### Create an Operator, Account, User
Let's create an operator, system account and system account user:
@@ -29,7 +31,7 @@ Success! - added user "SYSU" to "SYS"
By default, the operator JWT can be found in `~/.nsc/nats/<operator_name>/<operator.name>.jwt`.
## NATS-Account-Server
### NATS-Account-Server
To vend the credentials to the nats-server, we'll use a [nats-account-server](../../../nats-tools/nas/). Let's start a nats-account-server to serve the JWT credentials:
@@ -39,7 +41,7 @@ To vend the credentials to the nats-server, we'll use a [nats-account-server](..
The server will by default vend JWT configurations on the an endpoint at: `http(s)://<server_url>/jwt/v1/accounts/`.
## NATS Server Configuration
### NATS Server Configuration
The server configuration will need:
@@ -76,7 +78,7 @@ Let's start the nats-server:
> nats-server -c server.conf
```
# Inspecting Server Events
## Inspecting Server Events
Let's add a subscriber for all the events published by the system account:
@@ -136,9 +138,9 @@ The subscriber will print the connect and disconnect:
}'
```
# System Services
## System Services
## `$SYS.REQ.SERVER.PING` - Discovering Servers
### `$SYS.REQ.SERVER.PING` - Discovering Servers
To discover servers in the cluster, and get a small heath summary, publish a request to `$SYS.REQ.SERVER.PING`. Note that while the example below uses `nats-req`, only the first answer for the request will be printed. You can easily modify the example to wait until no additional responses are received for a specific amount of time, thus allowing for all responses to be collected.
@@ -175,7 +177,7 @@ Received [_INBOX.G5mbsf0k7l7nb4eWHa7GTT.omklmvnm] : '{
}'
```
## `$SYS.SERVER.<id>.STATSZ` - Requesting Server Stats Summary
### `$SYS.SERVER.<id>.STATSZ` - Requesting Server Stats Summary
If you know the server id for a particular server \(such as from a response to `$SYS.REQ.SERVER.PING`\), you can query the specific server for its health information:

6
nats-server/flags.md
View File

@@ -49,9 +49,9 @@ The following flags are available on the server to configure logging:
| `-r`, `--remote_syslog` | The syslog server address, like `udp://localhost:514` |
| `-D`, `--debug` | Enable debugging output |
| `-V`, `--trace` | Enable protocol trace log messages |
| `-VV` | Verbose trace (traces system account as well) |
| `-VV` | Verbose trace \(traces system account as well\) |
| `-DV` | Enable both debug and protocol trace messages |
| `-DVV` | Debug and verbose trace (traces system account as well)|
| `-DVV` | Debug and verbose trace \(traces system account as well\) |
| `--max_traced_msg_len` | Maximum printable length for traced messages. 0 for unlimited |
You can read more about [logging configuration here](configuration/logging.md).
@@ -80,7 +80,7 @@ The following flags are available on the server to configure clustering:
| `--cluster_advertise` | Cluster URL to advertise to other servers |
| `--connect_retries` | For implicit routes, number of connect retries |
You can read more about [clustering configuration here](configuration/clustering/README.md).
You can read more about [clustering configuration here](configuration/clustering/).
## Common Options

43
nats-server/installation.md
View File

@@ -32,7 +32,7 @@ To run NATS on Docker:
[1] 2019/05/24 15:42:58.229003 [INF] Listening for route connections on 0.0.0.0:6222
```
More information on [containerized NATS is available here](nats_docker/README.md).
More information on [containerized NATS is available here](nats_docker/).
## Installing on Kubernetes with NATS Operator
@@ -107,14 +107,14 @@ To test your installation \(provided the $GOPATH/bin is set\):
If you are having issues when using the recent versions of NATS and Go modules such as:
```
```text
go: github.com/nats-io/go-nats@v1.8.1: parsing go.mod: unexpected module path "github.com/nats-io/nats.go"
go: github.com/nats-io/go-nats-streaming@v0.5.0: parsing go.mod: unexpected module path "github.com/nats-io/stan.go"
```
To fix it:
To fix it:
1) Update your `go.mod` using the latest tags, for example for both NATS and NATS Streaming clients:
1\) Update your `go.mod` using the latest tags, for example for both NATS and NATS Streaming clients:
```ruby
module github.com/wallyqs/hello-nats-go-mod
@@ -122,8 +122,8 @@ module github.com/wallyqs/hello-nats-go-mod
go 1.12
require (
github.com/nats-io/nats.go v1.8.1
github.com/nats-io/stan.go v0.5.0
github.com/nats-io/nats.go v1.8.1
github.com/nats-io/stan.go v0.5.0
)
```
@@ -131,8 +131,8 @@ Or if you want to import the NATS Server v2 to embed it, notice the `/v2` after
```ruby
require (
github.com/nats-io/nats-server/v2 v2.0.0
github.com/nats-io/nats.go v1.8.1
github.com/nats-io/nats-server/v2 v2.0.0
github.com/nats-io/nats.go v1.8.1
)
```
@@ -140,14 +140,14 @@ If embedding both NATS Streaming and NATS Servers:
```ruby
require (
github.com/nats-io/nats-server/v2 v2.0.0 // indirect
github.com/nats-io/nats-streaming-server v0.15.1
)
github.com/nats-io/nats-server/v2 v2.0.0 // indirect
github.com/nats-io/nats-streaming-server v0.15.1
)
```
2) Next, update the imports within the repo:
2\) Next, update the imports within the repo:
```sh
```bash
find ./ -type f -name "*.go" -exec sed -i -e 's/github.com\/nats-io\/go-nats-streaming/github.com\/nats-io\/stan.go/g' {} \;
find ./ -type f -name "*.go" -exec sed -i -e 's/github.com\/nats-io\/go-nats/github.com\/nats-io\/nats.go/g' {} \;
@@ -157,35 +157,35 @@ find ./ -type f -name "*.go" -exec sed -i -e 's/github.com\/nats-io\/gnatsd/gith
find ./ -type f -name "*.go" -exec sed -i -e 's/github.com\/nats-io\/nats-server/github.com\/nats-io\/nats-server\/v2/g' {} \;
```
3) (Recommended) Run Go fmt as the rename will affect the proper ordering of the imports
3\) \(Recommended\) Run Go fmt as the rename will affect the proper ordering of the imports
### Gotchas when using `go get`
### Gotchas when using `go get`
When using `go get` to fetch the client, include an extra slash at the end of the repo. For example:
```
```text
GO111MODULE=on go get github.com/nats-io/nats.go/@latest
GO111MODULE=on go get github.com/nats-io/nats.go/@v1.8.1
```
When trying to fetch the latest version of the server with `go get`, you have to add `v2` at the end:
```
```text
GO111MODULE=on go get github.com/nats-io/nats-server/v2@latest
```
Otherwise, `go get` will fetch the `v1.4.1` version of the server, which is also named (`gnatsd`), the previous name for nats-server.
Otherwise, `go get` will fetch the `v1.4.1` version of the server, which is also named \(`gnatsd`\), the previous name for nats-server.
```
```text
GO111MODULE=on go get github.com/nats-io/nats-server@latest
go: finding github.com/nats-io/gnatsd/server latest
go: finding golang.org/x/crypto/bcrypt latest
go: finding golang.org/x/crypto latest
```
In order to use an older tag, you will have to use the previous name (gnatsd) otherwise it will result in `go mod` parsing errors.
In order to use an older tag, you will have to use the previous name \(gnatsd\) otherwise it will result in `go mod` parsing errors.
```
```text
# OK
GO111MODULE=on go get github.com/nats-io/go-nats/@v1.7.2
@@ -205,3 +205,4 @@ go: error loading module requirements
```
For more information you can review the original issue in [GitHub](https://github.com/nats-io/nats.go/issues/478).

5
nats-server/nats_admin/README.md
View File

@@ -6,5 +6,6 @@ Managing a NATS server is simple, typical lifecycle operations include:
* [Upgrading](upgrading_cluster.md) a server \(or cluster\)
* Understanding [slow consumers](slow_consumers.md)
* Monitoring the server via:
* The monitoring [endpoint](../configuration/monitoring.md) and tools like [nats-top](../../nats-tools/nats_top/README.md)
* By subscribing to [system events](../configuration/sys_accounts/sys_accounts.md)
* The monitoring [endpoint](../configuration/monitoring.md) and tools like [nats-top](../../nats-tools/nats_top/)
* By subscribing to [system events](https://github.com/nats-io/nats.docs/tree/e59525da15403e4a01839339b24d7804d4a26db9/nats-server/configuration/sys_accounts/sys_accounts.md)

2
nats-server/running/README.md
View File

@@ -32,5 +32,5 @@ docker run -p 4222:4222 -ti nats:latest
...
```
More information on [containerized NATS is available here](../nats_docker/README.md).
More information on [containerized NATS is available here](../nats_docker/).