# Driver `acme`

**Supported keywords:**

- comment
- directory
- renew_before
- webroot

## Keyword `comment`

	required:    false
	scopable:    false

**Description:**

A free form text describing the role of the object, of the node, or of the
section it is set in.

The keyword is accepted in any section, so the DEFAULT section can document a
configuration as a whole, and a resource, pool, heartbeat, array or network
section can document itself.

The agent does not interpret the value.


## Keyword `directory`

	required:    false
	scopable:    false

**Example:**

	directory=letsencrypt

**Description:**

The ACME directory the certificate of the sec is issued by, renewed by
`om <path> certificate renew` or a `task.acme` resource. `letsencrypt` and
`letsencrypt-staging` name the directories of Let's Encrypt, and any other
value is the url of a directory.

The domains are the `cn` and the `alt_names` of the sec, and the account is
registered there, with its `email` as the contact when it has one.

A sec naming no directory has its certificate generated as `certificate
create` does, self-signed or signed by its `ca`, and renewed the same way when
due.

Use the staging directory of Let's Encrypt to try a setup out: its
certificates are not trusted, and its rate limits are far higher.

A certificate of Let's Encrypt for two names, its http-01 challenges served
by the http server of the domains from a webroot:

```
[DEFAULT]
cn = www.example.com
alt_names = example.com
email = admin@example.com

[acme]
directory = letsencrypt
webroot = /srv/web.ns1.vol.cluster1/acme-challenges
```

The same, tried out first on the staging directory:

```
[acme]
directory = letsencrypt-staging
webroot = /srv/web.ns1.vol.cluster1/acme-challenges
```

Changing the directory, as from `letsencrypt-staging` to `letsencrypt` once
the setup works, makes the next renewal issue a new certificate from the
directory now named, due or not.

A sec listed in the `listener.tls_secs` of the cluster needs no webroot: the
listener of every node answers its challenges on `listener.acme_port`.

A certificate of the directory of an ACME server of your own, as a smallstep
`step-ca` with an ACME provisioner named `acme`, served with a certificate the
node trusts:

```
[acme]
directory = https://ca.example.com/acme/acme/directory
```

A certificate of a pebble test server, its certificate trusted by the node
too:

```
[acme]
directory = https://pebble.example.com:14000/dir
```

A directory requiring an external account binding, as ZeroSSL and Google
Trust Services do, is not supported: the account is registered without one.


## Keyword `renew_before`

	required:    false
	scopable:    false
	default:     30d
	convert:     duration

**Example:**

	renew_before=20d

**Description:**

How long before its expiry the certificate is renewed: a renewal earlier
than that does nothing. A certificate naming other domains than the sec asks,
or self-signed, is renewed whatever its expiry.


## Keyword `webroot`

	required:    false
	scopable:    true
	rbac:        A host path the challenge token is written in requires the root grant.

**Example:**

	webroot=/srv/web-cfg.ns1.vol.cluster1/acme-challenges

**Description:**

The directory, on the node renewing the certificate, the http server of the
domains serves `/.well-known/acme-challenge/` from: the renewal writes the
http-01 challenge token there, under `.well-known/acme-challenge/`, and the
ACME directory reads it back through the domains.

It is usually a directory of a volume of the service publishing the domains,
the renewal running as a task of that service, where it runs.