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


Installation & configuration of the Let's Encrypt client can for example be done using


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.

salt.modules.acme.cert(name, aliases=None, email=None, webroot=None, test_cert=False, renew=None, keysize=None, server=None, owner='root', group='root', certname=None)

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

  • 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 private key
  • group -- group of private key
  • certname -- Name of the certificate to save

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

CLI example:

salt '' acme.cert "[]" test_cert=True renew=14 webroot=/opt/gitlab/embedded/service/gitlab-rails/public

Return a list of active certificates

CLI example:

salt '' acme.certs

The expiry date of a certificate in ISO format

Parameters:name -- CommonName of cert

CLI example:

salt '' acme.expires

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

Parameters:name -- CommonName of cert

Code example:

if __salt__['acme.has'](''):'That is one nice certificate you have there!')

Return information about a certificate


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

Parameters:name -- CommonName of cert

CLI example:

salt ''
salt.modules.acme.needs_renewal(name, window=None)

Check if a certificate needs renewal

  • 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'](''):
    __salt__['acme.cert']('', **kwargs)
else:'Your certificate is still good')
salt.modules.acme.renew_by(name, window=None)

Date in ISO format when a certificate should first be renewed

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