.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Ocsinventory::Agent::Modules::Apache::Vhosts::Common 3pm"
.TH Ocsinventory::Agent::Modules::Apache::Vhosts::Common 3pm "2020-09-14" "perl v5.30.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Apache::Vhosts::Common \- Lib for common operations in vhosts inventory
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This package is meant to contain common functions used by \s-1OCS\s0 modules for
Apache virtualhosts.
.PP
For example, we could have two \s-1OCS\s0 modules:
.IP "ApacheVhostsPackaged" 4
.IX Item "ApacheVhostsPackaged"
which would deal with packaged apache setups
.IP "ApacheVhostsCompiled" 4
.IX Item "ApacheVhostsCompiled"
which would deal with compiled apache versions
.PP
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, ...
.PP
To avoid code duplication, the specific modules can call the functions
contained in this common package.
.SS "Exports"
.IX Subsection "Exports"
The module exports the following functions:
.ie n .IP """readVhostsDump""" 4
.el .IP "\f(CWreadVhostsDump\fR" 4
.IX Item "readVhostsDump"
.PD 0
.ie n .IP """readVhostConfFile""" 4
.el .IP "\f(CWreadVhostConfFile\fR" 4
.IX Item "readVhostConfFile"
.PD
.SS "\fBreadVhostsDump()\fP"
.IX Subsection "readVhostsDump()"
Return an array of hashes with the virtualhosts found thanks to Apache's vhosts
dump (\f(CW\*(C`httpd \-S\*(C'\fR command).
.PP
\fIReturn type\fR
.IX Subsection "Return type"
.PP
The function returns a reference to an array of hashes.
.PP
\fIProcess\fR
.IX Subsection "Process"
.PP
The function's workflow is as follows:
.IP "1." 4
Open \f(CW\*(C`httpd \-S\*(C'\fR command output, with the current configuration file
.IP "2." 4
Read dump line by line to match IP-based or name-based virtualhost information
(both types of lines should be recognized):
.Sp
.Vb 2
\& 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)
.Ve
.IP "3." 4
Create a hash with the virtualhost's data
.Sp
We put the following attributes in it:
.Sp
.Vb 2
\& (string) computedname, (int) port, (string) srvname,
\& (string) vhostfile, (string) vhostline, (string) docroot, (bool) ssl
.Ve
.Sp
At this stage we do not know docroot or ssl, so they are \*(L"/nonexistent\*(R" and
false (0), respectively.
.IP "4." 4
Push the vhost hash to the array.
.PP
\fIReturn example\fR
.IX Subsection "Return example"
.PP
.Vb 10
\& [
\&   {
\&     \*(Aqcomputedname\*(Aq => "[httpd] myvhost.fr:80",
\&     \*(Aqport\*(Aq => 80,
\&     \*(Aqsrvname\*(Aq => \*(Aqmyvhost.fr\*(Aq,
\&     \*(Aqvhostfile\*(Aq => \*(Aq/etc/httpd/conf.d/10\-myvhost.conf\*(Aq,
\&     \*(Aqvhostline\*(Aq => 1,
\&     \*(Aqdocroot\*(Aq => \*(Aq/nonexistent\*(Aq,
\&     \*(Aqssl\*(Aq => 0
\&   },
\&   {
\&     \*(Aqcomputedname\*(Aq => "[httpd] myvhost.fr:443",
\&     \*(Aqport\*(Aq => 443,
\&     \*(Aqsrvname\*(Aq => \*(Aqmyvhost.fr\*(Aq,
\&     \*(Aqvhostfile\*(Aq => \*(Aq/etc/httpd/conf.d/10\-myvhost.conf\*(Aq,
\&     \*(Aqvhostline\*(Aq => 20,
\&     \*(Aqdocroot\*(Aq => \*(Aq/nonexistent\*(Aq,
\&     \*(Aqssl\*(Aq => 0
\&   }
\& ]
.Ve
.PP
\fICalling\fR
.IX Subsection "Calling"
.PP
.Vb 1
\&    my $vhosts = readVhostsDump($httpd_bin, $httpd_conf_file, $logger);
.Ve
.ie n .IP "Parameter: $httpd_bin (string)" 4
.el .IP "Parameter: \f(CW$httpd_bin\fR (string)" 4
.IX Item "Parameter: $httpd_bin (string)"
Path to the httpd binary to execute (for example: \f(CW\*(C`/usr/sbin/httpd\*(C'\fR).
Specific options (such as \f(CW\*(C`\-D\*(C'\fR parameters) may be added to the string.
.ie n .IP "Parameter: $httpd_conf_file (string)" 4
.el .IP "Parameter: \f(CW$httpd_conf_file\fR (string)" 4
.IX Item "Parameter: $httpd_conf_file (string)"
Path to the main httpd configuration file (for example:
\&\f(CW\*(C`/etc/httpd/conf/httpd.conf\*(C'\fR).
.ie n .IP "Parameter: $logger (reference to \s-1OCS\s0 logger instance)" 4
.el .IP "Parameter: \f(CW$logger\fR (reference to \s-1OCS\s0 logger instance)" 4
.IX Item "Parameter: $logger (reference to OCS logger instance)"
To make use of \s-1OCS\s0 logging capabilities within the function.
.SS "\fBreadVhostConfFile()\fP"
.IX Subsection "readVhostConfFile()"
Enhance a virtualhost's information with elements found when parsing the
vhost's configuration file.
.PP
\fIReturn type\fR
.IX Subsection "Return type"
.PP
The function returns nothing.
.PP
It only operates on the (referenced) vhost hash it got in parameter.
.PP
\fIProcess\fR
.IX Subsection "Process"
.PP
The function must read the apache configuration file in which the vhost gets
defined (<VirtualHost> block).
.PP
The path to the particular configuration file and the line number of the vhost
declaration are known in the \f(CW\*(C`vhostfile\*(C'\fR and \f(CW\*(C`vhostline\*(C'\fR attributes, thanks
to the vhost dump.
.PP
The function's process, for the given vhost, is as follows:
.IP "1." 4
Open the configuration file at \f(CW\*(C`vhostfile\*(C'\fR
.IP "2." 4
Read line by line, waiting to be at correct line number (\f(CW\*(C`vhostline\*(C'\fR) to
start searching for information.
.IP "3." 4
Search for the following information in the <VirtualHost> and enhance the
given vhost hash with:
.RS 4
.IP "\(bu" 4
docroot (string)
.Sp
the value of the \f(CW\*(C`DocumentRoot\*(C'\fR directive
.IP "\(bu" 4
ssl (bool)
.Sp
we turn it to true if we find a \f(CW\*(C`SSLEngine on\*(C'\fR directive
.IP "\(bu" 4
sslcertpath (string)
.Sp
value of the \f(CW\*(C`SSLCertificateFile\*(C'\fR directive, if such a directive is present
.RE
.RS 4
.RE
.IP "4." 4
File reading stops when we find the \f(CW\*(C`</VirtualHost>\*(C'\fR closing block
(in case multiple vhosts are declared in the same configuration file).
.PP
\fICalling\fR
.IX Subsection "Calling"
.PP
.Vb 4
\&    foreach my $vhost (@$vhosts) # Generally
\&    {
\&        readVhostConfFile($vhost, $httpd_basedir);
\&    }
.Ve
.ie n .IP "Parameter: $vhost (reference to hash)" 4
.el .IP "Parameter: \f(CW$vhost\fR (reference to hash)" 4
.IX Item "Parameter: $vhost (reference to hash)"
The virtualhost hash to enhance.
.ie n .IP "Parameter: $httpd_basedir (string)" 4
.el .IP "Parameter: \f(CW$httpd_basedir\fR (string)" 4
.IX Item "Parameter: $httpd_basedir (string)"
The path to base directory of httpd, in case we encounter a relative path
in \f(CW\*(C`SSLCertificateFile\*(C'\fR and need to complete it.
.Sp
\&\fB\s-1IMPORTANT\s0\fR: the given path is expected to end with a slash '/', for example:
.Sp
.Vb 1
\&    "/etc/httpd/"
.Ve