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
21 changed files with 80 additions and 84 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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.

20
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
@@ -41,13 +41,13 @@ In addition other tools with system account privileges, can initiate requests \(
* `$SYS.REQ.SERVER.PING.<endpoint-name>` \(from all server request server monitoring endpoint corresponding to endpoint name - will return multiple messages\)
| 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
```