GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  CONFIG::APACHEFORMAT (3)

.ds Aq ’

NAME

Config::ApacheFormat - use Apache format config files

CONTENTS

SYNOPSIS

Config files used with this module are in Apache’s format:



  # comment here
  RootDir /path/foo
  LogDir  /path/foo/log
  Colors red green orange blue \
         black teal

  <Directory /path/foo>
     # override Colors inside block
     Colors red blue black
  </Directory>



Code to use this config file might look like:



  use Config::ApacheFormat;

  # load a conf file
  my $config = Config::ApacheFormat->new();
  $config->read("my.conf");

  # access some parameters
  $root_dir = $config->get("RootDir");
  $log_dir  = $config->get("LogDir");
  @colors   = $config->get("colors");

  # using the autoloaded methods
  $config->autoload_support(1);
  $root_dir = $config->RootDir;
  $log_dir  = $config->logdir;

  # access parameters inside a block
  my $block = $config->block(Directory => "/path/foo");
  @colors = $block->get("colors");
  $root_dir = $block->get("root_dir");



DESCRIPTION

This module is designed to parse a configuration file in the same syntax used by the Apache web server (see http://httpd.apache.org for details). This allows you to build applications which can be easily managed by experienced Apache admins. Also, by using this module, you’ll benefit from the support for nested blocks with built-in parameter inheritance. This can greatly reduce the amount or repeated information in your configuration files.

A good reference to the Apache configuration file format can be found here:



  http://httpd.apache.org/docs-2.0/configuring.html



To quote from that document, concerning directive syntax:



 Apache configuration files contain one directive per line. The
 back-slash "\" may be used as the last character on a line to
 indicate that the directive continues onto the next line. There must
 be no other characters or white space between the back-slash and the
 end of the line.

 Directives in the configuration files are case-insensitive, but
 arguments to directives are often case sensitive. Lines that begin
 with the hash character "#" are considered comments, and are
 ignored. Comments may not be included on a line after a configuration
 directive. Blank lines and white space occurring before a directive
 are ignored, so you may indent directives for clarity.



And block notation:



 Directives placed in the main configuration files apply to the entire
 server. If you wish to change the configuration for only a part of the
 server, you can scope your directives by placing them in <Directory>,
 <DirectoryMatch>, <Files>, <FilesMatch>, <Location>, and
 <LocationMatch> sections. These sections limit the application of the
 directives which they enclose to particular filesystem locations or
 URLs. They can also be nested, allowing for very fine grained
 configuration.



This module will parse actual Apache configuration files, but you will need to set some options to non-default values. See Parsing a Real Apache Config File.

METHODS

$config = Config::ApacheFormat->new(opt => ‘‘value’’) This method creates an object that can then be used to read configuration files. It does not actually read any files; for that, use the read() method below. The object supports the following attributes, all of which may be set through new():
inheritance_support Set this to 0 to turn off the inheritance feature. Block inheritance means that variables declared outside a block are available from inside the block unless overriden. Defaults to 1.
include_support When this is set to 1, the directive Include will be treated specially by the parser. It will cause the value to be treated as a filename and that filename will be read in. If you use Include with a directory, every file in that directory will be included. This matches Apache’s behavior and allows users to break up configuration files into multiple, possibly shared, pieces. Defaults to 1.
autoload_support Set this to 1 and all your directives will be available as object methods. So instead of:



  $config->get("foo");



You can write:



  $config->foo;



Defaults to 0.

case_sensitive Set this to 1 to preserve the case of directive names. Otherwise, all names will be lc()ed and matched case-insensitively. Defaults to 0.
fix_booleans If set to 1, then during parsing, the strings Yes, On, and True will be converted to 1, and the strings No, Off, and False will be converted to 0. This allows you to more easily use get() in conditional statements.

For example:



  # httpd.conf
  UseCanonicalName  On



Then in Perl:



  $config = Config::ApacheFormat->new(fix_booleans => 1);
  $config->read("httpd.conf");

  if ($config->get("UseCanonicalName")) {
      # this will get executed if set to Yes/On/True
  }



This option defaults to 0.

expand_vars If set, then you can use variable expansion in your config file by prefixing directives with a $. Hopefully this seems logical to you:



  Website     http://my.own.dom
  JScript     $Website/js
  Images      $Website/images



Undefined variables in your config file will result in an error. To use a literal $, simply prefix it with a \ (backslash). Like in Perl, you can use brackets to delimit the variables more precisely:



  Nickname    Rob
  Fullname    ${Nickname}ert



Since only scalars are supported, if you use a multi-value, you will only get back the first one:



  Options     Plus Minus "About the Same"
  Values      $Options



In this examples, Values will become Plus. This is seldom a limitation since in most cases, variable subsitution is used like the first example shows. This option defaults to 0.

setenv_vars If this is set to 1, then the special SetEnv directive will be set values in the environment via %ENV. Also, the special UnSetEnv directive will delete environment variables.

For example:



  # $ENV{PATH} = "/usr/sbin:/usr/bin"
  SetEnv PATH "/usr/sbin:/usr/bin"

  # $ENV{MY_SPECIAL_VAR} = 10
  SetEnv MY_SPECIAL_VAR 10

  # delete $ENV{THIS}
  UnsetEnv THIS



This option defaults to 0.

valid_directives If you provide an array of directive names then syntax errors will be generated during parsing for invalid directives. Otherwise, any directive name will be accepted. For exmaple, to only allow directives called Bar and Bif:



  $config = Config::ApacheFormat->new(
                      valid_directives => [qw(Bar Bif)],
                                     );



valid_blocks If you provide an array of block names then syntax errors will be generated during parsing for invalid blocks. Otherwise, any block name will be accepted. For exmaple, to only allow Directory and Location blocks in your config file:



  $config = Config::ApacheFormat->new(
                      valid_blocks => [qw(Directory Location)],
                                     );



include_directives This directive controls the name of the include directive. By default it is [Include], but you can set it to any list of directive names.
root_directive This controls what the root directive is, if any. If you set this to the name of a directive it will be used as a base directory for Include processing. This mimics the behavior of ServerRoot in real Apache config files, and as such you’ll want to set it to ’ServerRoot’ when parsing an Apache config. The default is undef.
hash_directives This determines which directives (if any) should be parsed so that the first value is actually a key into the remaining values. For example, AddHandler is such a directive.



  AddHandler cgi-script .cgi .sh
  AddHandler server-parsed .shtml



To parse this correctly, use:



  $config = Config::ApacheFormat->new(
                      hash_directives => [qw(AddHandler PerlSetVar)]
                                     );



Then, use the two-argument form of get():



  @values = $config->get(AddHandler => cgi-script);



This allows you to access each directive individually, which is needed to correctly handle certain special-case Apache settings.

duplicate_directives This option controls how duplicate directives are handled. By default, if multiple directives of the same name are encountered, the last one wins:



  Port 8080
  # ...
  Port 5053



In this case, the directive Port would be set to the last value, 5053. This is useful because it allows you to include other config files, which you can then override:



  # default setup
  Include /my/app/defaults.conf

  # override port
  Port 5053



In addition to this default behavior, Config::ApacheFormat also supports the following modes:



  last     -  the value from the last one is kept (default)
  error    -  duplicate directives result in an error
  combine  -  combine values of duplicate directives together



These should be self-explanatory. If set to error, any duplicates will result in an error. If set to last (the default), the last value wins. If set to combine, then duplicate directives are combined together, just like they had been specified on the same line.

All of the above attributes are also available as accessor methods. Thus, this:



  $config = Config::ApacheFormat->new(inheritance_support => 0,
                                      include_support => 1);



Is equivalent to:



  $config = Config::ApacheFormat->new();
  $config->inheritance_support(0);
  $config->include_support(1);



$config->read(‘‘my.conf’’);
$config->read(\*FILE); Reads a configuration file into the config object. You must pass either the path of the file to be read or a reference to an open filehandle. If an error is encountered while reading the file, this method will die().

Calling read() more than once will add the new configuration values from another source, overwriting any conflicting values. Call clear() first if you want to read a new set from scratch.

$value = $config->get(‘‘var_name’’)
@vals = $config->get(‘‘list_name’’)
$value = $config->get(‘‘hash_var_name’’, ‘‘key’’) Returns values from the configuration file. If the directive contains a single value, it will be returned. If the directive contains a list of values then they will be returned as a list. If the directive does not exist in the configuration file then nothing will be returned (undef in scalar context, empty list in list context).

For example, given this confiuration file:



  Foo 1
  Bar bif baz bop



The following code would work as expected:



  my $foo = $config->get("Foo");   # $foo = 1
  my @bar = $config->get("Bar");   # @bar = ("bif", "baz", "bop")



If the name is the name of a block tag in the configuration file then a list of available block specifiers will be returned. For example, given this configuration file:



  <Site big>
     Size 10
  </Site>

  <Site small>
     Size 1
  </Site>



This call:



  @sites = $config->get("Site");



Will return ([ Site = big], [ Site => small ])>. These arrays can then be used with the block() method described below.

If the directive was included in the file but did not have a value, 1 is returned by get().

Calling get() with no arguments will return the names of all available directives.

Directives declared in hash_directives require a key value:



  $handler = $config->get("AddHandler", "cgi-script");



directive() is available as an alias for get().

$block = $config->block(‘‘BlockName’’)
$block = $config->block(Directory => ‘‘/foo/bar’’)
$block = $config->block(Directory => ‘‘~’’ => ‘‘^.*/bar’’) This method returns a Config::ApacheFormat object used to access the values inside a block. Parameters specified within the block will be available. Also, if inheritance is turned on (the default), values set outside the block that are not overwritten inside the block will also be available. For example, given this file:



  MaxSize 100

  <Site "big">
     Size 10
  </Site>

  <Site "small">
     Size 1
  </Site>



this code:



  print "Max: ", $config->get("MaxSize"), "\n";

  $block = $config->block(Site => "big");
  print "Big: ", $block->get("Size"), " / ",
                 $block->get("MaxSize"), "\n";

  $block = $config->block(Site => "small");
  print "Small: ", $block->get("Size"), " / ",
                   $block->get("MaxSize"), "\n";



will print:



  Max: 100
  Big: 10 / 100
  Small: 1 / 100



Note that block() does not require any particular number of parameters. Any number will work, as long as they uniquely identify a block in the configuration file. To get a list of available blocks, use get() with the name of the block tag.

This method will die() if no block can be found matching the specifier passed in.

$config->clear() Clears out all data in $config. Call before re-calling $config->read() for a fresh read.
$config->dump() This returns a dumped copy of the current configuration. It can be used on a block object as well. Since it returns a string, you should say:



    print $config->dump;



Or:



    for ($config->block(VirtualHost => 10.1.65.1)) {
        print $_->dump;
    }



If you want to see any output.

Parsing a Real Apache Config File

To parse a real Apache config file (ex. httpd.conf) you’ll need to use some non-default options. Here’s a reasonable starting point:



  $config = Config::ApacheFormat->new(
              root_directive     => ServerRoot,
              hash_directives    => [ AddHandler ],
              include_directives => [ Include,
                                      AccessConfig,
                                      ResourceConfig ],
              setenv_vars        => 1,
              fix_booleans       => 1);



TODO

Some possible ideas for future development:
o Add a set() method. (useless?)
o Add a write() method to create a new configuration file. (useless?)

BUGS

I know of no bugs in this software. If you find one, please create a bug report at:



  http://rt.cpan.org/



Include the version of the module you’re using and a small piece of code that I can run which demonstrates the problem.

COPYRIGHT AND LICENSE

Copyright (C) 2002-2003 Sam Tregar

This program is free software; you can redistribute it and/or modify it under the same terms as Perl 5 itself.

AUTHORS

Sam Tregar <sam@tregar.com> Original author and maintainer
Nathan Wiger <nate@wiger.org> Porting of features from Apache::ConfigFile

SEE ALSO

Apache::ConfigFile

Apache::ConfigParser

POD ERRORS

Hey! <B>The above document had some coding errors, which are explained below:B>
Around line 94: ’=item’ outside of any ’=over’
Around line 1017: You forgot a ’=back’ before ’=head1’
Around line 1068: ’=item’ outside of any ’=over’
Around line 1076: You forgot a ’=back’ before ’=head1’
Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 APACHEFORMAT (3) 2003-11-04

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.