Acme Setup

This is an Ansible role for setting up everything needed to sign certificates with Let's Encrypt. It installs the necessary user, directories, scripts, and sets the right permissions.

This role should be run on any server that needs certificates for itself or signs them for other servers.

For generating the private key and certificate requests, check out inofix.acme-request, as well as the installation of a remotely created request on a "signing" or "certificate-proxy" server.

The inofix.acme-tiny-install role installs the acme-tiny script on signing servers.

The inofix.acme-tiny-sign and inofix.acme-tiny-cron roles are responsible for signing certificates (immediately or periodically) on signing servers.

Any server signing certificates with Let's Encrypt needs a web server listening on port 80 and resolving /.well-known/acme-challenge to the directory accessible by the signing tool. For examples, see inofix.acme-sign.

Servers that rely on others for signing (for example, those without a web service) can use inofix.acme-proxy to access and transfer signed certificates from their proxy server.

Check the "Overview / Concept" section below for more details.

This role's development began as zwischenloesung.acme-tiny-setup.

Why not use existing roles?

1. We need something reliable—see the "Promise" section below for details.
2. This role will be used by maestro and must align with its logic. (Of course, it can be used independently of maestro.)

State

• preSTABLE (Feature-Freeze/RC)

Promise

This role may change in the future, but we will only add features to maintain backwards compatibility. If major changes are required, a new role will be created, likely with a version suffix.

Installation

To install, run:

# ansible-galaxy install inofix.acme-setup

Requirements

• Ansible >2.0
• Python 2/3 on the target host
• Generic UNIX with FHS
• Sudo
• Systemd (by default)

Overview / Concept

This role is central and needed on any involved server. Here’s the overview:

Role Perspective

• inofix.acme-setup
  • Run on any server
  • Set up the environment:
    • Create user ‘acme’
    • Create keys, etc.:
      • /etc/ssl/acme
        • scripts
        • connected services
      • /var/log/acme
        • logs
      • /var/lib/acme
        • home for signing user and certificate copies
• inofix.acme-request
  • Run on servers using or signing a certificate:
    • On servers using a certificate:
      • Generate a private key
      • Create a certificate request (CSR)
    • On proxy servers:
      • Install the CSR from "offline" servers
• inofix.acme-tiny-install
  • Run on servers signing certificates with Let's Encrypt:
    • Install the acme-tiny.py script
• inofix.acme-tiny-sign
  • Run on servers signing certificates with Let's Encrypt:
    • Only requires the CSR; the private key is not even needed (or absent for proxies)
    • Use acme-tiny.py to request Let's Encrypt to sign the CSR
• inofix.acme-tiny-cron
  • Run on servers signing certificates:
    • Only requires the CSR; the private key is not needed (or absent for proxies)
    • Set up a cron job to handle signing (like in inofix.acme-tiny-sign)
• inofix.acme-proxy
  • Run on servers using a certificate but not signing themselves (e.g., mail/jabber).
  • Copy the certificate from a remote signing host.
• inofix.acme-service-...
  • Run on all servers using a certificate (i.e., running a certified service).
  • Register to restart the service if any certificate has changed.

Host Perspective

• A signing host that doesn’t use the certificates directly will need to run:
  • inofix.acme-setup (this role)
  • inofix.acme-tiny-install
  • inofix.acme-tiny-sign
  • inofix.acme-tiny-cron (for monthly auto-signing)
• A host that only uses certificates without directly requesting signing will need to run:
  • inofix.acme-setup (this role)
  • inofix.acme-request
  • inofix.acme-proxy (to automatically get certificates)
  • inofix.acme-service-<service> (to restart if certificate changes)
• A host running both signing and a service will require:
  • inofix.acme-setup (this role)
  • inofix.acme-tiny-install
  • inofix.acme-request
  • inofix.acme-tiny-sign
  • inofix.acme-tiny-cron (for monthly auto-signing)
  • inofix.acme-service-<service> (to restart if certificate changes)

Role Variables

• app__acme__user: optional, default='acme'
• app__acme__group: optional, default='acme'
• app__acme__home: optional, default='/var/lib/acme'
• app__acme__config_dir: optional, default='/etc/ssl/acme'
• app__acme__openssl_config: optional, default='/etc/ssl/openssl.cnf'
• app__acme__challenge_dir: optional, default='/var/www/acme-challenges'
• app__acme__scripts_dir: optional, default='/etc/ssl/acme/scripts'
• app__acme__service_dir: optional, default='/etc/ssl/acme/service.d'
• app__acme__bin_dir: optional, default='/usr/local/bin'
• app__acme__account_key: optional, default='account.key'
• app__acme__key_length: optional, default=4096
• app__acme__ssh_keytype: optional, default='rsa'
• app__acme__log_dir: optional, default='/var/log/acme'
• app__acme__letsencrypt_certs: optional, default=[{url='https://letsencrypt.org/certs/lets-encrypt-x3-cross-signed.pem', file='intermediate.crt'}, {url='https://letsencrypt.org/certs/isrgrootx1.pem', file='ca.crt'}]
• app__acme__cron_minute: optional, default='11'
• app__acme__cron_hour: optional, default='5'
• app__acme__cron_day: optional, default='*'
• app__acme__cron_month: optional, default='*'
• app__acme__cron_year: optional, default='*'
• fqdn: optional, default={{ ansible_fqdn | d(inventory_hostname) }}
• workdir: optional, default=/tmp (local directory for ssh pub-key exchange)

Dependencies

(Include any dependencies here)

Example Playbook

To use this role, include it in a playbook:

- hosts: servers
  roles:
    - inofix.acme-setup

For a complete playbook with all relevant roles included, see: setup-lets-encrypt.yml.

License

GPLv3

Author Information

• Michael Lustenberger at inofix.ch