From dcd4117928e688699058beea240db6c389529eab Mon Sep 17 00:00:00 2001 From: Leo Date: Thu, 8 Oct 2026 15:48:08 -0700 Subject: [PATCH 01/11] Harden opt-add-lightning-terminal.yml --- .../opt-add-lightning-terminal.yml | 35 ++++++++----------- 1 file changed, 15 insertions(+), 20 deletions(-) diff --git a/docker-compose-generator/docker-fragments/opt-add-lightning-terminal.yml b/docker-compose-generator/docker-fragments/opt-add-lightning-terminal.yml index 63f06cd6b..a1f3859e8 100644 --- a/docker-compose-generator/docker-fragments/opt-add-lightning-terminal.yml +++ b/docker-compose-generator/docker-fragments/opt-add-lightning-terminal.yml @@ -1,45 +1,40 @@ -required-routes: - - "lightning-terminal" services: btcpayserver: - environment: - BTCPAY_EXTERNALSERVICES: "Lightning Terminal:${BTCPAY_PROTOCOL:-https}://${BTCPAY_HOST}/lit/;" + volumes: + - "lnd_lit_datadir:/lit:ro" lnd_bitcoin: environment: LND_EXTRA_ARGS: | rpcmiddleware.enable=true lnd_lit: - image: "lightninglabs/lightning-terminal:v0.17.6-path-prefix" + image: "lightninglabs/lightning-terminal:v0.17.6" + container_name: btcpayserver_litd restart: unless-stopped environment: LIT_AUTO_MIGRATE_TO_SQL: "true" expose: - - "8080" - secrets: - - lit_password + - "8443" volumes: - - "lnd_lit_datadir:/root/.lit" + - "lnd_lit_datadir:/lit" - "lnd_bitcoin_datadir:/data/lnd:ro" - - "bitcoin_datadir:/deps/.bitcoin:ro" links: - - bitcoind - lnd_bitcoin command: - - "--insecure-httplisten=0.0.0.0:8080" + - "--disableui" + - "--lit-dir=/lit/.lit" + - "--loop.loopdir=/lit/.loop" + - "--pool.basedir=/lit/.pool" + - "--faraday.faradaydir=/lit/.faraday" + - "--taproot-assets.tapddir=/lit/.tapd" + - "--httpslisten=0.0.0.0:8443" - "--network=${NBITCOIN_NETWORK}" - - "--uipassword_file=/run/secrets/lit_password" - "--lnd-mode=remote" - "--remote.lnd.rpcserver=lnd_bitcoin:10009" - "--remote.lnd.macaroonpath=/data/lnd/admin.macaroon" - "--remote.lnd.tlscertpath=/data/lnd/tls.cert" - - "--faraday.connect_bitcoin" - - "--faraday.bitcoin.host=bitcoind:43782" - - "--faraday.bitcoin.user=lnd" - - "--faraday.bitcoin.passwordfile=/deps/.bitcoin/RPCUsers/lnd" + volumes: lnd_lit_datadir: -secrets: - lit_password: - file: ../secrets/lit_password + required: - "bitcoin-lnd" From 7e70d2ea8cfe492dca012bb6c0796169e0af5b06 Mon Sep 17 00:00:00 2001 From: Leo Date: Thu, 8 Oct 2026 15:49:41 -0700 Subject: [PATCH 02/11] remove lightning-terminal nginx route --- nginx/routes/lightning-terminal.conf | 19 ------------------- 1 file changed, 19 deletions(-) delete mode 100644 nginx/routes/lightning-terminal.conf diff --git a/nginx/routes/lightning-terminal.conf b/nginx/routes/lightning-terminal.conf deleted file mode 100644 index 6ed01d84f..000000000 --- a/nginx/routes/lightning-terminal.conf +++ /dev/null @@ -1,19 +0,0 @@ -location /lit/ { - set $btcpay_route_upstream lnd_lit; - rewrite ^/lit/(.*)$ /$1 break; - proxy_pass http://$btcpay_route_upstream:8080; - proxy_redirect ~^http://lnd_lit:8080/?(.*)$ /lit/$1; -} - -# LND's wallet unlocker and state methods are not protected by macaroons. Return -# 500 to mimic ChangePassword after a wallet is open, and avoid logging bot traffic. -location ~* ^/lnrpc\.(WalletUnlocker/(GenSeed|InitWallet|UnlockWallet|ChangePassword)|State/(GetState|SubscribeState))$ { - access_log off; - return 500; -} - -location ~* ^/(ln|loop|pool|lit)rpc\. { - set $btcpay_route_upstream lnd_lit; - proxy_pass http://$btcpay_route_upstream:8080; - proxy_redirect ~^http://lnd_lit:8080(/.*)$ $1; -} From 43e4052ded8d81d68afb08ab0818d86e0784f43d Mon Sep 17 00:00:00 2001 From: Leo Date: Thu, 8 Oct 2026 15:52:29 -0700 Subject: [PATCH 03/11] add frcli litcli loop pool and tapcli scripts --- bitcoin-frcli.sh | 12 ++++++++++++ bitcoin-litcli.sh | 10 ++++++++++ bitcoin-loop.sh | 12 ++++++++++++ bitcoin-pool.sh | 12 ++++++++++++ bitcoin-tapcli.sh | 12 ++++++++++++ 5 files changed, 58 insertions(+) create mode 100755 bitcoin-frcli.sh create mode 100755 bitcoin-litcli.sh create mode 100755 bitcoin-loop.sh create mode 100755 bitcoin-pool.sh create mode 100755 bitcoin-tapcli.sh diff --git a/bitcoin-frcli.sh b/bitcoin-frcli.sh new file mode 100755 index 000000000..9484c75e4 --- /dev/null +++ b/bitcoin-frcli.sh @@ -0,0 +1,12 @@ +#!/bin/bash + +. /etc/profile.d/btcpay-env.sh + +docker exec btcpayserver_litd frcli \ + --rpcserver=localhost:8443 \ + --tlscertpath=/lit/.lit/tls.cert \ + --macaroonpath="/lit/.faraday/$NBITCOIN_NETWORK/faraday.macaroon" \ + --network="$NBITCOIN_NETWORK" \ + "$@" + +# Example usage: . ./bitcoin-frcli.sh insights diff --git a/bitcoin-litcli.sh b/bitcoin-litcli.sh new file mode 100755 index 000000000..1bf889bbf --- /dev/null +++ b/bitcoin-litcli.sh @@ -0,0 +1,10 @@ +#!/bin/bash + +. /etc/profile.d/btcpay-env.sh + +docker exec btcpayserver_litd litcli \ + --basedir="/lit/.lit/" \ + --network="$NBITCOIN_NETWORK" \ + "$@" + +# Example usage: . ./bitcoin-litcli.sh status diff --git a/bitcoin-loop.sh b/bitcoin-loop.sh new file mode 100755 index 000000000..dd81bab7f --- /dev/null +++ b/bitcoin-loop.sh @@ -0,0 +1,12 @@ +#!/bin/bash + +. /etc/profile.d/btcpay-env.sh + +docker exec btcpayserver_litd loop \ + --rpcserver=localhost:8443 \ + --tlscertpath=/lit/.lit/tls.cert \ + --macaroonpath="/lit/.loop/$NBITCOIN_NETWORK/loop.macaroon" \ + --network="$NBITCOIN_NETWORK" \ + "$@" + +# Example usage: . ./bitcoin-loop.sh getinfo diff --git a/bitcoin-pool.sh b/bitcoin-pool.sh new file mode 100755 index 000000000..21cd89a14 --- /dev/null +++ b/bitcoin-pool.sh @@ -0,0 +1,12 @@ +#!/bin/bash + +. /etc/profile.d/btcpay-env.sh + +docker exec btcpayserver_litd pool \ + --rpcserver=localhost:8443 \ + --tlscertpath=/lit/.lit/tls.cert \ + --macaroonpath="/lit/.pool/$NBITCOIN_NETWORK/pool.macaroon" \ + --network="$NBITCOIN_NETWORK" \ + "$@" + +# Example usage: . ./bitcoin-pool.sh getinfo diff --git a/bitcoin-tapcli.sh b/bitcoin-tapcli.sh new file mode 100755 index 000000000..dcfa1a629 --- /dev/null +++ b/bitcoin-tapcli.sh @@ -0,0 +1,12 @@ +#!/bin/bash + +. /etc/profile.d/btcpay-env.sh + +docker exec btcpayserver_litd tapcli \ + --rpcserver=localhost:8443 \ + --tlscertpath=/lit/.lit/tls.cert \ + --macaroonpath="/lit/.tapd/data/$NBITCOIN_NETWORK/admin.macaroon" \ + --network="$NBITCOIN_NETWORK" \ + "$@" + +# Example usage: . ./bitcoin-tapcli.sh getinfo From ed94cbf11b22e4c804f2382a10d9426305a4a8f0 Mon Sep 17 00:00:00 2001 From: Leo Date: Tue, 13 Oct 2026 12:36:28 -0700 Subject: [PATCH 04/11] remove litd password test --- tests/docker-compose-generator-test.sh | 23 ----------------------- 1 file changed, 23 deletions(-) diff --git a/tests/docker-compose-generator-test.sh b/tests/docker-compose-generator-test.sh index 819e84bc0..88befe52f 100755 --- a/tests/docker-compose-generator-test.sh +++ b/tests/docker-compose-generator-test.sh @@ -119,29 +119,6 @@ docker compose \ -f "$test_dir/Generated/docker-compose.clightning-tor-test.yml" \ config --quiet -( - cd "$generator_dir" - BTCPAYGEN_REVERSEPROXY="nginx" \ - BTCPAYGEN_ADDITIONAL_FRAGMENTS="opt-add-lightning-terminal" \ - BTCPAYGEN_SUBNAME="lit-secret-test" \ - dotnet run \ - --no-build \ - --project src/docker-compose-generator.csproj \ - --configuration Release \ - --no-launch-profile \ - -p:TargetFrameworkOverride=net8.0 -) - -jq -e '.secrets | index("../secrets/lit_password") != null' \ - "$test_dir/Generated/manifest.json" >/dev/null -grep -q -- '--uipassword_file=/run/secrets/lit_password' \ - "$test_dir/Generated/docker-compose.lit-secret-test.yml" -if grep -q -- '--uipassword=' \ - "$test_dir/Generated/docker-compose.lit-secret-test.yml"; then - printf 'Lightning Terminal password was rendered into the command\n' >&2 - exit 1 -fi - set +e proxy_conflict_output="$({ cd "$generator_dir" || exit 1 From a735f1b8a1cc132e575c6f65b545c9fe2c3ae98a Mon Sep 17 00:00:00 2001 From: Leo Date: Tue, 13 Oct 2026 12:43:46 -0700 Subject: [PATCH 05/11] remove special litd password case --- generate-secrets.sh | 17 ++++++----------- tests/generate-secrets-test.sh | 8 -------- 2 files changed, 6 insertions(+), 19 deletions(-) diff --git a/generate-secrets.sh b/generate-secrets.sh index e70d7de13..5fc92e786 100755 --- a/generate-secrets.sh +++ b/generate-secrets.sh @@ -64,20 +64,15 @@ while IFS= read -r secret; do fi temporary="$(mktemp "$secret_dir/.btcpay-secret.XXXXXX")" - # Preserve the UI password when migrating existing LiT deployments. - if [[ "$relative_path" == "lit_password" && -n "${LIT_PASSWD:-}" ]]; then - printf '%s' "$LIT_PASSWD" > "$temporary" - else - secret_value="" - while (( ${#secret_value} < 64 )); do - secret_value+="$(dd if=/dev/urandom bs=128 count=1 2>/dev/null | LC_ALL=C tr -dc 'a-zA-Z0-9')" - done - printf '%s' "${secret_value:0:64}" > "$temporary" - fi + secret_value="" + while (( ${#secret_value} < 64 )); do + secret_value+="$(dd if=/dev/urandom bs=128 count=1 2>/dev/null | LC_ALL=C tr -dc 'a-zA-Z0-9')" + done + printf '%s' "${secret_value:0:64}" > "$temporary" chmod 644 -- "$temporary" if [[ ! -e "$secret_path" && ! -L "$secret_path" ]]; then mv -n -- "$temporary" "$secret_path" printf 'Generated secret %s\n' "$secret" fi rm -f -- "$temporary" -done < <(jq -r '(.secrets // [])[]' "$manifest") +done < <(jq -r '(.secrets // [])[]' "$manifest") \ No newline at end of file diff --git a/tests/generate-secrets-test.sh b/tests/generate-secrets-test.sh index cb5165b07..4bb256036 100755 --- a/tests/generate-secrets-test.sh +++ b/tests/generate-secrets-test.sh @@ -20,14 +20,6 @@ original="$(< "$test_dir/secrets/test")" "$repo_dir/generate-secrets.sh" "$test_dir/Generated/manifest.json" [[ "$(< "$test_dir/secrets/test")" == "$original" ]] -jq -n '{secrets:["../secrets/lit_password"]}' > "$test_dir/Generated/manifest.json" -LIT_PASSWD="existing-lit-password" \ - "$repo_dir/generate-secrets.sh" "$test_dir/Generated/manifest.json" -[[ "$(< "$test_dir/secrets/lit_password")" == "existing-lit-password" ]] -LIT_PASSWD="replacement-lit-password" \ - "$repo_dir/generate-secrets.sh" "$test_dir/Generated/manifest.json" -[[ "$(< "$test_dir/secrets/lit_password")" == "existing-lit-password" ]] - jq -n '{requiredRoutes:[],optionalRoutes:[],fragments:[]}' > "$test_dir/Generated/manifest.json" "$repo_dir/generate-secrets.sh" "$test_dir/Generated/manifest.json" From cc4db7f47ba7a78f56bcad41ba20970cd135090a Mon Sep 17 00:00:00 2001 From: Leo Date: Tue, 13 Oct 2026 13:18:43 -0700 Subject: [PATCH 06/11] update documentation --- docs/lightning-terminal.md | 56 +++++++++++++++++++++++++++----------- 1 file changed, 40 insertions(+), 16 deletions(-) diff --git a/docs/lightning-terminal.md b/docs/lightning-terminal.md index bddc6eb5c..e0b902a0b 100644 --- a/docs/lightning-terminal.md +++ b/docs/lightning-terminal.md @@ -1,7 +1,7 @@ # Lightning Terminal -[Lightning Terminal](https://github.com/lightninglabs/lightning-terminal) (LiT) is a browser-based interface for managing channel liquidity. -It integrates the Lightning Labs services Loop, Poold and Faraday all in one and offers a web UI to manage them. +[Lightning Terminal](https://github.com/lightninglabs/lightning-terminal) (LiT) is a software bundle for Lightning Labs products and services. +It integrates Loop, Pool, Faraday and Taproot Assets and includes LND Accounts and LNC Sessions. This fragment requires Bitcoin LND. It selects that dependency automatically. ## Installation @@ -10,9 +10,7 @@ This requires an existing BTCPay Server Docker deployment and must be run from a root login shell. The fragment selects Bitcoin LND automatically. > **Important:** Lightning Terminal receives LND's administrative macaroon and -> can control funds and channels; it is not a read-only dashboard. Its UI and -> RPC endpoints are routed through the public BTCPay hostname. Protect the -> generated UI password and consider an additional access-control layer. +> can control funds and channels. Generate LNC Sessions with caution. The fragment enables LiT's automatic bbolt-to-SQL migration. Once that migration completes, its data cannot be downgraded to a pre-0.17 LiT release or migrated @@ -26,20 +24,46 @@ Enable the fragment: btcpay-fragments add opt-add-lightning-terminal ``` -Setup generates a 64-character UI password once, stores it in -`secrets/lit_password`, and mounts it into the container as a Compose secret. -Display the password from a root login shell with: +Lightning Terminal appears under **Server Settings > Services**. -```bash -cat "$BTCPAY_BASE_DIRECTORY/btcpayserver-docker/secrets/lit_password" -``` +## Command Line Interface + +To interact with LiT you may use the command line interface over gRPC. To create an admin session: + +`. ./litcli.sh sessions add --label "btcpay" --type admin` + +To see the current Loop terms: + +`. ./loop.sh terms` + +To interact with Pool: + +`. ./loop.sh getinfo` + + +To get a report from Faraday: + +`. ./frcli.sh insights` + +To interact with Taproot Assets: + +`. ./tapcli.sh getinfo` + +## Web Interface + +To interact with LiT through the web-UI you will have to first generate a session through the command line (shown above). + +Then, navigate to `https://terminal.lightning.engineering` and click on "Connect My Node." + +Enter your pairing phrase and set a password. Each pairing phrase can only be used once. + +You may inspect your sessions with: + +`. ./bitcoin-litcli.sh sessions list all` -Treat the secret file and Docker access as privileged. To rotate the password, -replace the file contents with a new password of at least eight characters and -restart the `lnd_lit` service. +And revoke a session with: -Lightning Terminal appears under **Server Settings > Services** and is served at -`/lit/` on the BTCPay Server host. +`. ./bitcoin-litcli.sh sessions revoke --localpubkey` ## Troubleshooting From 830f888c96395dd7c739fa7452ac7ad4ffc831ae Mon Sep 17 00:00:00 2001 From: Leo Date: Tue, 13 Oct 2026 13:19:04 -0700 Subject: [PATCH 07/11] rename CLI scripts --- bitcoin-frcli.sh => frcli.sh | 0 bitcoin-litcli.sh => litcli.sh | 0 bitcoin-loop.sh => loop.sh | 0 bitcoin-pool.sh => pool.sh | 0 bitcoin-tapcli.sh => tapcli.sh | 0 5 files changed, 0 insertions(+), 0 deletions(-) rename bitcoin-frcli.sh => frcli.sh (100%) rename bitcoin-litcli.sh => litcli.sh (100%) rename bitcoin-loop.sh => loop.sh (100%) rename bitcoin-pool.sh => pool.sh (100%) rename bitcoin-tapcli.sh => tapcli.sh (100%) diff --git a/bitcoin-frcli.sh b/frcli.sh similarity index 100% rename from bitcoin-frcli.sh rename to frcli.sh diff --git a/bitcoin-litcli.sh b/litcli.sh similarity index 100% rename from bitcoin-litcli.sh rename to litcli.sh diff --git a/bitcoin-loop.sh b/loop.sh similarity index 100% rename from bitcoin-loop.sh rename to loop.sh diff --git a/bitcoin-pool.sh b/pool.sh similarity index 100% rename from bitcoin-pool.sh rename to pool.sh diff --git a/bitcoin-tapcli.sh b/tapcli.sh similarity index 100% rename from bitcoin-tapcli.sh rename to tapcli.sh From 3b24d9253f480f33162e899259316768f3df783b Mon Sep 17 00:00:00 2001 From: Leo Date: Tue, 13 Oct 2026 13:36:52 -0700 Subject: [PATCH 08/11] register scripts through helpers.sh and simplify documentation --- docs/lightning-terminal.md | 14 +++++++------- helpers.sh | 5 +++++ 2 files changed, 12 insertions(+), 7 deletions(-) diff --git a/docs/lightning-terminal.md b/docs/lightning-terminal.md index e0b902a0b..03b78df43 100644 --- a/docs/lightning-terminal.md +++ b/docs/lightning-terminal.md @@ -30,24 +30,24 @@ Lightning Terminal appears under **Server Settings > Services**. To interact with LiT you may use the command line interface over gRPC. To create an admin session: -`. ./litcli.sh sessions add --label "btcpay" --type admin` +`litcli.sh sessions add --label "btcpay" --type admin` To see the current Loop terms: -`. ./loop.sh terms` +`loop.sh terms` To interact with Pool: -`. ./loop.sh getinfo` +`loop.sh getinfo` To get a report from Faraday: -`. ./frcli.sh insights` +`frcli.sh insights` To interact with Taproot Assets: -`. ./tapcli.sh getinfo` +`tapcli.sh getinfo` ## Web Interface @@ -59,11 +59,11 @@ Enter your pairing phrase and set a password. Each pairing phrase can only be us You may inspect your sessions with: -`. ./bitcoin-litcli.sh sessions list all` +`bitcoin-litcli.sh sessions list all` And revoke a session with: -`. ./bitcoin-litcli.sh sessions revoke --localpubkey` +`bitcoin-litcli.sh sessions revoke --localpubkey` ## Troubleshooting diff --git a/helpers.sh b/helpers.sh index 625b4fe17..9a19c6866 100755 --- a/helpers.sh +++ b/helpers.sh @@ -29,6 +29,11 @@ install_tooling() { "btcpayserver_bitcoind" "bitcoin-cli.sh" "Command line for your Bitcoin instance" \ "btcpayserver_clightning_bitcoin" "bitcoin-lightning-cli.sh" "Command line for your Bitcoin C-Lightning instance" \ "btcpayserver_lnd_bitcoin" "bitcoin-lncli.sh" "Command line for your Bitcoin LND instance" \ + "btcpayserver_litd" "frcli.sh" "Command Line for your Faraday instance" \ + "btcpayserver_litd" "litcli.sh" "Command Line for your litd instance" \ + "btcpayserver_litd" "loop.sh" "Command Line for your Loop instance" \ + "btcpayserver_litd" "pool.sh" "Command Line for your Pool instance" \ + "btcpayserver_litd" "tapcli.sh" "Command Line for your Taproot Assets instance" \ "phoenixd" "phoenix-cli.sh" "Command line for your Phoenixd instance" \ "btcpayserver_dashd" "dash-cli.sh" "Command line for your Dash instance" \ "btcpayserver_dogecoind" "dogecoin-cli.sh" "Command line for your Dogecoin instance" \ From b8432bdb37832dd126f581ef0ee29f3bd1182924 Mon Sep 17 00:00:00 2001 From: Leo Date: Tue, 13 Oct 2026 13:38:48 -0700 Subject: [PATCH 09/11] improve documentation based on agentic feedback --- docs/lightning-terminal.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/lightning-terminal.md b/docs/lightning-terminal.md index 03b78df43..97f64ae73 100644 --- a/docs/lightning-terminal.md +++ b/docs/lightning-terminal.md @@ -61,9 +61,9 @@ You may inspect your sessions with: `bitcoin-litcli.sh sessions list all` -And revoke a session with: +Retrieve the local pubkey using the command above revoke a session with: -`bitcoin-litcli.sh sessions revoke --localpubkey` +`bitcoin-litcli.sh sessions revoke --localpubkey ` ## Troubleshooting From 28b29bd1a5d3dd5ff6ed016ca1eae8866c45dcb5 Mon Sep 17 00:00:00 2001 From: Leo Date: Tue, 13 Oct 2026 13:53:42 -0700 Subject: [PATCH 10/11] pool loop typo --- docs/lightning-terminal.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/lightning-terminal.md b/docs/lightning-terminal.md index 97f64ae73..9a33eca6f 100644 --- a/docs/lightning-terminal.md +++ b/docs/lightning-terminal.md @@ -38,7 +38,7 @@ To see the current Loop terms: To interact with Pool: -`loop.sh getinfo` +`pool.sh getinfo` To get a report from Faraday: From 0afab422f9cfaf11c1b5daa0ef8ac5c235a6ebff Mon Sep 17 00:00:00 2001 From: Leo Date: Tue, 13 Oct 2026 13:54:40 -0700 Subject: [PATCH 11/11] remove bitcoin- prefix from examples --- docs/lightning-terminal.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/lightning-terminal.md b/docs/lightning-terminal.md index 9a33eca6f..bf501dc10 100644 --- a/docs/lightning-terminal.md +++ b/docs/lightning-terminal.md @@ -59,11 +59,11 @@ Enter your pairing phrase and set a password. Each pairing phrase can only be us You may inspect your sessions with: -`bitcoin-litcli.sh sessions list all` +`litcli.sh sessions list all` Retrieve the local pubkey using the command above revoke a session with: -`bitcoin-litcli.sh sessions revoke --localpubkey ` +`litcli.sh sessions revoke --localpubkey ` ## Troubleshooting