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

Merge branch 'master' into accountz

Browse Source
This commit is contained in:
Colin Sullivan
2021-03-15 10:59:32 -06:00
committed by GitHub
parent 9c95e9012c bd4a6dc5e1
commit 2010bbd6b6
62 changed files with 3722 additions and 264 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -117,6 +117,8 @@ authorization: {
| [`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/). | |
| [`mqtt`](https://github.com/nats-io/nats.docs/tree/53202d44215a11c4c4ad7caea03a703d302bc954/nats-server/configuration/mqtt/mqtt_conf.md) | Configuration map for a [mqtt](mqtt.md). | |
| [`websocket`](https://github.com/nats-io/nats.docs/tree/53202d44215a11c4c4ad7caea03a703d302bc954/nats-server/configuration/websocket/websocket_conf.md) | Configuration map for [websocket](websocket.md). | |
### Connection Timeouts

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

@@ -27,7 +27,7 @@ If gateways are to be used in a cluster, **all** servers of this cluster need to
A nats-server in a gateway role will specify a port where it will accept gateway connections. If the configuration specifies other _external_ `gateways`, the gateway will create one outbound gateway connection for each gateway in its configuration. It will also gossip other gateways it knows or discovers. Fewer _external_ `gateways` mean less configuration. Yet, the ability to discover more gateways and gateway nodes depends on these servers running. This is similar to _seed server_ in cluster. It is recommended to have all _seed server_ of a cluster listed in the `gateways` section.
If the local cluster has three gateway nodes, this means there will be three outbound connections to each external gateway.
If the local cluster has three gateway nodes, this means there will be three outbound connections from the local cluster to each external gateway cluster.
![Gateway Connections](../../../.gitbook/assets/simple.svg)

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

@@ -93,6 +93,33 @@ If other form of credentials are used \(jwt, nkey or other\), then the server wi
| `account` | [Account](../securing_nats/accounts.md) name or jwt public key identifying the local account to bind to this remote server. Any traffic locally on this account will be forwarded to the remote server. |
| `credentials` | Credential file for connecting to the leafnode server. |
| `tls` | A [TLS configuration](leafnode_conf.md#tls-configuration-block) block. Leafnode client will use specified TLS certificates when connecting/authenticating. |
| `ws_compression` | If connecting with [Websocket](https://github.com/nats-io/nats.docs/tree/0ab2bb72b305dcf4817b8f1fc4f37ab9b0c8a2db/nats-server/configuration/leafnodes/leafnode_conf/README.md#connecting-using-websocket-protocol) protocol, this boolean \(`true` or `false`\) indicates to the remote server that it wishes to use compression. The default is `false`. |
| `ws_no_masking` | If connecting with [Websocket](https://github.com/nats-io/nats.docs/tree/0ab2bb72b305dcf4817b8f1fc4f37ab9b0c8a2db/nats-server/configuration/leafnodes/leafnode_conf/README.md#connecting-using-websocket-protocol) protocol, this boolean indicates to the remote server that it wishes not to mask outbound websocket frames. The default is `false`, which means that outbound frames will be masked. |
### Connecting using Websocket protocol
Since NATS 2.2.0, Leaf nodes support outbound websocket connections by specifying `ws` as the scheme component of the remote server URLs:
```text
leafnodes {
remotes [
{urls: ["ws://hostname1:443", "ws://hostname2:443"]}
]
}
```
Note that if a URL has the `ws` scheme, all URLs the list must be `ws`. You cannot mix and match. Therefore this would be considered an invalid configuration:
```text
remotes [
# Invalid configuration that will prevent the server from starting
{urls: ["ws://hostname1:443", "nats-leaf://hostname2:7422"]}
]
```
Note that the decision to make a TLS connection is not based on `wss://` \(as opposed to `ws://`\) but instead in the presence of a TLS configuration in the `leafnodes{}` or the specific remote configuration block.
To configure Websocket in the remote server, check the [Websocket](https://github.com/nats-io/nats.docs/tree/0ab2bb72b305dcf4817b8f1fc4f37ab9b0c8a2db/nats-server/configuration/websocket/websocket_conf.md) secion.
### `tls` Configuration Block

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

@@ -11,6 +11,7 @@ To monitor the NATS messaging system, `nats-server` provides a lightweight HTTP
* [Leaf Nodes](monitoring.md#leaf-nodes-information)
* [Subscription Routing](monitoring.md#subscription-routing-information)
* [Account Information](monitoring.md#account-information)
* [JetStream Information](monitoring.md#jetstream-information)
All endpoints return a JSON object.
@@ -57,7 +58,7 @@ http: localhost:8222
For example, to monitor this server locally, the endpoint would be [http://localhost:8222/varz](http://localhost:8222/varz). It reports various general statistics.
## Monitoring endpoints
## 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.
@@ -247,6 +248,61 @@ You can also report detailed subscription information on a per connection basis
}
```
### JetStream Information
The `/jsz` endpoint reports information about the JetStream subsystem.
**Endpoint:** `http://server:port/jsm`
| Result | Return Code |
| :--- | :--- |
| Success | 200 \(OK\) |
| Error | 400 \(Bad Request\) |
#### Arguments
| Argument | Values | Description |
| :--- | :--- | :--- |
| acc | account name | Provide information for a specfic account |
| accounts | true, 1, false, 0 | Provide information for all accounts. The default is false. |
| streams | true, 1, false, 0 | Include stream information. The default is false. |
| consumers | true, 1, false, 0 | Include consumer information. The default is false. |
| config | true, false | Include configuration with streams and consumers. The default is false. |
| offset | integer > 0 | Pagination offset. Default is 0. |
| limit | integer > 0 | Number of results to return. Default is 1024. |
| leader-only | true, false | TODO |
As noted above, the `routez` endpoint does support the `subs` argument from the `/connz` endpoint. For example: [http://demo.nats.io:8222/routez?subs=1](http://demo.nats.io:8222/jsz?accounts=1&streams=1&consumers=1&config=1)
#### Example
* Get JetStream information: [http://host:port/jsz?accounts=1&streams=1&consumers=1&config=1](http://host:port/jsz?accounts=1&streams=1&consumers=1&config=1)
#### Response
```javascript
{
"server_id": "NACDVKFBUW4C4XA24OOT6L4MDP56MW76J5RJDFXG7HLABSB46DCMWCOW",
"now": "2019-06-24T14:29:16.046656-07:00",
"num_routes": 1,
"routes": [
{
"rid": 1,
"remote_id": "de475c0041418afc799bccf0fdd61b47",
"did_solicit": true,
"ip": "127.0.0.1",
"port": 61791,
"pending_size": 0,
"in_msgs": 0,
"out_msgs": 0,
"in_bytes": 0,
"out_bytes": 0,
"subscriptions": 0
}
]
}
```
### Route Information
The `/routez` endpoint reports information on active routes for a cluster. Routes are expected to be low, so there is no paging mechanism with this endpoint.
@@ -433,7 +489,7 @@ The `/gatewayz` endpoint reports information about gateways used to create a NAT
}
```
### Leaf Nodes Information
### Leaf Node Information
The `/leafz` endpoint reports detailed information about the leaf node connections.
@@ -520,7 +576,6 @@ The `/subsz` endpoint reports detailed information about the current subscriptio
"avg_fanout": 0
}
```
### Account Information
The `/accountz` endpoint reports information on a servers active accounts.
@@ -528,15 +583,6 @@ The default behavior is to return a list of all accounts known to the server.
**Endpoint:** `http://server:port/accountz`
| Result | Return Code |
| :--- | :--- |
| Success | 200 \(OK\) |
| Error | 400 \(Bad Request\) |
#### Arguments
| Argument | Values | Description |
| :--- | :--- | :--- |
| acc | account name | Include metrics for the specified account. Default is empty. When not set, a list of all accounts is included. |
#### Example
@@ -626,6 +672,147 @@ Retrieve specific account:
}
```
### JetStream Information
The `/jsz` endpoint reports more detailed information on JetStream. For accounts it uses a paging mechanism which defaults to 1024 connections.
**Endpoint:** `http://server:port/jsz`
| Result | Return Code |
| :--- | :--- |
| Success | 200 \(OK\) |
| Error | 400 \(Bad Request\) |
#### Arguments
| Argument | Values | Description |
| :--- | :--- | :--- |
| acc | account name | Include metrics for the specified account. Default is unset. |
| accounts | true, 1, false, 0 | Include account specific JetStream information. Default is false. |
| streams | true, 1, false, 0 | Include streams. When set, implies `accounts=true`. Default is false. |
| consumers | true, 1, false, 0 | Include consumer. When set, implies `streams=true`. Default is false. |
| config | true, 1, false, 0 | When stream or consumer are requested, include their respective configuration. Default is false. |
| leader-only | true, 1, false, 0 | Only the leader responds. Default is false. |
| offset | number > 0 | Pagination offset. Default is 0. |
| limit | number > 0 | Number of results to return. Default is 1024. |
#### Examples
Get basic JetStream information: [http://demo.nats.io:8222/jsz](http://demo.nats.io:8222/jsz)
Request accounts and control limit and offset: [http://demo.nats.io:8222/jsz?accounts=true&limit=16&offset=128](http://demo.nats.io:8222/jsz?accounts=true&limit=16&offset=128).
You can also report detailed consumer information on a per connection basis using consumer=true. For example: [http://demo.nats.io:8222/jsz?consumers=true](http://demo.nats.io:8222/jsz/consumer=true).
#### Response
```javascript
{
"server_id": "NCVIDODSZ45C5OD67ZD7EJUIJPQDP6CM74SJX6TJIF2G7NLYS5LCVYHS",
"now": "2021-02-08T19:08:30.555533-05:00",
"config": {
"max_memory": 10485760,
"max_storage": 10485760,
"store_dir": "/var/folders/9h/6g_c9l6n6bb8gp331d_9y0_w0000gn/T/srv_7500251552558"
},
"memory": 0,
"storage": 66,
"api": {
"total": 5,
"errors": 0
},
"total_streams": 1,
"total_consumers": 1,
"total_messages": 1,
"total_message_bytes": 33,
"meta_cluster": {
"name": "cluster_name",
"replicas": [
{
"name": "server_5500",
"current": false,
"active": 2932926000
}
]
},
"account_details": [
{
"name": "BCC_TO_HAVE_ONE_EXTRA",
"id": "BCC_TO_HAVE_ONE_EXTRA",
"memory": 0,
"storage": 0,
"api": {
"total": 0,
"errors": 0
}
},
{
"name": "ACC",
"id": "ACC",
"memory": 0,
"storage": 66,
"api": {
"total": 5,
"errors": 0
},
"stream_detail": [
{
"name": "my-stream-replicated",
"cluster": {
"name": "cluster_name",
"replicas": [
{
"name": "server_5500",
"current": false,
"active": 2931517000
}
]
},
"state": {
"messages": 1,
"bytes": 33,
"first_seq": 1,
"first_ts": "2021-02-09T00:08:27.623735Z",
"last_seq": 1,
"last_ts": "2021-02-09T00:08:27.623735Z",
"consumer_count": 1
},
"consumer_detail": [
{
"stream_name": "my-stream-replicated",
"name": "my-consumer-replicated",
"created": "2021-02-09T00:08:27.427631Z",
"delivered": {
"consumer_seq": 0,
"stream_seq": 0
},
"ack_floor": {
"consumer_seq": 0,
"stream_seq": 0
},
"num_ack_pending": 0,
"num_redelivered": 0,
"num_waiting": 0,
"num_pending": 1,
"cluster": {
"name": "cluster_name",
"replicas": [
{
"name": "server_5500",
"current": false,
"active": 2933232000
}
]
}
}
]
}
]
}
]
}
```
## Creating Monitoring Applications
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). You can easily create single page web applications for monitoring. To do this you simply pass the `callback` query parameter to any endpoint.

128
nats-server/configuration/mqtt.md Normal file
View File

@@ -0,0 +1,128 @@
# MQTT
_Supported since NATS Server version 2.2_
NATS follows as closely as possible to the MQTT v3.1.1 [specification](https://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html).
## When to Use MQTT
MQTT support in NATS is intended to be an enabling technology allowing users to leverage existing investments in their IoT deployments. Updating software on the edge or endpoints can be onerous and risky, especially when embedded applications are involved.
In greenfield IoT deployments, when possible, we prefer NATS extended out to endpoints and devices for a few reasons. There are significant advantages with security and observability when using a single technology end to end. Compared to MQTT, NATS is nearly as lightweight in terms of protocol bandwidth and maintainer supported clients efficiently utilize resources so we consider NATS to be a good choice to use end to end, including use on resource constrained devices.
In existing MQTT deployments or in situations when endpoints can only support MQTT, using a NATS server as a drop-in MQTT server replacement to securely connect to a remote NATS cluster or supercluster is compelling. You can keep your existing IoT investment and use NATS for secure, resilient, and scalable access to your streams and services.
## JetStream Requirements
For an MQTT client to connect to the NATS server, the user's account must be JetStream enabled. This is because persistence is needed for the sessions and retained messages since even retained messages of QoS 0 are persisted.
## MQTT Topics and NATS Subjects
MQTT Topics are similar to NATS Subjects, but have distinctive differences.
MQTT topic uses "`/`" as a level separator. For instance `foo/bar` would translate to NATS subject `foo.bar`. But in MQTT, `/foo/bar/` is a valid subject, which, if simply translated, would become `.foo.bar.`, which is NOT a valid NATS Subject.
NATS Server will convert an MQTT topic following those rules:
| MQTT character | NATS character\(s\) | Topic \(MQTT\) | Subject \(NATS\) |
| :---: | :---: | :---: | :---: |
| `/` between two levels | `.` | `foo/bar` | `foo.bar` |
| `/` as first level | `/.` | `/foo/bar` | `/.foo.bar` |
| `/` as last level | `./` | `foo/bar/` | `foo.bar./` |
| `/` next to another | `./` | `foo//bar` | `foo./.bar` |
| `/` next to another | `/.` | `//foo/bar` | `/./.foo.bar` |
| `.` | Not Support | `foo.bar` | Not Supported |
| | Not Support | `foo bar` | Not Supported |
As indicated above, if an MQTT topic contains the character ``` or``.\`, NATS will reject it, causing the connection to be closed for published messages, and returning a failure code in the SUBACK packet for a subscriptions.
### MQTT Wildcards
As in NATS, MQTT wildcards represent either multi or single levels. As in NATS, they are allowed only for subscriptions, not for published messages.
| MQTT Wildcard | NATS Wildcard |
| :---: | :---: |
| `#` | `>` |
| `+` | `*` |
The wildcard `#` matches any number of levels within a topic, which means that a subscription on `foo/#` would receive messages on `foo/bar`, or `foo/bar/baz`, but also on `foo`. This is not the case in NATS where a subscription on `foo.>` can receive messages on `foo/bar` or `foo/bar/baz`, but not on `foo`. To solve this, NATS Server will create two subscriptions, one on `foo.>` and one on `foo`. If the MQTT subscription is simply on `#`, then a single NATS subscription on `>` is enough.
The wildcard `+` matches a single level, which means `foo/+` can receive message on `foo/bar` or `foo/baz`, but not on `foo/bar/baz` nor `foo`. This is the same with NATS subscriptions using the wildcard `*`. Therefore `foo/+` would translate to `foo.*`.
## Communication Between MQTT and NATS
When an MQTT client creates a subscription on a topic, the NATS server creates the similar NATS subscription \(with conversion from MQTT topic to NATS subject\) so that the interest is registered in the cluster and known to any NATS publishers.
That is, say an MQTT client connects to server "A" and creates a subscription of `foo/bar`, server "A" creates a subscription on `foo.bar`, which interest is propagated as any other NATS subscription. A publisher connecting anywhere in the cluster and publishing on `foo.bar` would cause server "A" to deliver a QoS 0 message to the MQTT subscription.
This works the same way for MQTT publishers. When the server receives an MQTT publish message, it is converted to the NATS subject and published, which means that any matching NATS subscription will receive the MQTT message.
If the MQTT subscription is QoS1 and an MQTT publisher publishes an MQTT QoS1 message on the same or any other server in the cluster, the message will be persisted in the cluster and routed and delivered as QoS 1 to the MQTT subscription.
## QoS 1 Redeliveries
When the server delivers a QoS 1 message to a QoS 1 subscription, it will keep the message until it receives the PUBACK for the corresponding packet identifier. If it does not receive it within the "ack\_wait" interval, that message will be resent.
## Max Ack Pending
This is the amount of QoS 1 messages the server can send to a subscription without receiving any PUBACK for those messages. The maximum value is 65535.
The total of subscriptions' `max_ack_pending` on a given session cannot exceed 65535. Attempting to create a subscription that would bring the total above the limit would result in the server returning a failure code in the SUBACK for this subscription.
Due to how the NATS server handles the MQTT "`#`" wildcard, each subscription ending with "`#`" will use 2 times the `max_ack_pending` value.
## Sessions
NATS Server will persist all sessions, even if they are created with the "clean session" flag, meaning that sessions only last for the duration of the network connection between the client and the server.
A session is identified by a client identifier. If two connections try to use the same client identifier, the server, per specification, will close the existing connection and accept the new one.
If the user incorrectly starts two applications that use the same client identifier, this would result in a very quick flapping if the MQTT client has a reconnect feature and quickly reconnects.
To prevent this, the NATS server will accept the new session and will delay the closing of the old connection to reduce the flapping rate.
Detection of the concurrent use of sessions also works in cluster mode.
## Retained Messages
When a server receives an MQTT publish packet with the RETAIN flag set \(regardless of its QoS\), it stores the application message and its QoS, so that it can be delivered to future subscribers whose subscriptions match its topic name.
When a new subscription is established, the last retained message, if any, on each matching topic name will be sent to the subscriber.
A PUBLISH Packet with a RETAIN flag set to 1 and a payload containing zero bytes will be processed as normal and sent to clients with a subscription matching the topic name. Additionally any existing retained message with the same topic name will be removed and any future subscribers for the topic will not receive a retained message.
## Clustering
NATS supports MQTT in a NATS cluster. The replication factor is automatically set based on the size of the cluster.
### Connections with Same Client ID
If a client is connected to a server "A" in the cluster and another client connects to a server "B" and uses the same client identifier, server "A" will close its client connection upon discovering the use of an active client identifier.
Users should avoid this situation as this is not as easy and immediate as if the two applications are connected to the same server.
There may be cases where the server will reject the new connection if there is no safe way to close the existing connection, such as when it is in the middle of processing some MQTT packets.
### Retained Messages
Retained messages are stored in the cluster and available to any server in the cluster. However, this is not immediate and if a producer connects to a server and produces a retained message and another connection connects to another server and starts a matching subscription, it may not receive the retained message if the server it connects to has not yet been made aware of this retained message.
In other words, retained messages in clustering mode is best-effort, and applications that rely on the presence of a retained message should connect on the server that produced them.
## Limitations
* NATS does not support QoS 2 messages. If it receives a published message with QoS greater than 1,
it will close the connection.
* NATS messages published to MQTT subscriptions are always delivered as QoS 0 messages.
* MQTT published messages on topic names containing "```" or "``.\`" characters will cause the
connection to be closed. Presence of those characters in MQTT subscriptions will result in error
code in the SUBACK packet.
* MQTT wildcard `#` may cause the NATS server to create two subscriptions.
* MQTT concurrent sessions may result in the new connection to be evicted instead of the existing one.
* MQTT retained messages in clustering mode is best effort.

179
nats-server/configuration/mqtt/mqtt_conf.md Normal file
View File

@@ -0,0 +1,179 @@
# Configuration
To enable MQTT support in the server, add a `mqtt` configuration
block in the server's configuration file like the following:
```
mqtt {
# Specify a host and port to listen for websocket connections
#
# listen: "host:port"
# It can also be configured with individual parameters,
# namely host and port.
#
# host: "hostname"
port: 1883
# TLS configuration.
#
tls {
cert_file: "/path/to/cert.pem"
key_file: "/path/to/key.pem"
# Root CA file
#
# ca_file: "/path/to/ca.pem"
# If true, require and verify client certificates.
#
# verify: true
# TLS handshake timeout in fractional seconds.
#
# timeout: 2.0
# If true, require and verify client certificates and map certificate
# values for authentication purposes.
#
# verify_and_map: true
}
# If no user name is provided when an MQTT client connects, will default
# this user name in the authentication phase. If specified, this will
# override, for MQTT clients, any `no_auth_user` value defined in the
# main configuration file.
# Note that this is not compatible with running the server in operator mode.
#
# no_auth_user: "my_username_for_apps_not_providing_credentials"
# See below to know what is the normal way of limiting MQTT clients
# to specific users.
# If there are no users specified in the configuration, this simple authorization
# block allows you to override the values that would be configured in the
# equivalent block in the main section.
#
# authorization {
# # If this is specified, the client has to provide the same username
# # and password to be able to connect.
# # username: "my_user_name"
# # password: "my_password"
#
# # If this is specified, the password field in the CONNECT packet has to
# # match this token.
# # token: "my_token"
#
# # This overrides the main's authorization timeout. For consistency
# # with the main's authorization configuration block, this is expressed
# # as a number of seconds.
# # timeout: 2.0
#}
# This is the amount of time after which a QoS 1 message sent to
# a client is redelivered as a DUPLICATE if the server has not
# received the PUBACK packet on the original Packet Identifier.
# The value has to be positive.
# Zero will cause the server to use the default value (30 seconds).
# Note that changes to this option is applied only to new MQTT subscriptions.
#
# Expressed as a time duration, with "s", "m", "h" indicating seconds,
# minutes and hours respectively. For instance "10s" for 10 seconds,
# "1m" for 1 minute, etc...
#
# ack_wait: "1m"
# This is the amount of QoS 1 messages the server can send to
# a subscription without receiving any PUBACK for those messages.
# The valid range is [0..65535].
#
# The total of subscriptions' max_ack_pending on a given session cannot
# exceed 65535. Attempting to create a subscription that would bring
# the total above the limit would result in the server returning 0x80
# in the SUBACK for this subscription.
# Due to how the NATS Server handles the MQTT "#" wildcard, each
# subscription ending with "#" will use 2 times the max_ack_pending value.
# Note that changes to this option is applied only to new subscriptions.
#
# max_ack_pending: 100
}
```
## Authorization of MQTT Users
A new field when configuring users allows you to restrict which type of connections are allowed for a specific user.
Consider this configuration:
```
authorization {
users [
{user: foo password: foopwd, permission: {...}}
{user: bar password: barpwd, permission: {...}}
]
}
```
If an MQTT client were to connect and use the username `foo` and password `foopwd`, it would be accepted.
Now suppose that you would want an MQTT client to only be accepted if it connected using the username `bar`
and password `barpwd`, then you would use the option `allowed_connection_types` to restrict which type
of connections can bind to this user.
```
authorization {
users [
{user: foo password: foopwd, permission: {...}}
{user: bar password: barpwd, permission: {...}, allowed_connection_types: ["MQTT"]}
]
}
```
The option `allowed_connection_types` (also can be named `connection_types` or `clients`) as you can see
is a list, and you can allow several type of clients. Suppose you want the user `bar` to accept both
standard NATS clients and MQTT clients, you would configure the user like this:
```
authorization {
users [
{user: foo password: foopwd, permission: {...}}
{user: bar password: barpwd, permission: {...}, allowed_connection_types: ["STANDARD", "MQTT"]}
]
}
```
The absence of `allowed_connection_types` means that all type of connections are allowed (the default behavior).
The possible values are currently:
* `STANDARD`
* `WEBSOCKET`
* `LEAFNODE`
* `MQTT`
### Special permissions
When an MQTT client creates a QoS 1 subscription, this translates to the creation
of a JetStream durable subscription. To receive messages for this durable, the NATS Server
creates a subscription with a subject such as `$MQTT.sub.<nuid>` and sets it as the
JetStream durable's delivery subject.
Therefore, if you have set some permissions for the MQTT user, you need to allow
subscribe permissions on `$MQTT.sub.>`.
Here is an example of a basic configuration that sets some permissions to a user named "mqtt".
As you can see, the subscribe permission `$MQTT.sub.>` is added to allow this client to
create QoS 1 subscriptions.
```
listen: 127.0.0.1:4222
jetstream: enabled
authorization {
mqtt_perms = {
publish = ["baz"]
subscribe = ["foo", "bar", "$MQTT.sub.>"]
}
users = [
{user: mqtt, password: pass, permissions: $mqtt_perms, allowed_connection_types: ["MQTT"]}
]
}
mqtt {
listen: 127.0.0.1:1883
}
```

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

@@ -189,4 +189,6 @@ no_auth_user: a
The above example shows how clients without authentication can be associated with the user `a` within account `A`.
> Please note that the `no_auth_user` will not work with nkeys. The user referenced can also be part of the [authorization](authorization.md) block.
>
> Despite `no_auth_user` being set, clients still need to communicate that they will not be using credentials. The [authentication timeout](auth_intro/auth_timeout.md) applies to this process as well. When your connection is slow, you may run into this timeout and the resulting `Authentication Timeout` error, despite not providing credentials.

10
nats-server/configuration/securing_nats/auth_intro/tokens.md
View File

@@ -29,12 +29,14 @@ Listening on [>]
Tokens can be bcrypted enabling an additional layer of security, as the clear-text version of the token would not be persisted on the server configuration file.
You can generate bcrypted tokens and passwords using the [`mkpasswd`](../../../../nats-tools/mkpasswd.md) tool:
You can generate bcrypted tokens and passwords using the [`nats`](../../../../nats-tools/natscli.md) tool:
```text
> mkpasswd
pass: dag0HTXl4RGg7dXdaJwbC8
bcrypt hash: $2a$11$PWIFAL8RsWyGI3jVZtO9Nu8.6jOxzxfZo7c/W0eLk017hjgUKWrhy
> nats server passwd
? Enter password [? for help] **********************
? Reenter password [? for help] **********************
$2a$11$PWIFAL8RsWyGI3jVZtO9Nu8.6jOxzxfZo7c/W0eLk017hjgUKWrhy
```
Here's a simple configuration file:

12
nats-server/configuration/securing_nats/auth_intro/username_password.md
View File

@@ -30,12 +30,14 @@ authorization: {
## Bcrypted Passwords
Username/password also supports bcrypted passwords using the [`mkpasswd`](../../../../nats-tools/mkpasswd.md) tool. Simply replace the clear text password with the bcrypted entries:
Username/password also supports bcrypted passwords using the [`nats`](../../../../nats-tools/natscli.md) tool. Simply replace the clear text password with the bcrypted entries:
```text
> mkpasswd
pass: (Uffs#rG42PAu#Oxi^BNng
bcrypt hash: $2a$11$V1qrpBt8/SLfEBr4NJq4T.2mg8chx8.MTblUiTBOLV3MKDeAy.f7u
> nats server passwd
? Enter password [? for help] **********************
? Reenter password [? for help] **********************
$2a$11$V1qrpBt8/SLfEBr4NJq4T.2mg8chx8.MTblUiTBOLV3MKDeAy.f7u
```
And on the configuration file:
@@ -44,7 +46,7 @@ And on the configuration file:
authorization: {
users: [
{user: a, password: "$2a$11$V1qrpBt8/SLfEBr4NJq4T.2mg8chx8.MTblUiTBOLV3MKDeAy.f7u"},
...
...
]
}
```

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

@@ -1,9 +1,10 @@
# Account lookup using Resolver
The `resolver` configuration option is used in conjunction with [NATS JWT Authentication](./) and [nsc](../../../../nats-tools/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](../../../../nats-tools/nsc/). The `resolver` option specifies a URL where the nats-server can retrieve an account JWT. There are three built-in resolver implementations:
* `URL`
* `MEMORY`
* [`URL`](resolver.md#URL-Resolver)
* [`MEMORY`](resolver.md#Memory)
* [NATS Based Resolver](resolver.md#nats-based-resolver)
> If the operator JWT specified in `operator` contains an account resolver URL, `resolver` only needs to be specified in order to overwrite that default.
@@ -34,3 +35,59 @@ The `MEMORY` resolver is recommended when the server has a small number of accou
For more information on how to configure a memory resolver, see [this tutorial](mem_resolver.md).
## NATS Based Resolver
The NATS based resolver embeds the functionality of the [account server](https://github.com/nats-io/nats-account-server) inside the nats-server. In order to avoid having to store all account JWT on every server, this resolver has two sub types `full` and `cache`. Their commonalities are that they exchange/lookup account JWT via NATS and the system account, and store them in a local \(not shared\) directory.
### Full
The Full resolver stores all JWTs and exchanges them in an eventually consistent way with other resolvers of the same type. [`nsc`](../../../../nats-tools/nsc/) supports push/pull/purge with this resolver type. [JWTs](https://github.com/nats-io/nats.docs/tree/8c85d9c047d2203c7867b62a8415cdfa4d117f04/nats-server/configuration/nats-server/configuration/securing_nats/jwt/README.md), uploaded this way, are stored in a directory the server has exclusive access to.
```yaml
resolver: {
type: full
# Directory in which account jwt will be stored
dir: './jwt'
# In order to support jwt deletion, set to true
# If the resolver type is full delete will rename the jwt.
# This is to allow manual restoration in case of inadvertent deletion.
# To restore a jwt, remove the added suffix .delete and restart or send a reload signal.
# To free up storage you must manually delete files with the suffix .delete.
allow_delete: false
# Interval at which a nats-server with a nats based account resolver will compare
# it's state with one random nats based account resolver in the cluster and if needed,
# exchange jwt and converge on the same set of jwt.
interval: "2m"
# limit on the number of jwt stored, will reject new jwt once limit is hit.
limit: 1000
}
```
This resolver type also supports `resolver_preload`. When present, JWTs are listed and stored in the resolver. There, they may be subject to updates. Restarts of the `nats-server` will hold on to these more recent versions.
Not every server in a cluster needs to be set to `full`. You need enough to still serve your workload adequately, while some servers are offline.
### Cache
The Cache resolver only stores a subset of [JWT](https://github.com/nats-io/nats.docs/tree/8c85d9c047d2203c7867b62a8415cdfa4d117f04/nats-server/configuration/nats-server/configuration/securing_nats/jwt/README.md) and evicts others based on an LRU scheme. Missing JWTs are downloaded from `full` nats based resolver. This resolver is essentially the URL Resolver in NATS.
```yaml
resolver: {
type: cache
# Directory in which account jwt will be store
dir: "./"
# limit on the number of jwt stored, will evict old jwt once limit is hit.
limit: 1000
# How long to hold on to a jwt before discarding it.
ttl: "2m"
}
```
### NATS Based Resolver - Integration
The NATS based resolver utilizes the system account for lookup and upload of account [JWTs](https://github.com/nats-io/nats.docs/tree/8c85d9c047d2203c7867b62a8415cdfa4d117f04/nats-server/configuration/nats-server/configuration/securing_nats/jwt/README.md) . If your application requires tighter integration you can make use of these subjects for tighter integration.
To upload or update any generated account JWT without [`nsc`](../../../../nats-tools/nsc/), send it as a request to `$SYS.REQ.CLAIMS.UPDATE`. Each participating `full` NATS based account resolver will respond with a message detailing success or failure.
To serve a requested account [JWT](https://github.com/nats-io/nats.docs/tree/8c85d9c047d2203c7867b62a8415cdfa4d117f04/nats-server/configuration/nats-server/configuration/securing_nats/jwt/README.md) yourself and essentially implement an account server, subscribe to `$SYS.REQ.ACCOUNT.*.CLAIMS.LOOKUP` and respond with the account JWT corresponding to the requested account id \(wildcard\).

11
nats-server/configuration/websocket.md Normal file
View File

@@ -0,0 +1,11 @@
# Websocket
_Supported since NATS Server version 2.2_
Websocket support can be enabled in the server and may be used alongside the traditional TCP socket connections. TLS, compression and Origin Header checking are supported.
**Important**
* NATS Supports only Websocket data frames in Binary, not Text format \([https://tools.ietf.org/html/rfc6455\#section-5.6](https://tools.ietf.org/html/rfc6455#section-5.6)\). The server will always send in Binary and your clients MUST send in Binary too.
* For writers of client libraries: a Websocket frame is not guaranteed to contain a full NATS protocol \(actually will generally not\). Any data from a frame must be going through a parser that can handle partial protocols. See the protocol description [here](../../nats-protocol/nats-protocol/).

158
nats-server/configuration/websocket/websocket_conf.md Normal file
View File

@@ -0,0 +1,158 @@
# Configuration
To enable websocket support in the server, add a `websocket` configuration
block in the server's configuration file like the following:
```
websocket {
# Specify a host and port to listen for websocket connections
#
# listen: "host:port"
# It can also be configured with individual parameters,
# namely host and port.
#
# host: "hostname"
port: 443
# This will optionally specify what host:port for websocket
# connections to be advertised in the cluster.
#
# advertise: "host:port"
# TLS configuration is required by default
#
tls {
cert_file: "/path/to/cert.pem"
key_file: "/path/to/key.pem"
}
# For test environments, you can disable the need for TLS
# by explicitly setting this option to `true`
#
# no_tls: true
# [Cross-origin resource sharing option](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS). When set to `true`, the HTTP origin header must match the request’s hostname.
# The default is `false`.
#
# same_origin: true
# [Cross-origin resource sharing option](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS). List of accepted origins. When empty, and `same_origin` is `false`, clients from any origin are allowed to connect.
# This list specifies the only accepted values for the client's request Origin header. The scheme,
# host and port must match. By convention, the absence of TCP port in the URL will be port 80
# for an "http://" scheme, and 443 for "https://".
#
# allowed_origins [
# "http://www.example.com"
# "https://www.other-example.com"
# ]
# This enables support for compressed websocket frames
# in the server. For compression to be used, both server
# and client have to support it.
#
# compression: true
# This is the total time allowed for the server to
# read the client request and write the response back
# to the client. This includes the time needed for the
# TLS handshake.
#
# handshake_timeout: "2s"
# Name for an HTTP cookie, that if present will be used as a client JWT.
# If the client specifies a JWT in the CONNECT protocol, this option is ignored.
# The cookie should be set by the HTTP server as described [here](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#restrict_access_to_cookies).
# This setting is useful when generating NATS `Bearer` client JWTs as the
# result of some authentication mechanism. The HTTP server after correct
# authentication can issue a JWT for the user, that is set securely preventing
# access by unintended scripts. Note these JWTs must be [NATS JWTs](https://docs.nats.io/nats-server/configuration/securing_nats/jwt).
#
# jwt_cookie: "my_jwt_cookie_name"
# If no user name is provided when a websocket client connects, will default
# this user name in the authentication phase. If specified, this will
# override, for websocket clients, any `no_auth_user` value defined in the
# main configuration file.
# Note that this is not compatible with running the server in operator mode.
#
# no_auth_user: "my_username_for_apps_not_providing_credentials"
# See below to know what is the normal way of limiting websocket clients
# to specific users.
# If there are no users specified in the configuration, this simple authorization
# block allows you to override the values that would be configured in the
# equivalent block in the main section.
#
# authorization {
# # If this is specified, the client has to provide the same username
# # and password to be able to connect.
# # username: "my_user_name"
# # password: "my_password"
#
# # If this is specified, the password field in the CONNECT has to
# # match this token.
# # token: "my_token"
#
# # This overrides the main's authorization timeout. For consistency
# # with the main's authorization configuration block, this is expressed
# # as a number of seconds.
# # timeout: 2.0
#}
}
```
## Authorization of Websocket Users
A new field when configuring users allows you to restrict which type of connections are allowed for a specific user.
Consider this configuration:
```
authorization {
users [
{user: foo password: foopwd, permission: {...}}
{user: bar password: barpwd, permission: {...}}
]
}
```
If a websocket client were to connect and use the username `foo` and password `foopwd`, it would be accepted.
Now suppose that you would want websocket client to only be accepted if it connected using the username `bar`
and password `barpwd`, then you would use the option `allowed_connection_types` to restrict which type
of connections can bind to this user.
```
authorization {
users [
{user: foo password: foopwd, permission: {...}}
{user: bar password: barpwd, permission: {...}, allowed_connection_types: ["WEBSOCKET"]}
]
}
```
The option `allowed_connection_types` (also can be named `connection_types` or `clients`) as you can see
is a list, and you can allow several type of clients. Suppose you want the user `bar` to accept both
standard NATS clients and websocket clients, you would configure the user like this:
```
authorization {
users [
{user: foo password: foopwd, permission: {...}}
{user: bar password: barpwd, permission: {...}, allowed_connection_types: ["STANDARD", "WEBSOCKET"]}
]
}
```
The absence of `allowed_connection_types` means that all type of connections are allowed (the default behavior).
The possible values are currently:
* `STANDARD`
* `WEBSOCKET`
* `LEAFNODE`
* `MQTT`
## Leaf nodes connections
You can configure remote Leaf node connections so that they connect to the Websocket port instead of the Leaf node port.
See [Leafnode](../leafnodes/leafnode_conf.md#connecting-using-websocket-protocol) section.

16
nats-server/nats_admin/lame_duck_mode.md
View File

@@ -1,9 +1,6 @@
# Lame Duck Mode
In production we recommend that a server is shut down with ​lame duck mode​
as a graceful way to slowly evict clients. With large deployments this
mitigates the "thundering herd" situation that will place CPU pressure on
servers as TLS enabled clients reconnect.
In production we recommend that a server is shut down with ​lame duck mode​ as a graceful way to slowly evict clients. With large deployments this mitigates the "thundering herd" situation that will place CPU pressure on servers as TLS enabled clients reconnect.
## Server
@@ -13,16 +10,9 @@ Lame duck mode is initiated by signaling the server:
nats-server --signal ldm
```
After entering lame duck mode, the server will stop accepting new connections,
wait for a 10 second grace period, then begin to evict clients over a period of time
configurable by the [lame_duck_duration](https://docs.nats.io/nats-server/configuration#runtime-configuration)
configuration option. This period defaults to 2 minutes.
After entering lame duck mode, the server will stop accepting new connections, wait for a 10 second grace period, then begin to evict clients over a period of time configurable by the [lame\_duck\_duration](https://docs.nats.io/nats-server/configuration#runtime-configuration) configuration option. This period defaults to 2 minutes.
## Clients
When entering lame duck mode, the server will send a message to clients. Some
maintainer supported clients will invoke an optional callback indicating that
a server is entering lame duck mode. This is used for cases where an application
can benefit from preparing for the short outage between the time it is evicted and
automatically reconnected to another server.
When entering lame duck mode, the server will send a message to clients. Some maintainer supported clients will invoke an optional callback indicating that a server is entering lame duck mode. This is used for cases where an application can benefit from preparing for the short outage between the time it is evicted and automatically reconnected to another server.

2
nats-server/nats_admin/upgrading_cluster.md
View File

@@ -38,7 +38,7 @@ nats-sub -s nats://localhost:4222 ">"
`nats-sub` is a subscriber sample included with all NATS clients. `nats-sub` subscribes to a subject and prints out any messages received. You can find the source code to the go version of `nats-sub` in [GitHub](https://github.com/nats-io/nats.go/tree/master/examples). After starting the subscriber you should see a message on 'A' that a new client connected.
We have two servers and a client. Time to simulate our rolling upgrade. But wait, before we upgrade 'A', let's introduce a new server 'C'. Server 'C' will join the existing cluster while we perform the upgrade. Its sole purpose is to provide an additional place where clients can go other than 'A' and ensure we don't end up with a single server serving all the clients after the upgrade procedure. Clients will randomly select a server when connecting unless a special option is provided that disables that functionality \(usually called 'DontRandomize' or 'noRandomize'\). You can read more about ["Avoiding the Thundering Herd"](). Suffice it to say that clients redistribute themselves about evenly between all servers in the cluster. In our case 1/2 of the clients on 'A' will jump over to 'B' and the remaining half to 'C'.
We have two servers and a client. Time to simulate our rolling upgrade. But wait, before we upgrade 'A', let's introduce a new server 'C'. Server 'C' will join the existing cluster while we perform the upgrade. Its sole purpose is to provide an additional place where clients can go other than 'A' and ensure we don't end up with a single server serving all the clients after the upgrade procedure. Clients will randomly select a server when connecting unless a special option is provided that disables that functionality \(usually called 'DontRandomize' or 'noRandomize'\). You can read more about ["Avoiding the Thundering Herd"](upgrading_cluster.md). Suffice it to say that clients redistribute themselves about evenly between all servers in the cluster. In our case 1/2 of the clients on 'A' will jump over to 'B' and the remaining half to 'C'.
Let's start our temporary server: