FreeBSD Manual Pages
LIGHTNING-PLUGIN(7) LIGHTNING-PLUGIN(7) NAME lightning-plugin -- Manage plugins with RPC SYNOPSIS plugin subcommand [plugin|directory] [options] ... DESCRIPTION The plugin RPC command can be used to control dynamic plugins, i.e. plugins that declared themself 'dynamic' (in getmanifest). • subcommand (string) (one of "start", "stop", "rescan", "startdir", "list"): Determines what action is taken: • subcommand start takes a path to an executable as argument and starts it as plugin. path may be an absolute path or a path rela- tive to the plugins directory (default ~/.lightning/plugins). If the plugin is already running and the executable (checksum) has changed, the plugin is killed and restarted except if its an im- portant (or builtin) plugin. If the plugin doesn't complete the 'getmanifest' and 'init' handshakes within 60 seconds, the com- mand will timeout and kill the plugin. Additional options may be passed to the plugin, but requires all parameters to be passed as keyword=value pairs using the -k|--keyword option which is recom- mended. For example the following command starts the plugin hel- loworld.py (present in the plugin directory) with the option greeting set to 'A crazy': shell. $ lightning-cli -k plugin sub- command=start plugin=helloworld.py greeting='A crazy'. . • subcommand stop takes a plugin executable path or name as argu- ment and stops the plugin. If the plugin subscribed to 'shut- down', it may take up to 30 seconds before this command returns. If the plugin is important and dynamic, this will shutdown light- ningd. • subcommand startdir starts all executables it can find in direc- tory (excl. subdirectories) as plugins. Checksum and timeout be- havior as in start applies. • subcommand rescan starts all plugins in the default plugins di- rectory (default ~/.lightning/plugins) that are not already run- ning. Checksum and timeout behavior as in start applies. • subcommand list lists all running plugins (incl. non-dynamic). • plugin (string, optional): path or name of a plugin executable to start or stop. • directory (string, optional): path of a directory containing plug- ins. • options (array of strings, optional): • (string, optional): keyword=value options passed to plugin, can be repeated. RETURN VALUE On success, an object is returned, containing: • command (string) (one of "start", "stop", "rescan", "startdir", "list"): The subcommand this is responding to. If command is "start", "startdir", "rescan" or "list": - plugins (array of objects): - name (string): Full pathname of the plugin. - active (boolean): Status; plugin completed init and is operational, plugins are configured asynchronously. - dynamic (boolean): Plugin can be stopped or started without restarting lightningd. If command is "stop": - result (string): A message saying it success- fully stopped. ERRORS On error, the reason why the action could not be taken upon the plugin is returned. AUTHOR Antoine Poinsot <<darosior@protonmail.com>> is mainly responsible. SEE ALSO $ lightning-cli(1), lightning-listconfigs(7), writing plugins <https://docs.corelightning.org/docs/plugin-development> RESOURCES Main web site: <https://github.com/ElementsProject/lightning> EXAMPLES Example 1: Request: $ lightning-cli plugin -k "subcommand"="start" "plugin"="/root/lightning/tests/plugins/allow_even_msgs.py" { "id": "example:plugin#1", "method": "plugin", "params": { "subcommand": "start", "plugin": "/root/lightning/tests/plugins/allow_even_msgs.py" } } Response: { "command": "start", "plugins": [ { "name": "/root/lightning/plugins/autoclean", "active": true, "dynamic": false }, { "name": "/root/lightning/plugins/chanbackup", "active": true, "dynamic": false }, { "name": "/root/lightning/plugins/bcli", "active": true, "dynamic": false }, { "name": "/root/lightning/plugins/commando", "active": true, "dynamic": false }, { "name": "/root/lightning/plugins/funder", "active": true, "dynamic": true }, { "name": "/root/lightning/plugins/topology", "active": true, "dynamic": false }, { "name": "/root/lightning/plugins/exposesecret", "active": true, "dynamic": true }, { "name": "/root/lightning/plugins/keysend", "active": true, "dynamic": false }, { "name": "/root/lightning/plugins/offers", "active": true, "dynamic": true }, { "name": "/root/lightning/plugins/pay", "active": true, "dynamic": true }, { "name": "/root/lightning/plugins/recklessrpc", "active": true, "dynamic": true }, { "name": "/root/lightning/plugins/recover", "active": true, "dynamic": false }, { "name": "/root/lightning/plugins/txprepare", "active": true, "dynamic": true }, { "name": "/root/lightning/plugins/cln-renepay", "active": true, "dynamic": true }, { "name": "/root/lightning/plugins/cln-xpay", "active": true, "dynamic": true }, { "name": "/root/lightning/plugins/spenderp", "active": true, "dynamic": false }, { "name": "/root/lightning/plugins/cln-askrene", "active": true, "dynamic": true }, { "name": "/root/lightning/plugins/sql", "active": true, "dynamic": true }, { "name": "/root/lightning/plugins/cln-grpc", "active": true, "dynamic": false }, { "name": "/root/lightning/plugins/bookkeeper", "active": true, "dynamic": false }, { "name": "/root/lightning/tests/plugins/allow_even_msgs.py", "active": true, "dynamic": true } ] } Example 2: Request: $ lightning-cli plugin -k "subcommand"="stop" "plugin"="/root/lightning/tests/plugins/allow_even_msgs.py" { "id": "example:plugin#2", "method": "plugin", "params": { "subcommand": "stop", "plugin": "/root/lightning/tests/plugins/allow_even_msgs.py" } } Response: { "command": "stop", "result": "Successfully stopped allow_even_msgs.py." } Example 3: Request: $ lightning-cli plugin "list" { "id": "example:plugin#3", "method": "plugin", "params": [ "list" ] } Response: { "command": "list", "plugins": [ { "name": "/root/lightning/plugins/autoclean", "active": true, "dynamic": false }, { "name": "/root/lightning/plugins/chanbackup", "active": true, "dynamic": false }, { "name": "/root/lightning/plugins/bcli", "active": true, "dynamic": false }, { "name": "/root/lightning/plugins/commando", "active": true, "dynamic": false }, { "name": "/root/lightning/plugins/funder", "active": true, "dynamic": true }, { "name": "/root/lightning/plugins/topology", "active": true, "dynamic": false }, { "name": "/root/lightning/plugins/exposesecret", "active": true, "dynamic": true }, { "name": "/root/lightning/plugins/keysend", "active": true, "dynamic": false }, { "name": "/root/lightning/plugins/offers", "active": true, "dynamic": true }, { "name": "/root/lightning/plugins/pay", "active": true, "dynamic": true }, { "name": "/root/lightning/plugins/recklessrpc", "active": true, "dynamic": true }, { "name": "/root/lightning/plugins/recover", "active": true, "dynamic": false }, { "name": "/root/lightning/plugins/txprepare", "active": true, "dynamic": true }, { "name": "/root/lightning/plugins/cln-renepay", "active": true, "dynamic": true }, { "name": "/root/lightning/plugins/cln-xpay", "active": true, "dynamic": true }, { "name": "/root/lightning/plugins/spenderp", "active": true, "dynamic": false }, { "name": "/root/lightning/plugins/cln-askrene", "active": true, "dynamic": true }, { "name": "/root/lightning/plugins/sql", "active": true, "dynamic": true }, { "name": "/root/lightning/plugins/cln-grpc", "active": true, "dynamic": false }, { "name": "/root/lightning/plugins/bookkeeper", "active": true, "dynamic": false } ] } Core Lightning v25.02 LIGHTNING-PLUGIN(7)
NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | AUTHOR | SEE ALSO | RESOURCES | EXAMPLES
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=lightning-plugin&sektion=7&manpath=FreeBSD+Ports+14.3.quarterly>