mirror of
https://github.com/taigrr/nats.docs
synced 2025-01-18 04:03:23 -08:00
GitBook: [master] 61 pages modified
This commit is contained in:
Ginger Collison
gitbook-bot
parent
ed6c1ba06d
commit
de933e912d
@ -84,7 +84,7 @@
|
||||
* [Multi Tenancy using Accounts](nats-server/configuration/securing_nats/accounts.md)
|
||||
* [Decentralized JWT Authentication/Authorization](nats-server/configuration/securing_nats/jwt/README.md)
|
||||
* [Account lookup using Resolver](nats-server/configuration/securing_nats/jwt/resolver.md)
|
||||
* [Memory Resolver Tutorial](nats-server/configuration/securing_nats/jwt/mem_resolver.md))
|
||||
* [Memory Resolver Tutorial](nats-server/configuration/securing_nats/jwt/mem_resolver.md)
|
||||
* [Mixed Authentication/Authorization Setup](nats-server/configuration/securing_nats/jwt/jwt_nkey_auth.md)
|
||||
* [Clustering](nats-server/configuration/clustering/README.md)
|
||||
* [Configuration](nats-server/configuration/clustering/cluster_config.md)
|
||||
|
||||
@ -16,12 +16,7 @@ sub, err := sc.Subscribe("foo",
|
||||
}, stan.SetManualAckMode(), stan.AckWait(aw))
|
||||
```
|
||||
|
||||
> Note that if processing a particular message exceeds ack wait, the following behavior can be observed with [queue subscriptions](queues.md):
|
||||
> 1. Subscriber A receives the message.
|
||||
> 2. Subscriber A exceeds ack wait time and Subscriber B receives the message.
|
||||
> 3. Subscriber B exceeds ack wait time and Subscriber C receives the message.
|
||||
> 6. Subscriber A finishes processing and acknowledges the message.
|
||||
> 7. Re-delivery of the message ceases.
|
||||
> Note that if processing a particular message exceeds ack wait, the following behavior can be observed with [queue subscriptions](queues.md): 1. Subscriber A receives the message. 2. Subscriber A exceeds ack wait time and Subscriber B receives the message. 3. Subscriber B exceeds ack wait time and Subscriber C receives the message. 6. Subscriber A finishes processing and acknowledges the message. 7. Re-delivery of the message ceases.
|
||||
>
|
||||
> How often the message is re-delivered depends on processing time for the message and available subscriber.
|
||||
|
||||
|
||||
@ -1,10 +1,10 @@
|
||||
# Miscellaneous Functionalities
|
||||
# Miscellaneous functionalities
|
||||
|
||||
This section contains miscellaneous functionalities and options for connect.
|
||||
|
||||
## Get the Maximum Payload Size
|
||||
|
||||
While the client can't control the maximum payload size, clients may provide a way for applications to obtain the configured [`max_payload`](../../nats-server/configuration/README.md#limits) after the connection is made. This will allow the application to chunk or limit data as needed to pass through the server.
|
||||
While the client can't control the maximum payload size, clients may provide a way for applications to obtain the configured [`max_payload`](../../nats-server/configuration/#limits) after the connection is made. This will allow the application to chunk or limit data as needed to pass through the server.
|
||||
|
||||
{% tabs %}
|
||||
{% tab title="Go" %}
|
||||
@ -182,9 +182,7 @@ nc.close();
|
||||
|
||||
## Set the Maximum Control Line Size
|
||||
|
||||
The protocol between the client and the server is fairly simple and relies on a control line and sometimes a body. The control line contains the operations being sent, like PING or PONG, followed by a carriage return and line feed, CRLF or "\r\n".
|
||||
The server has a [`max_control_line`](../../nats-server/configuration/README.md#limits) option that can limit the maximum size of a control line. For PING and PONG this doesn't come into play, but for messages that contain subject names and possibly queue group names, the control line length can be important as it effectively limits the possibly combined length.
|
||||
Some clients will try to limit the control line size internally to prevent an error from the server. These clients may or may not allow you to set the size being used, but if they do, the size should be set to match the server configuration.
|
||||
The protocol between the client and the server is fairly simple and relies on a control line and sometimes a body. The control line contains the operations being sent, like PING or PONG, followed by a carriage return and line feed, CRLF or "\r\n". The server has a [`max_control_line`](../../nats-server/configuration/#limits) option that can limit the maximum size of a control line. For PING and PONG this doesn't come into play, but for messages that contain subject names and possibly queue group names, the control line length can be important as it effectively limits the possibly combined length. Some clients will try to limit the control line size internally to prevent an error from the server. These clients may or may not allow you to set the size being used, but if they do, the size should be set to match the server configuration.
|
||||
|
||||
> It is not recommended to set this to a value that is higher than the one of other clients or the nats-server.
|
||||
|
||||
@ -244,8 +242,7 @@ let nc = NATS.connect({
|
||||
|
||||
Clients can request _verbose_ mode from NATS server. When requested by a client, the server will reply to every message from that client with either a +OK or an error -ERR. However, the client will not block and wait for a response. Errors will be sent without verbose mode as well and client libraries handle them as documented.
|
||||
|
||||
> This functionality is only used for debugging the client library or the nats-server themselves.
|
||||
> By default the server sets it to on, but every client turns it off.
|
||||
> This functionality is only used for debugging the client library or the nats-server themselves. By default the server sets it to on, but every client turns it off.
|
||||
|
||||
To turn on verbose mode:
|
||||
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
# Setting the Connection Name
|
||||
# Connection Name
|
||||
|
||||
Connections can be assigned a name which will appear in some of the server monitoring data. This name is not required, but is **highly recommended** as a friendly connection name will help in monitoring, error reporting, debugging, and testing.
|
||||
|
||||
@ -87,3 +87,4 @@ nc.close();
|
||||
```
|
||||
{% endtab %}
|
||||
{% endtabs %}
|
||||
|
||||
|
||||
@ -94,3 +94,4 @@ nc.close();
|
||||
```
|
||||
{% endtab %}
|
||||
{% endtabs %}
|
||||
|
||||
|
||||
@ -368,3 +368,4 @@ nc.on('error', (err) => {
|
||||
```
|
||||
{% endtab %}
|
||||
{% endtabs %}
|
||||
|
||||
|
||||
@ -6,4 +6,5 @@ Some languages, like Go or Java, provide synchronous and asynchronous APIs, whil
|
||||
|
||||
In all cases, the process of subscribing involves having the client library tell the NATS system that an application is interested in a particular subject. When an application is done with a subscription it unsubscribes telling the server to stop sending messages.
|
||||
|
||||
A client will receive a message for each matching subscription ,so if a connection has multiple subscriptions using identical or overlapping subjects (say `foo` and `>`) the same message will be sent to the client multiple times.
|
||||
A client will receive a message for each matching subscription ,so if a connection has multiple subscriptions using identical or overlapping subjects \(say `foo` and `>`\) the same message will be sent to the client multiple times.
|
||||
|
||||
|
||||
@ -122,3 +122,4 @@ await nc.subscribe('updates', (err, msg) => {
|
||||
{% endtabs %}
|
||||
|
||||
If you run this example with the publish examples that send to `updates`, you will see that one of the instances gets a message while the others you run won't. But the instance that receives the message will change.
|
||||
|
||||
|
||||
@ -3,3 +3,4 @@
|
||||
Most, if not all, of the client libraries will reconnect to the NATS system if they are disconnected for any reason. The reconnect logic can differ by library, so check your client library's documentation.
|
||||
|
||||
In general, the client will try to re-connect to one of the servers it knows about, either through the URLs provided in the `connect` call or the URLs provided by the NATS system during earlier connects. This feature allows NATS applications and the NATS system itself to self heal and reconfigure itself with no additional configuration or intervention. The library may have several options to help control reconnect behavior, to notify about reconnect state and to inform about a new server.
|
||||
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
# Authenticating with a Credentials File
|
||||
|
||||
The 2.0 version of NATS server introduced the idea of decentralized authentication based on [JSON Web Tokens \(JWT\)](https://jwt.io/). Clients interact with this new scheme using a [user JWT](../../nats-server/configuration/securing_nats/jwt/README.md) and corresponding [NKey](../../nats-server/configuration/securing_nats/auth_intro/nkey_auth.md) private key. To help make connecting with a JWT easier, the client libraries support the concept of a credentials file. This file contains both the private key and the JWT and can be generated with the `nsc` [tool](../../nats-tools/nsc/README.md). The contents will look like the following and should be protected because it contains a private key. This credentials file is unused and only for example purposes.
|
||||
The 2.0 version of NATS server introduced the idea of decentralized authentication based on [JSON Web Tokens \(JWT\)](https://jwt.io/). Clients interact with this new scheme using a [user JWT](../../nats-server/configuration/securing_nats/jwt/) and corresponding [NKey](../../nats-server/configuration/securing_nats/auth_intro/nkey_auth.md) private key. To help make connecting with a JWT easier, the client libraries support the concept of a credentials file. This file contains both the private key and the JWT and can be generated with the `nsc` [tool](../../nats-tools/nsc/). The contents will look like the following and should be protected because it contains a private key. This credentials file is unused and only for example purposes.
|
||||
|
||||
```text
|
||||
-----BEGIN NATS USER JWT-----
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
# Authenticating with an NKey
|
||||
|
||||
The 2.0 version of NATS server introduces a new challenge response authentication option. This challenge response is based on a wrapper we call [NKeys](../../nats-server/configuration/securing_nats/auth_intro/nkey_auth.md). The server can use these keys in several ways for authentication. The simplest is for the server to be configured with a list of known public keys and for the clients to respond to the challenge by signing it with its private key. (A printable private NKey is referred to as seed). This challenge-response ensures security by ensuring that the client has the private key, but also protects the private key from the server, which never has access to it!
|
||||
The 2.0 version of NATS server introduces a new challenge response authentication option. This challenge response is based on a wrapper we call [NKeys](../../nats-server/configuration/securing_nats/auth_intro/nkey_auth.md). The server can use these keys in several ways for authentication. The simplest is for the server to be configured with a list of known public keys and for the clients to respond to the challenge by signing it with its private key. \(A printable private NKey is referred to as seed\). This challenge-response ensures security by ensuring that the client has the private key, but also protects the private key from the server, which never has access to it!
|
||||
|
||||
Handling challenge response may require more than just a setting in the connection options, depending on the client library.
|
||||
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
# Encrypting and Authenticating Connections with TLS
|
||||
# Encrypting Connections with TLS
|
||||
|
||||
While authentication limits which clients can connect, TLS can be used to encrypt traffic between client/server and check the server’s identity. Additionally - in the most secure version of TLS with NATS - the server can be configured to verify the client's identity, thus authenticating it. When started in [TLS mode](../../nats-server/configuration/securing_nats/tls.md), a `nats-server` will require all clients to connect with TLS. Moreover, if configured to connect with TLS, client libraries will fail to connect to a server without TLS.
|
||||
|
||||
@ -207,4 +207,5 @@ let nc = await connect({
|
||||
|
||||
## Connecting with the TLS Protocol
|
||||
|
||||
Clients (such as Go, Java, Javascript, Ruby and Type Script) support providing a URL containing the `tls` protocol to the NATS connect call. This will turn on TLS without the need for further code changes. However, in that case there is likely some form of default or environmental settings to allow the TLS libraries of your programming language to find certificate and trusted CAs. Unless these settings are taken into accounts or otherwise modified, this way of connecting is very likely to fail.
|
||||
Clients \(such as Go, Java, Javascript, Ruby and Type Script\) support providing a URL containing the `tls` protocol to the NATS connect call. This will turn on TLS without the need for further code changes. However, in that case there is likely some form of default or environmental settings to allow the TLS libraries of your programming language to find certificate and trusted CAs. Unless these settings are taken into accounts or otherwise modified, this way of connecting is very likely to fail.
|
||||
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
# Buffers and Flush
|
||||
# Caches, Flush and Ping
|
||||
|
||||
For performance reasons, most if not all, of the client libraries will buffer outgoing data so that bigger chunks can be written to the network at one time. This may be as simple as a byte buffer that stores a few messages before being pushed to the network.
|
||||
|
||||
@ -116,3 +116,4 @@ nc.close();
|
||||
Many of the client libraries use the [PING/PONG interaction](../connecting/pingpong.md) built into the NATS protocol to ensure that flush pushed all of the buffered messages to the server. When an application calls flush, most libraries will put a PING on the outgoing queue of messages, and wait for the server to respond with a PONG before saying that the flush was successful.
|
||||
|
||||
Even though the client may use PING/PONG for flush, pings sent this way do not count towards [max outgoing pings](../connecting/pingpong.md).
|
||||
|
||||
|
||||
@ -41,3 +41,4 @@ This means that the NATS receiver client is listening for requests messages on t
|
||||
The NATS requestor client makes a request by sending the message "I need help!" on the “help.please” subject.
|
||||
|
||||
The NATS receiver client receives the message, formulates the reply \("OK, I CAN HELP!!!"\), and sends it to the inbox of the requester.
|
||||
|
||||
|
||||
@ -7,3 +7,4 @@ NATS makes it easy for programs to communicate across different environments, la
|
||||
|
||||
|
||||
NATS core offers an **at most once** quality of service. If a subscriber is not listening on the subject \(no subject match\), or is not active when the message is sent, the message is not received. This is the same level of guarantee that TCP/IP provides. By default, NATS is a fire-and-forget messaging system. If you need higher levels of service, you can use [NATS Streaming](../nats-streaming-concepts/intro.md) or build additional reliability into your client applications with proven and scalable reference designs such as [acks](acks.md) and [sequence numbers](seq_num.md).
|
||||
|
||||
|
||||
@ -41,3 +41,4 @@ Subject to your security configuration, wildcards can be used for monitoring by
|
||||
### Mix Wildcards
|
||||
|
||||
The wildcard `*` can appear multiple times in the same subject. Both types be used as well. For example, `*.*.east.>` will receive `time.us.east.atlanta`.
|
||||
|
||||
|
||||
@ -1,13 +1,12 @@
|
||||
# Creating a Kubernetes Cluster
|
||||
|
||||
Below you will find examples of creating a small 3 node Kubernetes
|
||||
cluster to try NATS on multiple clouds.
|
||||
Below you will find examples of creating a small 3 node Kubernetes cluster to try NATS on multiple clouds.
|
||||
|
||||
## Google Kubernetes Engine
|
||||
|
||||
Use [gcloud](https://cloud.google.com/sdk/gcloud/) to create a 3 node [regional](https://cloud.google.com/kubernetes-engine/docs/how-to/creating-a-regional-cluster) Kubernetes cluster on `us-west2`.
|
||||
|
||||
```sh
|
||||
```bash
|
||||
# Create a 3 node Kubernetes cluster. One node in each of the region's three zones.
|
||||
gcloud container clusters create nats-k8s-cluster \
|
||||
--project $YOUR_GOOGLE_CLOUD_PROJECT \
|
||||
@ -18,14 +17,11 @@ gcloud container clusters create nats-k8s-cluster \
|
||||
|
||||
Note that since this is a regional cluster we are specifying `--num-nodes 1` which will create a kubelet on 3 different zones. If you are creating a [single-zone cluster](https://cloud.google.com/kubernetes-engine/docs/how-to/creating-a-cluster) but want 3 nodes then you have to specify `--num-nodes 3`.
|
||||
|
||||
|
||||
## Amazon Kubernetes Service
|
||||
|
||||
The [eksctl](https://github.com/weaveworks/eksctl) is a very helpful
|
||||
tool to manage EKS clusters, you can find more docs on how to set it
|
||||
up [here](https://docs.aws.amazon.com/eks/latest/userguide/getting-started-eksctl.html).
|
||||
The [eksctl](https://github.com/weaveworks/eksctl) is a very helpful tool to manage EKS clusters, you can find more docs on how to set it up [here](https://docs.aws.amazon.com/eks/latest/userguide/getting-started-eksctl.html).
|
||||
|
||||
```sh
|
||||
```bash
|
||||
# Create 3 node Kubernetes cluster
|
||||
eksctl create cluster --name nats-k8s-cluster \
|
||||
--nodes 3 \
|
||||
@ -40,7 +36,7 @@ eksctl utils write-kubeconfig --name $YOUR_EKS_NAME --region eu-west-1
|
||||
|
||||
You can use [doctl](https://github.com/digitalocean/doctl) to create a cluster as follows:
|
||||
|
||||
```sh
|
||||
```bash
|
||||
doctl kubernetes cluster create nats-k8s-nyc2 --count 3 --region nyc1
|
||||
```
|
||||
|
||||
@ -48,7 +44,7 @@ doctl kubernetes cluster create nats-k8s-nyc2 --count 3 --region nyc1
|
||||
|
||||
Using [az](https://docs.microsoft.com/en-us/cli/azure/?view=azure-cli-latest) you can create a cluster like this:
|
||||
|
||||
```sh
|
||||
```bash
|
||||
# In case not done already, register to use some services:
|
||||
az login
|
||||
az provider register -n Microsoft.Network
|
||||
@ -62,21 +58,19 @@ az aks create --resource-group nats --name nats --node-count 3 --node-vm-size
|
||||
az aks get-credentials --resource-group nats --name nats
|
||||
```
|
||||
|
||||
*Note* In order to be able to access NATS externally you need to
|
||||
provision public IPs for your cluster installing the following component [dgkanatsios/AksNodePublicIPController](https://github.com/dgkanatsios/AksNodePublicIPController):
|
||||
_Note_ In order to be able to access NATS externally you need to provision public IPs for your cluster installing the following component [dgkanatsios/AksNodePublicIPController](https://github.com/dgkanatsios/AksNodePublicIPController):
|
||||
|
||||
```sh
|
||||
```bash
|
||||
kubectl create -n kube-system -f https://raw.githubusercontent.com/dgkanatsios/AksNodePublicIPController/7846c78f77dc5cd4b43629bb5cb7ff3818594aee/deploy.yaml
|
||||
```
|
||||
|
||||
After this component has been installed, eventually your cluster will
|
||||
be provided ExternalIPs that the NATS cluster can advertise to
|
||||
clients:
|
||||
After this component has been installed, eventually your cluster will be provided ExternalIPs that the NATS cluster can advertise to clients:
|
||||
|
||||
```
|
||||
```text
|
||||
kubectl get nodes -o wide
|
||||
NAME STATUS ROLES AGE VERSION INTERNAL-IP EXTERNAL-IP OS-IMAGE KERNEL-VERSION CONTAINER-RUNTIME
|
||||
aks-nodepool1-18657977-0 Ready agent 5d16h v1.13.12 10.240.0.6 52.191.186.114 Ubuntu 16.04.6 LTS 4.15.0-1060-azure docker://3.0.7
|
||||
aks-nodepool1-18657977-1 Ready agent 5d17h v1.13.12 10.240.0.4 52.229.11.82 Ubuntu 16.04.6 LTS 4.15.0-1060-azure docker://3.0.7
|
||||
aks-nodepool1-18657977-2 Ready agent 5d17h v1.13.12 10.240.0.5 13.77.149.235 Ubuntu 16.04.6 LTS 4.15.0-1060-azure docker://3.0.7
|
||||
```
|
||||
|
||||
|
||||
@ -37,7 +37,7 @@ curl -sSL https://nats-io.github.io/k8s/setup.sh | sh -s -- --without-tls
|
||||
curl -sSL https://nats-io.github.io/k8s/setup.sh | sh -s -- --without-tls --without-auth
|
||||
```
|
||||
|
||||
**Note**: Since [NATS Streaming](https://github.com/nats-io/nats-streaming-server) will be running as a [leafnode](../nats-server/configuration/leafnodes/README.md) to NATS \(under the STAN account\) and that [NATS Surveyor](https://github.com/nats-io/nats-surveyor) requires the [system account](../nats-server/configuration/sys_accounts/README.md) to monitor events, disabling auth also means that NATS Streaming and NATS Surveyor based monitoring will be disabled.
|
||||
**Note**: Since [NATS Streaming](https://github.com/nats-io/nats-streaming-server) will be running as a [leafnode](../nats-server/configuration/leafnodes/) to NATS \(under the STAN account\) and that [NATS Surveyor](https://github.com/nats-io/nats-surveyor) requires the [system account](../nats-server/configuration/sys_accounts/) to monitor events, disabling auth also means that NATS Streaming and NATS Surveyor based monitoring will be disabled.
|
||||
|
||||
The monitoring dashboard setup using NATS Surveyor can be accessed by using port-forward:
|
||||
|
||||
|
||||
@ -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:
|
||||
|
||||
|
||||
@ -106,6 +106,7 @@ authorization: {
|
||||
## Configuration Properties
|
||||
|
||||
### Connectivity
|
||||
|
||||
| Property | Description | Default |
|
||||
| :--- | :--- | :--- |
|
||||
| `host` | Host for client connections. | `0.0.0.0` |
|
||||
@ -113,11 +114,12 @@ authorization: {
|
||||
| `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). ||
|
||||
| [`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,39 +127,44 @@ 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_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.
|
||||
|
||||
The Configuration options here refer to [JWT](securing_nats/jwt/) 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`. |
|
||||
| [`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 |
|
||||
@ -174,7 +181,7 @@ The Configuration options here refer to [JWT](./securing_nats/jwt/README.md) bas
|
||||
| [`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. | |
|
||||
| `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 |
|
||||
@ -187,3 +194,4 @@ A server can reload most configuration changes without requiring a server restar
|
||||
```text
|
||||
> nats-server --signal reload
|
||||
```
|
||||
|
||||
|
||||
@ -4,8 +4,7 @@
|
||||
|
||||
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.
|
||||
|
||||
@ -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
|
||||
```
|
||||
|
||||
|
||||
@ -12,7 +12,7 @@ The `cluster` configuration map has the following configuration options:
|
||||
| `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,6 +3,7 @@
|
||||
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.
|
||||
|
||||
```text
|
||||
cluster {
|
||||
listen: 127.0.0.1:4244
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
# Gateways
|
||||
# Super-cluster with Gateways
|
||||
|
||||
## Gateways
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
# 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.
|
||||
|
||||
@ -9,7 +9,7 @@ Leaf nodes are useful in IoT and edge scenarios and when the local server traffi
|
||||
* 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.
|
||||
|
||||
|
||||
@ -13,7 +13,7 @@ The leaf node configuration block is used to configure incoming as well as outgo
|
||||
| `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. |
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
|
||||
@ -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,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
|
||||
|
||||
|
||||
@ -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`\) |
|
||||
| `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
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -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.
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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:
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -114,7 +113,7 @@ authorization: {
|
||||
}
|
||||
```
|
||||
|
||||
### allow_responses
|
||||
### allow\_responses
|
||||
|
||||
Here's an example with `allow_responses`:
|
||||
|
||||
@ -154,3 +153,4 @@ users = [
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
> 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.
|
||||
|
||||
|
||||
@ -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,10 +39,9 @@ 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 {
|
||||
@ -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 {
|
||||
@ -120,7 +114,7 @@ Even though they have different authorization mechanisms, these two servers are
|
||||
|
||||
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:
|
||||
|
||||
@ -200,3 +194,4 @@ func main() {
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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).
|
||||
|
||||
|
||||
@ -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,16 +61,11 @@ 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!!!**
|
||||
|
||||
@ -80,13 +75,10 @@ This is a **short** guide on how to do just that and what to watch out for.
|
||||
|
||||
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.
|
||||
@ -95,34 +87,27 @@ Please check your system's documentation on how to trust a particular self signe
|
||||
|
||||
#### 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
|
||||
```
|
||||
|
||||
|
||||
@ -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).
|
||||
|
||||
|
||||
@ -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:
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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:
|
||||
|
||||
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
|
||||
@ -145,9 +145,9 @@ require (
|
||||
)
|
||||
```
|
||||
|
||||
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`
|
||||
|
||||
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).
|
||||
|
||||
|
||||
@ -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)
|
||||
|
||||
|
||||
@ -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/).
|
||||
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
# Clustering
|
||||
|
||||
NATS Streaming Server supports clustering and data replication, implemented with the [Raft consensus algorithm](https://raft.github.io/), for the purposes of high availability. It provides protection for some of the nodes in the cluster failing, but since the leader is handling all incoming data from publishers and outgoing data to subscribers, it is not horizontally scalable. The cluster size should probably be limited to 3 to 5 nodes (RAFT recommends an odd number of nodes).
|
||||
NATS Streaming Server supports clustering and data replication, implemented with the [Raft consensus algorithm](https://raft.github.io/), for the purposes of high availability. It provides protection for some of the nodes in the cluster failing, but since the leader is handling all incoming data from publishers and outgoing data to subscribers, it is not horizontally scalable. The cluster size should probably be limited to 3 to 5 nodes \(RAFT recommends an odd number of nodes\).
|
||||
|
||||
There are two ways to bootstrap a cluster: with an explicit cluster configuration or with "auto" configuration using a seed node. With the first, we provide the IDs of the nodes participating in the cluster. In this case, the participating nodes will elect a leader. With the second, we start one server as a seed node, which will elect itself as leader, and subsequent servers will automatically join the seed \(note that this also works with the explicit cluster configuration once the leader has been established\). With the second method, we need to be careful to avoid starting multiple servers as seed as this will result in a split-brain. Both of these configuration methods are shown in the sections below.
|
||||
|
||||
|
||||
@ -71,29 +71,30 @@ Here you'll find examples demonstrating how to use Prometheus query expressions
|
||||
|
||||
### Pending Messages from Channel Foo
|
||||
|
||||
```
|
||||
```text
|
||||
sum(nss_chan_subs_pending_count{channel="foo"}) by (client_id)
|
||||
```
|
||||
|
||||
<img width="1580" alt="Pending" src="https://user-images.githubusercontent.com/26195/54960400-b0c52e80-4f19-11e9-9e92-88fba89fd55e.png">
|
||||
|
||||
|
||||
### Messages Per Sec Delivered on Channel Foo
|
||||
|
||||
In this case, `3` is the size of the quorum of NATS Streaming Server nodes. In case of a single instance backed by a relational database we would set it to `1`:
|
||||
|
||||
```
|
||||
```text
|
||||
sum(rate(nss_chan_msgs_total{channel="foo"}[5m])) by (channel) / 3
|
||||
```
|
||||
|
||||
<img width="1579" alt="msgs-per-sec" src="https://user-images.githubusercontent.com/26195/54960588-80ca5b00-4f1a-11e9-92d5-de59c81b6c63.png">
|
||||
|
||||
|
||||
### Msgs/Sec vs Pending on Channel
|
||||
|
||||
Example of combining the rate of messages with the pending count to detect whether processing is getting behind:
|
||||
|
||||
```
|
||||
```text
|
||||
sum(rate(nss_chan_msgs_total{channel="foo"}[5m])) by (channel) / 3
|
||||
sum(nss_chan_subs_pending_count{channel="foo"}) by (channel) / 3
|
||||
```
|
||||
|
||||
<img width="1468" alt="combination" src="https://user-images.githubusercontent.com/26195/54960992-4235a000-4f1c-11e9-8e55-47515a5d944d.png">
|
||||
|
||||
|
||||
|
||||
@ -85,7 +85,7 @@ Note that the Streaming Server uses a connection to a NATS Server, and so the NA
|
||||
| client\_key | Client certificate for the streaming server | File path | `client_key: "/path/to/client/key_file"` |
|
||||
| client\_ca | Client certificate CA for the streaming server | File path | `client_ca: "/path/to/client/ca_file"` |
|
||||
| server\_name | Expected hostname returned in the NATS Server certificate | String | `server_name: "theserverhostname"` |
|
||||
| insecure | Skips the NATS server's certificate chain and host name verification. Should not be used in production | `true` or `false` (default `false`) | `insecure: true` |
|
||||
| insecure | Skips the NATS server's certificate chain and host name verification. Should not be used in production | `true` or `false` \(default `false`\) | `insecure: true` |
|
||||
|
||||
## Store Limits Configuration
|
||||
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
# Persistence
|
||||
|
||||
By default, the NATS Streaming Server stores its state in memory, which means that if the streaming server is stopped, all state is lost. On server restart, since no connection information is recovered, running applications will stop receiving messages and new published messages will be rejected with an `invalid publish request` error. Client libraries that support and set the `Connection Lost` handler \(refer to [this](https://github.com/nats-io/stan.go#connection-status) for more information\) will be notified that the connection is lost with the error `client has been replaced or is no longer registered`.<br>
|
||||
By default, the NATS Streaming Server stores its state in memory, which means that if the streaming server is stopped, all state is lost. On server restart, since no connection information is recovered, running applications will stop receiving messages and new published messages will be rejected with an `invalid publish request` error. Client libraries that support and set the `Connection Lost` handler \(refer to [this](https://github.com/nats-io/stan.go#connection-status) for more information\) will be notified that the connection is lost with the error `client has been replaced or is no longer registered`.
|
||||
Still, this level of persistence allows applications to stop and later resume the stream of messages, and protect against applications disconnect \(network or applications crash\).
|
||||
|
||||
* [File Store](file_store.md)
|
||||
|
||||
@ -139,8 +139,8 @@ On startup, the server will apply the store limits, which means that this channe
|
||||
We strongly recommend not raising the limit back to the higher limit if messages have been removed in the previous step because those removed messages may or may not become available again depending on the store implementation or if running in clustering mode or not.
|
||||
|
||||
## Clustering
|
||||
When running `--clustered`, messages are kept in a RAFT consensus log file (under `--cluster_log_path`) in addition to the configured store.
|
||||
|
||||
This directory will grow as more messages keep coming within the 2-4 minute intervals of RAFT Snapshotting.
|
||||
After snapshotting the RAFT log will not shrink, but the space for more messages will be allocated internally.
|
||||
As a result - in addition to `max_bytes` multiplied by `max_channels` - disk space needs to be provisioned for RAFT Log, which can grow up to the size of payloads that channels could receive per minute * 4.
|
||||
When running `--clustered`, messages are kept in a RAFT consensus log file \(under `--cluster_log_path`\) in addition to the configured store.
|
||||
|
||||
This directory will grow as more messages keep coming within the 2-4 minute intervals of RAFT Snapshotting. After snapshotting the RAFT log will not shrink, but the space for more messages will be allocated internally. As a result - in addition to `max_bytes` multiplied by `max_channels` - disk space needs to be provisioned for RAFT Log, which can grow up to the size of payloads that channels could receive per minute \* 4.
|
||||
|
||||
|
||||
@ -1,7 +1,6 @@
|
||||
# nats-account-server
|
||||
|
||||
The [NATS Account Server](https://github.com/nats-io/nats-account-server) is an HTTP server that hosts and vends [JWTs](../../nats-server/configuration/securing_nats/jwt/README.md) for nats-server 2.0 account authentication.
|
||||
The server supports an number of stores which enable it to serve account [JWTs](../../nats-server/configuration/securing_nats/jwt/README.md) from:
|
||||
The [NATS Account Server](https://github.com/nats-io/nats-account-server) is an HTTP server that hosts and vends [JWTs](../../nats-server/configuration/securing_nats/jwt/) for nats-server 2.0 account authentication. The server supports an number of stores which enable it to serve account [JWTs](../../nats-server/configuration/securing_nats/jwt/) from:
|
||||
|
||||
* a [directory](nas_conf.md#directory-configuration)
|
||||
* an [NSC](../nsc/nsc.md) [directory](nas_conf.md#nsc-configuration)
|
||||
@ -14,5 +13,5 @@ The server supports replica mode, which allows load balancing, fault tolerance a
|
||||
|
||||
The account server can host activation tokens as well as account JWTs. These tokens are used when one account needs to give permission to another account to access a private export. Tokens can be configured as full tokens, or URLs. By hosting them in the account server you can avoid the copy/paste process of embedding tokens. They can also be updated more easily on expiration. The account serer furthermore allows for jwt inspection.
|
||||
|
||||
All account server configuration options can be found [here](nas_conf.md#Configuration-File).
|
||||
It futhermore allows [inspection](inspecting_jwts.md) of JWT.
|
||||
All account server configuration options can be found [here](nas_conf.md#Configuration-File). It futhermore allows [inspection](inspecting_jwts.md) of JWT.
|
||||
|
||||
|
||||
@ -101,3 +101,4 @@ Quick check on nsc to verify the ids of the accounts on nsc, match the files:
|
||||
Note that the `@` before the file name is required for `curl` to read the specified file, and use it as the payload. Otherwise, it will simply post the path specified, which will result in an update error.
|
||||
|
||||
Curl can also be used to [inspect](inspecting_jwts.md) JWTs.
|
||||
|
||||
|
||||
@ -168,7 +168,7 @@ Provided a setup with 4 accounts, one of them a system account, this example sho
|
||||
* configure a `nats-server` to make use of the account server
|
||||
* test the setup
|
||||
|
||||
```sh
|
||||
```bash
|
||||
$ export NKEYS_PATH=$(pwd)/nsc/nkeys
|
||||
$ export NSC_HOME=$(pwd)/nsc/accounts
|
||||
|
||||
@ -230,3 +230,4 @@ Listening on [test]
|
||||
# Subscribe using the system account user credentials can receive all system events
|
||||
$ nats-sub -creds nsc/nkeys/creds/KO/SYS/sys.creds '>'
|
||||
```
|
||||
|
||||
|
||||
@ -1,8 +1,8 @@
|
||||
# Update Notifications
|
||||
|
||||
The `nats-account-server` can notify a nats-server about [JWT](../../nats-server/configuration/securing_nats/jwt/README.md) updates, enabling the NATS server to update itself to the newly updated JWT.
|
||||
The `nats-account-server` can notify a nats-server about [JWT](../../nats-server/configuration/securing_nats/jwt/) updates, enabling the NATS server to update itself to the newly updated JWT.
|
||||
|
||||
To push notifications, the nats-account-server makes use of [system accounts](../../nats-server/configuration/sys_accounts/sys_accounts.md).
|
||||
To push notifications, the nats-account-server makes use of [system accounts](https://github.com/nats-io/nats.docs/tree/aecb86faf9be946a413d1c6200fc0ff5d1b0baef/nats-server/configuration/sys_accounts/sys_accounts.md).
|
||||
|
||||
Here's a nats-account-server configuration with updates enabled:
|
||||
|
||||
|
||||
@ -23,7 +23,7 @@ The script will download the latest version of `nsc` and install it into your sy
|
||||
|
||||
Alternatively, you can use `nsc` with the [nats-box](https://hub.docker.com/r/synadia/nats-box) Docker image:
|
||||
|
||||
```sh
|
||||
```bash
|
||||
$ docker run --rm -it -v $(pwd)/nsc:/nsc synadia/nats-box:latest
|
||||
|
||||
# In case NSC not initialized already:
|
||||
|
||||
20
whats_new.md
20
whats_new.md
@ -1,30 +1,34 @@
|
||||
# What's New in NATS
|
||||
# What's New!
|
||||
|
||||
The NATS.io team is always working to bring you features to improve your NATS experience. Below you will find feature summaries for new implementations to NATS. Check back often for release highlights and updates.
|
||||
|
||||
## Server release v2.1.6
|
||||
|
||||
### TLS Configuration for Account Resolver
|
||||
|
||||
This release adds the ability to specify TLS configuration for the account resolver.
|
||||
```code
|
||||
|
||||
```text
|
||||
resolver_tls {
|
||||
cert_file: ...
|
||||
key_file: ...
|
||||
ca_file: ...
|
||||
}
|
||||
```
|
||||
|
||||
### Additional Trace & Debug Verbosity Options
|
||||
|
||||
`trace_verbose` and command line parameters `-VV` and `-DVV` added. See [NATS Logging Configuration](nats-server/configuration/logging.md)
|
||||
|
||||
### Subscription Details in Monitoring Endpoints
|
||||
|
||||
We've added the option to include subscription details in monitoring endpoints `/routez` and `/connz`. For instance `/connz?subs=detail` will now return not only the subjects of the subscription, but the queue name (if applicable) and some other details.
|
||||
We've added the option to include subscription details in monitoring endpoints `/routez` and `/connz`. For instance `/connz?subs=detail` will now return not only the subjects of the subscription, but the queue name \(if applicable\) and some other details.
|
||||
|
||||
* Release notes [2.1.6](https://github.com/nats-io/nats-server/releases/tag/v2.1.6)
|
||||
* Full list of Changes [2.1.4...2.1.6](https://github.com/nats-io/nats-server/compare/v2.1.4...v2.1.6)
|
||||
|
||||
## Server release v2.1.4
|
||||
|
||||
### Log Rotation
|
||||
|
||||
NATS introduces `logfile_size_limit` allowing auto-rotation of log files when the size is greater than the configured limit set in `logfile_size_limit` as a number of bytes. You can provide the size with units, such as MB, GB, etc. The backup files will have the same name as the original log file with the suffix .yyyy.mm.dd.hh.mm.ss.micros. For more information see Configuring Logging in the [NATS Server Configuration section](nats-server/configuration/logging.md#using-the-configuration-file).
|
||||
@ -33,16 +37,19 @@ NATS introduces `logfile_size_limit` allowing auto-rotation of log files when th
|
||||
* Full list of Changes [2.1.2...2.1.4](https://github.com/nats-io/nats-server/compare/v2.1.2...v2.1.4)
|
||||
|
||||
## Server release v2.1.2
|
||||
|
||||
### Queue Permissions
|
||||
|
||||
Queue Permissions allow you to express authorization for queue groups. As queue groups are integral to implementing horizontally scalable microservices, control of who is allowed to join a specific queue group is important to the overall security model. Original PR - <https://github.com/nats-io/nats-server/pull/1143>
|
||||
Queue Permissions allow you to express authorization for queue groups. As queue groups are integral to implementing horizontally scalable microservices, control of who is allowed to join a specific queue group is important to the overall security model. Original PR - [https://github.com/nats-io/nats-server/pull/1143](https://github.com/nats-io/nats-server/pull/1143)
|
||||
|
||||
More information on Queue Permissions can be found in the [Developing with NATS](developing-with-nats/receiving/queues.md#queue-permissions) section.
|
||||
|
||||
## Server release v2.1.0
|
||||
|
||||
### Service Latency Tracking
|
||||
|
||||
As services and service mesh functionality has become prominent, we have been looking at ways to make running scalable services on NATS.io a great experience. One area we have been looking at is observability. With publish/subscribe systems, everything is inherently observable, however we realized it was not as simple as it could be. We wanted the ability to transparently add service latency tracking to any given service with no changes to the application. We also realized that global systems, such as those NATS.io can support, needed something more than a single metric. The solution was to allow any sampling rate to be attached to an exported service, with a delivery subject for all collected metrics. We collect metrics that show the requestor’s view of latency, the responder’s view of latency and the NATS subsystem itself, even when requestor and responder are in different parts of the world and connected to different servers in a NATS supercluster.
|
||||
|
||||
* Release notes [2.1.0](https://github.com/nats-io/nats-server/releases/tag/v2.1.0)
|
||||
* Full list of Changes [2.0.4...2.1.0](https://github.com/nats-io/nats-server/compare/v2.0.4...v2.1.0)
|
||||
|
||||
@ -50,11 +57,12 @@ As services and service mesh functionality has become prominent, we have been lo
|
||||
|
||||
### Response Only Permissions
|
||||
|
||||
For services, the authorization for responding to requests usually included wildcards for _INBOX.> and possibly $GR.> with a supercluster for sending responses. What we really wanted was the ability to allow a service responder to only respond to the reply subject it was sent.
|
||||
For services, the authorization for responding to requests usually included wildcards for \_INBOX.> and possibly $GR.> with a supercluster for sending responses. What we really wanted was the ability to allow a service responder to only respond to the reply subject it was sent.
|
||||
|
||||
### Response Types
|
||||
|
||||
Exported Services were originally tied to a single response. We added the type for the service response and now support singletons (default), streams and chunked. Stream responses represent multiple response messages, chunked represents a single response that may have to be broken up into multiple messages.
|
||||
Exported Services were originally tied to a single response. We added the type for the service response and now support singletons \(default\), streams and chunked. Stream responses represent multiple response messages, chunked represents a single response that may have to be broken up into multiple messages.
|
||||
|
||||
* Release notes [2.0.4](https://github.com/nats-io/nats-server/releases/tag/v2.0.4)
|
||||
* Full list of Changes [2.0.2...2.0.4](https://github.com/nats-io/nats-server/compare/v2.0.2...v2.0.4)
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user