taigrr/nats.docs
1
0
Fork 0
mirror of https://github.com/taigrr/nats.docs synced 2025-01-18 04:03:23 -08:00
Code Issues Projects Releases Wiki Activity

Major rewrite of NATS Streaming Server concepts section

Browse Source 
and updates to the developing section.

Signed-off-by: Ivan Kozlovic <ivan@synadia.com>
This commit is contained in:
Ivan Kozlovic
2019-05-22 18:11:42 -06:00
parent 3f95943077
commit 5a458036a2
49 changed files with 1521 additions and 403 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
nats_streaming/gettingstarted/configuring.md Normal file
View File

@@ -0,0 +1,3 @@
## 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#configuring) for further information on usage, configuration, and administration.

81
nats_streaming/gettingstarted/install.md Normal file
View File

@@ -0,0 +1,81 @@
# NATS Streaming 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.
## Installing via a Package Manager
On Mac OS:
```
> brew install nats-streaming-server
```
Via Docker:
```
> docker pull nats-streaming
```
## Installing a release build
You can find the latest release of `nats-streaming-server` [here](https://github.com/nats-io/nats-streaming-server/releases/latest).
Download the zip file matching your systems architecture, and unzip. For this example, assuming version 0.14.2 of the server, and a Linux AMD64:
```
> curl -L https://github.com/nats-io/nats-streaming-server/releases/download/v0.14.2/nats-streaming-server-v0.14.2-linux-amd64.zip -o nats-streaming-server.zip
> unzip nats-streaming-server.zip -d tmp
Archive: nats-streaming-server.zip
creating: tmp/nats-streaming-server-v0.14.2-linux-amd64/
inflating: tmp/nats-streaming-server-v0.14.2-linux-amd64/README.md
inflating: tmp/nats-streaming-server-v0.14.2-linux-amd64/LICENSE
inflating: tmp/nats-streaming-server-v0.14.2-linux-amd64/nats-streaming-server
> cp tmp/nats-streaming-server-v0.14.2-linux-amd64/nats-streaming-server /usr/local/bin
```
## Installing from the source
If you have go installed, installing the binary is easy:
```
> go get github.com/nats-io/nats-streaming-server
```
This mechanism will install a build of master, which almost certainly will not be a released version. If you are a developer and want to play with the latest, this is the easiest way of obtaining it.
You can run the test suite from the `nats-streaming-server` root directory:
```
go test -v -p=1 ./...
```
Some of the store tests require a SQL server to be running. To skip those, use this command instead:
```
go test -v -p=1 ./... -sql=false
```
## Testing Your Installation
To test your installation (provided the executable is visible to your shell):
```
> nats-streaming-server
[58061] 2019/05/22 13:56:45.463562 [INF] STREAM: Starting nats-streaming-server[test-cluster] version 0.14.2
[58061] 2019/05/22 13:56:45.463639 [INF] STREAM: ServerID: Avb51sMf9imRPVVwv6Ts0v
[58061] 2019/05/22 13:56:45.463657 [INF] STREAM: Go version: go1.11.10
[58061] 2019/05/22 13:56:45.463659 [INF] STREAM: Git commit: [not set]
[58061] 2019/05/22 13:56:45.464086 [INF] Starting nats-server version 1.4.1
[58061] 2019/05/22 13:56:45.464092 [INF] Git commit [not set]
[58061] 2019/05/22 13:56:45.464310 [INF] Listening for client connections on 0.0.0.0:4222
[58061] 2019/05/22 13:56:45.464328 [INF] Server is ready
[58061] 2019/05/22 13:56:45.495045 [INF] STREAM: Recovering the state...
[58061] 2019/05/22 13:56:45.495055 [INF] STREAM: No recovered state
[58061] 2019/05/22 13:56:45.749604 [INF] STREAM: Message store is MEMORY
[58061] 2019/05/22 13:56:45.749658 [INF] STREAM: ---------- Store Limits ----------
[58061] 2019/05/22 13:56:45.749664 [INF] STREAM: Channels: 100 *
[58061] 2019/05/22 13:56:45.749668 [INF] STREAM: --------- Channels Limits --------
[58061] 2019/05/22 13:56:45.749671 [INF] STREAM: Subscriptions: 1000 *
[58061] 2019/05/22 13:56:45.749675 [INF] STREAM: Messages : 1000000 *
[58061] 2019/05/22 13:56:45.749678 [INF] STREAM: Bytes : 976.56 MB *
[58061] 2019/05/22 13:56:45.749682 [INF] STREAM: Age : unlimited *
[58061] 2019/05/22 13:56:45.749686 [INF] STREAM: Inactivity : unlimited *
[58061] 2019/05/22 13:56:45.749690 [INF] STREAM: ----------------------------------
```

6
nats_streaming/gettingstarted/intro.md Normal file
View File

@@ -0,0 +1,6 @@
# 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.
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.11+ is required) to build the NATS Streaming server.

27
nats_streaming/gettingstarted/process-signaling.md Normal file
View File

@@ -0,0 +1,27 @@
# Process Signaling
On Unix systems, the NATS Streaming Server responds to the following signals:
| Signal | Result |
| --------------- | ------------------------------------- |
| SIGKILL | Kills the process immediately |
| SIGINT, SIGTERM | Stops the server gracefully |
| SIGUSR1 | Reopens the log file for log rotation |
The `nats-streaming-server` binary can be used to send these signals to running NATS Streaming Servers using the `-sl` flag:
```sh
# Reopen log file for log rotation
nats-streaming-server -sl reopen
# Stop the server
nats-streaming-server -sl quit
```
If there are multiple `nats-streaming-server` processes running, specify a PID:
```sh
nats-streaming-server -sl quit=<pid>
```
See the [Windows Service](#windows-service) section for information on signaling the NATS Streaming Server on Windows.

96
nats_streaming/gettingstarted/run.md Normal file
View File

@@ -0,0 +1,96 @@
# Getting Started with NATS Streaming
This tutorial demonstrates NATS Streaming using example [Go NATS Streaming clients](https://github.com/nats-io/stan.go.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/stan.go.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
[59232] 2019/05/22 14:24:54.426344 [INF] STREAM: Starting nats-streaming-server[test-cluster] version 0.14.2
[59232] 2019/05/22 14:24:54.426423 [INF] STREAM: ServerID: 3fpvAuXHo3C66Rkd4rmfFX
[59232] 2019/05/22 14:24:54.426440 [INF] STREAM: Go version: go1.11.10
[59232] 2019/05/22 14:24:54.426442 [INF] STREAM: Git commit: [not set]
[59232] 2019/05/22 14:24:54.426932 [INF] Starting nats-server version 1.4.1
[59232] 2019/05/22 14:24:54.426937 [INF] Git commit [not set]
[59232] 2019/05/22 14:24:54.427104 [INF] Listening for client connections on 0.0.0.0:4222
[59232] 2019/05/22 14:24:54.427108 [INF] Server is ready
[59232] 2019/05/22 14:24:54.457604 [INF] STREAM: Recovering the state...
[59232] 2019/05/22 14:24:54.457614 [INF] STREAM: No recovered state
[59232] 2019/05/22 14:24:54.711407 [INF] STREAM: Message store is MEMORY
[59232] 2019/05/22 14:24:54.711465 [INF] STREAM: ---------- Store Limits ----------
[59232] 2019/05/22 14:24:54.711471 [INF] STREAM: Channels: 100 *
[59232] 2019/05/22 14:24:54.711474 [INF] STREAM: --------- Channels Limits --------
[59232] 2019/05/22 14:24:54.711478 [INF] STREAM: Subscriptions: 1000 *
[59232] 2019/05/22 14:24:54.711481 [INF] STREAM: Messages : 1000000 *
[59232] 2019/05/22 14:24:54.711485 [INF] STREAM: Bytes : 976.56 MB *
[59232] 2019/05/22 14:24:54.711488 [INF] STREAM: Age : unlimited *
[59232] 2019/05/22 14:24:54.711492 [INF] STREAM: Inactivity : unlimited *
[59232] 2019/05/22 14:24:54.711495 [INF] STREAM: ----------------------------------
```
## Run the publisher client
Publish several messages. For each publication you should get a result.
```sh
> cd $GOPATH/src/github.com/nats-io/stan.go/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/stan.go/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
```

46
nats_streaming/gettingstarted/tls.md Normal file
View 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.

28
nats_streaming/gettingstarted/windows-service.md Normal file
View File

@@ -0,0 +1,28 @@
# Windows Service
The NATS Streaming Server supports running as a Windows service. There is currently no installer and instead users should use `sc.exe` to install the service:
Here is how to create and start a NATS Streaming Server named `nats-streaming-server`. Note that the server flags should be passed in when creating the service.
```sh
sc.exe create nats-streaming-server binPath="\"<streaming server path>\nats-streaming-server.exe\" [NATS Streaming flags]"
sc.exe start nats-streaming-server
```
You can create several instances, giving it a unique name. For instance, this is how you would create two services, named `nss1` and `nss2`, each one with its own set of parameters.
```
sc.exe create nss1 binPath="\"c:\nats-io\nats-streaming\nats-streaming-server.exe\" --syslog --syslog_name=nss1 -p 4222"
sc.exe create nss2 binPath="\"c:\nats-io\nats-streaming\nats-streaming-server.exe\" --syslog --syslog_name=nss2 -p 4223"
```
By default, when no logfile is specified, the server will use the system log. The default event source name is `NATS-Streaming-Server`. However, you can specify the name you want, which is especially useful when installing more than one service as described above.
Once the service is running, it can be controlled using `sc.exe` or `nats-streaming-server.exe -sl`:
```batch
REM Stop the server
nats-streaming-server.exe -sl quit
```
The above commands will default to controlling the service named `nats-streaming-server`. If the service has another name, it can be specified like this:
```batch
nats-streaming-server.exe -sl quit=<service name>
```