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

FreeBSD Manual Pages

  
 
  

home | help
ACMED.TOML(5)		    BSD	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.

	     Unix style	globing	is supported.

     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 username|user_id string
		     Specify the user who will own newly-created certificates
		     files. See	chown(2) for more details.

	     cert_file_group group_name|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 username|user_id string
		     Specify the user who will own newly-created private-key
		     files. See	chown(2) for more details.

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

	     renew_delay string
		     Period of time between the	certificate renewal and	its
		     expiration	date. The format is described in the TIME
		     PERIODS section. Default is 3w.

	     root_certificates array
		     Array containing the path to root certificates that
		     should be added to	the trust store.

     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.

	     renew_delay string
		     Period of time between the	certificate renewal and	its
		     expiration	date. The format is described in the TIME
		     PERIODS section. Default is the value defined in the
		     global section.

	     root_certificates array
		     Array containing the path to root certificates that
		     should be added to	the trust store.

     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.

	     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 end-
	     point.

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

	     contacts 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 as-
		     sociated values are:

		     mailto string
			     A mailto URI as defined by	RFC 6068.  This	URI
			     cannot contains neither "hfields" nor more	than
			     one "addr-spec" in	the "to" component.

	     key_type string
		     Name of the asymmetric cryptography algorithm used	to
		     generate the key pair. Possible values are:
		     -	 rsa2048
		     -	 rsa4096
		     -	 ecdsa_p256 <default>
		     -	 ecdsa_p384
		     -	 ecdsa_p521

	     signature_algorithm string
		     Name of the signature algorithm used to sign the messages
		     sent to the endpoint as defined in	RFC 7518.  The default
		     value is derived from the key type. Possible values are:
		     -	 RS256
		     -	 ES256
		     -	 ES384
		     -	 ES512

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

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

	     external_account table
		     Table containing the information required to bind the ac-
		     count to an external one. Possible	fields and values are:

		     identifier	string
			     ASCII string identifying the key.

		     key string
			     Private key encoded in base64url without padding.

		     signature_algorithm string
			     Name of the signature algorithm used to sign the
			     external account binding message sent to the end-
			     point as defined in RFC 7518.  Possible values
			     are:
			     -	 HS256 <default>
			     -	 HS384
			     -	 HS512

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

	     Note that certificates are	identified by the first	identifier in
	     the list of identifiers. That means that if you reorder the iden-
	     tifiers so	that a different identifier is at the first position,
	     a new certificate with a new name will be issued.

	     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.

	     identifiers array
		     Array of tables listing the identifiers that should be
		     included in the certificate along with the	challenge to
		     use for each one. The dns and ip fields are mutually ex-
		     clusive.

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

		     dns string
			     The domain	name.

		     ip	string
			     The IP address.

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

	     subject_attributes	table
		     Table where the certificate's subject attributes are
		     specified.	Possible keys are:
		     -	 country_name
		     -	 locality_name
		     -	 state_or_province_name
		     -	 street_address
		     -	 organization_name
		     -	 organizational_unit_name
		     -	 name
		     -	 given_name
		     -	 initials
		     -	 title
		     -	 surname
		     -	 pseudonym
		     -	 generation_qualifier
		     -	 friendly_name

	     key_type string
		     Name of the asymmetric cryptography algorithm used	to
		     generate the certificate's	key pair. Possible values are:
		     -	 rsa2048 <default>
		     -	 rsa4096
		     -	 ecdsa_p256
		     -	 ecdsa_p384
		     -	 ecdsa_p521

	     csr_digest	string
		     Name of the certificate's signing request digest algo-
		     rithm. Possible values are:
		     -	 sha256	<default>
		     -	 sha384
		     -	 sha512

	     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.

	     renew_delay string
		     Period of time between the	certificate renewal and	its
		     expiration	date. The format is described in the TIME
		     PERIODS section. Default is the value defined in the as-
		     sociated endpoint.

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	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 full automation of the three above steps	without	impos-
     ing 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 an	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 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.

     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 an identifier 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.
	     identifier	string
		     The identifier name whom ownership	is currently being
		     validated.
	     identifier_tls_alpn string
		     The identifier name whom ownership	is currently being
		     validated,	in a form suitable for the TLS ALPN challenge.
	     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 an identifier	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, excepted is_clean_hook which is set to
	     true.

     challenge-dns-01
	     Invoked when the ownership	of an identifier 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.
	     identifier	string
		     The identifier name whom ownership	is currently being
		     validated.
	     identifier_tls_alpn string
		     The identifier name whom ownership	is currently being
		     validated,	in a form suitable for the TLS ALPN challenge.
	     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 an identifier	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, excepted is_clean_hook which	is set to true.

     challenge-tls-alpn-01
	     Invoked when the ownership	of an identifier 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.
	     identifier	string
		     The identifier name whom ownership	is currently being
		     validated.
	     identifier_tls_alpn string
		     The identifier name whom ownership	is currently being
		     validated,	in a form suitable for the TLS ALPN challenge.
	     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 an identifier	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:
	     key_type string
		     Name of the asymmetric cryptography algorithm used	to
		     generate the certificate's	key pair.
	     identifiers string
		     Array containing the identifiers 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}}/{{identifier}}/.well-known/acme-challenge/{{file_name}}.

	     The web server must be configured so the file
	     http://{{identifier}}/.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 identifier 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_{{identifier}}.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_{{identifier}}.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_{{identifier}}.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, several subdomains and an IP	address.

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

     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}}/{{identifier}}/.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}}/{{identifier}}/.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}}/{{identifier}}/.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}}/{{identifier}}/.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 {{identifiers.[0]}}

	   The following certificate has {{#unless is_success}}*not* {{/unless}}been renewed.
	   identifiers:	{{#each	identifiers}}{{#if @index}}, {{/if}}{{this}}{{/each}}
	   key type: {{key_type}}
	   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/.

     -	 M. Jones, JSON	Web Algorithms (JWA), RFC 7518,	May 2015.

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

BSD			       October 10, 2020				   BSD

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+13.0-RELEASE+and+Ports>

home | help