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

GitBook: [master] 21 pages modified

Browse Source
This commit is contained in:
Ginger Collison 2020-06-09 14:20:36 +00:00 committed by gitbook-bot
parent 87c12ebd3f
commit dde41d778b
No known key found for this signature in database
GPG Key ID: 07D2180C7B12D0FF
21 changed files with 80 additions and 84 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
SUMMARY.md
View File

@ -203,3 +203,4 @@
* [Using a Load Balancer for External Access to NATS](nats-on-kubernetes/nats-external-nlb.md)
* [Creating a NATS Super Cluster in Digital Ocean with Helm](nats-on-kubernetes/super-cluster-on-digital-ocean.md)
* [From Zero to K8S to Leafnodes using Helm](nats-on-kubernetes/from-zero-to-leafnodes.md)

24
nats-on-kubernetes/from-zero-to-leafnodes.md
View File

@ -1,19 +1,16 @@
# From Zero to Communicating Across K8S Regions using NATS Leafnodes
# From Zero to K8S to Leafnodes using Helm
First, we need a number of Kubernetes clusters to be setup already. In
this case we'll create a few in Digital Ocean using the `doctl` tool but
you could use any K8S solution available:
First, we need a number of Kubernetes clusters to be setup already. In this case we'll create a few in Digital Ocean using the `doctl` tool but you could use any K8S solution available:
```
```text
brew install doctl
doctl kubernetes cluster create nats-k8s-sfo2 --count 3 --region sfo2
doctl kubernetes cluster create nats-k8s-ams3 --count 3 --region ams3
```
Next, get your NGS credentials with leafnodes enabled. For this follow [these instructions](https://synadia.com/ngs/signup) and choose the `Developer` plan which is free and will allow you to create leafnode connections for a couple of clusters.
Once you got the credentials, upload them as a secret to your K8S clusters:
Next, get your NGS credentials with leafnodes enabled. For this follow [these instructions](https://synadia.com/ngs/signup) and choose the `Developer` plan which is free and will allow you to create leafnode connections for a couple of clusters. Once you got the credentials, upload them as a secret to your K8S clusters:
```sh
```bash
for ctx in do-ams3-nats-k8s-ams3 do-sfo2-nats-k8s-sfo2; do
kubectl --context $ctx create secret generic ngs-creds --from-file $HOME/.nkeys/creds/synadia/NGS/NGS.creds
done
@ -21,7 +18,7 @@ done
Install Helm3 and add the NATS helm chart repo:
```
```text
brew install helm
helm repo add nats https://nats-io.github.io/k8s/helm/charts/
helm repo update
@ -29,7 +26,7 @@ helm repo update
Create the config that adds the leafnode connection to NGS:
```
```text
# nats.yaml
leafnodes:
enabled: true
@ -45,7 +42,7 @@ natsbox:
Deploy it to your K8S regions:
```sh
```bash
for ctx in do-ams3-nats-k8s-ams3 do-sfo2-nats-k8s-sfo2; do
helm --kube-context $ctx install nats nats/nats -f nats.yaml
done
@ -53,7 +50,7 @@ done
To test the multi-region connectivity by using the `nats-box` container that got deployed in each cluster:
```
```text
kubectl --context do-ams3-nats-k8s-ams3 exec -it nats-box -- nats-sub -s nats hello
Listening on [hello]
@ -64,7 +61,7 @@ done
Results from the subscribe session:
```
```text
[#1] Received on [hello]: 'Hello World!'
[#2] Received on [hello]: 'Hello World!'
[#3] Received on [hello]: 'Hello World!'
@ -75,3 +72,4 @@ Results from the subscribe session:
[#8] Received on [hello]: 'Hello World!'
[#9] Received on [hello]: 'Hello World!'
```

3
nats-on-kubernetes/nats-cluster-and-cert-manager.md
View File

@ -7,7 +7,8 @@ kubectl create namespace cert-manager
kubectl label namespace cert-manager certmanager.k8s.io/disable-validation=true
kubectl apply --validate=false -f https://github.com/jetstack/cert-manager/releases/download/v0.14.0/cert-manager.yaml
```
If you are running Kubernetes < 1.15, use `cert-manager-legacy.yaml` instead.
If you are running Kubernetes &lt; 1.15, use `cert-manager-legacy.yaml` instead.
```yaml
apiVersion: cert-manager.io/v1alpha2

16
nats-on-kubernetes/nats-external-nlb.md
View File

@ -1,14 +1,10 @@
# Using a load balancer for external access to NATS on K8S
# Using a Load Balancer for External Access to NATS
Although it is not recommended in general to use a load balancer
with NATS for external access, sometimes due to policy it might
help to use one. If that is the case, then one option would be
to use an L4 load balancer that has raw tcp support.
Although it is not recommended in general to use a load balancer with NATS for external access, sometimes due to policy it might help to use one. If that is the case, then one option would be to use an L4 load balancer that has raw tcp support.
In the example below, you can find how to use an [AWS Network Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/introduction.html)
to connect externally to a cluster that has TLS setup.
In the example below, you can find how to use an [AWS Network Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/introduction.html) to connect externally to a cluster that has TLS setup.
```sh
```bash
# One-line installer creates a secure cluster named 'nats'
$ curl -sSL https://nats-io.github.io/k8s/setup.sh | sh
@ -42,5 +38,5 @@ nats-nlb LoadBalancer 10.100.67.123 a18b60a948fc611eaa7840286c60df32-9e96a
$ nats-pub -s nats://a18b60a948fc611eaa7840286c60df32-9e96a2af4b5675ec.elb.us-east-2.amazonaws.com:4222 -creds nsc/nkeys/creds/KO/A/test.creds test.foo bar
```
Also, it would be recommended to disable [no_advertise](../nats-server/configuration/clustering/cluster_config.md)
to avoid gossiping internal addresses from pods in Kubernetes to NATS clients.
Also, it would be recommended to disable [no\_advertise](../nats-server/configuration/clustering/cluster_config.md) to avoid gossiping internal addresses from pods in Kubernetes to NATS clients.

18
nats-on-kubernetes/super-cluster-on-digital-ocean.md
View File

@ -1,9 +1,8 @@
# Creating a NATS Super Cluster in Digital Ocean with Helm
Let's create a super cluster using NATS Gateways. First let's create
3 different clusters in NYC, Amsterdam, and San Francisco:
Let's create a super cluster using NATS Gateways. First let's create 3 different clusters in NYC, Amsterdam, and San Francisco:
```sh
```bash
doctl kubernetes cluster create nats-k8s-nyc1 --count 3 --region nyc1
doctl kubernetes cluster create nats-k8s-sfo2 --count 3 --region sfo2
doctl kubernetes cluster create nats-k8s-ams3 --count 3 --region ams3
@ -11,7 +10,7 @@ doctl kubernetes cluster create nats-k8s-ams3 --count 3 --region ams3
Next, open up the firewall across the 3 regions to be able to access the client, leafnode and gateways ports:
```sh
```bash
for firewall in `doctl compute firewall list | tail -n 3 | awk '{print $1}'`; do
doctl compute firewall add-rules $firewall --inbound-rules protocol:tcp,ports:4222,address:0.0.0.0/0
doctl compute firewall add-rules $firewall --inbound-rules protocol:tcp,ports:7422,address:0.0.0.0/0
@ -19,12 +18,9 @@ for firewall in `doctl compute firewall list | tail -n 3 | awk '{print $1}'`; do
done
```
For this setup, we will create a super cluster using the external IPs
from the nodes of the 3 clusters. For a production type of setup, it
is recommended to use a DNS entry and an A record for each one of the
servers.
For this setup, we will create a super cluster using the external IPs from the nodes of the 3 clusters. For a production type of setup, it is recommended to use a DNS entry and an A record for each one of the servers.
```sh
```bash
for ctx in do-ams3-nats-k8s-ams3 do-nyc1-nats-k8s-nyc1 do-sfo2-nats-k8s-sfo2; do
echo "name: $ctx"
for externalIP in `kubectl get nodes -o jsonpath='{.items[*].status.addresses[?(@.type=="ExternalIP")].address}'`; do
@ -78,7 +74,7 @@ natsbox:
Let's deploy the super cluster with Helm using the name of cluster as the name of the gateway:
```sh
```bash
for ctx in do-ams3-nats-k8s-ams3 do-nyc1-nats-k8s-nyc1 do-sfo2-nats-k8s-sfo2; do
helm --kube-context $ctx install nats nats/nats -f super-cluster.yaml --set gateway.name=$ctx
done
@ -86,7 +82,7 @@ done
That's it! It should now be possible to send some messages across regions:
```sh
```bash
# Start subscription in Amsterdam
nats-box:~# kubectl --context do-ams3-nats-k8s-ams3 exec -it nats-box -- /bin/sh -l
nats-box:~# nats-sub -s nats hello

2
nats-protocol/nats-protocol/nats-client-dev.md
View File

@ -62,7 +62,7 @@ NATS implements auto-pruning. When a client connects to the server, the server e
## Parsing the protocol
NATS provides a text-based message format. The text-based [protocol](README.md) makes it easy to implement NATS clients. The key consideration is deciding on a parsing strategy.
NATS provides a text-based message format. The text-based [protocol](./) makes it easy to implement NATS clients. The key consideration is deciding on a parsing strategy.
The NATS server implements a [zero allocation byte parser](https://youtu.be/ylRKac5kSOk?t=10m46s) that is fast and efficient. Off the wire, a NATS message is simply a slice of bytes. Across the wire the message is transported as an immutable string over a TCP connection. It is up to the client to implement logic to parse the message.

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

@ -144,7 +144,7 @@ authorization: {
| :--- | :--- |
| [`authorization`](securing_nats/auth_intro/) | Configuration map for client authentication/authorization. |
| [`accounts`](securing_nats/accounts.md) | Configuration map for multi tenancy via accounts. |
| [`no_auth_user`](securing_nats/accounts.md#No-Auth-User) | [Username](securing_nats/auth_intro/username_password.md) present in the [authorization block](securing_nats/auth_intro/README.md) or an [`account`](securing_nats/accounts.md). A client connecting without any form of authentication will be associated with this user, its permissions and account. |
| [`no_auth_user`](securing_nats/accounts.md#No-Auth-User) | [Username](securing_nats/auth_intro/username_password.md) present in the [authorization block](securing_nats/auth_intro/) or an [`account`](securing_nats/accounts.md). A client connecting without any form of authentication will be associated with this user, its permissions and account. |
#### Decentralized Authentication and Authorization
@ -152,8 +152,8 @@ The Configuration options here refer to [JWT](securing_nats/jwt/) based authenti
| 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.\) |
| [`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`. |
@ -182,7 +182,7 @@ The Configuration options here refer to [JWT](securing_nats/jwt/) based authenti
| [`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](sys_accounts/README.md) for more details. | |
| `system_account` | Name of the system account. Users of this account can subscribe to system events. See [System Accounts](sys_accounts/) 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 |

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

@ -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 {

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

@ -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

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

@ -13,7 +13,7 @@ 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.
>
@ -21,7 +21,7 @@ The NATS monitoring endpoints support [JSONP](https://en.wikipedia.org/wiki/JSON
### 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

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

@ -170,7 +170,7 @@ It is important to reiterate that:
Clients connecting without authentication can be associated with a particular user within an account.
```
```text
accounts: {
A: {
users: [
@ -188,5 +188,5 @@ 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.
> 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.

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

@ -1,6 +1,6 @@
# Account lookup using Resolver
The `resolver` configuration option is used in conjunction with [NATS JWT Authentication](README.md) and [nsc](../../../../nats-tools/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:
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:
* `URL`
* `MEMORY`
@ -9,7 +9,7 @@ The `resolver` configuration option is used in conjunction with [NATS JWT Authen
## 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/README.md) 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](../../../../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:
```yaml
resolver: URL(http://localhost:9090/jwt/v1/accounts/)

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

@ -10,7 +10,7 @@ The NATS server uses modern TLS semantics to encrypt client, route, and monitori
| `cipher_suites` | When set, only the specified TLS cipher suites will be allowed. Values must match the golang version used to build the server. |
| `curve_preferences` | List of TLS cipher curves to use in order. |
| `insecure` | Skip certificate verification. **NOT Recommended** |
| `timeout` | TLS handshake [timeout](#tls-timeout) in fractional seconds. Default set to `0.5` seconds. |
| `timeout` | TLS handshake [timeout](tls.md#tls-timeout) in fractional seconds. Default set to `0.5` seconds. |
| `verify` | If `true`, require and [verify](auth_intro/tls_mutual_auth.md#validating-a-client-certificate) client certificates. To support use by Browser, this option does not apply to monitoring. |
| `verify_and_map` | If `true`, require and verify client certificates and [map](auth_intro/tls_mutual_auth.md#mapping-client-certificates-to-a-user) certificate values for authentication purposes. Does not apply to monitoring either. |
@ -97,9 +97,9 @@ 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 the 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 the 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.
@ -116,15 +116,16 @@ 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`/[`cluster`](../cluster/README.md)/[`gateway`](../gateway/README.md)/[`leaf_nodes`](../leafnodes/README.md) provide the `-client` option. It will cause the appropriate key usage for client authentication to be added. This example also adds a SAN email for usage as user name in `verify_and_map`.
To generate certificates that work with `verify`/[`cluster`](https://github.com/nats-io/nats.docs/tree/3a28d211cf69cf56df02d958abc40be790c367df/nats-server/configuration/cluster/README.md)/[`gateway`](https://github.com/nats-io/nats.docs/tree/3a28d211cf69cf56df02d958abc40be790c367df/nats-server/configuration/gateway/README.md)/[`leaf_nodes`](../leafnodes/) provide the `-client` option. It will cause the appropriate key usage for client authentication to be added. This example also adds 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
```
> Please note:
>
> * That client refers to connecting process, not necessarily a NATS client.
> * `mkcert -client` will generate a certificate with key usage suitable for client **and** server authentication.

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

@ -9,12 +9,12 @@ NATS servers leverage [Accounts](../securing_nats/accounts.md) support and gener
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](../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/README.md) as shown in this [Tutorial](sys_accounts.md). In this case `system_account` contains the account public key.
* [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](sys_accounts.md). In this case `system_account` contains the account public key.
## Available Events and Services
@ -42,12 +42,12 @@ In addition other tools with system account privileges, can initiate requests \(
| Endpoint | Endpoint Name |
| :--- | :--- |
| [General Server Information](../monitoring.md#general-information)| `VARZ` |
| [Connections](../monitoring.md#connection-information)| `CONNZ` |
| [Routing](../monitoring.md#route-information)| `ROUTEZ` |
| [Gateways](../monitoring.md#gateway-information)| `GATEWAYZ` |
| [Leaf Nodes](../monitoring.md#leaf-nodes-information)| `LEAFZ` |
| [Subscription Routing](../monitoring.md#subscription-routing-information)| `SUBSZ` |
| [General Server Information](../monitoring.md#general-information) | `VARZ` |
| [Connections](../monitoring.md#connection-information) | `CONNZ` |
| [Routing](../monitoring.md#route-information) | `ROUTEZ` |
| [Gateways](../monitoring.md#gateway-information) | `GATEWAYZ` |
| [Leaf Nodes](../monitoring.md#leaf-nodes-information) | `LEAFZ` |
| [Subscription Routing](../monitoring.md#subscription-routing-information) | `SUBSZ` |
Servers like `nats-account-server` publish system account messages when a claim is updated, the nats-server listens for them, and updates its account information accordingly:

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

@ -6,6 +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/README.md)
* The monitoring [endpoint](../configuration/monitoring.md) and tools like [nats-top](../../nats-tools/nats_top/)
* By subscribing to [system events](../configuration/sys_accounts/)

15
nats-server/nats_docker/ngs-docker-python.md
View File

@ -1,39 +1,40 @@
# Getting started with Python and NGS running in Docker
# Python and NGS Running in Docker
Start a lightweight Docker container:
```
```text
docker run --entrypoint /bin/bash -it python:3.8-slim-buster
```
Or you can also mount local creds via a volume:
```
```text
docker run --entrypoint /bin/bash -v $HOME/.nkeys/creds/synadia/NGS/:/creds -it python:3.8-slim-buster
```
Install nats.py and dependencies to install nkeys:
```
```text
apt-get update && apt-get install -y build-essential curl
pip install asyncio-nats-client[nkeys]
```
Get the Python examples using curl:
```
```text
curl -o nats-pub.py -O -L https://raw.githubusercontent.com/nats-io/nats.py/master/examples/nats-pub/__main__.py
curl -o nats-sub.py -O -L https://raw.githubusercontent.com/nats-io/nats.py/master/examples/nats-sub/__main__.py
```
Create a subscription that lingers:
```
```text
python nats-sub.py --creds /creds/NGS.creds -s tls://connect.ngs.global:4222 hello &
```
Publish a message:
```
```text
python nats-pub.py --creds /creds/NGS.creds -s tls://connect.ngs.global:4222 hello -d world
```

6
nats-streaming-concepts/clustering/supported-stores.md
View File

@ -7,5 +7,7 @@ The NATS Streaming Server stores server meta information and messages to the sto
However, in clustered mode, we use RAFT for leader election. The raft layer uses its own stores which are currently necessarily file based. The location of the RAFT stores defaults to the current directory under a sub-directory named after the cluster ID, or you can configure it using `--cluster_log_path`.
**Important if using a SQL Store:**
- There is still a need for storing RAFT data on the file system.
- Each node in the cluster needs to have its own "database", that is, no two nodes should share the same tables.
* There is still a need for storing RAFT data on the file system.
* Each node in the cluster needs to have its own "database", that is, no two nodes should share the same tables.

4
nats-streaming-server/configuring/persistence/file_store.md
View File

@ -33,7 +33,7 @@ Regardless of channel limits, you can configure message logs to be split in indi
When messages accumulate in a channel, and limits are reached, older messages are removed. When the first file slice becomes empty, the server removes this file slice \(and corresponding index file\).
However, if you specify a script \(`--file_slice_archive_script`\), then the server will rename the slice files \(data and index\) with a `.bak` extension and invoke the script with the channel name, data and index file names.
The files are left in the channel's directory and therefore it is the script responsibility to delete those files when done. At any rate, those files will not be recovered on a server restart, but having lots of unused files in the directory may slow down the server restart.
The files are left in the channel's directory and therefore it is the script responsibility to delete those files when done. At any rate, those files will not be recovered on a server restart, but having lots of unused files in the directory may slow down the server restart.
For instance, suppose the server is about to delete file slice `datastore/foo/msgs.1.dat` \(and `datastore/foo/msgs.1.idx`\), and you have configured the script `/home/nats-streaming/archive_script.sh`. The server will invoke:
@ -56,7 +56,7 @@ Since dataloss is likely to occur, the default behavior for the server on startu
With the `-file_truncate_bad_eof` parameter, the server will still print those bad records but truncate each file at the position of the first corrupted record in order to successfully start.
To prevent the use of this parameter as the default value, this option is not available in the configuration file. Moreover, the server will fail to start if started more than once with that parameter.
This flag may help recover from a store failure, but since data may be lost in that process, we think that the operator needs to be aware and make an informed decision.
This flag may help recover from a store failure, but since data may be lost in that process, we think that the operator needs to be aware and make an informed decision.
Note that this flag will not help with file corruption due to bad CRC for instance. You have the option to disable CRC on recovery with the `-file_crc=false` option.

2
nats-tools/nas/notifications.md
View File

@ -2,7 +2,7 @@
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/README.md).
To push notifications, the nats-account-server makes use of [system accounts](../../nats-server/configuration/sys_accounts/).
Here's a nats-account-server configuration with updates enabled:

2
nats-tools/nsc/services.md
View File

@ -172,7 +172,7 @@ If you want to create a service that is only accessible to accounts you designat
As before, we declared an export, but this time we added the `--private` flag. The other thing to note is that the subject for the request has a wildcard. This enables the account to map specific subjects to specifically authorized accounts.
```text
```bash
> nsc describe account A
╭──────────────────────────────────────────────────────────────────────────────────────╮
│ Account Details │

4
whats_new.md
View File

@ -11,7 +11,7 @@ Monitoring endpoints as listed in the table below are accessible as system servi
* `$SYS.REQ.SERVER.<id>.<endpoint-name>` \(request server monitoring endpoint corresponding to endpoint name.\)
* `$SYS.REQ.SERVER.PING.<endpoint-name>` \(from all server request server monitoring endpoint corresponding to endpoint name - will return multiple messages\)
For more information on monitoring endpoints see [NATS Server Configurations System Events](nats-server/configuration/sys_accounts#available-events-and-services).
For more information on monitoring endpoints see [NATS Server Configurations System Events](nats-server/configuration/sys_accounts/#available-events-and-services).
### Addition of `no_auth_user` Configuration
@ -20,10 +20,10 @@ Configuration of `no_auth_user` allows you to refer to a configured user/account
For more information and example, see [Securing NATS](nats-server/configuration/securing_nats/accounts.md#no-auth-user)
For full release information, see links below;
* Release notes [2.1.7](https://github.com/nats-io/nats-server/releases/tag/v2.1.7)
* Full list of Changes [2.1.6...2.1.7](https://github.com/nats-io/nats-server/compare/v2.1.6...v2.1.7)
## Server release v2.1.6
### TLS Configuration for Account Resolver