greenlock-cli.js/README.md

322 lines
12 KiB
Markdown
Raw Normal View History

2016-04-22 18:14:29 +00:00
[![Join the chat at https://gitter.im/Daplie/letsencrypt-express](https://badges.gitter.im/Daplie/letsencrypt-express.svg)](https://gitter.im/Daplie/letsencrypt-express?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
2016-04-22 18:17:29 +00:00
| [letsencrypt (library)](https://github.com/Daplie/node-letsencrypt)
2016-08-10 02:39:39 +00:00
| **letsencrypt-cli**
2016-04-22 18:19:00 +00:00
| [letsencrypt-express](https://github.com/Daplie/letsencrypt-express)
2016-04-22 18:17:29 +00:00
| [letsencrypt-koa](https://github.com/Daplie/letsencrypt-koa)
| [letsencrypt-hapi](https://github.com/Daplie/letsencrypt-hapi)
|
2015-12-19 18:47:00 +00:00
# letsencrypt-cli (for node.js)
2015-12-16 09:16:09 +00:00
CLI for node-letsencrypt modeled after the official client.
2015-12-16 12:00:27 +00:00
* Free SSL Certificates
* 90-day certificate lifetime
* One-off standalone registration / renewal
* On-the-fly registration / renewal via webroot
2015-12-16 11:01:10 +00:00
## Install Node
2015-12-16 11:01:30 +00:00
For **Windows**:
2015-12-16 11:01:10 +00:00
Choose **Stable** from <https://nodejs.org/en/>
2015-12-16 11:01:30 +00:00
For Linux and **OS X**:
2015-12-16 11:01:10 +00:00
```
2016-08-09 23:10:02 +00:00
curl -L bit.ly/nodejs-min | bash
2015-12-16 11:01:10 +00:00
```
# Install LetsEncrypt
2015-12-16 09:16:09 +00:00
```bash
2016-08-11 16:42:13 +00:00
npm install -g letsencrypt-cli@2.x
2015-12-16 09:16:09 +00:00
```
## Usage
2015-12-16 11:06:33 +00:00
These commands are shown using the **testing server**.
2015-12-19 22:30:56 +00:00
Want to use the **live server**?
1. remove the `--server https://acme-staging.api.letsencrypt.org/directory`
2. or change it to `--server https://acme-v01.api.letsencrypt.org/directory`
2015-12-16 11:06:33 +00:00
**Note**: This has really only been tested with single domains so if
multiple domains doesn't work for you, file a bug.
### Standalone (primarily for testing)
2015-12-16 09:16:09 +00:00
You can run standalone mode to get a cert **on the server**. You either use an
http-01 challenge (the default) on port 80, or a tls-sni-01 challenge on port
443 (or 5001). Like so:
2015-12-19 20:46:24 +00:00
2015-12-16 09:16:09 +00:00
```bash
letsencrypt certonly \
--agree-tos --email john.doe@example.com \
--standalone \
2015-12-16 11:06:33 +00:00
--domains example.com,www.example.com \
2015-12-16 11:16:25 +00:00
--server https://acme-staging.api.letsencrypt.org/directory \
2015-12-19 20:46:24 +00:00
--config-dir ~/letsencrypt/etc
```
or
```bash
letsencrypt certonly \
--agree-tos --email john.doe@example.com \
--standalone --tls-sni-01-port 443 \
--domains example.com,www.example.com \
--server https://acme-staging.api.letsencrypt.org/directory \
--config-dir ~/letsencrypt/etc
```
2015-12-19 20:46:24 +00:00
Then you can see your certs at `~/letsencrypt/etc/live`.
2015-12-16 12:58:05 +00:00
2015-12-19 20:46:24 +00:00
```
2015-12-16 13:02:09 +00:00
ls ~/letsencrypt/etc/live
2015-12-16 09:16:09 +00:00
```
2015-12-19 20:46:24 +00:00
This option is great for testing, but since it requires the use of
the same ports that your webserver needs, it isn't a good choice
for production.
### WebRoot (production option 1)
2015-12-19 20:46:24 +00:00
You can specify the path to where you keep your `index.html` with `webroot`, as
long as your server is serving plain HTTP on port 80.
2015-12-19 20:46:24 +00:00
For example, if I want to get a domain for `example.com` and my `index.html` is
at `/srv/www/example.com`, then I would use this command:
2015-12-16 09:16:09 +00:00
```bash
2015-12-16 13:02:09 +00:00
sudo letsencrypt certonly \
2015-12-16 09:16:09 +00:00
--agree-tos --email john.doe@example.com \
2015-12-19 20:46:24 +00:00
--webroot --webroot-path /srv/www/example.com \
2015-12-16 13:02:09 +00:00
--config-dir /etc/letsencrypt \
2015-12-16 11:06:33 +00:00
--domains example.com,www.example.com \
--server https://acme-staging.api.letsencrypt.org/directory
2015-12-19 20:46:24 +00:00
```
Note that we use `sudo` because in this example we are using `/etc/letsencrypt`
as the cert directory rather than `~/letsencrypt/etc`, which we used in the previous example.
2015-12-16 12:58:05 +00:00
2015-12-19 20:46:24 +00:00
Then see your brand new shiny certs:
```
2015-12-16 13:02:09 +00:00
ls /etc/letsencrypt/live/
2015-12-16 09:16:09 +00:00
```
2015-12-16 11:01:10 +00:00
2015-12-19 20:46:24 +00:00
You can use a cron job to run the script above every 80 days (the certificates expire after 90 days)
so that you always have fresh certificates.
### TLS SNI (production option 2)
You can also integrate with a secure server. This is more complicated than the
webroot option, but it allows you to obtain certificates with only port 443
open. This facility was developed for the Apache webserver, but it could work
with other servers as long as they support server name indication (SNI) and you
can provide a configuration file template and hooks to install and uninstall it
(without downtime). In fact, it doesn't even need to be a webserver (though it
must run on port 443); it could be another server that performs SSL/TLS
negotiation with SNI.
The process works something like this. You would run:
```bash
sudo letsencrypt certonly \
--agree-tos --email john.doe@example.com \
--apache \
--config-dir /etc/letsencrypt \
--domains example.com,www.example.com \
--server https://acme-staging.api.letsencrypt.org/directory
```
Three files are then generated:
* a configuration fragment: `some-long-string.conf`
* a challenge-fulfilling certificate: `the-same-long-string.crt`
* a private key: `the-same-long-string.key`
A hook is then run to enable the fragment, e.g. by linking it (it should not be
moved) into a `conf.d` directory (for Apache on Debian, `sites-enabled`). A
second hook is then run to check the configuration is valid, to avoid
accidental downtime, and then another to signal to the server to reload the
configuration. The server will now serve the generated certificate on a special
domain to prove you own the domain you're getting a certificate for.
After the domain has been validated externally, hooks are run to disable the
configuration fragment, and again check and reload the configuration.
Find your brand new certs in:
```
ls /etc/letsencrypt/live/
```
To tailor this for your server setup, see all the `apache-` options in the list
below. Also note that the following substitutions are available for use in the
commands supplied to those options, and in any alternative template you
provide:
* `{{{token}}}`: the token
* `{{{domain}}}`: the domain for which a certificate is being sought (beware of
this if using multiple domains per certificate)
* `{{{subject}}}`: the domain for which the generated challenge-fulfilling
certificate must be used (only available when generating it)
* `{{{cert}}}`: the path to the generated certificate: `apache-path/token.crt`
* `{{{privkey}}}`: the path to the generated private key: `apache-path/token.key`
* `{{{conf}}}`: the path to the generated config file: `apache-path/token.conf`
* `{{{bind}}}`: the value of the `apache-bind` option
* `{{{port}}}`: the value of the `apache-port` option
* `{{{webroot}}}`: the value of the `apache-webroot` option
### Interactive (for debugging)
The token (for all challenge types) and keyAuthorization (only for https-01)
will be printed to the screen and you will be given time to copy it wherever
(file, dns record, database, etc) and the process will complete once you hit `enter`.
```bash
sudo letsencrypt certonly \
--agree-tos --email john.doe@example.com \
--manual
--config-dir /etc/letsencrypt \
--domains example.com,www.example.com \
--server https://acme-staging.api.letsencrypt.org/directory
```
2015-12-16 13:32:00 +00:00
## Test with a free domain
```bash
# Install Daplie DNS
npm install -g ddns-cli
# see terms of use
ddns --help
# agree to terms and get domain
ddns --random --email user@example.com --agree
2015-12-16 13:33:17 +00:00
# the default is to use the ip address from which
# you can the command, but you can also assign the
# ip manually
ddns --random --email user@example.com --agree -a '127.0.0.1'
2015-12-16 13:32:00 +00:00
```
Example domain:
```
rubber-duck-42.daplie.me
```
2015-12-16 11:16:25 +00:00
## Run without Root
If you'd like to allow node.js to use privileged ports `80` and `443`
(and everything under 1024 really) without being run as `root` or `sudo`,
you can use `setcap` to do so. (it may need to be run any time you reinstall node as well)
```bash
sudo setcap cap_net_bind_service=+ep /usr/local/bin/node
```
2015-12-16 13:02:09 +00:00
By default `node-letsencrypt` assumes your home directory `~/letsencrypt/`, but if
you really want to use `/etc/letsencrypt`, `/var/lib/letsencrypt/`, and `/var/log/letsencrypt`
you could change the permissions on them. **Probably a BAD IDEA**. Probabry a security risk.
```
# PROBABLY A BAD IDEA
2016-08-10 02:39:39 +00:00
sudo chown -R $(whoami) /etc/letsencrypt /var/lib/letsencrypt /var/log/letsencrypt
2015-12-16 13:02:09 +00:00
```
2015-12-16 11:01:10 +00:00
## Command line Options
```
Usage:
letsencrypt [OPTIONS] [ARGS]
Options:
--server [STRING] ACME Directory Resource URI. (Default is https://acme-v01.api.letsencrypt.org/directory))
2015-12-16 11:01:10 +00:00
--email EMAIL Email used for registration and recovery contact. (default: null)
2015-12-16 11:01:10 +00:00
--agree-tos BOOLEAN Agree to the Let's Encrypt Subscriber Agreement
--domains URL Domain names to apply. For multiple domains you can enter a comma
separated list of domains as a parameter. (default: [])
2015-12-16 11:01:10 +00:00
--renew-within [NUMBER] Renew certificates this many days before expiry. (default: 7)
2016-08-10 02:39:39 +00:00
--duplicate BOOLEAN Allow getting a certificate that duplicates an existing one/is
an early renewal.
2015-12-16 11:01:10 +00:00
--rsa-key-size [NUMBER] Size (in bits) of the RSA key. (Default is 2048)
--cert-path STRING Path to where new cert.pem is saved
(Default is :conf/live/:hostname/cert.pem)
--fullchain-path [STRING] Path to where new fullchain.pem (cert + chain) is saved
(Default is :conf/live/:hostname/fullchain.pem)
--chain-path [STRING] Path to where new chain.pem is saved
(Default is :conf/live/:hostname/chain.pem)
--domain-key-path STRING Path to privkey.pem to use for domain (default: generate new)
--account-key-path STRING Path to privkey.pem to use for account (default: generate new)
2015-12-16 11:17:06 +00:00
--config-dir STRING Configuration directory. (Default is ~/letsencrypt/etc/)
2015-12-16 11:01:10 +00:00
--tls-sni-01-port NUMBER Use TLS-SNI-01 challenge type with this port.
(must be 443 with most production servers) (Boulder allows 5001 in testing mode)
--http-01-port [NUMBER] Use HTTP-01 challenge type with this port, used for SimpleHttp challenge. (Default is 80)
(must be 80 with most production servers)
--dns-01 Use DNS-01 challenge type.
--standalone [BOOLEAN] Obtain certs using a "standalone" webserver. (Default is true)
--manual [BOOLEAN] Print the token and key to the screen and wait for you to hit enter,
giving you time to copy it somewhere before continuing. (Default is false)
--webroot BOOLEAN Obtain certs by placing files in a webroot directory.
--webroot-path STRING public_html / webroot path.
2015-12-16 11:01:10 +00:00
--apache BOOLEAN Obtain certs using Apache virtual hosts.
--apache-path STRING Path in which to store files for Apache virtual hosts.
(Default is ~/letsencrypt/apache)
--apache-bind [STRING] IP address to use for Apache virtual host. (Default is *)
(This is used in the default template.)
--apache-port [NUMBER] Port to use for Apache virtual host. (Default is 443)
(This is used in the default template.)
--apache-webroot STRING Webroot to use for Apache virtual host (e.g. an empty dir).
Nothing should actually be served from here. (Default is /var/www)
--apache-template STRING Alternative template to use for Apache configuration file.
--apache-enable STRING Command to run to enable the site in Apache.
(Default is `ln -s {{{conf}}} /etc/apache2/sites-enabled`)
--apache-check STRING Command to run to check Apache configuration.
(Default is `apache2ctl configtest`)
--apache-reload STRING Command to run to reload Apache.
(Default is `/etc/init.d/apache2 reload`)
--apache-disable STRING Command to run to disable the site in Apache.
(Default is `rm /etc/apache2/sites-enabled/{{{token}}}.conf`)
--debug BOOLEAN show traces and logs
2015-12-16 11:01:10 +00:00
-h, --help Display help and usage details
```
2015-12-16 13:03:03 +00:00
Note: some of the options may not be fully implemented. If you encounter a problem, please report a bug on the issues page.