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
@@ -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).
|
||||
|
||||
Reference in New Issue
Block a user