From 417f8fc2c24cbe601a73c13c28d4c83ce211bc31 Mon Sep 17 00:00:00 2001
From: Anton Nikiforov <an.nikiforov@yadro.com>
Date: Mon, 22 Jan 2024 13:41:26 +0300
Subject: [PATCH] [#876] cli: Add doc for commands `control *-rule`

Signed-off-by: Anton Nikiforov <an.nikiforov@yadro.com>
---
 cmd/frostfs-cli/docs/policy.md | 115 +++++++++++++++++++++++++++++++++
 1 file changed, 115 insertions(+)
 create mode 100644 cmd/frostfs-cli/docs/policy.md

diff --git a/cmd/frostfs-cli/docs/policy.md b/cmd/frostfs-cli/docs/policy.md
new file mode 100644
index 000000000..06c325c62
--- /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>[: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.
+@:~$
+```