acmed/man/en/acmed.toml.5

.\" Copyright (c) 2019-2020 Rodolphe Bréard <rodolphe@breard.tf>
.\"
.\" Copying and distribution of this file, with or without modification,
.\" are permitted in any medium without royalty provided the copyright
.\" notice and this notice are preserved.  This file is offered as-is,
.\" without any warranty.
.Dd Dec 21, 2024
.Dt ACMED.TOML 5
.Os
.Sh NAME
.Nm acmed.toml
.Nd ACMEd configuration file format
.Sh DESCRIPTION
Configuration files for
.Xr acmed 8
are written in the
.Em TOML
format. The allowed elements are described below.
.Bl -tag
.It Ic account
Table representing an account on one or several endpoint.
.Bl -tag
.It Ic contacts Ar array
Array of tables describing describing the account holder's contact information. Each table must have one and only one key-value pair. Possible keys and their associated values are:
.Bl -tag
.It Ic mailto Ar string
A mailto URI as defined by
.Em RFC 6068 .
This URI cannot contains neither
.Dq hfields
nor more than one
.Dq addr-spec
in the
.Dq to
component.
.El
.It Ic env Ar table
Table of environment variables that will be accessible from hooks.
.It Ic external_account Ar table
Table containing the information required to bind the account to an external one. Possible fields and values are:
.Bl -tag
.It Ic identifier Ar string
ASCII string identifying the key.
.It Ic key Ar string
Private key encoded in base64url without padding.
.It Ic signature_algorithm Ar string
Name of the signature algorithm used to sign the external account binding message sent to the endpoint as defined in
.Em RFC 7518 .
Possible values are:
.Bl -dash -compact
.It
HS256
.Aq default
.It
HS384
.It
HS512
.El
.El
.It Ic hooks Ar array
Names of hooks that will be called during operations on the account storage file. The hooks are guaranteed to be called sequentially in the declaration order.
.It Cm key_type Ar string
Name of the asymmetric cryptography algorithm used to generate the key pair. Possible values are:
.Bl -dash -compact
.It
ed25519
.It
ed448
.It
ecdsa_p256
.Aq default
.It
ecdsa_p384
.It
ecdsa_p521
.It
rsa2048
.It
rsa4096
.El
.It Cm signature_algorithm Ar string
Name of the signature algorithm used to sign the messages sent to the endpoint as defined in
.Em RFC 7518 .
The default value is derived from the key type. Possible values are:
.Bl -dash -compact
.It
ES256
.It
ES384
.It
ES512
.It
RS256
.El
.El
.It Ic certificate
Array of table representing a certificate that will be requested to a CA.
.Pp
Note that, by default, certificates are identified by the first identifier in the list of identifiers. That means that if you reorder the identifiers so that a different identifier is at the first position, a new certificate with a new name will be issued.
.Bl -tag
.It Ic account Ar string
Name of the account to use.
.It Ic csr_digest Ar string
Name of the certificate's signing request digest algorithm. Possible values are:
.Bl -dash -compact
.It
sha256
.Aq default
.It
sha384
.It
sha512
.El
.It Ic directory Ar string
Path to the directory where certificates and their associated private keys are stored.
.It Ic endpoint Ar string
Name of the endpoint to use.
.It Ic env Ar table
Table of environment variables that will be accessible from hooks.
.It Ic file_name_format Ar string
Template used to build the file's name. The template syntax is
.Em MiniJinja .
See the
.Sx STANDARDS
section for a link to the
.Em MiniJinja
specifications. If not specified, the value defined in the
.Em endpoint
element, and then the
.Em global
element, is used. Default is
.Dq {{ name }}_{{ key_type }}.{{ file_type }}.{{ ext }} .
Possible variables are:
.Bl -tag
.It Ic ext Ar string
File extension. See
.Xr cert_file_ext
and
.Xr pk_file_ext .
.It Ic file_type Ar string
Contains
.Dq pk
for the private key file and
.Dq crt
for the certificate file.
.It Ic key_type Ar string
The certificate's private key type.
.It Ic name Ar string
The certificate's name.
.El
.It Ic hooks Ar array
Names of hooks that will be called when requesting a new certificate. The hooks are guaranteed to be called sequentially in the declaration order.
.It Ic identifiers Ar array
Array of tables listing the identifiers that should be included in the certificate along with the challenge to use for each one. The
.Em dns
and
.Em ip
fields are mutually exclusive.
.Bl -tag
.It Ic challenge Ar string
The name of the challenge to use to prove the identifier's ownership. Possible values are:
.Bl -dash -compact
.It
dns-01
.It
http-01
.It
tls-alpn-01
.El
.It Ic dns Ar string
The domain name.
.It Ic env Ar table
Table of environment variables that will be accessible from hooks.
.It Ic ip Ar string
The IP address.
.El
.It Ic key_type Ar string
Name of the asymmetric cryptography algorithm used to generate the certificate's key pair. Possible values are:
.Bl -dash -compact
.It
ed25519
.It
ed448
.It
ecdsa_p256
.It
ecdsa_p384
.It
ecdsa_p521
.It
rsa2048
.Aq default
.It
rsa4096
.El
.It Ic kp_reuse Ar boolean
Set whether or not the private key should be reused when renewing the certificate. Default is false.
.It Ic name
Name of the certificate. Must be unique unless the key type is different. Will be used in logs and in the associated file's name. The
.Sq * ,
.So
:
.Sc
and
.Sq /
characters will be replaced by an underscore. Default is the first identifier.
.It Cm random_early_renew Ar string
Period of time before the usual certificate renewal, in which the certificate will renew at a random time. This is useful for when
you want to even out your certificate orders when you're dealing with very large numbers of certificates. The format is described in the
.Sx TIME PERIODS
section. Default is the value defined in the associated endpoint.
.It Cm renew_delay Ar string
Period of time between the certificate renewal and its expiration date. The format is described in the
.Sx TIME PERIODS
section. Default is the value defined in the associated endpoint.
.It Ic subject_attributes Ar table
Table where the certificate's subject attributes are specified. Possible keys, with their RFC 4519 and X.500 equivalents, are:
.Bl -column -offset indent ".Sy organizational_unit_name" ".Sy generationQualifier" ".Sy organizationalUnitName"
.It Sy ACMEd key Ta Sy RFC 4519 Ta Sy X.500
.It Li country_name Ta c Ta countryName
.It Li generation_qualifier Ta generationQualifier Ta
.It Li given_name Ta givenName Ta
.It Li initials Ta initials Ta
.It Li locality_name Ta l Ta localityName
.It Li name Ta name Ta
.It Li organization_name Ta o Ta organizationName
.It Li organizational_unit_name Ta ou Ta organizationalUnitName
.It Li pkcs9_email_address Ta Ta
.It Li postal_address Ta postalAddress Ta
.It Li postal_code Ta postalCode Ta
.It Li state_or_province_name Ta st Ta stateOrProvinceName
.It Li street Ta street Ta streetAddress
.It Li surname Ta sn Ta surname
.It Li title Ta title Ta
.El
.El
.It Ic endpoint
Table where each element defines a Certificate Authority
.Pq CA
which may be used to request certificates.
.Bl -tag
.It Cm file_name_format Ar string
Template used to build the file's name. For detailed documentation, see the
.Em file_name_format
directive located in the
.Em certificate
element.
.It Cm rate_limits Ar array
Array containing the names of the HTTPS rate limits to apply.
.It Cm random_early_renew Ar string
Period of time before the usual certificate renewal, in which the certificate will renew at a random time. This is useful for when
you want to even out your certificate orders when you're dealing with very large numbers of certificates. The format is described in the
.Sx TIME PERIODS
section. Default is the value defined in the global section.
.It Cm renew_delay Ar string
Period of time between the certificate renewal and its expiration date. The format is described in the
.Sx TIME PERIODS
section. Default is the value defined in the global section.
.It Cm root_certificates Ar array
Array containing the path to root certificates that should be added to the trust store.
.It Cm tos_agreed Ar boolean
Set whether or not the user agrees to the Terms Of Service
.Pq TOS .
.It Cm url Ar string
The endpoint's directory URL.
.El
.It Ic global
Table containing the global configuration options.
.Bl -tag
.It Cm accounts_directory Ar string
Specify the directory where the accounts private and public keys are stored.
.It Cm cert_file_group Ar group_name|group_id Ft string
Specify the group who will own newly-created certificates files. See
.Xr chown 2
for more details.
.It Cm cert_file_mode Ar integer
Specify the permissions to use for newly-created certificates files. See
.Xr chmod 2
for more details.
.It Cm cert_file_user Ar username|user_id Ft string
Specify the user who will own newly-created certificates files. See
.Xr chown 2
for more details.
.It Cm cert_file_ext Ft string
Specify the file extension of certificate files. Default is
.Dq pem .
.It Cm certificates_directory Ar string
Specify the directory where the certificates and their associated private keys are stored.
.It Ic env Ar table
Table of environment variables that will be accessible from hooks.
.It Ic file_name_format Ar string
Template used to build the file's name. For detailed documentation, see the
.Em file_name_format
directive located in the
.Em certificate
element.
.It Cm pk_file_group Ar group_name|group_id Ft string
Specify the group who will own newly-created private-key files. See
.Xr chown 2
for more details.
.It Cm pk_file_mode Ar integer
Specify the permissions to use for newly-created private-key files. See
.Xr chmod 2
for more details.
.It Cm pk_file_user Ar username|user_id Ft string
Specify the user who will own newly-created private-key files. See
.Xr chown 2
for more details.
.It Cm pk_file_ext Ft string
Specify the file extension of private-key files.
.It Cm random_early_renew Ar string
Period of time before the usual certificate renewal, in which the certificate will renew at a random time. This is useful for when
you want to even out your certificate orders when you're dealing with very large numbers of certificates. The format is described in the
.Sx TIME PERIODS
section. By default, this is disabled, or rather, the time frame is set to 0.
.It Cm renew_delay Ar string
Period of time between the certificate renewal and its expiration date. The format is described in the
.Sx TIME PERIODS
section. Default is 30d.
.It Cm root_certificates Ar array
Array containing the path to root certificates that should be added to the trust store.
.El
.It Ic group
Table of array allowing to group several hooks as one. A group is considered as new hook. The array contains the names of the hooks that are grouped. The hooks are guaranteed to be called sequentially in the declaration order. The group name must not start with
.Dq internal: .
.It Ic hook
Table where each element defines a command that will be launched at a defined point. See section
.Sx WRITING A HOOK
for more details. The hook name must not start with
.Dq internal: .
.Bl -tag
.It Cm allow_failure Ar boolean
Defines if an error return value for this hook is allowed or not. If not allowed, a failure in this hook will fail the whole certificate request process. Default is false.
.It Ic args Ar array
Array of strings representing the command's arguments.
.It Ic cmd Ar string
The name of the command that will be launched.
.It Ic stderr Ar string
Path to the file where the command's standard error output if written.
.It Ic stdin Ar string
Path to the file that will be written into the command's standard intput. Mutually exclusive with
.Em stdin_str .
.It Ic stdin_str Ar string
String that will be written into the command's standard input. Mutually exclusive with
.Em stdin .
.It Ic stdout Ar string
Path to the file where the command's standard output if written.
.It Cm type Ar array
Array of strings. Possible types are:
.Bl -dash -compact
.It
challenge-dns-01
.It
challenge-dns-01-clean
.It
challenge-http-01
.It
challenge-http-01-clean
.It
challenge-tls-alpn-01
.It
challenge-tls-alpn-01-clean
.It
file-post-create
.It
file-post-edit
.It
file-pre-create
.It
file-pre-edit
.It
post-operation
.El
.El
.It Ic logging_facility
Table where each element defines a logging facility. Possible fields and values are:
.Bl -tag
.It Cm output Ar string
Path of the file where the log will be written. If the file does not exists, it will be created. It the file already exists, logs will be appended at the end of the file. The following special values may be specified:
.Bl -dash -compact
.It
stderr: write the logs into the terminal's standard error stream
.It
stdout: write the logs into the terminal's standard stream
.It
syslog: write the logs into syslog using the daemon facility
.El
.It Cm format Ar string
Log format. Possible values are:
.Bl -dash -compact
.It
compact
.It
full
.Aq default
.It
json
.It
pretty
.El
.It Cm level Ar string
Log level. Possible values are:
.Bl -dash -compact
.It
error
.It
warn
.It
info
.Aq default
.It
debug
.It
trace
.El
.It Cm ansi Ar boolean
Defines whether or not the log will use the ANSI terminal escape codes for colors and other text formatting. Default if true for terminal outputs (strerr and stdout) and false for syslog and files.
.El
.It Ic rate-limit
Table where each element defines a HTTPS rate limit. Possible fields and values are:
.Bl -tag
.It Cm number Ar integer
Number of requests authorized withing the time period.
.It Cm period Ar string
Period of time during which a maximal number of requests is authorized. The format is described in the
.Sx TIME PERIODS
section.
.El
.El
.Sh CONFIGURATION FILES ORGANIZATION
It is strongly recommended to split the configuration into several files, each file containing directives related to only one logical component. Ideally, those files should be prefixed using a 2 digit number and an underscore. The first digit should indicate the type of directives within the file:
.Pp
.Bl -tag -compact
.It 0
global configuration (including logging facilities)
.It 1
hooks and hook groups
.It 2
endpoints and their associated rate limits
.It 3
accounts
.It 4
certificates
.El
.Pp
The second digit should a zero, unless a specific loading order is required.
.Pp
For example, the file containing the endpoint for the
.Dq Example Org
certificate authority should be named
.Dq 20_example_org.toml .
Accounts on this same certificate authority should either be named
.Dq 30_example_org.toml
or
.Dq 30_account_name.toml .
.Pp
Some default and example configuration files are available in the conf-available directory. When using those files without modification, you should create a symbolic link pointing to them instead of copying them.
.Pp
For legal reasons, the default configuration files for certificate authorities endpoints do not accept the terms of services by default. The recommended way to accept those terms of service is to override this directive, either in a dedicated file or directly in the certificate's configuration. If a dedicated file is used, it is recommended to name it the same way as the endpoint file but with a higher second digit in the prefix (example:
.Dq 21_example_org.toml
).
.Sh WRITING A HOOK
When requesting a certificate from a CA using ACME, there are three steps that are hard to automatize. The first one is solving challenges in order to prove the ownership of every identifier to be included: it requires to interact with the configuration of other services, hence depends on how the infrastructure works. The second one is restarting all the services that use a given certificate, for the same reason. The last one is archiving: although several default methods can be implemented, sometimes admins wants or are required to do it in a different way.
.Pp
In order to allow full automation of the three above steps without imposing arbitrary restrictions or methods,
.Xr acmed 8
uses hooks. Fundamentally, a hook is a command line template that will be called at a specific time of the process. Such an approach allows admins to use any executable script or program located on the machine to customize the process.
.Pp
For a given certificate, hooks are guaranteed to be called sequentially in the declaration order. It is therefore possible to have a hook that depends on another one. Nevertheless, several certificates may be renewed at the same time. Hence, hooks shall not use globing or any other action that may disrupt hooks called by a different certificate.
.Pp
A hook has a type that will influence both the moment it is called and the available template variables. It is possible to declare several types. In such a case, the hook will be invoked whenever one of its type request it. When called, the hook only have access to template variable for the current type. If a hook uses a template variable that does not exists for the current type it is invoked for, the variable is empty.
.Pp
When writing a hook, the values of
.Em args ,
.Em stdin ,
.Em stdin_str ,
.Em stdout
and
.Em stderr
are considered as template strings whereas
.Em cmd
is not. The template syntax is
.Em MiniJinja .
See the
.Sx STANDARDS
section for a link to the
.Em MiniJinja
specifications.
.Pp
The available types and the associated template variable are described below.
.Bl -tag
.It Ic challenge-dns-01
Invoked when the ownership of an identifier must be proved using the
.Em dns-01
challenge. The available template variables are:
.Bl -tag -compact
.It Cm challenge Ar string
The name of the challenge type
.Aq dns-01 .
Mostly used in hooks with multiple types.
.It Cm env Ar array
Array containing all the environment variables.
.It Cm identifier Ar string
The identifier name whom ownership is currently being validated.
.It Cm is_clean_hook Ar bool
False
.It Cm proof Ar string
The content of the proof that must be written to a
.Ql TXT
entry of the DNS zone for the
.Ql _acme-challenge
subdomain.
.El
.It Ic challenge-dns-01-clean
Invoked once an identifier ownership has been proven using the
.Em dns-01
challenge. This hook is intended to remove the proof since it is no longer required. The template variables are strictly identical to those given in the corresponding
.Em challenge-dns-01
hook, excepted
.Em is_clean_hook
which is set to
.Em true .
.It Ic challenge-http-01
Invoked when the ownership of an identifier must be proved using the
.Em http-01
challenge. The available template variables are:
.Bl -tag -compact
.It Cm challenge Ar string
The name of the challenge type
.Aq http-01 .
Mostly used in hooks with multiple types.
.It Cm env Ar array
Array containing all the environment variables.
.It Cm file_name Ar string
Name of the file containing the proof. This is not a full path and does not include the
.Ql .well-known/acme-challenge/
prefix.
.It Cm identifier Ar string
The identifier name whom ownership is currently being validated.
.It Cm is_clean_hook Ar bool
False
.It Cm proof Ar string
The content of the proof that must be written to
.Em file_name .
.El
.It Ic challenge-http-01-clean
Invoked once an identifier ownership has been proven using the
.Em http-01
challenge. This hook is intended to remove the proof since it is no longer required. The template variables are strictly identical to those given in the corresponding
.Em challenge-http-01
hook, excepted
.Em is_clean_hook
which is set to
.Em true .
.It Ic challenge-tls-alpn-01
Invoked when the ownership of an identifier must be proved using the
.Em tls-alpn-01
challenge. The available template variables are:
.Bl -tag -compact
.It Cm challenge Ar string
The name of the challenge type
.Aq tls-alpn-01 .
Mostly used in hooks with multiple types.
.It Cm env Ar array
Array containing all the environment variables.
.It Cm identifier Ar string
The identifier name whom ownership is currently being validated.
.It Cm identifier_tls_alpn Ar string
The identifier name whom ownership is currently being validated, in a form suitable for the TLS ALPN challenge.
.It Cm is_clean_hook Ar bool
False
.It Cm proof Ar string
Plain-text representation of the
.Em acmeIdentifier
extension that should be used in the self-signed certificate presented when a TLS connection is initiated with the
.Qd acme-tls/1
ALPN extension value.
.Xr acmed 8
will not generate the certificate itself since it can be done using
.Xr tacd 8 .
.It Cm raw_proof Ar string
The SHA-256 digest of the key authorization, encoded using Base64 URL scheme without padding. This is intended for the use of ACMEd with a TLS-ALPN responder other than
.Xr tacd 8 .
.El
.It Ic challenge-tls-alpn-01-clean
Invoked once an identifier ownership has been proven using the
.Em tls-alpn-01
challenge. This hook is intended to remove the proof since it is no longer required. The template variables are strictly identical to those given in the corresponding
.Em challenge-tls-alpn-01
hook, excepted
.Em is_clean_hook
which is set to
.Em true .
.It Ic file-post-create
Invoked
.Em after
a non-existent file
.Em created .
The available template variables are the same as those available for the
.Em file-pre-create
type.
.It Ic file-post-edit
Invoked
.Em after
an existent file
.Em modified .
The available template variables are the same as those available for the
.Em file-pre-create
type.
.It Ic file-pre-create
Invoked
.Em before
a non-existent file
.Em created .
The available template variables are:
.Bl -tag -compact
.It Cm env Ar array
Array containing all the environment variables.
.It Cm file_directory Ar string
Name of the directory where the impacted file is located.
.It Cm file_name Ar string
Name of the impacted file.
.It Cm file_path Ar string
Full path to the impacted file.
.El
.It Ic file-pre-edit
Invoked
.Em before
an existent file
.Em modified .
The available template variables are the same as those available for the
.Em file-pre-create
type.
.It Ic post-operation
Invoked at the end of the certificate request process. The available template variables are:
.Bl -tag -compact
.It Cm env Ar array
Array containing all the environment variables.
.It Cm identifiers Ar string
Array containing the identifiers included in the requested certificate.
.It Cm is_success Ar boolean
True if the certificate request is successful.
.It Cm key_type Ar string
Name of the asymmetric cryptography algorithm used to generate the certificate's key pair.
.It Cm status Ar string
Human-readable status. If the certificate request failed, it contains the error description.
.It Cm certificate_path Ar string
Path to the file containing the certificate.
.It Cm private_key_path Ar string
Path to the file containing the private key.
.El
.El
.Sh DEFAULT HOOKS
Because many people have the same needs, ACMEd comes with a set of hooks that should serve most situations. Hook names being unique, the following names and any other name starting by those is reserved and should not be used.
.Bl -tag
.It Pa git
This hook uses
.Xr git 1
to archive private keys, public keys and certificates. It is possible to customize the commit username and email by using respectively the
.Ev GIT_USERNAME
and
.Ev GIT_EMAIL
environment variables.
.It Pa http-01-echo
This hook is designed to solve the http-01 challenge. For this purpose, it will write the proof into
.Pa {{ env.HTTP_ROOT }}/{{ identifier }}/.well-known/acme-challenge/{{ file_name }} .
.Pp
The web server must be configured so the file
.Pa http://{{ identifier }}/.well-known/acme-challenge/{{ file_name }}
can be accessed from the CA.
.Pp
If
.Ev HTTP_ROOT
is not specified, it will be set to
.Pa /var/www .
.It Pa tls-alpn-01-tacd-tcp
This hook is designed to solve the tls-alpn-01 challenge using
.Xr tacd 8 .
It requires
.Xr pkill 1
to support the
.Em -F
option.
.Pp
.Xr tacd 8
will listen on the host defined by the
.Ev TACD_HOST
environment variable (default is the identifier to be validated) and on the port defined by the
.Ev TACD_PORT
environment variable (default is 5001).
.Pp
.Xr tacd 8
will store its pid into
.Pa {{ TACD_PID_ROOT }}/tacd_{{ identifier }}.pid .
If
.Ev TACD_PID_ROOT
is not specified, it will be set to
.Pa /run .
.It Pa tls-alpn-01-tacd-unix
This hook is designed to solve the tls-alpn-01 challenge using
.Xr tacd 8 .
It requires
.Xr pkill 1
to support the
.Em -F
option.
.Pp
.Xr tacd 8
will listen on the unix socket
.Pa {{ env.TACD_SOCK_ROOT }}/tacd_{{ identifier }}.sock .
If
.Ev TACD_SOCK_ROOT
is not specified, it will be set to
.Pa /run .
.Pp
.Xr tacd 8
will store its pid into
.Pa {{ TACD_PID_ROOT }}/tacd_{{ identifier }}.pid .
If
.Ev TACD_PID_ROOT
is not specified, it will be set to
.Pa /run .
.El
.Sh TIME PERIODS
ACMEd uses its own time period format, which is vaguely inspired by the ISO 8601 one. Periods are formatted as
.Ar PM[PM...]
where
.Ar M
is case sensitive character representing a length and
.Ar P
is an integer representing a multiplayer for the following length. The authorized length are:
.Bl -dash -compact
.It
.Ar s :
second
.It
.Ar m :
minute
.It
.Ar h :
hour
.It
.Ar d :
day
.It
.Ar w :
week
.El
The
.Ar PM
couples can be specified multiple times and in any order.
.Pp
For example,
.Dq 1d42s
and
.Dq 40s20h4h2s
both represents a period of one day and forty-two seconds.
.Sh TEMPLATE FILTERS
In addition the the filters provided by default by MiniJinja, ACMEd provides the following filters:
.Bl -tag
.It Pa rev_labels
Reverts the labels of a domain name (eg:
.Dq mx1.example.org
becomes
.Dq org.example.mx1
).
.El
.Sh FILES
.Bl -tag
.It Pa /var/lib/acmed/accounts
Default accounts private and public keys directory.
.It Pa /etc/acmed/acmed.toml
Default
.Xr acmed 8
configuration file.
.It Pa /var/lib/acmed/certs
Default certificates and associated private keys directory.
.El
.Sh EXAMPLES
The following example defines a typical endpoint, account and certificate for a domain, several subdomains and an IP address.
.Bd -literal -offset indent
[endpoint."example-name"]
url = "https://acme.example.org/directory"
tos_agreed = true

[[account]]
name = "my test account"
contacts = [
  { mailto = "certs@exemple.net" }
]

[[certificate]]
endpoint = "example-name"
account = "my test account"
identifiers = [
    { dns = "exemple.net", challenge = "http-01"},
    { dns = "1.exemple.net", challenge = "dns-01"},
    { dns = "2.exemple.net", challenge = "tls-alpn-01", env.TACD_PORT="5010"},
    { dns = "3.exemple.net", challenge = "tls-alpn-01", env.TACD_PORT="5011"},
    { ip = "203.0.113.1", challenge = "http-01"},
]
hooks = ["git", "http-01-echo", "tls-alpn-01-tacd-tcp", "some-dns-01-hook"]
env.HTTP_ROOT = "/srv/http"
.Ed
.Pp
It is possible to use
.Xr echo 1
to solve the
.Em http-01
challenge and
.Xr rm 1
to clean it.
.Xr mkdir 1
and
.Xr chmod 1
are used to prevent issues related to file access.
.Bd -literal -offset indent
[[hook]]
name = "http-01-echo-mkdir"
type = ["challenge-http-01"]
cmd = "mkdir"
args = [
    "-m", "0755",
    "-p", "{{ env.HTTP_ROOT | default('/var/www') }}/{{ identifier }}/.well-known/acme-challenge"
]

[[hook]]
name = "http-01-echo-echo"
type = ["challenge-http-01"]
cmd = "echo"
args = ["{{ proof }}"]
stdout = "{{ env.HTTP_ROOT | default('/var/www') }}/{{ identifier }}/.well-known/acme-challenge/{{ file_name }}"

[[hook]]
name = "http-01-echo-chmod"
type = ["challenge-http-01-clean"]
cmd = "chmod"
args = [
    "a+r",
    "{{ env.HTTP_ROOT | default('/var/www') }}/{{ identifier }}/.well-known/acme-challenge/{{ file_name }}"
]

[[hook]]
name = "http-01-echo-clean"
type = ["challenge-http-01-clean"]
cmd = "rm"
args = [
    "-f",
    "{{ env.HTTP_ROOT | default('/var/www') }}/{{ identifier }}/.well-known/acme-challenge/{{ file_name }}"
]
.Ed
.Pp
The hooks from the previous example can be grouped in order to reduce the number of hooks to define in the certificate.
.Bd -literal -offset indent
[[group]]
name = "http-01-echo-var-www"
hooks = [
    "http-01-echo-mkdir",
    "http-01-echo-echo",
    "http-01-echo-chmod",
    "http-01-echo-clean"
]

[[certificate]]
# Some fields omitted
hooks = ["http-01-echo"]
env.HTTP_ROOT = "/srv/http"
.Ed
.Pp
It is also possible to use
.Xr sendmail 8
in a hook in order to notify someone when the certificate request process is done.
.Bd -literal -offset indent
[[hook]]
name = "email-report"
type = ["post-operation"]
cmd = "sendmail"
args = [
    "-f", "noreply.certs@example.net",
    "contact@example.net"
]
stdin_str = """Subject: Certificate renewal {{ 'succeeded' if is_success else 'failed' }} for {{ identifiers.0 }}

The following certificate has {{ '' if is_success else '*not* ' }}been renewed.
identifiers: {% for ident in identifiers %}{% if not loop.first %}, {% endif %}{{ ident }}{% endfor %}
key type: {{ key_type }}
status: {{ status }}"""
.Ed
.Sh SEE ALSO
.Xr acmed 8 ,
.Xr tacd 8
.Sh STANDARDS
.Bl -hyphen
.It
.Rs
.%A Tom Preston-Werner
.%D July 2018
.%T TOML v0.5.0
.%U https://toml.io/en/v0.5.0
.Re
.It
.Rs
.%A Armin Ronacher
.%T MiniJinja
.%U https://docs.rs/minijinja/latest/minijinja/syntax/index.html
.Re
.It
.Rs
.%A M. Jones
.%D May 2015
.%R RFC 7518
.%T JSON Web Algorithms (JWA)
.Re
.El
.Sh AUTHORS
.An Rodolphe Bréard
.Aq rodolphe@breard.tf