root
/
greenlock-cli.js
mirror of https://git.coolaj86.com/coolaj86/greenlock-cli.js
2
0
Fork 0
Code Issues 2 Releases Wiki Activity
greenlock-cli.js/README.md

9.6 KiB
Raw Blame History

Greenlock Logo

Greenlock™ for Web Servers

Free SSL, Free Wildcard SSL, and Fully Automated HTTPS made dead simple
certificates issued by Let's Encrypt v2 via ACME

"Lifetime Downloads" "Monthly Downloads" "Weekly Downloads" "Stackoverflow Questions"

| Sponsored by ppl | Greenlock for Web Servers | Greenlock for Web Browsers | Greenlock for Express.js | Greenlock™.js |

Features

  • Commandline (cli) Certificate Manager (like certbot)
  • Integrated Web Server
  • Free SSL Certificates
  • Automatic certificate renewal before expiration
  • One-off standalone registration / renewal
  • On-the-fly registration / renewal via webroot

Install

Mac & Linux

Open Terminal and run this install script:

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:

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
  2. Open Node.js
  3. 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

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

primarily for testing

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

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

for testing and production

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:
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:
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

primarily 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 --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:

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.