view release on metacpan or  search on metacpan

acmeman  view on Meta::CPAN

=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>

    <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>