# salt.modules.acme

## ACME / Let's Encrypt module

Added in version 2016.3.0.

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, manual_auth_hook=None, manual_cleanup_hook=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' or 'digitalocean')

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

    - dns_plugin_propagate_seconds -- Number of seconds to wait for DNS propogations before asking ACME servers to verify the DNS record. (default 10)

    - manual_auth_hook -- Path to the manual authentication hook script.

    - manual_cleanup_hook -- Path to the manual cleanup or post-authentication hook script.

  Return type:

    dict

  Returns:

    Dictionary 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 (str) -- Name of certificate

  Return type:

    str

  Returns:

    Expiry date in ISO format.

  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 (str) -- Name of certificate

  Return type:

    bool

  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

  Parameters:

    name (str) -- Name of certificate

  Return type:

    dict

  Returns:

    Dictionary with information about the certificate. If neither the `tls` nor the `x509` module can be used to determine the certificate information, the information will be retrieved as one big text block under the key `text` using the openssl cli.

  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 (str) -- Name of certificate

    - window (bool/str/int) -- Window in days to renew earlier or True/force to just return True

  Return type:

    bool

  Returns:

    Whether or not the certificate needs to be renewed.

  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 (str) -- Name of certificate

    - window (int) -- number of days before expiry when renewal should take place

  Return type:

    str

  Returns:

    Date of certificate renewal in ISO format.