EliChin/frostfs-s3-gw
1
0
Fork 0
forked from TrueCloudLab/frostfs-s3-gw
Code Issues Pull requests Projects Releases Packages Wiki Activity

[#206] docs: Language check

Browse source 
Signed-off-by: Elizaveta Chichindaeva <elizaveta@nspcc.ru>
This commit is contained in:
Elizaveta Chichindaeva 2021-08-19 15:46:41 +03:00 committed by Stanislav Bogatyrev
parent e2f4872180
commit a0f59bb348
3 changed files with 47 additions and 47 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

38
docs/authmate.md
View file

@ -4,22 +4,22 @@ Authmate is a tool to create gateway AWS credentials. AWS users
are authenticated with access key IDs and secrets, while NeoFS users are are authenticated with access key IDs and secrets, while NeoFS users are
authenticated with key pairs. To complicate things further we have S3 gateway authenticated with key pairs. To complicate things further we have S3 gateway
that usually acts on behalf of some user, but user doesn't necessarily want to that usually acts on behalf of some user, but user doesn't necessarily want to
give his keys to the gateway. give their keys to the gateway.
To solve this we use NeoFS bearer tokens that are signed by the owner (NeoFS To solve this, we use NeoFS bearer tokens that are signed by the owner (NeoFS
"user") and that can implement any kind of policy for NeoFS requests allowed "user") and that can implement any kind of policy for NeoFS requests allowed
using this token. But tokens can't be used directly as AWS credentials, thus using this token. However, tokens can't be used as AWS credentials directly, thus
they're stored on NeoFS as regular objects and access key ID is just an they're stored on NeoFS as regular objects, and access key ID is just an
address of this object while secret is generated randomly. address of this object while secret is generated randomly.
Tokens are not stored on NeoFS in plaintext, they're encrypted with a set of Tokens are not stored on NeoFS in plaintext, they're encrypted with a set of
gateway keys. So in order for gateway to be able to successfully extract bearer gateway keys. So in order for a gateway to be able to successfully extract bearer
token the object needs to be stored in a container available for the gateway 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 to read, and it needs to be encrypted with this gateway's key (among others
potentially). potentially).
## Variables ## Variables
Authmate support the following variables to decrypt wallets provided by `--wallet` and `--gate-wallet` Authmate supports the following variables to decrypt wallets provided by `--wallet` and `--gate-wallet`
parameters respectevely: parameters respectevely:
* `AUTHMATE_WALLET_PASSPHRASE` * `AUTHMATE_WALLET_PASSPHRASE`
* `AUTHMATE_WALLET_GATE_PASSPHRASE` * `AUTHMATE_WALLET_GATE_PASSPHRASE`
@ -84,20 +84,20 @@ NhLQpDnerpviUWDF77j5qyjFgavCmasJ4p (simple signature contract):
## Issuance of a secret ## 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. put them as an object into a container on the NeoFS network.
By default, the tool creates the container with a name `auth-container` and ACL By default, the tool creates a container with a name `auth-container` and ACL
0x3c8c8cce (all operations are forbidden for `OTHERS` and `BEARER` user groups, 0x3c8c8cce (all operations are forbidden for `OTHERS` and `BEARER` user groups,
except for `GET`). except for `GET`).
Also, you can put the tokens into existing container via `--container-id` Also, you can put the tokens into an existing container via `--container-id`
parameter, but this way is **not recommended**. parameter, but this way is **not recommended**.
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, and creation of the session token is Creation of the bearer token is mandatory, while creation of the session token is
optional. If you want to add the session token you need to add a parameter optional. If you want to add the session token, you need to add a parameter
`create-session-token`. `create-session-token`.
Rules for bearer token can be set via param `bearer-rules` (json-string and file path allowed), if it is not set, Rules for bearer token can be set via param `bearer-rules` (json-string and file path allowed), if it is not set,
@ -128,7 +128,7 @@ it will be auto-generated with values:
} }
``` ```
Rules for session token can be set via param `session-rules` (json-string and file path allowed), default value is: Rules for a session token can be set via param `session-rules` (json-string and file path allowed), the default value is:
``` ```
{ {
"verb": "PUT", "verb": "PUT",
@ -137,8 +137,8 @@ Rules for session token can be set via param `session-rules` (json-string and fi
} }
``` ```
If `session-rules` is set, but `create-session-token` is not, the session If `session-rules` are set, but `create-session-token` is not, no session
token will not be created. token will be created.
Rules for mapping of `LocationConstraint` ([aws spec](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateBucket.html#API_CreateBucket_RequestBody)) 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)) to `PlacementPolicy` ([neofs spec](https://github.com/nspcc-dev/neofs-spec/blob/master/01-arch/02-policy.md))
@ -179,9 +179,9 @@ the secret. Format of access_key_id: `%cid0%oid`, where 0(zero) is a delimiter.
## Obtainment of a secret access key ## Obtainment of a secret access key
You can get a secret access key associated with access key ID by obtaining a You can get a secret access key associated with an access key ID by obtaining a
secret stored on the NeoFS network. Here example of providing one password (for `wallet.json`) via env variable secret stored on the NeoFS network. Here is an example of providing one password (for `wallet.json`) via env variable
and other (for `gate-wallet.json`) interactively: and the other (for `gate-wallet.json`) interactively:
``` ```
$ AUTHMATE_WALLET_PASSPHRASE=some-pwd \ $ AUTHMATE_WALLET_PASSPHRASE=some-pwd \

20
docs/aws_cli.md
View file

@ -4,7 +4,7 @@
### Credentials ### Credentials
To configure basic settings that the AWS CLI uses to interact with the Gateway, do the following steps: To configure basic settings that the AWS CLI uses to interact with the Gateway, follow steps below:
1. issue a secret with neofs-authmate tool (see [NeoFS Authmate] (#neofs-authmate)) 1. issue a secret with neofs-authmate tool (see [NeoFS Authmate] (#neofs-authmate))
2. execute the command 2. execute the command
@ -22,13 +22,13 @@ Default output format [none]: json
## Basic usage ## Basic usage
> **_NOTE:_** To specify IP and port of the gate, append `--endpoint-url https://%IP:%PORT` to your commands. > **_NOTE:_** To specify the IP and the port of the gate, append `--endpoint-url https://%IP:%PORT` to your commands.
### Bucket ### Bucket
#### Obtainment of a list of buckets #### Obtainment of a list of buckets
To view the list of the buckets in the NeoFS node, to which the gateway is connected, enter the command: To view the list of the buckets in the NeoFS node, to which the gateway is connected, enter the following command:
``` ```
$ aws s3 ls $ aws s3 ls
``` ```
@ -37,7 +37,7 @@ $ aws s3 ls
At this moment, the gateway supports only canned ACL and doesn't support the setting of location constraints. At this moment, the gateway supports only canned ACL and doesn't support the setting of location constraints.
To create a bucket, run the command: To create a bucket, run the following command:
``` ```
$ aws s3api create-bucket --bucket %BUCKET_NAME --acl %ACL $ aws s3api create-bucket --bucket %BUCKET_NAME --acl %ACL
``` ```
@ -62,15 +62,15 @@ $ aws s3api list-objects --bucket %BUCKET_NAME
#### Upload of a file #### Upload of a file
To upload the file into a bucket in the NeoFS network, run the following command: To upload a file into a bucket in the NeoFS network, run the following command:
``` ```
$ aws s3api put-object --bucket %BUCKET_NAME --key %OBJECT_KEY --body %FILEPATH $ aws s3api put-object --bucket %BUCKET_NAME --key %OBJECT_KEY --body %FILEPATH
``` ```
where %OBJECT_KEY is a filename of an object in NeoFS where %OBJECT_KEY is the filename of an object in NeoFS
#### Upload of a dir #### Upload of a dir
To upload the dir into a bucket in the NeoFS network, run the following command: To upload a dir into a bucket in the NeoFS network, run the following command:
``` ```
$ aws s3 sync %DIRPATH s3://%BUCKET_NAME $ aws s3 sync %DIRPATH s3://%BUCKET_NAME
@ -78,15 +78,15 @@ $ aws s3 sync %DIRPATH s3://%BUCKET_NAME
#### Download of a file #### Download of a file
To download the file from a bucket in the NeoFS Network, execute: To download a file from a bucket in the NeoFS Network, execute:
``` ```
$ aws s3api get-object --bucket %BUCKET_NAME --key %OBJECT_KEY %OUTFILE $ aws s3api get-object --bucket %BUCKET_NAME --key %OBJECT_KEY %OUTFILE
``` ```
where %OUTFILE is a file to store object content. where %OUTFILE is the file to store object content.
#### Deletion of a file #### Deletion of a file
To delete the file: To delete a file:
``` ```
$ aws s3api delete-object --bucket %BUCKET_NAME --key %FILE_NAME $ aws s3api delete-object --bucket %BUCKET_NAME --key %FILE_NAME
``` ```

32
docs/configuration.md
View file

@ -1,39 +1,39 @@
# Configuration # Configuration
In general, everything available as CLI parameter can also be specified via Actually, everything available as a CLI parameter can also be specified via
environment variables, so they're not specifically mentioned in most cases 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. (see `--help` also). If you prefer a config file you can use it in yaml format.
## Nodes and weights ## Nodes and weights
You can specify multiple `-p` options to add more NeoFS nodes, this will make You can specify multiple `-p` options to add more NeoFS nodes; this will make
gateway spread requests equally among them (using weight 1 for every node): a gateway spread requests equally among them (using weight 1 for every node):
``` ```
$ neofs-s3-gw -p 192.168.130.72:8080 -p 192.168.130.71:8080 $ 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 they If you want some specific load distribution proportions, use weights, but keep it in mind that they
can only be specified via environment variables: can only be specified via environment variables:
``` ```
$ HTTP_GW_PEERS_0_ADDRESS=192.168.130.72:8080 HTTP_GW_PEERS_0_WEIGHT=9 \ $ HTTP_GW_PEERS_0_ADDRESS=192.168.130.72:8080 HTTP_GW_PEERS_0_WEIGHT=9 \
HTTP_GW_PEERS_1_ADDRESS=192.168.130.71:8080 HTTP_GW_PEERS_1_WEIGHT=1 neofs-s3-gw HTTP_GW_PEERS_1_ADDRESS=192.168.130.71:8080 HTTP_GW_PEERS_1_WEIGHT=1 neofs-s3-gw
``` ```
This command will make gateway use 192.168.130.72 for 90% of requests and This command will make gateway use 192.168.130.72 for 90% of the requests and
192.168.130.71 for remaining 10%. 192.168.130.71 for the remaining 10%.
## Key ## Key
Wallet (`--wallet`) is mandatory parameter. It is a path to wallet file. You can provide password to decrypt wallet 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 the password interactively. via `S3_GW_WALLET_PASSPHRASE` variable or you will be asked to enter a password interactively.
You also can specify account address to use from wallet using `--address` parameter. You can also specify an account address to use from a wallet using `--address` parameter.
## Binding and TLS ## Binding and TLS
Gateway binds to `0.0.0.0:8080` by default and you can change that with Gateway binds to `0.0.0.0:8080` by default, and you can change that with
`--listen_address` option. `--listen_address` option.
It can also provide TLS interface for its users, just specify paths to key and 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 certificate files via `--tls.key_file` and `--tls.cert_file` parameters. Note
that using these options makes gateway TLS-only, if you need to serve both TLS 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 and plain text you either have to run two gateway instances or use some
@ -50,7 +50,7 @@ $ neofs-s3-gw --listen_address 192.168.130.130:443 \
## Monitoring and metrics ## Monitoring and metrics
Pprof and Prometheus are integrated into the gateway, but not enabled by Pprof and Prometheus are integrated into the gateway, but not enabled by
default. To enable them use `--pprof` and `--metrics` flags or default. To enable them, use `--pprof` and `--metrics` flags or
`HTTP_GW_PPROF`/`HTTP_GW_METRICS` environment variables. `HTTP_GW_PPROF`/`HTTP_GW_METRICS` environment variables.
## Yaml file ## Yaml file
@ -76,22 +76,22 @@ peers:
weight: 1 weight: 1
``` ```
To know nesting level of variable you need to cut off the prefix `S3_GW` from variable and split the rest parts by `_`. 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: For example, variable `S3_GW_PEERS_0_WEIGHT=1` will be transformed to:
``` ```
peers: peers:
0: 0:
weight: 1 weight: 1
``` ```
If parameter doesn't support environment variable (e.g. `--listen_address 0.0.0.0:8084`) form it is used as is: 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 listen_address: 0.0.0.0:8084
``` ```
### Cache parameters ### Cache parameters
Parameters for caches in s3-gw can be specified in .yaml config file. E.g.: Parameters for caches in s3-gw can be specified in a .yaml config file. E.g.:
``` ```
cache: cache:
lifetime: 300s lifetime: 300s