greenlock-cli.js/README.md

![Greenlock Logo](https://git.coolaj86.com/coolaj86/greenlock.js/raw/branch/master/logo/greenlock-1063x250.png "Greenlock Logo")

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