wip

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)

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

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 |
+

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=<pid>
+```
+
+```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.

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=<service name>
+```