App-Acmeman
view release on metacpan or search on metacpan
[B<-f> I<FILE>]
[B<--alt-names>]
[B<--config-file=>I<FILE>]
[B<--debug>]
[B<--dry-run>]
[B<--force>]
[B<--stage>]
[B<--time-delta=>I<N>]
[I<DOMAIN>...]
B<acmeman> B<--setup> | B<-S>
[B<-Fdn>]
[B<--config-file=>I<FILE>]
[B<--debug>]
[B<--dry-run>]
[B<--force>]
B<acmeman>
[B<-h>]
[B<--help>]
[B<--usage>]
=head1 DESCRIPTION
B<Acmeman> is a tool for automatic management of ACME (LetsEncrypt) SSL
certificates.
Most existing ACME tools take a list of domain names for which to issue
certificates from their command line or configuration file. B<Acmeman>
takes a completely different approach. It gathers domain names directly
from the configuration of the B<http> server that manages them. Thus,
a domain name obtains its certificate automatically, once the administrator
configures the http server to serve it via https.
This version of B<acmeman> is able to handle configuration files of
B<Apache> http server, and servers that are able to read the list of
domain names from disk files, such as B<HAProxy>.
For trivial configurations, B<acmeman> can be used without any additional
configuration. For example, support for B<Apache> is enabled by default,
so all the administrator has to do is to run
acmeman --setup
which will set up additional macro definitions for the apache configuration
file, then enable the B<mod_macro> module and to use the provided definitions
in httpd configuration. This is discussed in detail in the section B<APACHE>
below.
In more complex configurations, B<acmeman> should be instructed what to
do using its configuration file. This file, normally named
F</etc/acmeman.conf>, supplies the definitions of I<domain sources>,
i.e. configuration files from which to obtain domain names to form the
certificate CNs and other parameters. At a pinch, the list of domain names
can be declared in it as well. Several domain sources can be used
simultaneously. E.g. you can have B<acmeman> look for domain names in
B<Apache> and B<HAProxy> configurations and obtain an additional list of
domains from its own configuration, all in the same time.
In any case, B<acmeman> should be run as a periodic cron job, in order to
ensure that expiring certificates are updated in time. The usual crontab
entry (for Vixie cron) is
0 4 * * * root /usr/bin/acmeman
Exact interval configuration is entirely up to you. For Dillon cron, omit
the user name field.
When started this way, B<acmeman> will scan the existing certificates and
select those of them which will expire within a predefined amount of time
(24h by default, configurable by the B<core.time-delta> statement). Then
it will scan the configured domain sources to see if any certificates are
added an alternative CN and if any new certificates should be issued. Having
created a list of the certificates, it will interact with the ACME server,
issuing the new ones and updating the ones that need prolongation or
modification.
=head1 QUICK START
The following is a short introduction to the B<acmeman> configuration. For
a detailed discussion, see the B<CONFIGURATION> section below. For detailed
discussion of particular domain sources, refer to the section B<SOURCES>.
The configuration file, B</etc/acmeman.conf>, consists of statements,
which have the form B<I<KW>=I<VAL>>, grouped into sections, declared
as B<[I<NAME>]> (square brackets are part of the syntax). Empty lines
and comments (introduced by a hash sign) are ignored.
There are four main use cases:
=head2 APACHE
In most cases no special configuration file is needed. The following
recipe describes each configuration step. Refer to the section B<SOURCE>,
subsection B<apache> for a detailed discussion.
=over 4
=item 1. Initial configuration
Run
acmeman --setup
It will detect the Apache layout, install an additional Apache configuration
file, F<httpd-letsencrypt.conf> and print the instructions on how to
enable it. Follow them and enable the B<mod_macro> module.
=item 2. Apache domain setup: plain HTTP
To declare that a virtual host needs SSL certificate, add the following
line to the Apache B<VirtualHost> block serving plain HTTP for that host:
Use LetsEncryptChallenge
This will instruct Apache B<httpd> to serve ACME challenges and B<acmeman>
to request a certificate for that virtual host. The hostname declared with
the B<ServerName> statement will be used as the B<CN> for the certificate,
and any names declared via B<ServerAlias> statements will form the list of
alternative names. For example:
one with a backslash immediately followed by a newline character.
Configuration consists of settings grouped into sections. Syntactically,
a I<setting> is
KEYWORD = VALUE
where I<KEYWORD> stands for a symbolic name consisting of alphanumeric
characters, dashes and underscores, and I<VALUE> stands for any sequence
of characters.
A I<section> is identified by its name and optional arguments. It begins
with the following construct:
[NAME]
or, if arguments are present:
[NAME ARG1 ARG2 ...]
The square brackets are part of the syntax.
A section can contain one or more settings.
The statements in the configuration file form a directed graph. Often
in this document we will identify the statement by its I<path>, i.e. a
list of section name, its arguments, and the keyword, separated by dots. For
example, the path B<files.apache.type> corresponds to the following
configuration file fragment:
[files apache]
type = single
The following describes the available sections and keywords
=head2 B<[core]>
This section defines the behavior of the program as a whole.
=over 4
=item B<rootdir=>I<DIR>
Defines the root directory to use instead of the default </var/www/acme>.
Root directory is the directory under which the
F<.well-known/acme-challenge> subdirectory is located.
=item B<time-delta=>I<SECONDS>
Sets the time window before the actual expiration time, when the certificate
becomes eligible for renewal. I<N> is time in seconds. The default
value is 86400, which means that B<acmeman> will attempt to renew any
certificate that expires within 24 hours.
The command line option B<--time-delta> overrides this setting.
=item B<postrenew=>I<COMMAND>
Defines the command to be run at the end of the run if at least one
certificate has been updated. Normally this command reloads the httpd
server (or whatever server is using the certificates). If more than one
B<postrenew> statements are defined, they will be run in sequence, in the
same order as they appeared in the configuration file.
I<COMMAND> inherits the environment from the B<acmeman> process, with the
following additional variables:
=over 8
=item ACMEMAN_CERTIFICATE_COUNT
Total count of renewed certificate files.
=item ACMEMAN_CERTIFICATE_FILE
Whitespace-delimited list of renewed certificate files
=item ACMEMAN_DOMAIN_NAME
Whitespace-delimited list of renewed domain names (CNs).
=item ACMEMAN_ALT_NAMES
Whitespace-delimited list of alternative DNS names from the renewed
certificate files.
=back
=item B<source=>I<NAME> [I<ARG>...]
Defines the source of domain names. The I<NAME> parameter identifies the
source, and additional arguments supply the initialization parameters.
The present version of B<acmeman> is shipped with three sources: B<null>,
B<apache>, and B<file>.
The B<null> module is an empty source. It takes no additional arguments.
Use this source if all domains are described in the configuration file
using one or more B<domain> sections.
The B<apache> source module is the default. It scans B<httpd> configuration
files as described in section B<apache>. One argument is allowed. If supplied,
it defines the apache configuration layout. Allowed values are: B<debian>,
B<slackware>, B<suse> and B<rh> (for Red Hat). Without arguments, the layout
will be autodetected.
The B<pound> source gathers host names from B<pound> configuration file.
The B<file> source reads domain names from one or more disk files. A
mandatory argument specifies the name of the directory where the files
are located. This mode is suitable for use with B<haproxy> pattern files.
Multiple B<source> statements can be defined. They will be processed
sequentially.
=item B<files=>I<NAME>
Identifies the B<[files]> section which describes how to create certificate
files for domains which lack explicit B<files> keyword. Default I<NAME> is
B<default>. See the description of the B<files> statement in B<domain>
The default is B<split>.
=item B<certificate-file=>I<FILENAME>
Defines the name of the certificate file for this domain. This statement
is mandatory.
=item B<key-file=>I<FILENAME>
Defines the name of the certificate key file. This statement must be present
if B<type> is set to B<split>.
=item B<ca-file=>I<FILENAME>
Defines the name of the certificate authority file. This statement may
be present if B<type> is set to B<split>.
=item B<argument=>I<STRING>
Defines the name of the meta-variable in I<FILENAME> arguments, which will
be replaced with the actual domain name. Default is B<$domain>.
=back
=head1 SOURCES
=head2 null
[core]
source = null
Declares empty source. This means that B<acmeman> will handle only domain
names explicitly declared in the configuration file using the B<domain>
setting.
=head2 apache
[core]
source = apache [--server-root=DIR] [LAYOUT]
This is the default source. It assumes Apache httpd, version 2.4 or later
(although only minor changes are necessary to make it work with version 2.2).
The optional I<LAYOUT> argument defines the layout of the apache configuration
files. Allowed layout values are: B<debian>, B<slackware>, B<suse> and
B<rh> (for Red Hat). If not supplied, the layout is determined automatically.
Use the B<--server-root> option to supply the name of the server root
directory, if for some reason the module is unable to determine it
automatically.
A special directory should be configured for receiving ACME challenges.
The package provides two Apache macros: for serving ACME challenges and
declaring SSL virtual hosts.
Upon startup the program scans Apache configuration for virtual hosts
that use ACME certificates, checks their expiration times, and renews those
of the certificates that are nearing their expiration times within a
predefined number of seconds (24 hours by default). If any of the
certificates were updated during the run, B<acmeman> will restart the
B<httpd> server.
=head3 Setup
To set up the necessary infrastructure, run B<acmeman --setup>. It will
create the configuration file B<httpd-letsencrypt.conf>, defining two
macros for SSL-enabled sites (B<mod_macro> is needed). Finally, it will
create the directory B</var/www/acme>, which will be used for receiving
and serving ACME challenges. If another directory is preferred, it can
be specified as an argument to B<acmeman --setup>.
The tool will try to determine the layout of the Apache configuration
files and place the created file accordingly, so that it will be included
into the main configuration file. It will print the name of the created
file at the end of the run. You are advised to ensure that the file is
included and that the module B<mod_macro> is loaded prior to it. You
may also wish to revise B<httpd-letsencrypt.conf> and edit the paths to
SSL files configured there. By default, the directory F</etc/acme/I<DOMAIN>>
will be created for each domain name needing SSL, and two files will be placed
there: F<cert.pem>, containing the leaf and intermediate certificates for that
domain, and F<privkey.pem>, containing the private key for that domain.
The program will refuse to overwrite existing files B<httpd-letsencrypt.conf>,
unless given the B<--force> (B<-F>) option.
=head3 Configuring SSL
To declare that a virtual host needs SSL certificate, add the following
line to the Apache B<VirtualHost> block serving plain HTTP for that host:
Use LetsEncryptChallenge
This will instruct B<acmeman> to request a certificate for that virtual
host. The hostname declared with the B<ServerName> statement will be used
as the B<CN> for the certificate, and any names declared via B<ServerAlias>
statements will form the list of alternative names (obviously, wildcards are
not allowed).
If such a certificate doesn't exist, it will be requested and created when
B<acmeman> is run.
To use the created certificate, create a new B<VirtualHost> block that
contains the following statement:
Use LetsEncryptServer DOMAIN
where I<DOMAIN> is the name used in the B<ServerName> statement of the plain
HTTP configuration. Copy the B<ServerAlias> statements (if any), and add the
rest of configuration statements. Note, that you need not use the
B<ServerName> statement, as it will be included when the B<LetsEncryptServer>
macro is expanded.
Example:
<VirtualHost *:80>
ServerName example.org
ServerAlias www.example.com
Use LetsEncryptChallenge
...
</VirtualHost>
( run in 2.575 seconds using v1.01-cache-2.11-cpan-39bf76dae61 )