GlcoinCore/lightning-terminal
1
0
Fork 0
mirror of https://github.com/lightninglabs/lightning-terminal.git synced 2026-08-13 12:33:36 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

docs: add documentation for configuring the Let's Encrypt cert

Browse source
This commit is contained in:
jamaljsr 2020-10-01 10:57:15 -04:00
parent b15ad20853
commit 306ffdd2eb
2 changed files with 137 additions and 16 deletions
Download patch file Download diff file Expand all files Collapse all files

20
README.md
View file

@ -117,23 +117,11 @@ you store this password as an environment variable.
#### Optional
You can also configure the HTTP server to automatically install a free SSL certificate
provided by [LetsEncrypt](https://letsencrypt.org/). This is recommended if you plan to
provided by [Let's Encrypt](https://letsencrypt.org/). This is recommended if you plan to
access the website from a remote computer and do not want to deal with the browser warning
you about the self-signed certificate. You just need to specify the domain name you wish
to use, and make sure port 80 is open in your firewall. LetsEncrypt requires this
to verify that you own the domain name. LiT will listen on port 80 to handle the
verification requests.
On some linux-based platforms, you may need to run LiT with superuser privileges since
port 80 is a system port. You can permit the
[`CAP_NET_BIND_SERVICE`](https://www.man7.org/linux/man-pages/man7/capabilities.7.html)
capability using `setcap 'CAP_NET_BIND_SERVICE=+eip' /path/to/litd` to allow binding on
port 80 without needing to run the daemon as root.
> Note: LiT only serves content over **HTTPS**. If you do not use `letsencrypt`, LiT will
> use the self-signed certificate that is auto-generated by `lnd` to encrypt the
> browser-to-server communication. Web browsers will display a warning when using the
> self-signed certificate.
you about the self-signed certificate. View the
[Let's Encrypt Configuration](./doc/letsencrypt.md) doc for instructions on how to
configure this.
```text
Application Options:

133
doc/letsencrypt.md Normal file
View file

@ -0,0 +1,133 @@
# Terminal with a Let's Encrypt Certificate
You can configure the HTTPS server to automatically install a free SSL certificate
provided by [Let's Encrypt](https://letsencrypt.org/). This is recommended if you plan to
access the website from a remote computer and do not want to deal with the browser warning
you get about the self-signed certificate. Another benefit is you can use a memorable URL
to access the Terminal UI instead of an IP address.
> Note: LiT only serves content over **HTTPS**. If you do not use `letsencrypt`, LiT will
> use the self-signed certificate that is auto-generated by `lnd` (or LiT itself in
> `remote` mode) to encrypt the browser-to-server communication. Web browsers will display
> a warning when using the self-signed certificate.
## Domain Configuration
- Purchase a domain name to use. It can be a root domain such as `mydomain.com` or a
sub-domain such as `terminal.mydomain.com`.
- Update the domain's DNS to point the domain name to your node's public IP address, by
creating an `A` record. The specific steps to configure the `A` record varies depending
on the service you use to host your domain's DNS zone.
## Firewall Configuration
In order for Let's Encrypt to automatically install and renew your SSL certificate, it
will need to validate that you control the domain name. LiT uses the
[HTTP-01 challenge](https://letsencrypt.org/docs/challenge-types/#http-01-challenge)
method for this validation. You will need to open port `80` in your firewall or configure
port forwarding on your router so that `http` requests for your domain name can be
responded to by LiT.
On some linux-based platforms, you may need to run LiT with superuser privileges since
port `80` is a system port. You can permit the
[`CAP_NET_BIND_SERVICE`](https://www.man7.org/linux/man-pages/man7/capabilities.7.html)
capability using `setcap 'CAP_NET_BIND_SERVICE=+eip' /path/to/litd` to allow binding on
port `80` without needing to run the daemon as root.
If you are able to use port-forwarding on your router/firewall, you can specify a
different port (ex: `8080`) to listen for LetsEncrypt challenges using the
`letsencryptlisten` flag.
## LiT Configuration
There are a few `litd` flags that you need to set to make use of LetsEncrypt certificates.
These can be provided on the command line or via the `lit.conf` file.
| Flag | Required | Default Value | Description |
| ------------------- | -------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `letsencrypt` | Yes | `false` | Use Let's Encrypt to create a TLS certificate for the UI instead of using `lnd`'s TLS certificate. |
| `letsencrypthost` | Yes | `""` | The host name to create a Let's Encrypt certificate for. |
| `letsencryptdir` | No | `{lit-dir}/letsencrypt` | The directory where the Let's Encrypt library will store its key and certificate. |
| `letsencryptlisten` | No | `:80` | The `IP:PORT` on which LiT will listen for Let's Encrypt challenges. Let's Encrypt will always try to contact on port 80. Often non-root processes are not allowed to bind to ports lower than 1024. This configuration option allows a different port to be used, but must be used in combination with port forwarding from port 80. This configuration can also be used to specify another IP address to listen on, for example an IPv6 address. |
**Examples:**
Command Line:
`$ litd --letsencrypt --letsencrypthost=terminal.mydomain.com`
Configuration file (`litd.conf`):
```
--letsencrypt=true
--letsencrypthost=terminal.mydomain.com
```
## Example commands for interacting with the command line
When using a LetsEncrypt certificate, you will need to provide the correct `--rpcserver`
and `--tlscertpath` flags to the `lncli`, `loop` and `faraday` commands.
Let's go 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
letsencrypt=1
letsencrypthost=terminal.mydomain.com
lnd-mode=integrated
lnd.bitcoin.testnet=true
```
### Example `lncli` command
The `lncli` commands in the "integrated" mode are the same as if `lnd` was running
standalone.
```shell script
$ lncli --network=testnet getinfo
```
### Example `loop` command
Since `loopd` also runs on the same gRPC server as `lnd`, we have to specify the
**LetEncrypt** `host:port` and TLS certificate. But `loopd` verifies its own macaroon, so
we have to specify that one from the `.loop` directory.
```shell script
$ loop \
--rpcserver=terminal.mydomain.com:8443 \
--tlscertpath=~/.lit/letsencrypt/terminal.mydomain.com \
--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:
```shell script
alias lit-loop="loop --rpcserver=terminal.mydomain.com:8443 --tlscertpath=~/.lit/letsencrypt/terminal.mydomain.com --macaroonpath=~/.loop/testnet/loop.macaroon"
```
### Example `frcli` command
Faraday's command line tool follows the same pattern as loop. We also have to specify the
**LetEncrypt** `host:port` and TLS certificate but use `faraday`'s macaroon:
```shell script
$ frcli \
--rpcserver=terminal.mydomain.com:8443 \
--tlscertpath=~/.lit/letsencrypt/terminal.mydomain.com \
--macaroonpath=~/.faraday/testnet/faraday.macaroon \
audit
```
You can easily create an alias for this by adding the following line to your `~/.bashrc`
file:
```shell script
alias lit-frcli="frcli --rpcserver=terminal.mydomain.com:8443 --tlscertpath=~/.lit/letsencrypt/terminal.mydomain.com --macaroonpath=~/.faraday/testnet/faraday.macaroon"
```