tyler.durden/pandorafms
1
0
Fork 0
mirror of https://github.com/pandorafms/pandorafms.git synced 2025-07-25 23:05:30 +02:00
Code Issues Packages Projects Releases Wiki Activity

2006-09-20 Sancho Lerena <slerena@artica.es>

Browse Source 
* en/pandora.xml: Changes in copyright notice and other minor stuff.

	* en/pandora_introduction.xml: Major cut/paste info from older
	docs. Formatting and some graphics inline. Initial first version
	of introduction chapter for main/install pandora doc. Please
	review it MANY times before publish it.

	* en/pandora_install.xml: More formatting and text added. Second
	version, with new stuff from last revision. Please review it MANY
	times before publish it.

	* en/images/*.jpg: New files added for introduction chapter.
	



git-svn-id: https://svn.code.sf.net/p/pandora/code/trunk@180 c3f86ba8-e40f-0410-aaad-9ba5e7f4b01f
This commit is contained in:
slerena 2006-09-20 15:40:56 +00:00
parent f3ef889d83
commit 0c5061fa4c
8 changed files with 818 additions and 318 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

BIN
pandora_doc/en/images/mini_pandora_box.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 2.1 KiB

BIN
pandora_doc/en/images/pandora_arch1.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 15 KiB

BIN
pandora_doc/en/images/pandora_arch2.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 76 KiB

BIN
pandora_doc/en/images/pandora_login.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 29 KiB

BIN
pandora_doc/en/images/pandora_logo.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 15 KiB

12
pandora_doc/en/pandora.xml
View File

@ -3,6 +3,7 @@
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
<!ENTITY pandora_version "v1.2">
<!ENTITY pandora "<emphasis>Pandora</emphasis>">
<!ENTITY include_pandora_introduction SYSTEM "pandora_introduction.xml">
<!ENTITY include_pandora_install SYSTEM "pandora_install.xml">
<!ENTITY include_fdl SYSTEM "fdl.xml">
<!ENTITY include_gpl SYSTEM "gpl.xml">
@ -11,11 +12,12 @@
<book lang="en">
<bookinfo>
<title>&pandora; &pandora_version;</title>
<graphic fileref="./img/pandora_logo.jpg" valign="bottom" align="center"/>
<graphic fileref="./images/pandora_logo.jpg" valign="bottom" align="center"/>
<copyright>
<year>2006</year>
<holder>
Ártica Soluciones Tecnológicas S.L, Sancho Lerena, Esteban Sánchez y otros.
Ártica Soluciones Tecnológicas S.L, Sancho Lerena, Esteban
Sánchez y otros.
</holder>
</copyright>
<date>11/09/2006</date>
@ -42,14 +44,16 @@
<date>11 Sept 2006</date>
<revremark>Submitted.</revremark>
</revision>
<revision>
<revnumber>0.1</revnumber>
<date>11 Sept 2006</date>
<revnumber>1.1</revnumber>
<date>20 Sept 2006</date>
<revremark>First draft for review.</revremark>
</revision>
</revhistory>
</bookinfo>
&include_pandora_introduction;
&include_pandora_install;
&include_fdl;
&include_gpl;

500
pandora_doc/en/pandora_install.xml
View File

@ -14,7 +14,14 @@
</para>
</sect1>
<sect1>
<title>Pandora Server install and setup</title>
<title>Pandora Servers</title>
<para>
Pandora 1.2 has three kind of servers: Data server, Network
Server and SNMP Server/Trap console. All of them could be
installed in the same machine or in different machines, also,
you could setup many of them in a High Availability enviroment
or using it to manage highs loads of data.
</para>
<sect2><title>Pandora Data Server</title>
<para>
To build <emphasis>Pandora Data Server</emphasis> you need to
@ -39,6 +46,8 @@
</listitem>
</itemizedlist>
</blockquote>
</para>
<para>
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
@ -247,8 +256,8 @@
</sect1>
<sect1>
<title>Installing Pandora Console and database</title>
<sect2><title>Pandora database</title>
<title>Pandora Console and Pandora database</title>
<sect2><title>Pandora database install</title>
<para>
Please look at MySQL install and management guide
(http://dev.mysql.com/doc) to obtain information about how to
@ -266,7 +275,8 @@
you need to reconfigure in server too.
</para>
<para>
To create the structure of Pandora database in MySQL Server you have the SQL script "pandoradb.sql".
To create the structure of Pandora database in MySQL Server you
have the SQL script "pandoradb.sql".
</para>
<para>
It creates tables and indexes needed to insert information into
@ -316,12 +326,13 @@
Now we will create an user "pandora" and will be given to it
privileges from the localhost:
<programlisting>
mysql> grant all on pandora.* to 'pandora'@'localhost' identified by 'pandora';
mysql> grant all on pandora.* to 'pandora'@'localhost'
identified by 'pandora';
</programlisting>
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.
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.
</para>
<para>
If you get the error "Warning: mysql_connect()
@ -340,8 +351,9 @@
<sect2>
<title>Pandora Console.</title>
<para>Prior to install Pandora console, you need the following dependencies and software needed:
<title>Pandora console install.</title>
<para>Prior to install Pandora console, you need the following
dependencies and software needed:
<blockquote>
<itemizedlist mark='bullet'>
<listitem>
@ -379,16 +391,16 @@
variables are included in .php code:
</para>
<programlisting>
$dbname="pandora"; // name of database for pandora (default: pandora)
$dbname="pandora"; // name of database for pandora)
$dbuser="pandora"; // mysql user to access db
$dbpassword="pandora"; // Password for mysql user to access db
$dbhost="pandora"; // Hostname or IP where mySQL server runs
$dbpassword="pandora"; // Password for mysql user
$dbhost="pandora"; // Hostname or IP of mySQL server
</programlisting>
<para>
If database is defined and was correctly installed, you can
now access:
<programlisting>
http://hostname:port/installation_directory/index.php
http://hoste:port/installdir/index.php
</programlisting>
The first time you log there is a default admin user "admin"
and password "pandora". It's worth to say that <emphasis>YOU
@ -397,7 +409,7 @@
privileges, and disable this one.
</para>
<para>
<graphic fileref="img/pandora_login.jpg" scale="70" align="center"/>
<graphic fileref="images/pandora_login.jpg" scale="70" align="center"/>
If you cannot see a screen like this, it's possible that you
have problems with PHP instalation. When you installed the
Web, please check that PHP engine its running. Fist try to
@ -462,13 +474,15 @@
</sect3>
</sect2>
</sect1>
<sect1><title>Installing agents</title>
<sect1><title>Pandora Agents</title>
<sect2><title>Introduction</title>
<para>
Pandora<EFBFBD>s agents collect all the Pandora system's data. They are
executed in each local system, although they can also collect
remote information by installing monitoring systems for the agent
in several different machines - called satellite agents.
&pandora; agents collect all system's data. They are executed in
each local system, although they can also collect remote
information by installing monitoring systems for the agent in
several different machines - called satellite agents.
</para>
<para>
They are developed to work under a given platform, making use of
@ -491,7 +505,6 @@
This document describes the installation of agents in machines
running over Windows and Unix operating systems.
</para>
<graphic fileref="images/pandora_agentbox.jpg" valign="bottom" align="right"/>
</sect2>
<sect2><title>Generic role of the agents</title>
@ -503,8 +516,8 @@
<para>
A script (or binary application in Windows) that collects and
sends the data to the server. For UNIX machines the script is
called pandora_agent.sh and is executed directly from the Pandora<EFBFBD>
s agent folder.
called pandora_agent.sh and is executed directly from the Pandora
agent folder.
</para>
<para>
One or several configuration files where the values to be
@ -513,7 +526,7 @@
</para>
<para>
This simple structure makes it easy the customisation of an
agent. There is no need to <EFBFBD>reprogram<EFBFBD> the agent to modify the
agent. There is no need to "reprogram" the agent to modify the
way it works, as the configuration file holds most of the
parameters needed to do so.
</para>
@ -535,100 +548,113 @@
<para>
The data collection in the host system is the gathering of
independent data units, which are defined in the
pandora_agent.conf file. The pandora_agent.conf file is divided in
two parts:
</para>
<filename>pandora_agent.conf</filename> file. The
pandora_agent.conf file is divided in two parts:
<itemizedlist mark='bullet'>
<listitem>
<para>
General parameters.
<emphasis>General parameters</emphasis>: Configure general
options about server location, agent name, interval, and
other general options.
</para>
</listitem>
<listitem>
<para>
Module definitions.
<emphasis>Module definitions</emphasis>: Configure and
define the method of extraction for each piece of
information that will be extracted from local host and sent
to Pandora Server.
</para>
</listitem>
</itemizedlist>
</para>
<sect3><title>General parameters</title>
<para>
The general parameters of the agent configuration are defined in this section. Some of these parameters are common for all systems and others specific for Windows or UNIX. The general parameters are:
The general parameters of the agent configuration are defined in
this section. Some of these parameters are common for all systems
and others specific for Windows or UNIX. The general parameters
are:
</para>
<itemizedlist mark='bullet'>
<listitem>
<para>
server_path: (Shared parameter) The server path is the
full path of the folder where the server stores the data
sent by the agent. It is usually /opt/pandora/data_in.
<emphasis>server_path</emphasis>: (Shared parameter) The
server path is the full path of the folder where the
server stores the data sent by the agent. It is usually
<filename>/opt/pandora/data_in</filename>.
</para>
</listitem>
<listitem>
<para>
server_ip: (Parameter shared by Windows and Unix agents)
The server IP is the IP address or the host name of the
Pandora server, where the data will be stored. The host
must be reachable and must be listening to port 22
(SSH).
<emphasis>server_ip</emphasis>: (Parameter shared by
Windows and Unix agents) The server IP is the IP address
or the host name of the Pandora server, where the data
will be stored. The host must be reachable and must be
listening to port 22 (SSH).
</para>
</listitem>
<listitem>
<para>
temporal: (Shared parameter) This is the full path of
the folder where the agent stores the data locally,
before it is sent to the server. It must be said that
the data packages are deleted once the agent tries to
contact the Pandora<EFBFBD>s server, no matter if the
<emphasis>temporal</emphasis>: (Shared parameter) This
is the full path of the folder where the agent stores
the data locally, before it is sent to the server. It
must be said that the data packages are deleted once the
agent tries to contact Pandora server, no matter if the
communication was successful or not. This is done to
avoid over flooding hard drive of the host system where
the agent runs. The location of the local folder varies
with the architecture of the host system. In Unix
systems this is usually /opt/pandora/data_out, and in
Windows systems C:\pandora\data_out.
systems this is usually
<filename>/opt/pandora/data_out</filename>, and in
Windows systems
<filename>C:\pandora\data_out</filename>.
</para>
</listitem>
<listitem>
<para>
interval: (Shared parameter) This is the time interval
in seconds in which the agent will collect data from the
host system and send the data packages to the
server. The recommended value ranges from 300 (5
minutes) to 600 (10 minutes). This number could be
larger, although it is important to consider the impact
of a larger number on the database.
<emphasis>interval</emphasis>: (Shared parameter) This
is the time interval in seconds in which the agent will
collect data from the host system and send the data
packages to the server. The recommended value ranges
from 300 (5 minutes) to 600 (10 minutes). This number
could be larger, although it is important to consider
the impact of a larger number on the database.
</para>
</listitem>
<listitem>
<para>
debug: (Unix only) This parameter is used to test
the connection between agent and server and the correct
working condition of the agent. The process consists of
a loop, data collection and data transfer. It doesn<73>t
delete any data when the process is finished. The
activity is written in a log file, stored in the Pandora
root folder. The file is named pandora_agent.log. This
log file can be used to test the system and to
investigate potential issues.
<emphasis>debug</emphasis>: (Unix only) This parameter
is used to test the connection between agent and server
and the correct working condition of the agent. The
process consists of a loop, data collection and data
transfer. It does not delete any data when the process
is finished. The activity is written in a log file,
stored in the Pandora root folder. The file is named
pandora_agent.log. This log file can be used to test the
system and to investigate potential issues.
</para>
</listitem>
<listitem>
<para>
agent_name: (Shared parameter) This is an
alternative host name. This parameter is optional as if
it is not declared the name is obtained directly from
the system.
<emphasis>agent_name</emphasis>: (Shared parameter) This
is an alternative host name. This parameter is optional
as if it is not declared the name is obtained directly
from the system.
</para>
</listitem>
<listitem>
<para>
pandora_path: (Unix exclusive parameter) This is then
path of the folder where the files of the Pandora agent
are stored. This is usually /opt/pandora.
<emphasis>pandora_path</emphasis>: (Unix exclusive
parameter) This is then path of the folder where the
files of the Pandora agent are stored. This is usually
<filename>/opt/pandora</filename> or
<filename>/opt/pandora_agent</filename>.
</para>
</listitem>
<listitem>
<para>
checksum: (Shared parameter). This parameter
<emphasis>checksum</emphasis>: (Shared parameter). This parameter
can take two values. If the value is 1, the checksums
are performed through MD5. If the value is 0, the
checksum is not performed at all. This may be useful for
@ -641,7 +667,7 @@
</itemizedlist>
<para>
An example of the general parameters from a Unix configuration would be.
<programlisting>
<screen>
server_ip Pandora_Server
server_path /opt/pandora/data_in
pandora_path /opt/pandora
@ -650,7 +676,7 @@
agent_name satellite_agent
debug 1
checksum 1
</programlisting>
</screen>
</para>
</sect3>
<sect3><title>Module definition</title>
@ -659,17 +685,28 @@
in each module, using the exact syntax. As many values as
necessary can be set to be collected, adding at the end of the
general parameters as many modules as the number of values to
collect. Each module is made of several directives:
collect. Each module is made of several directives. Following is a
descriptive relation of all module marks available for Unix agents
(almost all of them are applicable to Windows Agent too).
</para>
<sect4><title>module_begin</title>
<para>
Beginning of the module: <filename>module_begin</filename>
Defines the beginning of the module.
</para>
</sect4>
<sect4><title>module_name name</title>
<para>
Name of the module: <filename>module_name _name_</filename>
Name of the module. This is the id for this module, choose a
name without blank spaces and not very long. There is no
practical limitation (max of 250 chars) but will be more easy to
manage if you use short names. This name CANNOT be duplicated
with a similar name in the same agent. This name could be
duplicated with other modules in other agents.
</para>
</sect4>
<sect4><title>module_type type</title>
<para>
Data type: <filename>module_type _type_</filename>. Data type the
module will handle. There are four data types for agents:
Data type the module will handle. There are four data types for agents:
<itemizedlist mark='bullet'>
<listitem>
<para>
@ -700,79 +737,106 @@
</listitem>
</itemizedlist>
</para>
</sect4>
<sect4><title>module_exec command</title>
<para>
<emphasis>Command to execute</emphasis>: Several different
system-dependant directives are used to define the command that
will be executed to obtained a specific value.
This is the generic "<emphasis>command to execute</emphasis>"
directive. Both, for Unix and Windows agents there is only one
directive to obtain data in a generic way, executing a single
command (you could use pipes for redirecting execution to anoter
command). This directive executes a command and stores the
returned value. This method is also available on Windows
agents. This is the "general purpose method" for both kind of
agents.
</para>
<para>
Both, for Unix and Windows agentsthere is only one directive to
obtain data in a generic way, executing a single command (you
could use pipes for redirecting execution to anoter command):
For a Windows agent there are more directives to obtain data, who
are described following this lines.
</para>
</sect4>
<sect4><title>module_service service (Win32 Only)</title>
<para>
<filename>module_exec _command_</filename>: Executes a command and
stores the returned value. This method is also available on
Windows agents. This is the "general purpose method" for both kind
of agents.
Checks if a given service name is running in this host. Remember
to use " " characters if service name contains blank spaces.
</para>
</sect4>
<sect4><title>module_proc process (Win32 Only)</title>
<para>
For a Windows agent there are more directives to obtain to data:
Checks if a given processname is running in this host. Remember
to use " " characters if process name contains blank spaces.
</para>
</sect4>
<sect4><title>module_freedisk drive_letter: (Win32 Only)</title>
<para>
<filename>module_service _service_</filename> : Checks if a given
service name is running in this host. Remember to use " "
characters if service name contains blank spaces.
Checks free disk on drive letter (do not forget ":" after drive
letter.
</para>
</sect4>
<sect4><title>module_cpuusage cpu id (Win32 Only)</title>
<para>
<filename>module_proc _proc_</filename>: Checks if a given
processname is running in this host. Remember to use " "
characters if process name contains blank spaces.
Returns CPU usage on CPU number cpu. If you only have one cpu,
use 0 as value.
</para>
</sect4>
<sect4><title>module_freememory (Win32 Only)</title>
<para>
<filename>module_freedisk _drive_letter_:_</filename>: Checks free
disk on drive letter (do not forget ":" after drive letter.
Return free memory in the whole system.
</para>
</sect4>
<sect4><title>module_min value </title>
<para>
<filename>module_cpuusage _cpu_</filename>: Returns CPU usage on
CPU number _cpu_. If you only have one cpu, use 0 as value.
</para>
<para>
<filename>module_freememory</filename>: Return free memory usage.
</para>
<para>
Minimum accepted value: <filename>module_min _value_</filename>:
This is the minimum valid value for the data generated in this
module. If the module has not yet been defined in the web console
this value will be taken from this directive. This directive is
not compulsory. This value does not override the value defined in
the agent if the module does not exist in the management
console. It is created automatically when working on learning
mode.
module. If the module has not yet been defined in the web
console this value will be taken from this directive. This
directive is not compulsory. This value does not override the
value defined in the agent if the module does not exist in the
management console. It is created automatically when working on
learning mode.
</para>
</sect4>
<sect4><title>module_max value </title>
<para>
Maximum accepted value: <filename>module_max _value_</filename>:
It is the maximum valid value for the data generated in this
module. If the module hasn<73>t been defined in the web console this
value will be taken from this directive. This directive is not
compulsory and is not supported by the Windows agent. This value
does not override the value defined in the agent if the module
doesn<EFBFBD>t exist in the management console. This is created
module. If the module has not been defined in the web console
this value will be taken from this directive. This directive is
not compulsory and is not supported by the Windows agent. This
value does not override the value defined in the agent if the
module does not exist in the management console. This is created
automatically when working on learning mode.
</para>
</sect4>
<sect4><title>module_description text</title>
<para>
Description: <filename>module_description _text_</filename>: This
directive is used to add a comment to the module. This directive
is not compulsory. This value does not override the value defined
in the agent if the module doesn<73>t exist in the management
console. This is created automatically when working on learning
mode.
This directive is used to add a comment to the module. This
directive is not compulsory. This value does not override the
value defined in the agent if the module does not exist in the
management console. This is created automatically when working
on learning mode.
</para>
</sect4>
<sect4><title>module_interval factor</title>
<para>
End of module: <filename>module_end</filename>
Pandora 1.2 introduces this new feature. You can, for each
module, setup its own interval. This interval its calculated as
a multiply factor for agent interval. For example, if your agent
has interval 300 (5 minutes), and you want a module only be
calculated each 15 minutes, you could add this line:
<filename>module_interval 3</filename>. So this module will be
calculated each 300sec x 3 = 900sec (15 minutes).
</para>
</sect4>
<sect4><title>module_end</title>
<para>
An example of a Windows module, checking if EventLog service is alive, would be:
Ends module definition
</para>
</sect4>
<sect4><title>Examples</title>
<para>
An example of a Windows module, checking if EventLog service is
alive, would be:
<programlisting>
module_begin
module_name ServicioReg
@ -781,8 +845,6 @@
module_description Eventlog service availability
module_end
</programlisting>
</para>
<para>
An example of a Unix module would be:
<programlisting>
module_begin
@ -795,6 +857,7 @@
module_end
</programlisting>
</para>
</sect4>
</sect3>
</sect2>
@ -814,11 +877,9 @@
are configured to collect data from the external system by, for
example, an SNMPGET tool.
</para>
</sect2>
</sect1>
<sect1><title>UNIX agents</title>
<sect2><title>Introduction to Unix agents</title>
<sect3><title>UNIX agents</title>
<sect4><title>Introduction to Unix agents</title>
<para>
The in-built UNIX applications and tools make the agents running on
this system be very simple. There are also agents developed for AIX,
@ -826,7 +887,7 @@
identical. Requirements for the installation of Pandora Agents on
UNIX
</para>
<sect3><title>AIX</title>
<sect5><title>AIX</title>
<para>
MD5 signatures are used to guarantee the integrity of the
generated data packages. The MD5 package is integrated in AIX 5.1
@ -835,8 +896,8 @@
problems with the AIX agents the checksum system used to validate
the integrity of the data can be disabled.
</para>
</sect3>
<sect3><title>Solaris</title>
</sect5>
<sect5><title>Solaris</title>
<para>
The MD5 package is necessary to execute the Solaris agent
correctly. This package is available from http://sunfreeware.com
@ -845,7 +906,9 @@
<para>
ftp://ftp.sunfreeware.com/pub/freeware/sparc/8/md5-6142000-sol8-sparc-local.gz
</para>
<sect4><title>MD5 Package installation on Solaris</title>
<para>
<emphasis>MD5 Package installation on Solaris</emphasis>
</para>
<para>
<programlisting>
root@stest:/tmp:> gzip -d md5-6142000-sol8-sparc-local.gz
@ -859,7 +922,7 @@
all packages). (default: all) [?,??,q]: 1
</programlisting>
</para>
</sect4>
<para><emphasis>Solaris SSH</emphasis></para>
<para>
The suggested SSH client is OpenSSH. If any other SSH client is to
be used it must be considered that each piece software may have
@ -867,82 +930,86 @@
F-Secure SSH is used, the public key must be in OpenSSH format
when the keys are generated. The format can be changed from IETF
to OpenSSH with F-Secure SSH, using the following command:
<programlisting>
ssh-keygen -i -f file_ietf_pubkey
</programlisting>
</para>
</sect3>
<sect3><title>GNU/Linux</title>
<para>
<filename>
ssh-keygen -i -f file_ietf_pubkey
</filename>
</para>
</sect5>
<sect5><title>GNU/Linux</title>
<para>
SSH and MD5 should be installed in Linux by default, but if they
are not they can be installed using the tools available in each
distribution.
</para>
</sect3>
<sect3><title>BSD (IPSO)</title>
</sect5>
<sect5><title>BSD (IPSO)</title>
<para>
SSH and MD5 should be installed by default. If they are not, it is necessary to install them.
SSH and MD5 should be installed by default. If they are not, it is
necessary to install them.
</para>
</sect3>
</sect2>
</sect1>
</sect5>
</sect4>
</sect3>
</sect2>
<sect1><title>Software installation</title>
<sect2><title>UNIX Systems</title>
<para>
<sect2><title>Pandora Unix Agent install</title>
<para>
The software comes in a .tar.gz file. First of all the file needs
to be extracted into a folder, usually /opt/pandora_agent,
although any other folder may be used. If a different folder is
used, the daemon launcher must be modified by changing route to
$PANDORA_HOME.
</para>
<para>
</para>
<para>
There is hardly any difference between AIX, Solaris and Linux, and
they all work around the hash MD5 generation binaries.
</para>
<para>
</para>
<para>
This is the structure of the installation in /opt/pandora_agent/
once the files have been extracted:
</para>
<para>
<filename>/opt/pandora_agent/data_out</filename>, folder where the
data collected by the agents is stored.
</para>
<para>
/opt/pandora_agent/data_out, folder where the data collected by the agents is stored.
<filename>/opt/pandora_agent/doc</filename>, folder with
information about the agent and its license.
</para>
<para>
/opt/pandora_agent/doc, folder with information about the agent and its license.
<filename>/opt/pandora_agent/pandora_agent.conf</filename>, file
where the data to be collected is defined, along side the command
to be executed for the data collection. This is the system
core, as it defines the main data to be collected in any Firewall.
</para>
<para>
/opt/pandora_agent/pandora_agent.conf, file where the data to be
collected is defined, along side the command to be executed for
the data collection. This is the system<65>s core, as it
defines the main data to be collected in any Firewall.
<filename>/opt/pandora_agent/pandora_user.conf</filename>, file
where several of the parameters to collect data from the monitored
system are defined in more detail.
</para>
<para>
/opt/pandora_agent/pandora_user.conf, file where several of the
parameters to collect data from the monitored system are defined
in more detail.
<filename>/opt/pandora_agent/pandora_agent.sh</filename>, this is
the actual Pandora agent. This file is a shellscript that collects
the data configured in the pandora_agent.conf and
pandora_user.conf files. It also transfers the data packages to
the Pandora server.
</para>
<para>
/opt/pandora_agent/pandora_agent.sh, this is the actual Pandora
agent. This file is a shellscript that collects the data
configured in the pandora_agent.conf and pandora_user.conf
files. It also transfers the data packages to the Pandora server.
<filename>/opt/pandora_agent/pandora_agent_daemon</filename>,
start and stop script. It makes a call to pandora_agent.sh. It
offers two options, start and stop.
</para>
<para>
/opt/pandora_agent/pandora_agent_daemon, start and stop script. It
makes a call to pandora_agent.sh. It offers two options, start and
stop.
</para>
<para>
/opt/pandora_agent/pandora.log, text file where the activity of
the Pandora agent is saved, when the agent is executed in
debugging mode.
<filename>/opt/pandora_agent/pandora.log</filename>, text file
where the activity of the Pandora agent is saved, when the agent
is executed in debugging mode.
</para>
<sect3><title>Key generation</title>
<para>
The SSH keys generated must be:
<itemizedlist mark='bullet'>
<listitem>
<para>
@ -967,10 +1034,10 @@
</para>
<para>
The public key must be copied into the
/home/.pandora/authorized_keys file in the Pandora server. Before
starting the Pandora agent the SSH authentication must be
checked. To do this the following command must be executed on the
agent machine:
<filename>/home/.pandora/authorized_keys</filename> file in the
Pandora server. Before starting the Pandora agent the SSH
authentication must be checked. To do this the following command
must be executed on the agent machine:
<programlisting>
$ ssh pandora@pandora_server
</programlisting>
@ -978,7 +1045,7 @@
The system must connect successfully BEFORE launching the Pandora agent.
</para>
</sect3>
<sect3><title>First execution of the agent</title>
<sect3><title>First execution of the Unix agent</title>
<para>
To start the agent it is only necessary to execute
pandora_agent_daemon start from /opt/pandora_client. Pandora Agent
@ -998,17 +1065,19 @@
To stop agent, execute pandora_agent_daemon stop from /opt/pandora_agent.
</para>
</sect3>
</sect2>
</sect1>
<sect1><title>Advanced agent configuration for Unix</title>
<sect3><title>Advanced agent configuration for Unix</title>
<para>
The real power of Pandora resides in the capability of the agents to run user defined scripts. This could be used to collect specific data or to perform an operation to return any desired value. This is the purpose of pandora_user.conf.
The real power of Pandora resides in the capability of the agents
to run user defined scripts. This could be used to collect
specific data or to perform an operation to return any desired
value. This is the purpose of pandora_user.conf.
</para>
<para>
This file is executed every in agent loop. It is a shell-script in which any command can be executed, as long as the output is in the XML format the agent uses to send data to the server. The XML structure would be:
This file is executed every in agent loop. It is a shell-script in
which any command can be executed, as long as the output is in the
XML format the agent uses to send data to the server. The XML
structure would be:
<programlisting>
&lt;module&gt;
&lt;name&gt;NAME&lt;/name&gt;
@ -1017,7 +1086,9 @@
&lt;/module&gt;
</programlisting>
Where NAME, TYPE and DATA are the variables already defined in previous sections. The XML must be built manually, usually using echo commands.
Where NAME, TYPE and DATA are the variables already defined in
previous sections. The XML must be built manually, usually using
echo commands.
</para>
<para>
For example, this would be the script a customized agent would use
@ -1026,7 +1097,8 @@
#!/bin/sh
# Pandora User-Defined acquisition script
# This code is under GPL licence
# Please refer documentation for more example and a more depth usage instructions
# Please refer documentation for more example and a more
# depth usage instructions
# mbuf clusters usados (%)
MBUF_TOTAL=`netstat -m |grep "mbuf cluster" | tr -s "/" " " |awk '{ print $2 }'`
@ -1043,14 +1115,18 @@
<para>
A more complex example could be:
<screen>
<![CDATA[
#!/bin/sh
# Pandora User-Defined acquisition script
# This code is under GPL licence
# Please refer documentation for more example and a more depth usage instructions
# Please refer documentation for more example and a more
# depth usage instructions
# Calculating the number of packages generated by ETH2, if nothing is generated
# Calculating the number of packages generated by ETH2,
# if nothing is generated
# within 20 seconds an alert is rosen
# Perform the calculation between 8 to 23h. Return ok for times outside this range
# Perform the calculation between 8 to 23h. Return ok for times
# outside this range
echo "<module>"
echo "<name>Packet_Generator_Check</name>"
@ -1059,7 +1135,7 @@
sleep 20
DOS=`ifconfig eth2 | grep "TX packets" | cut -f 2 -d ":" | grep -o -e "[0-9]*"`
HORA=`date "+%k"`
if [ "$HORA" \< "8" ] && [ "$HORA" \> "11" ]
if [ "$HORA" -lt "8" ] && [ "$HORA" -gt "11" ]
then
# Time out of range, no checking, everything OK
# Fuera de hora, no compruebo, esta OK
@ -1073,16 +1149,16 @@
fi
fi
echo "</module>"
]]>
</screen>
</para>
</sect1>
</sect3>
<sect1><title>Implementation examples</title>
<sect3><title>Implementation examples for Unix Agents</title>
<para>
Example #1: calculate the number of HITS of the main page of an Apache Web server:
Example #1: calculate the number of HITS of the main page of an
Apache Web server:
<programlisting>
module_begin
module_name WEB_Hits
module_type generic_data_inc
@ -1091,7 +1167,8 @@
</programlisting>
</para>
<para>
Example: check if the process of the DNS server (named) is active or fell over:
Example: check if the process of the DNS server (named) is active
or fell over:
<programlisting>
module_begin
module_name DNS_Daemon
@ -1188,13 +1265,13 @@
module_type generic_data_inc
module_exec cat /var/log/mail/mail.log | grep "identified spam" | wc -l
module_end
</programlisting>
</para>
</sect3>
</sect2>
<sect2>
<title>Installing Pandora Agent for Windows</title>
<title>Pandora Windows Agents.</title>
<sect3>
<title>Build Windows Agent from sources</title>
<para>
@ -1222,7 +1299,7 @@
<para>
This directory will hold the configuration files, which are:
<screen>
c:\Pandora\pandora_agent.conf :: Pandora Windows service main configuration
c:\Pandora\pandora_agent.conf :: Pandoramain configuration
c:\Pandora\id_dsa :: Private SSH key
c:\Pandora\id_dsa.pub :: Public SSH key
</screen>
@ -1331,7 +1408,8 @@
module_begin
module_name ReceivedPackets
module_type generic_data
module_exec netstat -s | grep "Paquetes recibidos "| tr -d " " | cut -f 2 -d "=" | tr -d "\n"
module_exec netstat -s | grep "Paquetes recibidos "|
tr -d " " | cut -f 2 -d "=" | tr -d "\n"
module_description Conexiones abiertas (interval 2)
module_end

418
pandora_doc/en/pandora_introduction.xml Normal file
View File

@ -0,0 +1,418 @@
<?xml version="1.0" encoding="utf-8"?>
<chapter>
<title>Introduction to Pandora</title>
<sect1><title>Pandora. The Free monitoring system</title>
<para>
Pandora is a monitoring application to watch systems and
applications. Pandora allows to know the status of any element of
your bussiness systems. Pandora watch for your hardware, your
software, your multilayer system and of course your Operating
System. Pandora could detect a network interface down and the
movement of any value of the NASDAQ new technology market. If you
want, Pandora could sent a SMS message when your systems
fails... or when Google value low below 330$.
</para>
<para>
Pandora adapt, like an octopus, to your systems and requirements,
because has been designed to be open, modular, multiplattform and
easy to customize.
</para>
</sect1>
<sect1>
<title>Pandora detailed introduction.</title>
<para>
&pandora; is a monitoring tool that allows a system
administrator to visually analise the status and efficiency of
Operating Systems, Servers, Applications and Hardware Systems -
such as firewalls, proxies, databases, Web servers, tunnelling
servers, routers, switches, processes, services, remote access
servers, etc. - all integrated into an open and distributed
architecture. Pandora can be implemented over any operating
system, with specific agents for each platform. Pandora can also
monitor any TCP/IP hardware system, such as load balancers,
routers, switches, printers, etc.
<graphic fileref="images/esquema.png" scale="50" align="center"/>
Pandora architecture is formed of four main components:
<itemizedlist mark='bullet'>
<listitem>
<para>
<emphasis>Web Console</emphasis>: Pandora's user
interface. The user controls and operates the system with
it. Several Web consoles can be implemented in a single
system. The Web console is written in PHP, and rests on a
database and a Web server. It is compatible with any
platform - GNU/Linux, Solaris, Win2000, AIX, etc. However,
the official supported platform is GNU/Linux.
</para>
<para>
The console permits the user to control the status of the
agents, view statistical information, generate graphs and
data tables, keep a system incident control, as well as to
generate reports and change the alerts, agents, and user
profile settings.
</para>
</listitem>
<listitem>
<para>
<emphasis>Server</emphasis>: The core server is the receptor
of the data packages and generates the alerts - it is the
brain of the system. Several servers can work alongside for
larger systems. It has been developed in Perl and works over
any platform, although, the official platform is GNU/Linux.
</para>
<para>
The core server accesses Pandora database, which is shared
with the Web server, and stores the processed data
packages. Server executes as daemon, and processes the
packages stored in its file system. Data is generated by the
system agents. Despite the server's low system resources
comsumption and simple installation and operation, the core
server is the most critical element of the system. The core
server receives and processes the produced data, and fires
the alerts and the events.
</para>
<para>
With the new Pandora 1.2 Network Server technology, Pandora
Network Servers could monitorize remote systems using
network resources like ICMP, TCP, UDP or SNMP
Queries. Network Servers are acting itself like "Network
Agents".
</para>
</listitem>
<listitem>
<para>
<emphasis>Central Database</emphasis>: At the moment the
system only supports MySQL. The central database keeps all
the information Pandora needs to work - agent data,
settings, user information, incidents, system settings,
etc. The system can use a MySQL cluster to store the
information, or a high disponibility solution for larger
sytems.
</para>
<para>
This database can work with any of the platform officially
supported by MySQL. Pandora can be implemented with MySQL
versions 3.0 and 4.0, although the latest is recommended.
</para>
</listitem>
<listitem>
<para>
<emphasis>Pandora Agents</emphasis>: They collect all the
system's data. They are executed in each local system,
although they can also collect remote information by
intalling monitoring sytems for the agent in several
different machines - called satellite agents.
</para>
<para>
They have been developed to work under a specific platform,
making use of the specific tools of the used language:
ShellScripting for Unix - which includes GNU/Linux, Solaris,
AIX, HP-UX and BSD, as well as the Nokia's IPSO. Pandora
agents can be developed in virtually any language, given its
simple API and being open source. Windows agent are
developed in a free development enviroment for C++ and uses
the same interface and modularity than Unix agents.
</para>
<para>
The old agent for Windows plattforms was developed on VBS
Scripting language, and is deprecated with the new Pandora
1.2 windows agent.
</para>
</listitem>
</itemizedlist>
<graphic fileref="images/pandora_arch1.jpg" scale="70" align="center"/>
</para>
</sect1>
<sect1><title>What kind of systems/ services can be monitored?</title>
<para>
At present, with Pandora any process or system that through a
command returns a value can be monitored, as well as any value in
any Operating System log file or similar. Some examples of already
existing implementations can be the following ones:
<programlisting>
Number of connections (sessions) of Checkpoint FW-1
Number of NAT sessions of Checkpoint FW-1
Number of connections of Linux NetFilter / IPTables firewall
Number of FW-1 logged packets
Number of FW-1 dropped packets
Number of FW-1 accepted packets
State of High Availability in FW1 NG
Last policy installed in a Firewall-1 module
Synchronization state of the modules in FW1 NG
CPU of the system: idle, user and system
Number of processes of the system
Temperature of the CPU of a system
Value of a MS Windows registry entry
Queued jobs in a generic dispatcher
Memory of the system: free, swap, kernel Fw-1, cache
Percentage of free space on disc (for different partitions)
Messages processed by a mail gateway
Existence of a string in a text file
IP traffic (filtering based on the connections of the firewall)
Hits of pages in HTTP Servers (Apache, iPlanet, IIS, Netscape)
Percentage of erroneous packets in a Gateway
Connections established in a Remote Access Server (RAS)
Size of a file
Open sessions by a VPN server
MySQL Performance: Threads, queries, sessions...
Snort system state
Reported events by IDS (Snort) up to six levels of priority
Network load
Number of local Connections (TCP, UDP, Unix sockets)
Detected viruses by a Web Antivirus Gateway
ICMP latency time towards a host
Rate of average transference in a file transfer tool
Number of DNS requests attended by a server (including types)
Number of FTP sessions attended by a FTP server
(Generic) State of any active process / service in the system
(Generic) State of any countable parameter of the system
</programlisting>
</para>
<sect2><title>Global architecture</title>
<para>
Pandora 1.2 has changed many things from 1.1 version, but this
graph representing Pandora architecture is very useful to
understand in a single graph, all components.
<graphic fileref="images/pandora_arch2.jpg" scale="45" align="center"/>
</para>
</sect2>
</sect1>
<sect1><title>Information gathering with Pandora agents</title>
<para>
Pandora agents are based on native languages in every platform:
scripts that can be written in any language. It's possible to
reproduce any agent in any programming language and can be
extended without difficulty the existing ones in order to cover
aspects not taken into account up to the moment.
</para>
<para>
These scripts are formed by modules that each one gathers a
"chunk" of information. Thus, every agent gathers several "chunks"
of information; this one is organized in a data set and stored in
a single file, called data file.
</para>
<para>
The process of transferring the data file from the agent to the
server is made regularly at a defined time interval in the agent
configuration file, pandora_agent.conf. It's possible to modify
that parameter to not fill the database with non-relevant
information, not to load the network or to not affect the system
performance. The default interval is 300 (seconds), which is
equivalent to five minutes. Minor values of 100 (seconds) are not
recommended since host performance can be affected, besides
loading excessively Database and the Operating System of Pandora
Server. Pandora is not a real time system; it's an applications
and systems general monitoring system in environments that are not
critical at real time.
</para>
<para>
Packets transfers are made via SSH, with DSA authentication
(although also RSA can be used). The process is completely safe
since neither any password nor unencrypted confidential
information is sent. Confidentiality, integrity and authentication
of the connections between the agent and the server are
ensured. In the Agents and Server Installation and Configuration
guides, the process of generation of keys to do the automatic SCP
transfer is detailed.
</para>
<para>
Also the transfer via FTP or any other file transfer system could
be made, although SSH has been chosen for security and
compatibility with most of the systems in the market.
</para>
<para>
Pandora Agents are thought to be executed from the agent from
which they gather information, although the agents can gather
information of accessible machines from the host where they are
installed. In this case those agents are called "Satellite
Agents". These Satellite Agents can use Telnet, SNMP or any other
commands to get the information.
</para>
<para>
We can also have a host with several agents: Some that gather
information from the accessible machines (acting as "satellite
agents") and the Standard Agent that monitors the host where it's
running.
</para>
<sect2><title>XML Data files</title>
<para>
The data file has the following syntax:
<programlisting>
hostname.serialnumber.data
</programlisting>
This is an XML file, and its name is the combination of the
hostname where the agent runs, a different serial number for every
data package and the extension .data that indicates that it's a
data file.
</para>
<para>
We also have a control file for every data file:
<programlisting>
hostname.serialnumber.checksum
</programlisting>
This file has .checksum extension and contains a MD5 hash of the
data file. This allows checking that the information has not been
changed before being processed.
</para>
<para>
The XML data file generated by every agent is the core of
Pandora. This file has the information gathered by the Agent. Its
easy structure allows that any user could create it's own
developments to be processed in Pandora, or use the included ones.
An example of the information included into the data file is the
following one:
<screen>
<![CDATA[
<agent data os_name="SunOS" os_version="5.8" timestamp="300"
agent_name="pdges01" version="1.0">
<module>
<name>SSH Daemon</name>
<type>generic_proc</type>
<data>1</data>
</module>
<module>
<name>FTP Daemon</name>
<type>generic_proc</type>
<data>0</data>
</module>
<module>
<name>DiskFree</name>
<type>generic_data</type>
<data>5200000</data>
</module>
<module>
<name>UsersConnected</name>
<type>generic_data_inc</type>
<data>119</data>
<min>1</min>
<max>250</max>
<description>Users currently connected</description>
</module>
<module>
<name>LastLogin</name>
<type>generic_data_string</type>
<data>slerena</data>
</module>
</agent_data>
]]>
</screen>
</para>
</sect2>
<sect2><title>Pandora servers</title>
<para>
Pandora Server is a Perl script that processes the information
sent by the agents. The agents send the XML data file via SSH and
the server periodically verifies if it has new data files waiting
to be processed.
</para>
<para>
Data are extracted from the data file, identifying origin, type
and category. One classified, the data are inserted into the
Database by the same Perl script.
</para>
<para>
Pandora Server can work in High Availability and/or Load
Balancing. In a very big architecture, several Pandora Servers can
be arranged simultaneously to be able to manage big volumes of
information distributed by geographical or functional zones.
</para>
<para>
Pandora Server is always running (as a daemon) and permanently
verifies if some element causes to fire an alarm. If so, it
executes the action defined in the alarm, as to send a SMS, an
email, to activate the execution of a SCRIPT or to send an HTTP
form.
</para>
<para>
We could have several simultaneous servers, one of them is the
Main Server or "Master Server " and the rest servers are "Slave
Servers". The Master Server is the only one that verifies the
alarms if any agent goes down. The server who receives the data
file from the agent always fires the rest of alarms, defined in
the agents' modules. This is also important if this server changes
(due to configurations of high availability, load balancing or
clustering).
</para>
</sect2>
<sect2><title>Pandora console</title>
<para>
The Web Console it's a web application that allows to see
graphical reports, state of every agent, and to access to the
information sent by the agent, to see every monitored parameter
and to see its evolution throughout the time, to form the
different nodes, groups and users of the system. It is the part
that interacts with the final user, and that allows you to
administer the system.
</para>
<para>
The Web Console is written in PHP and no plug-in, Flash, Java or
ActiveX is needed to access the console, only a browser that
supports HTML and CSS (IE5+ o Mozilla 4+). Pandora Web Console can
run in several servers, the only thing you need is to access
Pandora Database, where Pandora stores all the information.
</para>
</sect2>
<sect2><title>Pandora database</title>
<para>
Pandora uses a SQL Database to store all the information. Pandora
maintains an asynchronous database with all the received data,
making a temporary cohesion of everything what it receives and
normalizing all the information from the different sources. Every
Agent data module generates an entry of information for every data
bundle, which implies that a real production system can have of
the order of ten million of data, or information atoms.
</para>
<para>
This information is managed automatically from Pandora, carrying
out a periodic and automatic maintenance of the database. This
allows that Pandora should need neither any type of administration
of database nor process attended by an operator or manager. This
is made by a periodic purge of the past information over a date
(by default 90 days), as well as a data compaction of the data
that have more than, by default, 30 days.
</para>
<sect3><title>Compacting data</title>
<para>
Data stored by Pandora are useful to see evolutions regard through
the time, to make statistics, to generate reports and to do
capacity planning, as well as other tasks of statistical
nature. For it, it isn't necessary to have all the data, but it's
enough to have a representative sample, of smaller resolution,
enough to carry out the task that is needed.
</para>
<para>
With that philosophy the compaction system has been
constructed. If we have a sample of 9.000 elements, distributed
during 90 days, for example, Pandora is going to take the data of
last month, which would be 3.000 elements and it's going them to
compress them in 300. In the graphs they will practically be seen
equal, which it will serve us for the reports, statistics and
other tasks. This is made by means of interpolation in temporary
strips, in a totally automatic and periodic way, without the user
or the administrator must himself or herself worry about it.
</para>
</sect3>
</sect2>
</sect1>
<sect1>
<title>About Pandora
</title>
<para>
Pandora is a project initiated and mainly developed by Sancho
Lerena, at present other people is working on it: Raúl Mateos,
David Villanueva, Esteban Sánchez, Jose Navarro and Jonathan
Barajas. We want to give thanks for many other people who help us
with translation, graphic design, bugs reporting and interesting
ideas.
</para>
<para>
Pandora is Free Software, and is published under GPL Licence. In
order to know the last features, go to the official web site of
the project in http://pandora.sourceforge.net.
</para>
</sect1>
</chapter>