diff options
author | Sergey Poznyakoff <gray@gnu.org.ua> | 2018-05-07 11:27:28 +0300 |
---|---|---|
committer | Sergey Poznyakoff <gray@gnu.org.ua> | 2018-05-07 11:27:28 +0300 |
commit | 95c82ca2a5562e60463a38519157ae1a8b60ac1a (patch) | |
tree | 5a6062e7b3cacb3a7da79d4f099d90003352745b | |
parent | d76f2f28aaff86ffd7e4a049d5ce7cd91885805f (diff) | |
download | acmeman-95c82ca2a5562e60463a38519157ae1a8b60ac1a.tar.gz acmeman-95c82ca2a5562e60463a38519157ae1a8b60ac1a.tar.bz2 |
Improve "file" source
* lib/App/Acmeman/Source/File.pm (new): New options --ignore and
--host.
* acmeman: Document the "file" source.
-rwxr-xr-x | acmeman | 74 | ||||
-rw-r--r-- | lib/App/Acmeman/Source/File.pm | 24 |
2 files changed, 77 insertions, 21 deletions
@@ -81,13 +81,13 @@ B<acmeman> or B<apache> configuration files, or from both. If the | |||
81 | default B<acmeman> configuration file doesn't exist, the program | 81 | default B<acmeman> configuration file doesn't exist, the program |
82 | scans B<apache> configuration files for a list of domains. | 82 | scans B<apache> configuration files for a list of domains. |
83 | 83 | ||
84 | B<Acmeman> is normally run periodically as a cronjob. | 84 | B<Acmeman> is normally run periodically as a cronjob. |
85 | 85 | ||
86 | If you plan to serve SSL protected domains using apache, you can skip | 86 | If you plan to serve SSL protected domains using apache, you can skip |
87 | right to the B<APACHE> section. | 87 | right to the B<apache> section. |
88 | 88 | ||
89 | The following is a short introduction to the B<acmeman> configuration. For | 89 | The following is a short introduction to the B<acmeman> configuration. For |
90 | a detailed discussion, see the B<CONFIGURATION> section below. | 90 | a detailed discussion, see the B<CONFIGURATION> section below. |
91 | 91 | ||
92 | The configuration file, B</etc/acmeman.conf>, consists of statements, | 92 | The configuration file, B</etc/acmeman.conf>, consists of statements, |
93 | which have the form B<I<KW>=I<VAL>>, grouped into sections, declared | 93 | which have the form B<I<KW>=I<VAL>>, grouped into sections, declared |
@@ -124,13 +124,15 @@ implicitly if no other B<files> section is defined in the configuration file. | |||
124 | Moreover, the string B<default> is the default identifier, which is used if | 124 | Moreover, the string B<default> is the default identifier, which is used if |
125 | the B<domain> section lacks the B<files> keyword. | 125 | the B<domain> section lacks the B<files> keyword. |
126 | 126 | ||
127 | The special section B<[core]> contains basic settings that control the | 127 | The special section B<[core]> contains basic settings that control the |
128 | program behavior. One of the important settings is B<source>, which declares | 128 | program behavior. One of the important settings is B<source>, which declares |
129 | an external source from which domain settings must be obtained. As | 129 | an external source from which domain settings must be obtained. As |
130 | of B<acmeman> version 2.00, the only available external source is B<apache>. | 130 | of B<acmeman> version 1.05, the following sources are available: |
131 | B<null>, B<apache>, and B<file>. | ||
132 | |||
131 | Consider the following configuration: | 133 | Consider the following configuration: |
132 | 134 | ||
133 | [core] | 135 | [core] |
134 | source = apache | 136 | source = apache |
135 | 137 | ||
136 | It instructs B<acmeman> to read domain settings from Apache configuration | 138 | It instructs B<acmeman> to read domain settings from Apache configuration |
@@ -208,26 +210,30 @@ The command line option B<--time-delta> overrides this setting. | |||
208 | Defines the command to be run at the end of the run if at least one | 210 | Defines the command to be run at the end of the run if at least one |
209 | certificate has been updated. Normally this command reloads the httpd | 211 | certificate has been updated. Normally this command reloads the httpd |
210 | server (or whatever server is using the certificates). If more than one | 212 | server (or whatever server is using the certificates). If more than one |
211 | B<postrenew> statements are defined, they will be run in sequence, in the | 213 | B<postrenew> statements are defined, they will be run in sequence, in the |
212 | same order as they appeared in the configuration file. | 214 | same order as they appeared in the configuration file. |
213 | 215 | ||
214 | =item B<source=>I<ID> [I<LAYOUT>] | 216 | =item B<source=>I<ID> [I<ARG>...] |
215 | 217 | ||
216 | Defines additional source of information. B<App::Acmeman> version 1.05 | 218 | Defines additional source of information. B<App::Acmeman> version 1.05 |
217 | is shipped with two sources: B<null> and B<apache>. | 219 | is shipped with three sources: B<null>, B<apache>, and B<file>. |
218 | 220 | ||
219 | The B<null> module is an empty source. Use it if all domains are described | 221 | The B<null> module is an empty source. Command line arguments are ignored. |
220 | in the configuration file. | 222 | Use this source if all domains are described in the configuration file. |
221 | 223 | ||
222 | The B<apache> source module is the default. It scans B<httpd> configuration | 224 | The B<apache> source module is the default. It scans B<httpd> configuration |
223 | files as described in section B<APACHE>. The optional I<LAYOUT> argument | 225 | files as described in section B<APACHE>. One argument is allowed. If supplied, |
224 | defines the apache configuration layout. Allowed values are: B<debian>, | 226 | it defines the apache configuration layout. Allowed values are: B<debian>, |
225 | B<slackware>, B<suse> and B<rh> (for Red Hat). If I<LAYOUT> is absent, it | 227 | B<slackware>, B<suse> and B<rh> (for Red Hat). Without arguments, the layout |
226 | will be autodetected. | 228 | will be autodetected. |
227 | 229 | ||
230 | The B<file> source reads domain names from one or more disk files. A | ||
231 | mandatory argument specifies the name of the directory where the files | ||
232 | are located. This mode is suitable for use with B<haproxy> pattern files. | ||
233 | |||
228 | =item B<files=>I<NAME> | 234 | =item B<files=>I<NAME> |
229 | 235 | ||
230 | Identifies the B<[files]> section which describes how to create certificate | 236 | Identifies the B<[files]> section which describes how to create certificate |
231 | files for domains which lack explicit B<files> keyword. Default I<NAME> is | 237 | files for domains which lack explicit B<files> keyword. Default I<NAME> is |
232 | B<default>. See the description of the B<files> statement in B<domain> | 238 | B<default>. See the description of the B<files> statement in B<domain> |
233 | section. | 239 | section. |
@@ -342,31 +348,47 @@ be present if B<type> is set to B<split>. | |||
342 | 348 | ||
343 | Defines the name of the meta-variable in I<FILENAME> arguments, which will | 349 | Defines the name of the meta-variable in I<FILENAME> arguments, which will |
344 | be replaced with the actual domain name. Default is B<$domain>. | 350 | be replaced with the actual domain name. Default is B<$domain>. |
345 | 351 | ||
346 | =back | 352 | =back |
347 | 353 | ||
348 | =head1 APACHE | 354 | =head1 SOURCES |
355 | |||
356 | =head2 null | ||
357 | |||
358 | [core] | ||
359 | source = null | ||
360 | |||
361 | Declares empty source. This means that B<acmeman> will handle only domain | ||
362 | names explicitly declared in the configuration file using the B<domain> | ||
363 | setting. | ||
364 | |||
365 | =head2 apache | ||
349 | 366 | ||
350 | This is the default mode. It assumes Apache httpd, version 2.4 or later | 367 | [core] |
368 | source = apache [LAYOUT] | ||
369 | |||
370 | This is the default source. It assumes Apache httpd, version 2.4 or later | ||
351 | (although only minor changes are necessary to make it work with version 2.2). | 371 | (although only minor changes are necessary to make it work with version 2.2). |
352 | Four most popular layouts of Apache configuration files are supported: | 372 | The optional I<LAYOUT> argument defines the layout of the apache configuration |
353 | Debian, Slackware, SuSe, and Red Hat. A special directory should be | 373 | files. Allowed layout values are: B<debian>, B<slackware>, B<suse> and |
354 | configured for receiving ACME challenges. | 374 | B<rh> (for Red Hat). If not supplied, the layout is determined automatically. |
375 | |||
376 | A special directory should be configured for receiving ACME challenges. | ||
355 | 377 | ||
356 | The package provides two Apache macros: for serving ACME challenges and | 378 | The package provides two Apache macros: for serving ACME challenges and |
357 | declaring SSL virtual hosts. | 379 | declaring SSL virtual hosts. |
358 | 380 | ||
359 | Upon startup the program scans Apache configuration for virtual hosts | 381 | Upon startup the program scans Apache configuration for virtual hosts |
360 | that use ACME certificates, checks their expiration times, and renews those | 382 | that use ACME certificates, checks their expiration times, and renews those |
361 | of the certificates that are nearing their expiration times within a | 383 | of the certificates that are nearing their expiration times within a |
362 | predefined number of seconds (24 hours by default). If any of the | 384 | predefined number of seconds (24 hours by default). If any of the |
363 | certificates were updated during the run, B<acmeman> will restart the | 385 | certificates were updated during the run, B<acmeman> will restart the |
364 | B<httpd> server. | 386 | B<httpd> server. |
365 | 387 | ||
366 | =head2 Setup | 388 | =head3 Setup |
367 | 389 | ||
368 | To set up the necessary infrastructure, run B<acmeman --setup>. It will | 390 | To set up the necessary infrastructure, run B<acmeman --setup>. It will |
369 | create the configuration file B<httpd-letsencrypt.conf>, defining two | 391 | create the configuration file B<httpd-letsencrypt.conf>, defining two |
370 | macros for SSL-enabled sites (B<mod_macro> is needed). Finally, it will | 392 | macros for SSL-enabled sites (B<mod_macro> is needed). Finally, it will |
371 | create the directory B</var/www/acme>, which will be used for receiving | 393 | create the directory B</var/www/acme>, which will be used for receiving |
372 | and serving ACME challenges. If another directory is preferred, it can | 394 | and serving ACME challenges. If another directory is preferred, it can |
@@ -383,13 +405,13 @@ will be created for each domain name needing SSL, and two files will be placed | |||
383 | there: F<cert.pem>, containing the leaf and intermediate certificates for that | 405 | there: F<cert.pem>, containing the leaf and intermediate certificates for that |
384 | domain, and F<privkey.pem>, containing the private key for that domain. | 406 | domain, and F<privkey.pem>, containing the private key for that domain. |
385 | 407 | ||
386 | The program will refuse to overwrite existing files B<httpd-letsencrypt.conf>, | 408 | The program will refuse to overwrite existing files B<httpd-letsencrypt.conf>, |
387 | unless given the B<--force> (B<-F>) option. | 409 | unless given the B<--force> (B<-F>) option. |
388 | 410 | ||
389 | =head2 Configuring SSL | 411 | =head3 Configuring SSL |
390 | 412 | ||
391 | To declare that a virtual host needs SSL certificate, add the following | 413 | To declare that a virtual host needs SSL certificate, add the following |
392 | line to the Apache B<VirtualHost> block serving plain HTTP for that host: | 414 | line to the Apache B<VirtualHost> block serving plain HTTP for that host: |
393 | 415 | ||
394 | Use LetsEncryptChallenge | 416 | Use LetsEncryptChallenge |
395 | 417 | ||
@@ -462,12 +484,32 @@ will use the B<LetsEncryptSSL> macro to configure the correct certificate: | |||
462 | <VirtualHost *:80> | 484 | <VirtualHost *:80> |
463 | ServerName git.example.org | 485 | ServerName git.example.org |
464 | Use LetsEncryptSSL example.org | 486 | Use LetsEncryptSSL example.org |
465 | ... | 487 | ... |
466 | </VirtualHost> | 488 | </VirtualHost> |
467 | 489 | ||
490 | =head2 file | ||
491 | |||
492 | [core] | ||
493 | source = file PATTERN [--ignore=RX] [--host=HOST] | ||
494 | |||
495 | Domain names will be read from files matching I<PATTERN>. This argument | ||
496 | can be either a valid globbing pattern or a directory name. In the latter | ||
497 | case, the source module will read all files from that directory, except | ||
498 | those whose names match the following perl regexp: C<^\.|~$|\.bak$|^#.*#$>. | ||
499 | The default regexp can be overridden using the B<--ignore> (B<-i>) option. | ||
500 | |||
501 | The input files must contain exactly one domain name per line. No empty | ||
502 | lines or comments are allowed. The first domain name will become the B<CN> | ||
503 | of the issued certificate. The rest of domain names will form alternative | ||
504 | names. | ||
505 | |||
506 | If the B<--host> (B<-h>) option is used, only one certificate will be | ||
507 | issued. The I<HOST> will be used as its B<CN>. All the domain names read | ||
508 | from the input files will form the list of its alternative names. | ||
509 | |||
468 | =head1 OPTIONS | 510 | =head1 OPTIONS |
469 | 511 | ||
470 | =over 4 | 512 | =over 4 |
471 | 513 | ||
472 | =item B<-D>, B<--time-delta=>I<N> | 514 | =item B<-D>, B<--time-delta=>I<N> |
473 | 515 | ||
diff --git a/lib/App/Acmeman/Source/File.pm b/lib/App/Acmeman/Source/File.pm index 561c279..48a4010 100644 --- a/lib/App/Acmeman/Source/File.pm +++ b/lib/App/Acmeman/Source/File.pm | |||
@@ -2,28 +2,38 @@ package App::Acmeman::Source::File; | |||
2 | 2 | ||
3 | use strict; | 3 | use strict; |
4 | use warnings; | 4 | use warnings; |
5 | use Carp; | 5 | use Carp; |
6 | use File::Spec; | 6 | use File::Spec; |
7 | use parent 'App::Acmeman::Source'; | 7 | use parent 'App::Acmeman::Source'; |
8 | use Getopt::Long qw(GetOptionsFromArray :config gnu_getopt no_ignore_case); | ||
8 |