view release on metacpan or  search on metacpan

acmeman  view on Meta::CPAN

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>

    <VirtualHost *:443>
	Use LetsEncryptServer example.org
	ServerAlias www.example.com
	...
    </VirtualHost>

Alternatively, you can use the B<LetsEncryptSSL> macro, which differs from
B<LetsEncryptServer> in that it configures only SSL settings, without the
B<ServerName> statement, which therefore must be included explicitly:

    <VirtualHost *:443>
	ServerName example.org
	ServerAlias www.example.com
	Use LetsEncryptSSL example.org
	...
    </VirtualHost>

LetsEncrypt limits the number of certificates requested for a single
registered domain per week (at the time of this writing - 20).  To avoid
hitting that limit, you may wish to use the same certificate for different
virtual hosts.  The special macro B<LetsEncryptReference> is provided for
that purpose.  Suppose, for example, that you wish to configure server
name B<git.example.org> to use the same certificate as B<example.org>
(configured in the example above).  You then declare the virtual host
for the plain HTTP as follows:

    <VirtualHost *:80>
	ServerName git.example.org
	Use LetsEncryptReference example.org
	...
    </VirtualHost>

The argument to the B<LetsEncryptReference> macro indicates the CN name of
the certificate to which the current server name (and aliases, if any) are
to be added as alternative names.  The corresponding virtual host for SSL
will use the B<LetsEncryptSSL> macro to configure the correct certificate:

    <VirtualHost *:80>
	ServerName git.example.org
	Use LetsEncryptSSL example.org
	...
    </VirtualHost>

=head2 file

    [core]
	source = file PATTERN [--ignore=RX] [--host=HOST]

Domain names will be read from files matching I<PATTERN>. The argument
can be a single file or directory name, or a valid globbing pattern.