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

12 KiB
Raw Permalink Blame History

Greenlock Logo

Greenlock™ Certificate Manager for Web Servers

A server-friendly commandline tool for Free SSL, Free Wildcard SSL, and Fully Automated HTTPS certificates issued by Let's Encrypt v2 via ACME

Greenlock is also available for Browsers, for node.js, and for API integrations

Why use Greenlock? Two Reasons:

One

You want to be able to run a command like this:

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:

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

  • Works with Windows, Mac, and Linux
  • Works with Apache, Nginx, node.js, HAProxy, etc
  • Great for VPS services - AWS, Digital Ocean, Vultr, etc
  • Great for Tiny Computers - Raspberry Pi, etc
  • Automatic HTTPS
    • Free SSL
    • Free Wildcard SSL
    • Multiple domain support (up to 100 altnames per SAN)
    • Virtual Hosting (vhost)
    • Automatical renewal (10 to 14 days before expiration)
    • Let's Encrypt v2 ACME API
  • Extensible via Plugins
    • HTTP Challenge Plugins - AWS S3, Azure, Consul, etcd
    • DNS Challenge Plugins - AWS Route53, CloudFlare, Digital Ocean
    • Account & Certificate Storage Plugins - AWS S3, Redis
  • Built-in WebServer

Install

Mac

Open Terminal and run this install script:

curl -fsS https://get.greenlock.app/ | bash

Linux

Open Terminal and run this install script:

curl -fsS https://get.greenlock.app/ | bash

Windows & Node.js

  1. Install node.js
  2. Open Node.js
  3. 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:

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)

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:

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:

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

Note: Replace whatever.com with your domain, use your real email, etc.

  1. Use the --staging flag while troubleshooting
  2. Do you have a valid A record for whatever.com?
  3. When you ping whatever.com do you see that same address?
  4. Can you confirm that's your server's address with ifconfig or ipconfig?
  5. 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:

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

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:

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.

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

# 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)

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.