cookbook 'acme', '= 2.0.0'
acme (11) Versions 2.0.0 Follow37
ACME client cookbook for free and trusted SSL/TLS certificates from Let's Encrypt
cookbook 'acme', '= 2.0.0', :supermarket
knife supermarket install acme
knife supermarket download acme
ACME cookbook
Automatically get/renew free and trusted certificates from Let's Encrypt (letsencrypt.org).
ACME is the Automated Certificate Management Environment protocol used by Let's Encrypt.
Attributes
default
-
node['acme']['contact']
- Contact information, default empty. Set tomailto:your@email.com
. -
node['acme']['endpoint']
- ACME server endpoint, defaulthttps://acme-v01.api.letsencrypt.org
. Set tohttps://acme-staging.api.letsencrypt.org
if you want to use the Let's Encrypt staging environment and corresponding certificates. -
node['acme']['renew']
- Days before the certificate expires at which the certificate will be renewed, default30
. -
node['acme']['source_ips']
- IP addresses used by Let's Encrypt to verify the TLS certificates, it will change over time. This attribute is for firewall purposes. Allow these IPs for HTTP (tcp/80). -
node['acme']['private_key']
- Private key content of registered account.
Recipes
default
Installs the required acme-client rubygem.
Usage
Use the acme_certificate
provider to request a certificate. The webserver for the domain for which you are requesting a certificate must be running on the local server. Currently only the http validation method is supported. Provide the path to your wwwroot
for the specified domain.
acme_certificate 'test.example.com' do crt '/etc/ssl/test.example.com.crt' key '/etc/ssl/test.example.com.key' method 'http' wwwroot '/var/www' end
In case your webserver needs an already existing certificate when installing a new server you will have a bootstrap problem. Webserver cannot start without certificate, but the certificate cannot be requested without the running webserver. To overcome this a self-signed certificate can be generated with the acme_selfsigned
provider.
acme_selfsigned 'test.example.com' do crt '/etc/ssl/test.example.com.crt' key '/etc/ssl/test.example.com.key' end
A working example can be found in the included acme_client
test cookbook.
Providers
certificate
Property | Type | Default | Description |
---|---|---|---|
cn |
string | name | The common name for the certificate |
alt_names |
array | [] | The common name for the certificate |
crt |
string | nil | File path to place the certificate |
key |
string | nil | File path to place the private key |
chain |
string | nil | File path to place the certificate chain |
fullchain |
string | nil | File path to place the certificate including the chain |
owner |
string | root | Owner of the created files |
group |
string | root | Group of the created files |
method |
string | http | Validation method |
wwwroot |
string | /var/www | Path to the wwwroot of the domain |
ignore_failure |
boolean | false | Whether to continue chef run if issuance fails |
retries |
integer | 0 | Number of times to catch exceptions and retry |
retry_delay |
integer | 2 | Number of seconds to wait between retries |
selfsigned
Property | Type | Default | Description |
---|---|---|---|
cn |
string | name | The common name for the certificate |
crt |
string | nil | File path to place the certificate |
key |
string | nil | File path to place the private key |
chain |
string | nil | File path to place the certificate chain |
owner |
string | root | Owner of the created files |
group |
string | root | Group of the created files |
Example
To generate a certificate for an apache2 website you can use code like this:
# Include the recipe to install the gems
include_recipe 'acme'
# Set up contact information. Note the mailto: notation
node.set['acme']['contact'] = [ 'mailto:me@example.com' ]
# Real certificates please...
node.set['acme']['endpoint'] = 'https://acme-v01.api.letsencrypt.org'
site="example.com"
sans=Array[ "www.#{site}" ]
# Set up your server here...
# Generate a self-signed if we don't have a cert to prevent bootstrap problems
acme_selfsigned "#{site}" do
crt "/etc/httpd/ssl/#{site}.crt"
key "/etc/httpd/ssl/#{site}.key"
chain "/etc/httpd/ssl/#{site}.pem"
owner "apache"
group "apache"
notifies :restart, "service[apache2]", :immediate
not_if do
# Only generate a self-signed cert if needed
::File.exists?("/etc/httpd/ssl/#{site}.crt")
end
end
# Get and auto-renew the certificate from Let's Encrypt
acme_certificate "#{site}" do
crt "/etc/httpd/ssl/#{site}.crt"
key "/etc/httpd/ssl/#{site}.key"
chain "/etc/httpd/ssl/#{site}.pem"
method "http"
wwwroot "/var/www/#{site}/htdocs/"
notifies :restart, "service[apache2]"
alt_names sans
end
Testing
The kitchen includes a boulder
server to run the integration tests with, so testing can run locally without interaction with the online API's.
Contributing
- Fork the repository on Github
- Create a named feature branch (like
add_component_x
) - Write your change
- Write tests for your change (if applicable)
- Run the tests, ensuring they all pass
- Submit a Pull Request using Github
License and Authors
Authors: Thijs Houtenbos thoutenbos@schubergphilis.com
Credits
Let’s Encrypt is a trademark of the Internet Security Research Group. All rights reserved.
Dependent cookbooks
This cookbook has no specified dependencies.
Contingent cookbooks
ACME Cookbook Changelog
This file is used to list changes made in each version of the acme cookbook.
2.0.0
- thoutenbos - Rename from
letsencrypt
toacme
to comply with the ISRG trademark policy - arr-dev - Add ChefSpec matchers
1.0.3
- chr4 - Bump versions of json-jwt and acme-client
- thoutenbos - Upgrade acme-client to drop dependencies
1.0.2
- miguelaferreira - Wrap test cookbooks in :integration group
1.0.1
- thoutenbos - Work around gem dependency problems
- thoutenbos - Rubocop fixes
- thoutenbos - Improve the example
1.0.0
- seccubus - Make production the default end-point
- seccubus - Add apache2 example
- thoutenbos - Fix for chef-client v11 compatibility
- thoutenbos - Fix integration tests
0.1.7
- glaszig - Use chef api inside ruby_block
- arr-dev - Document
node['letsencrypt']['private_key']
0.1.6
- funzoneq - Add verification IP for firewalling purposes
- acoulton - fail chef run if certificate not issued, unless
ignore_failure
resource attribute set
0.1.5
- thoutenbos - fix selfsigned chain
0.1.4
- patcon - spin-off the boulder test cookbook
- patcon - add Ubuntu support
- thoutenbos - various improvements
0.1.3
- sawanoboly - Add SAN support
0.1.2
- obazoud - Improved logging
- thoutenbos - Add Kitchen CI
- thoutenbos - Fix key/cert creation order issue
0.1.1
- Thijs Houtenbos - Added
chain
andfullchain
properties
0.1.0
- Thijs Houtenbos - Initial release
Check the Markdown Syntax Guide for help with Markdown.
The Github Flavored Markdown page describes the differences between markdown on github and standard markdown.
Collaborator Number Metric
2.0.0 failed this metric
Failure: Cookbook has 0 collaborators. A cookbook must have at least 2 collaborators to pass this metric.
Contributing File Metric
2.0.0 failed this metric
Failure: To pass this metric, your cookbook metadata must include a source url, the source url must be in the form of http://github.com/user/repo, and your repo must contain a CONTRIBUTING.md file
Foodcritic Metric
2.0.0 failed this metric
FC066: Ensure chef_version is set in metadata: acme/metadata.rb:1
FC067: Ensure at least one platform supported in metadata: acme/metadata.rb:1
FC069: Ensure standardized license defined in metadata: acme/metadata.rb:1
Run with Foodcritic Version 10.3.1 with tags metadata,correctness ~FC031 ~FC045 and failure tags any
License Metric
2.0.0 failed this metric
acme does not have a valid open source license.
Acceptable licenses include Apache-2.0, apachev2, Apache 2.0, MIT, mit, GPL-2.0, gplv2, GNU Public License 2.0, GPL-3.0, gplv3, GNU Public License 3.0.
No Binaries Metric
2.0.0 passed this metric
Testing File Metric
2.0.0 failed this metric
Failure: To pass this metric, your cookbook metadata must include a source url, the source url must be in the form of http://github.com/user/repo, and your repo must contain a TESTING.md file
Version Tag Metric
2.0.0 passed this metric
2.0.0 failed this metric
2.0.0 failed this metric
Failure: To pass this metric, your cookbook metadata must include a source url, the source url must be in the form of http://github.com/user/repo, and your repo must contain a CONTRIBUTING.md file
Foodcritic Metric
2.0.0 failed this metric
FC066: Ensure chef_version is set in metadata: acme/metadata.rb:1
FC067: Ensure at least one platform supported in metadata: acme/metadata.rb:1
FC069: Ensure standardized license defined in metadata: acme/metadata.rb:1
Run with Foodcritic Version 10.3.1 with tags metadata,correctness ~FC031 ~FC045 and failure tags any
License Metric
2.0.0 failed this metric
acme does not have a valid open source license.
Acceptable licenses include Apache-2.0, apachev2, Apache 2.0, MIT, mit, GPL-2.0, gplv2, GNU Public License 2.0, GPL-3.0, gplv3, GNU Public License 3.0.
No Binaries Metric
2.0.0 passed this metric
Testing File Metric
2.0.0 failed this metric
Failure: To pass this metric, your cookbook metadata must include a source url, the source url must be in the form of http://github.com/user/repo, and your repo must contain a TESTING.md file
Version Tag Metric
2.0.0 passed this metric
2.0.0 failed this metric
FC067: Ensure at least one platform supported in metadata: acme/metadata.rb:1
FC069: Ensure standardized license defined in metadata: acme/metadata.rb:1
Run with Foodcritic Version 10.3.1 with tags metadata,correctness ~FC031 ~FC045 and failure tags any
2.0.0 failed this metric
acme does not have a valid open source license.
Acceptable licenses include Apache-2.0, apachev2, Apache 2.0, MIT, mit, GPL-2.0, gplv2, GNU Public License 2.0, GPL-3.0, gplv3, GNU Public License 3.0.
No Binaries Metric
2.0.0 passed this metric
Testing File Metric
2.0.0 failed this metric
Failure: To pass this metric, your cookbook metadata must include a source url, the source url must be in the form of http://github.com/user/repo, and your repo must contain a TESTING.md file
Version Tag Metric
2.0.0 passed this metric
2.0.0 passed this metric
2.0.0 failed this metric
Failure: To pass this metric, your cookbook metadata must include a source url, the source url must be in the form of http://github.com/user/repo, and your repo must contain a TESTING.md file
Version Tag Metric
2.0.0 passed this metric
2.0.0 passed this metric