view release on metacpan or  search on metacpan

acmeman  view on Meta::CPAN

=head2 HAPROXY

Use the B<file> source. This domain source reads the list of domain
names from a disk file. The first name in the list becomes the certificate
B<CN>, rest of names (if any) are used as alternative CNs. For a detailed
discussion of the B<file> source, refer to the section B<SOURCE>,
subsection B<file>.

=over 4

=item 1. Create a directory for storing domain name files

This directory will keep domain name files, named after the corresponding
HAProxy backends.  E.g.

    mkdir /etc/haproxy/hosts

=item 2. Configure acmeman

Example F</etc/acmeman.conf> file is:

    [core]
       source = file /etc/haproxy/hosts
       postrenew = /usr/sbin/service haproxy restart
    [files default]
       type = single
       certificate-file = /etc/ssl/acme/crt/$domain.pem

The B<core> section declares the source to use. The first argument to
the B<file> source is the name of the directory where the domain name lists
are stored. The B<postrenew> statement declares the command to be run
after all certificates have been renewed. In our case, this command restarts
B<haproxy>, forcing it to re-read the certificates.

The B<files> statement instructs the program to create, for each domain,
a single file containing the private key, certificate chain and the domain
certificate for that domain. The B<$domain> variable in the
B<certificate-file> declaration will be replaced by the first domain name
from the list (the B<CN>) for that certificate.

This configuration will keep a separate certificate for each backend in
B<haproxy> that supports https access.  If concerned about request rate
limit, you can instruct B<acmeman> to maintain a single certificate with
all domain names as X509v3 subject alternative names instead.  To do so,
use the B<--host> option in the source definition.  Its argument specifies
the domain name to use as the CN for the certificate.  E.g.:

    [core]
       source = file /etc/haproxy/hosts --host=www.example.com
       ...

=item 3. Configure haproxy

First, configure the plain HTTP frontend, which will be responsible for
serving ACME challenges and redirecting the rest of the requests to
HTTPS. The simplest definition is:

    frontend http-in
	mode http
	bind :::80 v4v6
	http-request redirect code 301 location https://%[hdr(host)]%[capture.req.uri] unless { path_beg /.well-known/acme-challenge }
	use_backend acme if { path_beg /.well-known/acme-challenge }

Actual backend configuration for the B<acme> backend is beyond the scope of
this manual. Use some simple and lightweight B<http> server capable of serving
static files, such as B<fileserv> (L<https://www.gnu.org.ua/projects/fileserv>),
for example.

Then, configure HTTPS section to use certificates from the certificate file
directory:

    frontend https-in
	mode http
	bind :::443 v4v6 ssl crt /etc/ssl/acme/crt
	# Direct each group of domain names to the corresponding
	# backend.
	use_backend d1 if { hdr(host) -f /etc/haproxy/hosts/d1 }
	use_backend d2 if { hdr(host) -f /etc/haproxy/hosts/d2 }
	...

Finally, define the backends.

=back

=head2 Pound

B<Pound> is a light-weight proxy server available from L<https://github.com/graygnuorg/pound>.  It is supported by the B<acmeman> source B<pound>, which
scans the B<pound> configuration file F</etc/pound.cfg>, and extracts domain
names from the B<Host> directives in B<ListenHTTP> sections that contain
the B<ACME> statement.  Below is a short usage instruction for this source
module.  For a detailed discussion, refer to the section B<SOURCE>, subsection
B<pound>.

=over 4

=item 1. Add the B<ACME> directive to the B<ListenHTTP> section of your
F</etc/pound.cfg> file.  Its argument is a directory on local file system
where ACME challenge files will be stored.  Make sure that this directory
is the F<.well-known/acme-challenge> subdirectory of the B<rootdir> in your
B<acmeman> configuration file.

=item 2. In the same B<ListenHTTP> section, define hostnames which will obtain
ACME certificates.  Make sure to use B<Host> statements with exact string
matching algorithm.  If serving several host names, use the B<Match OR> block.

=back

After these two steps, your listener section will look like:

    ListenHTTP
	Address 0.0.0.0
	Port 80
	ACME "/var/lib/pound/acme/.well-known/acme-challenge"
	Service
	    Match OR
		Host "www.example.org"
		Host "example.org"
	    End
	    ...
	End
    End

=over 4

=item 3. Configure B<acmeman>.  Use the B<pound> source and make sure
B<rootdir> is synchronized with the B<ACME> statement in F<pound.cfg>, as
described in point 1.  E.g.:

    [core]
	source = pound
	rootdir = /var/lib/pound/acme
	postrenew = /usr/bin/systemctl restart pound

=back