diff options
Diffstat (limited to 'acmeman')
-rwxr-xr-x[-rw-r--r--] | acmeman | 174 |
1 files changed, 172 insertions, 2 deletions
@@ -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 |