====== ACME DNS ======
---- dataentry service ----
service-urls_urls          : https://acmedns.hamburg.ccc.de
other-service-fqdns        : 
host-fqdn                  : acmedns.hosts.hamburg.ccc.de
netbox-link_url            : https://netbox.hamburg.ccc.de/virtualization/virtual-machines/85/
server_page                : infrastructure:servers:chaosknoten
maintainers                : stb
ccchh-id-integration_yesno : false
----



===== Description =====

[[https://github.com/joohoi/acme-dns|acme-dns]] is a specialized name server that can be used to implent the [[https://letsencrypt.org/docs/challenge-types/#dns-01-challenge|ACME DNS-01 challenge]].

We run an instance of acme-dns so we can more easily create Let's Encrypt certificates for hosts, in particular those that are not accessible from the Internet, and thus can't use the HTTP-01 challenge.
===== Configuration =====

See the Ansible repo. We are using [[https://github.com/oauth2-proxy/oauth2-proxy|oauth2-proxy]] to limit access to the register API endpoint to users that can log in through our Keycloak.

===== Using ACME-DNS =====

To enable requesting Let's Encrypt certificates with acme-dns, you need to register a record in acme-dns, then you need to configure your DNS entry so it points to the acme-dns zone (and thus the acme-dns name server), and finally you need to configure your ACME client to issue the certificate.

==== Register an Entry in ACME DNS ====

Go to https://acmedns.hamburg.ccc.de, log in if necessary, and click Register. A table will be shown with four parameters that you will need. This information is only shown once, so make sure to save or copy it straight away.

  * Full Domain: is the target of the CNAME entry you need to create
  * Subdomain, X-Api-User and X-Api-Key: configuration for the ACME client.

**Note: there is no way to delete registrations.** Each registration is small, so it's not an immediate problem, but please do not click register unless you are planning to really create a new entry.

{{:infrastructure:services:acmedns-register.png?600|}}
==== Create a DNS Entry for the Challenge ====

Create a (ACME magic) CNAME record to your existing zone, pointing to the subdomain you got from the registration.

''_acme-challenge.domainiwantcertfor.tld. CNAME 3ed25037-79f1-4a89-8934-db3e162fe2bc.auth.acmedns.hamburg.ccc.de.''

You can request a cerificate for a wildcard DNS entry by simply creating the wildcard entry for the FQDN, and making sure the '_acme-challenge' entry aligns with it. For example, with the above entry you can add the wild card like so:

''*.domainiwantcertfor.tld. A 192.168.0.2''

==== Configure ACME client ====

  * [[https://github.com/joohoi/acme-dns-certbot-joohoi|acm-dns-certbot]] code and configuration
  * [[https://github.com/acmesh-official/acme.sh/wiki/dnsapi#45-use-acme-dns-api|acme.sh configuration for acme-dns]]
  * [[https://go-acme.github.io/lego/dns/acme-dns/index.html|LEGO configuration]]