core-lightning/doc/schemas/lightning-setconfig.json

{
  "$schema": "../rpc-schema-draft.json",
  "type": "object",
  "added": "v23.08",
  "rpc": "setconfig",
  "title": "Dynamically change some config options",
  "description": [
    "The **setconfig** RPC command allows you set the (dynamic) configuration option named by `config`: options which take a value (as separate from simple flag options) also need a `val` parameter.",
    "",
    "This new value will *also* be written at the end of the config file, for persistence across restarts (and any old value commented out).",
    "",
    "You can see what options are dynamically adjustable using lightning- listconfigs(7). Note that you can also adjust existing options for stopped plugins; they will have an effect when the plugin is restarted."
  ],
  "request": {
    "required": [
      "config"
    ],
    "additionalProperties": false,
    "properties": {
      "config": {
        "type": "string",
        "description": [
          "Name of the config variable which should be set to the value of the variable."
        ]
      },
      "val": {
        "oneOf": [
          {
            "type": "string"
          },
          {
            "type": "integer"
          },
          {
            "type": "boolean"
          }
        ],
        "description": [
          "Value of the config variable to be set or updated."
        ]
      }
    }
  },
  "response": {
    "required": [
      "config"
    ],
    "additionalProperties": false,
    "properties": {
      "config": {
        "type": "object",
        "description": [
          "Config settings after completion."
        ],
        "additionalProperties": false,
        "required": [
          "config",
          "source",
          "dynamic"
        ],
        "properties": {
          "config": {
            "type": "string",
            "description": [
              "Name of the config variable which was set."
            ]
          },
          "source": {
            "type": "string",
            "description": [
              "Source of configuration setting (`file`:`linenum`)."
            ]
          },
          "plugin": {
            "type": "string",
            "description": [
              "The plugin this configuration setting is for."
            ]
          },
          "dynamic": {
            "type": "boolean",
            "enum": [
              true
            ],
            "description": [
              "Whether this option is settable via setconfig."
            ]
          },
          "set": {
            "type": "boolean",
            "description": [
              "For simple flag options."
            ]
          },
          "value_str": {
            "type": "string",
            "description": [
              "For string options."
            ]
          },
          "value_msat": {
            "type": "msat",
            "description": [
              "For msat options."
            ]
          },
          "value_int": {
            "type": "integer",
            "description": [
              "For integer options."
            ]
          },
          "value_bool": {
            "type": "boolean",
            "description": [
              "For boolean options."
            ]
          }
        }
      }
    }
  },
  "errors": [
    "The following error codes may occur:",
    "",
    "- -32602: JSONRPC2_INVALID_PARAMS, i.e. the parameter is not dynamic, or the val was invalid."
  ],
  "author": [
    "Rusty Russell <<rusty@rustcorp.com.au>> is mainly responsible for this feature."
  ],
  "see_also": [
    "lightningd-config(5)",
    "lightning-listconfigs(7)"
  ],
  "resources": [
    "Main web site: <https://github.com/ElementsProject/lightning>"
  ],
  "examples": [
    {
      "request": {
        "id": "example:setconfig#1",
        "method": "setconfig",
        "params": [
          "autoclean-expiredinvoices-age",
          300
        ]
      },
      "response": {
        "config": {
          "config": "autoclean-expiredinvoices-age",
          "value_int": 300,
          "source": "/tmp/.lightning/regtest/config:2",
          "plugin": "/root/lightning/plugins/autoclean",
          "dynamic": true
        }
      }
    },
    {
      "request": {
        "id": "example:setconfig#2",
        "method": "setconfig",
        "params": {
          "config": "min-capacity-sat",
          "val": 500000
        }
      },
      "response": {
        "config": {
          "config": "min-capacity-sat",
          "value_int": 500000,
          "source": "/tmp/.lightning/regtest/config:4",
          "dynamic": true
        }
      }
    }
  ]
}