Forge Home

letsencrypt

Let's Encrypt

9,075 downloads

9,075 latest version

4.0 quality score

We run a couple of automated
scans to help you access a
module's quality. Each module is
given a score based on how well
the author has formatted their
code and documentation and
modules are also checked for
malware using VirusTotal.

Please note, the information below
is for guidance only and neither of
these methods should be considered
an endorsement by Puppet.

Version information

  • 0.1.0 (latest)
released Dec 4th 2015

Start using this module

  • r10k or Code Manager
  • Bolt
  • Manual installation
  • Direct download

Add this module to your Puppetfile:

mod 'pgassmann-letsencrypt', '0.1.0'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add pgassmann-letsencrypt
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install pgassmann-letsencrypt --version 0.1.0

Direct download is not typically how you would use a Puppet module to manage your infrastructure, but you may want to download the module in order to inspect the code.

Download

Documentation

pgassmann/letsencrypt — version 0.1.0 Dec 4th 2015

letsencrypt

Table of Contents

  1. Overview
  2. Module Description - What the module does and why it is useful
  3. Setup - The basics of getting started with letsencrypt
  4. Usage - Configuration options and additional functionality
  5. Reference - An under-the-hood peek at what the module is doing and how
  6. Limitations - OS compatibility, etc.
  7. Development - Guide for contributing to the module

Overview

The goal of Let's Encrypt is to automate ssl certificates. The tool to automate server configuration is Puppet. This module bridges the two efforts.

WARNING! This module is not ready yet!

Module Description

The goal of this module is to enable ssl on puppet managed resources like nginx_vhosts as simple as possible. The module reuses the domains configured in the vhost server_name

For the authorization, the webroot challenge is used and a custom location is automatically added to the ngninx vhost so that the challenge path is using the letsencrypt webroot. This allows to solve the challenge even if the vhost is just a proxy to another server.

Setup

What letsencrypt affects

WARNING! This module is not ready yet!

TODO

  • A list of files, packages, services, or operations that the module will alter, impact, or execute on the system it's installed on.
  • This is a great place to stick any warnings.
  • Can be in list or paragraph form.

Setup Requirements OPTIONAL

Requests to Port 80 (and 433) of the IPv4 address of the domains to encrypt need to reach your server.

Beginning with letsencrypt

See the following example for encrypting a nginx vhost. This will successfully configure nginx, the vhost and the ssl certificat in one run, if added to a blank Server.

Important: You should declare letsencrypt resources after the nginx resources. The fetching of the configured domains is parse order dependent.

Let's encrypt nginx vhost

class{'nginx':
  nginx_vhosts => {
    'letsencrypt-test1.example.com' => {
          server_name      => [
            'letsencrypt-test1.example.com',
            'letsencrypt-test2.example.com',
          ],
          proxy            => 'http://10.1.2.3',
          ssl              => true,
          rewrite_to_https => true,
          ssl_key          => '/etc/letsencrypt/live/letsencrypt-test1.example.com/privkey.pem',
          ssl_cert         => '/etc/letsencrypt/live/letsencrypt-test1.example.com/fullchain.pem',

    },
  },
}
class { 'letsencrypt':
  email            => 'email@example.com',
  agree_tos        => true
  firstrun_webroot => '/usr/share/nginx/html'
  nginx_vhosts     => {
    'letsencrypt-test1.example.com' => {}
  }
}

To add ssl configuration to an existing installation, you need first to configure the nginx_locations for your default vhost and your existing vhost.

class { 'letsencrypt':
  email            => 'email@example.com',
  agree_tos        => true
  nginx_locations     => {
    'default' => {}
    'letsencrypt-test1.example.com' => {}
  }
}

If this is applied successfully, you can then add the ssl configuration to your nginx vhost as above and declare your letsencrypt::nginx::vhost

Hiera example

classes:
  - nginx
  - letsencrypt

nginx::nginx_vhosts:
  'letsencrypt-test1.example.com':
      server_name:
                            - 'letsencrypt-test1.example.com'
                            - 'letsencrypt-test2.example.com'
      proxy:                'http://10.1.2.3'
      ssl:                  true
      rewrite_to_https:     true
      ssl_key:              '/etc/letsencrypt/live/letsencrypt-test1.example.com/privkey.pem'
      ssl_cert:             '/etc/letsencrypt/live/letsencrypt-test1.example.com/fullchain.pem'

letsencrypt::email: 'email@example.com'
letsencrypt::agree_tos: true
letsencrypt::firstrun_webroot: '/usr/share/nginx/html'
letsencrypt::nginx_vhosts:
  'letsencrypt-test1.example.com': {}

Usage

TODO

Put the classes, types, and resources for customizing, configuring, and doing the fancy stuff with your module here.

Reference

TODO

Here, list the classes, types, providers, facts, etc contained in your module. This section should include all of the under-the-hood workings of your module so people know what the module is touching on their system but don't need to mess with things. (We are working on automating this section!)

Class: letsencrypt

Let's Encrypt base configuration and hiera interface.

Parameters

[email] Required, email-address for registration and key recovery

[agree_tos] Required true, Please read the Terms of Service at https://letsencrypt.org/documents/LE-SA-v1.0.1-July-27-2015.pdf. You must agree in order to register with the ACME server at https://acme-v01.api.letsencrypt.org/directory

[server] ACME Server, defaults to staging instance. For Production use set it to 'https://acme-v01.api.letsencrypt.org/directory'

[webroot] This directory is configured as webroot for the webroot authentication locations added to the vhost to allow renewals

[firstrun_webroot] Use different webroot on first run. Set this to the default webroot of the webserver if the service starts automatically when installed. E.g. Nginx on Ubuntu: /usr/share/nginx/html

[firstrun_standalone] Use standalone mode on first run. Set this to true if the webserver does not start automatically when installed. letsencrypt will use standalone mode to get the certificate before the webserver is started the first time.

[rsa_key_size], [work_dir], [logs_dir], Configruation options for letsencrypt cli.ini

[nginx_locations], [nginx_vhosts], [exec_standalone], [exec_webroot] These Parameters can be used to create instances of these defined types through hiera

Limitations

Currently I only did basic testing on Ubuntu with the above hiera configuration

Development

Run bundle exec rake to execute the spec tests. There are already some basic tests for each class and define, but not all options are covered.

Release Notes

If you aren't using changelog, put your release notes here (though you should consider using changelog). You may also add any additional sections you feel are necessary or important to include here. Please use the ## header.

Contributors

TODO & Planned

  • More Documentation
  • More Testing
  • Other install method
  • Native ruby provider to get certificate? (https://github.com/unixcharles/acme-client)
  • Automatically configure SSL certificate and key on the vhost
  • Renewal management
  • Add Domains to existing Certificates
  • Fix Firstrun mode Success
  • Support for Apache
  • Support for RedHat, CentOS etc.