Chapter 3. WebTool Module API Reference

This section documents the interface for each existing WebTool module. Note that each "WebTool module" in /usr/webtool/modules has it's own associated Perl module. This allows any given module (ie, apache) to import another module (ie, services) and use it's functionality (ie, starting and stopping the httpd service).

3.1. apache

3.1.1. NAME

apache - Guardian Digital WebTool module interface to the Apache webserver.

3.1.2. SYNOPSIS

use apache;
my $apache   = new apache;

3.1.3. DESCRIPTION

This Guardian Digital WebTool module provides an interface to manipulating the Apache webserver. This module allows you to manage virtual hosts, databases for virtual hosts, and SSL certificates for SSL virual hosts.

3.1.4. METHODS

is_installed()

This function is used to check that apache web server is installed or not. It returns ture(1) or false(0).

Example Usage:

if ($apache->is_installed()).....

mysql_installed()

This function is used to check that MySQL server is installed or not. It returns ture(1) or false(0).

Example Usage:

if ($apache->mysql_installed()) ...

get_vhosts()

This function reads apache configuration file and returns information about all NameVirtualhosts and Virtualhosts(address, port, alias,redirect etc) as key-value pair in hash reference.

Example Usage:

my $vhosts  = $apache->get_vhosts();

create_vhost($$)

This function basically creates a virtual host(makes virtual host entry to httpd.conf). It receives two hash references, one contains information like hostname, port, webmaster, group etc information. Another hash reference argument contains existing virtual hosts information(from get_vhosts). After writing to httpd.conf, depending on the DB creation option it creates DB with provided hostname, db user and db password.

Example Usage:

my $vhosts  = $apache->get_vhosts();
$apache->create_vhost($newopts, $vhosts);

delete_vhost($)

This function used to delete a virtual host entry from httpd.conf. Virtual hostname is passed as argument. Besides deleting virtual host from httpd.conf, it delets whole directory tree related to that virtual host, it also drops related database, delete users, database permissions, disconnect to MySQL.

Example Usage:

$apache->delete_vhost($vhost);

update_vhost($)

This function used to update a virtual host entry in httpd.conf. It receives hash reference containing values of different virtual host parameters. It returns a string containing hostname-port format.

Example Usage:

$opt = { 'port' => 8000 };
my $newvhostkey = $apache->update_vhost($opt);

create_db($$$)

This function is used to create a MySQL Database with certain DB username and password. This function takes DB name, DB Username, DB password as arguments. It creates database, insert username and password in that as given with setting proper permissions.

Example Usage:

$apache->create_db($servername, $db_uname, $db_pass);

passchange_db($$$)

This function is used to change password of given user for a given database. It receives DB name, username and new password as arguments.

Example Usage:

$apache->passchange_db($servername, $db_uname, $db_pass);

set_docopts($)

This function receives document options as hash reference, depending on the options (e.g. includes, incnoexec etc) it generates a string and after checking some operations it writes them to httpd.conf.

Example Usage:

$opts = {
       'includes'  => 'yes',
       'incnoexec' => 'no',
       'indexes'   => 'no'
} 
$apache->set_docopts($opts);

remove_alias($)

This function is used to remove an alias from httpd.conf. Hash reference containing alias to be deleted is passed as argument.

Example Usage:

$opts = {
       'vhost'       => $vhost,
       'removealias' => $alias,
}
$apache->remove_alias($opts);

create_alias($)

This function is used to add an alias to httpd.conf. hash reference containing values of alias_to and alias_from is passed as arguments.

Example Usage:

$opts = {
       'vhost'       => $vhost,
       'alias_from'  => '/alias/from',
       'alias_to'    => '/alias'
}
$apache->create_alias($opts);

remove_redirect($)

This function is used to remove a redirect from httpd.conf. Hash reference containing value of redirect( to be removed) is passed as argument.

Example Usage:

$opts = {
       'vhost'          => $vhost,
       'removeredirect' => $redirect,
}
$apache->remove_redirect($opts);

create_redirect($)

This function is used to add a redirect to httpd.conf. Hash reference containing value of redirect_to and redirect_from is passed as arguments.

Example Usage:

$opts = {
       'vhost'          => $vhost,
       'redirect_from'  => '/redirect/from',
       'redirect_to'    => '/redirect/to'
}
$apache->create_redirect($opts);

save_errordocs($)

This function is used to save changed error documents for a given host into the httpd.conf. It receives hash reference containing various options containing virtual hostname and errordocuments with their values.

Example Usage:

$opts = {
      'vhost' => $vhost,
      'errordoc301' => /doc/301,
      'errordoc302' => /doc/302,
       ................  
}
$apache->save_errordocs($opts);

find_vhost_db($)

This function is used to get DB username and DB name as hash reference for a virtual host. Virtual host name(server name) is passed as argument to the function.

Example Usage:

$dbref = $apache->find_vhost_db($servername);
$DBuser = $dbref->{dbuser};
$DBname = $dbref->{dbname};

read_cert($)

This function is used to read a certificate from a given host. Hash reference containing detail of a given virtual host is passed as an argument and hash reference containing values of all certificate parameters(e.g. fingerprint, startdate, enddate, country, state, city etc.) is return as result.

Example Usage:

my $vhref     = $apache->get_vhosts();
my $vhost     = $vhref->{$in{vhost}};
my $cert      = $apache->read_cert($vhost);

create_cert($$)

This function basically creates a certificate for a given virtual host. It receives two arguments, hash reference containing virtual host details and a hash reference containing certificate parameter values(name, country, state, city, organization, department,email). Using these information it creates certificate and also modifies httpd.conf.

Example Usage:

my $vhref     = $apache->get_vhosts();
my $vhost     = $vhref->{$in{vhost}};
$apache->create_cert($vhost, $opts);

install_cert($$)

This function is used to install certificate for a given virtual host. It receives two arguments, hash reference containing virtual host details and a hash reference containing values like certificate,key. Certificate is created using certificate file and key file. SSL option is taken into consideration.

Example Usage:

my $vhref     = $apache->get_vhosts();
my $vhost     = $vhref->{$in{vhost}};
$apache->install_cert($vhost, $opt);

generate_csr($$)

This function is used to generate Certificate Signing Request. It receives two arguments, hash reference containing virtual host details and a hash reference containing certificate parameter values(name, country, state, city, organization, department,email).

Example Usage:

my $vhref     = $apache->get_vhosts();
my $vhost     = $vhref->{$in{vhost}};
my $tempcsr   = $apache->generate_csr($vhost, $opt);

validate_conf()

This function is used to validate/verify httpd.conf using /usr/sbin/httpd. It returns appropriate message on execution(Failed/Pass).

Example Usage:

my $validate = $apache->validate_conf();

restart()

This function is used to restart web server(httpd).

Example Usage:

$apache->restart();

3.1.5. AUTHORS

Pax Dickinson <pax@guardiandigital.com>

3.1.6. COPYRIGHT AND LICENSE

Copyright Guardian Digital, Inc., All Rights Reserved