From cf28cff3987bc2519de255f2611afc1ef6952ff7 Mon Sep 17 00:00:00 2001 From: Rusty Russell Date: Sat, 16 Jul 2022 22:48:27 +0930 Subject: [PATCH] doc: document commando and commando-rune. Signed-off-by: Rusty Russell --- doc/Makefile | 2 + doc/index.rst | 2 + doc/lightning-commando-rune.7.md | 101 +++++++++++++++++++++++++ doc/lightning-commando.7.md | 52 +++++++++++++ doc/schemas/commando-rune.request.json | 27 +++++++ doc/schemas/commando-rune.schema.json | 19 +++++ doc/schemas/commando.request.json | 27 +++++++ 7 files changed, 230 insertions(+) create mode 100644 doc/lightning-commando-rune.7.md create mode 100644 doc/lightning-commando.7.md create mode 100644 doc/schemas/commando-rune.request.json create mode 100644 doc/schemas/commando-rune.schema.json create mode 100644 doc/schemas/commando.request.json diff --git a/doc/Makefile b/doc/Makefile index 3f5a39453..04be559e9 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -13,6 +13,8 @@ MANPAGES := doc/lightning-cli.1 \ doc/lightning-checkmessage.7 \ doc/lightning-close.7 \ doc/lightning-connect.7 \ + doc/lightning-commando.7 \ + doc/lightning-commando-rune.7 \ doc/lightning-createonion.7 \ doc/lightning-createinvoice.7 \ doc/lightning-datastore.7 \ diff --git a/doc/index.rst b/doc/index.rst index 87e6601af..b60ced919 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -35,6 +35,8 @@ Core Lightning Documentation lightning-checkmessage lightning-cli lightning-close + lightning-commando + lightning-commando-rune lightning-connect lightning-createinvoice lightning-createonion diff --git a/doc/lightning-commando-rune.7.md b/doc/lightning-commando-rune.7.md new file mode 100644 index 000000000..23a8e9c6e --- /dev/null +++ b/doc/lightning-commando-rune.7.md @@ -0,0 +1,101 @@ +lightning-commando-rune -- Command to Authorize Remote Peer Access +=================================================================== + +SYNOPSIS +-------- + +**commando-rune** [*rune*] [*restrictions*] + +DESCRIPTION +----------- + +The **commando-rune** RPC command creates a base64 string called a +*rune* which can be used to access commands on this node. Each *rune* +contains a unique id (a number starting at 0), and can have +restrictions inside it. Nobody can remove restrictions from a rune: if +you try, the rune will be rejected. There is no limit on how many +runes you can issue: the node doesn't store them, but simply decodes +and checks them as they are received. + +If *rune* is supplied, the restrictions are simple appended to that +*rune* (it doesn't need to be a rune belonging to this node). If no +*rune* is supplied, a new one is constructed, with a new unique id. + +*restrictions* can be the string "readonly" (creates a rune which +allows most *get* and *list* commands, and the *summary* command), or +an array of restrictions, or a single resriction. + +Each restriction is a set of one or more alternatives, such as "method +is listpeers", or "method is listpeers OR time is before 2023". +Alternatives use a simple language to examine the command which is +being run: + +* time: the current UNIX time, e.g. "time<1656759180". +* id: the node_id of the peer, e.g. "id=024b9a1fa8e006f1e3937f65f66c408e6da8e1ca728ea43222a7381df1cc449605". +* method: the command being run, e.g. "method=withdraw". +* pnameX: the parameter named X. e.g. "pnamedestination=1RustyRX2oai4EYYDpQGWvEL62BBGqN9T". + +RESTRICTION FORMAT +------------------ + +Restrictions are one or more altneratives, separated by `|`. Each +alternative is *name* *operator* *value*. The valid names are shown +above. If a value contains `|`, `&` or `\\`, it must be preceeded by +a `\\`. + +* `=`: passes if equal ie. identical. e.g. `method=withdraw` +* `/`: not equals, e.g. `method/withdraw` +* `^`: starts with, e.g. `id^024b9a1fa8e006f1e3937f` +* `$`: ends with, e.g. `id$381df1cc449605`. +* `~`: contains, e.g. `id~006f1e3937f65f66c40`. +* `<`: is a decimal integer, and is less than. e.g. `time<1656759180` +* `>`: is a decimal integer, and is greater than. e.g. `time>1656759180` +* `{`: preceeds in alphabetical order (or matches but is shorter), e.g. `id{02ff`. +* `}`: follows in alphabetical order (or matches but is longer), e.g. `id}02ff`. +* `#`: a comment, ignored, e.g. `dumb example#`. +* `!`: only passes if the *name* does *not* exist. e.g. `pnamedestination!`. + Every other operator except `#` fails if *name* does not exist! + +For example, the "readonly" restriction is actually two restrictions: + +1. `method^list|method^get|method=summary`: You may call list, get or summary. +2. `method/listdatastore`: But not listdatastore: that contains sensitive stuff! + +SHARING RUNES +------------- + +Because anyone can add a restriction to a rune, you can always turn a +normal rune into a read-only rune, or restrict access for 30 minutes +from the time you give it to someone. Adding restrictions before +sharing runes is best practice. + +RETURN VALUE +------------ + +[comment]: # (GENERATE-FROM-SCHEMA-START) +On success, an object is returned, containing: +- **rune** (string): the resulting rune +- **unique_id** (string): the id of this rune: this is set at creation and cannot be changed (even as restrictions are added) + +[comment]: # (GENERATE-FROM-SCHEMA-END) + +AUTHOR +------ + +Rusty Russell <> wrote the original Python +commando.py plugin, the in-tree commando plugin, and this manual page. + +Christian Decker came up with the name "commando", which almost +excuses his previous adoption of the name "Eltoo". + +SEE ALSO +-------- + +lightning-commando(7) + +RESOURCES +--------- + +Main web site: + +[comment]: # ( SHA256STAMP:598337212d2e8a6833698e931f838d8cb424c353af4d7adf6891803ff0ee604b) diff --git a/doc/lightning-commando.7.md b/doc/lightning-commando.7.md new file mode 100644 index 000000000..871083f12 --- /dev/null +++ b/doc/lightning-commando.7.md @@ -0,0 +1,52 @@ +lightning-commando -- Command to Send a Command to a Remote Peer +================================================================ + +SYNOPSIS +-------- + +**commando** *peer_id* *method* [*params*] [*rune*] + +DESCRIPTION +----------- + +The **commando** RPC command is a homage to bad 80s movies. It also +sends a directly-connected *peer_id* a custom message, containing a +request to run *method* (with an optional dictionary of *params*); +generally the peer will only allow you to run a command if it has +provided you with a *rune* which allows it. + +RETURN VALUE +------------ + +On success, the return depends on the *method* invoked. + +On failure, one of the following error codes may be returned: + +- -32600: Usually means peer is not connected +- 19535: the local commando plugin discovered an error. +- 19536: the remote commando plugin discovered an error. +- 19537: the remote commando plugin said we weren't authorized. + +It can also fail if the peer does not respond, in which case it will simply +hang awaiting a response. + +AUTHOR +------ + +Rusty Russell <> wrote the original Python +commando.py plugin, the in-tree commando plugin, and this manual page. + +Christian Decker came up with the name "commando", which almost +excuses his previous adoption of the name "Eltoo". + +SEE ALSO +-------- + +lightning-commando-rune(7) + +RESOURCES +--------- + +Main web site: + +[comment]: # ( SHA256STAMP:6f4406cae30cab813b3bf4e1242af914276716a057e558474e29340665ee8c2f) diff --git a/doc/schemas/commando-rune.request.json b/doc/schemas/commando-rune.request.json new file mode 100644 index 000000000..a93ae80ad --- /dev/null +++ b/doc/schemas/commando-rune.request.json @@ -0,0 +1,27 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": [], + "properties": { + "rune": { + "type": "string", + "description": "optional rune to add to" + }, + "restrictions": { + "oneOf": [ + { + "type": "array", + "description": "array of restrictions to add to rune", + "items": { + "type": "string" + } + }, + { + "type": "string", + "description": "single restrictions to add to rune, or readonly." + } + ] + } + } +} diff --git a/doc/schemas/commando-rune.schema.json b/doc/schemas/commando-rune.schema.json new file mode 100644 index 000000000..c0519e51c --- /dev/null +++ b/doc/schemas/commando-rune.schema.json @@ -0,0 +1,19 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": [ + "rune", + "unique_id" + ], + "properties": { + "rune": { + "type": "string", + "description": "the resulting rune" + }, + "unique_id": { + "type": "string", + "description": "the id of this rune: this is set at creation and cannot be changed (even as restrictions are added)" + } + } +} diff --git a/doc/schemas/commando.request.json b/doc/schemas/commando.request.json new file mode 100644 index 000000000..354f83e86 --- /dev/null +++ b/doc/schemas/commando.request.json @@ -0,0 +1,27 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": [ + "peer_id", + "method" + ], + "properties": { + "peer_id": { + "type": "pubkey", + "description": "peer to command" + }, + "method": { + "type": "string", + "description": "method to invoke on peer" + }, + "params": { + "type": "object", + "description": "parameters for method" + }, + "rune": { + "type": "string", + "description": "rune to authorize the command" + } + } +}