lightning-terminal/doc/config-lnd-remote.md

Connecting LiT to a standalone LND process

By default LiT assumes that lnd is running as a standalone process locally. However litd can connect to lnd running on a remote host.

Quickstart

To connect Lightning Terminal to a remote LND instance first make sure your lnd.conf file contains the following additional configuration settings:

tlsextraip=<externally-reachable-ip-address>
rpclisten=0.0.0.0:10009

Copy the following files that are located in your ~/.lnd/data/chain/bitcoin/mainnet directory on your remote machine to /some/folder/with/lnd/data/ on your local machine (where you’ll be running LiT):

• tls.cert
• admin.macaroon

(Note that with LiT prior to v0.3.5-alpha all *.macaroon files need to be copied from the lnd machine.)

Create a lit.conf file. The default location LiT will look for the configuration file depends on your operating system:

• MacOS: ~/Library/Application Support/Lit/lit.conf
• Linux: ~/.lit/lit.conf
• Windows: ~/AppData/Roaming/Lit/lit.conf

Alternatively you can specify a different location by passing --lit-dir=~/.lit. After creating lit.conf populate it with the following configuration settings:

remote.lnd.rpcserver=<externally-reachable-ip-address>:10009
remote.lnd.macaroonpath=/some/folder/with/lnd/data/admin.macaroon
remote.lnd.tlscertpath=/some/folder/with/lnd/data/tls.cert

Run LiT:

⛰  ./litd --uipassword=UP48lm4VjqxmOxB9X9stry6VTKBRQI

Visit https://localhost:8443 to access LiT.

Additional Configuration

The default "remote" mode means that lnd is started as a standalone process, possibly on another host, and litd connects to it, right after starting its UI server. Once the connection to the remote lnd node has been established, litd then goes ahead and starts faraday, pool and loop and connects them to that lnd node as well.

Connecting LiT to a remote faraday node

To instruct LiT to not start its own integrated faraday daemon but instead connect to an existing node, use the following configuration options:

faraday-mode=remote
remote.faraday.rpcserver=<externally-reachable-ip-address>:8465
remote.faraday.macaroonpath=/some/folder/with/faraday/data/faraday.macaroon
remote.faraday.tlscertpath=/some/folder/with/faraday/data/tls.cert

Connecting LiT to a remote loopd node

To instruct LiT to not start its own integrated loopd daemon but instead connect to an existing node, use the following configuration options:

loop-mode=remote
remote.loop.rpcserver=<externally-reachable-ip-address>:11010
remote.loop.macaroonpath=/some/folder/with/loop/data/loop.macaroon
remote.loop.tlscertpath=/some/folder/with/loop/data/tls.cert

Connecting LiT to a remote poold node

To instruct LiT to not start its own integrated poold daemon but instead connect to an existing node, use the following configuration options:

pool-mode=remote
remote.pool.rpcserver=<externally-reachable-ip-address>:12010
remote.pool.macaroonpath=/some/folder/with/pool/data/pool.macaroon
remote.pool.tlscertpath=/some/folder/with/pool/data/tls.cert

Use command line parameters only

In addition to the LiT specific and remote lnd parameters, you must also provide configuration to the loop, pool, and faraday daemons. For the remote lnd node, all remote.lnd flags must be specified. Note that loopd and faraday will automatically connect to the same remote lnd node, so you do not need to provide them with any additional parameters unless you want to override them. If you do override them, be sure to add the loop., pool., and faraday. prefixes.

To see all available command line options, run litd --help.

The most minimal example command to start litd and connect it to a local lnd node that is running with default configuration settings is:

⛰  litd --uipassword=My$trongP@ssword

All other command line flags are only needed to overwrite the default behavior.

Here is an example command to start litd connected to a testnet lnd that is running on another host and overwrites a few default settings in loop, pool, and faraday (optional):

⛰  litd \
  --httpslisten=0.0.0.0:8443 \
  --uipassword=My$trongP@ssword \
  --letsencrypt \
  --letsencrypthost=loop.merchant.com \
  --lit-dir=~/.lit \
  --network=testnet \
  --remote.lit-debuglevel=debug \
  --remote.lnd.rpcserver=some-other-host:10009 \
  --remote.lnd.macaroonpath=/some/folder/with/lnd/data/admin.macaroon \
  --remote.lnd.tlscertpath=/some/folder/with/lnd/data/tls.cert \
  --loop.loopoutmaxparts=5 \
  --pool.newnodesonly=true \
  --faraday.min_monitored=48h \
  --faraday.connect_bitcoin \
  --faraday.bitcoin.host=some-other-host \
  --faraday.bitcoin.user=testnetuser \
  --faraday.bitcoin.password=testnetpw

Use a configuration file

You can also store the configuration in a persistent ~/.lit/lit.conf file, so you do not need to type in the command line arguments every time you start the server. Just remember to use the appropriate prefixes as necessary.

Make sure you don't add any section headers (the lines starting with [ and ending with ], for example [Application Options]) as these don't work with the additional levels of sub configurations. You can replace them with a comment (starting with the # character) to get the same grouping effect as before.

The most minimal example of a ~/.lit/lit.conf file that connects to a local lnd node that is running with default configuration settings is:

# Application Options
uipassword=My$trongP@ssword

All other configuration settings are only needed to overwrite the default behavior.

Here is an example ~/.lit/lit.conf file that connects LiT to a testnet lnd node running on another host and overwrites a few default settings in loop, pool, and faraday (optional):

# Application Options
httpslisten=0.0.0.0:8443
uipassword=My$trongP@ssword
letsencrypt=true
letsencrypthost=loop.merchant.com
lit-dir=~/.lit
network=testnet

# Remote options
remote.lit-debuglevel=debug

# Remote lnd options
remote.lnd.rpcserver=some-other-host:10009
remote.lnd.macaroonpath=/some/folder/with/lnd/data/admin.macaroon
remote.lnd.tlscertpath=/some/folder/with/lnd/data/tls.cert

# Loop
loop.loopoutmaxparts=5

# Pool
pool.newnodesonly=true

# Faraday
faraday.min_monitored=48h

# Faraday - bitcoin
faraday.connect_bitcoin=true
faraday.bitcoin.host=localhost
faraday.bitcoin.user=testnetuser
faraday.bitcoin.password=testnetpw

The default location for the lit.conf file will depend on your operating system:

• On MacOS: ~/Library/Application Support/Lit/lit.conf
• On Linux: ~/.lit/lit.conf
• On Windows: ~/AppData/Roaming/Lit/lit.conf

Example commands for interacting with the command line

Because not all functionality of lnd (or loop/faraday for that matter) is available through the web UI, it will still be necessary to interact with those daemons through the command line.

We are going through an example for each of the command line tools and will explain the reasons for the extra flags. The examples assume that LiT is started with the following configuration (only relevant parts shown here):

httpslisten=0.0.0.0:8443
lit-dir=~/.lit
network=testnet

remote.lnd.rpcserver=some-other-host:10009
remote.lnd.macaroonpath=/some/folder/with/lnd/data/admin.macaroon
remote.lnd.tlscertpath=/some/folder/with/lnd/data/tls.cert

Because in the remote lnd mode all other LiT components (loop, pool, faraday and the UI server) listen on the same port (8443 in this example) and use the same TLS certificate (~/.lit/tls.cert in this example), some command line calls now need some extra options that weren't necessary before.

NOTE: All mentioned command line tools have the following behavior in common: You either specify the --network flag and the --tlscertpath and --macaroonpath are implied by looking inside the default directories for that network. Or you specify the --tlscertpath and --macaroonpath flags explicitly, then you must not set the --network flag. Otherwise, you will get an error like [lncli] could not load global options: unable to read macaroon path (check the network setting!): open /home/<user>/.lnd/data/chain/bitcoin/testnet/admin.macaroon: no such file or directory.

Example lncli command

The lncli commands in the "remote" mode are the same as if lnd was running standalone on a remote host. We need to specify all flags explicitly.

⛰  lncli --rpcserver=some-other-host:10009 \
  --tlscertpath=/some/folder/with/lnd/data/tls.cert \
  --macaroonpath=/some/folder/with/lnd/data/admin.macaroon \
  getinfo

Example loop command

This is where things get a bit tricky. Because as mentioned above, loopd also runs on the same port as the UI server. That's why we have to both specify the host:port as well as the TLS certificate of LiT. But loopd verifies its own macaroon, so we have to specify that one from the .loop directory.

⛰  loop --rpcserver=localhost:8443 --tlscertpath=~/.lit/tls.cert \
  --macaroonpath=~/.loop/testnet/loop.macaroon \
  quote out 500000

You can easily create an alias for this by adding the following line to your ~/.bashrc file:

⛰  alias lit-loop="loop --rpcserver=localhost:8443 --tlscertpath=~/.lit/tls.cert --macaroonpath=~/.loop/testnet/loop.macaroon"

Example pool command

Again, poold also runs on the same port as the UI server and we have to specify the host:port and the TLS certificate of LiT but use the macaroon from the .pool directory.

⛰  pool --rpcserver=localhost:8443 --tlscertpath=~/.lit/tls.cert \
  --macaroonpath=~/.pool/testnet/pool.macaroon \
  accounts list

You can easily create an alias for this by adding the following line to your ~/.bashrc file:

⛰  alias lit-pool="pool --rpcserver=localhost:8443 --tlscertpath=~/.lit/tls.cert --macaroonpath=~/.pool/testnet/pool.macaroon"

Example frcli command

Faraday's command line tool follows the same pattern as loop. We also have to specify the server and TLS flags for lnd but use faraday's macaroon:

⛰  frcli --rpcserver=localhost:8443 --tlscertpath=~/.lit/tls.cert \
  --macaroonpath=~/.faraday/testnet/faraday.macaroon \
  audit

You can easily create an alias for this by adding the following line to your ~/.bashrc file:

⛰  alias lit-frcli="frcli --rpcserver=localhost:8443 --tlscertpath=~/.lit/tls.cert --macaroonpath=~/.faraday/testnet/faraday.macaroon"

Shutting down LiT

In the remote mode, there is no explicit command for stopping LiT yet. But a clean shutdown can be achieved by either pressing <Ctrl> + c in the terminal where LiT is running. Or, if LiT is running in the background, the following command can be used to send an interrupt signal which will trigger the clean shutdown:

⛰  kill -s INT $(pidof litd)