1lightningd-config -- Lightning daemon configuration file 2======================================================== 3 4SYNOPSIS 5-------- 6 7**~/.lightning/config** 8 9DESCRIPTION 10----------- 11 12When lightningd(8) starts up it usually reads a general configuration 13file (default: **$HOME/.lightning/config**) then a network-specific 14configuration file (default: **$HOME/.lightning/testnet/config**). This can 15be changed: see *--conf* and *--lightning-dir*. 16 17General configuration files are processed first, then network-specific 18ones, then command line options: later options override earlier ones 19except *addr* options and *log-level* with subsystems, which 20accumulate. 21 22*include * followed by a filename includes another configuration file at that 23point, relative to the current configuration file. 24 25All these options are mirrored as commandline arguments to 26lightningd(8), so *--foo* becomes simply *foo* in the configuration 27file, and *--foo=bar* becomes *foo=bar* in the configuration file. 28 29Blank lines and lines beginning with *\#* are ignored. 30 31DEBUGGING 32--------- 33 34*--help* will show you the defaults for many options; they vary with 35network settings so you can specify *--network* before *--help* to see 36the defaults for that network. 37 38The lightning-listconfigs(7) command will output a valid configuration 39file using the current settings. 40 41OPTIONS 42------- 43 44### General options 45 46 **allow-deprecated-apis**=*BOOL* 47Enable deprecated options, JSONRPC commands, fields, etc. It defaults to 48*true*, but you should set it to *false* when testing to ensure that an 49upgrade won't break your configuration. 50 51 **help** 52Print help and exit. Not very useful inside a configuration file, but 53fun to put in other's config files while their computer is unattended. 54 55 **version** 56Print version and exit. Also useless inside a configuration file, but 57putting this in someone's config file may convince them to read this man 58page. 59 60Bitcoin control options: 61 62 **network**=*NETWORK* 63Select the network parameters (*bitcoin*, *testnet*, *signet*, or *regtest*). 64This is not valid within the per-network configuration file. 65 66 **mainnet** 67Alias for *network=bitcoin*. 68 69 **testnet** 70Alias for *network=testnet*. 71 72 **signet** 73Alias for *network=signet*. 74 75 **bitcoin-cli**=*PATH* [plugin `bcli`] 76The name of *bitcoin-cli* executable to run. 77 78 **bitcoin-datadir**=*DIR* [plugin `bcli`] 79*-datadir* argument to supply to bitcoin-cli(1). 80 81 **bitcoin-rpcuser**=*USER* [plugin `bcli`] 82The RPC username for talking to bitcoind(1). 83 84 **bitcoin-rpcpassword**=*PASSWORD* [plugin `bcli`] 85The RPC password for talking to bitcoind(1). 86 87 **bitcoin-rpcconnect**=*HOST* [plugin `bcli`] 88The bitcoind(1) RPC host to connect to. 89 90 **bitcoin-rpcport**=*PORT* [plugin `bcli`] 91The bitcoind(1) RPC port to connect to. 92 93 **bitcoin-retry-timeout**=*SECONDS* [plugin `bcli`] 94Number of seconds to keep trying a bitcoin-cli(1) command. If the 95command keeps failing after this time, exit with a fatal error. 96 97 **rescan**=*BLOCKS* 98Number of blocks to rescan from the current head, or absolute 99blockheight if negative. This is only needed if something goes badly 100wrong. 101 102### Lightning daemon options 103 104 **lightning-dir**=*DIR* 105Sets the working directory. All files (except *--conf* and 106*--lightning-dir* on the command line) are relative to this. This 107is only valid on the command-line, or in a configuration file specified 108by *--conf*. 109 110 **subdaemon**=*SUBDAEMON*:*PATH* 111Specifies an alternate subdaemon binary. 112Current subdaemons are *channeld*, *closingd*, 113*connectd*, *gossipd*, *hsmd*, *onchaind*, and *openingd*. 114If the supplied path is relative the subdaemon binary is found in the 115working directory. This option may be specified multiple times. 116 117 So, **subdaemon=hsmd:remote_signer** would use a 118hypothetical remote signing proxy instead of the standard *lightning_hsmd* 119binary. 120 121 **pid-file**=*PATH* 122Specify pid file to write to. 123 124 **log-level**=*LEVEL*\[:*SUBSYSTEM*\] 125What log level to print out: options are io, debug, info, unusual, 126broken. If *SUBSYSTEM* is supplied, this sets the logging level 127for any subsystem containing that string. Subsystems include: 128 129* *lightningd*: The main lightning daemon 130* *database*: The database subsystem 131* *wallet*: The wallet subsystem 132* *gossipd*: The gossip daemon 133* *plugin-manager*: The plugin subsystem 134* *plugin-P*: Each plugin, P = plugin path without directory 135* *hsmd*: The secret-holding daemon 136* *connectd*: The network connection daemon 137* *jsonrpc#FD*: Each JSONRPC connection, FD = file descriptor number 138 139 140 The following subsystems exist for each channel, where N is an incrementing 141internal integer id assigned for the lifetime of the channel: 142* *openingd-chan#N*: Each opening / idling daemon 143* *channeld-chan#N*: Each channel management daemon 144* *closingd-chan#N*: Each closing negotiation daemon 145* *onchaind-chan#N*: Each onchain close handling daemon 146 147 148 So, **log-level=debug:plugin** would set debug level logging on all 149plugins and the plugin manager. **log-level=io:chan#55** would set 150IO logging on channel number 55 (or 550, for that matter). 151 152 **log-prefix**=*PREFIX* 153Prefix for log lines: this can be customized if you want to merge logs 154with multiple daemons. 155 156 **log-file**=*PATH* 157Log to this file instead of stdout. Sending lightningd(8) SIGHUP will 158cause it to reopen this file (useful for log rotation). 159 160 **log-timestamps**=*BOOL* 161Set this to false to turn off timestamp prefixes (they will still appear 162in crash log files). 163 164 **rpc-file**=*PATH* 165Set JSON-RPC socket (or /dev/tty), such as for lightning-cli(1). 166 167 **rpc-file-mode**=*MODE* 168Set JSON-RPC socket file mode, as a 4-digit octal number. 169Default is 0600, meaning only the user that launched lightningd 170can command it. 171Set to 0660 to allow users with the same group to access the RPC 172as well. 173 174 **daemon** 175Run in the background, suppress stdout and stderr. Note that you need 176to specify **log-file** for this case. 177 178 **conf**=*PATH* 179Sets configuration file, and disable reading the normal general and network 180ones. If this is a relative path, it is relative to the starting directory, not 181**lightning-dir** (unlike other paths). *PATH* must exist and be 182readable (we allow missing files in the default case). Using this inside 183a configuration file is invalid. 184 185 **wallet**=*DSN* 186Identify the location of the wallet. This is a fully qualified data source 187name, including a scheme such as `sqlite3` or `postgres` followed by the 188connection parameters. 189 190The default wallet corresponds to the following DSN: 191 192``` 193--wallet=sqlite3://$HOME/.lightning/bitcoin/lightningd.sqlite3 194``` 195 196The following is an example of a postgresql wallet DSN: 197 198``` 199--wallet=postgres://user:pass@localhost:5432/db_name 200``` 201 202This will connect to a DB server running on `localhost` port `5432`, 203authenticate with username `user` and password `pass`, and then use the 204database `db_name`. The database must exist, but the schema will be managed 205automatically by `lightningd`. 206 207 **encrypted-hsm** 208If set, you will be prompted to enter a password used to encrypt the `hsm_secret`. 209Note that once you encrypt the `hsm_secret` this option will be mandatory for 210`lightningd` to start. 211If there is no `hsm_secret` yet, `lightningd` will create a new encrypted secret. 212If you have an unencrypted `hsm_secret` you want to encrypt on-disk, or vice versa, 213see lightning-hsmtool(8). 214 215### Lightning node customization options 216 217 **alias**=*NAME* 218Up to 32 bytes of UTF-8 characters to tag your node. Completely silly, since 219anyone can call their node anything they want. The default is an 220NSA-style codename derived from your public key, but "Peter Todd" and 221"VAULTERO" are good options, too. 222 223 **rgb**=*RRGGBB* 224Your favorite color as a hex code. 225 226 **fee-base**=*MILLISATOSHI* 227Default: 1000. The base fee to charge for every payment which passes 228through. Note that millisatoshis are a very, very small unit! Changing 229this value will only affect new channels and not existing ones. If you 230want to change fees for existing channels, use the RPC call 231lightning-setchannelfee(7). 232 233 **fee-per-satoshi**=*MILLIONTHS* 234Default: 10 (0.001%). This is the proportional fee to charge for every 235payment which passes through. As percentages are too coarse, it's in 236millionths, so 10000 is 1%, 1000 is 0.1%. Changing this value will only 237affect new channels and not existing ones. If you want to change fees 238for existing channels, use the RPC call lightning-setchannelfee(7). 239 240 **min-capacity-sat**=*SATOSHI* 241Default: 10000. This value defines the minimal effective channel 242capacity in satoshi to accept for channel opening requests. This will 243reject any opening of a channel which can't pass an HTLC of least this 244value. Usually this prevents a peer opening a tiny channel, but it 245can also prevent a channel you open with a reasonable amount and the peer 246requesting such a large reserve that the capacity of the channel 247falls below this. 248 249 **ignore-fee-limits**=*BOOL* 250Allow nodes which establish channels to us to set any fee they want. 251This may result in a channel which cannot be closed, should fees 252increase, but make channels far more reliable since we never close it 253due to unreasonable fees. 254 255 **commit-time**=*MILLISECONDS* 256How long to wait before sending commitment messages to the peer: in 257theory increasing this would reduce load, but your node would have to be 258extremely busy node for you to even notice. 259 260 **force-feerates**==*VALUES* 261Networks like regtest and testnet have unreliable fee estimates: we 262usually treat them as the minimum (253 sats/kw) if we can't get them. 263This allows override of one or more of our standard feerates (see 264lightning-feerates(7)). Up to 5 values, separated by '/' can be 265provided: if fewer are provided, then the final value is used for the 266remainder. The values are in per-kw (roughly 1/4 of bitcoind's per-kb 267values), and the order is "opening", "mutual_close", "unilateral_close", 268"delayed_to_us", "htlc_resolution", and "penalty". 269 270You would usually put this option in the per-chain config file, to avoid 271setting it on Bitcoin mainnet! e.g. `~rusty/.lightning/regtest/config`. 272 273### Lightning channel and HTLC options 274 275 **large-channels** 276Removes capacity limits for channel creation. Version 1.0 of the specification 277limited channel sizes to 16777215 satoshi. With this option (which your 278node will advertize to peers), your node will accept larger incoming channels 279and if the peer supports it, will open larger channels. Note: this option 280is spelled **large-channels** but it's pronounced **wumbo**. 281 282 **watchtime-blocks**=*BLOCKS* 283How long we need to spot an outdated close attempt: on opening a channel 284we tell our peer that this is how long they'll have to wait if they 285perform a unilateral close. 286 287 **max-locktime-blocks**=*BLOCKS* 288The longest our funds can be delayed (ie. the longest 289**watchtime-blocks** our peer can ask for, and also the longest HTLC 290timeout we will accept). If our peer asks for longer, we'll refuse to 291create a channel, and if an HTLC asks for longer, we'll refuse it. 292 293 **funding-confirms**=*BLOCKS* 294Confirmations required for the funding transaction when the other side 295opens a channel before the channel is usable. 296 297 **commit-fee**=*PERCENT* [plugin `bcli`] 298The percentage of *estimatesmartfee 2/CONSERVATIVE* to use for the commitment 299transactions: default is 100. 300 301 **max-concurrent-htlcs**=*INTEGER* 302Number of HTLCs one channel can handle concurrently in each direction. 303Should be between 1 and 483 (default 30). 304 305 **cltv-delta**=*BLOCKS* 306The number of blocks between incoming payments and outgoing payments: 307this needs to be enough to make sure that if we have to, we can close 308the outgoing payment before the incoming, or redeem the incoming once 309the outgoing is redeemed. 310 311 **cltv-final**=*BLOCKS* 312The number of blocks to allow for payments we receive: if we have to, we 313might need to redeem this on-chain, so this is the number of blocks we 314have to do that. 315 316Invoice control options: 317 318 **autocleaninvoice-cycle**=*SECONDS* [plugin `autoclean`] 319Perform cleanup of expired invoices every *SECONDS* seconds, or disable 320if 0. Usually unpaid expired invoices are uninteresting, and just take 321up space in the database. 322 323 **autocleaninvoice-expired-by**=*SECONDS* [plugin `autoclean`] 324Control how long invoices must have been expired before they are cleaned 325(if *autocleaninvoice-cycle* is non-zero). 326 327Payment control options: 328 329 **disable-mpp** [plugin `pay`] 330Disable the multi-part payment sending support in the `pay` plugin. By default 331the MPP support is enabled, but it can be desirable to disable in situations 332in which each payment should result in a single HTLC being forwarded in the 333network. 334 335### Networking options 336 337Note that for simple setups, the implicit *autolisten* option does the 338right thing: it will try to bind to port 9735 on IPv4 and IPv6, and will 339announce it to peers if it seems like a public address. 340 341You can instead use *addr* to override this (eg. to change the port), or 342precisely control where to bind and what to announce with the 343*bind-addr* and *announce-addr* options. These will **disable** the 344*autolisten* logic, so you must specifiy exactly what you want! 345 346 **addr**=*\[IPADDRESS\[:PORT\]\]|autotor:TORIPADDRESS\[:SERVICEPORT\]\[/torport=TORPORT\]|statictor:TORIPADDRESS\[:SERVICEPORT\]\[/torport=TORPORT\]\[/torblob=\[blob\]\]* 347 348Set an IP address (v4 or v6) or automatic Tor address to listen on and 349(maybe) announce as our node address. 350 351An empty 'IPADDRESS' is a special value meaning bind to IPv4 and/or 352IPv6 on all interfaces, '0.0.0.0' means bind to all IPv4 353interfaces, '::' means 'bind to all IPv6 interfaces'. If 'PORT' is 354not specified, 9735 is used. If we can determine a public IP 355address from the resulting binding, the address is announced. 356 357If the argument begins with 'autotor:' then it is followed by the 358IPv4 or IPv6 address of the Tor control port (default port 9051), 359and this will be used to configure a Tor hidden service for port 9735. 360The Tor hidden service will be configured to point to the 361first IPv4 or IPv6 address we bind to. 362 363If the argument begins with 'statictor:' then it is followed by the 364IPv4 or IPv6 address of the Tor control port (default port 9051), 365and this will be used to configure a static Tor hidden service for port 9735. 366The Tor hidden service will be configured to point to the 367first IPv4 or IPv6 address we bind to and is by default unique to 368your nodes id. You can add the text '/torblob=BLOB' followed by up to 36964 Bytes of text to generate from this text a v3 onion service 370address text unique to the first 32 Byte of this text. 371You can also use an postfix '/torport=TORPORT' to select the external 372tor binding. The result is that over tor your node is accessible by a port 373defined by you and possible different from your local node port assignment 374 375This option can be used multiple times to add more addresses, and 376its use disables autolisten. If necessary, and 'always-use-proxy' 377is not specified, a DNS lookup may be done to resolve 'IPADDRESS' 378or 'TORIPADDRESS'. 379 380 **bind-addr**=*\[IPADDRESS\[:PORT\]\]|SOCKETPATH* 381Set an IP address or UNIX domain socket to listen to, but do not 382announce. A UNIX domain socket is distinguished from an IP address by 383beginning with a */*. 384 385An empty 'IPADDRESS' is a special value meaning bind to IPv4 and/or 386IPv6 on all interfaces, '0.0.0.0' means bind to all IPv4 387interfaces, '::' means 'bind to all IPv6 interfaces'. 'PORT' is 388not specified, 9735 is used. 389 390This option can be used multiple times to add more addresses, and 391its use disables autolisten. If necessary, and 'always-use-proxy' 392is not specified, a DNS lookup may be done to resolve 'IPADDRESS'. 393 394 **announce-addr**=*IPADDRESS\[:PORT\]|TORADDRESS.onion\[:PORT\]* 395Set an IP (v4 or v6) address or Tor address to announce; a Tor address 396is distinguished by ending in *.onion*. *PORT* defaults to 9735. 397 398Empty or wildcard IPv4 and IPv6 addresses don't make sense here. 399Also, unlike the 'addr' option, there is no checking that your 400announced addresses are public (e.g. not localhost). 401 402This option can be used multiple times to add more addresses, and 403its use disables autolisten. 404 405If necessary, and 'always-use-proxy' is not specified, a DNS 406lookup may be done to resolve 'IPADDRESS'. 407 408 **offline** 409Do not bind to any ports, and do not try to reconnect to any peers. This 410can be useful for maintenance and forensics, so is usually specified on 411the command line. Overrides all *addr* and *bind-addr* options. 412 413 **autolisten**=*BOOL* 414By default, we bind (and maybe announce) on IPv4 and IPv6 interfaces if 415no *addr*, *bind-addr* or *announce-addr* options are specified. Setting 416this to *false* disables that. 417 418 **proxy**=*IPADDRESS\[:PORT\]* 419Set a socks proxy to use to connect to Tor nodes (or for all connections 420if **always-use-proxy** is set). The port defaults to 9050 if not specified. 421 422 **always-use-proxy**=*BOOL* 423Always use the **proxy**, even to connect to normal IP addresses (you 424can still connect to Unix domain sockets manually). This also disables 425all DNS lookups, to avoid leaking information. 426 427 **disable-dns** 428Disable the DNS bootstrapping mechanism to find a node by its node ID. 429 430 **tor-service-password**=*PASSWORD* 431Set a Tor control password, which may be needed for *autotor:* to 432authenticate to the Tor control port. 433 434### Lightning Plugins 435 436lightningd(8) supports plugins, which offer additional configuration 437options and JSON-RPC methods, depending on the plugin. Some are supplied 438by default (usually located in **libexec/c-lightning/plugins/**). If a 439**plugins** directory exists under *lightning-dir* that is searched for 440plugins along with any immediate subdirectories). You can specify 441additional paths too: 442 443 **plugin**=*PATH* 444Specify a plugin to run as part of c-lightning. This can be specified 445multiple times to add multiple plugins. Note that unless plugins themselves 446specify ordering requirements for being called on various hooks, plugins will 447be ordered by commandline, then config file. 448 449 **plugin-dir**=*DIRECTORY* 450Specify a directory to look for plugins; all executable files not 451containing punctuation (other than *.*, *-* or *\_) in 'DIRECTORY* are 452loaded. *DIRECTORY* must exist; this can be specified multiple times to 453add multiple directories. The ordering of plugins within a directory 454is currently unspecified. 455 456 **clear-plugins** 457This option clears all *plugin*, *important-plugin*, and *plugin-dir* options 458preceeding it, 459including the default built-in plugin directory. You can still add 460*plugin-dir*, *plugin*, and *important-plugin* options following this 461and they will have the normal effect. 462 463 **disable-plugin**=*PLUGIN* 464If *PLUGIN* contains a /, plugins with the same path as *PLUGIN* will 465not be loaded at startup. Otherwise, no plugin with that base name will 466be loaded at startup, whatever directory it is in. This option is useful for 467disabling a single plugin inside a directory. You can still explicitly 468load plugins which have been disabled, using lightning-plugin(7) `start`. 469 470 **important-plugin**=*PLUGIN* 471Speciy a plugin to run as part of C-lightning. 472This can be specified multiple times to add multiple plugins. 473Plugins specified via this option are considered so important, that if the 474plugin stops for any reason (including via lightning-plugin(7) `stop`), 475C-lightning will also stop running. 476This way, you can monitor crashes of important plugins by simply monitoring 477if C-lightning terminates. 478Built-in plugins, which are installed with lightningd(8), are automatically 479considered important. 480 481### Experimental Options 482 483Experimental options are subject to breakage between releases: they 484are made available for advanced users who want to test proposed 485features. If lightningd is built configured with 486`--enable-experimental-features` these are on by default. 487 488 **experimental-onion-messages** 489 490Specifying this enables sending, forwarding and receiving onion messages, 491which are in draft status in the BOLT specifications. 492 493 **experimental-offers** 494 495Specifying this enables the `offers` and `fetchinvoice` plugins and 496corresponding functionality, which are in draft status as BOLT12. 497This usually requires **experimental-onion-messages** as well. See 498lightning-offer(7) and lightning-fetchinvoice(7). 499 500 **fetchinvoice-noconnect** 501 502Specifying this prevents `fetchinvoice` and `sendinvoice` from 503trying to connect directly to the offering node as a last resort. 504 505 **experimental-shutdown-wrong-funding** 506 507Specifying this allows the `wrong_funding` field in shutdown: if a 508remote node has opened a channel but claims it used the incorrect txid 509(and the channel hasn't been used yet at all) this allows them to 510negotiate a clean shutdown with the txid they offer. 511 512 **experimental-dual-fund** 513 514Specifying this enables support for the dual funding protocol, 515allowing both parties to contribute funds to a channel. The decision 516about whether to add funds or not to a proposed channel is handled 517automatically by a plugin that implements the appropriate logic for 518your needs. The default behavior is to not contribute funds. 519 520 **experimental-websocket-port** 521 522Specifying this enables support for accepting incoming WebSocket 523connections on that port, on any IPv4 and IPv6 addresses you listen 524to. The normal protocol is expected to be sent over WebSocket binary 525frames once the connection is upgraded. 526 527BUGS 528---- 529 530You should report bugs on our github issues page, and maybe submit a fix 531to gain our eternal gratitude! 532 533AUTHOR 534------ 535 536Rusty Russell <<rusty@rustcorp.com.au>> wrote this man page, and 537much of the configuration language, but many others did the hard work of 538actually implementing these options. 539 540SEE ALSO 541-------- 542 543lightning-listconfigs(7) lightning-setchannelfee(7) lightningd(8) 544lightning-hsmtool(8) 545 546RESOURCES 547--------- 548 549Main web site: <https://github.com/ElementsProject/lightning> 550 551COPYING 552------- 553 554Note: the modules in the ccan/ directory have their own licenses, but 555the rest of the code is covered by the BSD-style MIT license. 556 557