NAME

       Apache::Vhosts::Common - Lib for common operations in vhosts inventory

DESCRIPTION

       This package is meant to contain common functions used by OCS modules for Apache virtualhosts.

       For example, we could have two OCS modules:

       ApacheVhostsPackaged
           which would deal with packaged apache setups

       ApacheVhostsCompiled
           which would deal with compiled apache versions

       At  different  times,  these  modules  still  would  need  to  do the same things, such as parsing apache
       configuration files, reading and extracting information from a vhost dump,  reading  a  x509  certificate
       with openssl, ...

       To avoid code duplication, the specific modules can call the functions contained in this common package.

   Exports
       The module exports the following functions:

       "readVhostsDump"
       "readVhostConfFile"

   readVhostsDump()
       Return  an  array  of  hashes  with  the  virtualhosts  found  thanks to Apache's vhosts dump ("httpd -S"
       command).

       Return type

       The function returns a reference to an array of hashes.

       Process

       The function's workflow is as follows:

       1.  Open "httpd -S" command output, with the current configuration file

       2.  Read dump line by line to match IP-based or name-based virtualhost information (both types  of  lines
           should be recognized):

            port 80 namevhost mynamevhost.fr (/etc/httpd/.../10-mynamevhost.conf:50)
            10.0.0.1:80 myvhost myipvhost.fr (/etc/httpd/.../20-myipvhost.conf:1)

       3.  Create a hash with the virtualhost's data

           We put the following attributes in it:

            (string) computedname, (int) port, (string) srvname,
            (string) vhostfile, (string) vhostline, (string) docroot, (bool) ssl

           At this stage we do not know docroot or ssl, so they are "/nonexistent" and false (0), respectively.

       4.  Push the vhost hash to the array.

       Return example

        [
          {
            'computedname' => "[httpd] myvhost.fr:80",
            'port' => 80,
            'srvname' => 'myvhost.fr',
            'vhostfile' => '/etc/httpd/conf.d/10-myvhost.conf',
            'vhostline' => 1,
            'docroot' => '/nonexistent',
            'ssl' => 0
          },
          {
            'computedname' => "[httpd] myvhost.fr:443",
            'port' => 443,
            'srvname' => 'myvhost.fr',
            'vhostfile' => '/etc/httpd/conf.d/10-myvhost.conf',
            'vhostline' => 20,
            'docroot' => '/nonexistent',
            'ssl' => 0
          }
        ]

       Calling

           my $vhosts = readVhostsDump($httpd_bin, $httpd_conf_file, $logger);

       Parameter: $httpd_bin (string)
           Path to the httpd binary to execute (for example: "/usr/sbin/httpd").  Specific options (such as "-D"
           parameters) may be added to the string.

       Parameter: $httpd_conf_file (string)
           Path to the main httpd configuration file (for example: "/etc/httpd/conf/httpd.conf").

       Parameter: $logger (reference to OCS logger instance)
           To make use of OCS logging capabilities within the function.

   readVhostConfFile()
       Enhance a virtualhost's information with elements found when parsing the vhost's configuration file.

       Return type

       The function returns nothing.

       It only operates on the (referenced) vhost hash it got in parameter.

       Process

       The  function  must  read  the  apache  configuration file in which the vhost gets defined (<VirtualHost>
       block).

       The path to the particular configuration file and the line number of the vhost declaration are  known  in
       the "vhostfile" and "vhostline" attributes, thanks to the vhost dump.

       The function's process, for the given vhost, is as follows:

       1.  Open the configuration file at "vhostfile"

       2.  Read  line  by  line,  waiting  to  be  at  correct  line number ("vhostline") to start searching for
           information.

       3.  Search for the following information in the <VirtualHost> and enhance the given vhost hash with:

           •   docroot (string)

               the value of the "DocumentRoot" directive

           •   ssl (bool)

               we turn it to true if we find a "SSLEngine on" directive

           •   sslcertpath (string)

               value of the "SSLCertificateFile" directive, if such a directive is present

       4.  File reading stops when we find the "</VirtualHost>" closing  block  (in  case  multiple  vhosts  are
           declared in the same configuration file).

       Calling

           foreach my $vhost (@$vhosts) # Generally
           {
               readVhostConfFile($vhost, $httpd_basedir);
           }

       Parameter: $vhost (reference to hash)
           The virtualhost hash to enhance.

       Parameter: $httpd_basedir (string)
           The path to base directory of httpd, in case we encounter a relative path in "SSLCertificateFile" and
           need to complete it.

           IMPORTANT: the given path is expected to end with a slash '/', for example:

               "/etc/httpd/"

perl v5.40.1                                       2025-06-07             Ocsinventory::A...:Vhosts::Common(3pm)