NAME

Apache::ConfigParser - Load Apache configuration files

SYNOPSIS

use Apache::ConfigParser;

# Create a new empty parser.
my $c1 = Apache::ConfigParser->new;

# Create a new parser and load a specific configuration file.
my $c2 = Apache::ConfigParser->new('/etc/httpd/conf/httpd.conf');

# Load a configuration file explicitly.
$c1->parse_file('/etc/httpd/conf/httpd.conf');

# Get the root of a tree that represents the configuration file.
# This is an Apache::ConfigParser::Directive object.
my $root = $c1->root;

# Get all of the directives and starting of context's.
my @directives = $root->daughters;

# Get the first directive's name.
my $d_name = $directives[0]->name;

# This directive appeared in this file, which may be in an Include'd
# file.
my $d_filename = $directives[0]->filename;

# And it begins on this line number.
my $d_line_number = $directives[0]->line_number;

# Find all the CustomLog entries, regardless of context.
my @custom_logs = $c1->find_at_and_down_option_names('CustomLog');

# Get the first CustomLog.
my $custom_log = $custom_logs[0];

# Get the value in string form.
$custom_log_args = $custom_log->value;

# Get the value in array form already split.
my @custom_log_args = $custom_log->get_value_array;

# Get the same array but a reference to it.
my $customer_log_args = $custom_log->value_array_ref;

# The first value in a CustomLog is the filename of the log.
my $custom_log_file = $custom_log_args->[0];

# Get the original value before the path has been made absolute.
@custom_log_args   = $custom_log->get_orig_value_array;
$customer_log_file = $custom_log_args[0];

DESCRIPTION

The Apache::ConfigParser module is used to load an Apache configuration file to allow programs to determine Apache's configuration options. The resulting object contains a tree based structure using the Apache::ConfigParser::Directive class, which is a subclass of Tree::DAG_node, so all of the methods that enable tree based searches and modifications. The tree structure is used to represent the ability to nest sections, such as <VirtualHost>, <Directory>, etc.

Apache does a great job of checking Apache configuration files for errors and this modules leaves most of that to Apache. This module does minimal configuration file checking. The module currently checks for:

Start and end context names match

The module checks if the start and end context names match. If the end context name does not match the start context name, then it is ignored. The module does not even check if the configuration options modules have valid names.

PARSING

Notes regarding parsing of configuration files.

Line continuation is treated exactly as Apache 1.3.20. Line continuation occurs only when the line ends in [^\\]\\\r?\n. If the line ends in two \'s, then it will replace the two \'s with one \ and not continue the line.

EXPORTED VARIABLES

The following variables are exported via @EXPORT_OK.

%directive_has_non_abs_path

This hash is keyed by the lowercase version of a directive name. The hash value is a subroutine reference. If a hash entry exists for a particular entry, then the directive name can take a non absolute path, such as a relative path that may need to be made absolute, or a pipe to a command or an option to direct messages to syslog. The subroutine reference stored in the hash takes a single variable which should be the potential file path entry. It returns 1 if the potential filename does not match any strings that are valid non-file or non-directory values for the directive. It does not check if the value is a valid file or directory path. It also does not check if the path is absolute, File::Spec-file_name_is_absolute> can be used to check that in an operating system independent manner.

For example, ErrorLog can take a filename, such as

ErrorLog /var/log/httpd/error_log

or a piped command, such as

ErrorLog "| cronolog /var/log/httpd/%Y/%m/%d/error.log"

or a syslog entry of the two forms:

ErrorLog syslog
ErrorLog syslog:local7

The particular subroutine for ErrorLog checks if the value is not equal to File::Spec-devnull>, does not begin with a | or does not match syslog(:[a-zA-Z0-9]+)?.

On all operating systems, these subroutines return 0 if the value is equal to File::Spec-devnull> in a case sensitive or case insensitive manner depending upon the operating system.

These subroutines do not remove any "'s before checking on the type of value.

This is a list of directives and any special values to check for as of Apache 1.3.20.

AccessConfig
AuthGroupFile
AuthUserFile
CookieLog
CustomLog       check for "| command"
ErrorLog        check for "| command", or syslog or syslog:facility
Include
LoadFile
LoadModule
LockFile
MimeMagicFile
PidFile
RefererLog      check for "| command"
ResourceConf
ScoreBoardFile
ScriptLog
TransferLog     check for "| command"
TypesConfig

METHODS

The following methods are available:

$c = Apache::ConfigParser->new

$c = Apache::ConfigParser->new({options})

$c = Apache::ConfigParser->new($filename)

$c = Apache::ConfigParser->new({options}, $filename)

Create a new Apache::ConfigParser object that stores the content of an Apache configuration file. The first optional argument is a reference to a hash that contains options to new.

If $filename is given, then the contents of $filename will be loaded. If $filename cannot be be opened then $! will contain the error message for the failed open() and new will returns an empty list in a list content, an undefined value in a scalar context, or nothing in a void context.

The currently recognized options are:

pre_transform_path_sub => sub { }

pre_transform_path_sub => [sub { }, @args]

This allows the file or directory name for any directive that takes either a filename or directory name to be transformed by an arbitrary subroutine before it is made absolute with ServerRoot. This transformation is applied to any of the directives that appear in %directive_has_non_abs_path that have a filename or directory value instead of a pipe or syslog value, i.e. "| cronolog" or "syslog:warning".

If the second form of pre_transform_path_sub is used with an array reference, then the first element of the array reference must be a subroutine reference followed by zero or more arbitrary arguments. Any array elements following the subroutine reference are passed to the specified subroutine.

The subroutine is passed the following arguments:

Apache::ConfigParser object
lowercase string of the configuration directive
the file or directory name to transform
@args

If the subroutine returns an undefined value or a value with 0 length, then it is replaced with <File::Spec->devnull> which is the appropriate 0 length file for the operating system. This is done to keep a value in the directive name since otherwise the directive may not work properly. For example, with the input

CustomLog logs/access_log combined

and if pre_transform_path_sub were to replace 'logs/access_log' with '', then

CustomLog combined

would no longer be a valid directive. Instead,

CustomLog C<File::Spec->devnull> combined

would be appropriate for all systems.

post_transform_path_sub => sub { }

post_transform_path_sub => [sub { }, @args]

This allows the file or directory name for any directive that takes either a filename or directory name to be transformed by this subroutine after it is made absolute with ServerRoot. This transformation is applied to any of the directives that appear in %directive_has_non_abs_path that have a filename or directory value instead of a pipe or syslog value, i.e. "| cronolog" or "syslog:warning".

If the second form of post_transform_path_sub is used with an array reference, then the first element of the array reference must be a subroutine reference followed by zero or more arbitrary arguments. Any array elements following the subroutine reference are passed to the specified subroutine.

The subroutine is passed the following arguments:

Apache::ConfigParser object
lowercase version of the configuration directive
the file or directory name to transform
@args

If the subroutine returns an undefined value or a value with 0 length, then it is replaced with <File::Spec->devnull> which is the appropriate 0 length file for the operating system. This is done to keep a value in the directive name since otherwise the directive may not work properly. For example, with the input

CustomLog logs/access_log combined

and if post_transform_path_sub were to replace 'logs/access_log' with '', then

CustomLog combined

would no longer be a valid directive. Instead,

CustomLog C<File::Spec->devnull> combined

would be appropriate for all systems.

One example of where the transformations is useful is when the Apache configuration directory on one host is NFS exported to another host and the remote host parses the configuration file using Apache::ConfigParser and the paths to the access logs must be transformed so that the remote host can properly find them.

$c->DESTROY

There is an explicit DESTROY method for this class to destroy the tree, since it has cyclical references.

$c->parse_file($filename)

This method takes a filename and adds it to the already loaded configuration file inside the object. If a previous Apache configuration file was loaded either with new or parse_file and the configuration file did not close all of its contexts, such as <VirtualHost>, then the new configuration options in $filename will be added to the existing context. If $filename could not be opened, then $! will contain the reason for open's failure.

$c->root

Returns the root of the tree that represents the Apache configuration file. Each object here is a Apache::ConfigParser::Directive.

$c->find_at_and_down_option_names('option', ...)

$c->find_at_and_down_option_names($node, 'option', ...)

In list context, returns the list all of $c options that match the option names listed at the level of $node and below. In scalar context, returns the number of such options. The level here is in a tree sense, not in the sense that some options appear $node in the configuration file. If $node is given, then the search is started at $node, includes $node and searches $node's children. If $node is not passed, then it starts at the top of the tree and searches the whole configuration file.

All of the option names are made lowercase.

This is useful if you want to find all of the CustomLog's in the configuration file:

my @logs = $c->find_at_and_down_option_names('CustomLog');

$c->find_in_siblings_option_names('option', ...)

$c->find_in_siblings_option_names($node, 'option', ...)

In list context, returns the list of all $c options that match the option names at the same level of $node, that is siblings of $node. In scalar context, returns the number of such options. The level here is in a tree sense, not in the sense that some options appear $node in the configuration file. If $node is not given or $node is the passed and it is $c-tree>, then it will search through root's children.

All of the option names are made lowercase.

$c->find_in_siblings_and_up_option_names($node, 'option', ...)

In list context, returns the list of all $c options that match the option names at the same level of $node, that is siblings of $node, and above $node. In scalar context, returns the number of such options. The level here is in a tree sense, not in the sense that some options appear $node in the configuration file. In this method $node is a required option, because it does not make sense to check the root node.

All of the option names are made lowercase.

This is useful when you find an option and you want to find an associated option. For example, find all of the CustomLog's and find the associated ServerName.

foreach my $log_node ($c->find_at_and_down_option_names('CustomLog')) {
  my $log_filename = $log_node->name;
  my @server_names = $c->find_in_siblings_and_up_option_names($log_node);
  my $server_name  = $server_names[0];
  print "ServerName for $log_filename is $server_name\n";
}

$c->dump

Return an array of lines that represents the internal state of the tree.

SEE ALSO

Apache::ConfigParser::Directive and Tree::DAG_Node.

AUTHOR

Blair Zajac <blair@orcaware.com>.

COPYRIGHT

Copyright (C) 2001 Blair Zajac. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.