diff --git a/README.md b/README.md index ceb8d1d..afe6d15 100644 --- a/README.md +++ b/README.md @@ -60,6 +60,296 @@ TODO --> +# JavaScript API + + + +
+Greenlock.create({ packageAgent, maintainerEmail, staging }) + +## Greenlock.create() + +Creates an instance of greenlock with _environment_-level values. + +```js + +var pkg = require('./package.json'); +var gl = Greenlock.create({ + // Staging for testing environments + staging: true, + + // This should be the contact who receives critical bug and security notifications + // Optionally, you may receive other (very few) updates, such as important new features + maintainerEmail: 'jon@example.com', + // for an RFC 8555 / RFC 7231 ACME client user agent + packageAgent: pkg.name + '/' pkg.version +}); +``` + +| Parameter | Description | +| --------------- | ------------------------------------------------------------------------------------ | +| maintainerEmail | the developer contact for critical bug and security notifications | +| packageAgent | if you publish your package for others to use, `require('./package.json').name` here | +| staging | use the Let's Encrypt staging URL instead of the production URL | +| directoryUrl | for use with other (not Let's Encrypt) ACME services, and the Pebble test server | + + + +
+ +
+Greenlock#manager.defaults() + +## Greenlock#manager.defaults() + +Acts as a getter when given no arguments. + +Otherwise sets default, site-wide values as described below. + +```js +greenlock.manager.defaults({ + // The "Let's Encrypt Subscriber" (often the same as the maintainer) + // NOT the end customer (except where that is also the maintainer) + subscriberEmail: 'jon@example.com', + agreeToTerms: true + challenges: { + "http-01": { + module: "acme-http-01-webroot", + webroot: "/path/to/webroot" + } + } +}); +``` + +| Parameter | Description | +| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | +| agreeToTerms | (default: false) either 'true' or a function that presents the Terms of Service and returns it once accepted | +| challenges['http-01'] | provide an http-01 challenge module | +| challenges['dns-01'] | provide a dns-01 challenge module | +| challenges['tls-alpn-01'] | provide a tls-alpn-01 challenge module | +| challenges[type].module | the name of your challenge module | +| challenges[type].xxxx | module-specific options | +| servername | the default servername to use for non-sni requests (many IoT clients) | +| subscriberEmail | the contact who agrees to the Let's Encrypt Subscriber Agreement and the Greenlock Terms of Service
this contact receives renewal failure notifications | +| store | override the default storage module | +| store.module | the name of your storage module | +| store.xxxx | options specific to your storage module | + + + +
+ +
+Greenlock#add({ subject, altnames }) + +## Greenlock#add() + +Greenlock is a **Management Environment**. + +Once you add a "site", it will begin to automatically renew, immediately. + +The certificates will provided to the `store` callbacks as soon as they are ready, and whenever they renew. +Failure to renew will be reported to the `notify` callback. + +You can also retrieve them one-off with `get`. + +```js +gl.add({ + subject: 'example.com', + altnames: ['example.com', 'www.example.com', 'exampleapi.com'] +}); +``` + +| Parameter | Description | +| --------------- | -------------------------------------------------------------------------------------------- | +| subject | the first domain on, and identifier of the certificate | +| altnames | first domain, plus additional domains
note: the order should always be the same | +| subscriberEmail | if different from the default (i.e. multi-tenant, whitelabel) | +| challenges | (same as main config) use if this site needs to use non-default http-01 or dns-01 validation | + +
+ +
+Greenlock#get({ servername }) + +## Greenlock#get() + +**Disclaimer**: This is only intended for testing, demos, and SNICallback +(in [Greenlock Express](https://git.rootprojects.org/root/greenlock-express.js)). + +Greenlock is intended to be left running to allow it to fetech and renew certifictates automatically. + +It is intended that you use the `store` callbacks to new certificates instantly as soon as they renew. +This also protects you from accidentally stampeding the Let's Encrypt API with hundreds (or thousands) +of certificate requests. + +- [Store Callback Documentation](https://git.rootprojects.org/root/greenlock-store-test.js) + +```js +return greenlock.get({ servername }).then(function(site) { + if (!site) { + console.log(servername + ' was not found in any site config'); + return; + } + + var privkey = site.pems.privkey; + var fullchain = site.pems.cert + '\n' + site.pems.chain + '\n'; + console.log(privkey); + console.log(fullchain); +}); +``` + +| Parameter | Description | +| ---------- | ------------------------------------------------------------- | +| servername | any altname listed on the certificate (including the subject) | + +
+ +
+Greenlock#renew({ renewBefore }) + +## Greenlock#renew() + +This will renew only domains that have reached their `renewAt` or are within the befault `renewOffset`. + +**Note**: This runs at regular intervals, multiple times a day, in the background. +You are not required to call it. If you implement the `store` callbacks, the certificates +will automatically be saved (and if you don't implement them, they all get saved to disk). + +```js +return greenlock.renew({}).then(function(results) { + results.forEach(function(site) { + if (site.error) { + console.error(site.subject, site.error); + return; + } + console.log('Renewed certificate for', site.subject, site.altnames); + }); +}); +``` + +| Parameter | Type | Description | +| ----------- | ---- | ------------------------------------------------------------------------------- | +| (optional) | | ALL parameters are optional, but some should be paired | +| force | bool | force silly options, such as tiny durations | +| renewBefore | ms | Check domains that are scheduled to renew before the given date in milliseconds | + + + +
+ + + +# Node + +```bash +npm install --save @root/greenlock +npm install --save greenlock-manager-fs +npm install --save greenlock-store-fs +npm install --save acme-http-01-standalone +``` + + + +# HTTP-01 & DNS-01 Integrations + +For Public Web Servers running on a VPS, the **default HTTP-01 challenge plugin** +will work just fine for most people. + +However, for + +- **Wildcard Certificates** +- **IoT Environments** +- **Enterprise On-Prem** +- **Private Networks** + +Greenlock provides an easy way to integrate Let's Encrypt with your existing services +through a variety of **DNS-01** infrastructure + +Why +Typically file propagation is faster and more reliably than DNS propagation. +Therefore, http-01 will be preferred to dns-01 except when wildcards or **private domains** are in use. + +http-01 will only be supplied as a defaut if no other challenge is provided. + +You can use ACME (Let's Encrypt) with several ready-made integrations + +# Ready-made Integrations + +Greenlock Express integrates between Let's Encrypt's ACME Challenges and many popular services. + +| Type | Service | Plugin | +| ----------- | ----------------------------------------------------------------------------------- | ------------------------ | +| dns-01 | CloudFlare | acme-dns-01-cloudflare | +| dns-01 | [Digital Ocean](https://git.rootprojects.org/root/acme-dns-01-digitalocean.js) | acme-dns-01-digitalocean | +| dns-01 | [DNSimple](https://git.rootprojects.org/root/acme-dns-01-dnsimple.js) | acme-dns-01-dnsimple | +| dns-01 | [DuckDNS](https://git.rootprojects.org/root/acme-dns-01-duckdns.js) | acme-dns-01-duckdns | +| http-01 | File System / [Web Root](https://git.rootprojects.org/root/acme-http-01-webroot.js) | acme-http-01-webroot | +| dns-01 | [GoDaddy](https://git.rootprojects.org/root/acme-dns-01-godaddy.js) | acme-dns-01-godaddy | +| dns-01 | [Gandi](https://git.rootprojects.org/root/acme-dns-01-gandi.js) | acme-dns-01-gandi | +| dns-01 | [NameCheap](https://git.rootprojects.org/root/acme-dns-01-namecheap.js) | acme-dns-01-namecheap | +| dns-01 | [Name.com](https://git.rootprojects.org/root/acme-dns-01-namedotcom.js) | acme-dns-01-namedotcom | +| dns-01 | Route53 (AWS) | acme-dns-01-route53 | +| http-01 | S3 (AWS, Digital Ocean, Scaleway) | acme-http-01-s3 | +| dns-01 | [Vultr](https://git.rootprojects.org/root/acme-dns-01-vultr.js) | acme-dns-01-vultr | +| dns-01 | [Build your own](https://git.rootprojects.org/root/acme-dns-01-test.js) | acme-dns-01-test | +| http-01 | [Build your own](https://git.rootprojects.org/root/acme-http-01-test.js) | acme-http-01-test | +| tls-alpn-01 | [Contact us](mailto:support@therootcompany.com) | - | + +Search `acme-http-01-` or `acme-dns-01-` on npm to find more. + # Easy to Customize @@ -195,294 +485,7 @@ each domain before authorizing a certificate. -# JavaScript API - - -
-Greenlock.create({ packageAgent, maintainerEmail, staging }) - -### Greenlock.create() - -Creates an instance of greenlock with _environment_-level values. - -```js - -var pkg = require('./package.json'); -var gl = Greenlock.create({ - // Staging for testing environments - staging: true, - - // This should be the contact who receives critical bug and security notifications - // Optionally, you may receive other (very few) updates, such as important new features - maintainerEmail: 'jon@example.com', - // for an RFC 8555 / RFC 7231 ACME client user agent - packageAgent: pkg.name + '/' pkg.version -}); -``` - -| Parameter | Description | -| --------------- | ------------------------------------------------------------------------------------ | -| maintainerEmail | the developer contact for critical bug and security notifications | -| packageAgent | if you publish your package for others to use, `require('./package.json').name` here | -| staging | use the Let's Encrypt staging URL instead of the production URL | -| directoryUrl | for use with other (not Let's Encrypt) ACME services, and the Pebble test server | - - - -
- -
-Greenlock#manager.defaults() - -# Greenlock#manager.defaults() - -Acts as a getter when given no arguments. - -Otherwise sets default, site-wide values as described below. - -```js -greenlock.manager.defaults({ - // The "Let's Encrypt Subscriber" (often the same as the maintainer) - // NOT the end customer (except where that is also the maintainer) - subscriberEmail: 'jon@example.com', - agreeToTerms: true - challenges: { - "http-01": { - module: "acme-http-01-webroot", - webroot: "/path/to/webroot" - } - } -}); -``` - -| Parameter | Description | -| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | -| agreeToTerms | (default: false) either 'true' or a function that presents the Terms of Service and returns it once accepted | -| challenges['http-01'] | provide an http-01 challenge module | -| challenges['dns-01'] | provide a dns-01 challenge module | -| challenges['tls-alpn-01'] | provide a tls-alpn-01 challenge module | -| challenges[type].module | the name of your challenge module | -| challenges[type].xxxx | module-specific options | -| servername | the default servername to use for non-sni requests (many IoT clients) | -| subscriberEmail | the contact who agrees to the Let's Encrypt Subscriber Agreement and the Greenlock Terms of Service
this contact receives renewal failure notifications | -| store | override the default storage module | -| store.module | the name of your storage module | -| store.xxxx | options specific to your storage module | - - - -
- -
-Greenlock#add({ subject, altnames }) - -# Greenlock#add() - -Greenlock is a **Management Environment**. - -Once you add a "site", it will begin to automatically renew, immediately. - -The certificates will provided to the `store` callbacks as soon as they are ready, and whenever they renew. -Failure to renew will be reported to the `notify` callback. - -You can also retrieve them one-off with `get`. - -```js -gl.add({ - subject: 'example.com', - altnames: ['example.com', 'www.example.com', 'exampleapi.com'] -}); -``` - -| Parameter | Description | -| --------------- | -------------------------------------------------------------------------------------------- | -| subject | the first domain on, and identifier of the certificate | -| altnames | first domain, plus additional domains
note: the order should always be the same | -| subscriberEmail | if different from the default (i.e. multi-tenant, whitelabel) | -| challenges | (same as main config) use if this site needs to use non-default http-01 or dns-01 validation | - -
- -
-Greenlock#get({ servername }) - -# Greenlock#get() - -**Disclaimer**: This is only intended for testing, demos, and SNICallback -(in [Greenlock Express](https://git.rootprojects.org/root/greenlock-express.js)). - -Greenlock is intended to be left running to allow it to fetech and renew certifictates automatically. - -It is intended that you use the `store` callbacks to new certificates instantly as soon as they renew. -This also protects you from accidentally stampeding the Let's Encrypt API with hundreds (or thousands) -of certificate requests. - -- [Store Callback Documentation](https://git.rootprojects.org/root/greenlock-store-test.js) - -```js -return greenlock.get({ servername }).then(function(site) { - if (!site) { - console.log(servername + ' was not found in any site config'); - return; - } - - var privkey = site.pems.privkey; - var fullchain = site.pems.cert + '\n' + site.pems.chain + '\n'; - console.log(privkey); - console.log(fullchain); -}); -``` - -| Parameter | Description | -| ---------- | ------------------------------------------------------------- | -| servername | any altname listed on the certificate (including the subject) | - -
- -
-Greenlock#renew() - -# Greenlock#renew() - -This will renew only domains that have reached their `renewAt` or are within the befault `renewOffset`. - -**Note**: This runs at regular intervals, multiple times a day, in the background. -You are not required to call it. If you implement the `store` callbacks, the certificates -will automatically be saved (and if you don't implement them, they all get saved to disk). - -```js -return greenlock.renew({}).then(function(results) { - results.forEach(function(site) { - if (site.error) { - console.error(site.subject, site.error); - return; - } - console.log('Renewed certificate for', site.subject, site.altnames); - }); -}); -``` - -| Parameter | Type | Description | -| ----------- | ---- | ------------------------------------------------------------------------------- | -| (optional) | | ALL parameters are optional, but some should be paired | -| force | bool | force silly options, such as tiny durations | -| renewBefore | ms | Check domains that are scheduled to renew before the given date in milliseconds | - - - - - -# Node - -```bash -npm install --save @root/greenlock -npm install --save greenlock-manager-fs -npm install --save greenlock-store-fs -npm install --save acme-http-01-standalone -``` - - - -# HTTP-01 & DNS-01 Integrations - -For Public Web Servers running on a VPS, the **default HTTP-01 challenge plugin** -will work just fine for most people. - -However, for - -- **Wildcard Certificates** -- **IoT Environments** -- **Enterprise On-Prem** -- **Private Networks** - -Greenlock provides an easy way to integrate Let's Encrypt with your existing services -through a variety of **DNS-01** infrastructure - -Why -Typically file propagation is faster and more reliably than DNS propagation. -Therefore, http-01 will be preferred to dns-01 except when wildcards or **private domains** are in use. - -http-01 will only be supplied as a defaut if no other challenge is provided. - -You can use ACME (Let's Encrypt) with several ready-made integrations - -# Ready-made Integrations - -Greenlock Express integrates between Let's Encrypt's ACME Challenges and many popular services. - -| Type | Service | Plugin | -| ----------- | ----------------------------------------------------------------------------------- | ------------------------ | -| dns-01 | CloudFlare | acme-dns-01-cloudflare | -| dns-01 | [Digital Ocean](https://git.rootprojects.org/root/acme-dns-01-digitalocean.js) | acme-dns-01-digitalocean | -| dns-01 | [DNSimple](https://git.rootprojects.org/root/acme-dns-01-dnsimple.js) | acme-dns-01-dnsimple | -| dns-01 | [DuckDNS](https://git.rootprojects.org/root/acme-dns-01-duckdns.js) | acme-dns-01-duckdns | -| http-01 | File System / [Web Root](https://git.rootprojects.org/root/acme-http-01-webroot.js) | acme-http-01-webroot | -| dns-01 | [GoDaddy](https://git.rootprojects.org/root/acme-dns-01-godaddy.js) | acme-dns-01-godaddy | -| dns-01 | [Gandi](https://git.rootprojects.org/root/acme-dns-01-gandi.js) | acme-dns-01-gandi | -| dns-01 | [NameCheap](https://git.rootprojects.org/root/acme-dns-01-namecheap.js) | acme-dns-01-namecheap | -| dns-01 | [Name.com](https://git.rootprojects.org/root/acme-dns-01-namedotcom.js) | acme-dns-01-namedotcom | -| dns-01 | Route53 (AWS) | acme-dns-01-route53 | -| http-01 | S3 (AWS, Digital Ocean, Scaleway) | acme-http-01-s3 | -| dns-01 | [Vultr](https://git.rootprojects.org/root/acme-dns-01-vultr.js) | acme-dns-01-vultr | -| dns-01 | [Build your own](https://git.rootprojects.org/root/acme-dns-01-test.js) | acme-dns-01-test | -| http-01 | [Build your own](https://git.rootprojects.org/root/acme-http-01-test.js) | acme-http-01-test | -| tls-alpn-01 | [Contact us](mailto:support@therootcompany.com) | - | - -Search `acme-http-01-` or `acme-dns-01-` on npm to find more. # Commercial Support