mirror of
https://github.com/taigrr/nats.docs
synced 2025-01-18 04:03:23 -08:00
Move sys_accounts to configuration, add subs=detail to monitoring
Signed-off-by: Matthias Hanel <mh@synadia.com>
This commit is contained in:
Matthias Hanel
parent
453fb0d4a7
commit
9ff523d2c9
@ -92,12 +92,11 @@
|
||||
* [Configuration](nats-server/configuration/leafnodes/leafnode_conf.md)
|
||||
* [Logging](nats-server/configuration/logging.md)
|
||||
* [Monitoring](nats-server/configuration/monitoring.md)
|
||||
* [System Events](nats-server/configuration/sys_accounts/README.md)
|
||||
* [Managing A NATS Server](nats-server/nats_admin/README.md)
|
||||
* [Upgrading a Cluster](nats-server/nats_admin/upgrading_cluster.md)
|
||||
* [Slow Consumers](nats-server/nats_admin/slow_consumers.md)
|
||||
* [Signals](nats-server/nats_admin/signals.md)
|
||||
* [System Accounts](nats-server/nats_admin/sys_accounts/README.md)
|
||||
* [Configuration](nats-server/nats_admin/sys_accounts/sys_accounts.md)
|
||||
* [NATS and Docker](nats-server/nats_docker/README.md)
|
||||
* [Tutorial](nats-server/nats_docker/nats-docker-tutorial.md)
|
||||
* [Docker Swarm](nats-server/nats_docker/docker_swarm.md)
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
# Slow Consumers
|
||||
|
||||
NATS is designed to move messages through the server quickly. As a result, NATS depends on the applications to consider and respond to changing message rates. The server will do a bit of impedance matching, but if a client is too slow the server will eventually cut them off by closing the connection. These cut off connections are called _slow consumers_.
|
||||
NATS is designed to move messages through the server quickly. As a result, NATS depends on the applications to consider and respond to changing message rates. The server will do a bit of impedance matching, but if a client is too slow the server will eventually cut them off by closing the connection. These cut off connections are called [_slow consumers_](../../nats-server/nats_admin/slow_consumers.md).
|
||||
|
||||
One way some of the libraries deal with bursty message traffic is to buffer incoming messages for a subscription. So if an application can handle 10 messages per second and sometimes receives 20 messages per second, the library may hold the extra 10 to give the application time to catch up. To the server, the application will appear to be handling the messages and consider the connection healthy. Most client libraries will notify the application that there is a SlowConsumer error and discard messages.
|
||||
|
||||
|
||||
@ -5,7 +5,7 @@ In this section you can find several examples of how to deploy NATS, NATS Stream
|
||||
* [Getting Started](nats-kubernetes.md#getting-started)
|
||||
* [Basic NATS and NATS Streaming Setup on k8s](minimal-setup.md)
|
||||
* [Creating a NATS Streaming Cluster in k8s with FT mode](stan-ft-k8s-aws.md)
|
||||
* [NATS + Prometheus Operator](https://github.com/nats-io/nats.docs/tree/ccb05cdf9225a46fc872a6deab55dca4e072e902/nats-kubernetes/prometheus-and-nats-operator/README.md)
|
||||
* [NATS + Prometheus Operator](prometheus-and-nats-operator.md)
|
||||
* [NATS + Cert Manager in k8s](nats-cluster-and-cert-manager.md)
|
||||
* [Securing a NATS Cluster using cfssl](operator-tls-setup-with-cfssl.md)
|
||||
|
||||
@ -37,7 +37,7 @@ curl -sSL https://nats-io.github.io/k8s/setup.sh | sh -s -- --without-tls
|
||||
curl -sSL https://nats-io.github.io/k8s/setup.sh | sh -s -- --without-tls --without-auth
|
||||
```
|
||||
|
||||
**Note**: Since [NATS Streaming](https://github.com/nats-io/nats-streaming-server) will be running as a [leafnode](https://github.com/nats-io/docs/tree/master/leafnodes) to NATS \(under the STAN account\) and that [NATS Surveyor](https://github.com/nats-io/nats-surveyor) requires the [system account](https://github.com/nats-io/nats.docs/tree/ccb05cdf9225a46fc872a6deab55dca4e072e902/nats-kubernetes/,,/nats-server/nats_admin/sys_accounts/README.md) to monitor events, disabling auth also means that NATS Streaming and NATS Surveyor based monitoring will be disabled.
|
||||
**Note**: Since [NATS Streaming](https://github.com/nats-io/nats-streaming-server) will be running as a [leafnode](../nats-server/configuration/leafnodes/README.md) to NATS \(under the STAN account\) and that [NATS Surveyor](https://github.com/nats-io/nats-surveyor) requires the [system account](../nats-server/configuration/sys_accounts/README.md) to monitor events, disabling auth also means that NATS Streaming and NATS Surveyor based monitoring will be disabled.
|
||||
|
||||
The monitoring dashboard setup using NATS Surveyor can be accessed by using port-forward:
|
||||
|
||||
|
||||
@ -166,7 +166,7 @@ authorization: {
|
||||
| [`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](../nats_admin/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](monitoring/README.md) for more details. | |
|
||||
| `pid_file` | File containing PID, relative to ... This can serve as input to [nats-server --signal](../nats_admin/signals.md) | |
|
||||
| `port_file_dir` | Directory to write a file containing the servers open ports to, relative to ... | |
|
||||
| `connect_error_reports` | Number of attempts at which a repeated failed route, gateway or leaf node connection is reported. Connect attempts are made once every second.| `3600`, approx every hour |
|
||||
|
||||
@ -153,11 +153,11 @@ The `/connz` endpoint reports more detailed information on current and recently
|
||||
| :--- | :--- | :--- |
|
||||
| sort | \(_see sort options_\) | Sorts the results. Default is connection ID. |
|
||||
| auth | true, 1, false, 0 | Include username. Default is false. |
|
||||
| subs | true, 1, false, 0 | Include subscriptions. Default is false. |
|
||||
| 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. |
|
||||
| offset | number > 0 | Pagination offset. Default is 0. |
|
||||
| limit | number > 0 | Number of results to return. Default is 1024. |
|
||||
| cid | number, valid id | Return a connection by it's id |
|
||||
| state | open, \*closed, any | Return connections of partular state. Default is open. |
|
||||
| state | open, \*closed, any | Return connections of particular state. Default is open. |
|
||||
|
||||
_The server will default to holding the last 10,000 closed connections._
|
||||
|
||||
@ -263,7 +263,7 @@ The `/routez` endpoint reports information on active routes for a cluster. Route
|
||||
|
||||
| Argument | Values | Description |
|
||||
| :--- | :--- | :--- |
|
||||
| subs | true, 1, false, 0 | Include internal subscriptions. Default is false. |
|
||||
| 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)
|
||||
|
||||
|
||||
@ -71,11 +71,11 @@ Exports and imports from an account are explicit, and they are visible in the ac
|
||||
|
||||
## Configuration
|
||||
|
||||
Entity JWT configuration is done using the [`nsc` tool](../../../../nats-tools/nsc/). The basic steps include:
|
||||
Entity JWT configuration is done using the [`nsc` tool](../../../../nats-tools/nsc/README.md). The basic steps include:
|
||||
|
||||
* [Creation of an operator JWT](../../../../nats-tools/nsc/nsc.md#creating-an-operator)
|
||||
* [Configuring an Account Server](../../../../nats-tools/nsc/nsc.md#account-server-configuration)
|
||||
* [Setting up the NATS server to resolve Accounts](../../../../nats-tools/nsc/nsc.md#nats-server-configuration)
|
||||
|
||||
After that, `nsc` is used to create and edit accounts and users.
|
||||
After that, [`nsc`](../../../../nats-tools/nsc/README.md) is used to create and edit accounts and users.
|
||||
|
||||
|
||||
70
nats-server/configuration/sys_accounts/README.md
Normal file
70
nats-server/configuration/sys_accounts/README.md
Normal file
@ -0,0 +1,70 @@
|
||||
# System Events and Services
|
||||
|
||||
NATS servers leverage [Accounts](../../configuration/securing_nats/auth_intro/accounts.md) support and generate events such as:
|
||||
|
||||
* account connect/disconnect
|
||||
* authentication errors
|
||||
* server shutdown
|
||||
* server stat summary
|
||||
|
||||
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.
|
||||
|
||||
[Accounts](../../configuration/securing_nats/auth_intro/accounts.md) are used so that subscriptions from your applications, say `>`, do not receive system events and vice versa.
|
||||
Using accounts requires either:
|
||||
* [Configuring authentication locally](#Local-Configuration) and listing one of the accounts in `system_account`
|
||||
* Or by using decentralized authentication and authorization via [jwt](../../configuration/securing_nats/auth_intro/jwt_auth.md) as shown in this [Tutorial](sys_accounts.md).
|
||||
|
||||
## Available Events and Services
|
||||
|
||||
The system account publishes messages under well known subject patterns.
|
||||
|
||||
Server initiated events:
|
||||
|
||||
* `$SYS.ACCOUNT.<id>.CONNECT` \(client connects\)
|
||||
* `$SYS.ACCOUNT.<id>.DISCONNECT` \(client disconnects\)
|
||||
* `$SYS.SERVER.ACCOUNT.<id>.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.DISCONNECT` \(leaf node disconnects\)
|
||||
* `$SYS.SERVER.<id>.STATSZ` \(stats summary\)
|
||||
|
||||
In addition other tools with system account privileges, can initiate requests (Examples can be found [here](sys_accounts.md#System-Services)):
|
||||
|
||||
* `$SYS.REQ.SERVER.<id>.STATSZ` \(request server stat summary\)
|
||||
* `$SYS.REQ.SERVER.PING` \(discover servers - will return multiple messages\)
|
||||
|
||||
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:
|
||||
|
||||
* `$SYS.ACCOUNT.<id>.CLAIMS.UPDATE`
|
||||
|
||||
With these few messages you can build fairly surprisingly useful monitoring tools:
|
||||
|
||||
* health/load of your servers
|
||||
* client connects/disconnects
|
||||
* account connections
|
||||
* authentication errors
|
||||
|
||||
## Local Configuration
|
||||
|
||||
To make use of System events, just using accounts, your configuration can look like this:
|
||||
|
||||
```text
|
||||
accounts: {
|
||||
USERS: {
|
||||
users: [
|
||||
{user: a, password: a}
|
||||
]
|
||||
},
|
||||
SYS: {
|
||||
users: [
|
||||
{user: admin, password: changeit}
|
||||
]
|
||||
},
|
||||
}
|
||||
system_account: SYS
|
||||
```
|
||||
|
||||
Subscribe to all system events like this `nats-sub -s nats://admin:changeit@localhost:4222 ">"` and observe what happens when you do something like `nats-pub -s "nats://a:a@localhost:4222" foo bar`.
|
||||
Examples on how to use system services can be found [here](sys_accounts.md#System-Services).
|
||||
@ -1,49 +1,11 @@
|
||||
# Configuration
|
||||
|
||||
The following is a short tutorial on how you can activate a system account to:
|
||||
|
||||
* receive periodic updates from the server
|
||||
* send requests to the server
|
||||
* send an account update to the server
|
||||
|
||||
## Events and Services
|
||||
|
||||
The system account publishes messages under well known subject patterns.
|
||||
|
||||
Server initiated events:
|
||||
|
||||
* `$SYS.ACCOUNT.<id>.CONNECT` \(client connects\)
|
||||
* `$SYS.ACCOUNT.<id>.DISCONNECT` \(client disconnects\)
|
||||
* `$SYS.SERVER.ACCOUNT.<id>.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.DISCONNECT` \(leaf node disconnects\)
|
||||
* `$SYS.SERVER.<id>.STATSZ` \(stats summary\)
|
||||
|
||||
In addition other tools with system account privileges, can initiate requests:
|
||||
|
||||
* `$SYS.REQ.SERVER.<id>.STATSZ` \(request server stat summary\)
|
||||
* `$SYS.REQ.SERVER.PING` \(discover servers - will return multiple messages\)
|
||||
|
||||
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:
|
||||
|
||||
* `$SYS.ACCOUNT.<id>.CLAIMS.UPDATE`
|
||||
|
||||
With these few messages you can build fairly surprisingly useful monitoring tools:
|
||||
|
||||
* health/load of your servers
|
||||
* client connects/disconnects
|
||||
* account connections
|
||||
* authentication errors
|
||||
|
||||
## Enabling System Events
|
||||
# Enabling System Events with Decentralized Authentication/Authorization
|
||||
|
||||
To enable and access system events, you'll have to:
|
||||
|
||||
* Create an Operator, Account and User
|
||||
* Run a NATS Account Server \(or Memory Resolver\)
|
||||
|
||||
### Create an Operator, Account, User
|
||||
## Create an Operator, Account, User
|
||||
|
||||
Let's create an operator, system account and system account user:
|
||||
|
||||
@ -67,7 +29,7 @@ Success! - added user "SYSU" to "SYS"
|
||||
|
||||
By default, the operator JWT can be found in `~/.nsc/nats/<operator_name>/<operator.name>.jwt`.
|
||||
|
||||
### NATS-Account-Server
|
||||
## NATS-Account-Server
|
||||
|
||||
To vend the credentials to the nats-server, we'll use a [nats-account-server](../../../nats-tools/nas/). Let's start a nats-account-server to serve the JWT credentials:
|
||||
|
||||
@ -77,7 +39,7 @@ To vend the credentials to the nats-server, we'll use a [nats-account-server](..
|
||||
|
||||
The server will by default vend JWT configurations on the an endpoint at: `http(s)://<server_url>/jwt/v1/accounts/`.
|
||||
|
||||
### NATS Server Configuration
|
||||
## NATS Server Configuration
|
||||
|
||||
The server configuration will need:
|
||||
|
||||
@ -114,7 +76,7 @@ Let's start the nats-server:
|
||||
> nats-server -c server.conf
|
||||
```
|
||||
|
||||
## Inspecting Server Events
|
||||
# Inspecting Server Events
|
||||
|
||||
Let's add a subscriber for all the events published by the system account:
|
||||
|
||||
@ -174,6 +136,8 @@ The subscriber will print the connect and disconnect:
|
||||
}'
|
||||
```
|
||||
|
||||
# System Services
|
||||
|
||||
## `$SYS.REQ.SERVER.PING` - Discovering Servers
|
||||
|
||||
To discover servers in the cluster, and get a small heath summary, publish a request to `$SYS.REQ.SERVER.PING`. Note that while the example below uses `nats-req`, only the first answer for the request will be printed. You can easily modify the example to wait until no additional responses are received for a specific amount of time, thus allowing for all responses to be collected.
|
||||
@ -5,4 +5,6 @@ Managing a NATS server is simple, typical lifecycle operations include:
|
||||
* [Sending signals](signals.md) to a server to reload a configuration or rotate log files
|
||||
* [Upgrading](upgrading_cluster.md) a server \(or cluster\)
|
||||
* Understanding [slow consumers](slow_consumers.md)
|
||||
|
||||
* Monitoring the server via:
|
||||
* The monitoring [endpoint](../configuration/monitoring.md) and tools like [nats-top](../../nats-tools/nats_top/README.md)
|
||||
* By subscribing to [system events](../configuration/sys_accounts/sys_accounts.md)
|
||||
|
||||
@ -1,17 +0,0 @@
|
||||
# System Accounts
|
||||
|
||||
NATS servers leverage [Account](../../configuration/securing_nats/auth_intro/jwt_auth.md) support and generate events such as:
|
||||
|
||||
* account connect/disconnect
|
||||
* authentication errors
|
||||
* server shutdown
|
||||
* server stat summary
|
||||
|
||||
In addition the server supports a limitted number of requests that can be used to query for account connections, server stat summaries, and pinging servers in the cluster.
|
||||
|
||||
These events are only accepted and visible to _system account_ users.
|
||||
|
||||
## The System Events Tutorial
|
||||
|
||||
You can learn more about System Accounts in the [Tutorial](sys_accounts.md).
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
|
||||
The `nats-account-server` can notify a nats-server about 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/nats_admin/sys_accounts/).
|
||||
To push notifications, the nats-account-server makes use of [system accounts](../../nats-server/configuration/sys_accounts/sys_accounts.md).
|
||||
|
||||
Here's a nats-account-server configuration with updates enabled:
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user