greenlock.js-ARCHIVED/MIGRATION_GUIDE.md

Migrating Guide

Greenlock v4 is the current version.

v3 to v4

v4 is a very minor, but breaking, change from v3

configFile is replaced with configDir

The default config file ./greenlock.json is now ./greenlock.d/config.json.

This was change was mode to eliminate unnecessary configuration that was inadvertantly introduced in v3.

.greenlockrc is auto-generated

.greenlockrc exists for the sake of tooling - so that the CLI, Web API, and your code naturally stay in sync.

It looks like this:

{
    "manager": {
        "module": "@greenlock/manager"
    },
    "configDir": "./greenlock.d"
}

If you deploy to a read-only filesystem, it is best that you create the .greenlockrc file as part of your image and use that rather than including any configuration in your code.

v2 to v4

Greenlock Express uses Greenlock directly, the same as before.

All options described for Greenlock.create({...}) also apply to the Greenlock Express init() callback.

Overview of Major Differences

• Reduced API
• No code in the config
  • (config is completely serializable)
• Manager callbacks replace approveDomains
• Greenlock Express does more, with less config
  • cluster is supported out-of-the-box
  • high-performance
  • scalable
• ACME challenges are simplified
  • init
  • zones (dns-01)
  • set
  • get
  • remove
• Store callbacks are simplified
  • accounts
    • checkKeypairs
  • certificates
    • checkKeypairs
    • check
    • set

Greenlock JavaScript API greatly reduced

Whereas before there were many different methods with nuance differences, now there's just create, get, renew, and sometimes add ().

• Greenlock.create({ maintainerEmail, packageAgent, notify })
• Greenlock.get({ servername, wildname, duplicate, force })
  • (just a convenience wrapper around renew)
• Greenlock.renew({ subject, altnames, issuedBefore, expiresAfter })
  • (retrieves, issues, renews, all-in-one)
• optional Greenlock.add({ subject, altnames, subscriberEmail })
  • (partially replaces approveDomains)

Also, some disambiguation on terms:

• domains was often ambiguous and confusing, it has been replaced by:
  • subject refers to the subject of a certificate - the primary domain
  • altnames refers to the domains in the SAN (Subject Alternative Names) section of the certificate
  • servername refers to the TLS (SSL) SNI (Server Name Indication) request for a cetificate
  • wildname refers to the wildcard version of the servername (ex: www.example.com => *.example.com)

When you create an instance of Greenlock, you only supply package and maintainer info.

All other configuration is A) optional and B) handled by the Manager.

'use strict';

var pkg = require('./package.json');

var Greenlock = require('greenlock');
var greenlock = Greenlock.create({
    // used for the ACME client User-Agent string as per RFC 8555 and RFC 7231
    packageAgent: pkg.name + '/' + pkg.version,

    // used as the contact for critical bug and security notices
    // should be the same as pkg.author.email
    maintainerEmail: 'jon@example.com',

    // used for logging background events and errors
    notify: function(ev, args) {
        if ('error' === ev || 'warning' === ev) {
            console.error(ev, args);
            return;
        }
        console.info(ev, args);
    }
});

By default no certificates will be issued. See the manager section.

When you want to get a single certificate, you use get, which will:

• will return null if neither the servername or its wildname (wildcard) variant can be found
• retrieve a non-expired certificate, if possible
• will renew the certificate in the background, if stale
• will wait for the certificate to be issued if new

greenlock
    .get({ servername: 'www.example.com' })
    .then(function(result) {
        if (!result) {
            // certificate is not on the approved list
            return null;
        }

        var fullchain = result.pems.cert + '\n' + result.pems.chain + '\n';
        var privkey = result.pems.privkey;

        return {
            fullchain: fullchain,
            privkey: privkey
        };
    })
    .catch(function(e) {
        // something went wrong in the renew process
        console.error(e);
    });

By default no certificates will be issued. See the manager section.

When you want to renew certificates, en masse, you use renew, which will:

• check all certificates matching the given criteria
• only renew stale certificates by default
• return error objects (will NOT throw exception for failed renewals)

greenlock
    .renew({})
    .then(function(results) {
        if (!result.length) {
            // no certificates found
            return null;
        }

        // [{ site, error }]
        return results;
    })
    .catch(function(e) {
        // an unexpected error, not related to renewal
        console.error(e);
    });

Options:

Option	Description
altnames	only check and renew certs matching these altnames (including wildcards)
renewBefore	only check and renew certs marked for renewal before the given date, in ms
duplicate	renew certificates regardless of timing
force	allow silly things, like tiny renewOffsets

By default no certificates will be issued. See the manager section.

Greenlock Express Example

The options that must be returned from init() are the same that are used in Greenlock.create(), with a few extra that are specific to Greenlock Express:

require('@root/greenlock-express')
    .init(function() {
        // This object will be passed to Greenlock.create()

        var options = {
            // some options, like cluster, are special to Greenlock Express

            cluster: false,

            // The rest are the same as for Greenlock

            packageAgent: pkg.name + '/' + pkg.version,
            maintainerEmail: 'jon@example.com',
            notify: function(ev, args) {
                console.info(ev, args);
            }
        };

        return options;
    })
    .serve(function(glx) {
        // will start servers on port 80 and 443

        glx.serveApp(function(req, res) {
            res.end('Hello, Encrypted World!');
        });

        // you can get access to the raw server (i.e. for websockets)

        glx.httpsServer(); // returns raw server object
    });

Manager replaces approveDomains

approveDomains was always a little confusing. Most people didn't need it.

Instead, now there is a simple config file that will work for most people, as well as a set of callbacks for easy configurability.

Default Manager

The default manager is @greenlock/manager and the default configDir is ./.greenlock.d.

The config file should look something like this:

./greenlock.d/config.json:

{
    "subscriberEmail": "jon@example.com",
    "agreeToTerms": true,
    "sites": {
        "example.com": {
            "subject": "example.com",
            "altnames": ["example.com", "www.example.com"]
        }
    }
}

You can specify a acme-dns-01-* or acme-http-01-* challenge plugin globally, or per-site.

{
    "subscriberEmail": "jon@example.com",
    "agreeToTerms": true,
    "sites": {
        "example.com": {
            "subject": "example.com",
            "altnames": ["example.com", "www.example.com"],
            "challenges": {
                "dns-01": {
                    "module": "acme-dns-01-digitalocean",
                    "token": "apikey-xxxxx"
                }
            }
        }
    }
}

The same is true with greenlock-store-* plugins:

{
    "subscriberEmail": "jon@example.com",
    "agreeToTerms": true,
    "sites": {
        "example.com": {
            "subject": "example.com",
            "altnames": ["example.com", "www.example.com"]
        }
    },
    "store": {
        "module": "greenlock-store-fs",
        "basePath": "~/.config/greenlock"
    }
}

Customer Manager, the lazy way

At the very least you have to implement get({ servername, wildname }).

var greenlock = Greenlock.create({
    packageAgent: pkg.name + '/' + pkg.version,
    maintainerEmail: 'jon@example.com',
    notify: notify,

    packageRoot: __dirname,
    manager: {
        module: './manager.js'
    }
});

function notify(ev, args) {
    if ('error' === ev || 'warning' === ev) {
        console.error(ev, args);
        return;
    }
    console.info(ev, args);
}

In the simplest case you can ignore all incoming options and return a single site config in the same format as the config file

./manager.js:

'use strict';

module.exports.create = function() {
    return {
        get: async function({ servername }) {
            // do something to fetch the site
            var site = {
                subject: 'example.com',
                altnames: ['example.com', 'www.example.com']
            };

            return site;
        }
    };
};

If you want to use wildcards or local domains for a specific domain, you must specify the dns-01 challenge plugin to use:

'use strict';

module.exports.create = function() {
    return {
        get: async function({ servername }) {
            // do something to fetch the site
            var site = {
                subject: 'example.com',
                altnames: ['example.com', 'www.example.com'],

                // dns-01 challenge
                challenges: {
                    'dns-01': {
                        module: 'acme-dns-01-namedotcom',
                        apikey: 'xxxx'
                    }
                }
            };

            return site;
        }
    };
};

Customer Manager, Complete

See https://git.rootprojects.org/root/greenlock-manager-test.js#quick-start

ACME Challenge Plugins

The ACME challenge plugins are just a few simple callbacks:

• init
• zones (dns-01 only)
• set
• get
• remove

They are described here:

• dns-01 documentation
• http-01 documentation

Key and Cert Store Plugins

Again, these are just a few simple callbacks:

• certificates.checkKeypair
• certificates.check
• certificates.setKeypair
• certificates.set
• accounts.checkKeypair
• accounts.check (optional)
• accounts.setKeypair
• accounts.set (optional)

The name check is used instead of get because they only need to return something if it exists. They do not need to fail, nor do they need to generate anything.

They are described here:

• greenlock store documentation

If you are just implenting in-house and are not going to publish a module, you can also do some hack things like this: