pandorafms/pandora_server/INSTALL

Pandora Server install
======================

This small document try to guide you to a quick-and-irresponsable install. You must read the full install guide before try to install Pandora server and run it, but if you only want a quick step guide, this document is for you.

Requisites
==========

Database
~~~~~~~~
MySQL v4.x (or higher) database is used by Pandora Server as data storage. Only MySQL is supported by Pandora. InnoDB support is required, so you have to install MySQL4 or higher. If you want a MySQL cluster, use MySQL5. There are info about how to setup Pandora in a cluster enviroments.

Pandora Data Server
~~~~~~~~~~~~~~~~~~~
Requires SSH Servr and Perl v5.8 or higher and the next Perl Modules:

    XML::Simple, useful XML functions
    Digest::MD5, MD5 generation
    Time::Local, Date and Time basic manipulation
    DBI, DB interface with MySQL
    Date::Manip, needed to manipulate Date and Time formats of input, output and compare

You can find them at http://www.cpan.org or install using your default package instalation system. These packages are in the default distribution of Suse 9.1 and Debian 3.0 GNU/Linux. Also available for Solaris in CPAN repository. If you use Windows go to http://ppm.activestate.com. Or you can use the ppm tool to download the modules:
ppm install DBI
ppm install DBD-mysql
ppm install Datemanip

Next, you need to set the TZ (Time Zone) environment variable. In Windows: set TZ=WET (for example).

Pandora Network Server
~~~~~~~~~~~~~~~~~~~~~~
Requires SSH Server and Perl v5.8 or higher and the next Perl Modules:

    IO::Socket, manage and manipulation of TCP/UDP sockets
    Time::HiRes, needed for ICMP times
    Time::Local, Date and Time basic manipulation
    Net::Ping, to calculate latency times (it's required that the server runs as root user).
    Net::Ping::External, needed to "ping" to remote systems
    SNMP, for SNMP management
    Date::Manip, needed to manipulate Date and Time formats of input, output and compare

To use SNMP fuctions it's needed also to have installed the net-snmp package. It's worth to say that to run modules of GENERIC_ICMP_DATA type (calculate ICMP latency time) Pandora Network Server must run with root privileges.

Pandora SNMP Console
~~~~~~~~~~~~~~~~~~~~
It's needed to install the NET-SNMP package which is included in all GNU/Linux distributions. You have to use the snmptrapd binary and copy or link it to $HOME_PANDORA/util, where $HOME_PANDORA is the instalation directory of Pandroa Server. This usually is /opt/pandora_server.

This binary gets the SNMP traps, generating a log that is parsed by the Pandora Server.

Pandora Web Console
~~~~~~~~~~~~~~~~~~~
Requires a Web Server (Apache recommended) with PHP 4.3.x (PHP 5 works ok too), PHP4-MySQL and PHP4-session modules, PHP-GD v1.3 library and JpGraph (http://www.aditus.nu/jpgraph/) for graphic generation.

It's required to initialize session on request startup to include on /etc/php.ini (or similar, depends on OS) the lines:
session.bug_compat_42 = 1

For security, the transfer of data between Pandora Agents and Server it's recommended to use SSHv2 using SCP, so you need to install it on your systems. You can also use SSHv1, FTP, TFTP or TCP/Raw transfers, but this last procedure isn't included in the Pandora documentation.

Pandora Agents
~~~~~~~~~~~~~~
These are installed on every machine to be monitored. They depend on the Operating System. Clients for several OS are provided, but can be easily developed new ones.

Pandora Agents for Solaris and AIX

You need MD5 package to run Pandora Agent for Solaris and AIX, but it's possible to deactivate the check into the servers and agents, setting the checksum to 0 inside the agent's configuration file (pandora_agent.conf).
Installation

INSTALLATION
============

Download the packages Pandora Server for Pandora Data Server, Pandora Network Server and Pandora SNMP Console, Pandora Agents and Pandora Web Console for DataBase and Web Management System (Web Console).

Database
~~~~~~~~
You need a database with name "pandora". To create the structure of Pandora database in MySQL Server you have the SQL script pandoradb.sql inside Pandora WebConsole distribution. It creates tables and indexes needed to insert information into Pandora database.

You MUST populate database with pandoradb_data.sql, an SQL script included in the same distribution directory, that inserts data needed to run Web Console and default user (login: admin, password: pandora) to access Pandora Web Console.

To install the files, first create a database called "pandora", and set an user to be able to access this database:
mysql> create database pandora;

Later, execute the next commands using a user with enough privileges to create tables and indexes into Pandora Database into your MySQL Server:
cat pandoradb.sql | mysql -D pandora -u root -p
cat pandoradb_data.sql | mysql -D pandora -u root -p

Note: if your system is Windows, use the command type instead of cat.

You can also use the source command, if you are connected to MySQL, from the MySQL prompt:
mysql> use pandora;
mysql> source <path_to_pandoradb.sql>
mysql> source <path_to_pandoradb_data.sql>

This example is valid using root user in MySQL. Remember if you're in windows and you use MySQL v4.1, use the dobule slash ("//") with the path to the files, not the backslash ("\").

If you have any problem with this commands, from the OS command line you can run this commands:
cat pandoradb.sql | mysql -D pandora -u root -p
cat pandoradb_data.sql | mysql -D pandora -u root -p

Note: if you're using Windows, you must use type command instead of the cat one.

Now we will create an user "pandora" and will be given to it privileges from the localhost. Please look at MySQL install & management guide (http://dev.mysql.com/doc) to obtain information about how to create a MySQL user and give him/her privileges to read/write in Pandora database. The sentence will be something like:
mysql> grant all on pandora.* to 'pandora'@'localhost' identified by 'pandora';

Keep in mind that users need access from Pandora WEB Console and from Pandora Server, if your deployment has many subcomponents in different physical machines, you need to setup a MySQL user with privileges to access from different locations.

If you get the error "Warning: mysql_connect() [function.mysql-connect]: client does not support authentication protocol requested by server; consider upgrading" when authenticating Web Console, you have to change the way the password is stored into the database (see FAQ):
mysql> set password for 'pandora'@'localhost' = old_password('pandora');

Please note this user will be used by several Pandora subcomponents(Pandora Server, Pandora Web Console) to access database.

Dont forget to flush privileges before exiting mysql console:

flush privileges;

Pandora Server
~~~~~~~~~~~~~~

Create the /opt/pandora directory and "gunzip" and "untar" here the pandora_server_1.2beta1.tar.gz file.

Create an user pandora in OS. Usually you do that (in GNU/Linux) with commands:
useraddd pandora -d /home/pandora
mkdir /home/pandora
chown pandora /home/pandora

This user will be used by the SSH transfers to the server, so this user will need a strong password.

In the file /home/pandora/.ssh/authorized_keys we will add the public key of each agent which send data to Pandora Server. These keys must be SSH v2, OpenSSH DiffieHellman (DF) or RSA. To convert between keys you can use the ssh-keygen tool.

Pandora Server will check and parse XML files sent by Pandora Agents and will insert the data into the Database.

Check launch scripts (pandora_network, pandora_server, pandora_snmp) and check for pathnames in the first two variables in script.

Edit configuration file of Pandora Server, usually /opt/pandora/conf/pandora_server.conf and take a look at the lines:
dbuser pandora
dbpass pandora
dbhost localhost

Please change them to your own data. For security reasons isn't recommended use the default values.

Before running Pandora Server, you need to have Pandora DataBase running. In order to setup database configuration you'll need to edit pandora_server.pl perl script and change this parameters (all are together, in the first lines of code):
my $dirname = "/opt/pandora/data_in";
my $dbuser = "pandora";
my $dbpass = "pandora";
my $dbhost = "pandora";
my $log_file = "/opt/pandora/pandora.log";

If you run Pandora Server in Windows, you need to use the backslash twice in $dirname, that is: "\\", for example: my $dirname="C:\\pandora\\pandora_server\\data_in";, not needed in $log_file.

These are default values, and all must be existing directory and filename and valid username, password and hostname.

Remember: you need to create the directory /opt/pandora/data_in where Pandora Server will read and write data, sent by remote agents using ssh/scp. This directory must be owned or with permissions to write for user "pandora". If you dont have a "pandora" user yet, create it.

You can run Pandora Server with an user without privilegues, you can use the user "pandora", it only needs to run /usr/bin/perl and access to /opt/pandora and /opt/pandora/data_in directories.

This is true with all the components but with Pandora SNMP Console needs root user to open UDP port 161 (this can be solved setting SUID0 to the snmptrapd binary) and running the rest of the Server using an user without privileges.

Also Pandora Network Server can be run using an user without privileges, but the GENERIC_ICMP_DATA type won't work, as root privileges are required to get ICMP latency times.

Check the MySQL connection with the user and password before running the server

Pandora Server distribution tarball includes a Posix/System V start/stop script for "daemonize" Pandora Server. It is possible that you need to customize, but its runs smoothly on GNU/Linux (debian, Suse) and Solaris 8 systems. It has start|stop|restart parameters to include it in your default init level directory and it creates a logfile defined in $log_file variable (by default is /opt/pandora/pandora.log):
/etc/init.d/pandora_server start

Pandora Web Console
~~~~~~~~~~~~~~~~~~~

The only file you need to modify is include/config.php, where the following variables are included in .php code:
$dbname="pandora";   // name of database for pandora (default: pandora)
$dbuser="pandora";   // mysql user to access pandora database
$dbpassword="pandora";   // Password for mysql user to access pandora database
$dbhost="pandora";   // Hostname or IP where mySQL server runs

If database is defined and was correctly installed, you can now access:
http://<hostname_pandora_webconsole>:<port>/<installation_directory>/index.php

The first time you log there is a default admin user "admin" and password "pandora". It's worth to say that you MUST CHANGE CREDENTIALS BEFORE LOGIN FIRST TIME, change it or create another account, disabling this one.

Pandora Agents for Unix
~~~~~~~~~~~~~~~~~~~~~~~
There are two configuration files:
pandora_agent.conf
pandora_user.conf (only in Unix)

Pandora Agents use pandora_agent.conf to load initial data and load module data. Modules are atomic source of information. Please refer to Pandora Agents Configuration v1.1 file or Agents configuration - Quick Guide for more information.

pandora_user.conf is low level configuration. It will be executed in each iteration of pandora_agent.sh script. Please read it and see how it works.

There are one or more daemon scripts to load pandora_agent.sh at boot time. It depends on what type of Unix are you running. One of them is pandora_agent_daemon_generic which is a "supposed" multiplattform sh script to start/stop pandora_agent script. Rename it by /etc/init.d/pandora_agent and test it before including it your init level script directory. 

SNMP Troubleshooting
====================

You need to install libsnmp-perl package (debian name) to use SNMP Network Agents.

On PERL code for Pandora Server:

If problems occur there are number areas to look at to narrow down the possibilities.
The first step should be to test the UCD SNMP installation independently from the Perl5 SNMP interface.
Try running the apps from the UCD SNMP distribution, this means: try to exec manually snmpget in the Pandora Network Server. Try for example:

	snmpget -v 1 -c public 192.168.5.1 SNMPv2-MIB::sysName.0
	bash: snmpget: command not found

Houston, you've a problem with snmpget :-). Fix it before launch pandora network server.

Make sure your agent (snmpd) is running and properly configured with read-write access for the community you are using.
Ensure that your MIBs are installed and enviroment variables are set appropriately (see man mib_api)
Be sure to remove old ucd-snmp installations and ensure headers and libraries from old CMU installations are not being used by mistake.

If the problem occurs during compilation/linking check that the snmp library being linked is actually the UCD SNMP library (there have been name conflicts with existing snmp libs).
Also check that the header files are correct and up to date.
Sometimes compiling the UCD SNMP library with 'position-independent-code' enabled is required (HPUX specifically).

Network Agent: ICMP Latency
===========================

This module only works if Network Server component its executed under root privileges due limitations of Net::Ping perl library. You can run Network Server using an user without admin privileges but you cannot use ICMP Data / Latency module, but ICMP Proc it's usable using any user because other perl library it's used in this case.

Network Agent: UDP
==================

This module only works if Network Server component its executed under root privileges due limitations of Net::Ping perl library.

Network Agent chat
==================

Its possible to send data to remote TCP ports in Network Agents, you can use "^M" macro to replace \r\n (Return Carriage and Line Feed), for example, to use a simple http request: "GET / HTTP/1.0^M^M".

remote_tcp_proc moduletype allows you to "expect" a string (rcv data). If this string is matched in any place of the answer, value will be 1 (OK), if not, 0 (BAD).

Network SNMP Agent
==================

SNMP OID MUST be provided in dotted format, p.e:

IF-MIB::ifInOctets.6 -> .1.3.6.1.2.1.2.2.1.16.6

SNMPv2-MIB::sysUpTime -> .1.3.6.1.2.1.1.3