[#876] cli: Add doc for commands control *-rule

Signed-off-by: Anton Nikiforov <an.nikiforov@yadro.com>
This commit is contained in:
Anton Nikiforov 2024-01-22 13:41:26 +03:00
parent 51d1d935ef
commit 417f8fc2c2

View file

@ -0,0 +1,115 @@
# How manage local Access Policy Engine (APE) override of the node
## Overview
APE is a replacement for eACL. Each rule can restrict somehow access to the object/container or list of them.
Here is a simple representation for the rule:
`<status>[:status_detail] <action>... <condition>... <resource>...`
Rule start with `status`(with or without details), contains list of actions(which this rule regulate) or conditions
(which can be under resource or request) and ends with list of resources.
Resource is the combination of namespace, identificator of the FrostFS container/object and wildcard `*`.
For object it can be represented as:
- `namespace/cid/oid` object in the container of the namespace
- `namespace/cid/*` all objects in the container of the namespace
- `namespace/*` all objects in the namespace
- `*` all objects
- `/*` all object in the `root` namespace
- `/cid/*` all objects in the container of the `root` namespace
- `/cid/oid` object in the container of the `root` namespace
For container it can be represented as:
- `namespace/cid` container in the namespace
- `namespace/*` all containers in the namespace
- `*` all containers
- `/cid` container in the `root` namespace
- `/*` all containers in the `root` namespace
Actions is a regular operations upon FrostFS containers/objects. Like `Object.Put`, `Container.Get` etc.
In status section it is possible to use `allow`, `deny` or `deny:QuotaLimitReached` actions.
It is prohibited to mix operation under FrostFS container and object in one rule.
The same statement is equal for conditions and resources - one rule is for one type of items.
## Add rule
Local rule can be added with the command `frostfs-cli control add-rule`:
```shell
@:~$ frostfs-cli control add-rule --endpoint s04.frostfs.devenv:8081 -c cnt_create_cfg.yml \
--address NbUgTSFvPmsRxmGeWpuuGeJUoRoi6PErcM --cid SeHNpifDH2Fc4scNBphrbmrKi96QXj2HzYJkhSGuytH \
--chain-id TestPolicy \
--rule "allow Object.Get Object.Head /*" --rule "deny Container.Put *"
Parsed chain:
Chain ID: TestPolicy
HEX: 54657374506f6c696379
Rules:
Status: Allowed
Any: false
Conditions:
Actions: Inverted:false
GetObject
HeadObject
Resources: Inverted:false
native:object//*
Status: Access denied
Any: false
Conditions:
Actions: Inverted:false
PutContainer
Resources: Inverted:false
native:container/*
Rule has been added.
@:~$
```
## List rules
Local rules can be listed with command `frostfs-cli control list-rules`:
```shell
@:~$ frostfs-cli control list-rules --endpoint s04.frostfs.devenv:8081 --address NbUgTSFvPmsRxmGeWpuuGeJUoRoi6PErcM \
--cid SeHNpifDH2Fc4scNBphrbmrKi96QXj2HzYJkhSGuytH -w wallets/wallet.json
Enter password >
Chain ID: TestPolicy
HEX: 54657374506f6c696379
Rules:
Status: Allowed
Any: false
...
@:~$
```
## Get rule
Rules can be retrieved with `frostfs-cli control get-rule`:
```shell
@:~$ frostfs-cli control get-rule --endpoint s04.frostfs.devenv:8081 -c cnt_create_cfg.yml \
--address NbUgTSFvPmsRxmGeWpuuGeJUoRoi6PErcM --cid SeHNpifDH2Fc4scNBphrbmrKi96QXj2HzYJkhSGuytH \
--chain-id TestPolicy
Parsed chain (chain id hex: '54657374506f6c696379'):
Chain ID: TestPolicy
HEX: 54657374506f6c696379
Rules:
Status: Allowed
Any: false
...
@:~$
```
## Remove rule
To remove rule need to use command `frostfs-cli control remove-rule`:
```shell
@:~$ frostfs-cli control remove-rule --endpoint s04.frostfs.devenv:8081 -c cnt_create_cfg.yml \
--address NbUgTSFvPmsRxmGeWpuuGeJUoRoi6PErcM --cid SeHNpifDH2Fc4scNBphrbmrKi96QXj2HzYJkhSGuytH --chain-id TestPolicy
Rule has been removed.
@:~$ frostfs-cli control get-rule --endpoint s04.frostfs.devenv:8081 -c cnt_create_cfg.yml \
--address NbUgTSFvPmsRxmGeWpuuGeJUoRoi6PErcM --cid SeHNpifDH2Fc4scNBphrbmrKi96QXj2HzYJkhSGuytH --chain-id TestPolicy
rpc error: rpc error: code = NotFound desc = chain not found
@:~$ frostfs-cli control list-rules --endpoint s04.frostfs.devenv:8081 \
--address NbUgTSFvPmsRxmGeWpuuGeJUoRoi6PErcM --cid SeHNpifDH2Fc4scNBphrbmrKi96QXj2HzYJkhSGuytH -w wallets/wallet.json
Enter password >
Local overrides are not defined for the container.
@:~$
```