|
Apache::ConfigFile - Parse an Apache style httpd.conf config file |
read(filename)cmd_config(directive)dir_config()data()dump()reread()write([file])
Apache::ConfigFile - Parse an Apache style httpd.conf config file
#
# Parse the standard Apache httpd.conf
#
use Apache::ConfigFile;
my $ac = Apache::ConfigFile->read("/etc/apache/httpd.conf");
# You can get at individual configuration commands using
# the cmd_config() method:
my $hostname = $ac->cmd_config('ServerName');
my $doc_root = $ac->cmd_config('DocumentRoot');
# Multiple values are returned as a list, meaning that you
# can directly assign them to an array or even a hash:
my @perlmods = $ac->cmd_config('PerlModule');
my %ftypes = $ac->cmd_config('FileTypeSuffix');
# Then, you can reset the context of the calls using the
# cmd_context() method so that you are accessing the
# appropriate values. For example, if you had a context
# block like
#
# <VirtualHost "10.1.1.2">
# ServerName "www.mydomain.com"
# DocumentRoot "/www/mydomain.com/htdocs"
# </VirtualHost>
#
# You would get to this definition via:
my $vh = $ac->cmd_context(VirtualHost => '10.1.1.2');
my $vhost_server_name = $vh->cmd_config('ServerName');
my $vhost_doc_root = $vh->cmd_config('DocumentRoot');
# If you had multiple VirtualHost declarations for a
# given IP (as would be the case if you're using
# NameVirtualHosts), you could cycle through them with:
for my $vh ($ac->cmd_context(VirtualHost => '10.1.1.3')) {
my $vhost_server_name = $vh->cmd_config('ServerName');
my $vhost_doc_root = $vh->cmd_config('DocumentRoot');
}
# In fact, even better you can "search" for one by specifying
# an additional set of criteria to cmd_config(). To just get
# the VirtualHost "docs.mydomain.com", for example, try:
my $docs_svr = $ac->cmd_context(VirtualHost => '10.1.1.3',
ServerName => 'docs.mydomain.com');
my $docs_base_dir = $docs_svr->cmd_config('DocumentRoot');
# In addition, this module will automatically autoload
# directive-based functions, meaning you can get to
# commonly-used commands by name:
my $host = $ac->server_name;
my $root = $ac->server_root;
my $html = $ac->document_root;
# You also get the mod_perl dir_config() command to get
# at PerlSetVar declarations by name. So, the block:
#
# <Location /myapp>
# SetHandler perl-script
# PerlHandler Apache::MyApp
# PerlSetVar MyAppRoot "/usr/myapp"
# PerlSetVar MyAppRefresh "30m"
# </Location>
#
# Would be accessed as:
my $loc = $ac->cmd_context(Location => '/myapp');
my $app_root = $loc->dir_config('MyAppRoot');
my $app_refr = $loc->dir_config('MyAppRefresh');
# Finally, you get two other utility methods. The first
# will return the current data structure verbatim, and
# the second one will return a dump which you can print
# out or parse or whatever:
my %config = $self->data;
warn "DEBUG: ", $self->dump, "\n";
This module parses the Apache httpd.conf, or any compatible config
file, and provides methods for you to access the values from the
config file. The above examples show basic usage of this module,
which boils down to reading a given config file and then using
the cmd_config() and cmd_context() functions to access its
information.
By default, the config file is parsed more or less ``verbatim'',
meaning that directives are case-sensitive, variables are not
interpolated, and so forth. These features can be changed by
options given to the read() function (see below).
The read() function is the constructor, which reads in a
configuration file and returns an object with methods that can
be used to access directives from the file. The simplest usage
is something like this:
use Apache::ConfigFile;
my $ac = Apache::ConfigFile->read("/path/to/httpd.conf");
Which would parse the Apache httpd.conf file and give you back
an $ac object with the following methods:
cmd_config()cmd_context()dir_config()PerlSetVar command (for mod_perl)
For more examples of standard Apache usage, you should read the SYNOPSIS above or skip down to the FUNCTIONS.
In addition to reading an Apache config file, this module provides some options that allow the Apache syntax to be extended. This is useful if you're writing your own application and want to use a config file resembling Apache's.
use Apache::ConfigFile;
my $ac = Apache::ConfigFile->read(
file => "/path/to/httpd.conf",
ignore_case => 1,
expand_vars => 1,
fix_booleans => 1
);
These options would allow us to write a custom config file looking like this:
BaseDir "/export"
ImageDir "$BaseDir/images"
BuildDir "$BaseDir/images"
<Release "sw7">
OfficialName "Software Update 7"
BuildPath "$BuildDir/sw7/REL"
Platforms Solaris Linux IRIX HP-UX
Supported Yes
</Release>
Then, you would be able to access it as follows:
use Apache::ConfigFile;
my $swcfg = Apache::ConfigFile->read("releases.conf");
# Note that case does not matter
my $rel = $swcfg->cmd_context(release => 'sw7');
my $ofn = $rel->cmd_config('bUiLdPaTh');
# This is autoloading + fix_booleans
unless ($rel->supported) {
die "Sorry, that release is not supported";
}
There are several things to note. First, all our cmd_ functions
are now case-insensitive, since we turned on the ignore_case
flag (which is off by default). Second, notice a couple things
about our unless statement. Since we specified fix_booleans,
the words ``Yes'', ``True'', and ``On'' will be converted to 1 (true),
and ``No'', ``False'', and ``Off'' will become 0 (false). As such,
we can use these directives in boolean statements throughout our
code.
In addition, since this module provides autoloading so that all
config commands are turned into functions, you can access values
directly, as shown by the statement $rel->supported. This
statement is equivalent to the longer $rel->cmd_config('supported').
Finally, if you just wish to manually navigate the data structure (which is a huge hash of hashes of arrays) without using the accessor functions, you can return the thing verbatim:
my %conf = $ac->data;
print "Release is $conf{'release'}\n";
However, note that the internal representation is subject to change, so using the accessor functions is recommended.
read(filename)
The read() function reads the configuration file specified and
returns an object with methods to access its directives. read()
has two calling forms. In the simplest version, you just specify
a filename, and a new Apache::ConfigFile object is returned.
Or, if you want to specify options, you specify each one as a
key/value pair. For example:
# keep default options
my $ac = Apache::ConfigFile->read("httpd.conf");
# override the case sensitivity and boolean translation
my $ac = Apache::ConfigFile->read(file => "httpd.conf",
ignore_case => 1,
fix_booleans => 1);
The list of valid options is:
/usr/local/apache/conf/httpd.conf is used by default.
1 (true), and ``No'', ``False'', and ``Off'' will
become 0 (false). This allows you to easily use these
types of directives in if statements. Defaults to 0.
$. For example:
BaseDir "/export"
HomeDir "$BaseDir/home"
Currently, you can only reuse variables defined at the very top-level. Variables defined within context blocks of any kind cannot be reused.
cmd_config(directive)This is the meat-and-potatoes of the module; the method that lets you access configuration directives from your file. Examples:
my $server_name = $ac->cmd_config('ServerName');
my $doc_root = $ac->cmd_config('DocumentRoot');
This is a straightforward function. You just give it the name of the directive you wish to access and you get its value back. Multiple values are returned as a list, meaning that you can directly assign them to an array or even a hash (if the data structure is guaranteed to be consistent enough):
my @perlmods = $ac->cmd_config('PerlModule');
my %ftypes = $ac->cmd_config('FileTypeSuffix');
You use this command to change the current context of what you are looking at. When you start, you are looking at the very top-level of the config file. However, you may want to look at a specific virtual host or directory. You can do so with this command.
my $vhost = $ac->cmd_context(VirtualHost => '10.1.1.2');
my $server_name = $vhost->cmd_config('ServerName');
my $doc_root = $vhost->cmd_config('DocumentRoot');
You'll notice that the cmd_context() call returns an
object will all the same methods, but the data structure
now starts from that point down. The context has been altered
so that you are looking at the VirtualHost 10.1.1.2. As such,
any commands that you do will affect that part of the configuration.
In some cases, you may have multiple definitions for a certain
context level. One example is VirtualHost blocks if you're
using NameVirtualHosts. You have two options. First, you
could cycle through all of them in sequence:
for my $vhost ($ac->cmd_context(VirtualHost => '10.1.1.2')) {
# ... do stuff ...
}
Or, if you know which one you want specifically, you can specify
one additional ``search'' parameter. For example, if you want the
superfoo server, you could say:
my $sf = $ac->cmd_context(VirtualHost => '10.1.1.2',
ServerName => 'superfoo');
And this would look for a context block that looked something like this:
<VirtualHost "10.1.1.2">
ServerName "superfoo"
# ... more config options ...
</VirtualHost>
You can access nested configurations as well. If you had a configuration like this:
<Location "/upload">
SetHandler perl-script
PerlHandler Apache::MyUploadModule
PerlSetVar MyUploadModuleMaxsize "5M"
PerlSetVar MyUploadModuleTimeout "300s"
<Limit>
require user "bob"
require user "jim"
</Limit>
</Location>
And you wanted to find out what the valid users were who could access this page, you would navigate it like so:
my $loc = $ac->cmd_context(Location => '/upload');
my $lim = $loc->cmd_context('Limit');
my @users = $lim->cmd_config('require');
Or, more succintly:
my @users = $ac->cmd_context(Location => '/upload')
->cmd_context('Limit')->cmd_config('require');
Since cmd_context() returns an object pointing to the next
context, you can chain calls together to get to a deeply nested
level.
dir_config()This routine is provided for mod_perl compatibility. It allows
you to access configuration commands specified via the PerlSetVar
directive. So, assuming the above example, you could access the
settings for MyUploadModule like so:
my $upload = $ac->cmd_context(Location => '/upload');
my $maxsize = $upload->dir_config('MyUploadModuleMaxsize');
my $timeout = $upload->dir_config('MyUploadModuleTimeout');
The idea is to provide an interface which walks and talks roughly like Apache actually would.
data()This returns the entire data structure under the current context
verabatim. So, you could get all the values for a VirtualHost
with:
my $vh = $ac->cmd_context(VirtualHost => '10.1.1.4');
my %vhost = $vh->data;
If you specified ignore_case, then all the keys will be
lowercase; otherwise, they will be in whatever case they are in
the config file.
dump()This returns a dump of the current data structure in string form. So for debugging purposes you can dump the config with something like this:
warn "DUMP: ", $ac->dump, "\n";
reread()You can use this function to reread the configuration file. For
example, maybe you want your application to reread its config
if it receives a SIGHUP:
$SIG{HUP} = \&handler;
sub handler {
my $sig = shift;
if ($sig eq 'HUP') {
# reread our config file on kill -HUP
$config->reread;
}
}
The above would handle a SIGHUP by rereading the config file.
write([file])This writes the configuration out to disk. If no file is specified,
then the one passed to read() is used. This method is currently
under development and does not work. Patches welcome.
In addition to the above, you can also access values by calling a function named for the config command directly:
my $server_name = $ac->cmd_config('ServerName');
Is the same as:
my $server_name = $ac->server_name;
Underscores in the function name are taken as a place to put an uppercase letter. So these are all equivalent:
my $doc_root = $ac->cmd_config('DocumentRoot');
my $doc_root = $ac->DocumentRoot; # looks silly
my $doc_root = $ac->document_root;
Note, though, that the following would not work unless you had
set the ignore_case option:
my $doc_root = $ac->documentroot; # won't work
This is because it will look for the directive Documentroot,
which probably doesn't exist.
Currently LogFormat and any other directive with embedded quotes,
even if escaped, are not handled correctly. I know there is a fix for
it but I have a mental block and can't figure it out. Help wanted.
This module does not mimic the behavior of a live Apache config. In particular, there is no configuration ``inheritance''. This means that subdirectories and virtual hosts do not inherit their defaults from the upper levels of the configuration. This may or may not change in a future version.
This module has only been tested and used on UNIX platforms. Patches to fix problems with other OSes are welcome.
There are currently no tests written for this module. Sorry, short on time. Inventive (or even non-inventive!) tests welcome.
$Id: ConfigFile.pm,v 1.14 2001/09/06 23:57:54 nwiger Exp $
Copyright (c) 1999-2001, Nathan Wiger <nate@wiger.org>. All Rights Reserved.
This module is free software; you may copy this under the terms of the GNU General Public License, or the Artistic License, copies of which should have accompanied your Perl kit.
|
Apache::ConfigFile - Parse an Apache style httpd.conf config file |