diff --git a/assets/images/intro.svg b/assets/images/intro.svg deleted file mode 100644 index 19a2ced..0000000 --- a/assets/images/intro.svg +++ /dev/null @@ -1,58 +0,0 @@ - - - - - - -nats - - - -publisher - -Application 1 - -NATS Publisher - - - -natsserver - - - - -publisher:nats--natsserver - - - - -application - -Application 3 - - - - - -application:nats--natsserver - - - - -subscriber - -NATS Subscriber - -Application 2 - - - -natsserver--subscriber:nats - - - - - diff --git a/assets/images/pubsubtut.svg b/assets/images/pubsubtut.svg deleted file mode 100644 index a0d442c..0000000 --- a/assets/images/pubsubtut.svg +++ /dev/null @@ -1,95 +0,0 @@ - - - - - - -nats_pub_sub - - - -sub1 - -SUB -com.msg.one - - - -pub1 - -PUB -com.msg.one - - - -natsserver - -NATS - - - -pub1->natsserver - - - - - -non_active - -Non-Active -Subscriber - - - -natsserver->sub1 - - - - - -natsserver->non_active - - - - -sub2 - -SUB -com.msg.one - - - -natsserver->sub2 - - - - - -sub3 - -SUB -com.msg.two - - - -natsserver->sub3 - - - - -sub4 - -SUB -com.msg.* - - - -natsserver->sub4 - - - - - diff --git a/assets/images/queue.svg b/assets/images/queue.svg deleted file mode 100644 index 62652b3..0000000 --- a/assets/images/queue.svg +++ /dev/null @@ -1,71 +0,0 @@ - - - - - - -nats_queues - - - -publisher - -Publisher - - - -subject - -Queue - - - -publisher->subject - - -msgs 1,2,3 - - - -sub1 - -Subscriber - - - -subject->sub1 - - -msg 2 - - - -sub2 - -Subscriber - - - -subject->sub2 - - -msg 1 - - - -sub3 - -Subscriber - - - -subject->sub3 - - -msg 3 - - - diff --git a/assets/images/reqrepl.svg b/assets/images/reqrepl.svg deleted file mode 100644 index dc10798..0000000 --- a/assets/images/reqrepl.svg +++ /dev/null @@ -1,91 +0,0 @@ - - - - - - -nats_request_reply - - - -publisher - -Publisher - - - -subject - -Subject - - - -publisher->subject - - -msg1 - - - -reply - -Reply - - - - -sub1 - -Subscriber - - - -subject->sub1 - - -msg1 - - - -sub2 - -Subscriber - - - -subject->sub2 - - -msg1 - - - -sub3 - -Subscriber - - - -subject->sub3 - - -msg1 - - - -reply->publisher - - - - - - -sub3->reply - - - - - diff --git a/assets/images/seqno.svg b/assets/images/seqno.svg deleted file mode 100644 index 81e8a44..0000000 --- a/assets/images/seqno.svg +++ /dev/null @@ -1,59 +0,0 @@ - - - - - - -nats_pub_sub - - - -publisher - -Publisher - - - -subject - -Subject - - - -publisher->subject - - -updates.1 - - - -publisher->subject - - -updates.2 - - - -publisher->subject - - -updates.3 - - - -sub - -Subscriber - - - -subject->sub - - -updates.* - - - diff --git a/assets/images/subjects1.svg b/assets/images/subjects1.svg deleted file mode 100644 index dc7b877..0000000 --- a/assets/images/subjects1.svg +++ /dev/null @@ -1,58 +0,0 @@ - - - - - - -g - - - -publisher - -PUB time.us - - - -subject - -nats-server - - - -publisher->subject - - -msg - - - -sub1 - -SUB time.us - - - -subject->sub1 - - -msg - - - -sub2 - -SUB time.us - - - -subject->sub2 - - -msg - - - diff --git a/assets/images/subjects2.svg b/assets/images/subjects2.svg deleted file mode 100644 index b70adb2..0000000 --- a/assets/images/subjects2.svg +++ /dev/null @@ -1,58 +0,0 @@ - - - - - - -g - - - -publisher - -PUB time.us.east - - - -subject - -nats-server - - - -publisher->subject - - -msg - - - -sub1 - -SUB time.*.east - - - -subject->sub1 - - -msg - - - -sub2 - -SUB time.us.east - - - -subject->sub2 - - -msg - - - diff --git a/assets/images/subjects3.svg b/assets/images/subjects3.svg deleted file mode 100644 index e73c731..0000000 --- a/assets/images/subjects3.svg +++ /dev/null @@ -1,65 +0,0 @@ - - - - - - -g - - - -publisher - -PUB time.us.east.atlanta - - - -subject - -nats-server - - - -publisher->subject - - -msg - - - -sub1 - -SUB time.us.east.atlanta - - - -subject->sub1 - - -msg - - - -sub2 - -SUB time.us.* - - - - -sub3 - -SUB time.us.> - - - -subject->sub3 - - -msg - - - diff --git a/developing-with-nats-streaming/protocol.md b/developing-with-nats-streaming/protocol.md index 98606e2..c6794c8 100644 --- a/developing-with-nats-streaming/protocol.md +++ b/developing-with-nats-streaming/protocol.md @@ -186,7 +186,7 @@ The `MsgProto` message is received by client from the NATS Streaming Server, con * `sequence`: Globally ordered sequence number for the subject's channel * `subject`: Subject * `data`: Payload -* `timestamp`: Time the message was stored in the server. Represented as Unix time (number of nanoseconds elapsed since January 1, 1970 UTC) +* `timestamp`: Time the message was stored in the server. Represented as Unix time \(number of nanoseconds elapsed since January 1, 1970 UTC\) * `redelivered`: Flag specifying if the message is being redelivered [Back to table](protocol.md#protocols) diff --git a/gateways/simple.svg b/gateways/simple.svg deleted file mode 100644 index 1fade1e..0000000 --- a/gateways/simple.svg +++ /dev/null @@ -1,76 +0,0 @@ - - - - - - - - - - - - - - - - Produced by OmniGraffle 7.10.2 - 2019-05-07 16:42:18 +0000 - - - Canvas 1 - - - Layer 1 - - - - - A1 - - - - - - - A2 - - - - - - - A3 - - - - - - - B1 - - - - - - - B2 - - - - - - - - - - - - - - - - - - - - diff --git a/gateways/three_gw.svg b/gateways/three_gw.svg deleted file mode 100644 index 1fa78b4..0000000 --- a/gateways/three_gw.svg +++ /dev/null @@ -1,109 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - Produced by OmniGraffle 7.10.2 - 2019-05-07 16:43:34 +0000 - - - Canvas 1 - - - Layer 1 - - - - - A1 - - - - - - - A2 - - - - - - - A3 - - - - - - - B1 - - - - - - - B2 - - - - - - - - - - - - - - - - - - - - - - C1 - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/nats-on-kubernetes/stan-ft-k8s-aws.md b/nats-on-kubernetes/stan-ft-k8s-aws.md index cb45ca8..3142343 100644 --- a/nats-on-kubernetes/stan-ft-k8s-aws.md +++ b/nats-on-kubernetes/stan-ft-k8s-aws.md @@ -1,6 +1,8 @@ -# NATS Streaming Cluster with FT Mode on AWS +# NATS Streaming Cluster with FT Mode -## Preparation +## NATS Streaming Cluster with FT Mode on AWS + +### Preparation First, we need a Kubernetes cluster with a provider that offers a service with a `ReadWriteMany` filesystem available. In this short guide, we will create the cluster on AWS and then use EFS for the filesystem: @@ -21,7 +23,7 @@ For the FT mode to work, we will need to create an EFS volume which can be share ![Screen Shot 2019-12-04 at 12 40 13 PM](https://user-images.githubusercontent.com/26195/70179769-9497a500-16d6-11ea-9e18-2a8588a71819.png) -### Creating the EFS provisioner +#### Creating the EFS provisioner Confirm from the FilesystemID from the cluster and the DNS name, we will use those values to create an EFS provisioner controller within the K8S cluster: @@ -181,7 +183,7 @@ storageclass.storage.k8s.io/aws-efs created persistentvolumeclaim/efs created ``` -### Setting up the NATS Streaming cluster +#### Setting up the NATS Streaming cluster Now create a NATS Streaming cluster with FT mode enabled and using NATS embedded mode that is mounting the EFS volume: @@ -382,9 +384,9 @@ $ kubectl logs stan-0 -c stan [1] 2019/12/04 20:40:41.671546 [INF] STREAM: Streaming Server is ready ``` -# NATS Streaming Cluster with FT Mode on Azure +## NATS Streaming Cluster with FT Mode on Azure -First need to create a PVC (PersistentVolumeClaim), in Azure we can use azurefile to get a volume with `ReadWriteMany`: +First need to create a PVC \(PersistentVolumeClaim\), in Azure we can use azurefile to get a volume with `ReadWriteMany`: ```yaml --- @@ -434,16 +436,15 @@ store: claimName: stan-efs ``` - Now deploy with Helm: -```sh -helm install stan nats/stan -f ./examples/deploy-stan-ft-file.yaml +```bash +helm install stan nats/stan -f ./examples/deploy-stan-ft-file.yaml ``` Send a few commands to the NATS Server to which STAN/NATS Streaming is connected: -```sh +```bash kubectl port-forward nats-0 4222:4222 & stan-pub -c stan foo bar.1 @@ -453,6 +454,7 @@ stan-pub -c stan foo bar.3 Subscribe to get all the messages: -```sh -stan-sub -c stan -all foo +```bash +stan-sub -c stan -all foo ``` + diff --git a/nats-server/configuration/gateways/gateway.md b/nats-server/configuration/gateways/gateway.md index e507205..ba3c7fb 100644 --- a/nats-server/configuration/gateways/gateway.md +++ b/nats-server/configuration/gateways/gateway.md @@ -101,16 +101,7 @@ gateway { ### TLS Entry -In addition to the normal TLS configuration advice, bear in mind that -TLS keys and certificates for multiple clusters, or servers in different -locations, rarely rotate at the exact same time and that Certificate -Authorities do roll between multiple Intermediate certificates. +In addition to the normal TLS configuration advice, bear in mind that TLS keys and certificates for multiple clusters, or servers in different locations, rarely rotate at the exact same time and that Certificate Authorities do roll between multiple Intermediate certificates. + +If using a certificate bundle which accompanied the issuance of a certificate then the CA in that bundle will typically be for just that certificate. Using _only_ that CA as the CA for gateway authentication is ill-advised. You should ensure that you allow for rolling between Certificate Authorities, even if only between multiple CAs from the same organization entity, and use a separate certificate bundle for _verification_ of peers. This way when DC-B rolls before DC-A, it will not be cut off from your supercluster. -If using a certificate bundle which accompanied the issuance of a certificate -then the CA in that bundle will typically be for just that certificate. -Using _only_ that CA as the CA for gateway authentication is ill-advised. -You should ensure that you allow for rolling between Certificate Authorities, -even if only between multiple CAs from the same organization entity, -and use a separate certificate bundle for _verification_ of peers. -This way when DC-B rolls before DC-A, it will not be cut off from your -supercluster. diff --git a/nats-server/configuration/securing_nats/tls.md b/nats-server/configuration/securing_nats/tls.md index 7ae105d..baa4cd3 100644 --- a/nats-server/configuration/securing_nats/tls.md +++ b/nats-server/configuration/securing_nats/tls.md @@ -13,7 +13,7 @@ The NATS server uses modern TLS semantics to encrypt client, route, and monitori | `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. | -| `verify_cert_and_check_known_urls` | Only settable in a non client context where `verify: true` is the default ([cluster](../clustering/)/[gateway](../gateways/)). The incoming connections certificate's `X509v3 Subject Alternative Name` `DNS` entries will be matched against all urls in the configuration context that contains this tls map. If a match is found, the connection is accepted and rejected otherwise. Meaning for gateways we will match all DNS entries in the certificate against all gateway urls. For cluster we will match against all route urls. As a consequence of this, dynamic cluster growth may require config changes in other cluster where this flag is true. DNS name checking is performed according to [rfc6125](https://tools.ietf.org/html/rfc6125#section-6.4.1). Only the full wildcard `*` is supported for the left most label. This would be one way to keep cluster growth flexible. | +| `verify_cert_and_check_known_urls` | Only settable in a non client context where `verify: true` is the default \([cluster](../clustering/)/[gateway](../gateways/)\). The incoming connections certificate's `X509v3 Subject Alternative Name` `DNS` entries will be matched against all urls in the configuration context that contains this tls map. If a match is found, the connection is accepted and rejected otherwise. Meaning for gateways we will match all DNS entries in the certificate against all gateway urls. For cluster we will match against all route urls. As a consequence of this, dynamic cluster growth may require config changes in other cluster where this flag is true. DNS name checking is performed according to [rfc6125](https://tools.ietf.org/html/rfc6125#section-6.4.1). Only the full wildcard `*` is supported for the left most label. This would be one way to keep cluster growth flexible. | The simplest configuration: @@ -62,21 +62,11 @@ tls: { ## Certificate Authorities -The `ca_file` file should contain one or more Certificate Authorities in PEM -format, in a bundle. This is a common format. +The `ca_file` file should contain one or more Certificate Authorities in PEM format, in a bundle. This is a common format. -When a certificate is issued, it is often accompanied by a copy of the -intermediate certificate used to issue it. This is useful for validating that -certificate. It is not necessarily a good choice as the only CA suitable for -use in verifying other certificates a server may see. +When a certificate is issued, it is often accompanied by a copy of the intermediate certificate used to issue it. This is useful for validating that certificate. It is not necessarily a good choice as the only CA suitable for use in verifying other certificates a server may see. -Do consider though that organizations issuing certificates will change the -intermediate they use. For instance, a CA might issue intermediates in pairs, -with an active and a standby, and reserve the right to switch to the standby -without notice. You probably would want to trust _both_ of those for the -`ca_file` directive, to be prepared for such a day, and then after the first -CA has been compromised you can remove it. This way the roll from one CA to -another will not break your NATS server deployment. +Do consider though that organizations issuing certificates will change the intermediate they use. For instance, a CA might issue intermediates in pairs, with an active and a standby, and reserve the right to switch to the standby without notice. You probably would want to trust _both_ of those for the `ca_file` directive, to be prepared for such a day, and then after the first CA has been compromised you can remove it. This way the roll from one CA to another will not break your NATS server deployment. ## Self Signed Certificates for Testing @@ -108,7 +98,7 @@ Please check your system's documentation on how to trust a particular self signe Another common problem is failed [identity validation](https://tools.ietf.org/html/rfc6125). The IP or DNS name to connect to needs to match a [Subject Alternative Name \(SAN\)](https://tools.ietf.org/html/rfc4985) inside the certificate. Meaning, if a client/browser/server connect via tls to `127.0.0.1`, the server needs to present a certificate with a SAN containing the IP `127.0.0.1` or the connection will be closed with a handshake error. -When `verify_cert_and_check_known_urls` is specified, [Subject Alternative Name \(SAN\)](https://tools.ietf.org/html/rfc4985) `DNS` records are necessary. In order to succesfully connect there must be an overlap between the `DNS` records provided as part of the certificate and the urls configured. If you dynaimcally grow your cluster and use a new certificate, this route or gateway the server connects to will have to be reconfigured to include a url for the new server. Only then can the new server connect. If the `DNS` record is a wildcard, matching according to [rfc6125](https://tools.ietf.org/html/rfc6125#section-6.4.1) will be performed. Using certificates with a wildcard [Subject Alternative Name \(SAN\)](https://tools.ietf.org/html/rfc4985) and configuration with url(s) that would match are a way to keep the flexibility of dynamic cluster growth without configuration changes in ohter cluster. +When `verify_cert_and_check_known_urls` is specified, [Subject Alternative Name \(SAN\)](https://tools.ietf.org/html/rfc4985) `DNS` records are necessary. In order to succesfully connect there must be an overlap between the `DNS` records provided as part of the certificate and the urls configured. If you dynaimcally grow your cluster and use a new certificate, this route or gateway the server connects to will have to be reconfigured to include a url for the new server. Only then can the new server connect. If the `DNS` record is a wildcard, matching according to [rfc6125](https://tools.ietf.org/html/rfc6125#section-6.4.1) will be performed. Using certificates with a wildcard [Subject Alternative Name \(SAN\)](https://tools.ietf.org/html/rfc4985) and configuration with url\(s\) that would match are a way to keep the flexibility of dynamic cluster growth without configuration changes in ohter cluster. #### Wrong Key Usage @@ -139,7 +129,7 @@ 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\)](tls.md#missing-subject-alternative-name) -To generate certificates that work with `verify` and [`cluster`](../clustering/README.md)/[`gateway`](../gateways/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`. +To generate certificates that work with `verify` and [`cluster`](../clustering/)/[`gateway`](../gateways/)/[`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 diff --git a/nats-server/nats_admin/slow_consumers.md b/nats-server/nats_admin/slow_consumers.md index c09b3e5..9fd64d9 100644 --- a/nats-server/nats_admin/slow_consumers.md +++ b/nats-server/nats_admin/slow_consumers.md @@ -16,7 +16,7 @@ When detected at the client, the application is notified and messages are droppe ## Slow consumers identified in the client -A [client can detect it is a slow consumer](../../developing-with-nats/events/slow) on a local connection and notify the application through use of the asynchronous error callback. It is better to catch a slow consumer locally in the client rather than to allow the server to detect this condition. This example demonstrates how to define and register an asynchronous error handler that will handle slow consumer errors. +A [client can detect it is a slow consumer ](../../developing-with-nats/events/slow.md#detect-a-slow-consumer-and-check-for-dropped-messages)on a local connection and notify the application through use of the asynchronous error callback. It is better to catch a slow consumer locally in the client rather than to allow the server to detect this condition. This example demonstrates how to define and register an asynchronous error handler that will handle slow consumer errors. ```go func natsErrHandler(nc *nats.Conn, sub *nats.Subscription, natsErr error) { diff --git a/nats-streaming-server/configuring/cfgfile.md b/nats-streaming-server/configuring/cfgfile.md index 61a9667..3fd8a04 100644 --- a/nats-streaming-server/configuring/cfgfile.md +++ b/nats-streaming-server/configuring/cfgfile.md @@ -77,12 +77,13 @@ In general the configuration parameters are the same as the command line argumen | username | Username is used to connect to a NATS Server when authentication with multiple users is enabled | String | `username: "streaming_server"` | N/A | | password | Password used with above `username` | String | `password: "password"` | N/A | | token | Authentication token if the NATS Server requires a token | String | `token: "some_token"` | N/A | -| nkey_seed_file | Path to an NKey seed file (1) if NKey authentication is used | File Path | `nkey_seed_file: "/path/to/some/seedfile"` | N/A | +| nkey\_seed\_file | Path to an NKey seed file \(1\) if NKey authentication is used | File Path | `nkey_seed_file: "/path/to/some/seedfile"` | N/A | Notes: -(1) The seed file contains the NKey seed from which the Streaming server can extract the public key and the private key used to sign the nonce sent by the NATS Server when accepting connections from the Streaming server. The file is read during the connection process, the key is used to sign but then wiped from memory. The file must contain the seed file with the following format: -``` +\(1\) The seed file contains the NKey seed from which the Streaming server can extract the public key and the private key used to sign the nonce sent by the NATS Server when accepting connections from the Streaming server. The file is read during the connection process, the key is used to sign but then wiped from memory. The file must contain the seed file with the following format: + +```text -----BEGIN USER NKEY SEED----- SU ------END USER NKEY SEED------