frostfs-node/cmd/frostfs-cli/docs/policy.md

# 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.

If a statement does not contain lexeme `any`, field `Any` is set to `false` by default. Otherwise, it is set
to `true`. Optionally, `all` can be used - it also sets `Any=false`.

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.
@:~$
```