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

Gramarly

Browse Source
This commit is contained in:
Alberto Ricart
2019-05-20 17:51:27 -05:00
parent a1c12370c2
commit 5da9b66f5e
133 changed files with 246 additions and 249 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
nats_server/auth_intro.md
View File

@@ -9,7 +9,7 @@ The NATS server provides various ways of authenticating clients:
- [JWTs with Challenge](jwt_auth.md)
Authentication deals with allowing a NATS client to connect to the server.
With the exception of JWT authentication, authentication and authorization is configured in the `authorization` section of the configuration.
Except for JWT authentication, authentication and authorization are configured in the `authorization` section of the configuration.
## Authorization Map

12
nats_server/auth_timeout.md
View File

@@ -6,14 +6,14 @@ If a client doesn't authenticate to the server within the specified time, the se
Timeouts are specified in seconds (and can be fractional).
As with TLS timeouts, long timeouts can be an opportunity for abuse. If setting the authentication timeout, it is important to note. that it should be longer than the `tls timeout` option, as the authentication timeout includes the TLS upgrade time.
As with TLS timeouts, long timeouts can be an opportunity for abuse. If setting the authentication timeout, it is important to note that it should be longer than the `tls timeout` option, as the authentication timeout includes the TLS upgrade time.
```
authorization: {
timeout: 3
users: [
{user: a, password b},
{user: b, password a}
]
timeout: 3
users: [
{user: a, password b},
{user: b, password a}
]
}
```

12
nats_server/authorization.md
View File

@@ -1,9 +1,9 @@
## Authorization
The NATS server supports authorization using subject-level permissions on a per-user basis. Permission-based authorization is available withmulti-user authentication via the `users` list.
The NATS server supports authorization using subject-level permissions on a per-user basis. Permission-based authorization is available with multi-user authentication via the `users` list.
Each permission specifies the subjects the user can publish to and subscribe to. The parser is generous at understanding what the intent is, so both arrays and singletons are processed. For more complex configuation you can specify a `permission` object which explicetly allows or denies subjects. The specified subjects can specify wildcards. Permissions can make use of [variables](configuration.md#variables).
Each permission specifies the subjects the user can publish to and subscribe to. The parser is generous at understanding what the intent is, so both arrays and singletons are processed. For more complex configuration, you can specify a `permission` object which explicitly allows or denies subjects. The specified subjects can specify wildcards. Permissions can make use of [variables](configuration.md#variables).
You configure authorization by creating a `permissions` entry in the `authorization` object.
@@ -18,7 +18,7 @@ The `permissions` map specify subjects that can be subscribed to or published by
### Permission Map
The `permission` map provides additional properties for configuring a `permissions` map. Instead of providing a list of subjects that are allowed, the `permission` map allows you to explicitely list subjects you want to`allow` or `deny`:
The `permission` map provides additional properties for configuring a `permissions` map. Instead of providing a list of subjects that are allowed, the `permission` map allows you to explicitly list subjects you want to`allow` or `deny`:
| Property | Description |
| :------ | :---- |
@@ -27,7 +27,7 @@ The `permission` map provides additional properties for configuring a `permissio
**Important Note** NATS Authorizations are whitelist only, meaning in order to not break request/reply patterns you need to add rules as above with Alice and Bob for the `_INBOX.>` pattern. If an unauthorized client publishes or attempts to subscribe to a subject that has not been whitelisted, the action fails and is logged at the server, and an error message is returned to the client.
**Important Note** NATS Authorizations are whitelist only, meaning to not break request/reply patterns you need to add rules as above with Alice and Bob for the `_INBOX.>` pattern. If an unauthorized client publishes or attempts to subscribe to a subject that has not been whitelisted, the action fails and is logged at the server, and an error message is returned to the client.
### Example
@@ -66,8 +66,8 @@ authorization {
- _client_ is a `REQUESTOR` and can publish requests on subjects `req.a` or `req.b`, and subscribe to anything that is a response (`_INBOX.>`).
- _service_ is a `RESPONDER` to `req.a` and `req.b` requests, so it needs to be able to subscribe to the request subjects and respond to client's that are able to publish requests to `req.a` and `req.b`. The reply subject subject is an inbox. Typically inboxes start with the prefix `_INBOX.` followed by a generated string. The `_INBOX.>` subject matches all subjects that start with `_INBOX.`.
- _service_ is a `RESPONDER` to `req.a` and `req.b` requests, so it needs to be able to subscribe to the request subjects and respond to client's that can publish requests to `req.a` and `req.b`. The reply subject is an inbox. Typically inboxes start with the prefix `_INBOX.` followed by a generated string. The `_INBOX.>` subject matches all subjects that begin with `_INBOX.`.
- _other_ has no permissions granted and therefore inherits the default permission set. You set the inherited default permissions by assigning them to the `default_permissions` entry inside of the authorization configuration block.
> Note that in the above example, any client with permissions to subscribe to `_INBOX.>` is able to receive _all_ responses published. More sensitive installations will want to add or subset the prefix to further limit what a client can subscribe to. Alternatively [_Accounts_](jwt_auth.md) allow complete isolation limiting what members of an account can see.
> Note that in the above example, any client with permissions to subscribe to `_INBOX.>` can receive _all_ responses published. More sensitive installations will want to add or subset the prefix to further limit subjects that a client can subscribe. Alternatively, [_Accounts_](jwt_auth.md) allow complete isolation limiting what members of an account can see.

10
nats_server/clients.md
View File

@@ -2,7 +2,7 @@
The nats-server doesn't come bundled with any clients. But most client libraries come with tools that allow you to publish, subscribe, send requests and reply messages.
If you have a client library installed you can try using a bundled client. Otherwise you can easily install some clients.
If you have a client library installed, you can try using a bundled client. Otherwise, you can easily install some clients.
### If you have Go installed:
@@ -29,13 +29,13 @@ Open a terminal and [start a nats-server](running.md):
```
On another terminal start session start a subscriber:
On another terminal session start a subscriber:
```
> nats-sub ">"
Listening on [>]
```
Note that when the client connected, the server didn't log anything interesting because server output is fairly quiet unless something interesting happens.
Note that when the client connected, the server didn't log anything interesting because server output is relatively quiet unless something interesting happens.
To make the server output more lively, you can specify the `-V` flag to enable logging of server protocol tracing messages. Go ahead and `<ctrl>+c` the process running the server, and restart the server with the `-V` flag:
@@ -51,7 +51,7 @@ To make the server output more lively, you can specify the `-V` flag to enable l
[29785] 2019/05/16 08:46:13.467206 [TRC] 127.0.0.1:49805 - cid:1 - ->> [PONG]
```
If you had created a subscriber, you should notice output on the subscriber telling you that it diesconnected, and reconnected. The server output above is more interesting. You can see the subscriber send a `CONNECT` protocol message, and a `PING` which was responded to by the server with a `PONG`.
If you had created a subscriber, you should notice output on the subscriber telling you that it disconnected, and reconnected. The server output above is more interesting. You can see the subscriber send a `CONNECT` protocol message and a `PING` which was responded to by the server with a `PONG`.
> You can learn more about the [NATS protocol here](/nats_protocol/nats-protocol.md), but more intersting than the protocol description is [an interactive demo](/nats_protocol/nats-protocol-demo.md).
@@ -69,7 +69,7 @@ On the subscriber window you should see:
### Testing Against a Remote Server
If the NATS server was running in a different machine or a different port, you'll have to specify that to the client by specifying a _NATS URL_. NATS urls take the form of: `nats://<server>:<port>` and `tls://<server>:<port>`. URLs with a `tls` protocol sport a secured TLS connection.
If the NATS server were running in a different machine or a different port, you'd have to specify that to the client by specifying a _NATS URL_. NATS URLs take the form of: `nats://<server>:<port>` and `tls://<server>:<port>`. URLs with a `tls` protocol sport a secured TLS connection.
```
> nats-sub -s nats://server:port ">"

30
nats_server/configuration.md
View File

@@ -6,9 +6,9 @@ The NATS configuration file supports the following syntax:
- Lines can be commented with `#` and `//`
- Values can be assigned to properties with:
- Equals sign: `foo = 2`
- Colon: `foo: 2`
- Whitespace: `foo 2`
- Equals sign: `foo = 2`
- Colon: `foo: 2`
- Whitespace: `foo 2`
- Arrays are enclosed in brackets: `["a", "b", "c"]`
- Maps are enclosed in braces: `{foo: 2}`
- Maps can be assigned with no key separator
@@ -20,14 +20,14 @@ The configuration parser is very forgiving, as you have seen:
- values can be a primitive, or a list, or a map
- strings and numbers typically do the right thing
String values that start with a number _can_ create issues. To force such values as strings, simply quote them.
String values that start with a digit _can_ create issues. To force such values as strings, quote them.
*BAD Config*:
```
listen: 127.0.0.1:4222
authorization: {
# BAD!
token: 3secret
# BAD!
token: 3secret
}
```
@@ -35,7 +35,7 @@ Fixed Config:
```
listen: 127.0.0.1:4222
authorization: {
token: "3secret"
token: "3secret"
}
```
@@ -44,7 +44,7 @@ authorization: {
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 block-scoped
- Are referenced with a `$` prefix.
- Can be resolved from environment variables having the same name
@@ -57,16 +57,16 @@ TOKEN: "secret"
# Reference the variable
authorization {
token: $TOKEN
token: $TOKEN
}
```
A similar configuration, but this time, the value is in the environment:
```
# TOKEN should be defined in the environment
# TOKEN is defined in the environment
authorization {
token: $TOKEN
token: $TOKEN
}
```
@@ -89,7 +89,7 @@ include ./auth.conf
auth.conf:
```
authorization: {
token: "f0oBar"
token: "f0oBar"
}
```
@@ -128,8 +128,4 @@ A server can reload most configuration changes without requiring a server restar
```
> nats-server --signal reload
```
```

6
nats_server/flags.md
View File

@@ -1,7 +1,7 @@
## Flags
The NATS server has many flags to customize its behaviour without having to write a configuration file.
The NATS server has many flags to customize its behavior without having to write a configuration file.
The configuration flags revolve around:
@@ -31,7 +31,7 @@ The configuration flags revolve around:
### Authentication Options
The following options control very simple authentication:
The following options control straightforward authentication:
| Flag | Description |
| :-------------------- | :-------- |
@@ -77,7 +77,7 @@ The following flags are available on the server to configure clustering:
| Flag | Description |
| :-------------------- | :-------- |
| `--routes` | Comma separated list of cluster URLs to solicit and connect |
| `--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 |

9
nats_server/installation.md
View File

@@ -1,6 +1,6 @@
## NATS Server Installation
NATS philosophy is simplicity. Installation is just decompression a zip file and copying the binary to an appropiate directory; you can also use your favorite package manager.
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
@@ -23,7 +23,7 @@ Via Docker:
You can find the latest release of nats-server [here](https://github.com/nats-io/nats-server/releases/latest).
Simply download the zip file matching your systems architecture, and unzip. For this example, assuming version 2.0.0 of the server, and a Linux AMD64:
Download the zip file matching your systems architecture, and unzip. For this example, assuming version 2.0.0 of the server, and a Linux AMD64:
```
> curl -L https://github.com/nats-io/nats-server/releases/download/v2.0.0/nats-server-v2.0.0-linux-amd64.zip -o nats-server.zip
@@ -47,7 +47,7 @@ If you have go installed, installing the binary is easy:
> go get github.com/nats-io/nats-server
```
This mechanism will install a build of [master](https://github.com/nats-io/nats-server), which almost certainly will not be a released version. If you are a developer and want to play with the the latest, this is the easiest way of obtaining it.
This mechanism will install a build of [master](https://github.com/nats-io/nats-server), 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.
## Testing Your Installation
@@ -61,4 +61,5 @@ To test your installation (provided the executable is visible to your shell):
...
[41634] 2019/05/13 09:42:11.746249 [INF] Server id is NBNYNR4ZNTH4N2UQKSAAKBAFLDV3PZO4OUYONSUIQASTQT7BT4ZF6WX7
[41634] 2019/05/13 09:42:11.746252 [INF] Server is ready
```
```

16
nats_server/nkey_auth.md
View File

@@ -1,10 +1,10 @@
## NKey Authentication
NKeys are a new highly secure public-key signature system based on [Ed25519](https://ed25519.cr.yp.to/).
NKeys are a new, highly secure public-key signature system based on [Ed25519](https://ed25519.cr.yp.to/).
With NKeys the server can verify identities without ever storing secrets on the server. The authentication system works by requiring a connecting client to provide its public key and digitally sign a challenge with its private key. The server generates a random challenge with every connection request, making it immune to playback attacks. The generated signature is validated against the provided public key, thus proving the identity of the client. If the public key is known to the server, authentication succeeds.
> NKey is an awesome replacement for token authentication, because a connecting client will have to prove it controls the private key for the authorized public key.
> NKey is an excellent replacement for token authentication because a connecting client will have to prove it controls the private key for the authorized public key.
To generate nkeys, you'll need the [`nk` tool](/nats_tools/nk.md).
@@ -19,11 +19,11 @@ SUACSSL3UAHUDXKFSNVUZRF5UHPMWZ6BFDTJ7M6USDXIEDNPPQYYYCU3VY
UDXU4RCSJNZOIQHZNWXHXORDPRTGNJAHAHFRGZNEEJCPQTT2M7NLCNF4
```
The first output line starts with the letter `S` for _Seed_. The second letter `U` stands for _User_. Seeds are private keys; you should treat them as secrets and guard them with care.
The first output line starts with the letter `S` for _Seed_. The second letter, `U` stands for _User_. Seeds are private keys; you should treat them as secrets and guard them with care.
The second line starts with the letter `U` for _User_, and is a public key which can be safely shared.
The second line starts with the letter `U` for _User_ and is a public key which can be safely shared.
To use nkey authentication, add a user and set the `nkey` property to the public key of the user you want to authenticate:
To use nkey authentication, add a user, and set the `nkey` property to the public key of the user you want to authenticate:
```text
authorization: {
@@ -38,11 +38,11 @@ Note that the user section sets the `nkey` property (user/password/token propert
### Client Configuration
Now that you have a user nkey let's configure a client to use it for authentication. As an example, here are the connect options for the node client:
Now that you have a user nkey, let's configure a client to use it for authentication. As an example, here are the connect options for the node client:
```javascript
const NATS = require(‘nats‘);
const nkeys = require('ts-nkeys’);
const NATS = require('nats');
const nkeys = require('ts-nkeys');
const nkey_seed = ‘SUACSSL3UAHUDXKFSNVUZRF5UHPMWZ6BFDTJ7M6USDXIEDNPPQYYYCU3VY’;
const nc = NATS.connect({

2
nats_server/running.md
View File

@@ -2,7 +2,7 @@
The nats-server has many command line options. To get started, you don't have to specify anything.
In the absence of any flags, the NATS server will start listening for NATS client connections on port 4222.
By default, security is not enabled.
By default, security is disabled.
### Standalone

12
nats_server/tls.md
View File

@@ -1,15 +1,15 @@
## TLS Configuration
The NATS server uses modern TLS semantics to encrypt client, route and monitoring connections.
The NATS server uses modern TLS semantics to encrypt client, route, and monitoring connections.
Server configuration revolves around a `tls` map, which has the following properties:
| Property | Description |
| :------ | :---- |
| `ca_file` | TLS certificate authority file. |
| `cert_file` | TLS certificate file. |
| `cipher_suites` | When set, only the specified TLS cipher suites will be allowed. Values must match golang version used to build the server. |
| `curve_preferences` | List of TLS cypher curves to use in order. |
| `insecure` | Skip certificate verfication. |
| `cipher_suites` | When set, only the specified TLS cipher suites will be allowed. Values must match the golang version used to build the server. |
| `curve_preferences` | List of TLS cipher curves to use in order. |
| `insecure` | Skip certificate verification. |
| `key_file` | TLS certificate key file. |
| `timeout` | TLS handshake timeout in fractional seconds. |
| `verify_and_map` | If `true`, require and verify client certificates and map certificate values for authentication purposes. |
@@ -42,12 +42,12 @@ Notice that the log indicates that the client connections will be required to us
[22242] 2019/05/16 11:22:20.367291 [DBG] 127.0.0.1:51383 - cid:1 - TLS version 1.2, cipher suite TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
```
When a `tls` section is specified at the root of the configuration it also affects the monitoring port if `https_port` option is specified. Other sections such as `cluster` can specify a `tls` block.
When a `tls` section is specified at the root of the configuration, it also affects the monitoring port if `https_port` option is specified. Other sections such as `cluster` can specify a `tls` block.
### TLS Timeout
The `timeout` setting enables you to control the amount of time that a client is allowed to upgrade its connection to tls. If your clients are experiencing disconnects during TLS handshake, you'll want to increase the value. However if you do be aware that a long `timeout` exposes your server to attacks where a client doesn't upgrade to TLS and thus consumes resources. Conversely, if you reduce the TLS `timeout` too much, you are likely to experience handshake errors.
The `timeout` setting enables you to control the amount of time that a client is allowed to upgrade its connection to tls. If your clients are experiencing disconnects during TLS handshake, you'll want to increase the value, however, if you do be aware that an extended `timeout` exposes your server to attacks where a client doesn't upgrade to TLS and thus consumes resources. Conversely, if you reduce the TLS `timeout` too much, you are likely to experience handshake errors.
```

10
nats_server/tls_mutual_auth.md
View File

@@ -1,13 +1,13 @@
## Client TLS Mutual Authentication
The server can require TLS certificates from a client. When required, you can use the certificates to:
The server can require TLS certificates from a client. When needed, you can use the certificates to:
- Validate the client certificate matches a known or trusted CA
- Extract information from a trusted certificate to provide authentication
### Validating a Client Certificate
The server can verify a client certificate using CA certificate. To require verification, simply add the option `verify` the TLS configuration section as follows:
The server can verify a client certificate using a CA certificate. To require verification, add the option `verify` the TLS configuration section as follows:
```
tls {
@@ -24,13 +24,13 @@ Or via the command line:
> ./nats-server --tlsverify --tlscert=./test/configs/certs/server-cert.pem --tlskey=./test/configs/certs/server-key.pem --tlscacert=./test/configs/certs/ca.pem
```
This option simply verifies the client's certificate has been signed by the CA specified in the `ca_file` option.
This option verifies the client's certificate is signed by the CA specified in the `ca_file` option.
## Mapping Client Certificates To A User
In addition to verifying that a client certificate was issued by a specified CA, you can use information encoded in the certificate to authenticate a client. The client wouldn't have to provide or track usernames or passwords.
In addition to verifying that a specified CA issued a client certificate, you can use information encoded in the certificate to authenticate a client. The client wouldn't have to provide or track usernames or passwords.
To have TLS Mutual Authentication map certificate attributes to the users identity use `verify_and_map` as shown as follows:
To have TLS Mutual Authentication map certificate attributes to the user's identity use `verify_and_map` as shown as follows:
```
tls {

10
nats_server/tokens.md
View File

@@ -1,12 +1,12 @@
# Token Authentication
Token authentication is a string that if provided by a client, allows it to connect. It is the simplest authentication provided by the NATS server.
Token authentication is a string that if provided by a client, allows it to connect. It is the most straightforward authentication provided by the NATS server.
To use token authentication, you can just specify an `authorization` section with the `token` property set:
To use token authentication, you can specify an `authorization` section with the `token` property set:
```
authorization {
token: "s3cr3t"
token: "s3cr3t"
}
```
Token authentication can be used in the authorization section for clients and clusters.
@@ -24,7 +24,7 @@ Listening on [>]
## Bcrypted Tokens
Tokens can be bcrypted enabling an additional layer of security, as the clear-text version of the token would not be persisted on server configuration file.
Tokens can be bcrypted enabling an additional layer of security, as the clear-text version of the token would not be persisted on the server configuration file.
You can generate bcrypted tokens and passwords using the [`mkpasswd`](/nats_tools/mkpasswd.md) tool:
@@ -38,7 +38,7 @@ bcrypt hash: $2a$11$PWIFAL8RsWyGI3jVZtO9Nu8.6jOxzxfZo7c/W0eLk017hjgUKWrhy
Here's a simple configuration file:
```
authorization {
token: "$2a$11$PWIFAL8RsWyGI3jVZtO9Nu8.6jOxzxfZo7c/W0eLk017hjgUKWrhy"
token: "$2a$11$PWIFAL8RsWyGI3jVZtO9Nu8.6jOxzxfZo7c/W0eLk017hjgUKWrhy"
}
```

24
nats_server/username_password.md
View File

@@ -1,12 +1,12 @@
# Username and Password
You can authenticate one or more clients using username and passwords. This enables you to have greater control on the management and issuing of credential secrets.
You can authenticate one or more clients using username and passwords; this enables you to have greater control over the management and issuing of credential secrets.
For a single user:
```
authorization: {
user: a,
password: b
user: a,
password: b
}
```
@@ -19,10 +19,10 @@ You can also specify a single username/password by:
For multiple users:
```
authorization: {
users: [
{user: a, password: b},
{user: b, password: a}
]
users: [
{user: a, password: b},
{user: b, password: a}
]
}
```
@@ -39,16 +39,16 @@ And on the configuration file:
```
authorization: {
users: [
{user: a, password: "$2a$11$V1qrpBt8/SLfEBr4NJq4T.2mg8chx8.MTblUiTBOLV3MKDeAy.f7u"},
...
]
users: [
{user: a, password: "$2a$11$V1qrpBt8/SLfEBr4NJq4T.2mg8chx8.MTblUiTBOLV3MKDeAy.f7u"},
...
]
}
```
## Reloading a Configuration
As you add/remove passwords from the server configuration file, you'll want your changes to take effect. To reload without restarting the server and disconnecting clients, simply do:
As you add/remove passwords from the server configuration file, you'll want your changes to take effect. To reload without restarting the server and disconnecting clients, do:
```
> nats-server --signal reload

4
nats_server/windows_srv.md
View File

@@ -1,13 +1,13 @@
### 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:
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; 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 --signal`:
The above will create and start a `nats-server` service. Note that the nats-server flags should be provided 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 --signal`:
```batch
REM Reload server configuration