Skip to content

Commit 306ffdd

Browse files
jamaljsrjamaljsr
committed
docs: add documentation for configuring the Let's Encrypt cert
1 parent b15ad20 commit 306ffdd

File tree

2 files changed

+137
-16
lines changed

2 files changed

+137
-16
lines changed

‎README.md

Lines changed: 4 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -117,23 +117,11 @@ you store this password as an environment variable.
117117
#### Optional
118118

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

138126
```text
139127
Application Options:

‎doc/letsencrypt.md

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
# Terminal with a Let's Encrypt Certificate
2+
3+
You can configure the HTTPS server to automatically install a free SSL certificate
4+
provided by [Let's Encrypt](https://letsencrypt.org/). This is recommended if you plan to
5+
access the website from a remote computer and do not want to deal with the browser warning
6+
you get about the self-signed certificate. Another benefit is you can use a memorable URL
7+
to access the Terminal UI instead of an IP address.
8+
9+
> Note: LiT only serves content over **HTTPS**. If you do not use `letsencrypt`, LiT will
10+
> use the self-signed certificate that is auto-generated by `lnd` (or LiT itself in
11+
> `remote` mode) to encrypt the browser-to-server communication. Web browsers will display
12+
> a warning when using the self-signed certificate.
13+
14+
## Domain Configuration
15+
16+
- Purchase a domain name to use. It can be a root domain such as `mydomain.com` or a
17+
sub-domain such as `terminal.mydomain.com`.
18+
- Update the domain's DNS to point the domain name to your node's public IP address, by
19+
creating an `A` record. The specific steps to configure the `A` record varies depending
20+
on the service you use to host your domain's DNS zone.
21+
22+
## Firewall Configuration
23+
24+
In order for Let's Encrypt to automatically install and renew your SSL certificate, it
25+
will need to validate that you control the domain name. LiT uses the
26+
[HTTP-01 challenge](https://letsencrypt.org/docs/challenge-types/#http-01-challenge)
27+
method for this validation. You will need to open port `80` in your firewall or configure
28+
port forwarding on your router so that `http` requests for your domain name can be
29+
responded to by LiT.
30+
31+
On some linux-based platforms, you may need to run LiT with superuser privileges since
32+
port `80` is a system port. You can permit the
33+
[`CAP_NET_BIND_SERVICE`](https://www.man7.org/linux/man-pages/man7/capabilities.7.html)
34+
capability using `setcap 'CAP_NET_BIND_SERVICE=+eip' /path/to/litd` to allow binding on
35+
port `80` without needing to run the daemon as root.
36+
37+
If you are able to use port-forwarding on your router/firewall, you can specify a
38+
different port (ex: `8080`) to listen for LetsEncrypt challenges using the
39+
`letsencryptlisten` flag.
40+
41+
## LiT Configuration
42+
43+
There are a few `litd` flags that you need to set to make use of LetsEncrypt certificates.
44+
These can be provided on the command line or via the `lit.conf` file.
45+
46+
| Flag | Required | Default Value | Description |
47+
| ------------------- | -------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
48+
| `letsencrypt` | Yes | `false` | Use Let's Encrypt to create a TLS certificate for the UI instead of using `lnd`'s TLS certificate. |
49+
| `letsencrypthost` | Yes | `""` | The host name to create a Let's Encrypt certificate for. |
50+
| `letsencryptdir` | No | `{lit-dir}/letsencrypt` | The directory where the Let's Encrypt library will store its key and certificate. |
51+
| `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. |
52+
53+
**Examples:**
54+
55+
Command Line:
56+
57+
`$ litd --letsencrypt --letsencrypthost=terminal.mydomain.com`
58+
59+
Configuration file (`litd.conf`):
60+
61+
```
62+
--letsencrypt=true
63+
--letsencrypthost=terminal.mydomain.com
64+
65+
```
66+
67+
## Example commands for interacting with the command line
68+
69+
When using a LetsEncrypt certificate, you will need to provide the correct `--rpcserver`
70+
and `--tlscertpath` flags to the `lncli`, `loop` and `faraday` commands.
71+
72+
Let's go through an example for each of the command line tools and will explain the
73+
reasons for the extra flags. The examples assume that LiT is started with the following
74+
configuration (only relevant parts shown here):
75+
76+
```
77+
httpslisten=0.0.0.0:8443
78+
letsencrypt=1
79+
letsencrypthost=terminal.mydomain.com
80+
lnd-mode=integrated
81+
82+
lnd.bitcoin.testnet=true
83+
```
84+
85+
### Example `lncli` command
86+
87+
The `lncli` commands in the "integrated" mode are the same as if `lnd` was running
88+
standalone.
89+
90+
```shell script
91+
$ lncli --network=testnet getinfo
92+
```
93+
94+
### Example `loop` command
95+
96+
Since `loopd` also runs on the same gRPC server as `lnd`, we have to specify the
97+
**LetEncrypt** `host:port` and TLS certificate. But `loopd` verifies its own macaroon, so
98+
we have to specify that one from the `.loop` directory.
99+
100+
```shell script
101+
$ loop \
102+
--rpcserver=terminal.mydomain.com:8443 \
103+
--tlscertpath=~/.lit/letsencrypt/terminal.mydomain.com \
104+
--macaroonpath=~/.loop/testnet/loop.macaroon \
105+
quote out 500000
106+
```
107+
108+
You can easily create an alias for this by adding the following line to your `~/.bashrc`
109+
file:
110+
111+
```shell script
112+
alias lit-loop="loop --rpcserver=terminal.mydomain.com:8443 --tlscertpath=~/.lit/letsencrypt/terminal.mydomain.com --macaroonpath=~/.loop/testnet/loop.macaroon"
113+
```
114+
115+
### Example `frcli` command
116+
117+
Faraday's command line tool follows the same pattern as loop. We also have to specify the
118+
**LetEncrypt** `host:port` and TLS certificate but use `faraday`'s macaroon:
119+
120+
```shell script
121+
$ frcli \
122+
--rpcserver=terminal.mydomain.com:8443 \
123+
--tlscertpath=~/.lit/letsencrypt/terminal.mydomain.com \
124+
--macaroonpath=~/.faraday/testnet/faraday.macaroon \
125+
audit
126+
```
127+
128+
You can easily create an alias for this by adding the following line to your `~/.bashrc`
129+
file:
130+
131+
```shell script
132+
alias lit-frcli="frcli --rpcserver=terminal.mydomain.com:8443 --tlscertpath=~/.lit/letsencrypt/terminal.mydomain.com --macaroonpath=~/.faraday/testnet/faraday.macaroon"
133+
```

0 commit comments

Comments
 (0)