salt.modules.acme¶

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.