# Role `certbot`

A role for deploying Certbot and setting up certificates using it.

Note: This role doesn't take care of deleting certificates.

Also see the following documentation for a full How-to on how to get certificates using this role in the context of our infra: <https://wiki.ccchh.net/infrastructure:zertifikate>.

## Challenge Types

For the `certbot__certs` configuration, depending on the challenge type, different preparation needs to be done.

### `dns-01-acme-dns`

For the `dns-01-acme-dns` challenge type, ensure that:

1. An acme-dns entry got registered, so you have access to the `subdomain`, `apiUser` and `apiKey` for the configuration. The `apiKey` should be stored in some kind of secret, which then gets referenced in the relevant `certbot__certs` configuration.  
   For our acme-dns instance, go to <https://acmedns.hamburg.ccc.de/>, sign-in and register a new entry.
2. CNAME the `_acme-challenge` domain of the domain you want to obtain a certificate for (`certbot__certs.*.commonName`) to the full domain from the registration.  
   It should look something like this: `_acme-challenge.domainiwantcertfor.tld. CNAME 3ed25037-79f1-4a89-8934-db3e162fe2bc.auth.acmedns.hamburg.ccc.de.`

For more info see:

- [The ACME DNS hamburg.ccc.de Wiki page](https://wiki.hamburg.ccc.de/infrastructure:services:acme_dns)
- [The acme-dns GitHub](https://github.com/acme-dns/acme-dns)

## Required Arguments

- `certbot__acme_account_email_address`: The E-Mail address to use for the ACME account.

## Optional Arguments

- `certbot__certificate_domains`: The domains for which to obtain a certificate using the HTTP-01 challenge.
- `certbot__http_01_port`: The port number the bot listens on. Should be `80` if directly exposed to the internet.  
   Defaults to `31820` (for the public-reverse-proxy setup).
- `certbot__certs`: Certificates to create.  
  Defaults to the empty list (`[ ]`).
- `certbot__certs.*.commonName`: The common name to issue the certificate for.
- `certbot__certs.*.challengeType`: The challenge type to use for getting the certificate. Challenge type-specific configuration must be provided as well.
  Should be one of:
  - `dns-01-acme-dns`
- `certbot__certs.*.dns_01_acme_dns`: Configuration for the `dns-01-acme-dns` challenge type.
- `certbot__certs.*.dns_01_acme_dns.serverUrl`: The acme-dns server API URL.  
  Defaults to `https://acmedns.hamburg.ccc.de`.
- `certbot__certs.*.dns_01_acme_dns.subdomain`: The acme-dns subdomain to use.
- `certbot__certs.*.dns_01_acme_dns.apiUser`: The acme-dns API user to use.
- `certbot__certs.*.dns_01_acme_dns.apiKey`: The acme-dns API key to use.
- `certbot__new_cert_commands`: A list of commands to execute after getting a new certificate. Will be added into a bash script.  
  Defaults to the empty list (`[ ]`).

## `hosts`

The `hosts` for this role need to be the machines on which you want to make sure Certbot is deployed and given certificates are set up.