mirror of https://github.com/breard-r/acmed.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
585 lines
18 KiB
585 lines
18 KiB
.\" Copyright (c) 2019 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 May 9, 2019
|
|
.Dt ACMED.TOML 5
|
|
.Os
|
|
.Sh NAME
|
|
.Nm acmed.toml
|
|
.Nd ACMEd configuration file
|
|
.Sh DESCRIPTION
|
|
.Nm
|
|
is the configuration file for
|
|
.Xr acmed 8 .
|
|
It is written in the
|
|
.Em TOML
|
|
format. The allowed elements are described below.
|
|
.Bl -tag
|
|
.It Ic include
|
|
Array containing the path to configuration file to include. The path can be either relative or absolute. If relative, it is relative to the configuration file which included it.
|
|
.Pp
|
|
In case or overlapping global option definition, the one of the last included file will be used. For example, if a file
|
|
.Em A
|
|
includes files
|
|
.Em B
|
|
and
|
|
.Em C
|
|
and all three defines the same global option, the final value will be the one defined in file
|
|
.Em C .
|
|
.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 certificates_directory Ar string
|
|
Specify the directory where the certificates and their associated private keys are stored.
|
|
.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 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_group Ar group_id Ft string
|
|
Specify the group who will own newly-created certificates files. See
|
|
.Xr chown 2
|
|
for more details.
|
|
.It Ic env Ar table
|
|
Table of environment variables that will be accessible from hooks.
|
|
.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 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_group Ar group_id Ft string
|
|
Specify the group who will own newly-created private-key files. See
|
|
.Xr chown 2
|
|
for more details.
|
|
.El
|
|
.It Ic endpoint
|
|
Array of table where each element defines a Certificate Authority
|
|
.Pq CA
|
|
which may be used to request certificates.
|
|
.Bl -tag
|
|
.It Cm name Ar string
|
|
The name the endpoint is registered under. Must be unique.
|
|
.It Cm url Ar string
|
|
The endpoint's directory URL.
|
|
.It Cm tos_agreed Ar boolean
|
|
Set whether or not the user agrees to the Terms Of Service
|
|
.Pq TOS .
|
|
.El
|
|
.It Ic hook
|
|
Array of table where each element defines a command that will be launched at a defined point. See section
|
|
.Sx WRITING A HOOK
|
|
for more details.
|
|
.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 Cm name Ar string
|
|
The name the hook is registered under. Must be unique.
|
|
.It Cm hook_type Ar array
|
|
Array of strings. Possible types are:
|
|
.Bl -dash -compact
|
|
.It
|
|
challenge-http-01
|
|
.It
|
|
challenge-http-01-clean
|
|
.It
|
|
challenge-dns-01
|
|
.It
|
|
challenge-dns-01-clean
|
|
.It
|
|
challenge-tls-alpn-01
|
|
.It
|
|
challenge-tls-alpn-01-clean
|
|
.It
|
|
file-pre-create
|
|
.It
|
|
file-pre-edit
|
|
.It
|
|
file-post-create
|
|
.It
|
|
file-post-edit
|
|
.It
|
|
post-operation
|
|
.El
|
|
.It Ic cmd Ar string
|
|
The name of the command that will be launched.
|
|
.It Ic args Ar array
|
|
Array of strings representing the command's arguments.
|
|
.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 Ic stderr Ar string
|
|
Path to the file where the command's standard error output if written.
|
|
.El
|
|
.It Ic group
|
|
Array of table allowing to group several hooks as one. A group is considered as new hook.
|
|
.Bl -tag
|
|
.It Cm name Ar string
|
|
The name the group is registered under. This name is considered as a hook name. Must be unique.
|
|
.It Cm hooks Ar array
|
|
Array containing the names of the hooks that are grouped. The hooks are guaranteed to be called sequentially in the declaration order.
|
|
.El
|
|
.It Ic account
|
|
Array of table representing an account on one or several CA.
|
|
.Bl -tag
|
|
.It Ic name Ar string
|
|
The name the account is registered under. Must be unique.
|
|
.It Ic email Ar string
|
|
The email address used to contact the account's holder.
|
|
.El
|
|
.It Ic certificate
|
|
Array of table representing a certificate that will be requested to a CA.
|
|
.Bl -tag
|
|
.It Ic account Ar string
|
|
Name of the account to use.
|
|
.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 domains Ar array
|
|
Array of tables listing the domains that should be included in the certificate along with the challenge to use for each one.
|
|
.Bl -tag
|
|
.It Ic challenge Ar string
|
|
The name of the challenge to use to prove the domain's ownership. Possible values are:
|
|
.Bl -dash -compact
|
|
.It
|
|
http-01
|
|
.It
|
|
dns-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.
|
|
.El
|
|
.It Ic algorithm Ar string
|
|
Name of the asymetric cryptography algorithm used to generate the certificate's key pair. Possible values are :
|
|
.Bl -dash -compact
|
|
.It
|
|
rsa2048
|
|
.Aq default
|
|
.It
|
|
rsa4096
|
|
.It
|
|
ecdsa_p256
|
|
.It
|
|
ecdsa_p384
|
|
.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 directory Ar string
|
|
Path to the directory where certificates and their associated private keys are stored.
|
|
.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.
|
|
.El
|
|
.Sh WRITING A HOOK
|
|
When requesting a certificate to a CA using ACME, there is three steps that are hard to automatize. The first one is solving challenges in order to prove the ownership of every domains 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 uses 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 a 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 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 have 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 Handlebars .
|
|
See the
|
|
.Sx STANDARDS
|
|
section for a link to the
|
|
.Em Handlebars
|
|
specifications.
|
|
.Pp
|
|
The available types and the associated template variable are described below.
|
|
.Bl -tag
|
|
.It Ic challenge-http-01
|
|
Invoked when the ownership of a domain 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 domain Ar string
|
|
The domain name whom ownership is currently being validated.
|
|
.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 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 a domain 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-dns-01
|
|
Invoked when the ownership of a domain 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 domain Ar string
|
|
The domain name whom ownership is currently being validated.
|
|
.It Cm env Ar array
|
|
Array containing all the environment variables.
|
|
.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 a domain 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-tls-alpn-01
|
|
Invoked when the ownership of a domain 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 domain Ar string
|
|
The domain name whom ownership is currently being validated.
|
|
.It Cm env Ar array
|
|
Array containing all the environment variables.
|
|
.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 .
|
|
.El
|
|
.It Ic challenge-tls-alpn-01-clean
|
|
Invoked once a domain 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-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 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 post-operation
|
|
Invoked at the end of the certificate request process. The available template variables are:
|
|
.Bl -tag -compact
|
|
.It Cm algorithm Ar string
|
|
Name of the algorithm used in the certificate.
|
|
.It Cm domains Ar string
|
|
Array containing the domain names included in the requested certificate.
|
|
.It Cm env Ar array
|
|
Array containing all the environment variables.
|
|
.It Cm is_success Ar boolean
|
|
True if the certificate request is successful.
|
|
.It Cm status Ar string
|
|
Human-readable status. If the certificate request failed, it contains the error description.
|
|
.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}}/{{domain}}/.well-known/acme-challenge/{{file_name}} .
|
|
.Pp
|
|
The web server must be configured so the file
|
|
.Pa http://{{domain}}/.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 Ar -F
|
|
option.
|
|
.Pp
|
|
.Xr tacd 8
|
|
will listen on the host defined by the
|
|
.Ev TACD_HOST
|
|
environment variable (default is the domain 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_{{domain}}.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 Ar -F
|
|
option.
|
|
.Pp
|
|
.Xr tacd 8
|
|
will listen on the unix socket
|
|
.Pa {{env.TACD_SOCK_ROOT}}/tacd_{{domain}}.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_{{domain}}.pid .
|
|
If
|
|
.Ev TACD_PID_ROOT
|
|
is not specified, it will be set to
|
|
.Pa /run .
|
|
.El
|
|
.Sh FILES
|
|
.Bl -tag
|
|
.It Pa /etc/acmed/acmed.toml
|
|
Default
|
|
.Xr acmed 8
|
|
configuration file.
|
|
.It Pa /etc/acmed/accounts
|
|
Default accounts private and public keys directory.
|
|
.It Pa /etc/acmed/certs
|
|
Default certificates and associated private keys directory.
|
|
.Sh EXAMPLES
|
|
The following example defines a typical endpoint, account and certificate for a domain and several subdomains.
|
|
.Bd -literal -offset indent
|
|
[[endpoint]]
|
|
name = "example name"
|
|
url = "https://acme.example.org/directory"
|
|
tos_agreed = true
|
|
|
|
[[account]]
|
|
name = "my test account"
|
|
email = "certs@exemple.net"
|
|
|
|
[[certificate]]
|
|
endpoint = "example name"
|
|
account = "my test account"
|
|
domains = [
|
|
{ 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"},
|
|
]
|
|
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", "{{%if env.HTTP_ROOT}}{{env.HTTP_ROOT}}{{else}}/var/www{{/if}}/{{domain}}/.well-known/acme-challenge"
|
|
]
|
|
|
|
[[hook]]
|
|
name = "http-01-echo-echo"
|
|
type = ["challenge-http-01"]
|
|
cmd = "echo"
|
|
args = ["{{proof}}"]
|
|
stdout = "{{%if env.HTTP_ROOT}}{{env.HTTP_ROOT}}{{else}}/var/www{{/if}}/{{domain}}/.well-known/acme-challenge/{{file_name}}"
|
|
|
|
[[hook]]
|
|
name = "http-01-echo-chmod"
|
|
type = ["challenge-http-01-clean"]
|
|
cmd = "chmod"
|
|
args = [
|
|
"a+r",
|
|
"{{%if env.HTTP_ROOT}}{{env.HTTP_ROOT}}{{else}}/var/www{{/if}}/{{domain}}/.well-known/acme-challenge/{{file_name}}"
|
|
]
|
|
|
|
[[hook]]
|
|
name = "http-01-echo-clean"
|
|
type = ["challenge-http-01-clean"]
|
|
cmd = "rm"
|
|
args = [
|
|
"-f",
|
|
"{{%if env.HTTP_ROOT}}{{env.HTTP_ROOT}}{{else}}/var/www{{/if}}/{{domain}}/.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 notif 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 {{#if is_success}}succeeded{{else}}failed{{/if}} for {{domains.[0]}}
|
|
|
|
The following certificate has {{#unless is_success}}*not* {{/unless}}been renewed.
|
|
domains: {{#each domains}}{{#if @index}}, {{/if}}{{this}}{{/each}}
|
|
algorithm: {{algorithm}}
|
|
status: {{status}}"""
|
|
.Ed
|
|
.Sh SEE ALSO
|
|
.Xr acmed 8 ,
|
|
.Xr tacd 8
|
|
.Sh STANDARDS
|
|
.Bl
|
|
.It
|
|
.Rs
|
|
.%A Tom Preston-Werner
|
|
.%D July 2018
|
|
.%T TOML v0.5.0
|
|
.%U https://github.com/toml-lang/toml
|
|
.Re
|
|
.It
|
|
.Rs
|
|
.%A Yehuda Katz
|
|
.%T Handlebars
|
|
.%U https://handlebarsjs.com/
|
|
.Re
|
|
.El
|
|
.Sh AUTHORS
|
|
.An Rodolphe Bréard
|
|
.Aq rodolphe@breard.tf
|