diff --git a/cmd/frostfs-cli/docs/policy.md b/cmd/frostfs-cli/docs/policy.md new file mode 100644 index 00000000..06c325c6 --- /dev/null +++ b/cmd/frostfs-cli/docs/policy.md @@ -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_detail] ... ... ...` + +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. +@:~$ +```