mirror of
https://git.coolaj86.com/coolaj86/greenlock-cli.js
synced 2025-02-23 03:38:03 +00:00
396 lines
12 KiB
Markdown
396 lines
12 KiB
Markdown
|
||
|
||
# Greenlock™ Certificate Manager for Web Servers
|
||
|
||
A server-friendly commandline tool for Free SSL, Free Wildcard SSL, and Fully Automated HTTPS
|
||
<small>certificates issued by Let's Encrypt v2 via ACME</small>
|
||
|
||
Greenlock is also available
|
||
[for Browsers](https://git.coolaj86.com/coolaj86/greenlock.html),
|
||
[for node.js](https://git.coolaj86.com/coolaj86/greenlock-express.js),
|
||
and [for API integrations](https://git.coolaj86.com/coolaj86/greenlock.js)
|
||
|
||
Why use Greenlock? Two Reasons:
|
||
===============================
|
||
|
||
One
|
||
---
|
||
|
||
You want to be able to run a command like this:
|
||
|
||
```bash
|
||
sudo greenlock --domains example.com --config /etc/greenlock/greenlock.yml
|
||
```
|
||
|
||
And then get awesome results like this:
|
||
|
||
```
|
||
/etc/ssl/acme
|
||
├── accounts
|
||
│ └── acme-staging-v02.api.letsencrypt.org/directory
|
||
│ └── c07a31a70c691d64f6b4d31f51a6dd9c
|
||
│ ├── meta.json
|
||
│ ├── private_key.json
|
||
│ └── regr.json
|
||
└── live
|
||
└── example.com <-- Free SSL like magic! Wow!
|
||
├── bundle.pem
|
||
├── cert.pem
|
||
├── chain.pem
|
||
├── fullchain.pem
|
||
└── privkey.pem
|
||
```
|
||
|
||
That you use with your existing webserver - Apache, Nginx, HAProxy, node.js, etc
|
||
|
||
And install to renew so that you never worry about ssl again.
|
||
|
||
Two
|
||
---
|
||
|
||
You want to be able to run a command like this:
|
||
|
||
```bash
|
||
sudo greenlock --install systemd --config /etc/greenlock.yml --webroot '/srv/www/:hostname'
|
||
```
|
||
|
||
To immediately secure and publish any and all sites you have in a web root like this:
|
||
|
||
```
|
||
/srv/www/
|
||
├── coolsite.rocks
|
||
├── example.com
|
||
└── whatever.app
|
||
```
|
||
|
||
Features
|
||
========
|
||
|
||
- [x] Works with Windows, Mac, and Linux
|
||
- [x] Works with Apache, Nginx, node.js, HAProxy, etc
|
||
- [x] Great for VPS services - AWS, Digital Ocean, Vultr, etc
|
||
- [x] Great for Tiny Computers - Raspberry Pi, etc
|
||
- [x] Automatic HTTPS
|
||
- [x] Free SSL
|
||
- [x] Free Wildcard SSL
|
||
- [x] Multiple domain support (up to 100 altnames per SAN)
|
||
- [x] Virtual Hosting (vhost)
|
||
- [x] Automatical renewal (10 to 14 days before expiration)
|
||
- [x] Let's Encrypt v2 ACME API
|
||
- [x] Extensible via Plugins
|
||
- [x] HTTP Challenge Plugins - AWS S3, Azure, Consul, etcd
|
||
- [x] DNS Challenge Plugins - AWS Route53, CloudFlare, Digital Ocean
|
||
- [x] Account & Certificate Storage Plugins - AWS S3, Redis
|
||
- [x] Built-in WebServer
|
||
|
||
Install
|
||
=======
|
||
|
||
Mac
|
||
---
|
||
|
||
Open Terminal and run this install script:
|
||
|
||
```bash
|
||
curl -fsS https://get.greenlock.app/ | bash
|
||
```
|
||
|
||
Linux
|
||
-----
|
||
|
||
Open Terminal and run this install script:
|
||
|
||
```bash
|
||
curl -fsS https://get.greenlock.app/ | bash
|
||
```
|
||
|
||
Windows & Node.js
|
||
-----------------
|
||
|
||
1. Install [node.js](https://nodejs.org)
|
||
2. Open _Node.js_
|
||
2. Run the command `npm install -g greenlock-cli`
|
||
|
||
Important: How to Not Get Blocked
|
||
===================
|
||
|
||
PLEASE READ ALL THREE SENTENCES:
|
||
|
||
* These examples use the PRODUCTION ENVIRONMENT (where you can be blocked)
|
||
* If an example DOESN'T WORK on the first try, STOP!
|
||
* UNCOMMENT the `--staging` flag and see the TROUBLESHOOTING SECTION
|
||
|
||
Quick Examples
|
||
==============
|
||
|
||
The most basic options are exposed as commandline flags,
|
||
just so that we can do little domes like this.
|
||
|
||
The config file is explained after the troubleshooting section.
|
||
|
||
### The Greenlock HTTPS WebServer
|
||
|
||
Easy to run on your server, nothing else required:
|
||
|
||
```bash
|
||
sudo greenlock --webserver \
|
||
--agree-tos --email jon@example.com \
|
||
--domains example.com,www.example.com \
|
||
--webroot /srv/www/example.com \
|
||
--config-dir ~/acme/etc #--staging
|
||
```
|
||
|
||
### Add SSL to an Existing WebServer
|
||
|
||
For all the Apache, Nginx, and HAProxy fans out there:
|
||
|
||
(use your existing webroot)
|
||
|
||
```bash
|
||
sudo greenlock --agree-tos --email jon@example.com \
|
||
--domains example.com,www.example.com \
|
||
--webroot /srv/www/example.com \
|
||
--privkey-path /etc/ssl/example.com/privkey.pem \
|
||
--fullchain-path /etc/ssl/example.com/fullchain.pem \
|
||
--bundle-path /etc/ssl/example.com/bundle.pem \
|
||
--config-dir /etc/ssl/acme #--staging
|
||
```
|
||
|
||
### Get SSL Certificates Interactively
|
||
|
||
Run this manual process on your laptop and copy the certificates
|
||
to you server afterwards:
|
||
|
||
```bash
|
||
greenlock --agree-tos --email jon@example.com \
|
||
--domains example.com,www.example.com \
|
||
--privkey-path /etc/ssl/example.com/privkey.pem \
|
||
--fullchain-path /etc/ssl/example.com/fullchain.pem \
|
||
--bundle-path /etc/ssl/example.com/bundle.pem \
|
||
--manual \
|
||
--config-dir /etc/ssl/acme #--staging
|
||
```
|
||
|
||
### Standalone SSL Certificate Retrieval
|
||
|
||
Run this on a server standalone just to retrieve
|
||
certificates:
|
||
|
||
```bash
|
||
sudo greenlock --agree-tos --email jon@example.com \
|
||
--domains example.com,www.example.com \
|
||
--privkey-path /etc/ssl/example.com/privkey.pem \
|
||
--fullchain-path /etc/ssl/example.com/fullchain.pem \
|
||
--bundle-path /etc/ssl/example.com/bundle.pem \
|
||
--standalone \
|
||
--config-dir ~/etc/ssl/acme #--staging
|
||
```
|
||
|
||
Troubleshooting
|
||
===============
|
||
|
||
Watch the [Troubleshooting Screencast](https://youtu.be/e8vaR4CEZ5s?t=397)
|
||
|
||
**Note**: Replace `whatever.com` with your domain, use your real email, etc.
|
||
|
||
0. Use the `--staging` flag while troubleshooting
|
||
1. Do you have a valid A record for `whatever.com`?
|
||
2. When you `ping whatever.com` do you see that same address?
|
||
3. Can you confirm that's your server's address with `ifconfig` or `ipconfig`?
|
||
4. Do you have write access to all of the directories you've specified?
|
||
|
||
**Important**: Don't forget to delete the directory specified in `--config-dir`
|
||
when you get things figured out and remove `--staging`.
|
||
|
||
|
||
Usage
|
||
=====
|
||
|
||
These commands are shown using the **testing server**.
|
||
|
||
Want to use the **live server**?
|
||
|
||
1. change server to `--server https://acme-v02.api.letsencrypt.org/directory`
|
||
|
||
**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)
|
||
|
||
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:
|
||
|
||
```bash
|
||
greenlock certonly \
|
||
--agree-tos --email john.doe@example.com \
|
||
--standalone \
|
||
--domains example.com,www.example.com \
|
||
--server https://acme-staging-v02.api.letsencrypt.org/directory \
|
||
--acme-version draft-11
|
||
--config-dir ~/acme/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-v02.api.letsencrypt.org/directory \
|
||
--acme-version draft-11
|
||
--config-dir ~/acme/etc
|
||
```
|
||
|
||
Then you can see your certs at `~/letsencrypt/etc/live`.
|
||
|
||
```
|
||
ls ~/letsencrypt/etc/live
|
||
```
|
||
|
||
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
|
||
|
||
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.
|
||
|
||
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:
|
||
|
||
```bash
|
||
sudo greenlock certonly \
|
||
--agree-tos --email john.doe@example.com \
|
||
--webroot --webroot-path /srv/www/example.com \
|
||
--config-dir /etc/letsencrypt \
|
||
--domains example.com,www.example.com \
|
||
--server https://acme-staging-v02.api.letsencrypt.org/directory
|
||
--acme-version draft-11
|
||
```
|
||
|
||
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.
|
||
|
||
Then see your brand new shiny certs:
|
||
|
||
```
|
||
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.
|
||
|
||
### 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 greenlock certonly \
|
||
--agree-tos --email john.doe@example.com \
|
||
--manual
|
||
--config-dir /etc/acme \
|
||
--domains example.com,www.example.com \
|
||
--server https://acme-staging-v02.api.letsencrypt.org/directory
|
||
--acme-version draft-11
|
||
```
|
||
|
||
## 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
|
||
|
||
# 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'
|
||
```
|
||
|
||
Example domain:
|
||
|
||
```
|
||
rubber-duck-42.daplie.me
|
||
```
|
||
|
||
## 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
|
||
```
|
||
|
||
By default `node-greenlock` 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
|
||
sudo chown -R $(whoami) /etc/letsencrypt /var/lib/letsencrypt /var/log/letsencrypt
|
||
```
|
||
|
||
## Command Line Options
|
||
|
||
```
|
||
Usage:
|
||
greenlock [OPTIONS] [ARGS]
|
||
|
||
Options:
|
||
--server [STRING] ACME Directory Resource URI. (Default is https://acme-v01.api.letsencrypt.org/directory))
|
||
|
||
--email EMAIL Email used for registration and recovery contact. (default: null)
|
||
|
||
--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: [])
|
||
|
||
--renew-within [NUMBER] Renew certificates this many days before expiry. (default: 7)
|
||
|
||
--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)
|
||
|
||
--config-dir STRING Configuration directory. (Default is ~/letsencrypt/etc/)
|
||
|
||
--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.
|
||
|
||
--debug BOOLEAN show traces and logs
|
||
|
||
-h, --help Display help and usage details
|
||
```
|
||
|
||
Note: some of the options may not be fully implemented. If you encounter a problem, please report a bug on the issues page.
|