Merge https://github.com/nats-io/nats.docs

nats-concepts/core-nats/queue-groups/queue.md

@@ -1,20 +1,22 @@
-# Queue Groups
+# Queue Groups  
+When subscribers register themselves to receive messages from a publisher, the 1:N fan-out pattern of messaging ensures that any message sent by a publisher, reaches all subscribers that have registered. NATS provides an additional feature named "queue", which allows subscribers to register themselves as part of a queue. Subscribers that are part of a queue, form the "queue group".  
 
-## Queue Groups
+## How queue groups function  
+As an example, consider message delivery occurring in the 1:N pattern to all subscribers based on the subject name (delivery happens even to subscribers that are not part of a queue group). If a subscriber is registered based on a queue name, it will always receive messages it is subscribed to, based on the subject name. However, if more subscribers are added to the same queue name, they become a queue group, and only one randomly chosen subscriber of the queue group will consume a message each time a message is received by the queue group. Such distributed queues are a built-in load balancing feature that NATS provides.  
+
+**Advantages**  
+- Ensures application fault tolerance
+- Workload processing can be scaled up or down
+- No extra configuration required
+- Queue groups are defined by the application and their queue subscribers, rather than the server configuration
 
-NATS provides a built-in load balancing feature called distributed queues. Using queue subscribers will balance message delivery across a group of subscribers which can be used to provide application fault tolerance and scale workload processing.
-
-To create a queue subscription, subscribers register a queue name. All subscribers with the same queue name form the queue group. This requires no configuration. As messages on the registered subject are published, one member of the group is chosen randomly to receive the message. Although queue groups have multiple subscribers, each message is consumed by only one.
-
-Queue group names follow the same naming rules as [subjects](../../subjects.md). Foremost, they are case sensitive and cannot contain whitespace. Consider structuring queue groups hierarchically using `.`. Some server functionalities can use [wildcard matching](../../subjects.md#wildcards) on them.
-
-One of the great features of NATS is that queue groups are defined by the application and their queue subscribers, not on the server configuration.
+Queue group names follow the same naming rules as [subjects](../../subjects.md). Foremost, they are case sensitive and cannot contain whitespace. Consider structuring queue groups hierarchically using a period `.`. Some server functionalities can use [wildcard matching](../../subjects.md#wildcards) on them.
 
 Queue subscribers are ideal for scaling services. Scale up is as simple as running another application, scale down is terminating the application with a signal that drains the in flight requests. This flexibility and lack of any configuration changes makes NATS an excellent service communication technology that can work with all platform technologies.
 
 ### No responder
 
-When a request is made to a service (request-reply) and the NATS Server knows there are no services available (as there are no client applications currently subscribing to the subject in a queue-group) the server will short circuit the request. A “no-responders” protocol message will be sent back to the requesting client which will break from blocking API calls. This allows applications to immediately react which further enables building a highly responsive system at scale, even in the face of application failures and network partitions.
+When a request is made to a service (request/reply) and the NATS Server knows there are no services available (since there are no client applications currently subscribing to the subject in a queue-group) the server will send a “no-responders” protocol message back to the requesting client which will break from blocking API calls. This allows applications to react immediately. This further enables building a highly responsive system at scale, even in the face of application failures and network partitions.
 
 ## Stream as a queue
 

reference/faq.md

@@ -75,7 +75,7 @@ Yes. NATS is a publish and subscribe system that also has distributed queueing f
 
 ### How can I monitor my NATS cluster?
 
-NATS can be deployed to have an HTTP\(s\) monitoring port - see the demo server here: [http://demo.nats.io:8222/](http://demo.nats.io:8222/). Alternately, there are several options available, including some from the active NATS community:
+NATS can be deployed to have an HTTP\(s\) monitoring port - see the demo server here: [https://demo.nats.io:8222/](https://demo.nats.io:8222/). Alternately, there are several options available, including some from the active NATS community:
 
 * [Prometheus NATS Exporter](https://github.com/nats-io/prometheus-nats-exporter) Use Prometheus to configure metrics and Grafana to create a visual display.
 * [nats-top](https://github.com/nats-io/nats-top) A top-like monitoring tool developed by Wally Quevedo of Synadia.

running-a-nats-service/configuration/mqtt/mqtt_config.md

@@ -100,6 +100,17 @@ mqtt {
 }
 ```
 
+## Server name
+
+MQTT requires a server name to be set. Server names must be unique in a cluster or super-cluster topology. The server name is set in the top-level section of the server configuration. Here is an example:
+```
+server_name: "my_mqtt_server"
+mqtt {
+    port: 1883
+    ...
+}
+```
+
 ## Authentication/Authorization of MQTT Users
 
 ### Operator mode

running-a-nats-service/configuration/sys_accounts/README.md

@@ -26,7 +26,7 @@ Server initiated events:
 * `$SYS.ACCOUNT.<id>.DISCONNECT` \(client disconnects\)
 * `$SYS.ACCOUNT.<id>.SERVER.CONNS` \(connections for an account changed\)
 * `$SYS.SERVER.<id>.CLIENT.AUTH.ERR` \(authentication error\)
-* `$SYS.ACCOUNT.<id>.LEAFNODE.CONNECT` \(leaf node connnects\)
+* `$SYS.ACCOUNT.<id>.LEAFNODE.CONNECT` \(leaf node connects\)
 * `$SYS.ACCOUNT.<id>.LEAFNODE.DISCONNECT` \(leaf node disconnects\)
 * `$SYS.SERVER.<id>.STATSZ` \(stats summary\)
 

running-a-nats-service/nats_admin/jetstream_admin/disaster_recovery.md

@@ -1,25 +1,46 @@
 # Disaster Recovery
 
-Disaster Recovery of the JetStream system is a topic we are still exploring and fleshing out and that will be impacted by the clustering work. For example replication will extend the options available to you.
+In the event of unrecoverable JetStream message persistence on one (or more) server nodes, there are two recovery scenarios:
 
-Today we have a few approaches to consider:
+* Automatic recovery from intact quorum nodes
+* Manual recovery from existing stream snapshots (backups)
 
-* `nats` CLI + Configuration Backups + Data Snapshots
-* Configuration Management + Data Snapshots
+{% hint style="danger" %}
+For R1 streams, data is persisted on one server node only. If that server node is unrecoverable then recovery from
+backup is the sole option.
+{% endhint %}
 
-## Data Backup
+## Automatic Recovery
 
-In all scenarios you can perform data snapshots and restores over the NATS protocol. This is good if you do not manage the NATS servers hosting your data, and you wish to do a backup of your data.
+NATS will create replacement stream replicas automatically under the following conditions:
 
-The backup includes:
+* Impacted stream is of replica configuration R3 (or greater)
+* Remaining intact nodes (stream replicas) meet minimum RAFT quorum: floor(R/2) + 1
+* Available node(s) in the stream's cluster for new replica(s)
+* Impacted node(s) removed from the stream's domain RAFT Meta group (e.g. `nats server raft peer-remove`)
+
+## Manual Recovery
+
+Snapshots (also known as backups) can pro-actively be made of any stream regardless of replication configuration.
+
+The backup includes (by default):
 
 * Stream configuration and state
-* Stream Consumer configuration and state
-* All data including metadata like timestamps and headers
+* Stream durable consumer configuration and state
+* All message payload data including metadata like timestamps and headers
+
+### Backup
+
+The `nats stream backup` CLI command is used to create snapshots of a stream and its durable consumers.
+
+{% hint style="info" %}
+As an account owner, if you wish to make a backup of ALL streams in your account, you may use `nats account backup` instead.
+{% endhint %}
 
 ```shell
-nats stream backup ORDERS /data/js-backup/ORDERS.tgz
+nats stream backup ORDERS '/data/js-backup/backup1'
 ```
+Output
 ```text
 Starting backup of Stream "ORDERS" with 13 data blocks
 
@@ -28,19 +49,27 @@ Starting backup of Stream "ORDERS" with 13 data blocks
 Received 13 MiB bytes of compressed data in 3368 chunks for stream "ORDERS" in 1.223428188s, 813 MiB uncompressed
 ```
 
-During the backup the Stream is in a state where it's configuration cannot change and no data will be expired from it based on Limits or Retention Policies.
+During a backup operation, the stream is placed in a status where it's configuration cannot change and no data will be
+evicted based on stream retention policies.
 
+{% hint style="info" %}
 Progress using the terminal bar can be disabled using `--no-progress`, it will then issue log lines instead.
+{% endhint %}
 
-## Restoring Data
+### Restore
 
-The backup made above can be restored into another server - but into the same Stream name.
+An existing backup (as above) can be restored to the same or a new NATS server (or cluster) using the `nats stream restore` command.
+
+{% hint style="info" %}
+If there are multiple streams in the backup directory, they will all be restored.
+{% endhint %}
 
 ```shell
-nats str restore ORDERS /data/js-backup/ORDERS.tgz
+nats stream restore '/data/js-backup/backup1'
 ```
+Output
 ```text
-Starting restore of Stream "ORDERS" from file "/data/js-backup/ORDERS.tgz"
+Starting restore of Stream "ORDERS" from file "/data/js-backup/backup1"
 
 13 MiB/s [====================================================================] 100%
 
@@ -92,3 +121,7 @@ nats restore /tmp/backup --update-streams
 
 The `nats restore` tool does not support restoring data, the same process using `nats stream restore`, as outlined earlier, can be used which will also restore Stream and Consumer configurations and state.
 
+
+{% hint style="warning" %}
+On restore, if a stream already exists in the server of same name and account, you will receive a `Stream {name} already exist` error.
+{% endhint %}

running-a-nats-service/nats_admin/monitoring/readme.md

@@ -19,7 +19,7 @@ The NATS monitoring endpoints support [JSONP](https://en.wikipedia.org/wiki/JSON
 See 
 > 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.
+> In other words don't do what `https://demo.nats.io:8222/` does! It is done on purpose to simplify the examples below.
 
 ### Enabling monitoring from the command line
 
@@ -81,7 +81,7 @@ N/A
 
 #### Example
 
-[http://demo.nats.io:8222/varz](http://demo.nats.io:8222/varz)
+[https://demo.nats.io:8222/varz](https://demo.nats.io:8222/varz)
 
 #### Response
 
@@ -184,13 +184,13 @@ _The server will default to holding the last 10,000 closed connections._
 
 #### Examples
 
-Get up to 1024 connections: [http://demo.nats.io:8222/connz](http://demo.nats.io:8222/connz)
+Get up to 1024 connections: [https://demo.nats.io:8222/connz](https://demo.nats.io:8222/connz)
 
-Control limit and offset: [http://demo.nats.io:8222/connz?limit=16&offset=128](http://demo.nats.io:8222/connz?limit=16&offset=128).
+Control limit and offset: [https://demo.nats.io:8222/connz?limit=16&offset=128](https://demo.nats.io:8222/connz?limit=16&offset=128).
 
-Get closed connection information: [http://demo.nats.io:8222/connz?state=closed](http://demo.nats.io:8222/connz?state=closed).
+Get closed connection information: [https://demo.nats.io:8222/connz?state=closed](https://demo.nats.io:8222/connz?state=closed).
 
-You can also report detailed subscription information on a per connection basis using subs=1. For example: [http://demo.nats.io:8222/connz?limit=1&offset=1&subs=1](http://demo.nats.io:8222/connz?limit=1&offset=1&subs=1).
+You can also report detailed subscription information on a per connection basis using subs=1. For example: [https://demo.nats.io:8222/connz?limit=1&offset=1&subs=1](https://demo.nats.io:8222/connz?limit=1&offset=1&subs=1).
 
 #### Response
 
@@ -285,11 +285,11 @@ The `/routez` endpoint reports information on active routes for a cluster. Route
 | :--- | :--- | :--- |
 | subs | true, 1, false, 0 or `detail` | Include subscriptions. Default is false. When set to `detail` a list with more detailed subscription information will be returned. |
 
-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/routez?subs=1)
+As noted above, the `routez` endpoint does support the `subs` argument from the `/connz` endpoint. For example: [https://demo.nats.io:8222/routez?subs=1](https://demo.nats.io:8222/routez?subs=1)
 
 #### Example
 
-* Get route information:  [http://demo.nats.io:8222/routez?subs=1](http://demo.nats.io:8222/routez?subs=1)
+* Get route information:  [https://demo.nats.io:8222/routez?subs=1](https://demo.nats.io:8222/routez?subs=1)
 
 #### Response
 
@@ -337,7 +337,7 @@ The `/gatewayz` endpoint reports information about gateways used to create a NAT
 
 #### Examples
 
-* Retrieve Gateway Information: [http://demo.nats.io:8222/gatewayz](http://demo.nats.io:8222/gatewayz)
+* Retrieve Gateway Information: [https://demo.nats.io:8222/gatewayz](https://demo.nats.io:8222/gatewayz)
 
 #### Response
 
@@ -471,11 +471,11 @@ The `/leafz` endpoint reports detailed information about the leaf node connectio
 | :--- | :--- | :--- |
 | subs | true, 1, false, 0 | Include internal subscriptions.  Default is false. |
 
-As noted above, the `leafz` endpoint does support the `subs` argument from the `/connz` endpoint. For example: [http://demo.nats.io:8222/leafz?subs=1](http://demo.nats.io:8222/leafz?subs=1)
+As noted above, the `leafz` endpoint does support the `subs` argument from the `/connz` endpoint. For example: [https://demo.nats.io:8222/leafz?subs=1](https://demo.nats.io:8222/leafz?subs=1)
 
 #### Example
 
-* Get leaf nodes information:  [http://demo.nats.io:8222/leafz?subs=1](http://demo.nats.io:8222/leafz?subs=1)
+* Get leaf nodes information:  [https://demo.nats.io:8222/leafz?subs=1](https://demo.nats.io:8222/leafz?subs=1)
 
 #### Response
 
@@ -525,7 +525,7 @@ The `/subsz` endpoint reports detailed information about the current subscriptio
 
 #### Example
 
-* Get subscription routing information:  [http://demo.nats.io:8222/subsz](http://demo.nats.io:8222/subsz)
+* Get subscription routing information:  [https://demo.nats.io:8222/subsz](https://demo.nats.io:8222/subsz)
 
 #### Response
 
@@ -559,8 +559,8 @@ The `/accountz` endpoint reports information on a server's active accounts. The
 
 #### Example
 
-* Get list of all accounts:  [http://demo.nats.io:8222/accountz](http://demo.nats.io:8222/accountz)
-* Get details for specific account `$G`:  [http://demo.nats.io:8222/accountz?acc=$G](http://demo.nats.io:8222/accountz?acc=$G)
+* Get list of all accounts:  [https://demo.nats.io:8222/accountz](https://demo.nats.io:8222/accountz)
+* Get details for specific account `$G`:  [https://demo.nats.io:8222/accountz?acc=$G](https://demo.nats.io:8222/accountz?acc=$G)
 
 #### Response
 
@@ -670,11 +670,11 @@ The `/jsz` endpoint reports more detailed information on JetStream. For accounts
 
 #### Examples
 
-Get basic JetStream information: [http://demo.nats.io:8222/jsz](http://demo.nats.io:8222/jsz)
+Get basic JetStream information: [https://demo.nats.io:8222/jsz](https://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).
+Request accounts and control limit and offset: [https://demo.nats.io:8222/jsz?accounts=true&limit=16&offset=128](https://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).
+You can also report detailed consumer information on a per connection basis using consumer=true. For example: [https://demo.nats.io:8222/jsz?consumers=true](https://demo.nats.io:8222/jsz/consumer=true).
 
 #### Response
 
@@ -792,13 +792,13 @@ NATS monitoring endpoints support [JSONP](https://en.wikipedia.org/wiki/JSONP) a
 For example:
 
 ```text
-http://demo.nats.io:8222/connz?callback=cb
+https://demo.nats.io:8222/connz?callback=cb
 ```
 
 Here is a JQuery example implementation:
 
 ```javascript
-$.getJSON('http://demo.nats.io:8222/connz?callback=?', function(data) {
+$.getJSON('https://demo.nats.io:8222/connz?callback=?', function(data) {
   console.log(data);
 });
 ```

using-nats/developing-with-nats/connecting/security/creds.md

@@ -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/) and corresponding [NKey](../../../../running-a-nats-service/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.
+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](../../../../running-a-nats-service/configuration/securing_nats/auth_intro/jwt/) and corresponding [NKey](../../../../running-a-nats-service/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-----

zh-cn/README.md

@@ -0,0 +1 @@
+# NATS 简体中文文档