diff --git a/SUMMARY.md b/SUMMARY.md index 2b10714..c271a1f 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -5,3 +5,7 @@ * [Installing](nats_server/installation.md) * [Running](nats_server/running.md) * [Clients](nats_server/clients.md) + * [Flags](nats_server/flags.md) + * [Configuration File](nats_server/configuration.md) + * [Signals](nats_server/signals.md) + * [Window Service](nats_server/windows_srv.md) diff --git a/nats_server/configuration.md b/nats_server/configuration.md new file mode 100644 index 0000000..445c52c --- /dev/null +++ b/nats_server/configuration.md @@ -0,0 +1,47 @@ +## Configuration File Format + +The NATS server products provide a flexible configuration format that combines the best of traditional formats and newer styles such as JSON and YAML. + +The config file supports the following syntax: + +- Lines or options can be commented with `#` and `//` +- Value assignment can use: + - Equals sign: `foo = 2` + - Colon: `foo: 2` + - Whitespace: `foo 2` +- Arrays are enclosed in brackets: `[...]` +- Maps are enclosed in braces: `{...}` +- Maps can be assigned with no key separator +- Semicolons can be used as terminators + +### Variables + +Server configurations can specify variables. Variables allow you to reference a value from one or more sections in the configuration. + +Variables: +- Are block scoped +- Are referenced with a `$` prefix. +- Can be resolved from the environment + +> If the environment variable value begins with a number you may have trouble resolving it depending on the server version you are running. + + +``` +# Define a variable in the config +TOKEN: "secret" + +# Reference the variable +authorization { + token: $TOKEN +} +``` + +A similar configuration, but this time, the value is in the environment: + +``` +authorization { + token: $TOKEN +} +``` + +export TOKEN="hello"; nats-server -c /config/file diff --git a/nats_server/flags.md b/nats_server/flags.md new file mode 100644 index 0000000..c83935c --- /dev/null +++ b/nats_server/flags.md @@ -0,0 +1,81 @@ +## Flags + + +The NATS server has many flags to customize it's behaviour without having to write a configuration file. + +The configuration flags revolve around: + +- Server Options +- Logging +- Authorization +- TLS Security +- Clustering +- Information + + +### Server Options + +| Flag | Description | +| :-------------------- | :-------- | +| `-a`, `--addr` | Host address to bind to (default: 0.0.0.0) - all interfaces. | +| `-p`, `--port` | NATS client port (default: 4222). | +| `-P`, `--pid` | File to store the process ID (PID). | +| `-m`, `--http_port` | HTTP port for monitoring dashboard (exclusive of `--https_port`). | +| `-ms`, `--https_port` | HTTPS port monitoring for monitoring dashboard (exclusive of `--http_port`). | +| `-c`, `--config` | Path to NATS server configuration file. | +| `-sl`, `--signal` | Send a signal to nats-server process. See [process signaling](signals.md). | +| `--client_advertise` | Client HostPort to advertise to other servers. | +| `-t` | Test configuration and exit | + + + +### Logging Options +| Flag | Description | +| :-------------------- | :-------- | +| `-l`, `--log` | File to redirect log output | +| `-T`, `--logtime` | Specify `-T=false` to disable timestamping log entries | +| `-s`, `--syslog` | Log to syslog or windows event log | +| `-r`, `--remote_syslog` | The syslog server address, like `udp://localhost:514` | +| `-D`, `--debug` | Enable debugging output | +| `-V`, `--trace` | Enable protocol trace log messages | +| `-DV` | Enable both debug and protocol trace messages | + + +### Authorization Options + +| Flag | Description | +| :-------------------- | :-------- | +| `--user` | Required _username_ for connections. | +| `--pass` | Required _password_ for connections. | +| `--auth` | Required _authorization token_ for connections. | + + +### TLS Options + +| Flag | Description | +| :-------------------- | :-------- | +| `--tls` | Enable TLS, do not verify clients | +| `--tlscert` | Server certificate file | +| `--tlskey` | Private key for server certificate | +| `--tlsverify` | Enable client TLS certificate verification | +| `--tlscacert` | Client certificate CA for verification | + + +### Cluster Options + +| Flag | Description | +| :-------------------- | :-------- | +| `--routes` | Comma separated list of cluster URLs to solicit and connect | +| `--cluster` | Cluster URL for clustering requests | +| `--no_advertise` | Do not advertise known cluster information to clients | +| `--cluster_advertise` | Cluster URL to advertise to other servers | +| `--connect_retries` | For implicit routes, number of connect retries | + +### Common Options + +| Flag | Description | +| :-------------------- | :-------- | +| `-h`, `--help` | Show this message | +| `-v`, `--version` | Show version | +| `--help_tls` | TLS help | + diff --git a/nats_server/signals.md b/nats_server/signals.md new file mode 100644 index 0000000..41a7552 --- /dev/null +++ b/nats_server/signals.md @@ -0,0 +1,42 @@ +## Process Signaling + +On Unix systems, the NATS server responds to the following signals: + +| Signal | Result | +| :--- | :--- | +| SIGKILL | Kills the process immediately | +| SIGINT | Stops the server gracefully | +| SIGUSR1 | Reopens the log file for log rotation | +| SIGHUP | Reloads server configuration file | +| SIGUSR2 | Stops the server after evicting all clients (lame duck mode) | + +The `nats-server` binary can be used to send these signals to running NATS servers using the `-sl` flag: + +```sh +# Quit the server +nats-server -sl quit + +# Stop the server +nats-server -sl stop + +# Reopen log file for log rotation +nats-server -sl reopen + +# Reload server configuration +nats-server -sl reload + +# Lame duck mode server configuration +nats-server -sl ldm +``` + +If there are multiple `nats-server` processes running, or if `pgrep` isn't available, you must either specify a PID or the absolute path to a PID file: + +```sh +nats-server -sl stop= +``` + +```sh +nats-server -sl stop=/path/to/pidfile +``` + +See the [Windows Service](windows_srv.md) section for information on signaling the NATS server on Windows. \ No newline at end of file diff --git a/nats_server/windows_srv.md b/nats_server/windows_srv.md new file mode 100644 index 0000000..7929a8c --- /dev/null +++ b/nats_server/windows_srv.md @@ -0,0 +1,27 @@ +### 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 and instead users should use `sc.exe` to install the service: + +```batch +sc.exe create nats-server binPath= "%NATS_PATH%\nats-server.exe [nats-server flags]" +sc.exe start nats-server +``` + +The above will create and start a `nats-server` service. Note that the nats-server flags should be passed in when creating the service. This allows for running multiple NATS server configurations on a single Windows server by using a 1:1 service instance per installed NATS server service. Once the service is running, it can be controlled using `sc.exe` or `nats-server.exe -sl`: + +```batch +REM Reload server configuration +nats-server.exe -sl reload + +REM Reopen log file for log rotation +nats-server.exe -sl reopen + +REM Stop the server +nats-server.exe -sl stop +``` + +The above commands will default to controlling the `nats-server` service. If the service is another name, it can be specified: + +```batch +nats-server.exe -sl stop= +```