## Using ACME certificates in Apache/httpd {#module-security-acme-httpd}

Using ACME certificates with Apache virtual hosts is identical
to using them with Nginx. The attribute names are all the same, just replace
"nginx" with "httpd" where appropriate.

## Manual configuration of HTTP-01 validation {#module-security-acme-configuring}

First off you will need to set up a virtual host to serve the challenges.
This example uses a vhost called `certs.example.com`, with
the intent that you will generate certs for all your vhosts and redirect
everyone to HTTPS.

```nix
{
  security.acme.acceptTerms = true;
  security.acme.defaults.email = "admin+acme@example.com";

  # /var/lib/acme/.challenges must be writable by the ACME user
  # and readable by the Nginx user. The easiest way to achieve
  # this is to add the Nginx user to the ACME group.
  users.users.nginx.extraGroups = [ "acme" ];

  services.nginx = {
    enable = true;
    virtualHosts = {
      "acmechallenge.example.com" = {
        # Catchall vhost, will redirect users to HTTPS for all vhosts
        serverAliases = [ "*.example.com" ];
        locations."/.well-known/acme-challenge" = {
          root = "/var/lib/acme/.challenges";
        };
        locations."/" = {
          return = "301 https://$host$request_uri";
        };
      };
    };
  };
  # Alternative config for Apache
  users.users.wwwrun.extraGroups = [ "acme" ];
  services.httpd = {
    enable = true;
    virtualHosts = {
      "acmechallenge.example.com" = {
        # Catchall vhost, will redirect users to HTTPS for all vhosts
        serverAliases = [ "*.example.com" ];
        # /var/lib/acme/.challenges must be writable by the ACME user and readable by the Apache user.
        # By default, this is the case.
        documentRoot = "/var/lib/acme/.challenges";
        extraConfig = ''
          RewriteEngine On
          RewriteCond %{HTTPS} off
          RewriteCond %{REQUEST_URI} !^/\.well-known/acme-challenge [NC]
          RewriteRule (.*) https://%{HTTP_HOST}%{REQUEST_URI} [R=301]
        '';
      };
    };
  };
}
```

Now you need to configure ACME to generate a certificate.

```nix
{
  security.acme.certs."foo.example.com" = {
    webroot = "/var/lib/acme/.challenges";
    email = "foo@example.com";
    # Ensure that the web server you use can read the generated certs
    # Take a look at the group option for the web server you choose.
    group = "nginx";
    # Since we have a wildcard vhost to handle port 80,
    # we can generate certs for anything!
    # Just make sure your DNS resolves them.
    extraDomainNames = [ "mail.example.com" ];
  };
}
```

The private key {file}`key.pem` and certificate
{file}`fullchain.pem` will be put into
{file}`/var/lib/acme/foo.example.com`.

Refer to [](#ch-options) for all available configuration
options for the [security.acme](#opt-security.acme.certs)
module.

## Configuring ACME for DNS validation {#module-security-acme-config-dns}

This is useful if you want to generate a wildcard certificate, since
ACME servers will only hand out wildcard certs over DNS validation.
There are a number of supported DNS providers and servers you can utilise,
see the [lego docs](https://go-acme.github.io/lego/dns/)
for provider/server specific configuration values. For the sake of these
docs, we will provide a fully self-hosted example using bind.

```nix
{
  services.bind = {
    enable = true;
    extraConfig = ''
      include "/var/lib/secrets/dnskeys.conf";
    '';
    zones = [
      rec {
        name = "example.com";
        file = "/var/db/bind/${name}";
        master = true;
        extraConfig = "allow-update { key rfc2136key.example.com.; };";
      }
    ];
  };

  # Now we can configure ACME
  security.acme.acceptTerms = true;
  security.acme.defaults.email = "admin+acme@example.com";
  security.acme.certs."example.com" = {
    domain = "*.example.com";
    dnsProvider = "rfc2136";
    environmentFile = "/var/lib/secrets/certs.secret";
    # We don't need to wait for propagation since this is a local DNS server