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.

735 lines
22 KiB

5 years ago
4 years ago
  1. .\" Copyright (c) 2019-2020 Rodolphe Bréard <rodolphe@breard.tf>
  2. .\"
  3. .\" Copying and distribution of this file, with or without modification,
  4. .\" are permitted in any medium without royalty provided the copyright
  5. .\" notice and this notice are preserved. This file is offered as-is,
  6. .\" without any warranty.
  7. .Dd September 19, 2020
  8. .Dt ACMED.TOML 5
  9. .Os
  10. .Sh NAME
  11. .Nm acmed.toml
  12. .Nd ACMEd configuration file
  13. .Sh DESCRIPTION
  14. .Nm
  15. is the configuration file for
  16. .Xr acmed 8 .
  17. It is written in the
  18. .Em TOML
  19. format. The allowed elements are described below.
  20. .Bl -tag
  21. .It Ic include
  22. 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.
  23. .Pp
  24. In case or overlapping global option definition, the one of the last included file will be used. For example, if a file
  25. .Em A
  26. includes files
  27. .Em B
  28. and
  29. .Em C
  30. and all three defines the same global option, the final value will be the one defined in file
  31. .Em C .
  32. .Pp
  33. Unix style globing is supported.
  34. .It Ic global
  35. Table containing the global configuration options.
  36. .Bl -tag
  37. .It Cm accounts_directory Ar string
  38. Specify the directory where the accounts private and public keys are stored.
  39. .It Cm certificates_directory Ar string
  40. Specify the directory where the certificates and their associated private keys are stored.
  41. .It Cm cert_file_mode Ar integer
  42. Specify the permissions to use for newly-created certificates files. See
  43. .Xr chmod 2
  44. for more details.
  45. .It Cm cert_file_user Ar username|user_id Ft string
  46. Specify the user who will own newly-created certificates files. See
  47. .Xr chown 2
  48. for more details.
  49. .It Cm cert_file_group Ar group_name|group_id Ft string
  50. Specify the group who will own newly-created certificates files. See
  51. .Xr chown 2
  52. for more details.
  53. .It Ic env Ar table
  54. Table of environment variables that will be accessible from hooks.
  55. .It Cm pk_file_mode Ar integer
  56. Specify the permissions to use for newly-created private-key files. See
  57. .Xr chmod 2
  58. for more details.
  59. .It Cm pk_file_user Ar username|user_id Ft string
  60. Specify the user who will own newly-created private-key files. See
  61. .Xr chown 2
  62. for more details.
  63. .It Cm pk_file_group Ar group_name|group_id Ft string
  64. Specify the group who will own newly-created private-key files. See
  65. .Xr chown 2
  66. for more details.
  67. .It Cm renew_delay Ar string
  68. Period of time between the certificate renewal and its expiration date. The format is described in the
  69. .Sx TIME PERIODS
  70. section. Default is 3w.
  71. .El
  72. .It Ic rate-limit
  73. Array of table where each element defines a HTTPS rate limit.
  74. .Bl -tag
  75. .It Cm name Ar string
  76. The name the rate limit is registered under. Must be unique.
  77. .It Cm number Ar integer
  78. Number of requests authorized withing the time period.
  79. .It Cm period Ar string
  80. Period of time during which a maximal number of requests is authorized. The format is described in the
  81. .Sx TIME PERIODS
  82. section.
  83. .El
  84. .It Ic endpoint
  85. Array of table where each element defines a Certificate Authority
  86. .Pq CA
  87. which may be used to request certificates.
  88. .Bl -tag
  89. .It Cm name Ar string
  90. The name the endpoint is registered under. Must be unique.
  91. .It Cm rate_limits Ar array
  92. Array containing the names of the HTTPS rate limits to apply.
  93. .It Cm tos_agreed Ar boolean
  94. Set whether or not the user agrees to the Terms Of Service
  95. .Pq TOS .
  96. .It Cm url Ar string
  97. The endpoint's directory URL.
  98. .It Cm renew_delay Ar string
  99. Period of time between the certificate renewal and its expiration date. The format is described in the
  100. .Sx TIME PERIODS
  101. section. Default is the value defined in the global section.
  102. .El
  103. .It Ic hook
  104. Array of table where each element defines a command that will be launched at a defined point. See section
  105. .Sx WRITING A HOOK
  106. for more details.
  107. .Bl -tag
  108. .It Cm allow_failure Ar boolean
  109. 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.
  110. .It Cm name Ar string
  111. The name the hook is registered under. Must be unique.
  112. .It Cm type Ar array
  113. Array of strings. Possible types are:
  114. .Bl -dash -compact
  115. .It
  116. challenge-http-01
  117. .It
  118. challenge-http-01-clean
  119. .It
  120. challenge-dns-01
  121. .It
  122. challenge-dns-01-clean
  123. .It
  124. challenge-tls-alpn-01
  125. .It
  126. challenge-tls-alpn-01-clean
  127. .It
  128. file-pre-create
  129. .It
  130. file-pre-edit
  131. .It
  132. file-post-create
  133. .It
  134. file-post-edit
  135. .It
  136. post-operation
  137. .El
  138. .It Ic cmd Ar string
  139. The name of the command that will be launched.
  140. .It Ic args Ar array
  141. Array of strings representing the command's arguments.
  142. .It Ic stdin Ar string
  143. Path to the file that will be written into the command's standard intput. Mutually exclusive with
  144. .Em stdin_str .
  145. .It Ic stdin_str Ar string
  146. String that will be written into the command's standard input. Mutually exclusive with
  147. .Em stdin .
  148. .It Ic stdout Ar string
  149. Path to the file where the command's standard output if written.
  150. .It Ic stderr Ar string
  151. Path to the file where the command's standard error output if written.
  152. .El
  153. .It Ic group
  154. Array of table allowing to group several hooks as one. A group is considered as new hook.
  155. .Bl -tag
  156. .It Cm name Ar string
  157. The name the group is registered under. This name is considered as a hook name. Must be unique.
  158. .It Cm hooks Ar array
  159. Array containing the names of the hooks that are grouped. The hooks are guaranteed to be called sequentially in the declaration order.
  160. .El
  161. .It Ic account
  162. Array of table representing an account on one or several endpoint.
  163. .Bl -tag
  164. .It Ic name Ar string
  165. The name the account is registered under. Must be unique.
  166. .It Ic contacts Ar array
  167. 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:
  168. .Bl -tag
  169. .It Ic mailto Ar string
  170. A mailto URI as defined by
  171. .Em RFC 6068 .
  172. This URI cannot contains neither "hfields" nor more than one "addr-spec" in the "to" component.
  173. .El
  174. .It Cm key_type Ar string
  175. Name of the asymmetric cryptography algorithm used to generate the key pair. Possible values are :
  176. .Bl -dash -compact
  177. .It
  178. rsa2048
  179. .It
  180. rsa4096
  181. .It
  182. ecdsa_p256
  183. .Aq default
  184. .It
  185. ecdsa_p384
  186. .El
  187. .It Cm signature_algorithm Ar string
  188. Name of the signature algorithm used to sign the messages sent to the endpoint as defined in
  189. .Em RFC 7518 .
  190. The default value is derived from the key type. Possible values are:
  191. .Bl -dash -compact
  192. .It
  193. RS256
  194. .It
  195. ES256
  196. .It
  197. ES384
  198. .El
  199. .It Ic env Ar table
  200. Table of environment variables that will be accessible from hooks.
  201. .It Ic hooks Ar array
  202. 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.
  203. .It Ic external_account Ar table
  204. Table containing the information required to bind the account to an external one. Possible fields and values are:
  205. .Bl -tag
  206. .It Ic identifier Ar string
  207. ASCII string identifying the key.
  208. .It Ic key Ar string
  209. Private key encoded in base64url without padding.
  210. .It Ic signature_algorithm Ar string
  211. Name of the signature algorithm used to sign the external account binding message sent to the endpoint as defined in
  212. .Em RFC 7518 .
  213. Possible values are:
  214. .Bl -dash -compact
  215. .It
  216. HS256
  217. .Aq default
  218. .It
  219. HS384
  220. .It
  221. HS512
  222. .El
  223. .El
  224. .El
  225. .It Ic certificate
  226. Array of table representing a certificate that will be requested to a CA.
  227. .Pp
  228. Note that 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.
  229. .Bl -tag
  230. .It Ic account Ar string
  231. Name of the account to use.
  232. .It Ic endpoint Ar string
  233. Name of the endpoint to use.
  234. .It Ic env Ar table
  235. Table of environment variables that will be accessible from hooks.
  236. .It Ic identifiers Ar array
  237. Array of tables listing the identifiers that should be included in the certificate along with the challenge to use for each one. The
  238. .Em dns
  239. and
  240. .Em ip
  241. fields are mutually exclusive.
  242. .Bl -tag
  243. .It Ic challenge Ar string
  244. The name of the challenge to use to prove the identifier's ownership. Possible values are:
  245. .Bl -dash -compact
  246. .It
  247. http-01
  248. .It
  249. dns-01
  250. .It
  251. tls-alpn-01
  252. .El
  253. .It Ic dns Ar string
  254. The domain name.
  255. .It Ic ip Ar string
  256. The IP address.
  257. .It Ic env Ar table
  258. Table of environment variables that will be accessible from hooks.
  259. .El
  260. .It Ic key_type Ar string
  261. Name of the asymmetric cryptography algorithm used to generate the certificate's key pair. Possible values are :
  262. .Bl -dash -compact
  263. .It
  264. rsa2048
  265. .Aq default
  266. .It
  267. rsa4096
  268. .It
  269. ecdsa_p256
  270. .It
  271. ecdsa_p384
  272. .El
  273. .It Ic csr_digest Ar string
  274. Name of the certificate's signing request digest algorithm. Possible values are :
  275. .Bl -dash -compact
  276. .It
  277. sha256
  278. .Aq default
  279. .It
  280. sha384
  281. .It
  282. sha512
  283. .El
  284. .It Ic kp_reuse Ar boolean
  285. Set whether or not the private key should be reused when renewing the certificate. Default is false.
  286. .It Ic directory Ar string
  287. Path to the directory where certificates and their associated private keys are stored.
  288. .It Ic hooks Ar array
  289. Names of hooks that will be called when requesting a new certificate. The hooks are guaranteed to be called sequentially in the declaration order.
  290. .It Cm renew_delay Ar string
  291. Period of time between the certificate renewal and its expiration date. The format is described in the
  292. .Sx TIME PERIODS
  293. section. Default is the value defined in the associated endpoint.
  294. .El
  295. .Sh WRITING A HOOK
  296. 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.
  297. .Pp
  298. In order to allow full automation of the three above steps without imposing arbitrary restrictions or methods,
  299. .Xr acmed 8
  300. 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.
  301. .Pp
  302. 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.
  303. .Pp
  304. 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.
  305. .Pp
  306. When writing a hook, the values of
  307. .Em args ,
  308. .Em stdin ,
  309. .Em stdin_str ,
  310. .Em stdout
  311. and
  312. .Em stderr
  313. are considered as template strings whereas
  314. .Em cmd
  315. is not. The template syntax is
  316. .Em Handlebars .
  317. See the
  318. .Sx STANDARDS
  319. section for a link to the
  320. .Em Handlebars
  321. specifications.
  322. .Pp
  323. The available types and the associated template variable are described below.
  324. .Bl -tag
  325. .It Ic challenge-http-01
  326. Invoked when the ownership of an identifier must be proved using the
  327. .Em http-01
  328. challenge. The available template variables are:
  329. .Bl -tag -compact
  330. .It Cm challenge Ar string
  331. The name of the challenge type
  332. .Aq http-01 .
  333. Mostly used in hooks with multiple types.
  334. .It Cm identifier Ar string
  335. The identifier name whom ownership is currently being validated.
  336. .It Cm identifier_tls_alpn Ar string
  337. The identifier name whom ownership is currently being validated, in a form suitable for the TLS ALPN challenge.
  338. .It Cm env Ar array
  339. Array containing all the environment variables.
  340. .It Cm file_name Ar string
  341. Name of the file containing the proof. This is not a full path and does not include the
  342. .Ql .well-known/acme-challenge/
  343. prefix.
  344. .It Cm is_clean_hook Ar bool
  345. False
  346. .It Cm proof Ar string
  347. The content of the proof that must be written to
  348. .Em file_name .
  349. .El
  350. .It Ic challenge-http-01-clean
  351. Invoked once an identifier ownership has been proven using the
  352. .Em http-01
  353. 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
  354. .Em challenge-http-01
  355. hook, excepted
  356. .Em is_clean_hook
  357. which is set to
  358. .Em true .
  359. .It Ic challenge-dns-01
  360. Invoked when the ownership of an identifier must be proved using the
  361. .Em dns-01
  362. challenge. The available template variables are:
  363. .Bl -tag -compact
  364. .It Cm challenge Ar string
  365. The name of the challenge type
  366. .Aq dns-01 .
  367. Mostly used in hooks with multiple types.
  368. .It Cm identifier Ar string
  369. The identifier name whom ownership is currently being validated.
  370. .It Cm identifier_tls_alpn Ar string
  371. The identifier name whom ownership is currently being validated, in a form suitable for the TLS ALPN challenge.
  372. .It Cm env Ar array
  373. Array containing all the environment variables.
  374. .It Cm is_clean_hook Ar bool
  375. False
  376. .It Cm proof Ar string
  377. The content of the proof that must be written to a
  378. .Ql TXT
  379. entry of the DNS zone for the
  380. .Ql _acme-challenge
  381. subdomain.
  382. .El
  383. .It Ic challenge-dns-01-clean
  384. Invoked once an identifier ownership has been proven using the
  385. .Em dns-01
  386. 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
  387. .Em challenge-dns-01
  388. hook, excepted
  389. .Em is_clean_hook
  390. which is set to
  391. .Em true .
  392. .It Ic challenge-tls-alpn-01
  393. Invoked when the ownership of an identifier must be proved using the
  394. .Em tls-alpn-01
  395. challenge. The available template variables are:
  396. .Bl -tag -compact
  397. .It Cm challenge Ar string
  398. The name of the challenge type
  399. .Aq tls-alpn-01 .
  400. Mostly used in hooks with multiple types.
  401. .It Cm identifier Ar string
  402. The identifier name whom ownership is currently being validated.
  403. .It Cm identifier_tls_alpn Ar string
  404. The identifier name whom ownership is currently being validated, in a form suitable for the TLS ALPN challenge.
  405. .It Cm env Ar array
  406. Array containing all the environment variables.
  407. .It Cm is_clean_hook Ar bool
  408. False
  409. .It Cm proof Ar string
  410. Plain-text representation of the
  411. .Em acmeIdentifier
  412. extension that should be used in the self-signed certificate presented when a TLS connection is initiated with the
  413. .Qd acme-tls/1
  414. ALPN extension value.
  415. .Xr acmed 8
  416. will not generate the certificate itself since it can be done using
  417. .Xr tacd 8 .
  418. .El
  419. .It Ic challenge-tls-alpn-01-clean
  420. Invoked once an identifier ownership has been proven using the
  421. .Em tls-alpn-01
  422. 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
  423. .Em challenge-tls-alpn-01
  424. hook, excepted
  425. .Em is_clean_hook
  426. which is set to
  427. .Em true .
  428. .It Ic file-pre-create
  429. Invoked
  430. .Em before
  431. a non-existent file
  432. .Em created .
  433. The available template variables are:
  434. .Bl -tag -compact
  435. .It Cm env Ar array
  436. Array containing all the environment variables.
  437. .It Cm file_directory Ar string
  438. Name of the directory where the impacted file is located.
  439. .It Cm file_name Ar string
  440. Name of the impacted file.
  441. .It Cm file_path Ar string
  442. Full path to the impacted file.
  443. .El
  444. .It Ic file-pre-edit
  445. Invoked
  446. .Em before
  447. an existent file
  448. .Em modified .
  449. The available template variables are the same as those available for the
  450. .Em file-pre-create
  451. type.
  452. .It Ic file-post-create
  453. Invoked
  454. .Em after
  455. a non-existent file
  456. .Em created .
  457. The available template variables are the same as those available for the
  458. .Em file-pre-create
  459. type.
  460. .It Ic file-post-edit
  461. Invoked
  462. .Em after
  463. an existent file
  464. .Em modified .
  465. The available template variables are the same as those available for the
  466. .Em file-pre-create
  467. type.
  468. .It Ic post-operation
  469. Invoked at the end of the certificate request process. The available template variables are:
  470. .Bl -tag -compact
  471. .It Cm key_type Ar string
  472. Name of the asymmetric cryptography algorithm used to generate the certificate's key pair.
  473. .It Cm identifiers Ar string
  474. Array containing the identifiers included in the requested certificate.
  475. .It Cm env Ar array
  476. Array containing all the environment variables.
  477. .It Cm is_success Ar boolean
  478. True if the certificate request is successful.
  479. .It Cm status Ar string
  480. Human-readable status. If the certificate request failed, it contains the error description.
  481. .El
  482. .El
  483. .Sh DEFAULT HOOKS
  484. 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.
  485. .Bl -tag
  486. .It Pa git
  487. This hook uses
  488. .Xr git 1
  489. to archive private keys, public keys and certificates. It is possible to customize the commit username and email by using respectively the
  490. .Ev GIT_USERNAME
  491. and
  492. .Ev GIT_EMAIL
  493. environment variables.
  494. .It Pa http-01-echo
  495. This hook is designed to solve the http-01 challenge. For this purpose, it will write the proof into
  496. .Pa {{env.HTTP_ROOT}}/{{identifier}}/.well-known/acme-challenge/{{file_name}} .
  497. .Pp
  498. The web server must be configured so the file
  499. .Pa http://{{identifier}}/.well-known/acme-challenge/{{file_name}}
  500. can be accessed from the CA.
  501. .Pp
  502. If
  503. .Ev HTTP_ROOT
  504. is not specified, it will be set to
  505. .Pa /var/www .
  506. .It Pa tls-alpn-01-tacd-tcp
  507. This hook is designed to solve the tls-alpn-01 challenge using
  508. .Xr tacd 8 .
  509. It requires
  510. .Xr pkill 1
  511. to support the
  512. .Em Ar -F
  513. option.
  514. .Pp
  515. .Xr tacd 8
  516. will listen on the host defined by the
  517. .Ev TACD_HOST
  518. environment variable (default is the identifier to be validated) and on the port defined by the
  519. .Ev TACD_PORT
  520. environment variable (default is 5001).
  521. .Pp
  522. .Xr tacd 8
  523. will store its pid into
  524. .Pa {{TACD_PID_ROOT}}/tacd_{{identifier}}.pid .
  525. If
  526. .Ev TACD_PID_ROOT
  527. is not specified, it will be set to
  528. .Pa /run .
  529. .It Pa tls-alpn-01-tacd-unix
  530. This hook is designed to solve the tls-alpn-01 challenge using
  531. .Xr tacd 8 .
  532. It requires
  533. .Xr pkill 1
  534. to support the
  535. .Em Ar -F
  536. option.
  537. .Pp
  538. .Xr tacd 8
  539. will listen on the unix socket
  540. .Pa {{env.TACD_SOCK_ROOT}}/tacd_{{identifier}}.sock .
  541. If
  542. .Ev TACD_SOCK_ROOT
  543. is not specified, it will be set to
  544. .Pa /run .
  545. .Pp
  546. .Xr tacd 8
  547. will store its pid into
  548. .Pa {{TACD_PID_ROOT}}/tacd_{{identifier}}.pid .
  549. If
  550. .Ev TACD_PID_ROOT
  551. is not specified, it will be set to
  552. .Pa /run .
  553. .El
  554. .Sh TIME PERIODS
  555. ACMEd uses its own time period format, which is vaguely inspired by the ISO 8601 one. Periods are formatted as
  556. .Ar PM[PM...]
  557. where
  558. .Ar M
  559. is case sensitive character representing a length and
  560. .Ar P
  561. is an integer representing a multiplayer for the following length. The authorized length are:
  562. .Bl -dash -compact
  563. .It
  564. .Ar s :
  565. second
  566. .It
  567. .Ar m :
  568. minute
  569. .It
  570. .Ar h :
  571. hour
  572. .It
  573. .Ar d :
  574. day
  575. .It
  576. .Ar w :
  577. week
  578. .El
  579. The
  580. .Ar PM
  581. couples can be specified multiple times and in any order.
  582. .Pp
  583. For example,
  584. .Dq 1d42s and
  585. .Dq 40s20h4h2s
  586. both represents a period of one day and forty-two seconds.
  587. .Sh FILES
  588. .Bl -tag
  589. .It Pa /etc/acmed/acmed.toml
  590. Default
  591. .Xr acmed 8
  592. configuration file.
  593. .It Pa /etc/acmed/accounts
  594. Default accounts private and public keys directory.
  595. .It Pa /etc/acmed/certs
  596. Default certificates and associated private keys directory.
  597. .Sh EXAMPLES
  598. The following example defines a typical endpoint, account and certificate for a domain, several subdomains and an IP address.
  599. .Bd -literal -offset indent
  600. [[endpoint]]
  601. name = "example name"
  602. url = "https://acme.example.org/directory"
  603. tos_agreed = true
  604. [[account]]
  605. name = "my test account"
  606. email = "certs@exemple.net"
  607. [[certificate]]
  608. endpoint = "example name"
  609. account = "my test account"
  610. identifiers = [
  611. { dns = "exemple.net", challenge = "http-01"},
  612. { dns = "1.exemple.net", challenge = "dns-01"},
  613. { dns = "2.exemple.net", challenge = "tls-alpn-01", env.TACD_PORT="5010"},
  614. { dns = "3.exemple.net", challenge = "tls-alpn-01", env.TACD_PORT="5011"},
  615. { ip = "203.0.113.1", challenge = "http-01"},
  616. ]
  617. hooks = ["git", "http-01-echo", "tls-alpn-01-tacd-tcp", "some-dns-01-hook"]
  618. env.HTTP_ROOT = "/srv/http"
  619. .Ed
  620. .Pp
  621. It is possible to use
  622. .Xr echo 1
  623. to solve the
  624. .Em http-01
  625. challenge and
  626. .Xr rm 1
  627. to clean it.
  628. .Xr mkdir 1
  629. and
  630. .Xr chmod 1
  631. are used to prevent issues related to file access.
  632. .Bd -literal -offset indent
  633. [[hook]]
  634. name = "http-01-echo-mkdir"
  635. type = ["challenge-http-01"]
  636. cmd = "mkdir"
  637. args = [
  638. "-m", "0755",
  639. "-p", "{{%if env.HTTP_ROOT}}{{env.HTTP_ROOT}}{{else}}/var/www{{/if}}/{{identifier}}/.well-known/acme-challenge"
  640. ]
  641. [[hook]]
  642. name = "http-01-echo-echo"
  643. type = ["challenge-http-01"]
  644. cmd = "echo"
  645. args = ["{{proof}}"]
  646. stdout = "{{%if env.HTTP_ROOT}}{{env.HTTP_ROOT}}{{else}}/var/www{{/if}}/{{identifier}}/.well-known/acme-challenge/{{file_name}}"
  647. [[hook]]
  648. name = "http-01-echo-chmod"
  649. type = ["challenge-http-01-clean"]
  650. cmd = "chmod"
  651. args = [
  652. "a+r",
  653. "{{%if env.HTTP_ROOT}}{{env.HTTP_ROOT}}{{else}}/var/www{{/if}}/{{identifier}}/.well-known/acme-challenge/{{file_name}}"
  654. ]
  655. [[hook]]
  656. name = "http-01-echo-clean"
  657. type = ["challenge-http-01-clean"]
  658. cmd = "rm"
  659. args = [
  660. "-f",
  661. "{{%if env.HTTP_ROOT}}{{env.HTTP_ROOT}}{{else}}/var/www{{/if}}/{{identifier}}/.well-known/acme-challenge/{{file_name}}"
  662. ]
  663. .Ed
  664. .Pp
  665. The hooks from the previous example can be grouped in order to reduce the number of hooks to define in the certificate.
  666. .Bd -literal -offset indent
  667. [[group]]
  668. name = "http-01-echo-var-www"
  669. hooks = [
  670. "http-01-echo-mkdir",
  671. "http-01-echo-echo",
  672. "http-01-echo-chmod",
  673. "http-01-echo-clean"
  674. ]
  675. [[certificate]]
  676. # Some fields omitted
  677. hooks = ["http-01-echo"]
  678. env.HTTP_ROOT = "/srv/http"
  679. .Ed
  680. .Pp
  681. It is also possible to use
  682. .Xr sendmail 8
  683. in a hook in order to notif someone when the certificate request process is done.
  684. .Bd -literal -offset indent
  685. [[hook]]
  686. name = "email-report"
  687. type = ["post-operation"]
  688. cmd = "sendmail"
  689. args = [
  690. "-f", "noreply.certs@example.net",
  691. "contact@example.net"
  692. ]
  693. stdin_str = """Subject: Certificate renewal {{#if is_success}}succeeded{{else}}failed{{/if}} for {{identifiers.[0]}}
  694. The following certificate has {{#unless is_success}}*not* {{/unless}}been renewed.
  695. identifiers: {{#each identifiers}}{{#if @index}}, {{/if}}{{this}}{{/each}}
  696. key type: {{key_type}}
  697. status: {{status}}"""
  698. .Ed
  699. .Sh SEE ALSO
  700. .Xr acmed 8 ,
  701. .Xr tacd 8
  702. .Sh STANDARDS
  703. .Bl
  704. .It
  705. .Rs
  706. .%A Tom Preston-Werner
  707. .%D July 2018
  708. .%T TOML v0.5.0
  709. .%U https://github.com/toml-lang/toml
  710. .Re
  711. .It
  712. .Rs
  713. .%A Yehuda Katz
  714. .%T Handlebars
  715. .%U https://handlebarsjs.com/
  716. .Re
  717. .It
  718. .Rs
  719. .%A M. Jones
  720. .%D May 2015
  721. .%R RFC 7518
  722. .%T JSON Web Algorithms (JWA)
  723. .Re
  724. .El
  725. .Sh AUTHORS
  726. .An Rodolphe Bréard
  727. .Aq rodolphe@breard.tf