cdist-type__letsencrypt_cert(7)
===============================


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
--------

.. code-block:: sh

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

.. code-block:: sh

    # 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.