NAME

       cdist-type__letsencrypt_cert - Get an SSL certificate from Let's Encrypt

DESCRIPTION

       Automatically obtain a Let's Encrypt SSL certificate using Certbot.

       This  type  attempts to setup automatic renewals always. In many Linux distributions, that
       is         the         case         out         of         the          box,          see:
       https://certbot.eff.org/docs/using.html#automated-renewals

       For  Alpine  Linux  and  Arch Linux, we setup a system-wide cronjob that attempts to renew
       certificates daily.

       If you are using FreeBSD, we configure periodic(8) as recommended by the  port  mantainer,
       so there will be a weekly attempt at renewal.

       If  your  OS  is  not  mentioned here or on Certbot's docs as having support for automated
       renewals, please make sure you  check  your  OS  and  possibly  patch  this  type  so  the
       system-wide cronjob is installed.

REQUIRED PARAMETERS

       object id
              A cert name. If domain parameter is not specified then it is used as a domain to be
              included in the certificate.

       admin-email
              Where to send Let's Encrypt emails like "certificate needs renewal".

OPTIONAL PARAMETERS

       state  'present' or 'absent', defaults to 'present' where:

              present
                     if the certificate does not exist, it will be obtained

              absent the certificate will be removed

       webroot
              The path to your webroot, as set up in your webserver config. If this parameter  is
              not present, Certbot will be run in standalone mode.

OPTIONAL MULTIPLE PARAMETERS

       domain Domains  to  be  included  in the certificate. When specified then object id is not
              used as a domain.

       deploy-hook
              Command to be executed only when the certificate associated with this  $__object_id
              is  issued  or  renewed.   You  can specify it multiple times, but any failure will
              prevent further commands from being executed.

              For this command, the shell variable $RENEWED_LINEAGE will point to the config live
              subdirectory (for example, /etc/letsencrypt/live/${__object_id}) containing the new
              certificates  and  keys;  the  shell  variable  $RENEWED_DOMAINS  will  contain   a
              space-delimited  list  of  renewed  certificate  domains  (for example, example.com
              www.example.com)

       pre-hook
              Command to be run in a shell before obtaining any certificates.  You can specify it
              multiple times, but any failure will prevent further commands from being executed.

              Note these run regardless of which certificate is attempted, you may want to manage
              these system-wide hooks with __file in /etc/letsencrypt/renewal-hooks/pre/.

              Intended primarily for renewal, where it can be used to  temporarily  shut  down  a
              webserver  that might conflict with the standalone plugin. This will only be called
              if a certificate is actually to be obtained/renewed.

       post-hook
              Command to be run in a shell after attempting to  obtain/renew  certificates.   You
              can  specify  it multiple times, but any failure will prevent further commands from
              being executed.

              Note these run regardless of which certificate  was  attempted,  you  may  want  to
              manage these system-wide hooks with __file in /etc/letsencrypt/renewal-hooks/post/.

              Can  be  used  to  deploy renewed certificates, or to restart any servers that were
              stopped by --pre-hook. This is only run if an attempt was made  to  obtain/renew  a
              certificate.

BOOLEAN PARAMETERS

       staging
              Obtain a test certificate from a staging server.

MESSAGES

       change Certificate was changed.

       create Certificate was created.

       remove Certificate was removed.

EXAMPLES

          # use object id as domain
          __letsencrypt_cert example.com \
              --admin-email root@example.com \
              --deploy-hook "service nginx reload" \
              --webroot /data/letsencrypt/root

          # domain parameter is specified so object id is not used as domain
          # and example.com needs to be included again with domain parameter
          __letsencrypt_cert example.com \
              --admin-email root@example.com \
              --domain example.com \
              --domain foo.example.com \
              --domain bar.example.com \
              --deploy-hook "service nginx reload" \
              --webroot /data/letsencrypt/root

AUTHORS

       Nico Schottelius <nico-cdist--@--schottelius.org>
       Kamila Součková <kamila--@--ksp.sk>
       Darko Poljak <darko.poljak--@--gmail.com>
       Ľubomír Kučera <lubomir.kucera.jr at gmail.com>
       Evilham <contact@evilham.com>

COPYING

       Copyright  (C)  2017-2021  Nico  Schottelius,  Kamila  Součková,  Darko Poljak and Ľubomír
       Kučera. You can redistribute it and/or modify it under the terms of the GNU General Public
       License  as published by the Free Software Foundation, either version 3 of the License, or
       (at your option) any later version.

COPYRIGHT

       ungleich GmbH 2021