coolaj86
/
greenlock-cli.js
1
0
Fork 0
Code Issues 4 Pull Requests Releases Activity

Update intro, remove tls-sni-01 options, R.I.P.

This commit is contained in:
AJ ONeal 2018-05-15 08:52:19 +00:00
parent 5e832fa3d6
commit 076528320b
1 changed files with 26 additions and 122 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

148
README.md
View File

@ -1,18 +1,30 @@
# greenlock-cli (letsencrypt-cli for node.js) ![Greenlock Logo](https://git.coolaj86.com/coolaj86/greenlock.js/raw/branch/master/logo/greenlock-1063x250.png "Greenlock Logo")
| [greenlock (library)](https://git.coolaj86.com/coolaj86/greenlock.js) Greenlock™ for Web Servers
| **greenlock-cli** ================
| [greenlock-express](https://git.coolaj86.com/coolaj86/greenlock-express.js)
| [greenlock-koa](https://git.coolaj86.com/coolaj86/greenlock-koa.js) Free SSL, Free Wildcard SSL, and Fully Automated HTTPS made dead simple<br>
| [greenlock-hapi](https://git.coolaj86.com/coolaj86/greenlock-hapi.js) <small>certificates issued by Let's Encrypt v2 via [ACME](https://git.coolaj86.com/coolaj86/acme-v2.js)</small>
!["Lifetime Downloads"](https://img.shields.io/npm/dt/greenlock.svg "Lifetime Download Count can't be shown")
!["Monthly Downloads"](https://img.shields.io/npm/dm/greenlock.svg "Monthly Download Count can't be shown")
!["Weekly Downloads"](https://img.shields.io/npm/dw/greenlock.svg "Weekly Download Count can't be shown")
| Sponsored by [ppl](https://ppl.family)
| **Greenlock for Web Servers**
| [Greenlock for Web Browsers](https://git.coolaj86.com/coolaj86/greenlock.html)
| [Greenlock for Express.js](https://git.coolaj86.com/coolaj86/greenlock-express.js)
| [Greenlock&trade;.js](https://git.coolaj86.com/coolaj86/greenlock.js)
| |
CLI for node-greenlock modeled after the official client. Features
====
* Free SSL Certificates - [x] Commandline (cli) Certificate Manager (like certbot)
* 90-day certificate lifetime - [x] Integrated Web Server
* One-off standalone registration / renewal - [x] Free SSL Certificates
* On-the-fly registration / renewal via webroot - [x] Automatic certificate renewal before expiration
- [x] One-off standalone registration / renewal
- [x] On-the-fly registration / renewal via webroot
## Install Node ## Install Node
@ -46,8 +58,7 @@ multiple domains doesn't work for you, file a bug.
### Standalone (primarily for testing) ### Standalone (primarily for testing)
You can run standalone mode to get a cert **on the server**. You either use an 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 http-01 challenge (the default) on port 80. Like so:
443 (or 5001). Like so:
```bash ```bash
greenlock certonly \ greenlock certonly \
@ -58,17 +69,6 @@ greenlock certonly \
--config-dir ~/letsencrypt/etc --config-dir ~/letsencrypt/etc
``` ```
or
```bash
greenlock 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
```
Then you can see your certs at `~/letsencrypt/etc/live`. Then you can see your certs at `~/letsencrypt/etc/live`.
``` ```
@ -79,7 +79,7 @@ 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 the same ports that your webserver needs, it isn't a good choice
for production. for production.
### WebRoot (production option 1) ### WebRoot
You can specify the path to where you keep your `index.html` with `webroot`, as 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. long as your server is serving plain HTTP on port 80.
@ -108,70 +108,6 @@ ls /etc/letsencrypt/live/
You can use a cron job to run the script above every 80 days (the certificates expire after 90 days) 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. so that you always have fresh certificates.
### Hooks (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 can work with any web server as long as it supports server
name indication (SNI) and you can provide a configuration file template and
shell hooks to install and uninstall the configuration (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 greenlock certonly \
--agree-tos --email john.doe@example.com \
--hooks --hooks-server apache2-debian \
--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.
You can then find your brand new certs in:
```
ls /etc/letsencrypt/live/
```
Tailor to your server and distro using the `--hooks-server` option. So far, the
following are supported (contributions for additional servers welcome):
* apache2-debian
To tweak it for your setup and taste, see all the `hooks-` options in the
Command Line Options section below. Also note that the following substitutions
are available for use in the hooks and the template:
* `{{{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: `hooks-path/token.crt`
* `{{{privkey}}}`: the path to the generated private key: `hooks-path/token.key`
* `{{{conf}}}`: the path to the generated config file: `hooks-path/token.conf`
* `{{{bind}}}`: the value of the `hooks-bind` option
* `{{{port}}}`: the value of the `hooks-port` option
* `{{{webroot}}}`: the value of the `hooks-webroot` option
### Interactive (for debugging) ### Interactive (for debugging)
The token (for all challenge types) and keyAuthorization (only for https-01) The token (for all challenge types) and keyAuthorization (only for https-01)
@ -268,9 +204,6 @@ Options:
--config-dir STRING Configuration directory. (Default is ~/letsencrypt/etc/) --config-dir STRING Configuration directory. (Default is ~/letsencrypt/etc/)
--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) --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) (must be 80 with most production servers)
@ -285,35 +218,6 @@ Options:
--webroot-path STRING public_html / webroot path. --webroot-path STRING public_html / webroot path.
--hooks BOOLEAN Obtain certs with hooks that configure a webserver to meet TLS-SNI-01 challenges.
--hooks-path STRING Path in which to store files for hooks.
(Default is ~/letsencrypt/apache)
--hooks-server STRING Type of webserver to configure. Sets defaults for all the following --hooks- options.
Either --hooks-server or --hooks-template must be given.
(See the Hooks section above for a list of supported servers.)
--hooks-template STRING Template to use for hooks configuration file.
Either --hooks-server or --hooks-template must be given.
--hooks-bind STRING IP address to use in configuration for hooks. (Default is *)
--hooks-port STRING Port to use in configuration for hooks. (Default is 443)
--hooks-webroot STRING Webroot to use in configuration for hooks (e.g. empty dir).
Nothing should actually be served from here. (Default is /var/www)
--hooks-pre-enable STRING Hook to check the webserver configuration prior to enabling.
--hooks-enable STRING Hook to enable the webserver configuration.
--hooks-pre-reload STRING Hook to check the webserver configuration prior to reloading.
--hooks-reload STRING Hook to reload the webserver.
--hooks-disable STRING Hook to disable the webserver configuration.
--debug BOOLEAN show traces and logs --debug BOOLEAN show traces and logs
-h, --help Display help and usage details -h, --help Display help and usage details