diff --git a/doc/lightningd-config.5.txt b/doc/lightningd-config.5.txt deleted file mode 100644 index 91558184b..000000000 --- a/doc/lightningd-config.5.txt +++ /dev/null @@ -1,383 +0,0 @@ -LIGHTNINGD-CONFIG(5) -==================== -:doctype: manpage - -NAME ----- -lightningd-config - Lightning daemon configuration file - -SYNOPSIS --------- -*~/.lightning/config* - -DESCRIPTION ------------ - -When lightningd(8) starts up, it reads a configuration file. By -default that is 'config' in the *.lightning* subdirectory of the home -directory (if it exists), but that can be changed by the -'--lightning-dir' or '--conf' options on the lightningd(8) command -line. - -Configuration file options are processed first, then command line -options: later options override earlier ones except 'addr' options -which accumulate. - -All these options are mirrored as commandline arguments to -lightningd(8), so '--foo' becomes simply 'foo' in the configuration -file, and '--foo=bar' becomes 'foo=bar' in the configuration file. - -Blank lines and lines beginning with '#' are ignored. - -DEBUGGING ---------- - -'--help' will show you the defaults for many options; they vary with -network settings so you can specify '--network' before '--help' to see -the defaults for that network. - -The lightning-listconfigs(7) command will output a valid configuration -file using the current settings. - -OPTIONS -------- - -General options -~~~~~~~~~~~~~~~ - -*allow-deprecated-apis*='BOOL':: - Enable deprecated options, JSONRPC commands, fields, etc. It - defaults to 'true', but you should set it to 'false' when testing - to ensure that an upgrade won't break your configuration. - -*help*:: - Print help and exit. Not very useful inside a configuration file, but - fun to put in other's config files while their computer is unattended. - -*version*:: - Print version and exit. Also useless inside a configuration file, - but putting this in someone's config file may convince them to - read this man page. - -Bitcoin control options: - -*network*='NETWORK':: - Select the network parameters ('bitcoin', 'testnet', or 'regtest'). - -*testnet*:: - Alias for 'network=testnet'. - -*signet*:: - Alias for 'network=signet'. - -*mainnet*:: - Alias for 'network=bitcoin'. - -*bitcoin-cli*='PATH':: - The name of 'bitcoin-cli' executable to run. - -*bitcoin-datadir*='DIR':: - '-datadir' argument to supply to bitcoin-cli(1). - -*bitcoin-rpcuser*='USER':: - The RPC username for talking to bitcoind(1). - -*bitcoin-rpcpassword*='PASSWORD':: - The RPC password for talking to bitcoind(1). - -*bitcoin-rpcconnect*='HOST':: - The bitcoind(1) RPC host to connect to. - -*bitcoin-rpcport*='PORT':: - The bitcoind(1) RPC port to connect to. - -*bitcoin-retry-timeout*='SECONDS':: - Number of seconds to keep trying a bitcoin-cli(1) command. - If the command keeps failing after this time, exit with a - fatal error. - -*rescan*='BLOCKS':: - Number of blocks to rescan from the current head, or absolute blockheight - if negative. This is only needed if something goes badly wrong. - -Lightning daemon options -~~~~~~~~~~~~~~~~~~~~~~~~ - -*lightning-dir*='DIR':: - Sets the working directory. All files (except '--conf' and '--lightning-dir' - on the command line) are relative to this. - -*pid-file*='PATH':: - Specify pid file to write to. - -*log-level*='LEVEL':: - What log level to print out: options are io, debug, info, unusual, broken. - -*log-prefix*='PREFIX':: - Prefix for log lines: this can be customized if you want to merge logs with - multiple daemons. - -*log-file*='PATH':: - Log to this file instead of stdout. Sending lightningd(8) SIGHUP will cause - it to reopen this file (useful for log rotation). - -*rpc-file*='PATH':: - Set JSON-RPC socket (or /dev/tty), such as for lightning-cli(1). - -*daemon*:: - Run in the background, suppress stdout and stderr. - -*conf*='PATH':: - Sets configuration file (default: *lightning-dir*/'config' ). If this is - a relative path, it is relative to the starting directory, not - *lightning-dir* (unlike other paths). 'PATH' must exist and be readable - (we allow missing files in the default case). - Using this inside a configuration file is meaningless. - -Lightning node customization options -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -*rgb*='RRGGBB':: - Your favorite color as a hex code. - -*alias*='NAME':: - Up to 32 UTF-8 characters to tag your node. Completely silly, since anyone - can call their node anything they want. The default is an - NSA-style codename derived from your public key, but "Peter Todd" - and "VAULTERO" are good options, too. - -*fee-base*='MILLISATOSHI':: - Default: 1000. The base fee to charge for every payment which passes - through. Note that millisatoshis are a very, very small unit! - Changing this value will only affect new channels and not existing ones. - If you want to change fees for existing channels, use the RPC call - lightning-setchannelfee(7). - -*fee-per-satoshi*='MILLIONTHS':: - Default: 10 (0.001%). This is the proportional fee to charge for every - payment which passes through. As percentages are too coarse, it's in - millionths, so 10000 is 1%, 1000 is 0.1%. Changing this value will only - affect new channels and not existing ones. If you want to change fees for - existing channels, use the RPC call lightning-setchannelfee(7). - -*min-capacity-sat*='SATOSHI':: - Default: 10000. This value defines the minimal effective channel capacity - in satoshi to accept for channel opening requests. If a peer tries to open - a channel smaller than this, the opening will be rejected. - -*ignore-fee-limits*='BOOL':: - Allow nodes which establish channels to us to set any fee they - want. This may result in a channel which cannot be closed, should - fees increase, but make channels far more reliable since we never - close it due to unreasonable fees. - -*commit-time*='MILLISECONDS:: - How long to wait before sending commitment messages to the peer: in - theory increasing this would reduce load, but your node would have to be - extremely busy node for you to even notice. - -Lightning channel and HTLC options -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -*watchtime-blocks*='BLOCKS':: - How long we need to spot an outdated close attempt: on opening a channel - we tell our peer that this is how long they'll have to wait if they perform - a unilateral close. - -*max-locktime-blocks*='BLOCKS':: - The longest our funds can be delayed (ie. the longest *watchtime-blocks* - our peer can ask for, and also the longest HTLC timeout we will accept). - If our peer asks for longer, we'll refuse to create a channel, and if an - HTLC asks for longer, we'll refuse it. - -*funding-confirms*='BLOCKS':: - Confirmations required for the funding transaction when the other side - opens a channel before the channel is usable. - -*commit-fee*='PERCENT':: - The percentage of 'estimatesmartfee 2' to use for the bitcoin - transaction which funds a channel: can be greater than 100. - -*commit-fee-min*='PERCENT':: -*commit-fee-max*='PERCENT':: - Limits on what onchain fee range we'll allow when a node opens a - channel with us, as a percentage of 'estimatesmartfee 2'. If - they're outside this range, we abort their opening attempt. Note - that *commit-fee-max* can (should!) be greater than 100. - -*max-concurrent-htlcs*='INTEGER':: - Number of HTLCs one channel can handle concurrently in each direction. - Should be between 1 and 483 (default 30). - -*cltv-delta*='BLOCKS':: - The number of blocks between incoming payments and outgoing payments: - this needs to be enough to make sure that if we have to, we can close - the outgoing payment before the incoming, or redeem the incoming once - the outgoing is redeemed. - -*cltv-final*='BLOCKS':: - The number of blocks to allow for payments we receive: if we have to, - we might need to redeem this on-chain, so this is the number of blocks - we have to do that. - -Invoice control options: - -*autocleaninvoice-cycle*='SECONDS':: - Perform cleanup of expired invoices every 'SECONDS' seconds, or - disable if 0. Usually unpaid expired invoices are uninteresting, - and just take up space in the database. - -*autocleaninvoice-expired-by*='SECONDS':: - Control how long invoices must have been expired before they are - cleaned (if 'autocleaninvoice-cycle' is non-zero). - -Networking options -~~~~~~~~~~~~~~~~~~ - -Note that for simple setups, the implicit 'autolisten' option does the -right thing: it will try to bind to port 9735 on IPv4 and IPv6, and -will announce it to peers if it seems like a public address. - -You can instead use 'addr' to override this (eg. to change the port), -or precisely control where to bind and what to announce with the -'bind-addr' and 'announce-addr' options. These will *disable* the -'autolisten' logic, so you must specifiy exactly what you want! - -*addr*='[IPADDRESS[:PORT]]|autotor:TORIPADDRESS[:TORPORT]':: - - Set an IP address (v4 or v6) or automatic Tor address to listen on - and (maybe) announce as our node address. - - An empty 'IPADDRESS' is a special value meaning bind to IPv4 and/or - IPv6 on all interfaces, '0.0.0.0' means bind to all IPv4 - interfaces, '::' means 'bind to all IPv6 interfaces'. If 'PORT' is - not specified, 9735 is used. If we can determine a public IP - address from the resulting binding, and no other addresses of the - same type are already announced, the address is announced. - - If the argument begins with 'autotor:' then it is followed by the - IPv4 or IPv6 address of the Tor control port (default port 9051), - and this will be used to configure a Tor hidden service for port - 9735. The Tor hidden service will be configured to point to the - first IPv4 or IPv6 address we bind to. - - This option can be used multiple times to add more addresses, and - its use disables autolisten. If necessary, and 'always-use-proxy' - is not specified, a DNS lookup may be done to resolve 'IPADDRESS' - or 'TORIPADDRESS'. - -*bind-addr*='[IPADDRESS[:PORT]]|SOCKETPATH':: - - Set an IP address or UNIX domain socket to listen to, but do not - announce. A UNIX domain socket is distinguished from an IP address - by beginning with a '/'. - - An empty 'IPADDRESS' is a special value meaning bind to IPv4 and/or - IPv6 on all interfaces, '0.0.0.0' means bind to all IPv4 - interfaces, '::' means 'bind to all IPv6 interfaces'. 'PORT' is - not specified, 9735 is used. - - This option can be used multiple times to add more addresses, and - its use disables autolisten. If necessary, and 'always-use-proxy' - is not specified, a DNS lookup may be done to resolve 'IPADDRESS'. - -*announce-addr*='IPADDRESS[:PORT]|TORADDRESS.onion[:PORT]':: - - Set an IP (v4 or v6) address or Tor address to announce; a Tor address is - distinguished by ending in '.onion'. 'PORT' defaults to 9735. - - Empty or wildcard IPv4 and IPv6 addresses don't make sense here. - Also, unlike the 'addr' option, there is no checking that your - announced addresses are public (e.g. not localhost). - - This option can be used multiple times to add more addresses, and - its use disables autolisten. The spec says you can't announce - more that one address of the same type (eg. two IPv4 or two IPv6 - addresses) so `lightningd` will refuse if you specify more than one. - - If necessary, and 'always-use-proxy' is not specified, a DNS - lookup may be done to resolve 'IPADDRESS'. - -*offline*:: - Do not bind to any ports, and do not try to reconnect to any peers. - This can be useful for maintenance and forensics, so is usually - specified on the command line. Overrides all 'addr' and 'bind-addr' - options. - -*autolisten*='BOOL':: - By default, we bind (and maybe announce) on IPv4 and IPv6 interfaces if - no 'addr', 'bind-addr' or 'announce-addr' options are specified. Setting - this to 'false' disables that. - -*proxy*='IPADDRESS[:PORT]':: - Set a socks proxy to use to connect to Tor nodes (or for all connections if - *always-use-proxy* is set). - -*always-use-proxy*='BOOL':: - Always use the *proxy*, even to connect to normal IP addresses (you - can still connect to Unix domain sockets manually). This also disables - all DNS lookups, to avoid leaking information. - -*disable-dns*:: - Disable the DNS bootstrapping mechanism to find a node by its node ID. - -*tor-service-password*='PASSWORD':: - Set a Tor control password, which may be needed for 'autotor:' to - authenticate to the Tor control port. - - -Lightning Plugins -~~~~~~~~~~~~~~~~~ - -lightningd(8) supports plugins, which offer additional configuration -options and JSON-RPC methods, depending on the plugin. Some are -supplied by default (usually located in -*libexec/c-lightning/plugins/*). If a *plugins* directory exists -under 'lightning-dir' that is searched for plugins along with -any immediate subdirectories). You can specify additional paths too: - -*plugin*='PATH':: - Specify a plugin to run as part of c-lightning. This can be specified - multiple times to add multiple plugins. - -*plugin-dir*='DIRECTORY':: - Specify a directory to look for plugins; all executable files - not containing punctuation (other than '.', '-' or '_) in 'DIRECTORY' - are loaded. 'DIRECTORY' must exist; - this can be specified multiple times to add multiple directories. - -*clear-plugins*:: - This option clears all 'plugin' and 'plugin-dir' options - preceeding it, including the default built-in plugin directory. - You can still add 'plugin-dir' and 'plugin' options following - this and they will have the normal effect. - -*disable-plugin*='PLUGIN':: - If 'PLUGIN' contains a /, plugins with the same path as 'PLUGIN' - are disabled. Otherwise, any plugin with that base name is - disabled, whatever directory it is in. - -BUGS ----- -You should report bugs on our github issues page, and maybe submit a -fix to gain our eternal gratitude! - -AUTHOR ------- -Rusty Russell wrote this man page, and much -of the configuration language, but many others did the hard work -of actually implementing these options. - -SEE ALSO --------- -lightning-listconfigs(7) lightning-setchannelfee(7) -lightningd(8) - -RESOURCES ---------- -Main web site: https://github.com/ElementsProject/lightning - -COPYING -------- -Note: the modules in the ccan/ directory have their own licenses, but -the rest of the code is covered by the BSD-style MIT license.