Bonus guide: Auto-unlock LND on startup

Difficulty: Intermediate

Status: Not tested v3

Please note: this guide has not been updated to LND 0.5 yet and might not work as intended.

It takes a litte getting used to the fact that the LND wallet needs to be manually unlocked everytime the LND daemon is restarted. This makes sense from a security perspective, as the wallet is encrypted and the key is not stored on the same machine. For reliable operations, however, this is not optimal, as you can easily recover LND after it restarts for some reason (crash or power outage), but then it’s stuck with a locked wallet and cannot operate at all.

This is why a script that automatically unlocks the wallet is helpful. The password is stored in a root-only directory as plaintext, so clearly not so secure, but for reasonable amounts this is a good middle-ground in my opinion. You can always decide to stick to manual unlocking, or implement a solution that unlocks the wallet from a remote machine.

🚨 Important: this works only for “systemd” version 230+. You can check this as follows: $ systemd --version

  • As user “admin”, create a new directory, prepare it and save your LND wallet password [C] into a text file $ sudo mkdir -m 700 /etc/lnd $ sudo chown root:root /etc/lnd $ sudo install -o root -g root -m 600 -T /dev/null /etc/lnd/pwd $ sudo nano /etc/lnd/pwd

  • The following script unlocks the LND wallet through its web service (REST interface). Some additional information:
    • The script checks if the Pi has just booted or if just the service restarted. Depending on that, it waits for either 3 minutes (180s) or 10 seconds for lnd to be ready. This seem to work fine, but you can be adjust the sleep time if you run into timeout issues.
    • This script automatically detects whether you are on Bitcoin testnet or mainnet.
    • The output of the API call is appended to the file debug.log. Check here first if your wallet just does not unlock (you won’t see another error).
    • All automatic unlocks are recorded in audit.log.
  • Copy the following script it into a new file. $ sudo install -o root -g root -m 700 -T /dev/null /etc/lnd/unlock $ sudo nano /etc/lnd/unlock

    # LND wallet auto-unlock script (Updated for LND 0.5 and above)
    # 2018 by meeDamian, robclark56 (Updated by zwarbo, martinatime, CodingMuziekwijk)
    upSeconds="$(cat /proc/uptime | grep -o '^[0-9]\+')"
    upMins=$((${upSeconds} / 60))
    if [ "${upMins}" -lt "5" ]
      /bin/sleep 180s
      /bin/sleep 10s
    chain="$(bitcoin-cli -datadir=${BITCOIN_DIR} getblockchaininfo | jq -r '.chain')"
    curl -s \
            -H "Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 ${LN_ROOT}/data/chain/bitcoin/${chain}net/admin.macaroon))" \
            --cacert ${LN_ROOT}/tls.cert \
            -X POST -d "{\"wallet_password\": \"$(cat /etc/lnd/pwd | tr -d '\n' | base64 -w0)\"}" \
            https://localhost:8080/v1/unlockwallet >> /etc/lnd/debug.log 2>&1
    echo "$? $(date)" >> /etc/lnd/audit.log
    exit 0
  • Edit the LND systemd unit. This starts the script directly after LND is running. $ sudo nano /etc/systemd/system/lnd.service

    # remove this line (if present):
    # PIDFile=/home/bitcoin/.lnd/
    # add this line directly below ExecStart:
    # make sure that the overall timeout is longer than the script wait time, eg. 240s
  • Edit the LND config file to enable the REST interface on port 8080 $ sudo nano /home/bitcoin/.lnd/lnd.conf

    # add the following line in the [Application Options] section
  • Reload the systemd unit, restart LND and watch the startup process to see if the wallet is automatically unlocked

    $ sudo systemctl daemon-reload
    $ sudo systemctl restart lnd
  • You can observe how the LND starts and the wallet is unlocked by loggin into a second session and watching the log file: $ sudo journalctl -u lnd -f

« Back: + Lightning