Collect scripts:
================

Execution environment:
======================

Default collect types are located under "/usr/lib/cdat/types/".
User-defined collect types can be created under "/var/adm/ras/cdat/".

Collect scripts are executed on the master node as user "cdat"
or as the user specified with "cdat init".

Collect scripts are invoked with the following environment variables:

$CDAT_HOST:
Specifies the host name of the remote node.

$CDAT_USER:
Specifies the user name to log into the remote node.

$CDAT_TYPE:
Specifies the node type (e.g LPAR, HMC, VIOS, PSCALE).

$CDAT_PHASE:
Specifies the phase to be executed (see description of phases below.)

$CDAT_SRVC_DIR:
Specifies the path on the master node to the "get_file", "push_file",
"remote_cmd" and "mlog" services.

$CDAT_TYPE_DIR:
Specifies the directory containing the scripts for the current collect
type.

$CDAT_DEST_DIR:
Specifies the directory on the master node where the data collected on
the remote node should be stored.

$CDAT_PMR:
If set, specifies the PMR number associated with the current collect.

Collect scripts are invoked with the following parameters:

$*: Optional parameters passed to the cdat "collect" command

Collect scripts should return the following value:

0: SUCCESS: indicates that the collect script succeeded
1: IGNORE: indicates that the node should be ignored in next phases
>128: ERROR: indicates that an error occured during the execution of
the script.  The framework will invoke the "clean" phase when such
an error is occured.

Services:
=========

1. push_file

The "push_file" service allows the transfer of files or directories
from the master node to the remote node.  It automatically choses a
protocol to transfer the file (either SCP or FTP) and manages
authentication automatically.

2. get_file

The "get_file" service allows the transfer of files or directories
from the remote node to the master node.  It automatically choses a
protocol to transfer the file (either SCP or FTP) and manages
authentication automatically.

3. remote_cmd

The "remote_cmd" service allows the execution of commands on the
remote node.  It automatically choses a protocol to log into the
node (either SSH, REXEC or TELNET) and manages authentication
automatically.

4. mlog

The "mlog" service allows to log messages from the collect script.
It takes a level and a message as parameters.
Messages are stored in log files and printed to stderr at the end
of the collect phase if the specified level is -1.

Phases:
========

The framework defines a set of six phases:
check, init, execute, terminate, grab and clean

A collect type may provide scripts or executable to implement those
phases.  Not all phases are required though, and if no script exists
for a given phase, this phase is silently ignored.

There is a synchronization point after each phase, i.e. the framework
waits for the previous phase to finish on all nodes before starting
the next phase.

Here is a description of the different phases:

1. check

The purpose of the "check" phase is to verify that the collect can be
performed on the remote node.  This can include checking the OS level
of the remote node, checking that enough disk space is available etc...

2. init

The purpose of the "init" phase is to setup the environment required
for the execution of the collect.  This can include the installation
of filesets or scripts on the remote node.  It is recommended to use
the "push_file" service to copy files to the remote node.

3. execute

The purpose of the "execute" phase is to start the collect process on
the remote node.

4. terminate

The purpose of the "terminate" phase is to stop the collect process on
the remote node such that the result of the collect is available.

5. grab

The purpose of the "grab" phase is to retrieve the collected data from
the remote node and to copy it into the destination directory.
It is recommended to use the "get_file" service to retrieve files or
directories from a remote node as this service manages the authentication
with the remote node automatically and is also able to extend the size
of the repository when required.
The environment variable $CDAT_DEST_DIR specifies the location where
files should be copied.

6. clean

The purpose of the "clean" phase is to perform cleanup on the local
or remote node.  This can include the removal of temporary files or
the removal of filesets installed during the "init" phase from the
remote node.
Notice that the "clean" phase is always performed, even if the collect
fails or is interrupted.

manifest.xml:
=============

The manifest.xml file should be located at the root of the collect
type directory.  It describes the collect type and optional parameters.
See the "example/manifest.xml" file for an example.