Improve docs.

5 files changed, 416 insertions, 161 deletions

diff --git a/Changes b/Changes
index 39a5bdf..1c25821 100644
--- a/Changes
+++ b/Changes
@@ -1,3 +1,9 @@
+2.00 2019-08-26
+
+        - Released on CPAN
+        - Parses entire Apache configuration. In particular, correctly
+        handles Include statements and expands macros (the Use statement).
+        
 1.11 2019-08-15
 
         - Fix acmeman --setup
diff --git a/Makefile.PL b/Makefile.PL
index 846d342..43555f8 100644
--- a/Makefile.PL
+++ b/Makefile.PL
@@ -8,7 +8,7 @@ use ExtUtils::MakeMaker;
 my %makefile_args = (
     NAME      =>      'App::Acmeman',
     ABSTRACT_FROM  => 'acmeman',
-    VERSION_FROM =>   'acmeman',
+    VERSION_FROM =>   'lib/App/Acmeman.pm',
     AUTHOR    =>      'Sergey Poznyakoff <gray@gnu.org>',
     LICENSE   =>      'gpl_3',
     EXE_FILES =>      [ 'acmeman' ],
@@ -36,8 +36,7 @@ my %makefile_args = (
         'Apache::Defaults' => 1.02,
         'Apache::Config::Preproc' => 1.03
     },
-     
-    MIN_PERL_VERSION => 5.006,
+    MIN_PERL_VERSION => 5.016001,
     META_MERGE => {
         'meta-spec' => { version => 2 },
         resources => {
diff --git a/README b/README
new file mode 100644
index 0000000..bb6da72
--- /dev/null
+++ b/README
@@ -0,0 +1,40 @@
+acmeman
+=======
+
+Command line utility for issuing and maintaining ACME SSL certificates.
+
+While most existing ACME tools take a list of domain names for which to
+issue certificates from their command line or configuration file, acmeman
+gathers domain names directly from the configuration of the http server
+that serves them. Thus, a domain name obtains its certificate automatically,
+once the administrator configures the http server to serve it via https.
+
+The utility is normally run as a cron job.
+
+Installation
+------------
+
+To build run:
+
+   perl Makefile.PL
+
+as usual. The created Makefile will install the missing dependencies
+from CPAN automatically. If this is not desirable, run
+
+   perl Makefile.PL --no-autoinstall
+
+instead.
+
+See "man acmeman" (or "perldoc acmeman", or "acmeman --help"), for a
+detailed manual.
+
+Copying
+-------
+This package is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 3, or (at your option)
+any later version.
+
+See http://www.gnu.org/licenses.
+
+
diff --git a/acmeman b/acmeman
index 8c446b2..e0f22ab 100755
--- a/acmeman
+++ b/acmeman
@@ -18,16 +18,16 @@ acmeman - manages ACME certificates
 B<acmeman>
 [B<-Fadns>]
 [B<-D> I<N>]
-[B<-f> I<FILE>]    
+[B<-f> I<FILE>]
 [B<--alt-names>]
 [B<--config-file=>I<FILE>]
 [B<--debug>]
 [B<--dry-run>]
 [B<--force>]
-[B<--stage>]    
+[B<--stage>]
 [B<--time-delta=>I<N>]
 [I<DOMAIN>...]
-    
+
 B<acmeman> B<--setup> | B<-S>
 [B<-Fdn>]
 [B<--config-file=>I<FILE>]
@@ -39,35 +39,253 @@ B<acmeman>
 [B<-h>]
 [B<--help>]
 [B<--usage>]
-    
-=head1 DESCRIPTION
 
-A tool for automatic creation and renewal of ACME (LetsEncrypt) SSL
-certificates. The list of domains to handle can be obtained from
-B<acmeman> or B<apache> configuration files, or from both. If the
-default B<acmeman> configuration file doesn't exist, the program
-scans B<apache> configuration files for a list of domains.
+=head1 DESCRIPTION
 
-B<Acmeman> is normally run periodically as a cronjob.
-    
-If you plan to serve SSL protected domains using apache, you can skip
-right to the B<apache> section.
+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.
+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.
 
-Domains which require LetsEncrypt certificates are declared in B<domain>
-section. Each section introduces a single domain. E.g.:
+There are three 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:
+
+    <VirtualHost *:80>
+        ServerName example.org
+        ServerAlias www.example.com
+        Use LetsEncryptChallenge
+        ...
+    </VirtualHost>
+
+=item 3. Issue the certificate
+