view release on metacpan or  search on metacpan

VBTK.pm  view on Meta::CPAN

Note that you don't have to use the 'sync' functionality.  You could just use
rsync or something similar to copy the config files around, or you could just
edit the config files independently on each host.  I prefer to have one master
and sync out from there, because it makes it easier to keep track of all the
config differences.

=over 4

=item Initial Setup

Follow the 'PER-SERVER CONFIGURATION' instructions below for just the VBServer
host.  When you run the installer, answer (M)aster when prompted for which
type of processes you'll be running on this host.

=item Edit 'vbc' Configuration File

Look in the $VBHOME/examples directory and you'll find example config files.  These
are actually perl programs, so it will help if you know some perl.  The 'vbc'
config file will have already been copied over to the $VBHOME/conf directory.
Open up the 'vbc' config file.  This is the controller file which defines which
instances will be running on each host.  You should already see the master VBServer
host listed there.  Add in all your other hosts, and specify any slave servers.

=item Edit 'vbserver' Configuration File

Copy the 'vbserver' config file from the 'examples' directory into the 'conf'
directory and edit it.  Just read the comments.

=item Start the 'vbserver' process.

Run 'conf/vbc start vbserver' and then check the log file 'logs/vbserver...'
for errors.  Now try to connect with a web browser to 
'http://<hostname>:4712'.

=back

=head2 PER-SERVER INITIAL CONFIGURATION

Now that you've drawn your monitoring map, let's get the various servers setup.
The software install is identical regardless of what you're going to run on the
host.  If you have hosts which won't be running any local tests, then you 
obviously don't need to install anything there.

=over 4

=item Create a user and group 'vbtk'.

If you're running this on a unix machine, you don't want to run it as superuser,
so create a user 'vb' and group 'vb' to run all the processes under.

    useradd vbtk 
    groupadd vbtk

=item Create a home directory.

Create a home directory for the VBTK software.  I suggest '/usr/vbtk', which is
the default.  Change this directory to be owned by the 'vbtk' user and to be the
'vbtk' user's home directory.

    mkdir /usr/vbtk; chown vb:vb /usr/vbtk

If you're going to use a directory other than '/usr/vbtk', then make sure you 
set the environment variable $VBHOME to the new location.  Make sure this is
always set before you run any scripts.

=item Run the installer.

This will check the VBHOME directory and prompt you for either the location of
the VBTK install directory or a VBServerURI from which it can sync config files.
It also does some setup in the $VBHOME directory.

    perl -MVBTK -e install

=back

=head2 ON-GOING CONFIGURATION

Once you have the initial VBServer running, read through the config files in
the examples directory and copy ones you want to use over to the conf directory.
Remember you have to list these config files in the 'vbc' config file in order
to start them with the 'vbc' command.  

You can also look through the various modules in the 
L<Data Gathering Modules|VBTK/Data-Gathering Modules> section of this document
for help on creating new config files.

=head1 SECURITY

Don't expose the web interface to the public internet!  I make no claims about 
how secure it is.  There may be vulnerabilities which I don't know about.

=head1 FAQ

=over 4

=item How do I delete an object?

Before you can delete an object, make sure that there isn't a client process
which is still sending sending a status for that object.  Otherwise it will 
just get recreated with the next status submission.  If you're not sure which
client process is setting the status, look under the 'Info' tab for that 
object for the 'Script Name' and 'Running From' values.  This shows you 
which script is setting the status.  Once you think you've fixed the script, 
check the object history to see if it's still being updated.  If not, go to 
the 'vbobj' directory, on the Master or Slave server to which this object is
reported, and delete the sub-directory which matches the object name.  After
about a minute, the object will disappear from the web interface.

=item There are error messages in the VBServer log about the 'rrdupdate' 
command failing.

If you've changed the number of entries being passed in the 
L<RrdColumns|VBTK::Parser/item_RrdColumns> entry, or if you've changed the 
L<CF|VBTK::Parser/CF> specification, then you probably need to rebuild
the corresponding RRD database.  Look in the VBHOME/vbobj directory for a 
directory named the same as the object and delete the RRD.db file.  Then 
restart the client process which monitors the object and the RRD.db file 
will be regenerated.

=back