TrueCloudLab/frostfs-s3-gw
17
3
Fork 19
Code Issues 28 Pull requests 7 Projects Releases 17 Packages Activity Actions

[#396] Update docs

Browse source 
Signed-off-by: Angira Kekteeva <kira@nspcc.ru>
This commit is contained in:
Angira Kekteeva 2022-04-06 18:31:32 +04:00 committed by Alex Vanin
parent 3c5c2f20d8
commit 6a89ebb257
2 changed files with 207 additions and 164 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

176
docs/authmate.md
View file

@ -18,22 +18,18 @@ token, the object needs to be stored in a container available for the gateway
to read, and it needs to be encrypted with this gateway's key (among others
potentially).
## Variables
Authmate supports the following variables to decrypt wallets provided by `--wallet` and `--gate-wallet`
parameters respectevely:
* `AUTHMATE_WALLET_PASSPHRASE`
* `AUTHMATE_WALLET_GATE_PASSPHRASE`
If the passphrase is not specified, you will be asked to enter the password interactively:
```
Enter password for wallet.json >
```
1. [Generation of wallet](#Generation of wallet)
2. [Issuance of a secret](#Issuance of a secret)
1. [CLI parameters](#CLI parameters)
2. [Bearer tokens](#Bearer tokens)
3. [Session tokens](#Session tokens)
4. [Containers policy](#Containers policy)
3. [Obtainment of a secret](#Obtainment of a secret access key)
## Generation of wallet
To generate wallets for gateways, run the following command:
To generate a wallet for a gateway, run the following command:
```
```shell
$ ./neo-go wallet init -a -w wallet.json
Enter the name of the account > AccountTestName
@ -74,8 +70,8 @@ Confirm passphrase >
wallet successfully created, file location is wallet.json
```
To get public key from wallet run:
```
To get public key from the wallet:
```shell
$ ./bin/neo-go wallet dump-keys -w wallet.json
NhLQpDnerpviUWDF77j5qyjFgavCmasJ4p (simple signature contract):
@ -84,32 +80,93 @@ NhLQpDnerpviUWDF77j5qyjFgavCmasJ4p (simple signature contract):
## Issuance of a secret
To issue a secret means to create a Bearer and (optionally) Session tokens and
To issue a secret means to create a Bearer and, optionally, Session tokens and
put them as an object into a container on the NeoFS network.
By default, the tool creates a container with a name the same as container ID in NeoFS and ACL
0x3c8c8cce (all operations are forbidden for `OTHERS` and `BEARER` user groups,
except for `GET`).
### CLI parameters
Also, you can put the tokens into an existing container via `--container-id`
parameter, but this way is **not recommended**.
**Required parameters:**
* `--wallet` - a path to a wallet `.json` file. You can provide a passphrase to decrypt
a wallet via environment variable `AUTHMATE_WALLET_PASSPHRASE`, or you will be asked to enter a passphrase
interactively. You can also specify an account address to use from a wallet using the `--address` parameter.
* `--peer` - address of a NeoFS peer to connect to
* `--gate-public-key` -- public `secp256r1` 33-byte short key of a gate (use flags repeatedly for multiple gates). The tokens are encrypted
by a set of gateway keys, so you need to pass them as well.
The tokens are encrypted by a set of gateway keys, so you need to pass them as well.
You can issue a secret using the parameters above only. The tool will
1. create a new container
1. without a friendly name
2. with ACL `0x3c8c8cce` - all operations are forbidden for `OTHERS` and `BEARER` user groups, except for `GET`
3. with policy `REP 2 IN X CBF 3 SELECT 2 FROM * AS X`
2. put bearer and session tokens with default rules (details in [Bearer tokens](#Bearer tokens) and
[Session tokens](#Session tokens))
Creation of the bearer token is mandatory, while creation of the session token is
optional.
E.g.:
```shell
$ neofs-authmate issue-secret --wallet wallet.json \
--peer 192.168.130.71:8080 \
--gate-public-key 0313b1ac3a8076e155a7e797b24f0b650cccad5941ea59d7cfd51a024a8b2a06bf\
--gate-public-key 0317585fa8274f7afdf1fc5f2a2e7bece549d5175c4e5182e37924f30229aef967
Rules for bearer token can be set via param `bearer-rules` (json-string and file path allowed), if it is not set,
it will be auto-generated with values:
Enter password for wallet.json >
{
"access_key_id": "5g933dyLEkXbbAspouhPPTiyLZRg4axBW1axSPD87eVT0AiXsH4AjYy1iTJ4C1WExzjBrSobJsQFWEyKLREe5sQYM",
"secret_access_key": "438bbd8243060e1e1c9dd4821756914a6e872ce29bf203b68f81b140ac91231c",
"owner_private_key": "274fdd6e71fc6a6b8fe77bec500254115d66d6d17347d7db0880d2eb80afc72a",
"container_id":"5g933dyLEkXbbAspouhPPTiyLZRg4axBW1axSPD87eVT"
}
```
`access_key_id` and `secret_access_key` are AWS credentials that you can use with any S3 client.
`access_key_id` consists of Base58 encoded containerID(cid) and objectID(oid) stored on the NeoFS network and containing
the secret. Format of `access_key_id`: `%cid0%oid`, where 0(zero) is a delimiter.
**Optional parameters:**
* `--container-id` - you can put the tokens into an existing container, but this way is ***not recommended***.
* `--container-friendly-name` -- name of a container with tokens, by default container will not have a friendly name
* `--container-placement-policy` - placement policy of auth container to put the secret into. Default value is
`REP 2 IN X CBF 3 SELECT 2 FROM * AS X`
* `--lifetime`-- lifetime of tokens. For example 50h30m (note: max time unit is an hour so to set a day you should use
24h). Default value is `720h` (30 days). It will be ceil rounded to the nearest amount of epoch
* `--aws-cli-credentials` - path to the aws cli credentials file, where authmate will write `access_key_id` and
`secret_access_key` to
### Bearer tokens
Creation of the bearer tokens is mandatory.
Rules for bearer token can be set via parameter `--bearer-rules` (json-string and file path allowed):
```shell
$ neofs-authmate issue-secret --wallet wallet.json \
--peer 192.168.130.71:8080 \
--gate-public-key 0313b1ac3a8076e155a7e797b24f0b650cccad5941ea59d7cfd51a024a8b2a06bf \
--bearer-rules bearer-rules.json
```
where content of `bearer-rules.json`:
```json
{
"records": [
{"operation": "PUT", "action": "ALLOW", "filters": [], "targets": [{"role": "OTHERS", "keys": []}]},
{"operation": "GET", "action": "ALLOW", "filters": [], "targets": [{"role": "OTHERS", "keys": []}]},
{"operation": "HEAD", "action": "ALLOW", "filters": [], "targets": [{"role": "OTHERS", "keys": []}]},
{"operation": "DELETE", "action": "ALLOW", "filters": [], "targets": [{"role": "OTHERS", "keys": []}]},
{"operation": "SEARCH", "action": "ALLOW", "filters": [], "targets": [{"role": "OTHERS", "keys": []}]},
{"operation": "GETRANGE", "action": "ALLOW", "filters": [], "targets": [{"role": "OTHERS", "keys": []}]},
{"operation": "GETRANGEHASH", "action": "ALLOW", "filters": [], "targets": [{"role": "OTHERS", "keys": []}]}
]
}
```
If bearer rules are not set, a token will be auto-generated with a value:
```json
{
"version": {
"major": 2,
"minor": 6
"minor": 11
},
"containerID": {
"value": "%CID"
"value": null
},
"records": [
{
@ -127,16 +184,18 @@ it will be auto-generated with values:
}
```
With session token, there is 3 options:
* append `--session-token` parameter with your custom rules in json format (as a string or file path, see an example below)
### Session tokens
**NB!** To create buckets in NeoFS it's necessary to have session tokens with `PUT` and `SETEACL` permissions, that's why
the authmate creates a `SETEACL` session token automatically in case when a user specified the token rule with `PUT` and
forgot about the rule with `SETEACL`.
* append `--session-token` parameter with the value `none` -- no session token will be created
* skip the parameter and `authmate` will create and put session tokens with default rules:
With session token, there are 3 options:
1. append `--session-token` parameter with your custom rules in json format (as a string or file path). E.g.:
```shell
$ neofs-authmate issue-secret --wallet wallet.json \
--peer 192.168.130.71:8080 \
--gate-public-key 0313b1ac3a8076e155a7e797b24f0b650cccad5941ea59d7cfd51a024a8b2a06bf \
--session-token session.json
```
where content of `session.json`:
```json
[
{
"verb": "PUT",
@ -152,14 +211,24 @@ forgot about the rule with `SETEACL`.
"verb": "SETEACL",
"wildcard": true,
"containerID": null
},
}
]
```
> **_NB!_** To create buckets in NeoFS it's necessary to have session tokens with `PUT` and `SETEACL` permissions, that's why
the authmate creates a `SETEACL` session token automatically in case when a user specified the token rule with `PUT` and
forgot about the rule with `SETEACL`.
2. append `--session-token` parameter with the value `none` -- no session token will be created
3. skip the parameter, and `authmate` will create session tokens with default rules (the same as in `session.json`
in example above)
### Containers policy
Rules for mapping of `LocationConstraint` ([aws spec](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateBucket.html#API_CreateBucket_RequestBody))
to `PlacementPolicy` ([neofs spec](https://github.com/nspcc-dev/neofs-spec/blob/master/01-arch/02-policy.md))
can be set via param `container-policy` (json-string and file path allowed):
```
can be set via parameter `--container-policy` (json-string and file path allowed):
```json
{
"rep-3": "REP 3",
"complex": "REP 1 IN X CBF 1 SELECT 1 FROM * AS X",
@ -167,40 +236,15 @@ can be set via param `container-policy` (json-string and file path allowed):
}
```
Example of a command to issue a secret with custom rules for multiple gates:
```
$ ./neofs-authmate issue-secret --wallet wallet.json \
--peer 192.168.130.71:8080 \
--bearer-rules '{"records":[{"operation":"PUT","action":"ALLOW","filters":[],"targets":[{"role":"OTHERS","keys":[]}]}]}' \
--gate-public-key 0313b1ac3a8076e155a7e797b24f0b650cccad5941ea59d7cfd51a024a8b2a06bf \
--gate-public-key 0317585fa8274f7afdf1fc5f2a2e7bece549d5175c4e5182e37924f30229aef967 \
--session-token '[{"verb":"DELETE","wildcard":false,"containerID":{"value":"%CID"}}]'
--container-policy '{"rep-3": "REP 3"}'
Enter password for wallet.json >
{
"access_key_id": "5g933dyLEkXbbAspouhPPTiyLZRg4axBW1axSPD87eVT0AiXsH4AjYy1iTJ4C1WExzjBrSobJsQFWEyKLREe5sQYM",
"secret_access_key": "438bbd8243060e1e1c9dd4821756914a6e872ce29bf203b68f81b140ac91231c",
"owner_private_key": "274fdd6e71fc6a6b8fe77bec500254115d66d6d17347d7db0880d2eb80afc72a",
"container_id":"5g933dyLEkXbbAspouhPPTiyLZRg4axBW1axSPD87eVT"
}
```
Access key ID and secret access key are AWS credentials that you can use with
any S3 client.
Access key ID consists of Base58 encoded containerID(cid) and objectID(oid) stored on the NeoFS network and containing
the secret. Format of access_key_id: `%cid0%oid`, where 0(zero) is a delimiter.
## Obtainment of a secret access key
You can get a secret access key associated with an access key ID by obtaining a
secret stored on the NeoFS network. Here is an example of providing one password (for `wallet.json`) via env variable
and the other (for `gate-wallet.json`) interactively:
```
```shell
$ AUTHMATE_WALLET_PASSPHRASE=some-pwd \
./neofs-authmate obtain-secret --wallet wallet.json \
neofs-authmate obtain-secret --wallet wallet.json \
--peer 192.168.130.71:8080 \
--gate-wallet gate-wallet.json \
--access-key-id 5g933dyLEkXbbAspouhPPTiyLZRg4axBW1axSPD87eVT0AiXsH4AjYy1iTJ4C1WExzjBrSobJsQFWEyKLREe5sQYM

183
docs/configuration.md
View file

@ -1,37 +1,51 @@
# Configuration
Actually, everything available as a CLI parameter can also be specified via
environment variables, so they're not specifically mentioned in most cases
(see `--help` also). If you prefer a config file you can use it in yaml format.
There are three ways to configure the S3 GW:
1. CLI parameters
2. YAML file
3. Environment variables
## Nodes and weights
Everything available as a CLI parameter can also be specified via environment variables and almost everything can be
specified via `.yaml` configuration file.
But **not vice versa**, some parameters can be configured only with environment variables/configuration file.
Most of these parameters have default values, therefore, these ways to configure the gateway are optional and
basic configuration can be completed with CLI parameters only.
1. [CLI parameters](#CLI parameters)
1. [Nodes and weights](#Nodes and weights)
2. [Wallet](#Wallet)
3. [Binding and TLS](#Listening on address and TLS)
4. [RPC endpoint and resolving of bucket names](#RPC endpoint and resolving of bucket names)
5. [Processing of requests](#Processing of requests)
6. [Connection to NeoFS](#Connection to NeoFS)
7. [Monitoring and metrics](#Monitoring and metrics)
2. [YAML file and environment variables](#YAML file and environment variables)
1. [Notifications](#Notifications)
## CLI parameters
### Nodes and weights
You can specify multiple `-p` options to add more NeoFS nodes; this will make
a gateway spread requests equally among them (using weight 1 for every node):
```
```shell
$ neofs-s3-gw -p 192.168.130.72:8080 -p 192.168.130.71:8080
```
If you want some specific load distribution proportions, use weights, but keep it in mind that they
can only be specified via environment variables:
If you want some specific load distribution proportions, use weights and priorities, they
can only be specified via environment variables or configuration file.
```
$ S3_GW_PEERS_0_ADDRESS=192.168.130.72:8080 S3_GW_PEERS_0_WEIGHT=9 \
S3_GW_PEERS_1_ADDRESS=192.168.130.71:8080 S3_GW_PEERS_1_WEIGHT=1 neofs-s3-gw
```
This command will make gateway use 192.168.130.72 for 90% of the requests and
192.168.130.71 for the remaining 10%.
### Wallet
## Key
Wallet (`--wallet`) is a mandatory parameter. It is a path to a wallet file. You can provide a passphrase to decrypt
a wallet via env variable or conf file, or you will be asked to enter a password interactively.
You can also specify an account address to use from a wallet using the `--address` parameter.
Wallet (`--wallet`) is a mandatory parameter. It is a path to a wallet file. You can provide password to decrypt a wallet
via `S3_GW_WALLET_PASSPHRASE` variable or you will be asked to enter a password interactively.
You can also specify an account address to use from a wallet using `--address` parameter.
### Listening on address and TLS
## Binding and TLS
Gateway binds to `0.0.0.0:8080` by default, and you can change that with
`--listen_address` option.
Gateway listens on `0.0.0.0:8080` by default, and you can change that with the `--listen_address` option.
It can also provide TLS interface for its users, just specify paths to the key and
certificate files via `--tls.key_file` and `--tls.cert_file` parameters. Note
@ -39,92 +53,77 @@ that using these options makes gateway TLS-only, if you need to serve both TLS
and plain text you either have to run two gateway instances or use some
external redirecting solution.
Example to bind to `192.168.130.130:443` and serve TLS there (keys and nodes
Example to bind to `192.168.130.130:443` and serve TLS there (keys and nodes are
omitted):
```
```shell
$ neofs-s3-gw --listen_address 192.168.130.130:443 \
--tls.key_file=key.pem --tls.cert_file=cert.pem
```
## Monitoring and metrics
### RPC endpoint and resolving of bucket names
To set RPC endpoint specify a value of parameter `-r` or `--rpc-endpoint`. The parameter is **required if** another
parameter's `--resolve-order` value contains `nns`.
```shell
$ neofs-s3-gw --rpc-endpoint http://morph-chain.neofs.devenv:30333/ --resolve-order nns,dns
```
### Processing of requests
Maximum number of clients whose requests can be handled by the gateway can be specified by the value of
`--max_clients_count` parameter, the default value is 100.
`--max_clients_deadline` defines deadline after which the gate sends error `RequestTimeout` to a client, default value
is 30 seconds.
```shell
$ neofs-s3-gw --max_clients_count 150 --max_clients_deadline 1m
```
### Connection to NeoFS
Timeout to connect to NeoFS nodes can be set with `--connect_timeout` (default 30s)
and timeout to check node health during rebalance`--request_timeout` (default 15s).
Also, interval to check node health can be specified by `--rebalance_timer` value, default value is 15s.
```shell
$ neofs-s3-gw --request_timeout 15s --connect_timeout 1m --rebalance_timer 1h
```
### Monitoring and metrics
Pprof and Prometheus are integrated into the gateway, but not enabled by
default. To enable them, use `--pprof` and `--metrics` flags or
`S3_GW_PPROF`/`S3_GW_METRICS` environment variables.
## Yaml file
Configuration file is optional and can be used instead of environment variables/other parameters.
It can be specified with `--config` parameter:
```
## YAML file and environment variables
Example of YAML configuration file: [.yaml-example](/config/config.yaml)
Examples of environment variables: [.env-example](/config/config.env).
A path to a configuration file can be specified with `--config` parameter:
```shell
$ neofs-s3-gw --config your-config.yaml
```
Configuration file example:
```
listen_address: 0.0.0.0:8084
Parameters of the following groups can be configured via `.yaml` file or environment variables only:
1. logging -- logging level
2. caching -- lifetime and size for each cache
3. notifications
4. CORS
5. default policy of placing containers in NeoFS
wallet:
passphrase: 123456
### Notifications
logger:
level: debug
You can turn on notifications about successful completions of basic operations, and the gateway will send notifications
via NATS JetStream.
peers:
0:
address: s01.neofs.devenv:8080
weight: 1
```
To enable notifications you need:
1. to configure the NATS server with JetStream
2. to specify NATS parameters for the S3 GW. It's ***necessary*** to define a values of `nats.enable` or
`S3_GW_NATS_ENABLED` as `True`
3. to configure notifications in a bucket
To know the nesting level of the variable, you need to cut off the prefix `S3_GW` from the variable and split the rest parts by `_`.
For example, variable `S3_GW_PEERS_0_WEIGHT=1` will be transformed to:
```
peers:
0:
weight: 1
```
If a parameter doesn't support environment variable (e.g. `--listen_address 0.0.0.0:8084`) form, it is used as:
```
listen_address: 0.0.0.0:8084
```
### Default policy of placing containers in NeoFS
If a user sends a request `CreateBucket` and doesn't define policy for placing of a container in NeoFS, the S3 Gateway
will put the container with default policy. It can be specified via environment variable, e.g.:
```
S3_GW_DEFAULT_POLICY=REP 1 CBF 1 SELECT 1 FROM *
```
or via `.yaml` config file, e.g.:
```
default_policy: REP 1
```
If the value is not set at all it will be set as `REP 3`.
### Cache parameters
Parameters for caches in s3-gw can be specified in a .yaml config file. E.g.:
```
cache:
objects:
lifetime: 300s
size: 150
list:
lifetime: 1m
size: 100
names:
lifetime: 1m
size: 1000
buckets:
lifetime: 1m
size: 500
system:
lifetime: 2m
size: 1000
accessbox:
lifetime: 5m
size: 10
```
If invalid values are set, the gateway will use default values instead.