CDIST-TYPE__LETSENCRYPT_CERT(7)

💖 cdist-type__letsencrypt_cert — the cdist-type__letsencrypt_cert(7) moment 💖

okay bestie so this is the manual page for cdist-type__letsencrypt_cert(7), section 7, and it's genuinely giving "get your SSL certs sorted and never think about it again" energy ✨

---

🌸 NAME 🌸

cdist-type__letsencrypt_cert — get an SSL certificate from Let's Encrypt. no cap, that's the whole job 🎀

---

🦋 DESCRIPTION 🦋

So basically this type automatically obtains a Let's Encrypt SSL certificate using Certbot. You don't do the whole "openssl genrsa" ritual, it just handles it for you 💅

This type attempts to setup automatic renewals always. Like, always. On many Linux distributions that's already the case out of the box, check here if you wanna see:

https://certbot.eff.org/docs/using.html#automated-renewals

For Alpine Linux and Arch Linux, we set up a system-wide cronjob that tries to renew certificates daily. every day. main character scheduling honestly 🫶

If you're on FreeBSD, we configure periodic(8) exactly as recommended by the port mantainer, so you get a weekly attempt at renewal. one vibe check per week, slay 🌈

⚠️ 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. do not just assume the vibes are immaculate, bestie 😭

---

💜 REQUIRED PARAMETERS 💜

You literally cannot skip these, they're required, periodt.

• object id — a cert name. If the domain parameter is not specified then it is used as a domain to be included in the certificate. so it's the name and sometimes the domain, it's multitasking 💅
• admin-email — where to send Let's Encrypt emails like "certificate needs renewal". yes they email you, it's giving "your subscription is expiring" but make it TLS 📧

---

✨ OPTIONAL PARAMETERS ✨

These are the "you can but you don't have to" girlies.

• 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. bye bestie 👋
• 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. so either you point it at your webroot or it does its own thing 🦋

---

🌈 OPTIONAL MULTIPLE PARAMETERS 🌈

These ones you can pass more than once. iconic behavior tbh.

• domain — domains to be included in the certificate. When specified then object id is not used as a domain. heads up: the object id stops pulling double duty the second you do this ⭐
• deploy-hook — a 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. so if one flops, the rest don't get their turn 😭

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). free variables, no setup, we love to see it 💖

• pre-hook — a 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. so it's not just out here running for fun 🫶

• post-hook — a 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. it's the cleanup crew, the afterparty, the closer 💅

---

🔥 BOOLEAN PARAMETERS 🔥

• staging — obtain a test certificate from a staging server. practice round, no cap 🎀

---

💌 MESSAGES 💌

• change — Certificate was changed.
• create — Certificate was created.
• remove — Certificate was removed.

---

🌸 EXAMPLES 🌸

okay here's where it gets real, copy these exactly bestie ✨

# 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

like, notice how in the second one example.com has to show up again as a --domain because the object id stopped counting as a domain. the way that's such a gotcha 😭 read the comment, it's there for a reason 🫶

---

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

the icons who wrote this fr fr 🌟

---

📜 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

---

and that's the whole page, bestie!! 🎀 version 7.0.0, dated Jul 31, 2022 — shoutout to the cdist crew, go get those certs, you're doing amazing sweetie 💅✨🦋🌸💖