mirror of
https://github.com/taigrr/nats.docs
synced 2025-01-18 04:03:23 -08:00
proof reading commits
This commit is contained in:
ainsley
parent
d35e3cb277
commit
602700010d
@ -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 |
|
||||
| ------------- | ------------- |
|
||||
|
||||
@ -19,4 +19,4 @@ graph nats {
|
||||
}
|
||||
</code></div>
|
||||
|
||||
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.
|
||||
|
||||
@ -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.
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
|
||||
@ -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.
|
||||
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.
|
||||
@ -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.
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -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];
|
||||
}
|
||||
</code></div>
|
||||
|
||||
@ -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 <subject>
|
||||
@ -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 <subject> <message>
|
||||
@ -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.
|
||||
|
||||
@ -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!"
|
||||
|
||||
@ -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"
|
||||
|
||||
@ -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)
|
||||
|
||||
|
||||
@ -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. |
|
||||
|
||||
|
||||
|
||||
@ -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__
|
||||
|
||||
|
||||
@ -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:
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
|
||||
@ -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:
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
## Flags
|
||||
# Flags
|
||||
|
||||
|
||||
The NATS server has many flags to customize its behavior without having to write a configuration file.
|
||||
|
||||
@ -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:
|
||||
|
||||
|
||||
@ -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.
|
||||
- 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.
|
||||
@ -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</td>
|
||||
```
|
||||
|
||||
To test, run `gnatsd -m 8222`, then go to <a href="http://localhost:8222/" target="_blank">http://localhost:8222/</a>
|
||||
To test, run `nats-server -m 8222`, then go to <a href="http://localhost:8222/" target="_blank">http://localhost:8222/</a>
|
||||
|
||||
## 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.
|
||||
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.
|
||||
@ -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)
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -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)
|
||||
|
||||
@ -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.
|
||||
@ -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.
|
||||
|
||||
|
||||
@ -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:
|
||||
|
||||
|
||||
@ -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:
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user