Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
ACMED.TOML(5)		  FreeBSD File Formats Manual		 ACMED.TOML(5)

NAME
     acmed.toml	-- ACMEd configuration file

DESCRIPTION
     acmed.toml	is the configuration file for acmed(8).	 It is written in the
     TOML format. The allowed elements are described below.

     include
	     Array containing the path to configuration	file to	include. The
	     path can be either	relative or absolute. If relative, it is rela-
	     tive to the configuration file which included it.

	     In	case or	overlapping global option definition, the one of the
	     last included file	will be	used. For example, if a	file A in-
	     cludes files B and	C and all three	defines	the same global	op-
	     tion, the final value will	be the one defined in file C.

     global  Table containing the global configuration options.

	     accounts_directory	string
		     Specify the directory where the accounts private and pub-
		     lic keys are stored.

	     certificates_directory string
		     Specify the directory where the certificates and their
		     associated	private	keys are stored.

	     cert_file_mode integer
		     Specify the permissions to	use for	newly-created certifi-
		     cates files. See chmod(2) for more	details.

	     cert_file_user user_id string
		     Specify the user who will own newly-created certificates
		     files. See	chown(2) for more details.

	     cert_file_group group_id string
		     Specify the group who will	own newly-created certificates
		     files. See	chown(2) for more details.

	     env table
		     Table of environment variables that will be accessible
		     from hooks.

	     pk_file_mode integer
		     Specify the permissions to	use for	newly-created private-
		     key files.	See chmod(2) for more details.

	     pk_file_user user_id string
		     Specify the user who will own newly-created private-key
		     files. See	chown(2) for more details.

	     pk_file_group group_id string
		     Specify the group who will	own newly-created private-key
		     files. See	chown(2) for more details.

     rate-limit
	     Array of table where each element defines a HTTPS rate limit.

	     name string
		     The name the rate limit is	registered under. Must be
		     unique.

	     number integer
		     Number of requests	authorized withing the time period.

	     period string
		     Period of time during which a maximal number of requests
		     is	authorized. The	format is described in the TIME
		     PERIODS section.

     endpoint
	     Array of table where each element defines a Certificate Authority
	     (CA) which	may be used to request certificates.

	     name string
		     The name the endpoint is registered under.	Must be
		     unique.

	     rate_limits array
		     Array containing the names	of the HTTPS rate limits to
		     apply.

	     tos_agreed	boolean
		     Set whether or not	the user agrees	to the Terms Of	Ser-
		     vice (TOS).

	     url string
		     The endpoint's directory URL.

     hook    Array of table where each element defines a command that will be
	     launched at a defined point. See section WRITING A	HOOK for more
	     details.

	     allow_failure 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.

	     name string
		     The name the hook is registered under. Must be unique.

	     hook_type array
		     Array of strings. Possible	types are:
		     -	 challenge-http-01
		     -	 challenge-http-01-clean
		     -	 challenge-dns-01
		     -	 challenge-dns-01-clean
		     -	 challenge-tls-alpn-01
		     -	 challenge-tls-alpn-01-clean
		     -	 file-pre-create
		     -	 file-pre-edit
		     -	 file-post-create
		     -	 file-post-edit
		     -	 post-operation

	     cmd string
		     The name of the command that will be launched.

	     args array
		     Array of strings representing the command's arguments.

	     stdin string
		     Path to the file that will	be written into	the command's
		     standard intput. Mutually exclusive with stdin_str.

	     stdin_str string
		     String that will be written into the command's standard
		     input. Mutually exclusive with stdin.

	     stdout string
		     Path to the file where the	command's standard output if
		     written.

	     stderr string
		     Path to the file where the	command's standard error out-
		     put if written.

     group   Array of table allowing to	group several hooks as one. A group is
	     considered	as new hook.

	     name string
		     The name the group	is registered under. This name is con-
		     sidered as	a hook name. Must be unique.

	     hooks array
		     Array containing the names	of the hooks that are grouped.
		     The hooks are guaranteed to be called sequentially	in the
		     declaration order.

     account
	     Array of table representing an account on one or several CA.

	     name string
		     The name the account is registered	under. Must be unique.

	     email string
		     The email address used to contact the account's holder.

     certificate
	     Array of table representing a certificate that will be requested
	     to	a CA.

	     account string
		     Name of the account to use.

	     endpoint string
		     Name of the endpoint to use.

	     env table
		     Table of environment variables that will be accessible
		     from hooks.

	     domains array
		     Array of tables listing the domains that should be	in-
		     cluded in the certificate along with the challenge	to use
		     for each one.

		     challenge string
			     The name of the challenge to use to prove the do-
			     main's ownership. Possible	values are:
			     -	 http-01
			     -	 dns-01
			     -	 tls-alpn-01

		     dns string
			     The domain	name.

		     env table
			     Table of environment variables that will be ac-
			     cessible from hooks.

	     algorithm string
		     Name of the asymetric cryptography	algorithm used to gen-
		     erate the certificate's key pair. Possible	values are :
		     -	 rsa2048 <default>
		     -	 rsa4096
		     -	 ecdsa_p256
		     -	 ecdsa_p384

	     kp_reuse boolean
		     Set whether or not	the private key	should be reused when
		     renewing the certificate. Default is false.

	     directory string
		     Path to the directory where certificates and their	asso-
		     ciated private keys are stored.

	     hooks array
		     Names of hooks that will be called	when requesting	a new
		     certificate. The hooks are	guaranteed to be called	se-
		     quentially	in the declaration order.

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 ar-
     chiving: although several default methods can be implemented, sometimes
     admins wants or are required to do	it in a	different way.

     In	order to allow a full automation of the	three above steps without im-
     posing arbitrary restrictions or methods, acmed(8)	uses hooks. Fundamen-
     tally, a hook is a	command	line template that will	be called at a spe-
     cific time	of the process.	Such approach allows admins to use any exe-
     cutable script or program located on the machine to customize the
     process.

     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.

     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.

     When writing a hook, the values of	args, stdin, stdin_str,	stdout and
     stderr are	considered as template strings whereas cmd is not. The tem-
     plate syntax is Handlebars.  See the STANDARDS section for	a link to the
     Handlebars	specifications.

     The available types and the associated template variable are described
     below.

     challenge-http-01
	     Invoked when the ownership	of a domain must be proved using the
	     http-01 challenge.	The available template variables are:
	     challenge string
		     The name of the challenge type <http-01>.	Mostly used in
		     hooks with	multiple types.
	     domain string
		     The domain	name whom ownership is currently being vali-
		     dated.
	     env array
		     Array containing all the environment variables.
	     file_name string
		     Name of the file containing the proof. This is not	a full
		     path and does not include the
		     `.well-known/acme-challenge/' prefix.
	     is_clean_hook bool
		     False
	     proof string
		     The content of the	proof that must	be written to
		     file_name.

     challenge-http-01-clean
	     Invoked once a domain ownership has been proven using the 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 challenge-http-01 hook, ex-
	     cepted is_clean_hook which	is set to true.

     challenge-dns-01
	     Invoked when the ownership	of a domain must be proved using the
	     dns-01 challenge. The available template variables	are:
	     challenge string
		     The name of the challenge type <dns-01>.  Mostly used in
		     hooks with	multiple types.
	     domain string
		     The domain	name whom ownership is currently being vali-
		     dated.
	     env array
		     Array containing all the environment variables.
	     is_clean_hook bool
		     False
	     proof string
		     The content of the	proof that must	be written to a	`TXT'
		     entry of the DNS zone for the `_acme-challenge' subdo-
		     main.

     challenge-dns-01-clean
	     Invoked once a domain ownership has been proven using the 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 challenge-dns-01 hook,	ex-
	     cepted is_clean_hook which	is set to true.

     challenge-tls-alpn-01
	     Invoked when the ownership	of a domain must be proved using the
	     tls-alpn-01 challenge. The	available template variables are:
	     challenge string
		     The name of the challenge type <tls-alpn-01>.  Mostly
		     used in hooks with	multiple types.
	     domain string
		     The domain	name whom ownership is currently being vali-
		     dated.
	     env array
		     Array containing all the environment variables.
	     is_clean_hook bool
		     False
	     proof string
		     Plain-text	representation of the acmeIdentifier extension
		     that should be used in the	self-signed certificate	pre-
		     sented when a TLS connection is initiated with the	ALPN
		     extension value.  acmed(8)	will not generate the certifi-
		     cate itself since it can be done using tacd(8).

     challenge-tls-alpn-01-clean
	     Invoked once a domain ownership has been proven using the
	     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
	     challenge-tls-alpn-01 hook, excepted is_clean_hook	which is set
	     to	true.

     file-pre-create
	     Invoked before a non-existent file	created.  The available	tem-
	     plate variables are:
	     env array
		     Array containing all the environment variables.
	     file_directory string
		     Name of the directory where the impacted file is located.
	     file_name string
		     Name of the impacted file.
	     file_path string
		     Full path to the impacted file.

     file-pre-edit
	     Invoked before an existent	file modified.	The available template
	     variables are the same as those available for the file-pre-create
	     type.

     file-post-create
	     Invoked after a non-existent file created.	 The available tem-
	     plate variables are the same as those available for the
	     file-pre-create type.

     file-post-edit
	     Invoked after an existent file modified.  The available template
	     variables are the same as those available for the file-pre-create
	     type.

     post-operation
	     Invoked at	the end	of the certificate request process. The	avail-
	     able template variables are:
	     algorithm string
		     Name of the algorithm used	in the certificate.
	     domains string
		     Array containing the domain names included	in the re-
		     quested certificate.
	     env array
		     Array containing all the environment variables.
	     is_success	boolean
		     True if the certificate request is	successful.
	     status string
		     Human-readable status. If the certificate request failed,
		     it	contains the error description.

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.

     git     This hook uses git(1) to archive private keys, public keys	and
	     certificates. It is possible to customize the commit username and
	     email by using respectively the GIT_USERNAME and GIT_EMAIL	envi-
	     ronment variables.

     http-01-echo
	     This hook is designed to solve the	http-01	challenge. For this
	     purpose, it will write the	proof into
	     {{env.HTTP_ROOT}}/{{domain}}/.well-known/acme-challenge/{{file_name}}.

	     The web server must be configured so the file
	     http://{{domain}}/.well-known/acme-challenge/{{file_name}}	can be
	     accessed from the CA.

	     If	HTTP_ROOT is not specified, it will be set to /var/www.

     tls-alpn-01-tacd-tcp
	     This hook is designed to solve the	tls-alpn-01 challenge using
	     tacd(8).  It requires pkill(1) to support the -F option.

	     tacd(8) will listen on the	host defined by	the TACD_HOST environ-
	     ment variable (default is the domain to be	validated) and on the
	     port defined by the TACD_PORT environment variable	(default is
	     5001).

	     tacd(8) will store	its pid	into
	     {{TACD_PID_ROOT}}/tacd_{{domain}}.pid.  If	TACD_PID_ROOT is not
	     specified,	it will	be set to /run.

     tls-alpn-01-tacd-unix
	     This hook is designed to solve the	tls-alpn-01 challenge using
	     tacd(8).  It requires pkill(1) to support the -F option.

	     tacd(8) will listen on the	unix socket
	     {{env.TACD_SOCK_ROOT}}/tacd_{{domain}}.sock.  If TACD_SOCK_ROOT
	     is	not specified, it will be set to /run.

	     tacd(8) will store	its pid	into
	     {{TACD_PID_ROOT}}/tacd_{{domain}}.pid.  If	TACD_PID_ROOT is not
	     specified,	it will	be set to /run.

TIME PERIODS
     ACMEd uses	its own	time period format, which is vaguely inspired by the
     ISO 8601 one. Periods are formatted as PM[PM...] where M is case sensi-
     tive character representing a length and P	is an integer representing a
     multiplayer for the following length. The authorized length are:
     -	 s: second
     -	 m: minute
     -	 h: hour
     -	 d: day
     -	 w: week
     The PM couples can	be specified multiple times and	in any order.

     For example, "1d42s and" "40s20h4h2s" both	represents a period of one day
     and forty-two seconds.

FILES
     /etc/acmed/acmed.toml
	     Default acmed(8) configuration file.

     /etc/acmed/accounts
	     Default accounts private and public keys directory.

     /etc/acmed/certs
	     Default certificates and associated private keys directory.

EXAMPLES
     The following example defines a typical endpoint, account and certificate
     for a domain and several subdomains.

	   [[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"

     It	is possible to use echo(1) to solve the	http-01	challenge and rm(1) to
     clean it.	mkdir(1) and chmod(1) are used to prevent issues related to
     file access.

	   [[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}}"
	   ]

     The hooks from the	previous example can be	grouped	in order to reduce the
     number of hooks to	define in the certificate.

	   [[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"

     It	is also	possible to use	sendmail(8) in a hook in order to notif	some-
     one when the certificate request process is done.

	   [[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}}"""

SEE ALSO
     acmed(8), tacd(8)

STANDARDS
     Tom Preston-Werner, TOML v0.5.0, https://github.com/toml-lang/toml, July
     2018.
     Yehuda Katz, Handlebars, https://handlebarsjs.com/.

AUTHORS
     Rodolphe BrA(C)ard	<rodolphe@breard.tf>

FreeBSD	13.0			March 12, 2020			  FreeBSD 13.0

NAME | DESCRIPTION | WRITING A HOOK | DEFAULT HOOKS | TIME PERIODS | FILES | EXAMPLES | SEE ALSO | STANDARDS | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=acmed.toml&sektion=5&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help