Provided by: libapp-info-perl_0.57-1_all bug

NAME

       App::Info::HTTPD::Apache - Information about Apache web server

SYNOPSIS

         use App::Info::HTTPD::Apache;

         my $apache = App::Info::HTTPD::Apache->new;

         if ($apache->installed) {
             print "App name: ", $apache->name, "\n";
             print "Version:  ", $apache->version, "\n";
             print "Bin dir:  ", $apache->bin_dir, "\n";
         } else {
             print "Apache is not installed. :-(\n";
         }

DESCRIPTION

       App::Info::HTTPD::Apache supplies information about the Apache web server installed on the
       local system. It implements all of the methods defined by App::Info::HTTPD. Methods that
       trigger events will trigger them only the first time they're called (See App::Info for
       documentation on handling events). To start over (after, say, someone has installed
       Apache) construct a new App::Info::HTTPD::Apache object to aggregate new meta data.

       Some of the methods trigger the same events. This is due to cross-calling of methods or of
       functions common to methods. However, any one event should be triggered no more than once.
       For example, although the info event "Executing `httpd -v`" is documented for the methods
       "name()", "version()", "major_version()", "minor_version()", and "patch_version()", rest
       assured that it will only be triggered once, by whichever of those four methods is called
       first.

INTERFACE

   Constructor
       new

         my $apache = App::Info::HTTPD::Apache->new(@params);

       Returns an App::Info::HTTPD::Apache object. See App::Info for a complete description of
       argument parameters.

       When called, "new()" searches the the directories returned by "search_bin_dirs()" for an
       executable with a name returned by "search_exe_names()". If found, the executable
       (hereafter referred to as httpd, regardless of how it was actually found to be named) will
       be called by the object methods below to gather the data necessary for each. If httpd
       cannot be found, then Apache is assumed not to be installed, and each of the object
       methods will return "undef".

       In addition to the parameters supported by the parent classes, App::Info and
       App::Info::HTTPD, this class' "new()" method also supports:

       search_conf_names
           An array reference of possible names for Apache configuration files. These will be
           returned by the "search_conf_names()" method before the default names, and may be used
           by "conf_file()" to search for the configuration file.

       search_conf_dirs
           An array reference of possible directories in which to search for Apache configuration
           files. These will be returned by the "search_conf_dirs()" method before the default
           directories, and may be used by "conf_file()" to search for the configuration file.

       As well as these parameters to specify alternate names for Apache executables (other than
       httpd, which you specify via the "search_exe_names" parameter):

       search_ab_names
       search_apachectl_names
       search_apxs_names
       search_htdigest_names
       search_htpasswd_names
       search_logresolve_names
       search_rotatelogs_names

       Events:

       info
           Looking for Apache executable

       confirm
           Path to your httpd executable?

       unknown
           Path to your httpd executable?

   Class Method
       key_name

         my $key_name = App::Info::HTTPD::Apache->key_name;

       Returns the unique key name that describes this class. The value returned is the string
       "Apache".

   Object Methods
       installed

         print "apache is ", ($apache->installed ? '' : 'not '),
           "installed.\n";

       Returns true if Apache is installed, and false if it is not.  App::Info::HTTPD::Apache
       determines whether Apache is installed based on the presence or absence of the httpd
       application on the file system, as found when "new()" constructed the object. If Apache
       does not appear to be installed, then all of the other object methods will return empty
       values.

       name

         my $name = $apache->name;

       Returns the name of the application. App::Info::HTTPD::Apache parses the name from the
       system call "`httpd -v`".

       Events:

       info
           Executing `httpd -v`

       error
           Failed to find Apache version data with `httpd -v`

           Failed to parse Apache name and version from string

       unknown
           Enter a valid Apache name

       version

         my $version = $apache->version;

       Returns the apache version number. App::Info::HTTPD::Apache parses the version number from
       the system call "`httpd -v`".

       Events:

       info
           Executing `httpd -v`

       error
           Failed to find Apache version data with `httpd -v`

           Failed to parse Apache name and version from string

       unknown
           Enter a valid Apache version number

       major_version

         my $major_version = $apache->major_version;

       Returns the Apache major version number. App::Info::HTTPD::Apache parses the version
       number from the system call "`httpd --v`". For example, if "version()" returns "1.3.24",
       then this method returns "1".

       Events:

       info
           Executing `httpd -v`

       error
           Failed to find Apache version data with `httpd -v`

           Failed to parse Apache name and version from string

       unknown
           Enter a valid Apache major version number

       minor_version

         my $minor_version = $apache->minor_version;

       Returns the Apache minor version number. App::Info::HTTPD::Apache parses the version
       number from the system call "`httpd --v`". For example, if "version()" returns "1.3.24",
       then this method returns "3". See the version method for a list of possible errors.

       Events:

       info
           Executing `httpd -v`

       error
           Failed to find Apache version data with `httpd -v`

           Failed to parse Apache name and version from string

       unknown
           Enter a valid Apache minor version number

       patch_version

         my $patch_version = $apache->patch_version;

       Returns the Apache patch version number. App::Info::HTTPD::Apache parses the version
       number from the system call "`httpd --v`". For example, if "version()" returns "1.3.24",
       then this method returns "24".

       Events:

       info
           Executing `httpd -v`

       error
           Failed to find Apache version data with `httpd -v`

           Failed to parse Apache name and version from string

       unknown
           Enter a valid Apache patch version number

       httpd_root

         my $httpd_root = $apache->httpd_root;

       Returns the HTTPD root directory path. This path is defined at compile time, and
       App::Info::HTTPD::Apache parses it from the system call "`httpd -V`".

       Events:

       info
           Executing `httpd -V`

       error
           Unable to extract compile settings from `httpd -V`

           Cannot parse HTTPD root from `httpd -V`

       unknown
           Enter a valid HTTPD root

       magic_number

         my $magic_number = $apache->magic_number;

       Returns the "Magic Number" for the Apache installation. This number is defined at compile
       time, and App::Info::HTTPD::Apache parses it from the system call "`httpd -V`".

       Events:

       info
           Executing `httpd -V`

       error
           Unable to extract compile settings from `httpd -V`

           Cannot parse HTTPD root from `httpd -V`

       unknown
           Enter a valid magic number

       compile_option

         my $compile_option = $apache->compile_option($option);

       Returns the value of the Apache compile option $option. The compile option is looked up
       case-insensitively. All of the Apache compile options are collected from the system call
       "`httpd -V`". For compile options that contain a corresponding value (such as "SUEXEC_BIN"
       or "DEFAULT_PIDLOG"), "compile_option()" returns the value of the option if the option
       exists. For other options, it returns true (1) if the option was included, and
       false("undef") if it was not. Returns "undef" if Apache is not installed or if the option
       could not be parsed. See the httpd_root method for a list of possible errors.

       See the Apache documentation at <http://httpd.apache.org/docs-project/> to learn about all
       the possible compile options.

       Events:

       info
           Executing `httpd -V`

       error
           Unable to extract compile settings from `httpd -V`

           Cannot parse HTTPD root from `httpd -V`

       unknown
           Enter a valid option

       conf_file

       Returns the full path to the Apache configuration file. "conf_file()" looks for the
       configuration file in a number of locations and under a number of names. First it tries to
       use the file specified by the "SERVER_CONFIG_FILE" compile option (as returned by a call
       to "compile_option()") -- and if it's a relative file name, it gets appended to the
       directory returned by "httpd_root()". If that file isn't found, "conf_file()" then looks
       for a file with one of the names returned by "search_conf_names()" in the conf
       subdirectory of the HTTPD root directory. Failing that, it searches for them in each of
       the directories returned by "search_conf_dirs()" until it finds a match.

       Events:

       info
           Searching for Apache configuration file

       error
           No Apache config file found

       unknown
           Location of httpd.conf file?

       user

         my $user = $apache->user;

       Returns the name of the Apache user. This value is collected from the Apache configuration
       file as returned by "conf_file()".

       Events:

       info
           Searching for Apache configuration file

           Executing `httpd -V`

           Parsing Apache configuration file

       error
           No Apache config file found

           Cannot parse user from file

           Cannot parse group from file

           Cannot parse port from file

           Cannot parse DocumentRoot from file

       unknown
           Location of httpd.conf file?

           Enter Apache user name

       group

       Returns the name of the Apache user group. This value is collected from the Apache
       configuration file as returned by "conf_file()".

       Events:

       info
           Searching for Apache configuration file

           Executing `httpd -V`

           Parsing Apache configuration file

       error
           No Apache config file found

           Cannot parse user from file

           Cannot parse group from file

           Cannot parse port from file

           Cannot parse DocumentRoot from file

       unknown
           Location of httpd.conf file?

           Enter Apache user group name

       port

       Returns the port number on which Apache listens. This value is collected from Apache
       configuration file as returned by "conf_file()".

       Events:

       info
           Searching for Apache configuration file

           Executing `httpd -V`

           Parsing Apache configuration file

       error
           No Apache config file found

           Cannot parse user from file

           Cannot parse group from file

           Cannot parse port from file

           Cannot parse DocumentRoot from file

       unknown
           Location of httpd.conf file?

           Enter Apache TCP/IP port number

       doc_root

       Returns the local physical path where web pages are stored. This value is collected from
       Apache configuration file as returned by "conf_file()".

       Events:

       info
           Searching for Apache configuration file

           Executing `httpd -V`

           Parsing Apache configuration file

       error
           No Apache config file found

           Cannot parse user from file

           Cannot parse group from file

           Cannot parse port from file

           Cannot parse DocumentRoot from file

       unknown
           Location of httpd.conf file?

           Enter DocumentRoot actual directory

       cgibin_virtual

       Returns the virtual path where cgi-bin programs are stored. This value is collected from
       Apache configuration file as returned by "conf_file()".

       Events:

       info
           Searching for Apache configuration file

           Executing `httpd -V`

           Parsing Apache configuration file

       error
           No Apache config file found

           Cannot parse user from file

           Cannot parse group from file

           Cannot parse port from file

           Cannot parse ScriptAlias from file

       unknown
           Location of httpd.conf file?

           Enter ScriptAlias virtual directory

       cgibin_physical

       Returns the physical path where cgi-bin programs are stored. This value is collected from
       Apache configuration file as returned by "conf_file()".

       Events:

       info
           Searching for Apache configuration file

           Executing `httpd -V`

           Parsing Apache configuration file

       error
           No Apache config file found

           Cannot parse user from file

           Cannot parse group from file

           Cannot parse port from file

           Cannot parse ScriptAlias from file

       unknown
           Location of httpd.conf file?

           Enter ScriptAlias physical directory

       executable

         my $executable = $apache->executable;

       Returns the path to the Apache executable, which will be defined by one of the names
       returned by "search_exe_names()". The executable is searched for in "new()", so there are
       no events for this method.

       httpd

         my $httpd = $apache->httpd;

       An alias for "executable()".

       bin_dir

         my $bin_dir = $apache->bin_dir;

       Returns the SQLite binary directory path. App::Info::HTTPD::Apache simply retrieves it as
       the directory part of the path to the HTTPD executable.

       inc_dir

         my $inc_dir = $apache->inc_dir;

       Returns the Apache include directory path. App::Info::HTTPD::Apache simply looks for the
       include or inc directory under the httpd_root directory, as returned by "httpd_root()".

       Events:

       info
           Executing `httpd -V`

           Searching for include directory

       error
           Unable to extract compile settings from `httpd -V`

           Cannot parse HTTPD root from `httpd -V`

           Cannot find include directory

       unknown
           Enter a valid HTTPD root

           Enter a valid Apache include directory

       lib_dir

         my $lib_dir = $apache->lib_dir;

       Returns the Apache library directory path. App::Info::HTTPD::Apache simply looks for the
       lib, modules, or libexec directory under the HTTPD root> directory, as returned by
       "httpd_root()".

       Events:

       info
           Executing `httpd -V`

           Searching for library directory

       error
           Unable to extract compile settings from `httpd -V`

           Cannot parse HTTPD root from `httpd -V`

           Cannot find library directory

       unknown
           Enter a valid HTTPD root

           Enter a valid Apache library directory

       so_lib_dir

         my $so_lib_dir = $apache->so_lib_dir;

       Returns the Apache shared object library directory path. Currently, this directory is
       assumed to be the same as the lib directory, so this method is simply an alias for
       "lib_dir".

       Events:

       info
           Executing `httpd -V`

           Searching for library directory

       error
           Unable to extract compile settings from `httpd -V`

           Cannot parse HTTPD root from `httpd -V`

           Cannot find library directory

       unknown
           Enter a valid HTTPD root

           Enter a valid Apache library directory

       static_mods

       Returns a list (in an array context) or an anonymous array (in a scalar context) of all of
       the modules statically compiled into Apache. These are collected from the system call
       "`httpd -l`". If Apache is not installed, "static_mods()" returns an empty list in an
       array context or an empty anonymous array in a scalar context.

       Events:

       info
           Executing `httpd -l`

       error
           Unable to extract needed data from `httpd -l`

       shared_mods

       Returns a list (in an array context) or an anonymous array (in a scalar context) of all of
       the shared modules compiled for Apache. These are collected by searching for all files
       ending in .so in the directory returned from the system call "`apxs -q LIBEXECDIR`". If
       Apache is not installed, "shared_mods()" returns an empty list in an array context or an
       empty anonymous array in a scalar context.

       Events:

       info
           Looking for apxs

           Executing `apxs -q LIBEXECDIR`

       error
           Unable to extract module directory name from `apxs -q LIBEXECDIR`

       mod_so

       Boolean method that returns true when mod_so has been compiled into Apache, and false if
       it has not. The presence or absence of mod_so is determined by the system call "`httpd
       -l`".

       Events:

       info
           Executing `httpd -l`

       error
           Unable to extract needed data from `httpd -l`

       mod_perl

       Boolean method that returns true when mod_perl has been statically compiled into Apache,
       and false if it has not. The presence or absence of mod_perl is determined by the system
       call "`httpd -l`" or, for a dynamic mod_perl, by the contents of the directory returned by
       the system call "`apxs -q LIBEXECDIR`".

       Events:

       info
           Executing `httpd -l`

           Looking for apxs

           Executing `apxs -q LIBEXECDIR`

       error
           Unable to extract needed data from `httpd -l`

       home_url

         my $home_url = $apache->home_url;

       Returns the Apache home page URL.

       download_url

         my $download_url = $apache->download_url;

       Returns the Apache download URL.

       search_exe_names

         my @search_exe_names = $apache->search_exe_names;

       Returns a list of possible names for the Apache executable; .exe is appended to each on
       Win32. By default, the names are:

       httpd
       httpd2
       apache-perl
       apache
       apache2

       search_bin_dirs

         my @search_bin_dirs = $apache->search_bin_dirs;

       Returns a list of possible directories in which to search an executable. Used by the
       "new()" constructor to find an executable to execute and collect application info. The
       found directory will also be returned by the "bin_dir" method.

       The list of directories by default consists of the path as defined by "File::Spec->path"
       and the value returned by "Apache2::BuildConfig->new->{APXS_BINDIR}" (if
       Apache2::BuildConfig is installed), as well as the following directories:

       /usr/local/apache/bin
       /usr/local/apache2/bin
       /opt/apache/bin
       /opt/apache2/bin
       /usr/local/bin
       /usr/local/sbin
       /usr/bin
       /usr/sbin
       /bin
       /etc/httpd/bin
       /etc/apache/bin
       /etc/apache2/bin
       /home/httpd/bin
       /home/apache/bin
       /home/apache2/bin
       /sw/bin
       /sw/sbin
       /web/httpd

       search_lib_dirs

         my @search_lib_dirs = $apache->search_lib_dirs;

       Returns a list of possible directories in which to search for Apache libraries. By
       default, it returns this list of directories, each appended to the name of the directory
       returned by "httpd_root()":

       lib
       modules
       libexec

       search_inc_dirs

         my @search_inc_dirs = $apache->search_inc_dirs;

       Returns a list of possible directories in which to search for Apache include files. By
       default, it returns this list of directories, each appended to the name of the directory
       returned by "httpd_root()":

       include
       inc

       search_conf_names

         my @search_conf_dirs = $apache->search_conf_dirs;

       Returns a list of possible names for Apache configuration files. These will be used bye
       the "conf_file()" method to search for Apache configuration files.  By Default, the
       possible configuration file names are:

       httpd.conf
       httpd.conf.default

       search_conf_dirs

         my @search_conf_dirs = $apache->search_conf_dirs;

       Returns a list of directories in which the "conf_file()" method will search for Apache
       configuration files.

       /usr/share/doc/apache-perl
       /etc/httpd

   Other Executable Methods
       These methods return the complete paths to their like-named executables.  Apache comes
       with a fair number of them; we provide these methods to provide a path to a subset of
       them. Each method, when called, checks for an executable in the directory returned by
       "bin_dir()". The name of the executable must be one of the names returned by the
       corresponding "search_*_names" method.

       The available executable methods are:

       ab
       apachectl
       apxs
       htdigest
       htpasswd
       logresolve
       rotatelogs

       And the corresponding search names methods are:

       search_ab_names
       search_apachectl_names
       search_apxs_names
       search_htdigest_names
       search_htpasswd_names
       search_logresolve_names
       search_rotatelogs_names

       Events:

       info
           Looking for executable

       confirm
           Path to executable?

       unknown
           Path to executable?

KNOWN ISSUES

       It's likely that a lot more can be done to collect data about Apache. The methodology for
       determining the lib, inc, bin, and so_lib directories in particular may be considered
       rather weak. And the Port number can be specified multiple ways (and times!) in an Apache
       configuration file. Patches from those who know a great deal more about interrogating
       Apache will be most welcome.

TO DO

       Add method to return the names of available DSOs. These should either be parsed from the
       httpd.conf file or "glob"bed from the file system.

SUPPORT

       This module is stored in an open GitHub repository <http://github.com/theory/app-info/>.
       Feel free to fork and contribute!

       Please file bug reports via GitHub Issues <http://github.com/theory/app-info/issues/> or
       by sending mail to bug-App-Info@rt.cpan.org <mailto:bug-App-Info@rt.cpan.org>.

AUTHOR

       David E. Wheeler <david@justatheory.com> based on code by Sam Tregar <sam@tregar.com>.

SEE ALSO

       App::Info documents the event handling interface.

       App::Info::HTTPD is the App::Info::HTTP::Apache parent class.

       Apache and mod_perl_mod_perl document mod_perl.

       <http://httpd.apache.org/> is the Apache web server home page.

       <http://perl.apache.org/> is the mod_perl home page.

COPYRIGHT AND LICENSE

       Copyright (c) 2002-2011, David E. Wheeler. Some Rights Reserved.

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