From 6a89ebb2576929da027483ab47dd41ab7a4541e8 Mon Sep 17 00:00:00 2001 From: Angira Kekteeva Date: Wed, 6 Apr 2022 18:31:32 +0400 Subject: [PATCH] [#396] Update docs Signed-off-by: Angira Kekteeva --- docs/authmate.md | 188 ++++++++++++++++++++++++++---------------- docs/configuration.md | 183 ++++++++++++++++++++-------------------- 2 files changed, 207 insertions(+), 164 deletions(-) diff --git a/docs/authmate.md b/docs/authmate.md index c1d8e0da..756443f6 100644 --- a/docs/authmate.md +++ b/docs/authmate.md @@ -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. - -Creation of the bearer token is mandatory, while creation of the session token is -optional. - -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: +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)) +E.g.: +```shell +$ neofs-authmate issue-secret --wallet wallet.json \ + --peer 192.168.130.71:8080 \ + --gate-public-key 0313b1ac3a8076e155a7e797b24f0b650cccad5941ea59d7cfd51a024a8b2a06bf\ + --gate-public-key 0317585fa8274f7afdf1fc5f2a2e7bece549d5175c4e5182e37924f30229aef967 + + 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,43 +236,18 @@ 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: -``` - $ AUTHMATE_WALLET_PASSPHRASE=some-pwd \ - ./neofs-authmate obtain-secret --wallet wallet.json \ - --peer 192.168.130.71:8080 \ - --gate-wallet gate-wallet.json \ - --access-key-id 5g933dyLEkXbbAspouhPPTiyLZRg4axBW1axSPD87eVT0AiXsH4AjYy1iTJ4C1WExzjBrSobJsQFWEyKLREe5sQYM +```shell +$ AUTHMATE_WALLET_PASSPHRASE=some-pwd \ +neofs-authmate obtain-secret --wallet wallet.json \ +--peer 192.168.130.71:8080 \ +--gate-wallet gate-wallet.json \ +--access-key-id 5g933dyLEkXbbAspouhPPTiyLZRg4axBW1axSPD87eVT0AiXsH4AjYy1iTJ4C1WExzjBrSobJsQFWEyKLREe5sQYM Enter password for gate-wallet.json > { diff --git a/docs/configuration.md b/docs/configuration.md index 0bff1dfc..722ad247 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -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.