9.6 KiB
@root/greenlock
🔐 Free SSL, Free Wildcard SSL, and Fully Automated HTTPS for Node.js and Browsers, issued by Let's Encrypt v2 via ACME
Greenlock™ is the easiest way to integrate Let's Encrypt into your projects, products, and infrastructure.
- Wildcard Certificates
- IoT Environments
- Enterprise and On-Prem
- Private Networks
- Localhost Development
- Web Hosting Providers
- Commercial support
We've built it simple enough for Hobbyists, and robust enough for the Enterprise.
JavaScript Library
Greenlock API (shared among JS implementations)
Instantiate
// Creates an instance of greenlock with certain default values
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'
});
| 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 |
Add Approved Domains
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
});
| 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 |
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) |
| agreeToTerms | if subscriber is different from the default |
Issue and Renew Certificates
This will renew only domains that have reached their renewAt or are within the befault renewOffset.
return greenlock.renew().then(function(results) {
results.forEach(function(site) {
if (site.error) {
console.error(site.subject, site.error);
return;
}
});
});
| Parameter | Type | Description |
|---|---|---|
| (optional) | ALL parameters are optional, but some should be paired | |
| force | bool | force silly options, such as tiny durations |
| duplicate | bool | force the domain to renew, regardless of age or expiration |
| issuedBefore | ms | Check domains issued before the given date in milliseconds |
| expiresBefore | ms | Check domains that expire before the given date in milliseconds |
| renewBefore | ms | Check domains that are scheduled to renew before the given date in milliseconds |
Note: only previous approved domains (via gl.add()) may be renewed
Note: this will NOT throw an error. It will return an array of certifates or errors.
More
TODO
Node.js
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
- DNS-01 Challenges
- HTTP-01 Challenges
- In-Memory (Standalone)
- FileSystem (WebRoot)
- S3 (AWS, Digital Ocean, etc)
- TLS-ALPN-01 Challenges
- Contact us to learn about Greenlock Pro