From 602700010d311cd466983735e647e36d10458723 Mon Sep 17 00:00:00 2001 From: ainsley Date: Thu, 30 May 2019 12:38:58 -0500 Subject: [PATCH] proof reading commits --- developer/README.md | 2 +- developer/concepts/intro.md | 2 +- developer/connecting/cluster.md | 2 +- developer/receiving/drain.md | 2 +- developer/reconnect/intro.md | 2 +- developer/security/nkey.md | 2 +- developer/security/tls.md | 2 +- developer/security/token.md | 2 +- developer/tutorials/pubsub.md | 50 ++++++++++++++++---------------- developer/tutorials/queues.md | 18 ++++++------ developer/tutorials/reqreply.md | 10 +++---- leafnodes/README.md | 2 +- leafnodes/leafnode_conf.md | 2 ++ nats_admin/slow_consumers.md | 4 +-- nats_admin/upgrading_cluster.md | 4 +-- nats_docker/README.md | 2 +- nats_docker/docker_swarm.md | 1 + nats_docker/tutorial.md | 4 +-- nats_protocol/nats-client-dev.md | 18 ++++++------ nats_server/accounts.md | 6 ++-- nats_server/auth_intro.md | 4 +-- nats_server/clients.md | 2 +- nats_server/configuration.md | 2 +- nats_server/flags.md | 2 +- nats_server/installation.md | 8 ++--- nats_server/logging.md | 4 +-- nats_server/monitoring.md | 8 ++--- nats_server/nkey_auth.md | 2 -- nats_server/running.md | 2 +- nats_server/securing_nats.md | 4 +-- nats_server/tls_mutual_auth.md | 4 +-- nats_server/tokens.md | 4 +-- nats_server/username_password.md | 8 ++--- nats_server/windows_srv.md | 2 +- whats_new/whats_new_20.md | 6 ++-- 35 files changed, 100 insertions(+), 99 deletions(-) diff --git a/developer/README.md b/developer/README.md index 00b779e..0e9f3e5 100644 --- a/developer/README.md +++ b/developer/README.md @@ -1,6 +1,6 @@ # Developing with NATS -Developing with NATS is a combination of distributed application techniques, common NATS features and library specific syntax. As well as using this book for guidance, some of the libraries contain language-familiar formats of their API. For example, the go library has go doc, and the Java library has javadoc. +Developing with NATS is a combination of distributed application techniques, common NATS features and library specific syntax. As well as using this book for guidance, some of the libraries contain language-familiar formats of their API. For example, the Go library has godoc, and the Java library has javadoc. | Library | Doc Link | | ------------- | ------------- | diff --git a/developer/concepts/intro.md b/developer/concepts/intro.md index 963a8ff..b386fda 100644 --- a/developer/concepts/intro.md +++ b/developer/concepts/intro.md @@ -19,4 +19,4 @@ graph nats { } -NATS core offers an **at most once** quality of service. If a subscriber is not listening on the subject (no subject match), or is not active when the message is sent, the message is not received. This is the same level of guarantee that TCP/IP provides. By default, NATS is a fire-and-forget messaging system. If you need higher levels of service, you can either use NATS Streaming, or build the additional reliability into your client(s) yourself. +NATS core offers an **at most once** quality of service. If a subscriber is not listening on the subject (no subject match), or is not active when the message is sent, the message is not received. This is the same level of guarantee that TCP/IP provides. By default, NATS is a fire-and-forget messaging system. If you need higher levels of service, you can either use [NATS Streaming](/docs/nats_streaming/intro.md), or build the additional reliability into your client(s) yourself. diff --git a/developer/connecting/cluster.md b/developer/connecting/cluster.md index 914d041..4adf482 100644 --- a/developer/connecting/cluster.md +++ b/developer/connecting/cluster.md @@ -7,7 +7,7 @@ When connecting to a cluster, there are a few things to think about. * The reconnect algorithm (discussed later) * Server provided URLs -When a client library first tries to connect it will use the list of URLS provided to the connection options or function. These URLS are checked, usually in order, and the first successful connection is used. +When a client library first tries to connect it will use the list of URLs provided to the connection options or function. These URLs are checked, usually in order, and the first successful connection is used. After a client connects to the server, the server may provide a list of URLs for additional known servers. This allows a client to connect to one server and still have other servers available during reconnect. diff --git a/developer/receiving/drain.md b/developer/receiving/drain.md index c9c75d5..fe85446 100644 --- a/developer/receiving/drain.md +++ b/developer/receiving/drain.md @@ -1,6 +1,6 @@ # Draining Connections and Subscriptions -A new feature being added across the NATS client libraries is the ability to drain connections or subscriptions. Closing a connection, or unsubscribing from a subscription are generally considered immediate requests. When you close or unsubscribe the library will halt messages in any pending queue or cache for subscribers. When you drain a subscription or connection, it will process any cached/pending messages before closing. +A feature recently added across the NATS client libraries is the ability to drain connections or subscriptions. Closing a connection, or unsubscribing from a subscription are generally considered immediate requests. When you close or unsubscribe the library will halt messages in any pending queue or cache for subscribers. When you drain a subscription or connection, it will process any cached/pending messages before closing. Drain provides clients that use queue subscriptions with a way to bring down applications without losing any messages. A client can bring up a new queue member, drain and shut down the old queue member, all without losing messages sent to the old client. Without drain, there is the possibility of lost messages due to queue timing. diff --git a/developer/reconnect/intro.md b/developer/reconnect/intro.md index 8f3f730..f352d27 100644 --- a/developer/reconnect/intro.md +++ b/developer/reconnect/intro.md @@ -6,4 +6,4 @@ In general, the client will try to connect to all of the servers it knows about, The list of servers used during reconnect is library dependent, but generally is constructed from the list of servers passed to the connect function/options and the list of servers provided by the most recent connected server. -One, sometimes important, detail is that the server URLS provided to clients by servers will use addresses, while the URLS provided to the connect function will usually be host names. As a result, it is possible, on reconnect, for the same server to be tried multiple times without the client knowing about the match. \ No newline at end of file +One, sometimes important, detail is that the server URLs provided to clients by servers will use addresses, while the URLs provided to the connect function will usually be host names. As a result, it is possible, on reconnect, for the same server to be tried multiple times without the client knowing about the match. \ No newline at end of file diff --git a/developer/security/nkey.md b/developer/security/nkey.md index 5391f1a..0aeaf8d 100644 --- a/developer/security/nkey.md +++ b/developer/security/nkey.md @@ -1,6 +1,6 @@ # Authenticating with an NKey -The 2.0 version of NATS server introduces a new challenge response authentication option. This challenge response is based on a wrapper we call NKeys which uses ED25519 signing. The server can use these keys in several ways for authentication. The simplest is for the server to be configured with a list of known public keys and for the clients to respond to the challenge by signing it with its private key. This challenge-response insures security by insuring that the client has the private key, but also protects the private key from the server which never has to actually see it. +The 2.0 version of NATS server introduces a new challenge response authentication option. This challenge response is based on a wrapper we call NKeys which uses [Ed25519](https://ed25519.cr.yp.to/) signing. The server can use these keys in several ways for authentication. The simplest is for the server to be configured with a list of known public keys and for the clients to respond to the challenge by signing it with its private key. This challenge-response insures security by insuring that the client has the private key, but also protects the private key from the server which never has to actually see it. Handling challenge response may require more than just a setting in the connection options, depending on the client library. diff --git a/developer/security/tls.md b/developer/security/tls.md index cd44917..4159e3d 100644 --- a/developer/security/tls.md +++ b/developer/security/tls.md @@ -1,6 +1,6 @@ # Encrypting Connections with TLS -While authentication limits which clients can connect, TLS can be used to check the server’s identity and the client’s identity and will encrypt the traffic between the two. The most secure version of TLS with NATS is to use verified client certificates. In this mode, the client can check that it trusts the certificate sent by `nats-server` but the server will also check that it trusts the certificate sent by the client. From an applications perspective connecting to a server that does not verify client certificates may appear identical. Under the covers, disabling TLS verification removes the server side check on the client’s certificate. When started in TLS mode, `nats-server` will require all clients to connect with TLS. Moreover, if configured to connect with TLS, client libraries will fail to connect to a server without TLS. +While authentication limits which clients can connect, TLS can be used to check the server’s identity and the client’s identity and will encrypt the traffic between the two. The most secure version of TLS with NATS is to use verified client certificates. In this mode, the client can check that it trusts the certificate sent by `nats-server` but the server will also check that it trusts the certificate sent by the client. From an application's perspective connecting to a server that does not verify client certificates may appear identical. Under the covers, disabling TLS verification removes the server side check on the client’s certificate. When started in TLS mode, `nats-server` will require all clients to connect with TLS. Moreover, if configured to connect with TLS, client libraries will fail to connect to a server without TLS. The [Java examples repository](https://github.com/nats-io/java-nats-examples/tree/master/src/main/resources) contains certificates for starting the server in TLS mode. diff --git a/developer/security/token.md b/developer/security/token.md index f1b02d7..fc6acc7 100644 --- a/developer/security/token.md +++ b/developer/security/token.md @@ -6,7 +6,7 @@ Tokens are basically random strings, much like a password, and can provide a sim For this example, start the server using: ```sh -> gnatsd --auth mytoken +> nats-server --auth mytoken ``` The code uses localhost:4222 so that you can start the server on your machine to try them out. diff --git a/developer/tutorials/pubsub.md b/developer/tutorials/pubsub.md index b055746..ac93847 100644 --- a/developer/tutorials/pubsub.md +++ b/developer/tutorials/pubsub.md @@ -15,7 +15,7 @@ digraph nats_pub_sub { pub1 sub1 non_active } - nats-server [shape="box", label="NATS", width=8]; + gnatsd [shape="box", label="NATS", width=8]; sub2 [shape="box", label="SUB\ncom.msg.one"]; sub3 [shape="box", label="SUB\ncom.msg.two"]; @@ -26,13 +26,13 @@ digraph nats_pub_sub { sub2 sub3 sub4 } - pub1 -> nats-server [penwidth=2]; - nats-server -> sub1 [penwidth=2]; - nats-server -> non_active [style=dashed color=red arrowhead="none"]; + pub1 -> gnatsd [penwidth=2]; + gnatsd -> sub1 [penwidth=2]; + gnatsd -> non_active [style=dashed color=red arrowhead="none"]; - nats-server -> sub2 [penwidth=2]; - nats-server -> sub3 [style=dashed color=red arrowhead="none"]; - nats-server -> sub4 [penwidth=2]; + gnatsd -> sub2 [penwidth=2]; + gnatsd -> sub3 [style=dashed color=red arrowhead="none"]; + gnatsd -> sub4 [penwidth=2]; } @@ -40,7 +40,7 @@ digraph nats_pub_sub { Go and the NATS server should be installed. -## 1. Start the NATS server +### 1. Start the NATS server ```sh % nats-server @@ -56,17 +56,17 @@ When the server starts successfully, you will see the following messages: The NATS server listens for client connections on TCP Port 4222. -## 2. Start a shell or command prompt session +### 2. Start a shell or command prompt session You will use this session to run an example NATS client subscriber program. -## 3. CD to the Go client examples directory +### 3. CD to the Go client examples directory ```sh % cd $GOPATH/src/github.com/nats-io/nats/examples ``` -## 4. Run the client subscriber program +### 4. Run the client subscriber program ```sh % go run nats-sub.go @@ -82,7 +82,7 @@ For example: You should see the message: *Listening on [msg.test]* -## 5. Start another shell or command prompt session +### 5. Start another shell or command prompt session You will use this session to run a NATS publisher client. @@ -92,7 +92,7 @@ You will use this session to run a NATS publisher client. % cd $GOPATH/src/github.com/nats-io/nats/examples ``` -## 7. Publish a NATS message +### 7. Publish a NATS message ```sh % go run nats-pub.go @@ -112,7 +112,7 @@ or % go run nats-pub.go msg.test "NATS MESSAGE" ``` -## 8. Verify message publication and receipt +### 8. Verify message publication and receipt You should see that the publisher sends the message: *Published [msg.test] : 'NATS MESSAGE'* @@ -120,7 +120,7 @@ And that the subscriber receives the message: *[#1] Received on [msg.test]: 'NAT Note that if the receiver does not get the message, check that you are using the same subject name for the publisher and the subscriber. -## 9. Publish another message +### 9. Publish another message ```sh % go run nats-pub.go msg.test "NATS MESSAGE 2" @@ -128,23 +128,23 @@ Note that if the receiver does not get the message, check that you are using the You should see that the subscriber receive message 2. Note that the message count is incremented each time your subscribing client receives a message on that subject: -## 10. Start another shell or command prompt session +### 10. Start another shell or command prompt session You will use this session to run a second NATS subscriber. -## 11. CD to the examples directory +### 11. CD to the examples directory ```sh % cd $GOPATH/src/github.com/nats-io/nats/examples ``` -## 12. Subscribe to the message +### 12. Subscribe to the message ```sh % go run nats-sub.go msg.test ``` -## 13. Publish another message using the publisher client +### 13. Publish another message using the publisher client ```sh % go run nats-pub.go msg.test "NATS MESSAGE 3" @@ -152,17 +152,17 @@ You will use this session to run a second NATS subscriber. Verify that both subscribing clients receive the message. -## 14. Start another shell or command prompt session +### 14. Start another shell or command prompt session You will use this session to run a third NATS subscriber. -## 15. CD to the examples directory +### 15. CD to the examples directory ```sh % cd $GOPATH/src/github.com/nats-io/nats/examples ``` -## 16. Subscribe to a different message +### 16. Subscribe to a different message ```sh % go run nats-sub.go msg.test.new @@ -170,9 +170,9 @@ You will use this session to run a third NATS subscriber. All the but last subscriber receives the message. Why? Because that subscriber is not listening on the message subject used by the publisher. -## 17. Update the last subscriber to use a wildcard +### 17. Update the last subscriber to use a wildcard -NATS supports the use of wildcard characters for message subscribers. (You cannot publish a message using a wildcard subject.) +NATS supports the use of wildcard characters for message subscribers. You cannot publish a message using a wildcard subject. Change the last subscriber the listen on msg.* and run it: @@ -180,6 +180,6 @@ Change the last subscriber the listen on msg.* and run it: % go run nats-sub.go msg.* ``` -## 18. Publish another message +### 18. Publish another message This time, all three subscribing clients should receive the message. diff --git a/developer/tutorials/queues.md b/developer/tutorials/queues.md index b3de4e7..d996f12 100644 --- a/developer/tutorials/queues.md +++ b/developer/tutorials/queues.md @@ -6,13 +6,13 @@ NATS supports a form of load balancing using queue groups. Subscribers register Go and the NATS server should be installed. -## 1. Start the NATS server +### 1. Start the NATS server ```sh nats-server ``` -## 2. Clone the repositories for each client examples +### 2. Clone the repositories for each client examples ```sh go get github.com/nats-io/go-nats @@ -20,14 +20,14 @@ git clone https://github.com/nats-io/node-nats.git git clone https://github.com/nats-io/ruby-nats.git ``` -## 3. Run the Go client subscriber with queue group name +### 3. Run the Go client subscriber with queue group name ```sh cd $GOPATH/src/github.com/nats-io/go-nats/examples go run nats-qsub.go foo my-queue ``` -## 4. Install and run the Node client subscriber with queue group name +### 4. Install and run the Node client subscriber with queue group name ```sh npm install nats @@ -35,34 +35,34 @@ cd node-nats/examples node node-sub foo my-queue ``` -## 5. Install and run the Ruby client subscriber with queue group name +### 5. Install and run the Ruby client subscriber with queue group name ```sh gem install nats nats-queue foo my-queue & ``` -**6. Run another Go client subscriber *without* the queue group. +### 6. Run another Go client subscriber *without* the queue group. ```sh cd $GOPATH/src/github.com/nats-io/go-nats/examples go run nats-sub.go foo ``` -## 7. Publish a NATS message using the Go client +### 7. Publish a NATS message using the Go client ```sh cd $GOPATH/src/github.com/nats-io/go-nats/examples go run nats-pub.go foo "Hello NATS!" ``` -## 8. Verify message publication and receipt +### 8. Verify message publication and receipt You should see that the publisher sends the message: *Published [foo] : 'Hello NATS!'* You should see that only one of the my-queue group subscribers receives the message. In addition, the Go client subscriber not in the my-queue group should also receive the message. -## 9. Publish another message +### 9. Publish another message ```sh go run nats-pub.go foo "Hello NATS Again!" diff --git a/developer/tutorials/reqreply.md b/developer/tutorials/reqreply.md index c2c8a97..30760c7 100644 --- a/developer/tutorials/reqreply.md +++ b/developer/tutorials/reqreply.md @@ -6,23 +6,23 @@ NATS supports request/reply messaging. In this tutorial you explore how to excha Go and the NATS server should be installed. -## 1. Start the NATS server +### 1. Start the NATS server ```sh % nats-server ``` -## 2. Start two terminal sessions +### 2. Start two terminal sessions You will use these sessions to run the NATS request and reply clients. -## 3. Change to the examples directory +### 3. Change to the examples directory ```sh % cd $GOPATH/src/github.com/nats-io/nats/examples ``` -## 4. In one terminal, run the reply client listener +### 4. In one terminal, run the reply client listener ```sh % go run nats-rply.go foo "this is my response" @@ -30,7 +30,7 @@ You will use these sessions to run the NATS request and reply clients. You should see the message `Receiver is listening`, and that the NATS receiver client is listening on the "help.please" subject. The reply client acts as a receiver, listening for message requests. In NATS, the receiver is a subscriber. -## 5. In the other terminal, run the request client +### 5. In the other terminal, run the request client ```sh % go run nats-req.go foo "request payload" diff --git a/leafnodes/README.md b/leafnodes/README.md index ab9292c..93037d6 100644 --- a/leafnodes/README.md +++ b/leafnodes/README.md @@ -11,7 +11,7 @@ This effectively means that the leaf node clusters with the other server at an a - Subjects that the user is allowed to publish are exported to the cluster. - Subjects the user is allowed to subscribe to, are imported into the leaf node. -> Leaf Nodes are an important component as a way to bridge traffic between local nNATS Servers you control and servers that are managed by a third-party. Synadia's [NATS Global Service (NGS)](https://www.synadia.com/) allows accounts to use leaf nodes, but gain accessibility to the global network to inexpensively connect geographically distributed servers or small clusters. +> Leaf Nodes are an important component as a way to bridge traffic between local NATS servers you control and servers that are managed by a third-party. Synadia's [NATS Global Service (NGS)](https://www.synadia.com/) allows accounts to use leaf nodes, but gain accessibility to the global network to inexpensively connect geographically distributed servers or small clusters. [LeafNode Configuration Options](leafnode_conf.md) diff --git a/leafnodes/leafnode_conf.md b/leafnodes/leafnode_conf.md index b79e74c..a2ad64b 100644 --- a/leafnodes/leafnode_conf.md +++ b/leafnodes/leafnode_conf.md @@ -35,3 +35,5 @@ | `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. | | `timeout` | TLS handshake timeout in fractional seconds. | + + diff --git a/nats_admin/slow_consumers.md b/nats_admin/slow_consumers.md index 81c0a0e..096a9e3 100644 --- a/nats_admin/slow_consumers.md +++ b/nats_admin/slow_consumers.md @@ -18,7 +18,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](/documentation/writing_applications/advanced#slow-consumers) 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](/developer/events/slow.md) 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) { @@ -64,7 +64,7 @@ The server will also keep count of the number of slow consumer errors encountere ## Handling slow consumers -Apart from using [NATS streaming](http://nats.io/doc/streaming/nats-streaming-intro/) or optimizing your consuming application, there are a few options available: scale, meter, or tune NATS to your environment. +Apart from using [NATS streaming](nats_streaming/intro.md/) or optimizing your consuming application, there are a few options available: scale, meter, or tune NATS to your environment. __Scaling with queue subscribers__ diff --git a/nats_admin/upgrading_cluster.md b/nats_admin/upgrading_cluster.md index fe5298a..112da96 100644 --- a/nats_admin/upgrading_cluster.md +++ b/nats_admin/upgrading_cluster.md @@ -15,7 +15,7 @@ nats-server -D -p 4222 -cluster nats://localhost:6222 -routes nats://localhost:6 The command above is starting nats-server with debug output enabled, listening for clients on port 4222, and accepting cluster connections on port 6222. The `-routes` option specifies a list of nats URLs where the server will attempt to connect to other servers. These URLs define the cluster ports enabled on the cluster peers. -Keen readers will notice a self-route. Gnatsd will ignore the self-route, but it makes for a single consistent configuration for all servers. +Keen readers will notice a self-route. The NATS server will ignore the self-route, but it makes for a single consistent configuration for all servers. You will see the server started, we notice it emits some warnings because it cannot connect to 'localhost:6333'. The message more accurately reads: @@ -36,7 +36,7 @@ nats-sub -s nats://localhost:4222 ">" Nats-sub is a subscriber sample included with all NATS clients. Nats-sub subscribes to a subject and prints out any messages received. You can find the source code to the go version of nats-sub [here)(https://github.com/nats-io/go-nats/tree/master/examples). After starting the subscriber you should see a message on 'A' that a new client connected. -We have two servers and a client. Time to simulate our rolling upgrade. But wait, before we upgrade 'A,' let's introduce a new server 'T.' Server 'T' will join the existing cluster while we perform the upgrade. Its sole purpose is to provide an additional place where clients can go besides 'A.' and ensure we don't end up with a single server serving all the clients after the upgrade procedure. Clients will randomly select a server when connecting unless a special option is provided that disables that functionality (usually called 'DontRandomize' or 'noRandomize'). You can read more about ["Avoiding the Thundering Herd"](https://www.nats.io/documentation/writing_applications/connecting/). +We have two servers and a client. Time to simulate our rolling upgrade. But wait, before we upgrade 'A,' let's introduce a new server 'T.' Server 'T' will join the existing cluster while we perform the upgrade. Its sole purpose is to provide an additional place where clients can go besides 'A.' and ensure we don't end up with a single server serving all the clients after the upgrade procedure. Clients will randomly select a server when connecting unless a special option is provided that disables that functionality (usually called 'DontRandomize' or 'noRandomize'). You can read more about ["Avoiding the Thundering Herd"](/developer/reconnect/random.md/). Suffice it to say that clients redistribute themselves about evenly between all servers in the cluster. In our case 1/2 of the clients on 'A' will jump over to 'B' and the remaining half to 'T.' Let's start our temporary server: diff --git a/nats_docker/README.md b/nats_docker/README.md index ef1e071..af1e084 100644 --- a/nats_docker/README.md +++ b/nats_docker/README.md @@ -3,7 +3,7 @@ The NATS server is provided as a Docker image on [Docker Hub](https://hub.docker.com/_/nats/) that you can run using the Docker daemon. The NATS server Docker image is extremely lightweight, coming in under 10 MB in size. -Synadia actively maintains and supports the NATS server Docker image. +[Synadia](https://synadia.com) actively maintains and supports the NATS server Docker image. ### Usage diff --git a/nats_docker/docker_swarm.md b/nats_docker/docker_swarm.md index cceeff9..5b3fdda 100644 --- a/nats_docker/docker_swarm.md +++ b/nats_docker/docker_swarm.md @@ -1,3 +1,4 @@ +## Docker Swarm #### Step 1: Create an overlay network for the cluster (in this example, `nats-cluster-example`), and instantiate an initial NATS server. diff --git a/nats_docker/tutorial.md b/nats_docker/tutorial.md index 974fdaa..a1f2bfc 100644 --- a/nats_docker/tutorial.md +++ b/nats_docker/tutorial.md @@ -1,6 +1,6 @@ ## NATS Docker Tutorial -In this tutorial you run the [NATS server Docker image](https://hub.docker.com/_/nats/). The Docker image provides an instance of the [NATS Server](/README.md). Synadia actively maintains and supports the gnatsd Docker image. The NATS image is only 6 MB in size. +In this tutorial you run the [NATS server Docker image](https://hub.docker.com/_/nats/). The Docker image provides an instance of the [NATS Server](/README.md). Synadia actively maintains and supports the nats-server Docker image. The NATS image is only 6 MB in size. **1. Set up Docker.** @@ -8,7 +8,7 @@ See [Get Started with Docker](http://docs.docker.com/mac/started/) for guidance. The easiest way to run Docker is to use the [Docker Toolbox](http://docs.docker.com/mac/step_one/). -**2. Run the gnatsd Docker image.** +**2. Run the nats-server Docker image.** ```sh > docker run -p 4222:4222 -p 8222:8222 -p 6222:6222 --name gnatsd -ti nats:latest diff --git a/nats_protocol/nats-client-dev.md b/nats_protocol/nats-client-dev.md index b1bddfe..4a91579 100644 --- a/nats_protocol/nats-client-dev.md +++ b/nats_protocol/nats-client-dev.md @@ -16,15 +16,15 @@ This guide provides you with considerations for developing NATS clients, includi Probably the best way to learn about implementing a client is to look at one of the client's maintained by the Synadia team. These clients are generally full featured, so if you can use them, that is even better, but if you have to write a client these may go beyond your needs while still capturing many of the design considerations discussed here. -- [go](https://github.com/nats-io/go-nats) -- [node](https://github.com/nats-io/node-nats) -- [typescript](https://github.com/nats-io/ts-nats) -- [python2](https://github.com/nats-io/python-nats) -- [python asyncio](https://github.com/nats-io/asyncio-nats) -- [java](https://github.com/nats-io/java-nats) -- [c#](https://github.com/nats-io/csharp-nats) -- [ruby](https://github.com/nats-io/ruby-nats) -- [c](https://github.com/nats-io/cnats) +- [go](https://github.com/nats-io/nats.go) +- [node](https://github.com/nats-io/nats.js) +- [typescript](https://github.com/nats-io/nats.ts) +- [python2](https://github.com/nats-io/nats.py2) +- [python asyncio](https://github.com/nats-io/nats.py) +- [java](https://github.com/nats-io/nats.java) +- [c#](https://github.com/nats-io/nats.net) +- [ruby](https://github.com/nats-io/nats.rb) +- [c](https://github.com/nats-io/nats.c) ## Client connection options diff --git a/nats_server/accounts.md b/nats_server/accounts.md index c6d634f..a7512c7 100644 --- a/nats_server/accounts.md +++ b/nats_server/accounts.md @@ -43,7 +43,7 @@ accounts: { > While the name _account_ implies one or more users, it is much simpler and enlightening to think of one account as a messaging container for one application. Users in the account are simply the minimum number of services that must work together to provide some functionality. > In simpler terms, more accounts with few (even one) clients is a better design topology than a large account with many users with complex authorization configuration. -## Exporting and Importing +### Exporting and Importing Messaging exchange between different accounts is enabled by _exporting_ streams and services from one account and _importing_ them into another. Each account controls what is exported and imported. @@ -59,7 +59,7 @@ Services are messages your application can consume and act on, enabling other ac -## Export Configuration Map +### Export Configuration Map The export configuration map binds a subject for use as a `service` or `stream` and optionally defines specific accounts that can import the stream or service. Here are the supported configuration properties: @@ -105,7 +105,7 @@ The _source configuration map_ describes an export from a remote account by spec | `subject` | The subject under which the stream or service is made accessible to the importing account | -## Import Configuration Map +### Import Configuration Map An import enables an account to consume streams published by another account or make requests to services implemented by another account. All imports require a corresponding export on the exporting account. Accounts cannot do self-imports. diff --git a/nats_server/auth_intro.md b/nats_server/auth_intro.md index 48734a7..2f23515 100644 --- a/nats_server/auth_intro.md +++ b/nats_server/auth_intro.md @@ -21,13 +21,13 @@ The `authorization` block provides _authentication_ configuration as well as _au | [`token`](tokens.md) | Specifies a global token that can be used to authenticate to the server (exclusive of user and password) | | [`user`](username_password.md) | Specifies a single _global_ user name for clients to the server (exclusive of token) | | [`password`](username_password.md) | Specifies a single _global_ password for clients to the server (exclusive of `token`) | -| `users` | A list of `user` configuration maps | +| `users` | A list of user configuration maps | | `timeout` | Maximum number of seconds to wait for client authentication | For multiple username and password credentials, specify a `users` list. -### User Configuration Map +## User Configuration Map A `user` configuration map specifies credentials and permissions options for a single user: diff --git a/nats_server/clients.md b/nats_server/clients.md index 24953d3..bd8b406 100644 --- a/nats_server/clients.md +++ b/nats_server/clients.md @@ -1,4 +1,4 @@ -## NATS Clients +# NATS 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. diff --git a/nats_server/configuration.md b/nats_server/configuration.md index 8db2f44..bb273d8 100644 --- a/nats_server/configuration.md +++ b/nats_server/configuration.md @@ -1,4 +1,4 @@ -## Configuration File Format +# Configuration File Format While the NATS server has many flags that allow for simple testing of features, the NATS server products provide a flexible configuration format that combines the best of traditional formats and newer styles such as JSON and YAML. diff --git a/nats_server/flags.md b/nats_server/flags.md index 8ef7cf3..2f095e0 100644 --- a/nats_server/flags.md +++ b/nats_server/flags.md @@ -1,4 +1,4 @@ -## Flags +# Flags The NATS server has many flags to customize its behavior without having to write a configuration file. diff --git a/nats_server/installation.md b/nats_server/installation.md index 12a38d5..08473ce 100644 --- a/nats_server/installation.md +++ b/nats_server/installation.md @@ -1,4 +1,4 @@ -## NATS Server Installation +# NATS Server Installation NATS philosophy is simplicity. Installation is just decompressing a zip file and copying the binary to an appropriate directory; you can also use your favorite package manager. Here's a list of different ways you can install or run NATS: @@ -11,7 +11,7 @@ NATS philosophy is simplicity. Installation is just decompressing a zip file and ### Installing via Docker -With docker you can install the server easily without scattering binaries and other artifacts on your system. The only pre-requisite is to [install docker](https://docs.docker.com/install). +With Docker you can install the server easily without scattering binaries and other artifacts on your system. The only pre-requisite is to [install docker](https://docs.docker.com/install). ``` > docker pull nats:latest @@ -65,7 +65,7 @@ To test your installation (provided the executable is visible to your shell): [41634] 2019/05/13 09:42:11.746252 [INF] Server is ready ``` -### Downloading A Release Build +### Downloading a Release Build You can find the latest release of nats-server [here](https://github.com/nats-io/nats-server/releases/latest). @@ -85,7 +85,7 @@ Archive: nats-server.zip ``` -### Installing from the source +### Installing From the Source If you have Go installed, installing the binary is easy: diff --git a/nats_server/logging.md b/nats_server/logging.md index 6961911..85779b5 100644 --- a/nats_server/logging.md +++ b/nats_server/logging.md @@ -64,7 +64,7 @@ logtime: false log_file: "/tmp/nats-server.log" ``` -## Log Rotation with logrotate +### Log Rotation with logrotate NATS server does not provide tools to manage log files, but it does include mechanisms that make log rotation simple. We can use this mechanism with [logrotate](https://github.com/logrotate/logrotate); a simple standard Linux utility to rotate logs available on most distributions like Debian, Ubuntu, RedHat (CentOS), etc. @@ -93,4 +93,4 @@ The `/var/run/nats-server.pid` file is where NATS server stores the master proce ## Some Logging Notes -- The NATS Server, in verbose mode, will log the receipt of `UNSUB` messages, but this does not indicate the subscription is gone, only that the message was received. The `DELSUB` message in the log can be used to determine when the actual subscription removal has taken place. \ No newline at end of file +- The NATS server, in verbose mode, will log the receipt of `UNSUB` messages, but this does not indicate the subscription is gone, only that the message was received. The `DELSUB` message in the log can be used to determine when the actual subscription removal has taken place. \ No newline at end of file diff --git a/nats_server/monitoring.md b/nats_server/monitoring.md index a229cd8..72c702e 100644 --- a/nats_server/monitoring.md +++ b/nats_server/monitoring.md @@ -1,6 +1,6 @@ ## Monitoring -To monitor the NATS messaging system, `gnatsd` provides a lightweight HTTP server on a dedicated monitoring port. The monitoring server provides several endpoints, including [varz](#/varz), [connz](#/connz), [routez](#/routez), and [subsz](#/subz). All endpoints return a JSON object. +To monitor the NATS messaging system, `nats-server` provides a lightweight HTTP server on a dedicated monitoring port. The monitoring server provides several endpoints, including [varz](#/varz), [connz](#/connz), [routez](#/routez), and [subsz](#/subz). All endpoints return a JSON object. The NATS monitoring endpoints support JSONP and CORS, making it easy to create single page monitoring web applications. @@ -14,14 +14,14 @@ To enable the monitoring server, start the NATS server with the monitoring flag Example: ```sh -$ gnatsd -m 8222 +$ nats-server -m 8222 [4528] 2015/08/19 20:09:58.572939 [INF] Starting gnatsd version 0.8.0 [4528] 2015/08/19 20:09:58.573007 [INF] Starting http monitor on port 8222 [4528] 2015/08/19 20:09:58.573071 [INF] Listening for client connections on 0.0.0.0:4222 [4528] 2015/08/19 20:09:58.573090 [INF] gnatsd is ready ``` -To test, run `gnatsd -m 8222`, then go to http://localhost:8222/ +To test, run `nats-server -m 8222`, then go to http://localhost:8222/ ## Monitoring endpoints @@ -182,4 +182,4 @@ $.getJSON('http://localhost:8222/connz?callback=?', function(data) { ## Monitoring Tools -In addition to writing custom monitoring tools, you can nats-server into Prometheus. The [Prometheus NATS Exporter](https://github.com/nats-io/prometheus-nats-exporter) allows you to configure the metrics you want to observe and store in Prometheous. There's a sample [Graphana](https://graphana.com) dashboard that you can use to visualize the server metrics. \ No newline at end of file +In addition to writing custom monitoring tools, you can nats-server into Prometheus. The [Prometheus NATS Exporter](https://github.com/nats-io/prometheus-nats-exporter) allows you to configure the metrics you want to observe and store in Prometheous. There's a sample [Grafana](https://grafana.com) dashboard that you can use to visualize the server metrics. \ No newline at end of file diff --git a/nats_server/nkey_auth.md b/nats_server/nkey_auth.md index c55d8d2..127687a 100644 --- a/nats_server/nkey_auth.md +++ b/nats_server/nkey_auth.md @@ -67,6 +67,4 @@ Other NATS tooling such as `nats-pub` and `nats-sub` can directly use nkeys: nats-sub -nkey /path/to/file/storing/seed ">" ``` -For examples using other supported clients, please visit -our [documentation portal](https://nats.io/documentation/writing_applications/secure_connection) diff --git a/nats_server/running.md b/nats_server/running.md index af24df5..e4345dc 100644 --- a/nats_server/running.md +++ b/nats_server/running.md @@ -1,4 +1,4 @@ -## Running +# Running The nats-server has many command line options. To get started, you don't have to specify anything. In the absence of any flags, the NATS server will start listening for NATS client connections on port 4222. diff --git a/nats_server/securing_nats.md b/nats_server/securing_nats.md index 2df578c..c1753b8 100644 --- a/nats_server/securing_nats.md +++ b/nats_server/securing_nats.md @@ -1,6 +1,6 @@ -# Securing NATS +## Securing NATS -The nats-server provides several forms of security: +The NATS server provides several forms of security: - Connections can be [_encrypted_ with TLS](tls.md) - Client connections can require [_authentication_](auth_intro.md) diff --git a/nats_server/tls_mutual_auth.md b/nats_server/tls_mutual_auth.md index ca7240b..5ab3898 100644 --- a/nats_server/tls_mutual_auth.md +++ b/nats_server/tls_mutual_auth.md @@ -26,7 +26,7 @@ Or via the command line: This option verifies the client's certificate is signed by the CA specified in the `ca_file` option. -## Mapping Client Certificates To A User +### Mapping Client Certificates To A User In addition to verifying that a specified CA issued a client certificate, you can use information encoded in the certificate to authenticate a client. The client wouldn't have to provide or track usernames or passwords. @@ -91,6 +91,6 @@ authorization { } ``` -## TLS Timeout +### TLS Timeout [TLS timeout](/nats_server/tls.md#tls-timeout) is described here. \ No newline at end of file diff --git a/nats_server/tokens.md b/nats_server/tokens.md index 922e08d..77b230c 100644 --- a/nats_server/tokens.md +++ b/nats_server/tokens.md @@ -1,4 +1,4 @@ -# Token Authentication +## Token Authentication Token authentication is a string that if provided by a client, allows it to connect. It is the most straightforward authentication provided by the NATS server. @@ -22,7 +22,7 @@ A client can easily connect by specifying the server URL: Listening on [>] ``` -## Bcrypted Tokens +### Bcrypted Tokens Tokens can be bcrypted enabling an additional layer of security, as the clear-text version of the token would not be persisted on the server configuration file. diff --git a/nats_server/username_password.md b/nats_server/username_password.md index 4aac16b..a9fd0cd 100644 --- a/nats_server/username_password.md +++ b/nats_server/username_password.md @@ -1,6 +1,6 @@ -# Username and Password +## Username and Password -You can authenticate one or more clients using username and passwords; this enables you to have greater control over the management and issuing of credential secrets. +You can authenticate one or more clients using username and passwords; this enables you to have greater control over the management and issuance of credential secrets. For a single user: ``` @@ -26,7 +26,7 @@ authorization: { } ``` -## Bcrypted Passwords +### Bcrypted Passwords Username/password also supports bcrypted passwords using the [`mkpasswd`](/nats_tools/mkpasswd.md) tool. Simply replace the clear text password with the bcrypted entries: @@ -46,7 +46,7 @@ authorization: { } ``` -## Reloading a Configuration +### Reloading a Configuration As you add/remove passwords from the server configuration file, you'll want your changes to take effect. To reload without restarting the server and disconnecting clients, do: diff --git a/nats_server/windows_srv.md b/nats_server/windows_srv.md index 7b91195..a6dd5b6 100644 --- a/nats_server/windows_srv.md +++ b/nats_server/windows_srv.md @@ -1,4 +1,4 @@ -### Windows Service +## Windows Service The NATS server supports running as a Windows service. In fact, this is the recommended way of running NATS on Windows. There is currently no installer; users should use `sc.exe` to install the service: diff --git a/whats_new/whats_new_20.md b/whats_new/whats_new_20.md index 80ff054..c4e4248 100644 --- a/whats_new/whats_new_20.md +++ b/whats_new/whats_new_20.md @@ -119,7 +119,7 @@ monitoring and anomaly detection tools. NATS 2.0 supports global deployments, allowing for global topologies that optimize for WANs while extend to the edge or devices. -### Self healing +### Self Healing While self healing features have been part of NATS 1.X releases, we ensured they continue to work in global deployments. These include: @@ -136,7 +136,7 @@ for seamless rolling upgrades and scaling up or down. Conceptually, superclusters are clusters of NATS clusters. Create superclusters to deploy a truly global NATS network. Superclusters use -a novel spline based technology with a unique apporoach to topology, keeping +a novel spline based technology with a unique approach to topology, keeping one hop semantics and optimizing WAN traffic through optimistic sends with interest graph pruning. Superclusters provide transparent, intelligent support for geo-distributed queue subscribers. @@ -166,7 +166,7 @@ This is __zero configuration disaster recovery__. ### Leaf Nodes -Leaf nodes are a NATS servers running in a special configuration, allowing +Leaf nodes are NATS servers running in a special configuration, allowing hub and spoke topologies to extend superclusters. Leaf nodes can also bridge separate security domains. e.g. IoT, mobile, web.