aljaz/lightning
1
0
Fork 0
mirror of https://github.com/aljazceru/lightning.git synced 2025-12-22 08:34:20 +01:00
Code Issues Packages Projects Releases Wiki Activity

doc: Add guides and GitHub workflow for doc sync

Browse Source 
This PR:
- adds all the guides (in markdown format) that is published at https://docs.corelightning.org/docs
- adds a github workflow to sync any future changes made to files inside the guides folder
- does not include API reference (json-rpc commands). Those will be handled in a separate PR since they're used as manpages and will require a different github workflow

Note that the guides do not exactly map to their related files in doc/, since we reorganized the overall documentation structure on readme for better readability and developer experience. For example, doc/FUZZING.md and doc/HACKING.md#Testing are merged into testing.md in the new docs. As on the creation date of this PR, content from each of the legacy documents has been synced with the new docs. Until this PR gets merged, I will continue to push any updates made to the legacy documents into the new docs.

If this looks reasonable, I will add a separate PR to clean up the legacy documents from doc/ (or mark them deprecated) to avoid redundant upkeep and maintenance.

Changelog-None
This commit is contained in:
Adi Shankara
2023-04-22 17:21:44 +04:00
committed by Rusty Russell
parent 15e86f2bba
commit e83782f5de
44 changed files with 5823 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

25
doc/guides/Getting Started/advanced-setup/bitcoin-core.md Normal file
View File

@@ -0,0 +1,25 @@
---
title: "Bitcoin Core"
slug: "bitcoin-core"
hidden: false
createdAt: "2023-01-31T13:24:19.300Z"
updatedAt: "2023-02-21T13:30:53.906Z"
---
# Using a pruned Bitcoin Core node
Core Lightning requires JSON-RPC access to a fully synchronized `bitcoind` in order to synchronize with the Bitcoin network.
Access to ZeroMQ is not required and `bitcoind` does not need to be run with `txindex` like other implementations.
The lightning daemon will poll `bitcoind` for new blocks that it hasn't processed yet, thus synchronizing itself with `bitcoind`.
If `bitcoind` prunes a block that Core Lightning has not processed yet, e.g., Core Lightning was not running for a prolonged period, then `bitcoind` will not be able to serve the missing blocks, hence Core Lightning will not be able to synchronize anymore and will be stuck.
In order to avoid this situation you should be monitoring the gap between Core Lightning's blockheight using `[lightning-cli](ref:lightning-cli) getinfo` and `bitcoind`'s blockheight using `bitcoin-cli getblockchaininfo`. If the two blockheights drift apart it might be necessary to intervene.
# Connecting to Bitcoin Core remotely
You can use _trusted_ third-party plugins as bitcoin backends instead of using your own node.
- [sauron](https://github.com/lightningd/plugins/tree/master/sauron) is a bitcoin backend plugin relying on [Esplora](https://github.com/Blockstream/esplora).
- [trustedcoin](https://github.com/nbd-wtf/trustedcoin) is a plugin that uses block explorers (blockstream.info, mempool.space, blockchair.com and blockchain.info) as backends instead of your own bitcoin node.

220
doc/guides/Getting Started/advanced-setup/repro.md Normal file
View File

@@ -0,0 +1,220 @@
---
title: "Reproducible builds"
slug: "repro"
hidden: false
createdAt: "2023-01-25T10:37:03.476Z"
updatedAt: "2023-04-22T13:02:34.236Z"
---
Reproducible builds close the final gap in the lifecycle of open-source projects by allowing maintainers to verify and certify that a given binary was indeed produced by compiling an unmodified version of the publicly available source. In particular the maintainer certifies that the binary corresponds a) to the exact version of the and b) that no malicious changes have been applied before or after the compilation.
Core Lightning has provided a manifest of the binaries included in a release, along with signatures from the maintainers since version 0.6.2.
The steps involved in creating reproducible builds are:
- Creation of a known environment in which to build the source code
- Removal of variance during the compilation (randomness, timestamps, etc)
- Packaging of binaries
- Creation of a manifest (`SHA256SUMS` file containing the crytographic hashes of the binaries and packages)
- Signing of the manifest by maintainers and volunteers that have reproduced the files in the manifest starting from the source.
The bulk of these operations is handled by the [`repro-build.sh`](https://github.com/ElementsProject/lightning/blob/master/tools/repro-build.sh) script, but some manual operations are required to setup the build environment. Since a binary is built against platorm specific libraries we also need to replicate the steps once for each OS distribution and architecture, so the majority of this guide will describe how to set up those starting from a minimal trusted base. This minimal trusted base in most cases is the official installation medium from the OS provider.
Note: Since your signature certifies the integrity of the resulting binaries, please familiarize youself with both the [`repro-build.sh`](https://github.com/ElementsProject/lightning/blob/master/tools/repro-build.sh) script, as well as with the setup instructions for the build environments before signing anything.
# Build Environment Setup
The build environments are a set of docker images that are created directly from the installation mediums and repositories from the OS provider. The following sections describe how to create those images. Don't worry, you only have to create each image once and can then reuse the images for future builds.
## Base image creation
Depending on the distribution that we want to build for the instructions to create a base image can vary. In the following sections we discuss the specific instructions for each distribution, whereas the instructions are identical again once we have the base image.
### Debian / Ubuntu and derivative OSs
For operating systems derived from Debian we can use the `debootstrap` tool to build a minimal OS image, that can then be transformed into a docker image. The packages for the minimal OS image are directly downloaded from the installation repositories operated by the OS provider.
We cannot really use the `debian` and `ubuntu` images from the docker hub, mainly because it'd be yet another trusted third party, but it is also complicated by the fact that the images have some of the packages updated. The latter means that if we disable the `updates` and `security` repositories for `apt` we find ourselves in a situation where we can't install any additional packages (wrongly updated packages depending on the versions not available in
the non-updated repos).
The following table lists the codenames of distributions that we currently support:
- Ubuntu 18.06:
- Distribution Version: 18.04
- Codename: bionic
- Ubuntu 20.04:
- Distribution Version: 20.04
- Codename: focal
- Ubuntu 22.04:
- Distribution Version: 22.04
- Codename: jammy
Depending on your host OS release you might not have `debootstrap` manifests for versions newer than your host OS. Due to this we run the `debootstrap` commands in a container of the latest version itself:
```shell
for v in bionic focal jammy; do
echo "Building base image for $v"
sudo docker run --rm -v $(pwd):/build ubuntu:22.04 \
bash -c "apt-get update && apt-get install -y debootstrap && debootstrap $v /build/$v"
sudo tar -C $v -c . | sudo docker import - $v
done
```
Verify that the image corresponds to our expectation and is runnable:
```shell
sudo docker run bionic cat /etc/lsb-release
```
Which should result in the following output for `bionic`:
```shell
DISTRIB_ID=Ubuntu
DISTRIB_RELEASE=18.04
DISTRIB_CODENAME=bionic
DISTRIB_DESCRIPTION="Ubuntu 18.04 LTS"
```
## Builder image setup
Once we have the clean base image we need to customize it to be able to build Core Lightning. This includes disabling the update repositories, downloading the build dependencies and specifying the steps required to perform the build.
For this purpose we have a number of Dockerfiles in the [`contrib/reprobuild`](https://github.com/ElementsProject/lightning/tree/master/contrib/reprobuild) directory that have the specific instructions for each base image.
We can then build the builder image by calling `docker build` and passing it the `Dockerfile`:
```shell
sudo docker build -t cl-repro-bionic - < contrib/reprobuild/Dockerfile.bionic
sudo docker build -t cl-repro-focal - < contrib/reprobuild/Dockerfile.focal
sudo docker build -t cl-repro-jammy - < contrib/reprobuild/Dockerfile.jammy
```
Since we pass the `Dockerfile` through `stdin` the build command will not create a context, i.e., the current directory is not passed to `docker` and it'll be independent of the currently checked out version. This also means that you will be able to reuse the docker image for future builds, and don't have to repeat this dance every time. Verifying the `Dockerfile` therefore is
sufficient to ensure that the resulting `cl-repro-<codename>` image is reproducible.
The dockerfiles assume that the base image has the codename as its image name.
# Building using the builder image
Finally, after this rather lengthy setup we can perform the actual build. At this point we have a container image that has been prepared to build reproducibly. As you can see from the `Dockerfile` above we assume the source git repository gets mounted as `/repo` in the docker container. The container will clone the repository to an internal path, in order to keep the repository clean, build the artifacts there, and then copy them back to `/repo/release`.
We'll need the release directory available for this, so create it now if it doesn't exist:`mkdir release`, then we can simply execute the following command inside the git repository (remember to checkout the tag you are trying to build):
```bash
sudo docker run --rm -v $(pwd):/repo -ti cl-repro-bionic
sudo docker run --rm -v $(pwd):/repo -ti cl-repro-focal
sudo docker run --rm -v $(pwd):/repo -ti cl-repro-jammy
```
The last few lines of output also contain the `sha256sum` hashes of all artifacts, so if you're just verifying the build those are the lines that are of interest to you:
```shell
ee83cf4948228ab1f644dbd9d28541fd8ef7c453a3fec90462b08371a8686df8 /repo/release/clightning-v0.9.0rc1-Ubuntu-18.04.tar.xz
94bd77f400c332ac7571532c9f85b141a266941057e8fe1bfa04f054918d8c33 /repo/release/clightning-v0.9.0rc1.zip
```
Repeat this step for each distribution and each architecture you wish to sign. Once all the binaries are in the `release/` subdirectory we can sign the hashes:
# (Co-)Signing the release manifest
The release captain is in charge of creating the manifest, whereas contributors and interested bystanders may contribute their signatures to further increase trust in the binaries.
The release captain creates the manifest as follows:
```shell
cd release/
sha256sum *v0.9.0* > SHA256SUMS
gpg -sb --armor SHA256SUMS
```
Co-maintainers and contributors wishing to add their own signature verify that the `SHA256SUMS` and `SHA256SUMS.asc` files created by the release captain matches their binaries before also signing the manifest:
```shell
cd release/
gpg --verify SHA256SUMS.asc
sha256sum -c SHA256SUMS
cat SHA256SUMS | gpg -sb --armor > SHA256SUMS.new
```
Then send the resulting `SHA256SUMS.new` file to the release captain so it can be merged with the other signatures into `SHASUMS.asc`.
# Verifying a reproducible build
You can verify the reproducible build in two ways:
- Repeating the entire reproducible build, making sure from scratch that the binaries match. Just follow the instructions above for this.
- Verifying that the downloaded binaries match match the hashes in `SHA256SUMS` and that the signatures in `SHA256SUMS.asc` are valid.
Assuming you have downloaded the binaries, the manifest and the signatures into the same directory, you can verify the signatures with the following:
```shell
gpg --verify SHA256SUMS.asc
```
And you should see a list of messages like the following:
```shell
gpg: assuming signed data in 'SHA256SUMS'
gpg: Signature made Fr 08 Mai 2020 07:46:38 CEST
gpg: using RSA key 15EE8D6CAB0E7F0CF999BFCBD9200E6CD1ADB8F1
gpg: Good signature from "Rusty Russell <rusty@rustcorp.com.au>" [full]
gpg: Signature made Fr 08 Mai 2020 12:30:10 CEST
gpg: using RSA key B7C4BE81184FC203D52C35C51416D83DC4F0E86D
gpg: Good signature from "Christian Decker <decker.christian@gmail.com>" [ultimate]
gpg: Signature made Fr 08 Mai 2020 21:35:28 CEST
gpg: using RSA key 30DE693AE0DE9E37B3E7EB6BBFF0F67810C1EED1
gpg: Good signature from "Lisa Neigut <niftynei@gmail.com>" [full]
```
If there are any issues `gpg` will print `Bad signature`, it might be because the signatures in `SHA256SUMS.asc` do not match the `SHA256SUMS` file, and could be the result of a filename change. Do not continue using the binaries, and contact the maintainers, if this is not the case, a failure here means that the verification failed.
Next we verify that the binaries match the ones in the manifest:
```shell
sha256sum -c SHA256SUMS
```
Producing output similar to the following:
```shell
sha256sum: clightning-v0.9.0-Fedora-28-amd64.tar.gz: No such file or directory
clightning-v0.9.0-Fedora-28-amd64.tar.gz: FAILED open or read
clightning-v0.9.0-Ubuntu-18.04.tar.xz: OK
clightning-v0.9.0.zip: OK
sha256sum: WARNING: 1 listed file could not be read
```
Notice that the two files we downloaded are marked as `OK`, but we're missing one file. If you didn't download that file this is to be expected, and is nothing to worry about. A failure to verify the hash would give a warning like the following:
```shell
sha256sum: WARNING: 1 computed checksum did NOT match
```
If both the signature verification and the manifest checksum verification
succeeded, then you have just successfully verified a reproducible build and,
assuming you trust the maintainers, are good to install and use the
binaries. Congratulations! 🎉🥳

399
doc/guides/Getting Started/advanced-setup/tor.md Normal file
View File

@@ -0,0 +1,399 @@
---
title: "Using Tor"
slug: "tor"
hidden: false
createdAt: "2023-01-25T10:55:50.059Z"
updatedAt: "2023-02-21T13:30:33.294Z"
---
To use any Tor features with Core Lightning you must have Tor installed and running.
Note that we only support Tor v3: you can check your installed Tor version with `tor --version` or `sudo tor --version`
If Tor is not installed you can install it on Debian based Linux systems (Ubuntu, Debian, etc) with the following command:
```shell
sudo apt install tor
```
then `/etc/init.d/tor start` or `sudo systemctl enable --now tor` depending on your system configuration.
Most default setting should be sufficient.
To keep a safe configuration for minimal harassment (See [Tor FAQ](https://www.torproject.org/docs/faq.html.en#WhatIsTor)) just check that this line is present in the Tor config file `/etc/tor/torrc`:
`ExitPolicy reject *:* # no exits allowed`
This does not affect Core Lightning connect, listen, etc. It will only prevent your node from becoming a Tor exit node. Only enable this if you are sure about the implications.
If you don't want to create .onion addresses this should be enough.
There are several ways by which a Core Lightning node can accept or make connections over Tor. The node can be reached over Tor by connecting to its .onion address.
To provide the node with a .onion address you can:
- create a **non-persistent** address with an auto service or
- create a **persistent** address with a hidden service.
### Quick Start On Linux
It is easy to create a single persistent Tor address and not announce a public IP. This is ideal for most setups where you have an ISP-provided router connecting your Internet to your local network and computer, as it does not require a stable public IP from your ISP (which might not give one to you for free), nor port forwarding (which can be hard to set up for random cheap router models). Tor provides NAT-traversal for free, so even if you or your ISP has a complex
network between you and the Internet, as long as you can use Tor you can be connected to.
> 📘
>
> Core Lightning also support IPv4/6 address discovery behind NAT routers.
For this to work you need to forward the default TCP port 9735 to your node. In this case you don't need TOR to punch through your firewall. IP discovery is only active if no other addresses are announced. This usually has the benefit of quicker and more stable connections but does not
offer additional privacy.
On most Linux distributions, making a standard installation of `tor` will automatically set it up to have a SOCKS5 proxy at port 9050. As well, you have to set up the Tor Control Port. On most Linux distributions there will be commented-out settings below in the
`/etc/tor/torrc`:
```shell
ControlPort 9051
CookieAuthentication 1
CookieAuthFile /var/lib/tor/control_auth_cookie
CookieAuthFileGroupReadable 1
```
Uncomment those in, then restart `tor` (usually `systemctl restart tor` or
`sudo systemctl restart tor` on most SystemD-based systems, including recent Debian and Ubuntu, or just restart the entire computer if you cannot figure it out).
On some systems (such as Arch Linux), you may also need to add the following setting:
```shell
DataDirectoryGroupReadable 1
```
You also need to make your user a member of the Tor group.
"Your user" here is whatever user will run `lightningd`. On Debian-derived systems, the Tor group will most likely be `debian-tor`. You can try listing all groups with the below command, and check for a `debian-tor` or `tor` groupname.
```shell
getent group | cut -d: -f1 | sort
```
Alternately, you could check the group of the cookie file directly.
Usually, on most Linux systems, that would be `/run/tor/control.authcookie`:
```shell
stat -c '%G' /run/tor/control.authcookie
```
Once you have determined the `${TORGROUP}` and selected the
`${LIGHTNINGUSER}` that will run `lightningd`, run this as root:
```shell
usermod -a -G ${TORGROUP} ${LIGHTNINGUSER}
```
Then restart the computer (logging out and logging in again should also work).
Confirm that `${LIGHTNINGUSER}` is in `${TORGROUP}` by running the `groups` command as `${LIGHTNINGUSER}` and checking `${TORGROUP}` is listed.
If the `/run/tor/control.authcookie` exists in your system, then log in as the user that will run `lightningd` and check this command:
```shell
cat /run/tor/control.authcookie > /dev/null
```
If the above prints nothing and returns, then Core Lightning "should" work with your Tor.
If it prints an error, some configuration problem will likely prevent Core Lightning from working with your Tor.
Then make sure these are in your `${LIGHTNING_DIR}/config` or other Core Lightning configuration (or prepend `--` to each of them and add them to your `lightningd` invocation
command line):
```shell
proxy=127.0.0.1:9050
bind-addr=127.0.0.1:9735
addr=statictor:127.0.0.1:9051
always-use-proxy=true
```
1. `proxy` informs Core Lightning that you have a SOCKS5 proxy at port 9050.
Core Lightning will assume that this is a Tor proxy, port 9050 is the default in most Linux distributions; you can double-check `/etc/tor/torrc` for a `SocksPort` entry to confirm the port number.
2. `bind-addr` informs Core Lightning to bind itself to port 9735.
This is needed for the subsequent `statictor` to work.
9735 is the normal Lightning Network port, so this setting may already be present.
If you add a second `bind-addr=...` you may get errors, so choose this new one or keep the old one, but don't keep both.
This has to appear before any `statictor:` setting.
3. `addr=statictor:` informs Core Lightning that you want to create a persistent hidden service that is based on your node private key.
This informs Core Lightning as well that the Tor Control Port is 9051. You can also use `bind-addr=statictor:` instead to not announce the persistent hidden service, but if anyone wants to make a channel with you, you either have to connect to them, or you have to reveal your address to them explicitly (i.e. autopilots and the like will likely never connect to you).
4. `always-use-proxy` informs Core Lightning to always use Tor even when connecting to nodes with public IPs. You can set this to `false` or remove it, if you are not privacy-conscious **and** find Tor is too slow for you.
### Tor Browser and Orbot
It is possible to not install Tor on your computer, and rely on just Tor Browser.
Tor Browser will run a built-in Tor instance, but with the proxy at port 9150 and the control port at 9151 (the normal Tor has, by default, the proxy at port 9050 and the control
port at 9051). The mobile Orbot uses the same defaults as Tor Browser (9150 and 9151).
You can then use these settings for Core Lightning:
```shell
proxy=127.0.0.1:9150
bind-addr=127.0.0.1:9735
addr=statictor:127.0.0.1:9151
always-use-proxy=true
```
You will have to run Core Lightning after launching Tor Browser or Orbot, and keep Tor Browser or Orbot open as long as Core Lightning is running, but this is a setup which allows others to connect and fund channels to you, anywhere (no port forwarding! works wherever Tor works!), and you do not have to do anything more complicated than download and install Tor Browser.
This may be useful for operating system distributions that do not have Tor in their repositories, assuming we can ever get Core Lightning running on those.
### Detailed Discussion
#### Three Ways to Create .onion Addresses for Core Lightning
1. You can configure Tor to create an onion address for you, and tell Core Lightning to use that address
2. You can have Core Lightning tell Tor to create a new onion address every time
3. You can configure Core Lightning to tell Tor to create the same onion address every time it starts up
#### Tor-Created .onion Address
Having Tor create an onion address lets you run other services (e.g. a web server) at that same address, and you just tell that address to Core Lightning and it doesn't have to talk to the Tor server at all.
Put the following in your `/etc/tor/torrc` file:
```shell
HiddenServiceDir /var/lib/tor/lightningd-service_v3/
HiddenServiceVersion 3
HiddenServicePort 1234 127.0.0.1:9735
```
The hidden lightning service will be reachable at port 1234 (global port) of the .onion address, which will be created at the restart of the Tor service. Both types of addresses can coexist on the same node.
Save the file and restart the Tor service. In linux:
`/etc/init.d/tor restart` or `sudo systemctl restart tor` depending on the configuration of your system.
You will find the newly created address (myaddress.onion) with:
```shell
sudo cat /var/lib/tor/lightningd-service_v3/hostname
```
Now you need to tell Core Lightning to advertize that onion hostname and port, by placing `announce-addr=myaddress.onion` in your lightning config.
#### Letting Core Lightning Control Tor
To have Core Lightning control your Tor addresses, you have to tell Tor to accept control commands from Core Lightning, either by using a cookie, or a password.
##### Service authenticated by cookie
This tells Tor to create a cookie file each time: lightningd will have to be in the same group as tor (e.g. debian-tor): you can look at `/run/tor/control.authcookie` to check the group name.
Add the following lines in the `/etc/tor/torrc` file:
```shell
ControlPort 9051
CookieAuthentication 1
CookieAuthFileGroupReadable 1
```
Save the file and restart the Tor service.
##### Service authenticated by password
This tells Tor to allow password access: you also need to tell lightningd what the password is.
Create a hash of your password with
```shell
tor --hash-password yourpassword
```
This returns a line like
`16:533E3963988E038560A8C4EE6BBEE8DB106B38F9C8A7F81FE38D2A3B1F`
Put these lines in the `/etc/tor/torrc` file:
```shell
ControlPort 9051
HashedControlPassword 16:533E3963988E038560A8C4EE6BBEE8DB106B38F9C8A7F81FE38D2A3B1F
```
Save the file and restart the Tor service.
Put `tor-service-password=yourpassword` (not the hash) in your lightning configuration file.
##### Core Lightning Creating Persistent Hidden Addresses
This is usually better than transient addresses, as nodes won't have to wait for gossip propagation to find out your new address each time you restart.
Once you've configured access to Tor as described above, you need to add _two_ lines in your lightningd config file:
1. A local address which lightningd can tell Tor to connect to when connections come in, e.g. `bind-addr=127.0.0.1:9735`.
2. After that, a `addr=statictor:127.0.0.1:9051` to tell Core Lightning to set up and announce a Tor onion address (and tell Tor to send connections to our real address, above).
You can use `bind-addr` if you want to set up the onion address and not announce it to the world for some reason.
You may add more `addr` lines if you want to advertise other addresses.
There is an older method, called "autotor" instead of "statictor" which creates a different Tor address on each restart, which is usually not very helpful; you need to use lightning-cli getinfo\` to see what address it is currently using, and other peers need to wait for fresh gossip messages if you announce it, before they can connect.
### What do we support
| Case # | IP Number | Hidden service | Incoming / Outgoing Tor |
| ------ | ------------- | ----------------------- | ----------------------- |
| 1 | Public | NO | Outgoing |
| 2 | Public | FIXED BY TOR | Incoming [1] |
| 3 | Public | FIXED BY CORE LIGHTNING | Incoming [1] |
| 4 | Not Announced | FIXED BY TOR | Incoming [1] |
| 5 | Not Announced | FIXED BY CORE LIGHTNING | Incoming [1] |
> 📘
>
> In all the "Incoming" use case, the node can also make "Outgoing" Tor
> connections (connect to a .onion address) by adding the `proxy=127.0.0.1:9050` option.
#### Case #1: Public IP address and no Tor address, but can connect to Tor addresses
Without a .onion address, the node won't be reachable through Tor by other nodes but it will always be able to `connect` to a Tor enabled node (outbound connections), passing the `connect` request through the Tor service socks5 proxy. When the Tor service starts it creates a socks5 proxy which is by default at the address 127.0.0.1:9050.
If the node is started with the option `proxy=127.0.0.1:9050` the node will be always able to connect to nodes with .onion address through the socks5 proxy.
**You can always add this option, also in the other use cases, to add outgoing
Tor capabilities.**
If you want to `connect` to nodes ONLY via the Tor proxy, you have to add the `always-use-proxy=true` option (though if you only advertize Tor addresses, we also assume you want to always use the proxy).
You can announce your public IP address through the usual method: if your node is in an internal network:
```shell
bind-addr=internalIPAddress:port
announce-addr=externalIpAddress
```
or if it has a public IP address:
```shell
addr=externalIpAddress
```
> 📘
>
> If you are unsure which of the two is suitable for you, find your internal and external address and see if they match.
In linux:
Discover your external IP address with: `curl ipinfo.io/ip` and your internal IP Address with: `ip route get 1 | awk '{print $NF;exit}'`.
If they match you can use the `--addr` command line option.
#### Case #2: Public IP address, and a fixed Tor address in torrc
Other nodes can connect to you entirely over Tor, and the Tor address doesn't change every time you restart.
You simply tell Core Lightning to advertize both addresses (you can use `sudo cat /var/lib/tor/lightningd-service_v3/hostname` to get your Tor-assigned onion address).
If you have an internal IP address:
```shell
bind-addr=yourInternalIPAddress:port
announce-addr=yourexternalIPAddress:port
announce-addr=your.onionAddress:port
```
Or an external address:
```shell
addr=yourIPAddress:port
announce-addr=your.onionAddress:port
```
#### Case #3: Public IP address, and a fixed Tor address set by Core Lightning
Other nodes can connect to you entirely over Tor, and the Tor address doesn't change every time you restart.
See "Letting Core Lightning Control Tor" for how to get Core Lightning talking to Tor.
If you have an internal IP address:
```shell
bind-addr=yourInternalIPAddress:port
announce-addr=yourexternalIPAddress:port
addr=statictor:127.0.0.1:9051
```
Or an external address:
```shell
addr=yourIPAddress:port
addr=statictor:127.0.0.1:9051
```
#### Case #4: Unannounced IP address, and a fixed Tor address in torrc
Other nodes can only connect to you over Tor.
You simply tell Core Lightning to advertize the Tor address (you can use `sudo cat /var/lib/tor/lightningd-service_v3/hostname` to get your Tor-assigned onion address).
```
announce-addr=your.onionAddress:port
proxy=127.0.0.1:9050
always-use-proxy=true
```
#### Case #4: Unannounced IP address, and a fixed Tor address set by Core Lightning
Other nodes can only connect to you over Tor.
See "Letting Core Lightning Control Tor" for how to get Core Lightning
talking to Tor.
```
addr=statictor:127.0.0.1:9051
proxy=127.0.0.1:9050
always-use-proxy=true
```
## References
- [Configuring your node](doc:configuration) section (or [`lightningd-config`](ref:lightningd-config) manual page) covers the various address cases in detail.
- [The Tor project](https://www.torproject.org/)
- [Tor FAQ](https://www.torproject.org/docs/faq.html.en#WhatIsTor)
- [Tor Hidden Service](https://www.torproject.org/docs/onion-services.html.en)
- [.onion addresses version 3](https://blog.torproject.org/we-want-you-test-next-gen-onion-services)