278 lines
9.6 KiB
Markdown
278 lines
9.6 KiB
Markdown
|
|
|
|
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)
|
|
|
|
|
|
|
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
|
|
=======
|
|
|
|
Mac & Linux
|
|
-----------
|
|
|
|
Open Terminal and run this install script:
|
|
|
|
```bash
|
|
curl -fsS https://get.greenlock.app/ | bash
|
|
```
|
|
|
|
This will install greenlock to `/opt/greenlock` and put a symlink to
|
|
`/opt/greenlock/bin/greenlock` in `/usr/local/bin/greenlock` for convenience.
|
|
|
|
You can customize the installation:
|
|
|
|
```bash
|
|
export NODEJS_VER=v8.11.1
|
|
export GREENLOCK_PATH=/opt/greenlock
|
|
curl -fsS https://get.greenlock.app/ | bash
|
|
```
|
|
|
|
This will change which version of node.js is bundled with greenlock
|
|
and the path to which greenlock installs.
|
|
|
|
Windows & Node.js
|
|
-----------------
|
|
|
|
1. Install [node.js](https://nodejs.org)
|
|
2. Open _Node.js_
|
|
2. Run the command `npm install -g greenlock-cli`
|
|
|
|
Usage
|
|
=====
|
|
|
|
We have a few different examples of issuing SSL certificates:
|
|
|
|
* Standalone (testing): Issue a one-off certificate
|
|
* Webroot (production): Automatic certificate renewal for Apache, Nginx, HAProxy, etc
|
|
* Manual (debugging): Go through the certificate proccess step-by-step
|
|
<!-- * Server (production): Leave it all to Greenlock -->
|
|
|
|
**Important Note**: Staging vs Production
|
|
|
|
Each of these examples are using the **staging server**.
|
|
|
|
Once you've successfully gotten certificates with the staging server
|
|
you must **delete** `--config-dir` (i.e. `rm -rf ~/acme`) and then
|
|
switch to the **production server**.
|
|
|
|
```
|
|
--acme-version draft-11 --server https://acme-v02.api.letsencrypt.org/directory \
|
|
```
|
|
|
|
## Standalone
|
|
|
|
<small>**primarily for testing**</small>
|
|
|
|
You can run in standalone mode **on your server** and get a cert instantly.
|
|
|
|
Note: No other webserver may be running at the time (use Webroot mode for that).
|
|
|
|
```bash
|
|
sudo greenlock certonly --standalone \
|
|
--acme-version draft-11 --acme-url https://acme-staging-v02.api.letsencrypt.org/directory \
|
|
--agree-tos --email jon@example.com --domains example.com,www.example.com \
|
|
--community-member \
|
|
--config-dir ~/acme/etc
|
|
```
|
|
|
|
## WebRoot
|
|
|
|
<small>**for testing and production**</small>
|
|
|
|
With this method you must use **your existing http (port 80) server** (Apache, Nginx, HAProxy, etc).
|
|
You will specify the **path or template path** to your `public_html` or `www` webroot.
|
|
|
|
For example:
|
|
|
|
* I want to get an SSL cert for `example.com`
|
|
* `index.html` lives at `/srv/www/example.com`
|
|
* I would use this command:
|
|
|
|
```bash
|
|
sudo greenlock certonly --webroot \
|
|
--acme-version draft-11 --acme-url https://acme-staging-v02.api.letsencrypt.org/directory \
|
|
--agree-tos --email jon@example.com --domains example.com \
|
|
--community-member \
|
|
--root /srv/www/example.com \
|
|
--config-dir ~/acme/etc
|
|
```
|
|
|
|
Now let's say that
|
|
|
|
* I have many sites in `/srv/www/`, all by their name
|
|
* I already store my ssl certs in the format `/etc/apache/ssl/:hostname/{key.pem,ssl.crt}`
|
|
* I'll run this command instead:
|
|
|
|
```bash
|
|
sudo greenlock certonly --webroot \
|
|
--acme-version draft-11 --acme-url https://acme-staging-v02.api.letsencrypt.org/directory \
|
|
--agree-tos --email jon@example.com --domains example.com,whatever.com,foobar.net \
|
|
--community-member \
|
|
--root "/srv/www/:hostname" \
|
|
--privkey-path "/etc/apache/ssl/:hostname/key.pem" \
|
|
--fullchain-path "/etc/apache/ssl/:hostname/ssl.crt" \
|
|
--config-dir ~/acme/etc
|
|
```
|
|
|
|
### Run with cron
|
|
|
|
Those commands are safe to be run **daily** with cron.
|
|
The certificates will automatically renew 2 weeks before expiring.
|
|
|
|
## Interactive
|
|
|
|
<small>**primarily for debugging**</small>
|
|
|
|
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 --manual \
|
|
--acme-version draft-11 --acme-url https://acme-staging-v02.api.letsencrypt.org/directory \
|
|
--agree-tos --email jon@example.com --domains example.com \
|
|
--community-member \
|
|
--config-dir ~/acme/etc
|
|
```
|
|
|
|
Certificate Locations
|
|
=====================
|
|
Then you can see your certs at `~/acme/etc/live`.
|
|
|
|
```
|
|
~/acme/etc/
|
|
└── example.com
|
|
├── cert.pem
|
|
├── chain.pem
|
|
├── fullchain.pem (Apache, Nginx, node.js)
|
|
├── privkey.pem (Apache, Nginx, node.js)
|
|
└── bundle.pem (HAProxy)
|
|
```
|
|
|
|
|
|
## Run without root (no sudo)
|
|
|
|
`sudo` is used to allow greenlock to use port 80 and write to httpd-owned directories.
|
|
|
|
Allow greenlock to bind on system ports without root:
|
|
|
|
```bash
|
|
sudo setcap cap_net_bind_service=+ep /opt/greenlock/bin/node
|
|
```
|
|
|
|
To allow greenlock to write to folders owned by another user, set it to run as that user.
|
|
|
|
Otherwise, you can change the permissions on the folders, which is
|
|
**probably a BAD IDEA**. Probabry a **security risk**.
|
|
But since some of you are going to do it anyway I might as well tell you how:
|
|
|
|
```
|
|
# PROBABLY A BAD IDEA
|
|
sudo chown -R $(whoami) /etc/ssl /etc/acme
|
|
```
|
|
|
|
Command Line Options
|
|
====================
|
|
|
|
```
|
|
Usage:
|
|
greenlock [OPTIONS] [ARGS]
|
|
|
|
Options:
|
|
--acme-version [STRING] 'draft-11' for Let's Encrypt v2 or 'v01' for Let's Encrypt v1. (default: null)
|
|
|
|
--acme-url [URL] Directory URL for ACME API. Let's Encrypt URLs are:
|
|
draft-11
|
|
https://acme-staging-v02.api.letsencrypt.org/directory
|
|
https://acme-v02.api.letsencrypt.org/directory
|
|
|
|
v01
|
|
https://acme-staging.api.letsencrypt.org/directory
|
|
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
|
|
|
|
--community-member Submit stats to and receive updates from Greenlock
|
|
|
|
--domains HOSTNAME 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: 10)
|
|
|
|
--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)
|
|
|
|
--bundle-path [STRING] Path to where new bundle.pem (fullchain + privkey) is saved
|
|
(Default is :conf/live/:hostname/bundle.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)
|
|
|
|
--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)
|
|
|
|
--debug BOOLEAN show traces and logs
|
|
|
|
-h, --help Display help and usage details
|
|
```
|
|
|
|
|
|
Certbot Command Line Options
|
|
============================
|
|
|
|
These options are maintained for compatability with certbot:
|
|
|
|
```
|
|
--server [STRING] ACME Directory Resource URI. (Default is https://acme-v01.api.letsencrypt.org/directory))
|
|
|
|
--duplicate BOOLEAN Allow getting a certificate that duplicates an existing one/is
|
|
an early renewal.
|
|
|
|
--webroot BOOLEAN Obtain certs by placing files in a webroot directory.
|
|
|
|
--webroot-path STRING public_html / webroot path.
|
|
```
|
|
|
|
Note: some of the options may not be fully implemented. If you encounter a problem, please report a bug on the issues page.
|