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

added gateways, leafnodes, nats-account-server, fixed typos etc.

Browse Source
This commit is contained in:
Alberto Ricart
2019-05-20 09:15:03 -05:00
parent e832940daf
commit b33bd52668
19 changed files with 1212 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
nats_tools/nas/README.md Normal file
View File

@@ -0,0 +1,16 @@
## NATS Account Server
The [NATS Account Server](https://github.com/nats-io/nats-account-server) is an HTTP server that hosts and vends JWTs for nats-server 2.0 account authentication. The server supports an number of stores which enable it to serve JWTs from:
- a directory
- an [NSC](../nsc/nsc.md) directory
- memory (for testing purposes)
The server can operate in a _READ ONLY_ mode where it serves content from a directory, or in notification mode, where it can notify a NATS server that JWT in the store have been modified, updating the NATS server with the updated JWT.
### Memory Resolver
For very simple installations, where JWTs are mostly static, the NATS server also supports a _Memory Resolver_ that can be configured statically in the server's configuration file.
You can learn more about how to configure the [memory resolver here](mem_resolver.md).

24
nats_tools/nas/dir_store.md Normal file
View File

@@ -0,0 +1,24 @@
## Directory Store
### NATS Account Server Configuration
```
OperatorJWTPath: "/users/synadia/.nsc/nats/Test/Test.jwt",
http {
port: 9090
},
store {
dir: "/tmp/as_store",
readonly: false,
shard: true
}
```
### To Add/Update a JWT
```
> curl -i -X POST localhost:9090/jwt/v1/accounts/AC7PO3MREV26U3LFZFP5BN3HAI32X3PKLBRVMPAETLEHWPQEUG7EJY4H --data-binary @/Users/synadia/.nsc/nats/Test/accounts/TestAccount/TestAccount.jwt -H "Content-Type: text/text"
```
Note that the `@` before the file name is required for curl to read the specified file, and use it as the payload. Otherwise it will simply post the path specified, which will result in an update error.

40
nats_tools/nas/inspecting_jwts.md Normal file
View File

@@ -0,0 +1,40 @@
## Inspecting a JWT from the `nats-account-server`
Let’s say that you know the account for a stream that you are interested in, but you don't know all the details for creating an import. If you know and have access to a nats-account-server, you can help yourself. The nats-account-server can decode a JWT and give you human readable values that you can use.
The endpoint for retrieving an account JWT is:
`/jwt/v1/accounts/<account_id>`. To decode a JWT add the query string `?decode=true`.
```json
> curl http://localhost:9090/jwt/v1/accounts/AC7PO3MREV26U3LFZFP5BN3HAI32X3PKLBRVMPAETLEHWPQEUG7EJY4H\?decode=true
{
"typ": "jwt",
"alg": "ed25519"
}
{
"jti": "5YMRO4KNMYWQDMRAHVTT4KX63CA2L3M6F4VM3S7NNGPMCCATORXQ",
"iat": 1556229062 (2019-04-25),
"iss": "OAYI3YUZSWDNMERD2IN3HZSIP3JA2E3VDTXSTEVOIII273XL2NABJP64",
"name": "TestAccount",
"sub": "AC7PO3MREV26U3LFZFP5BN3HAI32X3PKLBRVMPAETLEHWPQEUG7EJY4H",
"type": "account",
"nats": {
"exports": [
{
"name": "abc",
"subject": "a.b.c.>",
"type": "stream"
}
],
…
```
As you can see from above, the JWT is decoded. The standard JWT claim field abbreviated names may be a little terse, so here's a list of the more important ones:
- `jti` is the _JWT ID_. All JWTs have one and they are unique.
- `iat` is _Issued At_ - the UNIX date (number of seconds since 1970) when the JWT was issued.
- `iss` is the _Issuer_. For NATS JWTs it is the public key of the issuer. In the example above the entity is an account, so the issuer will be an operator. Thus the id will always start with the letter `O`.
- `sub` is the _Subject_ of the claim. In NATS JWTs it is the public key of the entity of the claim is for. In the example above, it is an Account, so the issuer will always start with the letter `A`.
On the example above, we see that there is one export in this account, it is public (`token_req` is `false` or not set), and it is a `stream`. So this account exports a public stream. With that information you can create an import on the public stream.

78
nats_tools/nas/mem_resolver.md Normal file
View File

@@ -0,0 +1,78 @@
## Memory Resolver
The `MEMORY` resolver is a built-in resolver for JWTs. It is mostly used by test setups but can be used to test the simplest of environments where there is one or very few accounts, and the account JWTs don’t change often.
The basic configuration for the server requires:
- The operator JWT
- `resolver` set to `MEMORY`
- `resolver_preload` set to an object where account public keys are mapped to account JWTs.
### Create Required Entities
Let’s create the setup:
```text
> nsc add operator -n memory
Generated operator key - private key stored "/Users/synadia/.nkeys/memory/memory.nk"
Success! - added operator "memory"
> nsc add account --name A
Generated account key - private key stored "/Users/synadia/.nkeys/memory/accounts/A/A.nk"
Success! - added account "A"
> nsc describe account -W
╭──────────────────────────────────────────────────────────────────────────────────────╮
│ Account Details │
├───────────────────────────┬──────────────────────────────────────────────────────────┤
│ Name │ A │
│ Account ID │ ACSU3Q6LTLBVLGAQUONAGXJHVNWGSKKAUA7IY5TB4Z7PLEKSR5O6JTGR │
│ Issuer ID │ ODWZJ2KAPF76WOWMPCJF6BY4QIPLTUIY4JIBLU4K3YDG3GHIWBVWBHUZ │
│ Issued │ 2019-04-30 20:21:34 UTC │
│ Expires │ │
├───────────────────────────┼──────────────────────────────────────────────────────────┤
│ Max Connections │ Unlimited │
│ Max Leaf Node Connections │ Unlimited │
│ Max Data │ Unlimited │
│ Max Exports │ Unlimited │
│ Max Imports │ Unlimited │
│ Max Msg Payload │ Unlimited │
│ Max Subscriptions │ Unlimited │
│ Exports Allows Wildcards │ True │
├───────────────────────────┼──────────────────────────────────────────────────────────┤
│ Imports │ None │
│ Exports │ None │
╰───────────────────────────┴──────────────────────────────────────────────────────────╯
> cat /Users/synadia/.nsc/nats/memory/accounts/A/A.jwt
eyJ0eXAiOiJqd3QiLCJhbGciOiJlZDI1NTE5In0.eyJqdGkiOiJPRFhJSVI2Wlg1Q1AzMlFJTFczWFBENEtTSDYzUFNNSEZHUkpaT05DR1RLVVBISlRLQ0JBIiwiaWF0IjoxNTU2NjU1Njk0LCJpc3MiOiJPRFdaSjJLQVBGNzZXT1dNUENKRjZCWTRRSVBMVFVJWTRKSUJMVTRLM1lERzNHSElXQlZXQkhVWiIsIm5hbWUiOiJBIiwic3ViIjoiQUNTVTNRNkxUTEJWTEdBUVVPTkFHWEpIVk5XR1NLS0FVQTdJWTVUQjRaN1BMRUtTUjVPNkpUR1IiLCJ0eXBlIjoiYWNjb3VudCIsIm5hdHMiOnsibGltaXRzIjp7InN1YnMiOi0xLCJjb25uIjotMSwibGVhZiI6LTEsImltcG9ydHMiOi0xLCJleHBvcnRzIjotMSwiZGF0YSI6LTEsInBheWxvYWQiOi0xLCJ3aWxkY2FyZHMiOnRydWV9fX0._WW5C1triCh8a4jhyBxEZZP8RJ17pINS8qLzz-01o6zbz1uZfTOJGvwSTS6Yv2_849B9iUXSd-8kp1iMXHdoBA
> nsc add user --name TA
Generated user key - private key stored “/Users/synadia/.nkeys/memory/accounts/A/users/TA.nk"
Generated user creds file “/Users/synadia/.nkeys/memory/accounts/A/users/TA.creds"
Success! - added user "TA" to "A"
```
### Create the Server Config
With the above entries, we can reference the operator JWT and the account JWT in a server configuration. Remember that your configuration will be in `$NSC_HOME/nats/<operator_name>/<operator_name>.jwt` for the operator. The account JWT will be in `$NSC_HOME/nats/<operator_name>/accounts/<account_name>/<account_name>.jwt`
```text
operator: /Users/synadia/.nsc/nats/memory/memory.jwt
resolver: MEMORY
resolver_preload: {
ACSU3Q6LTLBVLGAQUONAGXJHVNWGSKKAUA7IY5TB4Z7PLEKSR5O6JTGR: eyJ0eXAiOiJqd3QiLCJhbGciOiJlZDI1NTE5In0.eyJqdGkiOiJPRFhJSVI2Wlg1Q1AzMlFJTFczWFBENEtTSDYzUFNNSEZHUkpaT05DR1RLVVBISlRLQ0JBIiwiaWF0IjoxNTU2NjU1Njk0LCJpc3MiOiJPRFdaSjJLQVBGNzZXT1dNUENKRjZCWTRRSVBMVFVJWTRKSUJMVTRLM1lERzNHSElXQlZXQkhVWiIsIm5hbWUiOiJBIiwic3ViIjoiQUNTVTNRNkxUTEJWTEdBUVVPTkFHWEpIVk5XR1NLS0FVQTdJWTVUQjRaN1BMRUtTUjVPNkpUR1IiLCJ0eXBlIjoiYWNjb3VudCIsIm5hdHMiOnsibGltaXRzIjp7InN1YnMiOi0xLCJjb25uIjotMSwibGVhZiI6LTEsImltcG9ydHMiOi0xLCJleHBvcnRzIjotMSwiZGF0YSI6LTEsInBheWxvYWQiOi0xLCJ3aWxkY2FyZHMiOnRydWV9fX0._WW5C1triCh8a4jhyBxEZZP8RJ17pINS8qLzz-01o6zbz1uZfTOJGvwSTS6Yv2_849B9iUXSd-8kp1iMXHdoBA
}
```
Save the config at server.conf and start the server:
```text
> nats-server -c server.conf
```
Start a subscriber:
```text
> nats-sub -creds /Users/synadia/.nkeys/memory/accounts/A/users/TA.creds ">"
Listening on [>]
```

164
nats_tools/nas/nas_conf.md Normal file
View File

@@ -0,0 +1,164 @@
## Configuration
Basic configuration revolves around 4 settings:
- The store to read JWTs from
- The HTTP/S configuration
- NATS (for cases where updates are enabled)
- Logging
For complete information on please refer to the project's [Github](https://github.com/nats-io/nats-account-server).
### `nsc` Configuration
For a basic usage of the server you can specify the `-nsc` flag, and specify the path to an operator in your environment.
> If you have not yet created an operator or accounts, you'll need to do so before continuing. See [NSC](../nsc/README.md)
You can easily locate the path by running `nsc env` to print your `nsc` settings:
```text
> nsc env
╭──────────────────────────────────────────╮
│ NSC Environment │
├──────────────────┬─────┬─────────────────┤
│ Setting │ Set │ Effective Value │
├──────────────────┼─────┼─────────────────┤
│ $NKEYS_PATH │ No │ ~/.nkeys │
│ $NSC_HOME │ No │ ~/.nsc │
│ Config │ │ ~/.nsc/nsc.json │
├──────────────────┼─────┼─────────────────┤
│ Stores Dir │ │ ~/.nsc/nats │
│ Default Operator │ │ Test │
│ Default Account │ │ TestAccount │
│ Default Cluster │ │ │
╰──────────────────┴─────┴─────────────────╯
```
The path you are interested in the `Stores Dir`. This is the root of all operators, you'll also need the name of your operator. If your current operator is not listed, you can list all your available operators by doing:
```text
> nsc list operators
```
To start the `nats-account-server` with the operator `Test`:
```text
> nats-account-server -nsc ~/.nsc/nats/Test
2019/05/10 11:22:41.845148 [INF] starting NATS Account server, version 0.0-dev
2019/05/10 11:22:41.845241 [INF] server time is Fri May 10 11:22:41 CDT 2019
2019/05/10 11:22:41.845245 [INF] loading operator from /Users/synadia/.nsc/nats/Test/Test.jwt
2019/05/10 11:22:41.846367 [INF] creating a read-only store for the NSC folder at /Users/synadia/.nsc/nats/Test
2019/05/10 11:22:41.846459 [INF] NATS is not configured, server will not fire notifications on update
2019/05/10 11:22:41.855291 [INF] http listening on port 9090
2019/05/10 11:22:41.855301 [INF] nats-account-server is running
2019/05/10 11:22:41.855303 [INF] configure the nats-server with:
2019/05/10 11:22:41.855306 [INF] resolver: URL(http://localhost:9090/jwt/v1/accounts/)
```
By default the server will serve JWTs on the localhost at port 9090. The last line in the shown in the printout is important, that is the resolver URL you'll have to provide on your NATS server configuration. You'll also need the matching operator JWT which is on `~/.nsc/nats/Test/Test.jwt` if you are following the example above. On the server configuration you'll need to expand the `~` as necessary. Here's what my NATS server configuration looks like:
```text
operator: /Users/synadia/.nsc/nats/Test/Test.jwt
resolver: URL(http://localhost:9090/jwt/v1/accounts/)
```
Note that servers you create with the `-nsc` option (or store option) are read-only. This means that the server will not accept POST requests to update the JWT store.
### Directory Configuration
You can start a server using a plain directory. In this case you'll be responsible for adding any JWT that you want resolved.
> The server looks for account JWTs by using the public key of the account as the file name followed by the extension `.jwt`. The server will not introspect the JWTs, so if you don't name the files correctly, it will fail to find them or serve a JWT that doesn't match the requested account.
```text
> mkdir /tmp/jwts
nats-account-server -dir /tmp/jwts
2019/05/10 11:33:40.501305 [INF] starting NATS Account server, version 0.0-dev
2019/05/10 11:33:40.501383 [INF] server time is Fri May 10 11:33:40 CDT 2019
2019/05/10 11:33:40.501404 [INF] creating a store at /tmp/jwts
2019/05/10 11:33:40.501430 [INF] NATS is not configured, server will not fire notifications on update
2019/05/10 11:33:40.510273 [INF] http listening on port 9090
2019/05/10 11:33:40.510283 [INF] nats-account-server is running
2019/05/10 11:33:40.510285 [INF] configure the nats-server with:
2019/05/10 11:33:40.510291 [INF] resolver: URL(http://localhost:9090/jwt/v1/accounts/)
```
Configuration for the NATS server is the same as in the previous example:
```text
operator: /Users/synadia/.nsc/nats/Test/Test.jwt
resolver: URL(http://localhost:9090/jwt/v1/accounts/)
```
### Configuration File
While the `-nsc` and `-dir` store flags are sufficient for some very simple developer setups, any production or non-read-only server will require a configuration file.
Let's take a look at the configuration options:
#### Configuration Options
| Option | Description |
| :- | :- |
| `http` | An `http` configuration block specifying HTTP options. |
| `logging` | A `logging` configuration block specifying server logging options. |
| `nats` | A `nats` configuration block specifying NATS connection information for the account server to push JWT changes to a NATS server. |
| `operatorjwtpath` | The path to an operator JWT. Required for non-read-only servers. Only JWTs signed by the operator (or one of it's signing keys) are accepted. |
| `store` | A `store` configuration block specifying store options. |
| `systemaccountjwtpath` | Path to an Account JWT that should be returned as the system account. |
#### `store` Configuration
| Option | Description |
| :- | :- |
| `dir` | Configures a directory as a store. |
| `nsc` | Configures an nsc read-only store. The value should be the path to an operator _directory_. Option is mutually exlusive with `dir`. |
| `readonly` | If `true`, the store will not accept POST requests. Note that to receive requests, the store must also have `operatorjwtpath` specified as a root option. |
| `shard` | If `true`, JWTs are sharded in the store directory. |
### `logging` Options
| Option | Description |
| :- | :- |
| `time` | If `true`, a timestamp is added to log messages. |
| `debug` | If `true`, debug messages are logged. |
| `trace` | If `true`, trace messages are logged. |
| `colors` | If `true`, messages are logged using ANSI color escape sequences. |
| `pid` | If `true`, the process id for the server is added to log messages. |
### `http` Options
| Option | Description |
| :- | :- |
| `host` | Interface to listen for requests on. |
| `port` | Port to listen for requests on. |
| `readtimeout` | Max amount of time in milliseconds to wait for a http read operation to complete. |
| `writetimeout` | Max amount of time in milliseconds to wait for a http write operation to complete. |
### `nats` Options
| Option | Description |
| :- | :- |
| `servers` | List of NATS servers for the account server to use when connecting to a NATS server to publish updates. |
| `connecttimeout` | Max amount of time in milliseconds to wait for a NATS connection. |
| `reconnecttimewait` | Amount of time in milliseconds to between NATS server reconnect attempts. |
| `tls` | A `tls` configuration block. |
| `usercredentials` | A credentials _creds_ file for connecting to the NATS server. Account must be a member of a system account. |
### `tls` Options
| Option | Description |
| :- | :- |
| `root` | filepath to the CA certificate. |
| `cert` | filepath to the certificate. |
| `cert` | filepath to the certificate key. |