1NAME
2 Apache::ConfigFile - Parse an Apache style httpd.conf configuration file
3
4SYNOPSIS
5 #
6 # Parse the standard Apache httpd.conf
7 #
8 use Apache::ConfigFile;
9 my $ac = Apache::ConfigFile->read("/etc/apache/httpd.conf");
10
11 # You can get at individual configuration commands using
12 # the cmd_config() method:
13
14 my $hostname = $ac->cmd_config('ServerName');
15 my $doc_root = $ac->cmd_config('DocumentRoot');
16
17 # Multiple values are returned as a list, meaning that you
18 # can directly assign them to an array:
19
20 my @perlmods = $ac->cmd_config('PerlModule');
21
22 # And, you can use the cmd_config_hash() routine to get at
23 # multiple settings where the first is a type of "key":
24
25 my %ftypes = $ac->cmd_config_hash('FileTypeSuffix');
26
27 # Then, you can reset the context of the calls using the
28 # cmd_context() method so that you are accessing the
29 # appropriate values. For example, if you had a context
30 # block like
31 #
32 # <VirtualHost "10.1.1.2">
33 # ServerName "www.mydomain.com"
34 # DocumentRoot "/www/mydomain.com/htdocs"
35 # </VirtualHost>
36 #
37 # You would get to this definition via:
38
39 my $vh = $ac->cmd_context(VirtualHost => '10.1.1.2');
40 my $vhost_server_name = $vh->cmd_config('ServerName');
41 my $vhost_doc_root = $vh->cmd_config('DocumentRoot');
42
43 # If you had multiple VirtualHost declarations for a
44 # given IP (as would be the case if you're using
45 # NameVirtualHosts), you could cycle through them with:
46
47 for my $vh ($ac->cmd_context(VirtualHost => '10.1.1.3')) {
48 my $vhost_server_name = $vh->cmd_config('ServerName');
49 my $vhost_doc_root = $vh->cmd_config('DocumentRoot');
50 }
51
52 # In fact, even better you can "search" for one by specifying
53 # an additional set of criteria to cmd_config(). To just get
54 # the VirtualHost "docs.mydomain.com", for example, try:
55
56 my $docs_svr = $ac->cmd_context(VirtualHost => '10.1.1.3',
57 ServerName => 'docs.mydomain.com');
58 my $docs_base_dir = $docs_svr->cmd_config('DocumentRoot');
59
60 # In addition, this module will automatically autoload
61 # directive-based functions, meaning you can get to
62 # commonly-used commands by name:
63
64 my $host = $ac->server_name;
65 my $root = $ac->server_root;
66 my $html = $ac->document_root;
67
68 # You also get the mod_perl dir_config() command to get
69 # at PerlSetVar declarations by name. So, the block:
70 #
71 # <Location /myapp>
72 # SetHandler perl-script
73 # PerlHandler Apache::MyApp
74 # PerlSetVar MyAppRoot "/usr/myapp"
75 # PerlSetVar MyAppRefresh "30m"
76 # </Location>
77 #
78 # Would be accessed as:
79
80 my $loc = $ac->cmd_context(Location => '/myapp');
81 my $app_root = $loc->dir_config('MyAppRoot');
82 my $app_refr = $loc->dir_config('MyAppRefresh');
83
84 # Finally, you get two other utility methods. The first
85 # will return the current data structure verbatim, and
86 # the second one will return a dump which you can print
87 # out or parse or whatever:
88
89 my %config = $self->data;
90 warn "DEBUG: ", $self->dump, "\n";
91
92UNSUPPORTED
93 I am no longer supporting this module in any way, shape, or form, so it is truly provided "as-is". It has
94 some edge-case bugs which will not be fixed. It will work on 95+% of Apache config files.
95
96 I believe some alternative modules, including Apache::Admin::Config and Config::ApacheFormat, are being
97 actively supported still, although this may or may not be true by the time you read this.
98
99 In case you care, the main reason I wrote this was to support Apache-like config files as a general case. But
100 it turns out the core `httpd.conf' is rife with special cases, and is just plain a pain in the ass.
101
102 If you would like to take over maintenance of this module, please contact me at `nate@wiger.org'
103
104DESCRIPTION
105 This module parses the Apache httpd.conf, or any compatible config file, and provides methods for you to
106 access the values from the config file. The above examples show basic usage of this module, which boils down
107 to reading a given config file and then using the `cmd_config()' and `cmd_context()' functions to access its
108 information.
109
110 By default, the config file is parsed more or less "verbatim", meaning that directives are case-sensitive,
111 variables are not interpolated, and so forth. These features can be changed by options given to the `read()'
112 function (see below).
113
114 The `read()' function is the constructor, which reads in a configuration file and returns an object with
115 methods that can be used to access directives from the file. The simplest usage is something like this:
116
117 use Apache::ConfigFile;
118 my $ac = Apache::ConfigFile->read("/path/to/httpd.conf");
119
120 Which would parse the Apache `httpd.conf' file and give you back an `$ac' object with the following methods:
121
122 cmd_config()
123 Used to access individual configuration commands
124
125 cmd_context()
126 Used to change the context of the commands you're accessing
127
128 dir_config()
129 Used to access values set via the `PerlSetVar' command (like `mod_perl')
130
131 For more examples of standard Apache usage, you should read the the section on "/"SYNOPSIS" above or skip
132 down to the the section on "/"FUNCTIONS".
133
134 In addition to reading an Apache config file, this module provides some options that allow the Apache syntax
135 to be extended. This is useful if you're writing your own application and want to use a config file
136 resembling Apache's.
137
138 use Apache::ConfigFile;
139 my $ac = Apache::ConfigFile->read(
140 file => "/path/to/httpd.conf",
141 ignore_case => 1,
142 expand_vars => 1,
143 fix_booleans => 1
144 );
145
146 These options would allow us to write a custom config file looking like this:
147
148 BaseDir "/export"
149 ImageDir "$BaseDir/images"
150 BuildDir "$BaseDir/images"
151
152 <Release "sw7">
153 OfficialName "Software Update 7"
154 BuildPath "$BuildDir/sw7/REL"
155 Platforms Solaris Linux IRIX HP-UX
156 Supported Yes
157 </Release>
158
159 Then, you would be able to access it as follows:
160
161 use Apache::ConfigFile;
162 my $swcfg = Apache::ConfigFile->read("releases.conf");
163
164 # Note that case does not matter
165 my $rel = $swcfg->cmd_context(release => 'sw7');
166 my $ofn = $rel->cmd_config('bUiLdPaTh');
167
168 # This is autoloading + fix_booleans
169 unless ($rel->supported) {
170 die "Sorry, that release is not supported";
171 }
172
173 There are several things to note. First, all our `cmd_' functions are now case-insensitive, since we turned
174 on the `ignore_case' flag (which is off by default). Second, notice a couple things about our `unless'
175 statement. Since we specified `fix_booleans', the words "Yes", "True", and "On" will be converted to `1'
176 (true), and "No", "False", and "Off" will become `0' (false). As such, we can use these directives in boolean
177 statements throughout our code.
178
179 In addition, since this module provides autoloading so that all config commands are turned into functions,
180 you can access values directly, as shown by the statement `< $rel-'supported >>. This statement is equivalent
181 to the longer `< $rel-'cmd_config('supported') >>.
182
183 Finally, if you just wish to manually navigate the data structure (which is a huge hash of hashes of arrays)
184 without using the accessor functions, you can return the thing verbatim:
185
186 my %conf = $ac->data;
187 print "Release is $conf{'release'}\n";
188
189 However, note that the internal representation is subject to change, so using the accessor functions is
190 recommended.
191
192FUNCTIONS
193 read(filename)
194
195 read(file => filename, opt => val, opt => val)
196
197 The `read()' function reads the configuration file specified and returns an object with methods to access its
198 directives. `read()' has two calling forms. In the simplest version, you just specify a filename, and a new
199 `Apache::ConfigFile' object is returned. Or, if you want to specify options, you specify each one as a
200 key/value pair. For example:
201
202 # keep default options
203 my $ac = Apache::ConfigFile->read("httpd.conf");
204
205 # override the case sensitivity and boolean translation
206 my $ac = Apache::ConfigFile->read(file => "httpd.conf",
207 ignore_case => 1,
208 fix_booleans => 1);
209
210 The list of valid options is:
211
212 file
213 Path to configuration file. If not provided then `/usr/local/apache/conf/httpd.conf' is used by default.
214
215 ignore_case
216 If set to 1, then all directives will be case-insensitive and stored in lowercase. Defaults to 0.
217
218 fix_booleans
219 If set to 1, then the words "Yes", "True", and "On" will be converted to `1' (true), and "No", "False",
220 and "Off" will become `0' (false). This allows you to easily use these types of directives in if
221 statements. Defaults to 0.
222
223 expand_vars
224 If set to 1, then you can reuse variables that you have defined elsewhere in the config file by prefixing
225 them with a `$'. For example:
226
227 BaseDir "/export"
228 HomeDir "$BaseDir/home"
229
230 Currently, you can only reuse variables defined at the very top-level. Variables defined within context
231 blocks of any kind cannot be reused.
232
233 raise_error
234 If set to 1, any type of error becomes fatal. Defaults to 0.
235
236 inherit_from
237 If set, then context blocks inherit from the specified default context. For example, say you have the
238 blocks:
239
240 <Category kitchen>
241 Name "Soup Kitchen"
242 Email "soup@kitchen.com"
243 Access all
244 </Category>
245
246 <Category tomato_soup>
247 Name "Tomato Soup"
248 </Category>
249
250 If you then specified:
251
252 ->read(..., inherit_from => 'kitchen');
253
254 Then all those variables that are not seen in the `tomato_soup' block would be filled in based on their
255 values from the `kitchen' block. So, `tomato_soup' would inherit `Email' and `Access' from `kitchen', but
256 would provide its own `Name'.
257
258 Note: In order for this to work, the block providing the inherited items MUST appear first, as shown
259 above.
260
261 root_directive
262 If set this specifies a directive other than RootDirective for relative path resolutions. For example:
263
264 ApplicationRoot /usr/local/etc
265
266 my $ac = Apache::ConfigFile->read(
267 file => "/usr/local/etc/app.config",
268 root_directive => 'ApplicationRoot'
269 );
270
271 This will cause /usr/local/etc to be added to relative paths for includes, etc. With this additional
272 behavior, the term ServerRoot, as used elsewhere in this document, comes to mean any directive that is
273 specified via this option. Also note that the default value of this option is 'ServerRoot'.
274
275 server_root
276 This explicitly sets the ServerRoot for relative path resolutions for includes, etc. This option
277 overrides any ServerRoot values found in the config file.
278
279 cmd_config(directive)
280
281 This is the meat-and-potatoes of the module; the method that lets you access configuration directives from
282 your file. Examples:
283
284 my $server_name = $ac->cmd_config('ServerName');
285 my $doc_root = $ac->cmd_config('DocumentRoot');
286
287 This is a fairly straightforward function. You just give it the name of the directive you wish to access and
288 you get its value back. Each time you call it, you will get the value for the next available instance of that
289 variable. If called in a scalar context, you will just get the first value, assumed to be the "key".
290
291 What this means is that if you have a config file like this:
292
293 ErrorDocument 404 /errors/404.cgi
294 ErrorDocument 500 /errors/500.cgi
295
296 To get each line you would use a `while' loop:
297
298 while (my @line = $ac->cmd_config('ErrorDocument')) {
299 print "For error $line[0] we're using $line[1]\n";
300 }
301
302 Which should print:
303
304 For error 404 we're using /errors/404.cgi
305 For error 500 we're using /errors/500.cgi
306
307 If you want more flexibility, read the following two functions.
308
309 cmd_config_array(directive)
310
311 This returns the entire data structure for a given directive as an array of arrays. So, you could get all the
312 `ErrorDocument' configs by saying:
313
314 my @errors = $ac->cmd_config_array('ErrorDocument');
315
316 Then, you would have to iterate over these yourself, since each element is an array reference:
317
318 for my $e (@errors) {
319 print "Code is $e->[0] and script is $e->[1]\n";
320 }
321
322 Which should print:
323
324 Code is 404 and script is /errors/404.cgi
325 Code is 500 and script is /errors/500.cgi
326
327 Assuming the same configuration as above.
328
329 cmd_config_hash(directive)
330
331 This is perhaps the most useful form. It returns a set of key/value pairs where the key is the first element
332 and the value is the rest of the line. This is great for handling `FileTypeSuffix' or `AddHandler' lines, for
333 example:
334
335 my %handler = $ac->cmd_config_hash('AddHandler');
336
337 This would return a hash where the keys would be the first field, such as `cgi-script' or `server-parsed',
338 and value is the remaining line as an array reference.
339
340 As such, you could access a specific one as:
341
342 print "Suffixes for CGI scripts are: @{$handler{cgi-script}}\n";
343
344 Which should print out something like this:
345
346 Suffixes for CGI scripts are: .cgi .pl
347
348 Note that you had to derefence the value inside of a `@{}' since the value is an array reference. This is so
349 that you can get a list of values reliably. For example:
350
351 my %handler = $ac->cmd_config_hash('AddHandler');
352 my @cgi_suffixes = @{$handler{cgi-script}};
353 my @shtml_suffixed = @{$handler{server-parsed}};
354
355 That way you get the proper values even in the case of embedded whitespace. In addition, it allows you to
356 define your own complex directives:
357
358 # Format: key "Real Name" option1 option2 option3
359 CustomField lname "Last Name"
360 CustomField ctry "Country" US CA MX JP Other
361
362 Then in your code:
363
364 my %custom_field = $ac->cmd_config_hash('CustomField');
365 while(my($key, $val) = each %custom_field) {
366 my $label = shift(@$val) || ucfirst($key);
367 # see if we have any options remaining
368 if (@$val) {
369 # have options; create select list
370 print qq($label: <select name="$key">\n");
371 for my $opt (@$val) {
372 print qq(<option value="$opt">$opt</option>\n);
373 }
374 print qq(</select>\n);
375 } else {
376 # no options; text field
377 print qq($label: <input name="$key" type="text type="text"">\n);
378 }
379 }
380
381 That way you could use an Apache style config file to setup a custom form based application.
382
383 cmd_context(context => specification)
384
385 You use this command to change the current context of what you are looking at. When you start, you are
386 looking at the very top-level of the config file. However, you may want to look at a specific virtual host or
387 directory. You can do so with this command.
388
389 my $vhost = $ac->cmd_context(VirtualHost => '10.1.1.2');
390 my $server_name = $vhost->cmd_config('ServerName');
391 my $doc_root = $vhost->cmd_config('DocumentRoot');
392
393 You'll notice that the `cmd_context()' call returns an object will all the same methods, but the data
394 structure now starts from that point down. The context has been altered so that you are looking at the `<
395 <VirtualHost "10.1.1.2"' >>. block. As such, any commands that you do will affect that part of the
396 configuration.
397
398 In some cases, you may have multiple definitions for a certain context level. One example is `VirtualHost'
399 blocks if you're using `NameVirtualHosts'. You have two options. First, you could cycle through all of them
400 in sequence:
401
402 for my $vhost ($ac->cmd_context(VirtualHost => '10.1.1.2')) {
403 # ... do stuff ...
404 }
405
406 However, you may not know what you're looking for. In this case, if you can iterate through all of them with
407 something like this:
408
409 for my $vhost ($ac->cmd_context('VirtualHost')) {
410 # ... do stuff ...
411 }
412
413 Since you didn't specify a specific block, the special var `_' will be set with the text tag for that block.
414 Printing it out will reveal which `VirtualHost' (or whatever) you're in:
415
416 print $vhost->cmd_config('_'); # "10.1.1.2"
417
418 Conversely, you may know *exactly* which one you're looking for. If so, you can specify one additional
419 "search" parameter. For example, if you want the `superfoo' server, you could say:
420
421 my $sf = $ac->cmd_context(VirtualHost => '10.1.1.2',
422 ServerName => 'superfoo');
423
424 And this would look for a context block that looked something like this:
425
426 <VirtualHost "10.1.1.2">
427 ServerName "superfoo"
428 # ... more config options ...
429 </VirtualHost>
430
431 you can easily access nested configurations as well. If you had a configuration like this:
432
433 <Location "/upload">
434 SetHandler perl-script
435 PerlHandler Apache::MyUploadModule
436 PerlSetVar MyUploadModuleMaxsize "5M"
437 PerlSetVar MyUploadModuleTimeout "300s"
438 <Limit>
439 require user "bob"
440 require user "jim"
441 </Limit>
442 </Location>
443
444 And you wanted to find out what the valid users were who could access this page, you would navigate it like
445 so:
446
447 my $loc = $ac->cmd_context(Location => '/upload');
448 my $lim = $loc->cmd_context('Limit');
449 my @users = $lim->cmd_config('require');
450
451 Or, more succintly:
452
453 my @users = $ac->cmd_context(Location => '/upload')
454 ->cmd_context(Limit => '')->cmd_config('require');
455
456 Since `cmd_context()' returns an object pointing to the next context, you can chain calls together to get to
457 a deeply nested level.
458
459 dir_config()
460
461 This routine is provided for `mod_perl' compatibility. It allows you to access configuration commands
462 specified via the `PerlSetVar' directive. So, assuming the above example, you could access the settings for
463 `MyUploadModule' like so:
464
465 my $upload = $ac->cmd_context(Location => '/upload');
466
467 my $maxsize = $upload->dir_config('MyUploadModuleMaxsize');
468 my $timeout = $upload->dir_config('MyUploadModuleTimeout');
469
470 The idea is to provide an interface which walks and talks roughly like Apache actually would.
471
472 data()
473
474 This returns the entire data structure under the current context verabatim. So, you could get all the values
475 for a `VirtualHost' with:
476
477 my $vh = $ac->cmd_context(VirtualHost => '10.1.1.4');
478 my %vhost = $vh->data;
479
480 If you specified `ignore_case', then all the keys will be lowercase; otherwise, they will be in whatever case
481 they are in the config file.
482
483 dump()
484
485 This returns a dump of the current data structure in string form. So for debugging purposes you can dump the
486 config with something like this:
487
488 warn "DUMP: ", $ac->dump, "\n";
489
490 reread()
491
492 You can use this function to reread the configuration file. For example, maybe you want your application to
493 reread its config if it receives a `SIGHUP':
494
495 $SIG{HUP} = \&handler;
496 sub handler {
497 my $sig = shift;
498 if ($sig eq 'HUP') {
499 # reread our config file on kill -HUP
500 $config->reread;
501 }
502 }
503
504 The above would handle a `SIGHUP' by rereading the config file.
505
506 write([file])
507
508 This writes the configuration out to disk. If no file is specified, then the one passed to `read()' is used.
509 This method is currently under development and does not work. Patches welcome.
510
511 autoloaded calls
512
513 In addition to the above, you can also access values by calling a function named for the config command
514 directly:
515
516 my $server_name = $ac->cmd_config('ServerName');
517
518 Is the same as:
519
520 my $server_name = $ac->server_name;
521
522 Underscores in the function name are taken as a place to put an uppercase letter. So these are all
523 equivalent:
524
525 my $doc_root = $ac->cmd_config('DocumentRoot');
526 my $doc_root = $ac->DocumentRoot; # looks silly
527 my $doc_root = $ac->document_root;
528
529 Note, though, that the following would not work unless you had set the `ignore_case' option:
530
531 my $doc_root = $ac->documentroot; # won't work
532
533 This is because it will look for the directive `Documentroot', which probably doesn't exist.
534
535ALIASES
536 When I initially wrote this module, I tried to follow the internal Apache API pretty closely. However, for
537 those unfamiliar with Apache these method names probably make little sense. As such, the following function
538 aliases are provided
539
540 directive
541 Same as `cmd_config()'
542
543 directive_array
544 Same as `cmd_config_array()'
545
546 directive_hash
547 Same as `cmd_config_hash()'
548
549 section
550 Same as `cmd_context()'
551
552 So this code:
553
554 my $vh = $ac->cmd_context(VirtualHost => '10.1.1.2');
555 my $vhost_server_name = $vh->cmd_config('ServerName');
556 my $vhost_doc_root = $vh->cmd_config('DocumentRoot');
557 my %error_handlers = $ac->cmd_config_hash('ErrorDocument');
558
559 Could be rewritten as the following and work exactly the same:
560
561 my $vh = $ac->section(VirtualHost => '10.1.1.2');
562 my $vhost_server_name = $vh->directive('ServerName');
563 my $vhost_doc_root = $vh->directive('DocumentRoot');
564 my %error_handlers = $ac->directive_hash('ErrorDocument');
565
566 These will always be supported so feel free to use them.
567
568NOTES
569 Currently `LogFormat' and any other directive with embedded quotes, even if escaped, are not handled
570 correctly. I know there is a fix for it but I have a mental block and can't figure it out. Help!
571
572 Currently, the order of context blocks is not maintained. So, if you define two blocks:
573
574 <Directory "/">
575 Options +MultiViews
576 </Directory>
577
578 <Directory "/var/apache/htdocs">
579 Options +ExecCGI
580 </Directory>
581
582 There will be no way for you to tell the order in which these were defined. Normally this should not matter,
583 since the idea of a context section is to create a logical entity. However, patches to overcome this
584 limitation are welcomed.
585
586 This module has only been tested and used on UNIX platforms. It may or may not be broke elsewhere.
587
588VERSION
589 $Id: ConfigFile.pm,v 1.23 2003/10/09 18:24:41 nwiger Exp $
590
591AUTHOR
592 Copyright (c) 1999-2003, Nathan Wiger <nate@wiger.org>. All Rights Reserved.
593
594 This module is free software; you may copy this under the terms of the GNU General Public License, or the
595 Artistic License, copies of which should have accompanied your Perl kit.
596
597