mirror of
https://github.com/taigrr/nats.docs
synced 2025-01-18 04:03:23 -08:00
wip
This commit is contained in:
Alberto Ricart
parent
a9cf7544ff
commit
9a531682fd
25
SUMMARY.md
25
SUMMARY.md
@ -2,9 +2,8 @@
|
||||
|
||||
* [Introduction](README.md)
|
||||
|
||||
## Administering NATS
|
||||
|
||||
* [NATS Server](nats_server/README.md)
|
||||
## NATS Server
|
||||
* [Basics](nats_server/README.md)
|
||||
* [Installing](nats_server/installation.md)
|
||||
* [Running](nats_server/running.md)
|
||||
* [Window Service](nats_server/windows_srv.md)
|
||||
@ -18,21 +17,27 @@
|
||||
* [Logging](nats_server/logging.md)
|
||||
* [Monitoring](nats_server/monitoring.md)
|
||||
|
||||
## Managing NATS Server
|
||||
### Managing A NATS Server
|
||||
* [Upgrading a Cluster](nats_admin/upgrading_cluster.md)
|
||||
* [Slow Consumers](nats_admin/slow_consumers.md)
|
||||
* [Signals](nats_admin/signals.md)
|
||||
|
||||
|
||||
## Containerization
|
||||
* [NATS.docker](nats_docker/README.md)
|
||||
* [Tutorial](nats_docker/tutorial.md)
|
||||
|
||||
## NATS Tools
|
||||
### NATS Tools
|
||||
* [NATS Top](nats_tools/nats_top/README.md)
|
||||
* [Tutorial](nats_tools/nats_top/tutorial.md)
|
||||
* [Benchmarking](nats_tools/natsbench.md)
|
||||
|
||||
### NATS Containerization
|
||||
* [NATS.docker](nats_docker/README.md)
|
||||
* [Tutorial](nats_docker/tutorial.md)
|
||||
|
||||
## NATS Streaming Server
|
||||
* [Basics](nats_streaming/nats-streaming-intro.md)
|
||||
* [Installing](nats_streaming/nats-streaming-install.md)
|
||||
* [Securing](nats_streaming/nats-streaming-tls.md)
|
||||
* [Protocol](nats_streaming/nats-streaming-protocol.md)
|
||||
* [Docker Swarm](nats_streaming/nats-streaming-swarm.md)
|
||||
|
||||
## Developing With NATS
|
||||
|
||||
* [Concepts](developer/concepts/intro.md)
|
||||
|
||||
102
nats_streaming/nats-streaming-install.md
Normal file
102
nats_streaming/nats-streaming-install.md
Normal file
@ -0,0 +1,102 @@
|
||||
# Install and Run NATS Streaming Server
|
||||
|
||||
In this tutorial you install and run the NATS Streaming server (`nats-streaming-server`).
|
||||
You can follow this same procedure anytime you want to run the NATS Streaming server.
|
||||
|
||||
### Install the NATS Streaming server
|
||||
|
||||
There are numerous ways to install the NATS Streaming server.
|
||||
|
||||
#### GitHub releases
|
||||
|
||||
The latest official release binaries are always available on the [GitHub releases page](https://github.com/nats-io/nats-streaming-server/releases).
|
||||
The following platforms are available:
|
||||
|
||||
- Linux (x86, x86_64, ARM)
|
||||
- Windows (x86, x86_64)
|
||||
- macOS
|
||||
|
||||
The following methods may also be used. _Please note that these methods may not install the latest released version_:
|
||||
|
||||
#### Go
|
||||
|
||||
Make sure [your Go environment is set up](/documentation/tutorials/go-install/)
|
||||
|
||||
```sh
|
||||
% go get github.com/nats-io/nats-streaming-server
|
||||
```
|
||||
|
||||
Note that this method may not install the latest released version.
|
||||
|
||||
#### Docker Hub
|
||||
|
||||
The latest [official Docker image](https://hub.docker.com/_/nats-streaming/) is always available on Docker Hub.
|
||||
|
||||
#### Windows
|
||||
|
||||
On Windows, the NATS Streaming server can also be installed via [Chocolatey](https://chocolatey.org/packages/nats-streaming-server):
|
||||
|
||||
```sh
|
||||
% choco install nats-streaming-server
|
||||
```
|
||||
|
||||
#### macOS
|
||||
|
||||
On macOS, the NATS Streaming server can be installed via [Homebrew](http://brewformulas.org/NatsStreamingServer):
|
||||
|
||||
```sh
|
||||
% brew install nats-streaming-server
|
||||
```
|
||||
|
||||
### Start the NATS Streaming server
|
||||
|
||||
You can invoke the NATS Streaming server binary, with no options and no configuration file, to start a server with acceptable standalone defaults (no authentication, no clustering).
|
||||
|
||||
```sh
|
||||
% nats-streaming-server
|
||||
```
|
||||
|
||||
When the server starts successfully, you will see that the NATS Streaming server listens for client connections on TCP Port 4222:
|
||||
|
||||
```sh
|
||||
[18085] 2016/10/31 13:11:44.059012 [INF] Starting nats-streaming-server[test-cluster] version 0.3.1
|
||||
[18085] 2016/10/31 13:11:44.059830 [INF] Starting nats-server version 0.9.4
|
||||
[18085] 2016/10/31 13:11:44.061544 [INF] Listening for client connections on 0.0.0.0:4222
|
||||
[18085] 2016/10/31 13:11:44.061966 [INF] Server is ready
|
||||
[18085] 2016/10/31 13:11:44.396819 [INF] STAN: Message store is MEMORY
|
||||
[18085] 2016/10/31 13:11:44.396832 [INF] STAN: --------- Store Limits ---------
|
||||
[18085] 2016/10/31 13:11:44.396837 [INF] STAN: Channels: 100 *
|
||||
[18085] 2016/10/31 13:11:44.396839 [INF] STAN: -------- channels limits -------
|
||||
[18085] 2016/10/31 13:11:44.396842 [INF] STAN: Subscriptions: 1000 *
|
||||
[18085] 2016/10/31 13:11:44.396844 [INF] STAN: Messages : 1000000 *
|
||||
[18085] 2016/10/31 13:11:44.396855 [INF] STAN: Bytes : 976.56 MB *
|
||||
[18085] 2016/10/31 13:11:44.396858 [INF] STAN: Age : unlimited *
|
||||
[18085] 2016/10/31 13:11:44.396859 [INF] STAN: --------------------------------
|
||||
```
|
||||
|
||||
### Start the NATS Streaming Server with NATS monitoring enabled (optional)
|
||||
|
||||
The NATS Streaming server exposes the monitoring interface of its embedded NATS Server (`nats-server`) on port 8222.
|
||||
|
||||
```sh
|
||||
% nats-streaming-server -m 8222
|
||||
```
|
||||
|
||||
If you run the NATS Streaming server with monitoring enabled, you see the following messages:
|
||||
|
||||
```sh
|
||||
[18122] 2016/10/31 13:13:10.048663 [INF] Starting nats-streaming-server[test-cluster] version 0.3.1
|
||||
[18122] 2016/10/31 13:13:10.048843 [INF] Starting nats-server version 0.9.4
|
||||
[18122] 2016/10/31 13:13:10.048890 [INF] Starting http monitor on 0.0.0.0:8222
|
||||
[18122] 2016/10/31 13:13:10.048968 [INF] Listening for client connections on 0.0.0.0:4222
|
||||
[18122] 2016/10/31 13:13:10.048992 [INF] Server is ready
|
||||
[18122] 2016/10/31 13:13:10.388282 [INF] STAN: Message store is MEMORY
|
||||
[18122] 2016/10/31 13:13:10.388301 [INF] STAN: --------- Store Limits ---------
|
||||
[18122] 2016/10/31 13:13:10.388309 [INF] STAN: Channels: 100 *
|
||||
[18122] 2016/10/31 13:13:10.388312 [INF] STAN: -------- channels limits -------
|
||||
[18122] 2016/10/31 13:13:10.388316 [INF] STAN: Subscriptions: 1000 *
|
||||
[18122] 2016/10/31 13:13:10.388319 [INF] STAN: Messages : 1000000 *
|
||||
[18122] 2016/10/31 13:13:10.388333 [INF] STAN: Bytes : 976.56 MB *
|
||||
[18122] 2016/10/31 13:13:10.388338 [INF] STAN: Age : unlimited *
|
||||
[18122] 2016/10/31 13:13:10.388341 [INF] STAN: --------------------------------
|
||||
```
|
||||
61
nats_streaming/nats-streaming-intro.md
Normal file
61
nats_streaming/nats-streaming-intro.md
Normal file
@ -0,0 +1,61 @@
|
||||
# NATS Streaming Concepts
|
||||
|
||||
NATS Streaming is a data streaming system powered by NATS, and written in the Go programming language. The executable name for the NATS Streaming server is `nats-streaming-server`. NATS Streaming embeds, extends, and interoperates seamlessly with the core NATS platform. The [NATS Streaming server](https://github.com/nats-io/nats-streaming-server) is provided as open source software under the Apache-2.0 license. Synadia actively maintains and supports the NATS Streaming server.
|
||||
|
||||
<div class="graphviz"><code data-viz="dot">
|
||||
digraph nats_streaming {
|
||||
graph [splines=ortho, nodesep=1];
|
||||
|
||||
application [shape="record", label="{Application Code | NATS Streaming Client API | <nats> NATS Client API}"];
|
||||
|
||||
subgraph cluster_nats_streaming_server {
|
||||
label="NATS Streaming Server";
|
||||
labelloc=b;
|
||||
nats_server [shape=box, label="NATS Server"];
|
||||
streaming_module [shape=box, label="Streaming Module"];
|
||||
nats_server -> streaming_module [penwidth=2, dir="both"];
|
||||
|
||||
{
|
||||
rank=same
|
||||
nats_server streaming_module
|
||||
}
|
||||
}
|
||||
|
||||
storage [shape=box, style="rounded", label="storage"];
|
||||
|
||||
application:nats -> nats_server [penwidth=2, dir="both"];
|
||||
streaming_module -> storage [penwidth=2, dir="both"];
|
||||
}
|
||||
</code></div>
|
||||
|
||||
## Features
|
||||
|
||||
In addition to the features of the core NATS platform, NATS Streaming provides the following:
|
||||
|
||||
- **Enhanced message protocol** - NATS Streaming implements its own enhanced message format using [Google Protocol Buffers] (https://developers.google.com/protocol-buffers/). These messages are transmitted as binary message payloads via core NATS platform, and thus require no changes to the basic NATS protocol. NATS Streaming messages contain the following fields:
|
||||
- Sequence - a globally ordered sequence number for the subject's channel
|
||||
- Subject - The NATS Streaming delivery subject
|
||||
- Reply - The optional "reply-to" subject
|
||||
- Data - The message payload
|
||||
- Timestamp - the received timestamp, in nanoseconds.
|
||||
- Redelivered - A flag signifying whether this message has been redelivered by the server
|
||||
- CRC32 - An optional IEEE CRC32
|
||||
- **Message/event persistence** - NATS Streaming offers configurable message persistence either in-memory or via flat files. The storage subsystem uses a public interface that allows contributors to develop their own custom implementations.
|
||||
- **At-least-once-delivery** - NATS Streaming offers message acknowledgements between publisher and server (for publish operations) and between subscriber and server (to confirm message delivery). Messages are persisted by the server in memory or secondary storage (or other external storage) and will be redelivered to eligible subscribing clients as needed.
|
||||
- **Publisher rate limiting** - NATS Streaming provides a connection option called `MaxPubAcksInFlight` that effectively limits the number of unacknowledged messages that a publisher may have in-flight at any given time. When this maximum is reached, further async publish calls will block until the number of unacknowledged messages falls below the specified limit.
|
||||
- **Rate matching/limiting per subscriber** - Subscriptions may specify a `MaxInFlight` option that designates the maximum number of outstanding acknowledgements (messages that have been delivered but not acknowledged) that NATS Streaming will allow for a given subscription. When this limit is reached, NATS Streaming will suspend delivery of messages to this subscription until the number of unacknowledged messages falls below the specified limit.
|
||||
- **Historical message replay by subject** - New subscriptions may specify a start position in the stream of messages stored for the subscribed subject's channel. By using this option, message delivery may begin at:
|
||||
- The earliest message stored for this subject
|
||||
- The most recently stored message for this subject, prior to the start of the current subscription. This is commonly thought of as "last value" or "initial value" caching.
|
||||
- A specific date/time in nanoseconds
|
||||
- An historical offset from the current server date/time, e.g. the last 30 seconds.
|
||||
- A specific message sequence number
|
||||
- **Durable subscriptions** - Subscriptions may also specify a "durable name" which will survive client restarts. Durable subscriptions cause the server to track the last acknowledged message sequence number for a client and durable name. When the client restarts/resubscribes, and uses the same client ID and durable name, the server will resume delivery beginning with the earliest unacknowledged message for this durable subscription.
|
||||
|
||||
## Installation
|
||||
|
||||
NATS provides a [server binary](/documentation/streaming/nats-streaming-install/) for Linux, Mac, and Windows. You can install the server from source on any platform you choose.
|
||||
|
||||
## Usage, Configuration and Administration
|
||||
|
||||
NATS Streaming provides a rich set of commands and parameters to configure all aspects of the server. Please refer to the [README](https://github.com/nats-io/nats-streaming-server/) for further info on usage, configuration, and administration.
|
||||
190
nats_streaming/nats-streaming-protocol.md
Normal file
190
nats_streaming/nats-streaming-protocol.md
Normal file
@ -0,0 +1,190 @@
|
||||
# NATS Streaming Protocol
|
||||
|
||||
|
||||
The NATS streaming protocol sits atop the core [NATS protocol](/documentation/internals/nats-protocol) and uses [Google's Protocol Buffers](https://developers.google.com/protocol-buffers/). Protocol buffer messages are marshaled into bytes and published as NATS messages on specific subjects described below. In communicating with the NATS Streaming Server, the NATS [request/reply](/documentation/writing_applications/concepts) pattern is used for all protocol messages that have a corresponding reply.
|
||||
|
||||
## NATS streaming protocol conventions
|
||||
|
||||
**Subject names**: Subject names, including reply subject (INBOX) names, are case-sensitive and must be non-empty alphanumeric strings with no embedded whitespace, and optionally token-delimited using the dot character (`.`), e.g.:
|
||||
|
||||
`FOO`, `BAR`, `foo.bar`, `foo.BAR`, `FOO.BAR` and `FOO.BAR.BAZ` are all valid subject names
|
||||
|
||||
`FOO. BAR`, `foo. .bar` and`foo..bar` are *not- valid subject names
|
||||
|
||||
**Wildcards**: NATS streaming does **not*- support wildcards in subject subscriptions
|
||||
|
||||
**Protocol definition**: The fields of NATS streaming protocol messages are defined in the go-nats-streaming [protocol file](https://github.com/nats-io/go-nats-streaming/blob/master/pb/protocol.proto).
|
||||
|
||||
## NATS streaming protocol messages
|
||||
|
||||
The following table briefly describes the NATS streaming protocol messages.
|
||||
|
||||
Click the name to see more detailed information, including usage:
|
||||
|
||||
| Message Name | Sent By | Description
|
||||
| --------------------------------- |:--------|:--------------------------------------------
|
||||
| [`ConnectRequest`](#CONNREQ) | Client | Request to connect to the NATS Streaming Server
|
||||
| [`ConnectResponse`](#CONNRESP) | Server | Result of a connection request
|
||||
| [`SubscriptionRequest`](#SUBREQ) | Client | Request sent to subscribe and retrieve data
|
||||
| [`SubscriptionResponse`](#SUBRESP)| Server | Result of a subscription request
|
||||
| [`UnsubscribeRequest`](#UNSUBREQ) | Client | Unsubscribe from a subject
|
||||
| [`PubMsg`](#PUBMSG) | Client | Publish a message to a subject, with optional reply subject
|
||||
| [`PubAck`](#PUBACK) | Server | An acknowledgement that a published message has been processed on the server
|
||||
| [`MsgProto`](#MSGPROTO) | Server | A message from the NATS Streaming Server to a subscribing client
|
||||
| [`Ack`](#ACK) | Client | Acknowledges that a message has been received
|
||||
| [`CloseRequest`](#CLOSEREQ) | Client | Request sent to close the connection to the NATS Streaming Server
|
||||
| [`CloseResp`](#CLOSERESP) | Server | Result of the close request
|
||||
|
||||
The following sections explain each protocol message.
|
||||
|
||||
## <a name="CONNREQ"></a>ConnectRequest
|
||||
|
||||
#### Description
|
||||
|
||||
A connection request is sent when a streaming client connects to the NATS Streaming Server. The connection request contains a unique identifier representing the client, and an inbox subject the client will listen on for incoming heartbeats. The identifier **must*- be unique; a connection attempt with an identifier currently in use will fail. The inbox subject is the subject where the client receives incoming heartbeats, and responds by publishing an empty NATS message to the reply subject, indicating it is alive. The NATS Streaming Server will return a [ConnectResponse](#CONNRESP) message to the reply subject specified in the NATS request message.
|
||||
|
||||
This request is published to a subject comprised of the `<discover-prefix>.cluster-id`, for example, if a NATS Streaming Server was started with a cluster-id of `mycluster`, and the default prefix was used, the client publishes to `_STAN.discover.mycluster`
|
||||
|
||||
#### Message Structure
|
||||
|
||||
- `clientID`: A unique identifier for a client
|
||||
- `heartbeatInbox`: An inbox to which the NATS Streaming Server will send heartbeats for the client to process
|
||||
|
||||
## <a name="CONNRESP"></a>ConnectResponse
|
||||
|
||||
#### Description
|
||||
|
||||
After a `ConnectRequest` is published, the NATS Streaming Server responds with this message on the reply subject of the underlying NATS request. The NATS Streaming Server requires the client to make requests and publish messages on certain subjects (described above), and when a connection is successful, the client saves the information returned to be used in sending other NATS streaming protocol messages. In the event the connection was not successful, an error is returned in the `error` field.
|
||||
|
||||
#### Message Structure
|
||||
|
||||
- `pubPrefix`: Prefix to use when publishing
|
||||
- `subRequests`: Subject used for subscription requests
|
||||
- `unsubRequests`: Subject used for unsubscribe requests
|
||||
- `closeRequests`: Subject for closing a connection
|
||||
- `error`: An error string, which will be empty/omitted upon success
|
||||
- `publicKey`: Reserved for future use
|
||||
|
||||
## <a name="SUBREQ"></a>SubscriptionRequest
|
||||
|
||||
#### Description
|
||||
|
||||
A `SubscriptionRequest` is published on the subject returned in the `subRequests` field of a [`ConnectResponse`](#CONNRESP), and creates a subscription to a subject on the NATS Streaming Server. This will return a [SubscriptionResponse](#SUBRESP) message to the reply subject specified in the NATS protocol request message.
|
||||
|
||||
#### Message Structure
|
||||
|
||||
- `clientID`: Client ID originally provided in the [ConnectRequest](#CONNREQ)
|
||||
- `subject`: Formal subject to subscribe to, e.g. foo.bar
|
||||
- `qGroup`: Optional queue group
|
||||
- `inbox`: Inbox subject to deliver messages on
|
||||
- `maxInFlight`: Maximum inflight messages without an acknowledgement allowed
|
||||
- `ackWaitInSecs`: Timeout for receiving an acknowledgement from the client
|
||||
- `durableName`: Optional durable name which survives client restarts
|
||||
- `startPosition`: An enumerated type specifying the point in history to start replaying data
|
||||
- `startSequence`: Optional start sequence number
|
||||
- `startTimeDelta`: Optional start time
|
||||
|
||||
#### StartPosition enumeration
|
||||
|
||||
- `NewOnly`: Send only new messages
|
||||
- `LastReceived`: Send only the last received message
|
||||
- `TimeDeltaStart`: Send messages from duration specified in the `startTimeDelta` field.
|
||||
- `SequenceStart`: Send messages starting from the sequence in the `startSequence` field.
|
||||
- `First`: Send all available messages
|
||||
|
||||
## <a name="SUBRESP"></a>SubscriptionResponse
|
||||
|
||||
#### Description
|
||||
|
||||
The `SubscriptionResponse` message is the response from the `SubscriptionRequest`. After a client has processed an incoming [MsgProto](#MSGPROTO) message, it must send an acknowledgement to the `ackInbox` subject provided here.
|
||||
|
||||
#### Message Structure
|
||||
|
||||
- `ackInbox`: subject the client sends message acknowledgements to the NATS Streaming Server
|
||||
- `error`: error string, empty/omitted if no error
|
||||
|
||||
## <a name="UNSUBREQ"></a>UnsubscribeRequest
|
||||
|
||||
#### Description
|
||||
|
||||
The `UnsubscribeRequest` unsubcribes the connection from the specified subject. The inbox specified is the `inbox` returned from the NATS Streaming Server in the `SubscriptionResponse`.
|
||||
|
||||
#### Message Structure
|
||||
|
||||
- `clientID`: Client ID originally provided in the [ConnectRequest](#CONNREQ)
|
||||
- `subject`: Subject for the subscription
|
||||
- `inbox`: Inbox subject to identify subscription
|
||||
- `durableName`: Optional durable name which survives client restarts
|
||||
|
||||
## <a name="PUBMSG"></a>PubMsg
|
||||
|
||||
#### Description
|
||||
|
||||
The `PubMsg` protocol message is published from a client to the NATS Streaming Server. The GUID must be unique, and is returned in the [PubAck](#PUBACK) message to correlate the success or failure of storing this particular message.
|
||||
|
||||
#### Message Structure
|
||||
|
||||
- `clientID`: Client ID originally provided in the [ConnectRequest](#CONNREQ)
|
||||
- `guid`: a guid generated for this particular message
|
||||
- `subject`: subject
|
||||
- `reply`: optional reply subject
|
||||
- `data`: payload
|
||||
- `sha256`: optional sha256 of payload data
|
||||
|
||||
## <a name="PUBACK"></a>PubAck
|
||||
|
||||
#### Description
|
||||
|
||||
The `PubAck` message is an acknowledgement from the NATS Streaming Server that a message has been processed. The message arrives on the subject specified on the reply subject of the NATS message the `PubMsg` was published on. The GUID is the same GUID used in the `PubMsg` being acknowledged. If an error string is present, the message was not persisted by the NATS Streaming Server and no guarantees regarding persistence are honored. `PubAck` messages may be handled asynchronously from their corresponding `PubMsg` in the client.
|
||||
|
||||
#### Message Structure
|
||||
|
||||
- `guid`: GUID of the message being acknowledged by the NATS Streaming Server
|
||||
- `error`: An error string, empty/omitted if no error
|
||||
|
||||
## <a name="MSGPROTO"></a>MsgProto
|
||||
|
||||
#### Description
|
||||
|
||||
The `MsgProto` message is received by client from the NATS Streaming Server, containing the payload of messages sent by a publisher. A `MsgProto` message that is not acknowledged with an [Ack](#ACK) message within the duration specified by the `ackWaitInSecs` field of the subscription request will be redelivered.
|
||||
|
||||
#### Message Structure
|
||||
|
||||
- `sequence`: Globally ordered sequence number for the subject's channel
|
||||
- `subject`: Subject
|
||||
- `reply`: Optional reply
|
||||
- `data`: Payload
|
||||
- `timestamp`: Time the message was stored in the server.
|
||||
- `redelivered`: Flag specifying if the message is being redelivered
|
||||
- `CRC32`: Optional IEEE CRC32
|
||||
|
||||
## <a name="ACK"></a>Ack
|
||||
|
||||
#### Description
|
||||
|
||||
An `Ack` message is an acknowledgement from the client that a [MsgProto](#MSGPROTO) message has been considered received. It is published to the `ackInbox` field of the [`SubscriptionResponse`](#SUBRESP).
|
||||
|
||||
#### Message Structure
|
||||
|
||||
- `subject`: Subject of the message being acknowledged
|
||||
- `sequence`: Sequence of the message being acknowledged
|
||||
|
||||
## <a name="CLOSEREQ"></a>CloseRequest
|
||||
|
||||
#### Description
|
||||
|
||||
A `CloseRequest` message is published on the `closeRequests` subject from the [`ConnectResponse`](#CONNRESP), and notifies the NATS Streaming Server that the client connection is closing, allowing the server to free up resources. This message should **always*- be sent when a client is finished using a connection.
|
||||
|
||||
#### Message Structure
|
||||
|
||||
- `clientID`: Client ID originally provided in the [ConnectRequest](#CONNREQ)
|
||||
|
||||
## <a name="CLOSERESP"></a>CloseResponse
|
||||
|
||||
#### Description
|
||||
|
||||
The `CloseResponse` is sent by the NATS Streaming Server on the reply subject of the `CloseRequest` NATS message. This response contains any error that may have occurred with the corresponding close call.
|
||||
|
||||
#### Message Structure
|
||||
|
||||
- `error`: error string, empty/omitted if no error
|
||||
82
nats_streaming/nats-streaming-quickstart.md
Normal file
82
nats_streaming/nats-streaming-quickstart.md
Normal file
@ -0,0 +1,82 @@
|
||||
# Getting Started with NATS Streaming
|
||||
|
||||
This tutorial demonstrates NATS Streaming using example [Go NATS Streaming clients](https://github.com/nats-io/go-nats-streaming.git).
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- [Set up your Git environment](https://help.github.com/articles/set-up-git/).
|
||||
- [Set up your Go environment](https://golang.org/doc/install).
|
||||
|
||||
## Setup
|
||||
|
||||
Download and install the [NATS Streaming Server](https://github.com/nats-io/nats-streaming-server/releases).
|
||||
|
||||
Clone the following repositories:
|
||||
|
||||
- NATS Streaming Server: `git clone https://github.com/nats-io/nats-streaming-server.git`
|
||||
- NATS Streaming Client: `git clone https://github.com/nats-io/go-nats-streaming.git`
|
||||
|
||||
## Start the NATS Streaming Server
|
||||
|
||||
Two options:
|
||||
|
||||
Run the binary that you downloaded, for example: `$ ./nats-streaming-server`
|
||||
|
||||
Or, run from source:
|
||||
|
||||
```sh
|
||||
% cd $GOPATH/src/github.com/nats-io/nats-streaming-server
|
||||
% go run nats-streaming-server.go
|
||||
```
|
||||
|
||||
You should see the following, indicating that the NATS Streaming Server is running:
|
||||
|
||||
```sh
|
||||
% go run nats-streaming-server.go
|
||||
[89999] 2016/06/25 08:54:35.399071 [INF] Starting nats-streaming-server[test-cluster] version 0.1.0
|
||||
[89999] 2016/06/25 08:54:35.399315 [INF] Starting nats-server version 0.9.0.beta
|
||||
[89999] 2016/06/25 08:54:35.399326 [INF] Listening for client connections on localhost:4222
|
||||
[89999] 2016/06/25 08:54:35.400721 [INF] Server is ready
|
||||
[89999] 2016/06/25 08:54:35.737589 [INF] STAN: Message store is MEMORY
|
||||
[89999] 2016/06/25 08:54:35.737610 [INF] STAN: Maximum of 1000000 will be stored
|
||||
```
|
||||
|
||||
## Run the publisher client
|
||||
|
||||
Publish several messages. For each publication you should get a result.
|
||||
|
||||
```sh
|
||||
% cd $GOPATH/src/github.com/nats-io/go-nats-streaming/examples/stan-pub
|
||||
% go run main.go foo "msg one"
|
||||
Published [foo] : 'msg one'
|
||||
% go run main.go foo "msg two"
|
||||
Published [foo] : 'msg two'
|
||||
% go run main.go foo "msg three"
|
||||
Published [foo] : 'msg three'
|
||||
```
|
||||
|
||||
## Run the subscriber client
|
||||
|
||||
Use the `--all` flag to receive all published messages.
|
||||
|
||||
```sh
|
||||
% cd $GOPATH/src/github.com/nats-io/go-nats-streaming/examples/stan-sub
|
||||
% go run main.go --all -c test-cluster -id myID foo
|
||||
Connected to nats://localhost:4222 clusterID: [test-cluster] clientID: [myID]
|
||||
subscribing with DeliverAllAvailable
|
||||
Listening on [foo], clientID=[myID], qgroup=[] durable=[]
|
||||
[#1] Received on [foo]: 'sequence:1 subject:"foo" data:"msg one" timestamp:1465962202884478817 '
|
||||
[#2] Received on [foo]: 'sequence:2 subject:"foo" data:"msg two" timestamp:1465962208545003897 '
|
||||
[#3] Received on [foo]: 'sequence:3 subject:"foo" data:"msg three" timestamp:1465962215567601196
|
||||
```
|
||||
|
||||
## Explore other subscription options
|
||||
|
||||
```sh
|
||||
--seq <seqno> Start at seqno
|
||||
--all Deliver all available messages
|
||||
--last Deliver starting with last published message
|
||||
--since <duration> Deliver messages in last interval (e.g. 1s, 1hr, https://golang.org/pkg/time/#ParseDuration)
|
||||
--durable <name> Durable subscriber name
|
||||
--unsubscribe Unsubscribe the durable on exit
|
||||
```
|
||||
68
nats_streaming/nats-streaming-swarm.md
Normal file
68
nats_streaming/nats-streaming-swarm.md
Normal file
@ -0,0 +1,68 @@
|
||||
# Using NATS Streaming with Docker Swarm
|
||||
|
||||
#### Step 1:
|
||||
|
||||
Create an overlay network for the NATS & NATS Streaming cluster (in this example, `nats-streaming-example`).
|
||||
Notice we added the `--attachable` option which will allow other containers to join the network which will be
|
||||
done at the end to confirm that can connect to the cluster.
|
||||
|
||||
```sh
|
||||
% docker network create --driver overlay --attachable nats-streaming-example
|
||||
```
|
||||
|
||||
#### Step 2:
|
||||
|
||||
Next create the NATS cluster which will be used by the NATS Streaming cluster.
|
||||
|
||||
```sh
|
||||
for i in `seq 1 3`; do
|
||||
sudo docker service create --network nats-streaming-example \
|
||||
--name nats-cluster-node-$i nats:1.1.0 \
|
||||
-cluster nats://0.0.0.0:6222 \
|
||||
-routes nats://nats-cluster-node-1:6222,nats://nats-cluster-node-2:6222,nats://nats-cluster-node-3:6222
|
||||
done
|
||||
```
|
||||
|
||||
#### Step 3:
|
||||
|
||||
Now that there is a NATS cluster available to connect, create the NATS Streaming cluster of three nodes as follows:
|
||||
|
||||
```sh
|
||||
for i in `seq 1 3`; do
|
||||
sudo docker service create --network nats-streaming-example \
|
||||
--name nats-streaming-node-$i nats-streaming:0.9.2 \
|
||||
-store file -dir store -clustered -cluster_id swarm -cluster_node_id node-$i \
|
||||
-cluster_peers node-1,node-2,node-3 \
|
||||
-nats_server nats://nats-cluster-node-1:4222,nats://nats-cluster-node-2:4222,nats://nats-cluster-node-3:4222
|
||||
done
|
||||
```
|
||||
|
||||
#### Step 4:
|
||||
|
||||
Next, confirm that it is possible to publish and replay messages via NATS Streaming by attaching a container
|
||||
to the same network where both NATS and NATS Streaming exist. Below you can find an example session of doing so,
|
||||
note that even though the client is only connecting to `nats://nats-cluster-node-1:4222` the NATS cluster will
|
||||
be routing the messages so that they will be processed to the NATS Streaming cluster service.
|
||||
|
||||
```sh
|
||||
$ sudo docker run --network nats-streaming-example -it golang:latest
|
||||
|
||||
root@d12f9f3fcdde:/go# cd src/github.com/nats-io/go-nats-streaming/
|
||||
|
||||
# Publishing 3 messages
|
||||
root@d12f9f3fcdde:/go/src/github.com/nats-io/go-nats-streaming# go run examples/stan-pub/main.go -s nats://nats-cluster-node-1:4222 --cluster swarm hello world
|
||||
Published [hello] : 'world'
|
||||
root@d12f9f3fcdde:/go/src/github.com/nats-io/go-nats-streaming# go run examples/stan-pub/main.go -s nats://nats-cluster-node-1:4222 --cluster swarm hello world
|
||||
Published [hello] : 'world'
|
||||
root@d12f9f3fcdde:/go/src/github.com/nats-io/go-nats-streaming# go run examples/stan-pub/main.go -s nats://nats-cluster-node-1:4222 --cluster swarm hello world
|
||||
Published [hello] : 'world'
|
||||
|
||||
# Replaying the messages from the beginning
|
||||
root@d12f9f3fcdde:/go/src/github.com/nats-io/go-nats-streaming# go run examples/stan-sub/main.go -s nats://nats-cluster-node-1:4222 --cluster swarm -id $RANDOM --all hello
|
||||
Connected to nats://nats-cluster-node-1:4222 clusterID: [swarm] clientID: [17010]
|
||||
subscribing with DeliverAllAvailable
|
||||
Listening on [hello], clientID=[17010], qgroup=[] durable=[]
|
||||
[#1] Received on [hello]: 'sequence:1 subject:"hello" data:"world" timestamp:1526948600795366785 '
|
||||
[#2] Received on [hello]: 'sequence:2 subject:"hello" data:"world" timestamp:1526948604613783399 '
|
||||
[#3] Received on [hello]: 'sequence:3 subject:"hello" data:"world" timestamp:1526948606124258269 '
|
||||
```
|
||||
46
nats_streaming/nats-streaming-tls.md
Normal file
46
nats_streaming/nats-streaming-tls.md
Normal file
@ -0,0 +1,46 @@
|
||||
# Securing NATS Streaming Server
|
||||
|
||||
|
||||
## Authenticating users
|
||||
|
||||
To enable user authentication from the command line, you can use the same mechanism as the NATS Server (`nats-server`). You pass in the `—user <user>` and `—pass <pass>` commands, or `--auth` parameters, and the NATS streaming server will automatically use these credentials. Or you can use a configuration file with a single user or token.
|
||||
|
||||
When using a configuration file with multi-user authorization, you must use the `—user` and `—pass` parameters with the NATS streaming server, matching a user in the configuration file, in order to specify which user the NATS streaming server should authenticate with to it's embedded NATS server.
|
||||
|
||||
For example, if you pass the NATS streaming server a file with a several users, you must run the streaming server as a user such as "Joe" who is defined in the configuration file.
|
||||
|
||||
## Using TLS
|
||||
|
||||
While there are several TLS related parameters for the NATS Streaming server, securing the server's connection is straightforward. However, bear in mind that the NATS Streaming server embeds the NATS server resulting in a client-server relationship where the NATS Streaming server is a client of it's embedded NATS server.
|
||||
|
||||
That means two sets of TLS configuration parameters must be used: TLS server parameters for the embedded NATS server, and TLS client parameters for the NATS Streaming server itself.
|
||||
|
||||
The streaming server specifies it's TLS client certificates with the following three parameters:
|
||||
|
||||
```sh
|
||||
-tls_client_key Client key for the streaming server
|
||||
-tls_client_cert Client certificate for the streaming server
|
||||
-tls_client_cacert Client certificate CA for the streaming server
|
||||
```
|
||||
|
||||
These could be the same certificates used with your NATS streaming clients.
|
||||
|
||||
The embedded NATS server specifies TLS server certificates with these:
|
||||
|
||||
```sh
|
||||
--tlscert <file> Server certificate file
|
||||
--tlskey <file> Private key for server certificate
|
||||
--tlscacert <file> Client certificate CA for verification
|
||||
```
|
||||
|
||||
The server parameters are used the same way you'd [secure a typical NATS server](https://github.com/nats-io/nats-server#securing-nats).
|
||||
|
||||
Proper usage of the NATS Streaming Server requires the use of both client and server parameters.
|
||||
|
||||
For example:
|
||||
|
||||
```sh
|
||||
% nats-streaming-server -tls_client_cert client-cert.pem -tls_client_key client-key.pem -tls_client_cacert ca.pem -tlscert server-cert.pem -tlskey server-key.pem -tlscacert ca.pem
|
||||
```
|
||||
|
||||
Further TLS related functionality can be found in [Securing NATS > TLS](https://github.com/nats-io/nats-server#securing-nats). Note that if specifying cipher suites is required, a configuration file for the embedded NATS server can be passed through the `-config` command line parameter.
|
||||
Loading…
x
Reference in New Issue
Block a user