aboutsummaryrefslogtreecommitdiff
path: root/acmeman
diff options
context:
space:
mode:
Diffstat (limited to 'acmeman')
-rwxr-xr-x[-rw-r--r--]acmeman174
1 files changed, 172 insertions, 2 deletions
diff --git a/acmeman b/acmeman
index 3539a12..5efffeb 100644..100755
--- a/acmeman
+++ b/acmeman
@@ -23,11 +23,181 @@ acmeman - manages ACME certificates
=head1 SYNOPSIS
+B<acmeman>
+[B<-Fdn>]
+[B<-D> I<N>]
+[B<-f> I<FILE>]
+[B<-l> B<slackware>|B<debian>|B<rh>]
+[B<--config-file=>I<FILE>]
+[B<--debug>]
+[B<--dry-run>]
+[B<--force>]
+[B<--layout=>B<slackware>|B<debian>|B<rh>]
+[B<--time-delta=>I<N>]
+
+B<acmeman> B<--setup> | B<-s>
+[B<-Fdn>]
+[B<-f> I<FILE>]
+[B<-l> B<slackware>|B<debian>|B<rh>]
+[B<--config-file=>I<FILE>]
+[B<--debug>]
+[B<--dry-run>]
+[B<--force>]
+[B<--layout=>B<slackware>|B<debian>|B<rh>]
+[I<DIR>]
+
+B<acmeman>
+[B<-h>]
+[B<--help>]
+[B<--usage>]
+
=head1 DESCRIPTION
+A tool for automatic creation and renewal of ACME (LetsEncrypt) SSL
+certificates. It assumes that HTTP is served by Apache server, version
+2.4 or later (although only minor changes are necessary to make it work
+with version 2.2). Three most popular layouts of Apache configuration
+files are supported: Debian, Slackware, and Red Hat. 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.
+
+B<Acmeman> should be started periodically, as a cronjob. Upon startup,
+it scans Apache configuration for virtual hosts using 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).
+
+=head2 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.
+
+If the program is unable to determine the Apache configuration layout, you can
+declare it using the B<--layout> option. It takes a single argument, one of:
+B<debian>, B<slackware>, or B<rh> (all lower case). Alternatively, you can
+specify the location of the main Apache configuration file, using the
+B<--config-file> option.
+
+The program will refuse to overwrite existing files B<httpd-letsencrypt.conf>,
+unless given the B<--force> (B<-F>) option.
+
+=head2 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 I<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>
+
=head1 OPTIONS
-=head1 AUTHOR
+=over 4
+
+=item B<-h>
+
+Prints a short usage summary.
+
+=item B<--help>
+
+Prints detailed user manual.
+
+=item B<--usage>
+
+Outputs a terse reminder of the command line syntax along with a
+list of available options.
+
+=item B<-D>, B<--tile-delta=>I<N>
+
+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.
+
+=item B<-F>, B<--force>
+
+Force renewal of certificates, no matter their expire date. With B<--setup>,
+force installing the B<httpd-letsencrypt.conf> file even if it already
+exists.
+
+=item B<-d>, B<--debug>
+
+Increase debugging level. Multiple options accumulate.
+
+=item B<-f>, B<--config-file=>I<FILE>
+
+Read I<FILE> as main Apache configuration file.
+
+=item B<-l>, B<--layout=>I<NAME>
+
+Defines Apache configuration file layout. Valid values for I<NAME> are:
+B<slackware>, B<debian>, and B<rh> (for Red Hat).
+
+=item B<-n>, B<--dry-run>
+
+With B<--setup>, don't actually write anything, just print what would
+have been done. Otherwise, use LetsEncrypt staging server, instead of
+production.
+
+=item B<-s>, B<--setup>
+
+Set up the B<acmeman> infrastructure files.
+
+=back
+
+=head1 AUTHOR
+
+Sergey Poznyakoff <gray@gnu.org>
=cut
@@ -429,7 +599,7 @@ sub initial_setup {
SSLHonorCipherOrder on
SSLCipherSuite EECDH+AES128:RSA+AES128:EECDH+AES256:RSA+AES256:EECDH+3DES:RSA+3DES:EECDH+RC4:RSA+RC4:!MD5
SSLCertificateFile /etc/ssl/acme/\$domain/cert.pem
- SSLCertificateKeyFile /etc/ssl/acme/private/\$domain/privkey.pem
+ SSLCertificateKeyFile /etc/ssl/acme/\$domain/privkey.pem
SSLCACertificateFile /etc/ssl/acme/lets-encrypt-x3-cross-signed.pem
</Macro>
EOT

Return to:

Send suggestions and report system problems to the System administrator.