![Greenlock Logo](https://git.rootprojects.org/root/greenlock.js/raw/branch/master/logo/greenlock-1063x250.png "Greenlock Logo") !["Greenlock Function"](https://git.rootprojects.org/root/greenlock.js/raw/branch/master/logo/from-not-secure-to-secure-url-bar.png "from url bar showing not secure to url bar showing secure") # [Greenlock™](https://git.rootprojects.org/root/greenlock-cli.js) for Web Servers | a [Root](https://rootprojects.org) project Free SSL, Free Wildcard SSL, and Fully Automated HTTPS made dead simple
certificates issued by Let's Encrypt v2 via [ACME](https://git.rootprojects.org/root/acme-v2.js) !["Lifetime Downloads"](https://img.shields.io/npm/dt/greenlock.svg "Lifetime Download Count can't be shown") !["Monthly Downloads"](https://img.shields.io/npm/dm/greenlock.svg "Monthly Download Count can't be shown") !["Weekly Downloads"](https://img.shields.io/npm/dw/greenlock.svg "Weekly Download Count can't be shown") !["Stackoverflow Questions"](https://img.shields.io/stackexchange/stackoverflow/t/greenlock.svg "S.O. Question count can't be shown") | **Greenlock for Web Servers** | [Greenlock for Web Browsers](https://git.rootprojects.org/root/greenlock.html) | [Greenlock for Express.js](https://git.rootprojects.org/root/greenlock-express.js) | [Greenlock™.js](https://git.rootprojects.org/root/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 **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). ```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 **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: ```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 **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`. ```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. # Legal & Rules of the Road Greenlock™ and Bluecrypt™ are [trademarks](https://rootprojects.org/legal/#trademark) of AJ ONeal The rule of thumb is "attribute, but don't confuse". For example: > Built with [Greenlock CLI](https://git.rootprojects.org/root/greenlock-cli.js) (a [Root](https://rootprojects.org) project). Please [contact us](mailto:aj@therootcompany.com) if you have any questions in regards to our trademark, attribution, and/or visible source policies. We want to build great software and a great community. [Greenlock™](https://git.rootprojects.org/root/greenlock.js) | MPL-2.0 | [Terms of Use](https://therootcompany.com/legal/#terms) | [Privacy Policy](https://therootcompany.com/legal/#privacy)