Regardless the platform an agent is running on, this is formed of
the following elements:
</para>
<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<72>
s agent folder.
</para>
<para>
One or several configuration files where the values to be
collected are defined. The file is called pandora_agent.conf both
for Windows and Unix machines.
</para>
<para>
This simple structure makes it easy the customisation of an
agent. There is no need to <20>reprogram<61> the agent to modify the
way it works, as the configuration file holds most of the
parameters needed to do so.
</para>
</sect2>
<sect2><title>Main Script</title>
<para>
The main script is the executable file that collects the data
specified in the configuration file. It sends the data to the
server in XML. In Windows machines application is installed as a
service and is executed at the time intervals set in the
configuration file. In machines running over UNIX the main script
is run through a special script called pandora_agent_daemon, and
runs continuously in the machine as a process.
</para>
</sect2>
<sect2><title>Configuration File</title>
<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>
<para>
General parameters.
</para>
<para>
Module definitions.
</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:
</para>
<itemizedlistmark='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.
</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).
</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<72>s 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.
</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.
</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.
</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.
</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.
</para>
</listitem>
<listitem>
<para>
checksum: (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
systems where a MD5 tool cannot be implemented. If the
checksum is deactivated in the agent it must be also
disconnected in the server. Otherwise it could create
problems.
</para>
</listitem>
</itemizedlist>
<para>
An example of the general parameters from a Unix configuration would be.
<programlisting>
server_ip Pandora_Server
server_path /opt/pandora/data_in
pandora_path /opt/pandora
temporal /opt/pandora/data_out
interval 300
agent_name satellite_agent
debug 1
checksum 1
</programlisting>
</para>
</sect3>
<sect3><title>Module definition</title>
<para>
Each data item that is to be collected must be defined precisely
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:
</para>
<para>
Beginning of the module: <filename>module_begin</filename>
</para>
<para>
Name of the module: <filename>module_name _name_</filename>
</para>
<para>
Data type: <filename>module_type _type_</filename>. Data type the
module will handle. There are four data types for agents:
<itemizedlistmark='bullet'>
<listitem>
<para>
Numeric (generic_data). Simple numeric data, float or
integer. If the values are of the float type, they will be
truncated to their integer value.
</para>
</listitem>
<listitem>
<para>
Incremental (generic_date_inc). Integer numeric data equal to
the differential between the actual value and the previous
one. When this differential is negative the value is set to 0.
</para>
</listitem>
<listitem>
<para>
Alphanumeric (generic_string). Text strings up to 255 characters.
</para>
</listitem>
<listitem>
<para>
Monitors (generic_proc). Stores numerically the status of the
processes. This data type is called monitor because it assigns
0 to an "Incorrect" status and any value above 0 to any
"Correct" status.
</para>
</listitem>
</itemizedlist>
</para>
<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.
</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):
</para>
<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.
</para>
<para>
For a Windows agent there are more directives to obtain to data:
</para>
<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.
</para>
<para>
<filename>module_proc _proc_</filename>: Checks if a given
processname is running in this host. Remember to use " "
Select package(s) you wish to process (or 'all' to process
all packages). (default: all) [?,??,q]: 1
</programlisting>
</para>
</sect4>
<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
different ways to generate or manage keys. For example, if
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>
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>
<para>
SSH and MD5 should be installed by default. If they are not, it is necessary to install them.
</para>
</sect3>
</sect2>
</sect1>
<sect1><title>Software installation</title>
<sect2><title>UNIX Systems</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>
There is hardly any difference between AIX, Solaris and Linux, and
they all work around the hash MD5 generation binaries.
</para>
<para>
This is the structure of the installation in /opt/pandora_agent/
once the files have been extracted:
</para>
<para>
/opt/pandora_agent/data_out, folder where the data collected by the agents is stored.
</para>
<para>
/opt/pandora_agent/doc, folder with information about the agent and its license.
</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.
</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.
</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.
</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.
</para>
<sect3><title>Key generation</title>
<para>
The SSH keys generated must be:
<itemizedlistmark='bullet'>
<listitem>
<para>
SSSH version2 keys
</para>
</listitem>
<listitem>
<para>
Open SSH format keys
</para>
</listitem>
<listitem>
<para>
DiffieHellman (DH) format keys
</para>
</listitem>
</itemizedlist>
To generate the keys the command ssh-keygen is executed followed
by the specific parameters for our operating system. Please,
create key WITHOUT password.
</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:
<programlisting>
$ ssh pandora@pandora_server
</programlisting>
The system must connect successfully BEFORE launching the Pandora agent.
</para>
</sect3>
<sect3><title>First execution of the agent</title>
<para>
To start the agent it is only necessary to execute
pandora_agent_daemon start from /opt/pandora_client. Pandora Agent
creates a file (/var/run/pandora.pid) with the PID number of the
process when it is started.
</para>
<para>
For IPSO systems the agent will be started with a nice -10
priority, so it becomes the process with the lowest priority over
the system CPU. It will be executed when no other processes with a
higher priority are waiting in the system CPU queue.
</para>
<para>
In BSD systems the maximum priority is +20 and the lowest -20.
</para>
<para>
To stop agent, execute pandora_agent_daemon stop from /opt/pandora_agent.
</para>
</sect3>
</sect2>
</sect1>
<sect1><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.
</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:
<programlisting>
<module>
<name>NAME</name>
<type>TYPE</type>
<data>DATA</data>
</module>
</programlisting>
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
for Checkpoint FW1 in IPSO agents:
<programlisting>
#!/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
