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.

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