Adoptable Cookbooks List

Looking for a cookbook to adopt? You can now see a list of cookbooks available for adoption!
List of Adoptable Cookbooks

Supermarket Belongs to the Community

Supermarket belongs to the community. While Chef has the responsibility to keep it running and be stewards of its functionality, what it does and how it works is driven by the community. The chef/supermarket repository will continue to be where development of the Supermarket application takes place. Come be part of shaping the direction of Supermarket by opening issues and pull requests or by joining us on the Chef Mailing List.

Select Badges

Select Supported Platforms

RSS

acme (3) Versions 3.1.0

ACME client cookbook for free and trusted SSL/TLS certificates from Let's Encrypt

Berkshelf/Librarian
Policyfile
Knife
cookbook 'acme', '~> 3.1.0'
cookbook 'acme', '~> 3.1.0', :supermarket
knife cookbook site install acme
knife cookbook site download acme
README
Dependencies
Changelog
Quality 44%

ACME cookbook

Build Status Cookbook Version

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

Attribute Description Default
contact Contact information, default empty. Set to mailto:your@email.com []
endpoint ACME server endpoint, Set to https://acme-staging.api.letsencrypt.org if you want to use the Let's Encrypt staging environment and corresponding certificates. https://acme-v01.api.letsencrypt.org
renew Days before the certificate expires at which the certificate will be renewed 30
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). ['66.133.109.36']
private_key Private key content of registered account. Private keys identify the ACME client with the endpoint and are not transferable between staging and production endpoints. nil
key_size Default private key size used when resource property is not. Must be one out of: 2048, 3072, 4096. 2048

Recipes

default

Installs the required acme-client rubygem.

Usage

Use the acme_certificate resource to request a certificate with the http-01 challange. The webserver for the domain for which you are requesting a certificate must be running on the local server. This resource only supports the http validation method. To use the tls-sni-01 challange, please see the resource below. Provide the path to your wwwroot for the specified domain.

acme_certificate 'test.example.com' do
  crt               '/etc/ssl/test.example.com.crt'
  chain             '/etc/ssl/test.example.com-chain.crt'
  key               '/etc/ssl/test.example.com.key'
  wwwroot           '/var/www'
end

Use the acme_ssl_certificate resource to request a certificate using the tls-sni-01 challange. By default an nginx server is expected to be running on the machine that will be configured to complete the challange. Using a differnet webserver is possible by specifying a different provider for the resource, but by default only the nginx provider is implemented (see libraries/ssl_certificate/nginx.rb on how to port the resource for another webserver).

acme_ssl_certificate '/etc/ssl/test.example.com.crt' do
  cn                'test.example.com'
  alt_names         ['foo.example.com', 'bar.example.com']
  output            :crt # or :fullchain
  key               '/etc/ssl/private/test.example.key.pem'
  min_validity      30 #Renew certificate if expiry is closed than this many days

  webserver         :nginx
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 resource.

acme_selfsigned 'test.example.com' do
  crt     '/etc/ssl/test.example.com.crt'
  chain   '/etc/ssl/test.example.com-chain.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
key_size integer 2048 Private key size. Must be one out of: 2048, 3072, 4096
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
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
key_size integer 2048 Private key size. Must be one out of: 2048, 3072, 4096
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 = ["www.#{site}"]

# 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
end

# Set up your webserver here...

# 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"
  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

  1. Fork the repository on Github
  2. Create a named feature branch (like add_component_x)
  3. Write your change
  4. Write tests for your change (if applicable)
  5. Run the tests, ensuring they all pass
  6. 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

compat_resource >= 12.19

Contingent cookbooks

There are no cookbooks that are contingent upon this one.

ACME Cookbook Changelog

This file is used to list changes made in each version of the acme cookbook.

3.1.0

  • axos88 - Add ssl validation method
  • notapatch - Update README
  • funzoneq - Extra validation server IP
  • faucct - Remove unknown attribute validation 'min'
  • faucct - Make sure nginx reloads
  • wndhydrnt - Update certificate when common name / alternate names change

3.0.0

By changes in Chef 13, the unused property method has been removed from the certificate provider.

  • mattrobenolt - Do not allow a crt without an accompanying chain
  • alex-tan - Improve README
  • rmoriz - Allow setting custom key size
  • szymonpk - Add missing matchers
  • rmoriz - Chef 13 compatibility
  • rmoriz - Multiple CI build improvements

2.0.0

  • thoutenbos - Rename from letsencrypt to acme 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 and fullchain 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
            

3.1.0 failed this metric

Failure: Cookbook has 0 collaborators. A cookbook must have at least 2 collaborators to pass this metric.

Contributing File Metric
            

3.1.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 https://github.com/user/repo, and your repo must contain a CONTRIBUTING.md file

Foodcritic Metric
            

3.1.0 failed this metric

FC058: Library provider declares use_inline_resources and declares #action_ methods: acme/libraries/ssl_certificate.rb:24
FC067: Ensure at least one platform supported in metadata: acme/metadata.rb:1
Run with Foodcritic Version 12.0.1 with tags metadata,correctness ~FC031 ~FC045 and failure tags any

License Metric
            

3.1.0 passed this metric

No Binaries Metric
            

3.1.0 passed this metric

Publish Metric
            

3.1.0 passed this metric

Supported Platforms Metric
            

3.1.0 failed this metric

acme should declare what platform(s) it supports.

Testing File Metric
            

3.1.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 https://github.com/user/repo, and your repo must contain a TESTING.md file

Version Tag Metric
            

3.1.0 passed this metric