diff --git a/SUMMARY.md b/SUMMARY.md index 079b7cb..0d6e9d0 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -203,3 +203,4 @@ * [Using a Load Balancer for External Access to NATS](nats-on-kubernetes/nats-external-nlb.md) * [Creating a NATS Super Cluster in Digital Ocean with Helm](nats-on-kubernetes/super-cluster-on-digital-ocean.md) * [From Zero to K8S to Leafnodes using Helm](nats-on-kubernetes/from-zero-to-leafnodes.md) + diff --git a/nats-on-kubernetes/from-zero-to-leafnodes.md b/nats-on-kubernetes/from-zero-to-leafnodes.md index 093c7be..a35f677 100644 --- a/nats-on-kubernetes/from-zero-to-leafnodes.md +++ b/nats-on-kubernetes/from-zero-to-leafnodes.md @@ -1,19 +1,16 @@ -# From Zero to Communicating Across K8S Regions using NATS Leafnodes +# From Zero to K8S to Leafnodes using Helm -First, we need a number of Kubernetes clusters to be setup already. In -this case we'll create a few in Digital Ocean using the `doctl` tool but -you could use any K8S solution available: +First, we need a number of Kubernetes clusters to be setup already. In this case we'll create a few in Digital Ocean using the `doctl` tool but you could use any K8S solution available: -``` +```text brew install doctl doctl kubernetes cluster create nats-k8s-sfo2 --count 3 --region sfo2 doctl kubernetes cluster create nats-k8s-ams3 --count 3 --region ams3 ``` -Next, get your NGS credentials with leafnodes enabled. For this follow [these instructions](https://synadia.com/ngs/signup) and choose the `Developer` plan which is free and will allow you to create leafnode connections for a couple of clusters. -Once you got the credentials, upload them as a secret to your K8S clusters: +Next, get your NGS credentials with leafnodes enabled. For this follow [these instructions](https://synadia.com/ngs/signup) and choose the `Developer` plan which is free and will allow you to create leafnode connections for a couple of clusters. Once you got the credentials, upload them as a secret to your K8S clusters: -```sh +```bash for ctx in do-ams3-nats-k8s-ams3 do-sfo2-nats-k8s-sfo2; do kubectl --context $ctx create secret generic ngs-creds --from-file $HOME/.nkeys/creds/synadia/NGS/NGS.creds done @@ -21,7 +18,7 @@ done Install Helm3 and add the NATS helm chart repo: -``` +```text brew install helm helm repo add nats https://nats-io.github.io/k8s/helm/charts/ helm repo update @@ -29,7 +26,7 @@ helm repo update Create the config that adds the leafnode connection to NGS: -``` +```text # nats.yaml leafnodes: enabled: true @@ -45,7 +42,7 @@ natsbox: Deploy it to your K8S regions: -```sh +```bash for ctx in do-ams3-nats-k8s-ams3 do-sfo2-nats-k8s-sfo2; do helm --kube-context $ctx install nats nats/nats -f nats.yaml done @@ -53,7 +50,7 @@ done To test the multi-region connectivity by using the `nats-box` container that got deployed in each cluster: -``` +```text kubectl --context do-ams3-nats-k8s-ams3 exec -it nats-box -- nats-sub -s nats hello Listening on [hello] @@ -64,7 +61,7 @@ done Results from the subscribe session: -``` +```text [#1] Received on [hello]: 'Hello World!' [#2] Received on [hello]: 'Hello World!' [#3] Received on [hello]: 'Hello World!' @@ -75,3 +72,4 @@ Results from the subscribe session: [#8] Received on [hello]: 'Hello World!' [#9] Received on [hello]: 'Hello World!' ``` + diff --git a/nats-on-kubernetes/nats-cluster-and-cert-manager.md b/nats-on-kubernetes/nats-cluster-and-cert-manager.md index cdf0e8f..78f0d14 100644 --- a/nats-on-kubernetes/nats-cluster-and-cert-manager.md +++ b/nats-on-kubernetes/nats-cluster-and-cert-manager.md @@ -7,7 +7,8 @@ kubectl create namespace cert-manager kubectl label namespace cert-manager certmanager.k8s.io/disable-validation=true kubectl apply --validate=false -f https://github.com/jetstack/cert-manager/releases/download/v0.14.0/cert-manager.yaml ``` -If you are running Kubernetes < 1.15, use `cert-manager-legacy.yaml` instead. + +If you are running Kubernetes < 1.15, use `cert-manager-legacy.yaml` instead. ```yaml apiVersion: cert-manager.io/v1alpha2 diff --git a/nats-on-kubernetes/nats-external-nlb.md b/nats-on-kubernetes/nats-external-nlb.md index ceb75cd..343fa25 100644 --- a/nats-on-kubernetes/nats-external-nlb.md +++ b/nats-on-kubernetes/nats-external-nlb.md @@ -1,14 +1,10 @@ -# Using a load balancer for external access to NATS on K8S +# Using a Load Balancer for External Access to NATS -Although it is not recommended in general to use a load balancer -with NATS for external access, sometimes due to policy it might -help to use one. If that is the case, then one option would be -to use an L4 load balancer that has raw tcp support. +Although it is not recommended in general to use a load balancer with NATS for external access, sometimes due to policy it might help to use one. If that is the case, then one option would be to use an L4 load balancer that has raw tcp support. -In the example below, you can find how to use an [AWS Network Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/introduction.html) -to connect externally to a cluster that has TLS setup. +In the example below, you can find how to use an [AWS Network Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/introduction.html) to connect externally to a cluster that has TLS setup. -```sh +```bash # One-line installer creates a secure cluster named 'nats' $ curl -sSL https://nats-io.github.io/k8s/setup.sh | sh @@ -42,5 +38,5 @@ nats-nlb LoadBalancer 10.100.67.123 a18b60a948fc611eaa7840286c60df32-9e96a $ nats-pub -s nats://a18b60a948fc611eaa7840286c60df32-9e96a2af4b5675ec.elb.us-east-2.amazonaws.com:4222 -creds nsc/nkeys/creds/KO/A/test.creds test.foo bar ``` -Also, it would be recommended to disable [no_advertise](../nats-server/configuration/clustering/cluster_config.md) -to avoid gossiping internal addresses from pods in Kubernetes to NATS clients. +Also, it would be recommended to disable [no\_advertise](../nats-server/configuration/clustering/cluster_config.md) to avoid gossiping internal addresses from pods in Kubernetes to NATS clients. + diff --git a/nats-on-kubernetes/super-cluster-on-digital-ocean.md b/nats-on-kubernetes/super-cluster-on-digital-ocean.md index f3a147a..08d0457 100644 --- a/nats-on-kubernetes/super-cluster-on-digital-ocean.md +++ b/nats-on-kubernetes/super-cluster-on-digital-ocean.md @@ -1,9 +1,8 @@ # Creating a NATS Super Cluster in Digital Ocean with Helm -Let's create a super cluster using NATS Gateways. First let's create -3 different clusters in NYC, Amsterdam, and San Francisco: +Let's create a super cluster using NATS Gateways. First let's create 3 different clusters in NYC, Amsterdam, and San Francisco: -```sh +```bash doctl kubernetes cluster create nats-k8s-nyc1 --count 3 --region nyc1 doctl kubernetes cluster create nats-k8s-sfo2 --count 3 --region sfo2 doctl kubernetes cluster create nats-k8s-ams3 --count 3 --region ams3 @@ -11,7 +10,7 @@ doctl kubernetes cluster create nats-k8s-ams3 --count 3 --region ams3 Next, open up the firewall across the 3 regions to be able to access the client, leafnode and gateways ports: -```sh +```bash for firewall in `doctl compute firewall list | tail -n 3 | awk '{print $1}'`; do doctl compute firewall add-rules $firewall --inbound-rules protocol:tcp,ports:4222,address:0.0.0.0/0 doctl compute firewall add-rules $firewall --inbound-rules protocol:tcp,ports:7422,address:0.0.0.0/0 @@ -19,12 +18,9 @@ for firewall in `doctl compute firewall list | tail -n 3 | awk '{print $1}'`; do done ``` -For this setup, we will create a super cluster using the external IPs -from the nodes of the 3 clusters. For a production type of setup, it -is recommended to use a DNS entry and an A record for each one of the -servers. +For this setup, we will create a super cluster using the external IPs from the nodes of the 3 clusters. For a production type of setup, it is recommended to use a DNS entry and an A record for each one of the servers. -```sh +```bash for ctx in do-ams3-nats-k8s-ams3 do-nyc1-nats-k8s-nyc1 do-sfo2-nats-k8s-sfo2; do echo "name: $ctx" for externalIP in `kubectl get nodes -o jsonpath='{.items[*].status.addresses[?(@.type=="ExternalIP")].address}'`; do @@ -78,7 +74,7 @@ natsbox: Let's deploy the super cluster with Helm using the name of cluster as the name of the gateway: -```sh +```bash for ctx in do-ams3-nats-k8s-ams3 do-nyc1-nats-k8s-nyc1 do-sfo2-nats-k8s-sfo2; do helm --kube-context $ctx install nats nats/nats -f super-cluster.yaml --set gateway.name=$ctx done @@ -86,7 +82,7 @@ done That's it! It should now be possible to send some messages across regions: -```sh +```bash # Start subscription in Amsterdam nats-box:~# kubectl --context do-ams3-nats-k8s-ams3 exec -it nats-box -- /bin/sh -l nats-box:~# nats-sub -s nats hello diff --git a/nats-protocol/nats-protocol/nats-client-dev.md b/nats-protocol/nats-protocol/nats-client-dev.md index 365cc03..c9c4142 100644 --- a/nats-protocol/nats-protocol/nats-client-dev.md +++ b/nats-protocol/nats-protocol/nats-client-dev.md @@ -62,7 +62,7 @@ NATS implements auto-pruning. When a client connects to the server, the server e ## Parsing the protocol -NATS provides a text-based message format. The text-based [protocol](README.md) makes it easy to implement NATS clients. The key consideration is deciding on a parsing strategy. +NATS provides a text-based message format. The text-based [protocol](./) makes it easy to implement NATS clients. The key consideration is deciding on a parsing strategy. The NATS server implements a [zero allocation byte parser](https://youtu.be/ylRKac5kSOk?t=10m46s) that is fast and efficient. Off the wire, a NATS message is simply a slice of bytes. Across the wire the message is transported as an immutable string over a TCP connection. It is up to the client to implement logic to parse the message. diff --git a/nats-server/configuration/README.md b/nats-server/configuration/README.md index e229f06..a0a64f0 100644 --- a/nats-server/configuration/README.md +++ b/nats-server/configuration/README.md @@ -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()`](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()`](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 ``, value is the ``. 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 `:`for server monitoring. | | | [`https_port`](monitoring.md) | https port for server monitoring. This is influenced by the tls property. | | | [`https`](monitoring.md) | Listen specification `:`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 | diff --git a/nats-server/configuration/clustering/cluster_config.md b/nats-server/configuration/clustering/cluster_config.md index ea2aa3f..1f8c0e9 100644 --- a/nats-server/configuration/clustering/cluster_config.md +++ b/nats-server/configuration/clustering/cluster_config.md @@ -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 { diff --git a/nats-server/configuration/gateways/gateway.md b/nats-server/configuration/gateways/gateway.md index 2ef6162..eed5a1e 100644 --- a/nats-server/configuration/gateways/gateway.md +++ b/nats-server/configuration/gateways/gateway.md @@ -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 `:` | -| `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 `:` 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 diff --git a/nats-server/configuration/monitoring.md b/nats-server/configuration/monitoring.md index cbf4c20..0416bad 100644 --- a/nats-server/configuration/monitoring.md +++ b/nats-server/configuration/monitoring.md @@ -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 diff --git a/nats-server/configuration/securing_nats/accounts.md b/nats-server/configuration/securing_nats/accounts.md index 2be7153..5b2576d 100644 --- a/nats-server/configuration/securing_nats/accounts.md +++ b/nats-server/configuration/securing_nats/accounts.md @@ -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. + diff --git a/nats-server/configuration/securing_nats/jwt/resolver.md b/nats-server/configuration/securing_nats/jwt/resolver.md index 792433f..f733a34 100644 --- a/nats-server/configuration/securing_nats/jwt/resolver.md +++ b/nats-server/configuration/securing_nats/jwt/resolver.md @@ -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/) diff --git a/nats-server/configuration/securing_nats/tls.md b/nats-server/configuration/securing_nats/tls.md index a6b8ab3..f30798c 100644 --- a/nats-server/configuration/securing_nats/tls.md +++ b/nats-server/configuration/securing_nats/tls.md @@ -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. diff --git a/nats-server/configuration/sys_accounts/README.md b/nats-server/configuration/sys_accounts/README.md index bb2f29b..d23f099 100644 --- a/nats-server/configuration/sys_accounts/README.md +++ b/nats-server/configuration/sys_accounts/README.md @@ -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.` \(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: diff --git a/nats-server/nats_admin/README.md b/nats-server/nats_admin/README.md index 77adf01..4fc1a05 100644 --- a/nats-server/nats_admin/README.md +++ b/nats-server/nats_admin/README.md @@ -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/) diff --git a/nats-server/nats_docker/ngs-docker-python.md b/nats-server/nats_docker/ngs-docker-python.md index 410497b..ae405f5 100644 --- a/nats-server/nats_docker/ngs-docker-python.md +++ b/nats-server/nats_docker/ngs-docker-python.md @@ -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 ``` + diff --git a/nats-streaming-concepts/clustering/supported-stores.md b/nats-streaming-concepts/clustering/supported-stores.md index 0841aac..03b05ae 100644 --- a/nats-streaming-concepts/clustering/supported-stores.md +++ b/nats-streaming-concepts/clustering/supported-stores.md @@ -7,5 +7,7 @@ The NATS Streaming Server stores server meta information and messages to the sto However, in clustered mode, we use RAFT for leader election. The raft layer uses its own stores which are currently necessarily file based. The location of the RAFT stores defaults to the current directory under a sub-directory named after the cluster ID, or you can configure it using `--cluster_log_path`. **Important if using a SQL Store:** -- There is still a need for storing RAFT data on the file system. -- Each node in the cluster needs to have its own "database", that is, no two nodes should share the same tables. + +* There is still a need for storing RAFT data on the file system. +* Each node in the cluster needs to have its own "database", that is, no two nodes should share the same tables. + diff --git a/nats-streaming-server/configuring/persistence/file_store.md b/nats-streaming-server/configuring/persistence/file_store.md index a03bafa..62e2440 100644 --- a/nats-streaming-server/configuring/persistence/file_store.md +++ b/nats-streaming-server/configuring/persistence/file_store.md @@ -33,7 +33,7 @@ Regardless of channel limits, you can configure message logs to be split in indi When messages accumulate in a channel, and limits are reached, older messages are removed. When the first file slice becomes empty, the server removes this file slice \(and corresponding index file\). However, if you specify a script \(`--file_slice_archive_script`\), then the server will rename the slice files \(data and index\) with a `.bak` extension and invoke the script with the channel name, data and index file names. - The files are left in the channel's directory and therefore it is the script responsibility to delete those files when done. At any rate, those files will not be recovered on a server restart, but having lots of unused files in the directory may slow down the server restart. +The files are left in the channel's directory and therefore it is the script responsibility to delete those files when done. At any rate, those files will not be recovered on a server restart, but having lots of unused files in the directory may slow down the server restart. For instance, suppose the server is about to delete file slice `datastore/foo/msgs.1.dat` \(and `datastore/foo/msgs.1.idx`\), and you have configured the script `/home/nats-streaming/archive_script.sh`. The server will invoke: @@ -56,7 +56,7 @@ Since dataloss is likely to occur, the default behavior for the server on startu With the `-file_truncate_bad_eof` parameter, the server will still print those bad records but truncate each file at the position of the first corrupted record in order to successfully start. To prevent the use of this parameter as the default value, this option is not available in the configuration file. Moreover, the server will fail to start if started more than once with that parameter. - This flag may help recover from a store failure, but since data may be lost in that process, we think that the operator needs to be aware and make an informed decision. +This flag may help recover from a store failure, but since data may be lost in that process, we think that the operator needs to be aware and make an informed decision. Note that this flag will not help with file corruption due to bad CRC for instance. You have the option to disable CRC on recovery with the `-file_crc=false` option. diff --git a/nats-tools/nas/notifications.md b/nats-tools/nas/notifications.md index a83a367..3f3ba4e 100644 --- a/nats-tools/nas/notifications.md +++ b/nats-tools/nas/notifications.md @@ -2,7 +2,7 @@ The `nats-account-server` can notify a nats-server about [JWT](../../nats-server/configuration/securing_nats/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/configuration/sys_accounts/README.md). +To push notifications, the nats-account-server makes use of [system accounts](../../nats-server/configuration/sys_accounts/). Here's a nats-account-server configuration with updates enabled: diff --git a/nats-tools/nsc/services.md b/nats-tools/nsc/services.md index 2b69291..1c77ea5 100644 --- a/nats-tools/nsc/services.md +++ b/nats-tools/nsc/services.md @@ -172,7 +172,7 @@ If you want to create a service that is only accessible to accounts you designat As before, we declared an export, but this time we added the `--private` flag. The other thing to note is that the subject for the request has a wildcard. This enables the account to map specific subjects to specifically authorized accounts. -```text +```bash > nsc describe account A ╭──────────────────────────────────────────────────────────────────────────────────────╮ │ Account Details │ diff --git a/whats_new.md b/whats_new.md index 369c1ef..f891b0f 100644 --- a/whats_new.md +++ b/whats_new.md @@ -11,7 +11,7 @@ Monitoring endpoints as listed in the table below are accessible as system servi * `$SYS.REQ.SERVER..` \(request server monitoring endpoint corresponding to endpoint name.\) * `$SYS.REQ.SERVER.PING.` \(from all server request server monitoring endpoint corresponding to endpoint name - will return multiple messages\) -For more information on monitoring endpoints see [NATS Server Configurations System Events](nats-server/configuration/sys_accounts#available-events-and-services). +For more information on monitoring endpoints see [NATS Server Configurations System Events](nats-server/configuration/sys_accounts/#available-events-and-services). ### Addition of `no_auth_user` Configuration @@ -20,10 +20,10 @@ Configuration of `no_auth_user` allows you to refer to a configured user/account For more information and example, see [Securing NATS](nats-server/configuration/securing_nats/accounts.md#no-auth-user) For full release information, see links below; + * Release notes [2.1.7](https://github.com/nats-io/nats-server/releases/tag/v2.1.7) * Full list of Changes [2.1.6...2.1.7](https://github.com/nats-io/nats-server/compare/v2.1.6...v2.1.7) - ## Server release v2.1.6 ### TLS Configuration for Account Resolver