salt.modules.acme module

ACME / Let's Encrypt module

This module currently looks for certbot script in the $PATH as - certbot, - lestsencrypt, - certbot-auto, - letsencrypt-auto eventually falls back to /opt/letsencrypt/letsencrypt-auto

Note

Installation & configuration of the Let's Encrypt client can for example be done using https://github.com/saltstack-formulas/letsencrypt-formula

Warning

Be sure to set at least accept-tos = True in cli.ini!

Most parameters will fall back to cli.ini defaults if None is given.

DNS plugins

This module currently supports the CloudFlare certbot DNS plugin. The DNS plugin credentials file needs to be passed in using the dns_plugin_credentials argument.

Make sure the appropriate certbot plugin for the wanted DNS provider is installed before using this module.

salt.modules.acme.cert(name, aliases=None, email=None, webroot=None, test_cert=False, renew=None, keysize=None, server=None, owner='root', group='root', mode='0640', certname=None, preferred_challenges=None, tls_sni_01_port=None, tls_sni_01_address=None, http_01_port=None, http_01_address=None, dns_plugin=None, dns_plugin_credentials=None)

Obtain/renew a certificate from an ACME CA, probably Let's Encrypt.

Parameters
  • name -- Common Name of the certificate (DNS name of certificate)

  • aliases -- subjectAltNames (Additional DNS names on certificate)

  • email -- e-mail address for interaction with ACME provider

  • webroot -- True or a full path to use to use webroot. Otherwise use standalone mode

  • test_cert -- Request a certificate from the Happy Hacker Fake CA (mutually exclusive with 'server')

  • renew -- True/'force' to force a renewal, or a window of renewal before expiry in days

  • keysize -- RSA key bits

  • server -- API endpoint to talk to

  • owner -- owner of the private key file

  • group -- group of the private key file

  • mode -- mode of the private key file

  • certname -- Name of the certificate to save

  • preferred_challenges -- A sorted, comma delimited list of the preferred challenge to use during authorization with the most preferred challenge listed first.

  • tls_sni_01_port -- Port used during tls-sni-01 challenge. This only affects the port Certbot listens on. A conforming ACME server will still attempt to connect on port 443.

  • tls_sni_01_address -- The address the server listens to during tls-sni-01 challenge.

  • http_01_port -- Port used in the http-01 challenge. This only affects the port Certbot listens on. A conforming ACME server will still attempt to connect on port 80.

  • https_01_address -- The address the server listens to during http-01 challenge.

  • dns_plugin -- Name of a DNS plugin to use (currently only 'cloudflare')

  • dns_plugin_credentials -- Path to the credentials file if required by the specified DNS plugin

Returns

dict with 'result' True/False/None, 'comment' and certificate's expiry date ('not_after')

CLI example:

salt 'gitlab.example.com' acme.cert dev.example.com "[gitlab.example.com]" test_cert=True renew=14 webroot=/opt/gitlab/embedded/service/gitlab-rails/public
salt.modules.acme.certs()

Return a list of active certificates

CLI example:

salt 'vhost.example.com' acme.certs
salt.modules.acme.expires(name)

The expiry date of a certificate in ISO format

Parameters

name -- CommonName of cert

CLI example:

salt 'gitlab.example.com' acme.expires dev.example.com
salt.modules.acme.has(name)

Test if a certificate is in the Let's Encrypt Live directory

Parameters

name -- CommonName of cert

Code example:

if __salt__['acme.has']('dev.example.com'):
    log.info('That is one nice certificate you have there!')
salt.modules.acme.info(name)

Return information about a certificate

Note

Will output tls.cert_info if that's available, or OpenSSL text if not

Parameters

name -- CommonName of cert

CLI example:

salt 'gitlab.example.com' acme.info dev.example.com
salt.modules.acme.needs_renewal(name, window=None)

Check if a certificate needs renewal

Parameters
  • name -- CommonName of cert

  • window -- Window in days to renew earlier or True/force to just return True

Code example:

if __salt__['acme.needs_renewal']('dev.example.com'):
    __salt__['acme.cert']('dev.example.com', **kwargs)
else:
    log.info('Your certificate is still good')
salt.modules.acme.renew_by(name, window=None)

Date in ISO format when a certificate should first be renewed

Parameters
  • name -- CommonName of cert

  • window -- number of days before expiry when renewal should take place