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

Adding explanations/links. Grouping main config options and adding defaults

Browse Source 
refreshed some sample output

Signed-off-by: Matthias Hanel <mh@synadia.com>
This commit is contained in:
Matthias Hanel 2020-02-11 11:58:20 -05:00
parent 77b1848373
commit 4f41f267fe
5 changed files with 102 additions and 59 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
nats-server/clients.md
View File

@ -1,6 +1,6 @@
# Clients # Clients
The nats-server doesn't come bundled with any clients. But most client libraries come with tools that allow you to publish, subscribe, send requests and reply messages. The nats-server doesn't come bundled with any clients. But most client libraries come with sample programs that allow you to publish, subscribe, send requests and reply messages.
If you have a client library installed, you can try using a bundled client. Otherwise, you can easily install some clients. If you have a client library installed, you can try using a bundled client. Otherwise, you can easily install some clients.
@ -17,7 +17,7 @@ You can install pre-built binaries from the [go-nats-examples repo](https://gith
## Testing your setup ## Testing your setup
Open a terminal and [start a nats-server](running/): Open a terminal and [start a nats-server](running/README.md):
```text ```text
> nats-server > nats-server
@ -40,20 +40,21 @@ Note that when the client connected, the server didn't log anything interesting
To make the server output more lively, you can specify the `-V` flag to enable logging of server protocol tracing messages. Go ahead and `<ctrl>+c` the process running the server, and restart the server with the `-V` flag: To make the server output more lively, you can specify the `-V` flag to enable logging of server protocol tracing messages. Go ahead and `<ctrl>+c` the process running the server, and restart the server with the `-V` flag:
```text ```text
> nats-server -V nats-server -V
[29785] 2019/05/16 08:46:12.731278 [INF] Starting nats-server version 2.0.0 [10864] 2020/02/06 14:17:18.085700 [INF] Starting nats-server version 2.1.4
[29785] 2019/05/16 08:46:12.731347 [INF] Git commit [not set] [10864] 2020/02/06 14:17:18.085811 [INF] Git commit [not set]
[29785] 2019/05/16 08:46:12.731488 [INF] Listening for client connections on 0.0.0.0:4222 [10864] 2020/02/06 14:17:18.086039 [INF] Listening for client connections on 0.0.0.0:4222
[29785] 2019/05/16 08:46:12.731493 [INF] Server id is NCEOJJ5SBJKUTMZEDNU3NBPJSLJPCMQJUIQIWKFHWE5DPETJKHX2CO2Y [10864] 2020/02/06 14:17:18.086046 [INF] Server id is NDKUZPVC3Y4YHLZBDDCDZSPLAH7KZU3NVTL3WQZ2QIIY2DQN7KZ5BDNW
[29785] 2019/05/16 08:46:12.731495 [INF] Server is ready [10864] 2020/02/06 14:17:18.086049 [INF] Server is ready
[29785] 2019/05/16 08:46:13.467099 [TRC] 127.0.0.1:49805 - cid:1 - <<- [CONNECT {"verbose":false,"pedantic":false,"tls_required":false,"name":"NATS Sample Subscriber","lang":"go","version":"1.7.0","protocol":1,"echo":true}] [10864] 2020/02/06 14:17:19.393075 [TRC] [::1]:62646 - cid:1 - <<- [CONNECT {"verbose":false,"pedantic":false,"lang":"ruby","version":"0.11.0","protocol":1,"echo":true}]
[29785] 2019/05/16 08:46:13.467200 [TRC] 127.0.0.1:49805 - cid:1 - <<- [PING] [10864] 2020/02/06 14:17:19.393265 [TRC] [::1]:62646 - cid:1 - <<- [SUB > 2]
[29785] 2019/05/16 08:46:13.467206 [TRC] 127.0.0.1:49805 - cid:1 - ->> [PONG] [10864] 2020/02/06 14:17:21.758750 [TRC] [::1]:62646 - cid:1 - ->> [PING]
[10864] 2020/02/06 14:17:21.759400 [TRC] [::1]:62646 - cid:1 - <<- [PONG]
``` ```
If you had created a subscriber, you should notice output on the subscriber telling you that it disconnected, and reconnected. The server output above is more interesting. You can see the subscriber send a `CONNECT` protocol message and a `PING` which was responded to by the server with a `PONG`. If you had created a subscriber, you should notice output on the subscriber telling you that it disconnected, and reconnected. The server output above is more interesting. You can see the subscriber send a `CONNECT` protocol message and a `PING` which was responded to by the server with a `PONG`.
> You can learn more about the [NATS protocol here](../nats-protocol/nats-protocol/), but more intersting than the protocol description is [an interactive demo](../nats-protocol/nats-protocol-demo.md). > You can learn more about the [NATS protocol here](../nats-protocol/nats-protocol/README.md), but more interesting than the protocol description is [an interactive demo](../nats-protocol/nats-protocol-demo.md).
On a third terminal, publish your first message: On a third terminal, publish your first message:
@ -65,7 +66,9 @@ Published [hello] : 'world'
On the subscriber window you should see: On the subscriber window you should see:
```text ```text
> nats-sub ">"
Listening on [>]
[#1] Received on [hello] : 'world'
``` ```
## Testing Against a Remote Server ## Testing Against a Remote Server

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

@ -20,6 +20,7 @@ The configuration parser is very forgiving, as you have seen:
* values can be a primitive, or a list, or a map * values can be a primitive, or a list, or a map
* strings and numbers typically do the right thing * strings and numbers typically do the right thing
* numbers support units such as, 1K for 1000, 1Kb for 1024
String values that start with a digit _can_ create issues. To force such values as strings, quote them. String values that start with a digit _can_ create issues. To force such values as strings, quote them.
@ -104,34 +105,70 @@ authorization: {
## Configuration Properties ## Configuration Properties
| Property | Description | ### Connectivity
| :--- | :--- | | Property | Description | Default |
| [`accounts`](securing_nats/auth_intro/accounts.md) | Configuration map for accounts | | :--- | :--- | :--- |
| [`authorization`](securing_nats/auth_intro/) | Configuration map for client authentication/authorization | | `host` | Host for client connections. | `0.0.0.0` |
| [`cluster`](clustering/cluster_config.md) | Configuration map for clustering configuration | | `port` | Port for client connections. | `4222` |
| `connect_error_reports` | Number of attempts at which a repeated failed route, gateway or leaf node connection is reported. Default is 3600, approx every hour. | | `listen` | Listen specification `<host>:<port>` for client connections. Either use this or the options `host` and/or `port`. | same as `host`, `port` |
| `debug` | If `true` enable debug log messages | | `client_advertise`| Alternative client listen specification `<host>:<port>` or just `<host>` to advertise to clients and other server. Useful in [cluster](clustering/cluster_config.md) setups with NAT. | Advertise what `host` and `port` specify. |
| [`gateway`](gateways/gateway.md) | Gateway configuration map | | [`tls`](securing_nats/tls.md) | Configuration map for tls for client and http monitoring. | |
| `host` | Host for client connections | | [`cluster`](clustering/cluster_config.md) | Configuration map for [cluster](clustering/README.md) configuration. | |
| [`http_port`](monitoring.md) | http port for server monitoring | | [`gateway`](gateways/gateway.md) | Configuration map for [Gateway](gateways/README.md) configuration. | |
| [`https_port`](monitoring.md) | https port for server monitoring | | [`leafnode`](leafnodes/leafnode_conf.md) | Configuration map for [leafnode](leafnodes/README.md). ||
| [`leafnode`](leafnodes/leafnode_conf.md) | Leafnode configuration map |
| `listen` | Host/port for client connections | ### Connection timeouts
| `max_connections` | Maximum number of active client connections | | Property | Description | Default |
| `max_control_line` | Maximum length of a protocol line \(including subject length\) | | :--- | :--- | :--- |
| `max_payload` | Maximum number of bytes in a message payload | | `ping_interval` | Interval in seconds, at which pings are sent to clients, leaf nodes and routes. In the presence of client traffic, such as messages or client side pings, the server will not send pings. Therefore it is recommended to keep this value bigger than what [clients use](../../developing-with-nats/connecting/pingpong.md). | `120`, 2 Minutes. |
| `max_pending` | Maximum number of bytes buffered for a connection | | `ping_max` | After how many unanswered pings the server will allow before closing the connection. | `2` |
| `max_subscriptions` | Maximum numbers of subscriptions for a client connection | | `write_deadline` | Maximum number of seconds the server will block when writing. Once this threshold is exceeded the connection will be closed. See [_slow consumer_](../../developing-with-nats/events/slow.md) on how to deal with this on the client. | `"2s"` |
| `max_traced_msg_len` | Set a limit to the trace of the payload of a message |
| `disable_sublist_cache` | Disable sublist cache globally for accounts. | ### Limits
| [`operator`](../../nats-tools/nsc/nsc.md#nats-server-configuration) | Path to an operator JWT | | Property | Description | Default |
| [`ping_interval`]() | Interval in seconds in which the server checks if a connection is active | | :--- | :--- | :--- |
| `port` | Port for client connections | | `max_connections` | Maximum number of active client connections. | `64K` |
| `reconnect_error_reports` | Number of failed attempt to reconnect a route, gateway or leaf node connection. Default is to report every attempt. | | `max_control_line` | Maximum length of a protocol line \(including combined length of subject and queue group\). Increasing this value may require [client changes](../../developing-with-nats/connecting/protocol.md#Set-the-Maximum-Control-Line-Size) to be used. Applies to all traffic. | `4Kb` |
| [`resolver`]() | Resolver type `MEMORY` or `URL` for account JWTs | | `max_payload` | Maximum number of bytes in a message payload. Reducing this size may force you to implement [chunking](../../developing-with-nats/connecting/protocol.md#Get-the-Maximum-Payload-Siz) in your clients. Applies to client and leafnode payloads.| `1Mb` |
| [`tls`](securing_nats/tls.md#tls-configuration) | Configuration map for tls for client and http monitoring | | `max_pending` | Maximum number of bytes buffered for a connection Applies to client connections.| `64Mb` |
| `trace` | If `true` enable protocol trace log messages | | `max_subscriptions` | Maximum numbers of subscriptions per client and leafnode accounts connection. | `0`, unlimited |
| `write_deadline` | Maximum number of seconds the server will block when writing a to a client \(slow consumer\) |
### Authentication and Authorization
| Property | Description | Default |
| :--- | :--- | :--- | :---|
| [`authorization`](securing_nats/auth_intro/README.md) | Configuration map for client authentication/authorization. |
| [`operator`](../../nats-tools/nsc/nsc.md#nats-server-configuration) | Path to an operator JWT. |
| [`accounts`](securing_nats/accounts.md) | Configuration map for accounts. | |
| [`resolver`](../../nats-tools/nas/README.md) | Resolver type `MEMORY` or `URL(<url>)` for account JWTs. | |
| `resolver_tls` | [`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` | Map to preload account public keys and their corresponding JWT. Keys consist of `<account public nkey>`, value is the `<corresponding jwt>`. | |
### Runtime Configuration
| Property | Description | Default |
| :--- | :--- | :--- |
| `disable_sublist_cache` | If `true` disable subscription caches for all accounts. This is saves resources in situations where different subjects are used all the time. | `false`, cache enabled |
| `lame_duck_duration` | In lame duck mode the server rejects new clients and **slowly** closes client connections. After this duration is over the server shuts down. Start lame duck mode with: [`nats-server --signal ldm`](../nats_admin/signals.md). | `"2m"` |
### Monitoring and Tracing
| Property | Description | Default |
| :--- | :--- | :--- |
| `server_name`| The servers name, shows up in logging. Defaults to the server's id. | Generated Server ID |
| `trace` | If `true` enable protocol trace log messages | `false`, disabled |
| `debug` | If `true` enable debug log messages | `false`, disabled |
| `logtime` | If set to `false`, log without timestamps | `true`, include timestamp|
| `log_file` | Log file name, relative to... | No log file |
| `log_size_limit` | Size in bytes after the log file rolls over to a new one | `0`, unlimited |
| `max_traced_msg_len` | Set a limit to the trace of the payload of a message. | `0`, unlimited |
| `syslog` | Log to syslog. | `false`, disabled |
| `remote_syslog` | Syslog server address.| |
| [`http_port`](monitoring.md) | http port for server monitoring. | |
| [`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. | |
| `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 |
| `reconnect_error_reports` | Number of failed attempt to reconnect a route, gateway or leaf node connection. Default is to report every attempt. | `1`, every failed attempt|
## Configuration Reloading ## Configuration Reloading
@ -140,4 +177,3 @@ A server can reload most configuration changes without requiring a server restar
```text ```text
> nats-server --signal reload > nats-server --signal reload
``` ```

4
nats-server/flags.md
View File

@ -64,6 +64,8 @@ You can read more about [logging configuration here](configuration/logging.md).
| `--tlsverify` | Enable client TLS certificate verification | | `--tlsverify` | Enable client TLS certificate verification |
| `--tlscacert` | Client certificate CA for verification | | `--tlscacert` | Client certificate CA for verification |
You can read more about [tls configuration here](configuration/securing_nats/tls.md).
## Cluster Options ## Cluster Options
The following flags are available on the server to configure clustering: The following flags are available on the server to configure clustering:
@ -76,7 +78,7 @@ The following flags are available on the server to configure clustering:
| `--cluster_advertise` | Cluster URL to advertise to other servers | | `--cluster_advertise` | Cluster URL to advertise to other servers |
| `--connect_retries` | For implicit routes, number of connect retries | | `--connect_retries` | For implicit routes, number of connect retries |
You can read more about [clustering configuration here](configuration/clustering/). You can read more about [clustering configuration here](configuration/clustering/README.md).
## Common Options ## Common Options

8
nats-server/installation.md
View File

@ -32,7 +32,7 @@ To run NATS on Docker:
[1] 2019/05/24 15:42:58.229003 [INF] Listening for route connections on 0.0.0.0:6222 [1] 2019/05/24 15:42:58.229003 [INF] Listening for route connections on 0.0.0.0:6222
``` ```
More information on [containerized NATS is available here](nats_docker/). More information on [containerized NATS is available here](nats_docker/README.md).
## Installing on Kubernetes with NATS Operator ## Installing on Kubernetes with NATS Operator
@ -161,14 +161,14 @@ find ./ -type f -name "*.go" -exec sed -i -e 's/github.com\/nats-io\/nats-server
### Gotchas when using `go get` ### Gotchas when using `go get`
If using `go get` for the client, then have to be careful with adding an extra slash at the end of the repo for example: When using `go get` to fetch the client, include an extra slash at the end of the repo. For example:
``` ```
GO111MODULE=on go get github.com/nats-io/nats.go/@latest GO111MODULE=on go get github.com/nats-io/nats.go/@latest
GO111MODULE=on go get github.com/nats-io/nats.go/@v1.8.1 GO111MODULE=on go get github.com/nats-io/nats.go/@v1.8.1
``` ```
If trying to fetch the latest version of the server with `go get`, then have to add `v2` at the end: When trying to fetch the latest version of the server with `go get`, you have to add `v2` at the end:
``` ```
GO111MODULE=on go get github.com/nats-io/nats-server/v2@latest GO111MODULE=on go get github.com/nats-io/nats-server/v2@latest
@ -183,7 +183,7 @@ go: finding golang.org/x/crypto/bcrypt latest
go: finding golang.org/x/crypto latest go: finding golang.org/x/crypto latest
``` ```
In order to use an older tag, you will also have to use the previous name (gnatsd) otherwise it would results in `go mod` parsing errors. In order to use an older tag, you will have to use the previous name (gnatsd) otherwise it will results in `go mod` parsing errors.
``` ```
# OK # OK

26
nats-server/running/README.md
View File

@ -8,11 +8,12 @@ When the server starts it will print some information including where the server
```text ```text
> nats-server > nats-server
[41634] 2019/05/13 09:42:11.745919 [INF] Starting nats-server version 2.0.0 [9318] 2020/02/06 14:06:08.220885 [INF] Starting nats-server version 2.1.4
[41634] 2019/05/13 09:42:11.746240 [INF] Listening for client connections on 0.0.0.0:4222 [9318] 2020/02/06 14:06:08.221099 [INF] Git commit [fb009af]
[9318] 2020/02/06 14:06:08.221466 [INF] Listening for client connections on 0.0.0.0:4222
[9318] 2020/02/06 14:06:08.221476 [INF] Server id is NAINBEK336OZMOZUBNOFCJWG4Q2XNFEROWLF6FQWOGM4CBLI5Y6G33NW
[9318] 2020/02/06 14:06:08.221478 [INF] Server is ready
... ...
[41634] 2019/05/13 09:42:11.746249 [INF] Server id is NBNYNR4ZNTH4N2UQKSAAKBAFLDV3PZO4OUYONSUIQASTQT7BT4ZF6WX7
[41634] 2019/05/13 09:42:11.746252 [INF] Server is ready
``` ```
## Docker ## Docker
@ -20,15 +21,16 @@ When the server starts it will print some information including where the server
If you are running your NATS server in a docker container: If you are running your NATS server in a docker container:
```text ```text
> docker run -p 4222:4222 -ti nats:latest docker run -p 4222:4222 -ti nats:latest
[1] 2019/05/13 14:55:11.981434 [INF] Starting nats-server version 2.0.0 [1] 2020/02/06 19:04:56.020658 [INF] Starting nats-server version 2.1.4
... [1] 2020/02/06 19:04:56.020712 [INF] Git commit [fb009af]
[1] 2019/05/13 14:55:11.981545 [INF] Starting http monitor on 0.0.0.0:8222 [1] 2020/02/06 19:04:56.020833 [INF] Starting http monitor on 0.0.0.0:8222
[1] 2019/05/13 14:55:11.981560 [INF] Listening for client connections on 0.0.0.0:4222 [1] 2020/02/06 19:04:56.020897 [INF] Listening for client connections on 0.0.0.0:4222
[1] 2019/05/13 14:55:11.981565 [INF] Server is ready [1] 2020/02/06 19:04:56.020919 [INF] Server id is NBSNFHIXGTZJ4OCMHU52UGVOLCJEKYTYEAFMABDJUAKZUQE2ULXBQGHX
[1] 2019/05/13 14:55:11.982492 [INF] Listening for route connections on 0.0.0.0:6222 [1] 2020/02/06 19:04:56.020923 [INF] Server is ready
[1] 2020/02/06 19:04:56.021174 [INF] Listening for route connections on 0.0.0.0:6222
... ...
``` ```
More information on [containerized NATS is available here](../nats_docker/). More information on [containerized NATS is available here](../nats_docker/README.md).