nats-streaming-server

README

NATS Streaming Server

NATS Streaming is an extremely performant, lightweight reliable streaming platform built on NATS.

NATS Streaming provides the following high-level feature set.

• Log based.
• At-Least-Once Delivery model, giving reliable message delivery.
• Rate matched on a per subscription basis.
• Replay/Restart
• Last Value Semantics

Getting Started

The best way to get the NATS Streaming Server is to use one of the pre-built release binaries which are available for OSX, Linux (x86-64/ARM), Windows. Instructions for using these binaries are on the GitHub releases page.

Of course you can build the latest version of the server from the master branch. The master branch will always build and pass tests, but may not work correctly in your environment. You will first need Go installed on your machine (version 1.5+ is required) to build the NATS server.

See also the NATS Streaming Quickstart tutorial.

Running

The NATS Streaming Server embeds a NATS Server. Starting the server with no argument will give you a server with default settings and a memory based store.

> ./nats-streaming-server
[73781] 2016/06/20 21:06:52.753188 [INF] Starting nats-streaming-server[test-cluster] version 0.0.1.alpha
[73781] 2016/06/20 21:06:52.754773 [INF] Starting nats-server version 0.8.2
[73781] 2016/06/20 21:06:52.754782 [INF] Listening for client connections on localhost:4222
[73781] 2016/06/20 21:06:52.757134 [INF] Server is ready
[73781] 2016/06/20 21:06:53.094875 [INF] STAN: Message store is MEMORY
[73781] 2016/06/20 21:06:53.094887 [INF] STAN: Maximum of 1000000 will be stored

The server will be started and listening for client connections on port 4222 (the default) from all available interfaces. The logs will be displayed to stderr as shown above.

Note that you do not need to start the embedded NATS Server. It is started automatically when you run the NATS Streaming Server. See below for details on how you secure the embedded NATS Server.

Configuring

The NATS Streaming Server accepts command line arguments to control its behavior. There is a set of parameters specific to the NATS Streaming Server and some to the embedded NATS Server.

Streaming Server Options:
    -cluster_id  <cluster ID>    Cluster ID (default: test-cluster)
    -store <type>                Store type: MEMORY|FILE (default: MEMORY)
    -dir <directory>             For FILE store type, this is the root directory
    -max_channels <number>       Max number of channels
    -max_subs <number>           Max number of subscriptions per channel
    -max_msgs <number>           Max number of messages per channel
    -max_bytes <number>          Max messages total size per channel

Streaming Server TLS Options:
    -secure                      Use a TLS connection to the NATS server without
	                             verification; weaker than specifying certificates.
    -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

Streaming Server Logging Options:
    -SD, --stan_debug            Enable STAN debugging output
    -SV, --stan_trace            Trace the raw STAN protocol
    -SDV                         Debug and trace STAN
    (See additional NATS logging options below)

Embedded NATS Server Options:
    -a, --addr <host>                Bind to host address (default: 0.0.0.0)
    -p, --port <port>                Use port for clients (default: 4222)
    -P, --pid <file>                 File to store PID
    -m, --http_port <port>           Use port for http monitoring
    -ms,--https_port <port>          Use port for https monitoring
    -c, --config <file>              Configuration file

Logging Options:
    -l, --log <file>                 File to redirect log output
    -T, --logtime                    Timestamp log entries (default: true)
    -s, --syslog                     Enable syslog as log method
    -r, --remote_syslog <addr>       Syslog server addr (udp://localhost:514)
    -D, --debug                      Enable debugging output
    -V, --trace                      Trace the raw protocol
    -DV                              Debug and trace

Authorization Options:
        --user <user>                User required for connections
        --pass <password>            Password required for connections
        --auth <token>               Authorization token required for connections

TLS Options:
        --tls                        Enable TLS, do not verify clients (default: false)
        --tlscert <file>             Server certificate file
        --tlskey <file>              Private key for server certificate
        --tlsverify                  Enable TLS, very client certificates
        --tlscacert <file>           Client certificate CA for verification

NATS Clustering Options:
        --routes <rurl-1, rurl-2>    Routes to solicit and connect
        --cluster <cluster-url>      Cluster URL for solicited routes

Common Options:
    -h, --help                       Show this message
    -v, --version                    Show version
        --help_tls                   TLS help.

Securing NATS Streaming Server

Authorization

If you use basic authorization, that is a single user defined through the configuration file or command line parameters, nothing else is required. The embedded NATS Server is started with those credentials and the NATS Streaming Server uses them.

However, if you define multiple users, then you must specify the username and password (or token) corresponding to the NATS Streaming Server's user.

For instance, suppose that your configuration file server.cfg has the following content:

listen: 127.0.0.1:4233
http: 127.0.0.1:8233

authorization {
    users = [
      {user: alice, password: foo}
      {user: bob,   password: bar}
    ]
}

and you start the NATS Streaming Server this way:

nats-streaming-server -config server.cfg

then the server would fail to start. You must specify the user used by the streaming server. For instance:

nats-streaming-server -config server.cfg -user alice -pass foo

TLS

While there are several TLS related parameters to the streaming server, securing the NATS Streaming server's connection is straightforward when you bear in mind that the relationship between the NATS Streaming server and the embedded NATS server is a client server relationship. To state simply, the 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 streaming server itself.

The streaming server specifies it's TLS client certificates with the following three parameters: -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:

    --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 would secure a typical NATS server. See here.

Proper usage of the NATS Streaming Server requires the use of both client and server parameters.

e.g.:

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 usage, and should specifying cipher suites be required, a configuration file for the embedded NATS server can be passed through the -config command line parameter.

Persistence

By default, the NATS Streaming Server stores its state in memory, which means that if the streaming server is stopped, all state is lost. Still, this level of persistence allows applications to stop and later resume the stream of messages, and protect against applications disconnect (network or applications crash).

File Store

For a higher level of message delivery, the server should be configured with a file store. NATS Streaming Server comes with a basic file store implementation. Various file store implementations may be added in the future.

To start the server with a file store, you need to provide two parameters:

nats-streamin-server -store file -dir datastore

The parameter -store indicates what type of store to use, in this case file. The other (-dir) indicates in which directory the state should be stored.

The first time the server is started, it will create two files in this directory, one containing some server related information (server.dat) another to record clients information (clients.dat).

When a streaming client connects, it uses a client identification, which the server registers in this file. When the client disconnects, the client is cleared from this file.

When the client publishes or subscribe to a new subject (also called channel), the server creates a sub-directory whose name is the subject. For instance, if the client subscribes to foo, and assuming that you started the server with -dir datastore, then you will find a directory called datastore/foo. In this directory you will find several files: one to record subscriptions information (subs.dat), and a serie of files that logs the messages msgs.1.dat, etc...

The number of sub-directories, which again correspond to channels, can be limited by the configuration parameter -max_channels. When the limit is reached, any new subscription or message published on a new channel will produce an error.

On a given channel, the number of subscriptions can also be limited with the configuration parameter -max_subs. A client that tries to create a subscription on a given channel (subject) for which the limit is reached will receive an error.

Finally, the number of stored messages for a given channel can also be limited with the parameter -max_msgs and/or -max_bytes. However, for messages, the client does not get an error when the limit is reached. The oldest messages are discarded to make room for the new messages.

Store Interface

Every store implementation follows the Store interface.

The main interace is the Store which the server will create a unique instance of. From a store, the server can add/delete clients, create/lookup channels, etc...

Creating/looking up a channel will return a ChannelStore, which points to two other interfaces, the SubStore and MsgStore. These stores handle, for a given channel, subscriptions and messages respectiverly.

If you wish to contribute to a new store type, your implementation must include all these interfaces. For stores that allow recovery (such as file store as opposed to memory store), there are additional structures that have been defined and that a store constructor should return. This allows the server to reconstruct its state on startup.

The memory and the provided file store implementations both use a generic store implementation to avoid code duplication. When writing your own store implementation, you can do the same for APIs that don't need to do more than what the generic implementation provides. You can check MemStore and FileStore implementations for more details.

Building

Building the NATS Streaming Server from source requires at least version 1.5 of Go, but we encourage the use of the latest stable release. Information on installation, including pre-built binaries, is available at http://golang.org/doc/install. Stable branches of operating system packagers provided by your OS vendor may not be sufficient.

Run go version to see the version of Go which you have installed.

Run go get inside the directory to include all possible dependencies.

Run go build inside the directory to build.

Run go test ./... to run the unit regression tests.

A successful build produces no messages and creates an executable called nats-streaming-server in the current directory. You can invoke that binary, with no options and no configuration file, to start a server with acceptable standalone defaults (no authentication, memory store).

Run go help for more guidance, and visit http://golang.org/ for tutorials, presentations, references and more.

Clients

Currently, there are two NATS Streaming clients, both supported by Apcera. We will be adding additional supported streaming clients in the future, and encourage community-contributed clients.

• Go
• Java

License

The MIT License (MIT)

Copyright (c) 2016 Apcera Inc.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.