mirror of
https://git.coolaj86.com/coolaj86/greenlock-cli.js
synced 2025-11-04 02:52:48 +00:00
Update intro, remove tls-sni-01 options, R.I.P.
This commit is contained in:
parent
5e832fa3d6
commit
076528320b
148
README.md
148
README.md
@ -1,18 +1,30 @@
|
||||
# greenlock-cli (letsencrypt-cli for node.js)
|
||||
|
||||
|
||||
| [greenlock (library)](https://git.coolaj86.com/coolaj86/greenlock.js)
|
||||
| **greenlock-cli**
|
||||
| [greenlock-express](https://git.coolaj86.com/coolaj86/greenlock-express.js)
|
||||
| [greenlock-koa](https://git.coolaj86.com/coolaj86/greenlock-koa.js)
|
||||
| [greenlock-hapi](https://git.coolaj86.com/coolaj86/greenlock-hapi.js)
|
||||
Greenlock™ for Web Servers
|
||||
================
|
||||
|
||||
Free SSL, Free Wildcard SSL, and Fully Automated HTTPS made dead simple<br>
|
||||
<small>certificates issued by Let's Encrypt v2 via [ACME](https://git.coolaj86.com/coolaj86/acme-v2.js)</small>
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
| 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™.js](https://git.coolaj86.com/coolaj86/greenlock.js)
|
||||
|
|
||||
|
||||
CLI for node-greenlock modeled after the official client.
|
||||
|
||||
* Free SSL Certificates
|
||||
* 90-day certificate lifetime
|
||||
* One-off standalone registration / renewal
|
||||
* On-the-fly registration / renewal via webroot
|
||||
Features
|
||||
====
|
||||
- [x] Commandline (cli) Certificate Manager (like certbot)
|
||||
- [x] Integrated Web Server
|
||||
- [x] Free SSL Certificates
|
||||
- [x] Automatic certificate renewal before expiration
|
||||
- [x] One-off standalone registration / renewal
|
||||
- [x] On-the-fly registration / renewal via webroot
|
||||
|
||||
## Install Node
|
||||
|
||||
@ -46,8 +58,7 @@ multiple domains doesn't work for you, file a bug.
|
||||
### Standalone (primarily for testing)
|
||||
|
||||
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:
|
||||
http-01 challenge (the default) on port 80. Like so:
|
||||
|
||||
```bash
|
||||
greenlock certonly \
|
||||
@ -58,17 +69,6 @@ greenlock certonly \
|
||||
--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`.
|
||||
|
||||
```
|
||||
@ -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
|
||||
for production.
|
||||
|
||||
### WebRoot (production option 1)
|
||||
### WebRoot
|
||||
|
||||
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.
|
||||
@ -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)
|
||||
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)
|
||||
|
||||
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/)
|
||||
|
||||
--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)
|
||||
|
||||
@ -285,35 +218,6 @@ Options:
|
||||
|
||||
--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
|
||||
|
||||
-h, --help Display help and usage details
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user