diff --git a/SUMMARY.md b/SUMMARY.md index 06309b4..949c3ab 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -20,6 +20,7 @@ * [Authentication Timeout](nats_server/auth_timeout.md) * [Authorization](nats_server/authorization.md) * [Clustering](nats_server/clustering.md) + * [Configuration](nats_server/cluster_config.md) * [TLS Authentication](nats_server/cluster_tls.md) * [Gateways](gateways/README.md) * [Configuration](gateways/gateway.md) @@ -36,20 +37,21 @@ * [Configuration](sys_accounts/sysaccounts.md) ### NATS Tools -* [mkpasswd](nats_tools/mkpasswd.md) -* [nk](nats_tools/nk.md) -* [nsc](nats_tools/nsc/README.md) - * [Basics](nats_tools/nsc/nsc.md) - * [Streams](nats_tools/nsc/streams.md) - * [Services](nats_tools/nsc/services.md) - * [Signing Keys](nats_tools/nsc/signing_keys.md) -* [nats account server](nats_tools/nas/README.md) - * [Basics](nats_tools/nas/nas_conf.md) - * [Inspecting JWTs](nats_tools/nas/inspecting_jwts.md) - * [Memory Resolver](nats_tools/nas/mem_resolver.md) -* [NATS Top](nats_tools/nats_top/README.md) - * [Tutorial](nats_tools/nats_top/tutorial.md) -* [Benchmarking](nats_tools/natsbench.md) +* [Tools](nats_tools/README.md) + * [mkpasswd](nats_tools/mkpasswd.md) + * [nk](nats_tools/nk.md) + * [nsc](nats_tools/nsc/README.md) + * [Basics](nats_tools/nsc/nsc.md) + * [Streams](nats_tools/nsc/streams.md) + * [Services](nats_tools/nsc/services.md) + * [Signing Keys](nats_tools/nsc/signing_keys.md) + * [nats-account-server](nats_tools/nas/README.md) + * [Basics](nats_tools/nas/nas_conf.md) + * [Inspecting JWTs](nats_tools/nas/inspecting_jwts.md) + * [Memory Resolver](nats_tools/nas/mem_resolver.md) + * [nats-top](nats_tools/nats_top/README.md) + * [Tutorial](nats_tools/nats_top/tutorial.md) + * [nats-bench](nats_tools/natsbench.md) ### NATS Containerization * [NATS.docker](nats_docker/README.md) diff --git a/gateways/gateway.md b/gateways/gateway.md index 777e436..67f30c0 100644 --- a/gateways/gateway.md +++ b/gateways/gateway.md @@ -69,7 +69,7 @@ Listening on [>] | `name` | Name for this cluster, all gateways belonging to the same cluster, should specify the same name. | | `port` | Port where the gateway will listen for incomming gateway connections. | | `reject_unknown` | If `true`, gateway will reject connections from gateways that are not configured in `gateways`. | -| `tls` | TLS configuration block (same as other nats-server `tls` configuration). | +| `tls` | TLS configuration block (same as other [nats-server `tls` configuration](/nats_server/tls.md#tls-configuration)). | @@ -83,18 +83,3 @@ The `gateways` configuration block is a list of gateway entries with the followi | `url` | Hostport `:` describing where the remote gateway can be reached. If multiple IPs are returned, one is randomly selected. | | `urls` | A list of `url` | - - -### `TLS` Configuration Block - -| Property | Description | -| :------ | :---- | -| `ca_file` | TLS certificate authority file. | -| `cert_file` | TLS certificate file. | -| `cipher_suites` | When set, only the specified TLS cipher suites will be allowed. Values must match golang version used to build the server. | -| `curve_preferences` | List of TLS cypher curves to use in order. | -| `insecure` | Skip certificate verfication. | -| `key_file` | TLS certificate key file. | -| `timeout` | TLS handshake timeout in fractional seconds. | -| `verify_and_map` | If `true`, require and verify client certificates and use values map certificate values for authentication purposes. | -| `verify` | If `true`, require and verify client certificates. | diff --git a/nats_server/auth_intro.md b/nats_server/auth_intro.md index 9ada7ed..6808b2e 100644 --- a/nats_server/auth_intro.md +++ b/nats_server/auth_intro.md @@ -11,3 +11,39 @@ The NATS server provides various ways of authenticating clients: Authentication deals with allowing a NATS client to connect to the server. With the exception of JWT authentication, authentication and authorization configuration is in the `authorization` block of the configuration. +## Authorization Block + +The `authorization` block provides _authentication_ configuration as well as _authorization_: + +| Property | Description | +| :------ | :---- | +| [`token`](tokens.md) | Specifies a token that can be used to authenticate to the server | +| [`user`](username_password.md) | Specifies a single user name for clients to the server | +| [`password`](username_password.md) | Specifies a single password for clients to the server | +| `users` | A list of `user` configuration maps | +| `timeout` | Maximum number of seconds to wait for client authentication | + + + +### User Configuration Map + +A `user` configuration map specifies credentials and permissions options for a single user: + +| Property | Description | +| :------ | :---- | +| [`user`](username_password.md) | username for client authentication | +| [`password`](username_password.md) | password for the user entry | +| [`nkey`](nkey_auth.md) | public nkey identifying an user | +| `permissions` | permissions map configuring subjects accessible to the user | + + +### Permissions Configuration Map + +The `permissions` map specify subjects that can be subscribed to or published by the specified client. + + + + + + + diff --git a/nats_server/cluster_config.md b/nats_server/cluster_config.md new file mode 100644 index 0000000..a55404a --- /dev/null +++ b/nats_server/cluster_config.md @@ -0,0 +1,34 @@ +## Cluster Configuration + +The `cluster` configuration map has the following configuration options: + +| Property | Description | +| :------ | :---- | +| `listen` | host/port for inbound route connections | +| `authorization` | [authorization](authorization.md) map for configuring cluster clients. Supports `token`, `username`/`password` and `TLS authentication`. `permissions` are ignored. | +| `timeout` | Maximum amount of time (in seconds) to wait for a clustering connection to complete +| `tls` | A [`tls` configuration map](tls.md#tls-configuration) for securing the clustering connection | +| `routes` | A list of other servers (URLs) to cluster with. Self-routes are ignored. | + + +```ascii +cluster { + listen: localhost:4244 # host/port for inbound route connections + + # Authorization for route connections + authorization { + user: route_user + # ./util/mkpasswd -p T0pS3cr3tT00! + password: $2a$11$xH8dkGrty1cBNtZjhPeWJewu/YPbSU.rXJWmS6SFilOBXzmZoMk9m + timeout: 0.5 + } + + # Routes are actively solicited and connected to from this server. + # Other servers can connect to us if they supply the correct credentials + # in their routes definitions from above. + routes = [ + nats-route://user1:pass1@127.0.0.1:4245 + nats-route://user2:pass2@127.0.0.1:4246 + ] +} +``` \ No newline at end of file diff --git a/nats_server/configuration.md b/nats_server/configuration.md index 901bef4..637dc73 100644 --- a/nats_server/configuration.md +++ b/nats_server/configuration.md @@ -97,6 +97,30 @@ authorization: { > nats-server -c server.conf ``` +### Configuration Properties + +| Property | Description | +| :------ | :---- | +| [`authorization`](auth_intro.md) | configuration map for client authentication/authorization | +| [`cluster`](cluster_config.md) | configuration map for clustering configuration | +| `debug` | if `true` enable debug log messages | +| [`gateway`](/gateways/gateway.md) | Gateway configuration map | +| `host` | host for client connections | +| [`http_port`](monitoring.md) | http port for server monitoring | +| [`https_port`](monitoring.md) | https port for server monitoring | +| [`leafnode`](/leafnodes/leafnode_conf.md) | Leafnode configuration map | +| `listen` | host/port for client connections | +| `max_connections` | Maximum number of active client connections | +| `max_control_line` | Maximum length of a protocol line (including subject length) | +| `max_payload` | Maximum number of bytes in a message payload | +| `max_subscriptions` | Maximum numbers of subscriptions for a client connection | +| [`operator`](/nats_tools/nsc/nsc.md#nats-server-configuration) | path to an operator JWT | +| `port` | port for client connections | +| [`resolver`](/nats_tools/nsc/nsc.md#nats-server-configuration) | Resolver type `MEMORY` or `URL` for account JWTs | +| [`tls`](tls.md#tls-configuration) | configuration map for tls for client and http monitoring | +| `trace` | if `true` enable protocol trace log messages | +| `write_deadline` | Maximum number of seconds the server will block when writing a to a client (slow consumer) | + ### Configuration Reloading diff --git a/nats_server/tls.md b/nats_server/tls.md index 191a2b0..2a03103 100644 --- a/nats_server/tls.md +++ b/nats_server/tls.md @@ -3,12 +3,17 @@ The NATS server uses modern TLS semantics to encrypt client, route and monitoring connections. Server configuration revolves around a `tls` map, which has the following properties: -- `cert_file` - the server's certificate -- `key_file` - the server's key file -- `ca_file` - a certificate file providing the trust chain for the certificate authority (CA). Used to validate client certificates. -- `timeout` - max seconds to allow for a TLS connection upgrade (default is 2 seconds) -- `verify` - set to `true` if you want to verify client certs against the `ca_file` certificate. - +| Property | Description | +| :------ | :---- | +| `ca_file` | TLS certificate authority file. | +| `cert_file` | TLS certificate file. | +| `cipher_suites` | When set, only the specified TLS cipher suites will be allowed. Values must match golang version used to build the server. | +| `curve_preferences` | List of TLS cypher curves to use in order. | +| `insecure` | Skip certificate verfication. | +| `key_file` | TLS certificate key file. | +| `timeout` | TLS handshake timeout in fractional seconds. | +| `verify_and_map` | If `true`, require and verify client certificates and map certificate values for authentication purposes. | +| `verify` | If `true`, require and verify client certificates. | The simplest configuration: ``` diff --git a/nats_tools/README.md b/nats_tools/README.md index c478ae8..bcffe24 100644 --- a/nats_tools/README.md +++ b/nats_tools/README.md @@ -1,5 +1,10 @@ ## NATS Tools -The NATS Ecosystem has many tools, some interesting tools include: +The NATS Ecosystem has many tools to support server configuration, enhance monitoring or tune performance: -- [NATS TOP (statistics)](nats_top/README.md) \ No newline at end of file +- [mkpasswd](nats_tools/mkpasswd.md) - Generates or bcrypts passwords +- [nk](nats_tools/nk.md) - Generate NKeys +- [nsc](nats_tools/nsc/README.md) - Configure Operators, Accounts and Users +- [nats account server](nats_tools/nas/README.md) - Serve Account JWTs +- [nats top](nats_tools/nats_top/README.md) - Monitor NATS Server +- [nats-bench](nats_tools/natsbench.md) - Benchmark NATS Server \ No newline at end of file