Mirror
/
acmed
mirror of https://github.com/breard-r/acmed.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
Browse Source

Add man pages 

Documentation is a crucial point for every project, and the most
effective and traditional way to document a program is to write man
page. Here, the mdoc is used because it is simple.
Because the documentation is quite different from the project itself,
the man pages and others helpful files are distributed under a different
license. For this usage, the GNU All-Permissive License is adequate.
https://www.gnu.org/prep/maintain/html_node/License-Notices-for-Other-Files.html
man 7 groff_mdoc
pull/5/head
Rodolphe Breard 6 years ago
parent
1c65795e2b
commit
e0d260ca8c
5 changed files with 633 additions and 2 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 14
      CHANGELOG.md
  2. 21
      README.md
  3. 81
      man/en/acmed.8
  4. 436
      man/en/acmed.toml.5
  5. 83
      man/en/tacd.8

14
CHANGELOG.md
View File

@ -1,3 +1,11 @@
[//]: # (Copyright 2019 Rodolphe Bréard <rodolphe@breard.tf>)
[//]: # (Copying and distribution of this file, with or without modification,)
[//]: # (are permitted in any medium without royalty provided the copyright)
[//]: # (notice and this notice are preserved. This file is offered as-is,)
[//]: # (without any warranty.)
# Changelog
All notable changes to this project will be documented in this file.
@ -5,6 +13,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [Unreleased]
### Added
- Man pages.
## [0.3.0] - 2019-04-30
### Added

21
README.md
View File

@ -1,3 +1,11 @@
[//]: # (Copyright 2019 Rodolphe Bréard <rodolphe@breard.tf>)
[//]: # (Copying and distribution of this file, with or without modification,)
[//]: # (are permitted in any medium without royalty provided the copyright)
[//]: # (notice and this notice are preserved. This file is offered as-is,)
[//]: # (without any warranty.)
# ACMEd
[![Build Status](https://api.travis-ci.org/breard-r/acmed.svg?branch=master)](https://travis-ci.org/breard-r/acmed)
@ -28,6 +36,15 @@ The Automatic Certificate Management Environment (ACME), is an internet standard
- Daemon and certificates management via the `acmectl` tool
## Documentation
This projects provides the following man pages:
- acmed (8)
- acmed.toml (5)
- tacd (8)
## Build from source
In order to compile ADMEd, you will need the [Rust](https://www.rust-lang.org/) compiler and its package manager, Cargo. The minimal required Rust version is 1.32.0, although it is recommended to use the latest stable one.
@ -53,9 +70,9 @@ After testing multiple ACME clients, I found out none supported all the features
### Is it free and open-source software?
Yes, ACMEd is dual-licensed under the MIT and Apache 2.0 terms.
Yes, ACMEd is dual-licensed under the MIT and Apache 2.0 terms. See [LICENSE-MIT.txt](LICENSE-MIT.txt) and [LICENSE-APACHE-2.0.txt](LICENSE-APACHE-2.0.txt) for details.
See [LICENSE-MIT.txt](LICENSE-MIT.txt) and [LICENSE-APACHE-2.0.txt](LICENSE-APACHE-2.0.txt) for details.
The man pages, the `CHANGELOG.md` and the `README.md` files are released under the [GNU All-Permissive License](https://www.gnu.org/prep/maintain/html_node/License-Notices-for-Other-Files.html).
### Can it automatically change my server configuration?

81
man/en/acmed.8
View File

@ -0,0 +1,81 @@
.\" Copyright (c) 2019 Rodolphe Bréard <rodolphe@breard.tf>
.\"
.\" Copying and distribution of this file, with or without modification,
.\" are permitted in any medium without royalty provided the copyright
.\" notice and this notice are preserved. This file is offered as-is,
.\" without any warranty.
.Dd May 3, 2019
.Dt ACMED 8
.Os
.Sh NAME
.Nm acmed
.Nd ACME client daemon
.Sh SYNOPSIS
.Nm
.Op Fl c|--config Ar FILE
.Op Fl f|--foregroung
.Op Fl h|--help
.Op Fl -log-stderr
.Op Fl -log-syslog
.Op Fl -log-level Ar LEVEL
.Op Fl -pid-file Ar FILE
.Op Fl -root-cert Ar FILE
.Op Fl V|--version
.Sh DESCRIPTION
.Nm
is an Automatic Certificate Management Environment
.Pq ACME
client daemon which can automatically request and renew X.509 security certificates from various Certification Authorities
.Pq CA .
.Pp
The options are as follows:
.Bl -tag
.It Fl c, -config Ar FILE
Specify an alternative configuration file.
.It Fl f, -foregroung
Runs in the foregroung
.It Fl h, -help
Prints help information
.It Fl -log-stderr
Prints log messages to the standard error output
.It Fl -log-syslog
Sends log messages via syslog
.It Fl -log-level Ar LEVEL
Specify the log level. Possible values: error, warn, info, debug and trace.
.It Fl -pid-file Ar FILE
Specifies the location of the PID file
.It Fl -root-cert Ar FILE
Add a root certificate to the trust store. This option can be used multiple times.
.It Fl V, -version
Prints version information
.Sh FILES
.Bl -tag
.It Pa /etc/acmed/acmed.toml
Default
.Nm
configuration file.
.Sh SEE ALSO
.Xr acmed.toml 5 ,
.Xr tacd 8
.Sh STANDARDS
.Bl
.It
.Rs
.%A R. Barnes
.%A J. Hoffman-Andrews
.%A D. McCarney
.%A J. Kasten
.%D March 2019
.%R RFC 8555
.%T Automatic Certificate Management Environment (ACME)
.Re
.It
.Rs
.%A R. Shoemaker
.%D August 2018
.%R draft-ietf-acme-tls-alpn-05
.%T ACME TLS ALPN Challenge Extension
.Re
.Sh AUTHORS
.An Rodolphe Bréard
.Aq rodolphe@breard.tf

436
man/en/acmed.toml.5
View File

@ -0,0 +1,436 @@
.\" Copyright (c) 2019 Rodolphe Bréard <rodolphe@breard.tf>
.\"
.\" Copying and distribution of this file, with or without modification,
.\" are permitted in any medium without royalty provided the copyright
.\" notice and this notice are preserved. This file is offered as-is,
.\" without any warranty.
.Dd May 3, 2019
.Dt ACMED.TOML 5
.Os
.Sh NAME
.Nm acmed.toml
.Nd ACMEd configuration file
.Sh DESCRIPTION
.Nm
is the configuration file for
.Xr acmed 8 .
It is written in the
.Em TOML
format. The allowed elements are described below.
.Bl -tag
.It Ic global
Table containing the global configuration options.
.Bl -tag
.It Cm accounts_directory Ar string
Specify the directory where the accounts private and public keys are stored.
.It Cm certificates_directory Ar string
Specify the directory where the certificates and their associated private keys are stored.
.It Cm cert_file_mode Ar integer
Specify the permissions to use for newly-created certificates files. See
.Xr chmod 2
for more details.
.It Cm cert_file_user Ar user_id Ft string
Specify the user who will own newly-created certificates files. See
.Xr chown 2
for more details.
.It Cm cert_file_group Ar group_id Ft string
Specify the group who will own newly-created certificates files. See
.Xr chown 2
for more details.
.It Cm pk_file_mode Ar integer
Specify the permissions to use for newly-created private-key files. See
.Xr chmod 2
for more details.
.It Cm pk_file_user Ar user_id Ft string
Specify the user who will own newly-created private-key files. See
.Xr chown 2
for more details.
.It Cm pk_file_group Ar group_id Ft string
Specify the group who will own newly-created private-key files. See
.Xr chown 2
for more details.
.El
.It Ic endpoint
Array of table where each element defines a Certificate Authority
.Pq CA
which may be used to request certificates.
.Bl -tag
.It Cm name Ar string
The name the endpoint is registered under. Must be unique.
.It Cm url Ar string
The endpoint's directory URL.
.It Cm tos_agreed Ar boolean
Set whether or not the user agrees to the Terms Of Service
.Pq TOS .
.El
.It Ic hook
Array of table where each element defines a command that will be launched at a defined point. See section
.Sx WRITING A HOOK
for more details.
.Bl -tag
.It Cm name Ar string
The name the hook is registered under. Must be unique.
.It Cm hook_type Ar array
Array of strings. Possible types are:
.Bl -dash -compact
.It
challenge-http-01
.It
challenge-http-01-clean
.It
challenge-dns-01
.It
challenge-dns-01-clean
.It
challenge-tls-alpn-01
.It
challenge-tls-alpn-01-clean
.It
file-pre-create
.It
file-pre-edit
.It
file-post-create
.It
file-post-edit
.It
post-operation
.El
.It Ic cmd Ar string
The name of the command that will be launched.
.It Ic args Ar array
Array of strings representing the command's arguments.
.It Ic stdin Ar string
String that will be written into the command's standard input.
.It Ic stdout Ar string
Path to the file where the command's standard output if written.
.It Ic stderr Ar string
Path to the file where the command's standard error output if written.
.El
.It Ic group
Array of table allowing to group several hooks as one. A group is considered as new hook.
.Bl -tag
.It Cm name Ar string
The name the group is registered under. This name is considered as a hook name. Must be unique.
.It Cm hooks Ar array
Array containing the names of the hooks that are grouped. The hooks are guaranteed to be called sequentially in the declaration order.
.El
.It Ic account
Array of table representing an account on one or several CA.
.Bl -tag
.It Ic name Ar string
The name the account is registered under. Must be unique.
.It Ic email Ar string
The email address used to contact the account's holder.
.El
.It Ic certificate
Array of table representing a certificate that will be requested to a CA.
.Bl -tag
.It Ic account Ar string
Name of the account to use.
.It Ic endpoint Ar string
Name of the endpoint to use.
.It Ic domains Ar array
Array of tables listing the domains that should be included in the certificate along with the challenge to use for each one.
.Bl -tag
.It Ic dns
The domain name.
.It Ic challenge
The name of the challenge to use to prove the domain's ownership. Possible values are:
.Bl -dash -compact
.It
http-01
.It
dns-01
.It
tls-alpn-01
.El
.El
.It Ic algorithm Ar string
Name of the asymetric cryptography algorithm used to generate the certificate's key pair. Possible values are :
.Bl -dash -compact
.It
rsa2048
.Aq default
.It
rsa4096
.It
ecdsa_p256
.It
ecdsa_p384
.El
.It Ic kp_reuse Ar boolean
Set whether or not the private key should be reused when renewing the certificate. Default is false.
.It Ic directory Ar string
Path to the directory where certificates and their associated private keys are stored.
.It Ic hooks Ar array
Names of hooks that will be called when requesting a new certificate. The hooks are guaranteed to be called sequentially in the declaration order.
.El
.Sh WRITING A HOOK
When requesting a certificate to a CA using ACME, there is three steps that are hard to automatize. The first one is solving challenges in order to prove the ownership of every domains to be included: it requires to interact with the configuration of other services, hence depends on how the infrastructure works. The second one is restarting all the services that uses a given certificate, for the same reason. The last one is archiving: although several default methods can be implemented, sometimes admins wants or are required to do it in a different way.
.Pp
In order to allow a full automation of the three above steps without imposing arbitrary restrictions or methods,
.Xr acmed 8
uses hooks. Fundamentally, a hook is a command line template that will be called at a specific time of the process. Such approach allows admins to use any executable script or program located on the machine to customize the process.
.Pp
For a given certificate, hooks are guaranteed to be called sequentially in the declaration order. It is therefore possible to have a hook that depends on another one. Nevertheless, several certificates may be renewed at the same time. Hence, hooks shall not use globing or any other action that may disrupt hooks called by a different certificate.
.Pp
A hook have a type that will influence both the moment it is called and the available template variables. It is possible to declare several types. In such a case, the hook will be invoked whenever one of its type request it. When called, the hook only have access to template variable for the current type. If a hook uses a template variable that does not exists for the current type it is invoked for, the variable is empty.
.Pp
When writing a hook, the values of
.Em args ,
.Em stdin ,
.Em stdout
and
.Em stderr
are considered as template strings whereas
.Em cmd
is not. The template syntax is
.Em Handlebars .
See the
.Sx STANDARDS
section for a link to the
.Em Handlebars
specifications.
.Pp
The available types and the associated template variable are described below.
.Bl -tag
.It Ic challenge-http-01
Invoked when the ownership of a domain must be proved using the
.Em http-01
challenge. The available template variables are:
.Bl -tag -compact
.It Cm domain Ar string
The domain name whom ownership is currently being validated.
.It Cm challenge Ar string
The name of the challenge type
.Aq http-01 .
Mostly used in hooks with multiple types.
.It Cm file_name Ar string
Name of the file containing the proof. This is not a full path and does not include the
.Ql .well-known/acme-challenge/
prefix.
.It Cm proof Ar string
The content of the proof that must be written to
.Em file_name .
.El
.It Ic challenge-http-01-clean
Invoked once a domain ownership has been proven using the
.Em http-01
challenge. This hook is intended to remove the proof since it is no longer required. The template variables are strictly identical to those given in the corresponding
.Em challenge-http-01
hook.
.It Ic challenge-dns-01
Invoked when the ownership of a domain must be proved using the
.Em dns-01
challenge. The available template variables are:
.Bl -tag -compact
.It Cm domain Ar string
The domain name whom ownership is currently being validated.
.It Cm challenge Ar string
The name of the challenge type
.Aq dns-01 .
Mostly used in hooks with multiple types.
.It Cm proof Ar string
The content of the proof that must be written to a
.Ql TXT
entry of the DNS zone for the
.Ql _acme-challenge
subdomain.
.El
.It Ic challenge-dns-01-clean
Invoked once a domain ownership has been proven using the
.Em dns-01
challenge. This hook is intended to remove the proof since it is no longer required. The template variables are strictly identical to those given in the corresponding
.Em challenge-dns-01
hook.
.It Ic challenge-tls-alpn-01
Invoked when the ownership of a domain must be proved using the
.Em tls-alpn-01
challenge. The available template variables are:
.Bl -tag -compact
.It Cm domain Ar string
The domain name whom ownership is currently being validated.
.It Cm challenge Ar string
The name of the challenge type
.Aq tls-alpn-01 .
Mostly used in hooks with multiple types.
.It Cm proof Ar string
Plain-text representation of the
.Em acmeIdentifier
extension that should be used in the self-signed certificate presented when a TLS connection is initiated with the
.Qd acme-tls/1
ALPN extension value.
.Xr acmed 8
will not generate the certificate itself since it can be done using
.Xr tacd 8 .
.El
.It Ic challenge-tls-alpn-01-clean
Invoked once a domain ownership has been proven using the
.Em tls-alpn-01
challenge. This hook is intended to remove the proof since it is no longer required. The template variables are strictly identical to those given in the corresponding
.Em challenge-tls-alpn-01
hook.
.It Ic file-pre-create
Invoked
.Em before
a non-existent file
.Em created .
The available template variables are:
.Bl -tag -compact
.It Cm file_name Ar string
Name of the impacted file.
.It Cm file_directory Ar string
Name of the directory where the impacted file is located.
.It Cm file_path Ar string
Full path to the impacted file.
.El
.It Ic file-pre-edit
Invoked
.Em before
an existent file
.Em modified .
The available template variables are the same as those available for the
.Em file-pre-create
type.
.It Ic file-post-create
Invoked
.Em after
a non-existent file
.Em created .
The available template variables are the same as those available for the
.Em file-pre-create
type.
.It Ic file-post-edit
Invoked
.Em after
an existent file
.Em modified .
The available template variables are the same as those available for the
.Em file-pre-create
type.
.It Ic post-operation
Invoked at the end of the certificate request process. The available template variables are:
.Bl -tag -compact
.It Cm domains Ar string
Array containing the domain names included in the requested certificate.
.It Cm algorithm Ar string
Name of the algorithm used in the certificate.
.It Cm status Ar string
Status of request. Is set to
.Dq Success.
in case the operation succeeded, in an error description otherwise.
.El
.El
.Sh FILES
.Bl -tag
.It Pa /etc/acmed/acmed.toml
Default
.Xr acmed 8
configuration file.
.It Pa /etc/acmed/accounts
Default accounts private and public keys directory.
.It Pa /etc/acmed/certs
Default certificates and associated private keys directory.
.Sh EXAMPLES
The following example defines a typical endpoint, account and certificate for a domain and several subdomains.
.Bd -literal -offset indent
[[endpoint]]
name = "example name"
url = "https://acme.example.org/directory"
tos_agreed = true
[[account]]
name = "my test account"
email = "certs@exemple.net"
[[certificate]]
endpoint = "example name"
account = "my test account"
domains = [
{ dns = "exemple.net", challenge = "http-01"},
{ dns = "1.exemple.net", challenge = "http-01"},
{ dns = "2.exemple.net", challenge = "dns-01"},
{ dns = "3.exemple.net", challenge = "tls-alpn-01"},
]
hooks = ["example-hook-1", "example-hook-2", "example-hook-3"]
.Ed
.Pp
It is possible to use
.Xr echo 1
to solve the
.Em http-01
challenge and
.Xr rm 1
to clean it.
.Bd -literal -offset indent
[[hook]]
name = "echo"
type = ["challenge-http-01"]
cmd = "echo"
args = ["{{proof}}"]
stdout = "/var/www/{{domain}}/.well-known/acme-challenge/{{file_name}}"
[[hook]]
name = "echo-clean"
type = ["challenge-http-01-clean"]
cmd = "rm"
args = [
"-f",
"/var/www/{{domain}}/.well-known/acme-challenge/{{file_name}}"
]
.Ed
.Pp
The two above hooks can be grouped in order to reduce the number of hooks to define in the certificate.
.Bd -literal -offset indent
[[group]]
name = "http-echo"
hooks = ["echo", "echo-clean"]
[[certificate]]
# Some fields omitted
hooks = ["http-echo"]
.Ed
.Pp
It is also possible to use
.Xr sendmail 8
in a hook in order to notif someone when the certificate request process is done.
.Bd -literal -offset indent
[[hook]]
name = "email-report"
type = ["post-operation"]
cmd = "sendmail"
args = [
"-f", "noreply.certs@example.net",
"contact@example.net"
]
stdin = """Subject: Certificate renewal alert for {{domains.[0]}}
The following certificate has been renewed.
domains: {{#each domains}}{{#if @index}}, {{/if}}{{this}}{{/each}}
algorithm: {{algorithm}}
status: {{status}}"""
.Ed
.Sh SEE ALSO
.Xr acmed 8 ,
.Xr tacd 8
.Sh STANDARDS
.Bl
.It
.Rs
.%A Tom Preston-Werner
.%D July 2018
.%T TOML v0.5.0
.%U https://github.com/toml-lang/toml
.Re
.It
.Rs
.%A Yehuda Katz
.%T Handlebars
.%U https://handlebarsjs.com/
.Re
.El
.Sh AUTHORS
.An Rodolphe Bréard
.Aq rodolphe@breard.tf

83
man/en/tacd.8
View File

@ -0,0 +1,83 @@
.\" Copyright (c) 2019 Rodolphe Bréard <rodolphe@breard.tf>
.\"
.\" Copying and distribution of this file, with or without modification,
.\" are permitted in any medium without royalty provided the copyright
.\" notice and this notice are preserved. This file is offered as-is,
.\" without any warranty.
.Dd May 3, 2019
.Dt TACD 8
.Os
.Sh NAME
.Nm tacd
.Nd TLS-ALPN Challenge Daemon
.Sh SYNOPSIS
.Nm
.Op Fl e|--acme-ext Ar STRING
.Op Fl -acme-ext-file Ar FILE
.Op Fl d|--domain Ar STRING
.Op Fl -domain-file Ar STRING
.Op Fl f|--foregroung
.Op Fl h|--help
.Op Fl l|--listen Ar host:port
.Op Fl -log-stderr
.Op Fl -log-syslog
.Op Fl -log-level Ar LEVEL
.Op Fl -pid-file Ar FILE
.Op Fl V|--version
.Sh DESCRIPTION
.Nm
is a server that will listen to incoming Transport Layer Security
.Pq TLS
connections and, if the
.Em acme-tls/1
protocol has been declared during the Application-Layer Protocol Negotiation
.Pq ALPN ,
present a self-signed certificate in order to attempt to solve the TLS-ALPN-01 challenge. It then drops the connection.
.Pp
In order to generate the self-signed certificate, it is required to specify both the
.Em domain name
to validate and the
.Em acmeIdentifier extension .
If one of those values is not specified using the available options, it is read from the standard input. When reading from the standard input, a new line character is expected at the end. In the case both values needs to be read from the standard input, the
.Em domain name
is read first, then the
.Em acmeIdentifier extension .
.Pp
The options are as follows:
.Bl -tag
.It Fl e, -acme-ext Ar STRING
The acmeIdentifier extension to set in the self-signed certificate
.It Fl -acme-ext-file Ar FILE
File from which is read the acmeIdentifier extension to set in the self-signed certificate
.It Fl d, -domain Ar STRING
The domain that is being validated
.It Fl -domain-file Ar STRING
File from which is read the domain that is being validated
.It Fl f, -foregroung
Runs in the foregroung
.It Fl h, -help
Prints help information
.It Fl i, -listen Ar host:port
Specifies the host and port to listen on
.It Fl -log-stderr
Prints log messages to the standard error output
.It Fl -log-syslog
Sends log messages via syslog
.It Fl -log-level Ar LEVEL
Specify the log level. Possible values: error, warn, info, debug and trace.
.It Fl -pid-file Ar FILE
Specifies the location of the PID file
.It Fl V, -version
Prints version information
.Sh SEE ALSO
.Xr acmed.toml 5
.Sh STANDARDS
.Rs
.%A R. Shoemaker
.%D August 2018
.%R draft-ietf-acme-tls-alpn-05
.%T ACME TLS ALPN Challenge Extension
.Re
.Sh AUTHORS
.An Rodolphe Bréard
.Aq rodolphe@breard.tf
Write Preview
Loading…
Cancel
Save