Skip to main content Link Search Menu Expand Document (external link)

Bonus guide: Core Lightning

CLN - Core Lightning is a lightweight, highly customizable and standard compliant implementation of the Lightning Network protocol. It can be used for the RaspiBolt as a replacement for LND or it can be run alongside it to create a second lightning nodes running on the same machine.

Difficulty: Medium

Status: Tested v3

Core Lightning

Table of contents

  1. Introduction
  2. Requirements
  3. Installation
    1. User Creation
    2. Data directories
    3. Dependencies & Symbolic Links
    4. Download
    5. Building CLN
  4. Configuration
    1. Config File
    2. Shortcuts & Aliases
    3. Autostart on boot
  5. CLN in action
  6. Allow user “admin” to work with CLN
  7. Backup
  8. Upgrade CLN
  9. Optional Steps
    1. Wallet Encryption
    2. Auto-Unlocking on Startup


Core Lightning (previously c-lightning) was one of the first implementation of the Bitcoin Lightning Network.


  • Bitcoin Core


We will download, verify, install and configure CLN on your RaspiBolt setup. This can be done independently from an existing LND installation. In fact, you can run both at the same time if you wish to.

User Creation

  • As “admin”, create a new user named “lightningd” and add it to groups “bitcoin” and “debian-tor”. Also add “admin” to group “lightningd” for later use.

    $ sudo adduser --disabled-password --gecos "" lightningd
    $ sudo usermod -a -G bitcoin,debian-tor lightningd
    $ sudo adduser admin lightningd

Data directories

  • Create data directories for CLN and future plugins. Adjust permissions afterwards.

    $ sudo mkdir /data/lightningd
    $ sudo mkdir /data/lightningd-plugins-available
    $ sudo chown -R lightningd:lightningd /data/lightningd
    $ sudo chown -R lightningd:lightningd /data/lightningd-plugins-available
  • Install required dependencies to compile CLN’s source code.

    $ sudo apt-get install -y \
      autoconf automake build-essential git libtool libgmp-dev libsqlite3-dev \
      python3 python3-pip net-tools zlib1g-dev libsodium-dev gettext
    $ pip3 install --user --upgrade pip
  • Open a “lightningd” user session and create symbolic links to bitcoin and lightningd data directories.

    $ sudo su - lightningd
    $ ln -s /data/lightningd /home/lightningd/.lightning
    $ ln -s /data/bitcoin /home/lightningd/.bitcoin
  • Display the links and check that they’re not shown in red (indicating errors).

    $ ls -la


  • As user “lightningd” download the git repository to the home folder of user “lightningd”.

    $ git clone
    $ cd lightning
    $ git fetch --all --tags
    $ git reset --hard v0.11.2
  • Don’t trust, verify! Check who released the current version and get their signing keys and verify checksums. Verification step should output Good Signature.

    $ wget -O "pgp_keys.asc"
    $ gpg --import ./pgp_keys.asc
    $ git verify-tag v0.11.2
  • Download user specific python packages.

    $ pip3 install --user mrkd==0.2.0
    $ pip3 install --user mistune==0.8.4
    $ pip3 install --user mako

Building CLN

  • Configure and build the source code. Experimental features will be activated. Read more about them here.

    $ ./configure --enable-experimental-features
    $ make


Config File

  • Create and edit the configuration file for CLN.

    $ cd /home/lightningd/.lightning
    $ nano config
  • Insert the following content, adjust parameters in brackets to your likings. At least remove the brackets else lightningd will not start up correctly! Choose if you want to replicate CLN’s channel database file to separate storage. It’s good practice to keep a synchronous state of the database somewhere else to be able to recover off-chain funds in case of emergency.

    alias=<your fancy alias>
    rgb=<your hex color>
    # for admin to interact with lightning-cli
    # default fees and channel min size
    min-capacity-sat=<your minchansize>
    ## optional
    # wumbo channels
    # channel confirmations needed
    # autoclean (86400=daily)
    # wallet settings (replication recommended, adjust backup path)
    # no replication:
    # network

Shortcuts & Aliases

  • Create shortcuts and aliases for easier command handling.

    $ cd ~/
    $ nano .bashrc
  • Append the following at the end of the file.

    alias lightning-cli="~/lightning/cli/lightning-cli"
    alias lightningd="~/lightning/lightningd/lightningd"
    alias hsmtool="~/lightning/tools/hsmtool"

Autostart on boot

  • As “admin”, create a systemd service that is automatically run on system startup.

    $ sudo nano /etc/systemd/system/lightningd.service
  • Insert the following content:

    # RaspiBolt: systemd unit for lightningd
    # /etc/systemd/system/lightningd.service
    Description=Core Lightning daemon
    ExecStart=/bin/sh -c '/home/lightningd/lightning/lightningd/lightningd \
                           --conf=/data/lightningd/config \
                           --daemon \
    ExecStop=/bin/sh -c '/home/lightningd/lightning/cli/lightning-cli stop'
    # process management
    # hardening measures
  • Enable and startup CLN.

    $ sudo systemctl daemon-reload
    $ sudo systemctl enable lightningd.service
    $ sudo systemctl start lightningd.service
  • Daemon information is now written into system journal. See the journal for CLN messages with the following command.

    $ sudo journalctl -f -u lightningd

CLN in action

  • If lightningd.service started without errors, we can check out and try CLN commands.

    $ sudo su - lightningd 
    $ lightning-cli --version
    $ lightning-cli getinfo
    $ lightning-cli listfunds

Allow user “admin” to work with CLN

  • Allow “admin” to access lightningd commands. Create a symlink, adjust permissions and create aliases (switch to “admin” with exit).

    $ ln -s /data/lightningd /home/admin/.lightning
    $ sudo chmod -R g+x /data/lightningd/bitcoin/
    $ nano .bashrc
    alias lightning-cli="/home/lightningd/lightning/cli/lightning-cli"
    alias lightningd="/home/lightningd/lightning/lightningd/lightningd"
    alias hsmtool="/home/lightningd/lightning/tools/hsmtool"


  • It is at least recommended to backup the wallet file hsm_secret that you can find in CLN’s data directory home/lightningd/.lightning/bitcoin/.
  • For more detailed information, please have a look at the official docs and RaspiBlitz’ incredible FAQ.

Upgrade CLN

  • Upgrade CLN with care and follow the instructions on CLN repository completely to understand the changes.
  • Remove the git repository or git pull from within and redo the verification and building steps as described above.
  • Verify with lightning-cli --version that the update applied.
  • Restart the systemd service for the update to take effect and reload configuration.

    $ sudo systemctl restart lightningd.service

Optional Steps

Wallet Encryption

  • Encrypt hsm_secret with a password as user “lightningd”. Choose a password and take a note!

    $ hsmtool encrypt .lightning/bitcoin/hsm_secret
    > YourFancyPassword
  • Adjust systemd service after encrypting. Edit ExecStart command and add parameter --encrypted-hsm, like so:

    ExecStart=/bin/sh -c '/home/lightningd/lightning/lightningd/lightningd \
                           --conf=/data/lightningd/config \
                           --daemon \
                           --encrypted-hsm \
  • With this change CLN requires you to enter the password on every restart. To automate this follow the steps below to auto-unlock on startup.

Auto-Unlocking on Startup

  • As user “lightningd”, create a password file to auto-unlock on startup (equivalent to LND’s wallet password) and enter the choosen encryption password from the step above.

    $ nano ~/.lightningdpw
  • As “admin”, adjust permissions of the password file (read-only for the user).

    $ sudo chmod 0600 /home/lightningd/.lightningdpw
  • Change systemd service accordingly. Open systemd file.

    $ sudo nano /etc/systemd/system/lightningd.service
  • Edit ExecStart line like this:

    ExecStart=/bin/sh -c ' (cat /home/lightningd/.lightningdpw;echo;cat /home/lightningd/.lightningdpw) | \
                           /home/lightningd/lightning/lightningd/lightningd \
                           --conf=/data/lightningd/config \
                           --daemon \
                           --encrypted-hsm \
  • Reload systemd configuration and restart it:

    $ sudo systemctl daemon-reload
    $ sudo systemctl start lightningd.service

« Back: + Lightning