#######################
#######################
#### IPG Swim v1.0 ####
#######################
#######################

############
# Contents #
############

NOSA.txt                    Swim license
README                      This file
Makefile                    Swim make file
doc/grid04.pdf              Swim conference paper
java                        Swim java source
perl                        Swim perl source
pour/swim.xsd               Swim user drain XML schema
pour/config.xml             Pour configuration file for Swim
python                      Swim python source
shar                        Swim compilation target directory


###############
# Preparation #
###############

1. Perl 5.0 or above

Download from http://www.cpan.org.  Tested with Perl 5.8.

2. Java 1.4 or above

Download from http://java.sun.com.  Tested with Java 1.4.2.

3. IPG Pour 1.0

Download from http://opensource.arc.nasa.gov.


###############
# Compilation #
###############

Type "make" in the root of the distribution directory.


##############
# Deployment #
##############

This section assumes familiarity with the concepts in "doc/grid04.pdf".
Once Pour has been downloaded and deployed as described in the Pour
documentation, Swim can be deployed as a Pour spout using the
configuration file defined in the "pourConfigFile" parameter of the
"$GLOBUS_LOCATION/server-config.wsdd" file.

Swim provides three executables for use in GRAM pumps to collect
software information on-demand, an executable for use in a keyed drain
to gather and publish software information periodically, and an XML
schema for use in a user drain to publish user-specific software
information.  A complete example of an appropriate Pour configuration
file is given in "pour/config.xml".  Swim is added as a spout using
the basic template:

    <pour:spout>
        <pour:xmlUri>http://ipg.nasa.gov/swim</pour:xmlUri>
        <pour:xmlPrefix>swim</pour:xmlPrefix>
        <pour:xmlRoot>swim</pour:xmlRoot>
        <pour:drains>
            ...
        </pour:drains>
        <pour:pumps>
            ...
        </pour:pumps>
    </pour:spout>


1. Stat GRAM pump

The stat pump retrieves stat information about any file on a
particular host as well as determining its type and canonical name.
After compilation, the corresponding executable can be found at
"shar/stat.shar".  This pump is added to Pour as follows:

    <!-- Stat -->
    <pour:GramPump pour:package="gov.nasa.ipg.pour.pump">
        <pour:prefixes>
            <pour:string>/file</pour:string>
        </pour:prefixes>
        <pour:restrictions>
            <pour:string>/file[@host]</pour:string>
            <pour:string>/file[@path]</pour:string>
        </pour:restrictions>
        <pour:validTimeMillis>604800000</pour:validTimeMillis>
        <pour:executable>/your/dir/shar/stat.shar</pour:executable>
        <pour:host>restrictions[0]</pour:host>
        <pour:arguments>
            <pour:string>restrictions[1]</pour:string>
        </pour:arguments>
    </pour:GramPump>

In this case, "/your/dir/shar" must be replaced by the location of the
"stat.shar" executable.  The valid time defined above is one week, but
may be changed as desired.  This pump provides information for queries
involving "/swim:swim/swim:file" that define a host and a path.  For
example, the Pour query:

    /swim:swim/swim:file[@swim:host='example.com'][@swim:path='/bin/ls']
    
would provide a response such as:

    <swim:file swim:host="example.com" swim:path="/bin/ls">
        <swim:name>ls</swim:name>
        <swim:type>elf</swim:type>
        <swim:os>Linux</swim:os>
        <swim:arch>i686</swim:arch>
        <swim:size>85232</swim:size>
        <swim:mode>755</swim:mode>
        <swim:owner>root</swim:owner>
        <swim:group>root</swim:group>
    </swim:file>


2. Dependency Analysis GRAM pump

The dependency analysis pump computes software dependency information
about any file on a particular host.  After compilation, the
corresponding executable can be found at "shar/analyze.shar".   This
pump is added to Pour as follows:

    <!-- Analyzer -->
    <pour:GramPump pour:package="gov.nasa.ipg.pour.pump">
        <pour:prefixes>
            <pour:string>/file/dependencies</pour:string>
        </pour:prefixes>
        <pour:restrictions>
            <pour:string>/file[@host]</pour:string>
            <pour:string>/file[@path]</pour:string>
        </pour:restrictions>
        <pour:validTimeMillis>604800000</pour:validTimeMillis>
        <pour:executable>/your/dir/shar/analyze.shar</pour:executable>
        <pour:host>restrictions[0]</pour:host>
        <pour:arguments>
            <pour:string>restrictions[1]</pour:string>
        </pour:arguments>
    </pour:GramPump>

As in the previous case, "/your/dir/shar" must be replaced by the
location of the "analyze.shar" executable.   This pump provides
information for queries involving "/swim:swim/swim:file/
swim:dependencies" that define a host and a path.  For example, the
Pour query:

    /swim:swim/swim:file[@swim:host='example.com']
        [@swim:path='/bin/ls']/swim:dependencies

would provide a response such as:

    <swim:dependencies>
        <swim:file swim:name="librt.so.1" swim:type="elf_shared"
            swim:version="unknown" swim:os="Linux" swim:arch="i686"/>
        <swim:file swim:name="libacl.so.1" swim:type="elf_shared"
            swim:version="unknown" swim:os="Linux" swim:arch="i686"/>
        <swim:file swim:name="libselinux.so.1" swim:type="elf_shared"
            swim:version="unknown" swim:os="Linux" swim:arch="i686"/>
        <swim:file swim:name="libc.so.6" swim:type="elf_shared"
            swim:version="unknown" swim:os="Linux" swim:arch="i686"/>
    </swim:dependencies>


3. Locator GRAM pump

The locator pump retrieves the location of a software component with a
particular name and type on a particular host.  After compilation, the
corresponding executable can be found at "shar/locate.shar".  This
pump is added to Pour as follows:

    <!-- Locator -->
    <pour:GramPump pour:package="gov.nasa.ipg.pour.pump">
        <pour:prefixes>
            <pour:string>/file</pour:string>
        </pour:prefixes>
        <pour:restrictions>
            <pour:string>/file[@host]</pour:string>
            <pour:string>/file[name]</pour:string>
            <pour:string>/file[type]</pour:string>
        </pour:restrictions>
        <pour:validTimeMillis>604800000</pour:validTimeMillis>
        <pour:executable>/your/dir/shar/locate.shar</pour:executable>
        <pour:host>restrictions[0]</pour:host>
        <pour:arguments>
            <pour:string>restrictions[1]</pour:string>
            <pour:string>restrictions[2]</pour:string>
        </pour:arguments>
    </pour:GramPump>

As in the previous two cases, "/your/dir/shar" must be replaced by the
location of the "locate.shar" executable.   This pump provides
information for queries involving "/swim:swim/swim:file" that define a
host, a name, and a type.  For example, the Pour query:

    /swim:swim/swim:file[@swim:host='example.com']
        [swim:name='ls'][swim:type='elf']

would provide a response such as:

    <swim:file swim:host="example.com" swim:path="/bin/ls">
        <swim:name>ls</swim:name>
        <swim:type>elf</swim:type>
        <swim:os>Linux</swim:os>
        <swim:arch>i686</swim:arch>
        <swim:size>85232</swim:size>
        <swim:mode>755</swim:mode>
        <swim:owner>root</swim:owner>
        <swim:group>root</swim:group>
    </swim:file>

Note that this is the same response provided for the example stat query,
but in this case, the user did not know the path of the software
component, only that it was named "ls" and was of type "elf".

The types supported by Swim include "elf" (ELF executable), "elf_shared"
(ELF shared library), "java" (java bytecode), "perl" (Perl module or
script), and "python" (Python module or script).  There are also
architecture-specific variants including "elfN32", "elf64",
"elfN32_shared", and "elf64_shared".


4. Swim keyed drain

The Swim keyed drain attempts to locate all software (of the supported
types) installed on a particular host.  This drain is added to Pour as
follows:

    <pour:KeyedDrain pour:package="gov.nasa.ipg.pour.drain">
        <pour:key>30313233343536373839616263646566</pour:key>
    </pour:KeyedDrain>

In this case, the key should be replaced with a suitable value in the
appropriate hexadecimal representation as described in the Pour
documentation.  In this example, the key is set to the hexadecimal
equivalent of "0123456789abcdef".

The keyed drain is intended for use within a cron job.  See the crontab
manual page on your system for directions on setting up cron jobs with
configurable frequencies.  See "client/cron.pl" in the Pour distribution
for an example of a suitable cron executable that inserts periodic
information into a Pour repository.  Instead of adding a static
"periodic.xml" file, however, the XML should be generated by the
"perl/swim.pl" script.  This script gathers software information and
produces the corresponding XML document for insertion into Pour.  If a
filename argument is given, output will be written to that file.
Otherwise, it will be written to STDOUT.


5. Swim user drain

The Swim user drain allows users to add their own software installations
into the information repository.  This information must be formatted
appropriately based on the provided XML schema in "pour/swim.xsd".
This drain is added to Pour as follows:

    <pour:UserDrain pour:package="gov.nasa.ipg.pour.drain">
    <pour:xsdFile>/your/dir/pour/swim.xsd</pour:xsdFile>
    <pour:validTimeMillis>604800000</pour:validTimeMillis>
    </pour:UserDrain>

In this case, "/your/dir/pour" must be replaced with the location of
the "swim.xsd" file.  This file can also be consulted to determine the
types of information that can be queried in Swim.


#########
# Usage #
#########

Once Swim has been deployed as a Pour spout, it can be used as described
in the Pour documentation.


#######################
# Contact Information #
#######################

Paul Kolano

kolano@nas.nasa.gov

http://www.nas.nasa.gov/~kolano/projects/swim.html