Inca 2.03 User's Guide

5.1. Repositories

Incat begins by showing the panel for Inca reporter repositories (as shown in Figure 10). The default Inca configuration retrieves reporters from the $INCA_DIST/Inca-Reporter-* repository on the agent machine. To add this repository to your list, press the Add button in the Repositories section, enter the file:/ location of the Packages.gz file in the pop-up window that appears, then press the OK button. Within a few seconds you should see the repository appear in the Repositories list, a set of reporters in the Reporters list, and properties for the first reporter in the Reporter Properties list. Reporter source code is viewable by double clicking on a reporter name or by selecting the reporter name and pressing the "Show" button.

5.2. Resource Configuration

The default Inca configuration defines three resource groups -- a group called "localResource" that specifies the host where the Inca Agent will launch a new Reporter Manager (localhost) and two container groups called "localSite" (contains "localResource") and "defaultGrid" (contains "localSite") that can be extended to include any other hosts running Reporter Managers. The default resource configuration is shown is Figure 11.

This configuration above can be duplicated in an empty Inca installation by pressing the Resource Configuration tab near the top of the incat window and then entering information about the hosts on which you want Inca to run reporters. To define the default groups above in incat, press the Add button in the Resource Groups section to open the resource group edit dialog shown in Figure 12.

In the Group Name text box, enter the name "localResource" as a nickname for the machine the Reporter Manager client runs on. Enter "localhost" in the Members text box and select "local" as the access method. Press OK to complete entry of this resource group. Incat will close the resource group edit dialog and will display localResource in the Resource Groups section of the Resource Configuration panel.

Press the Add button again to add a second resource group. Give this one the name "defaultGrid" and enter "localResource" in the Members text box. This tells incat that any hosts in the "localResource" group (localhost, in this case) are also part of the defaultGrid group. If you defined other groups, "siteB", "siteC", etc., you could include these in defaultGrid by listing them in the Members text box, separated by spaces. Press OK to complete entry of this resource group. In the Resource Groups list, select each group and notice that localhost is listed in the the Members panel.

5.3. Suites

Pressing the Suites tab near the top of the incat window takes you to incat's suite/series specification panel. Here you specify the reporters you want to run, the resource groups to run them on, how frequently to run them, and the arguments to use when running them.

The default Inca configuration defines a single suite named sampleSuite that contains eight series as shown in Figure 13.

In a new Inca installation, you can add the default suite above by pressing Add button in the Suites section of the panel, entering "sampleSuite" in the pop-up window, then pressing the OK button. To add series to the new suite, press the Add button in the Series section to open the incat series dialog and configure each like the atlas series in Figure 14.

The bottommost two text boxes in the series dialog allow you to test the output of the reporter and send email if the test fails. This is covered in Section 5.8 below; for this series leave these boxes blank. Press the OK button, and incat will close the series dialog box and add the series to the Series list in the suite/series specification panel.

The other nine series in the default Inca configuration are composed similarly to the first one. Press the Add button in the series section for each of them, then set the values in the series dialog as specified in the table below. Set the log argument for each series to 3 and the frequency to 10 minutes.

5.4. Committing/Saving

Your Inca deployment configuration is now complete. At this point, it's a good idea to use the "Save" option in incat's File menu to write the configuration to a file (Figure 15). That way, you have a local copy of the configuration that you can later modify. The file is formatted XML; if you're curious, you can read through it to see how incat represents the information you've entered.

Although your configuration is complete, it's not yet active. To tell Inca to begin running reporters, you need to have incat send your configuration to your Inca Agent. If you started incat with the -A argument, then you're already connected to your Agent. Otherwise, use the "Connect" option in incat's Agent menu to establish a connection. Once you're connected, you can use the "Commit" option in the Agent menu to send the configuration to the Agent (Figure 16). In response, the Agent will install the Inca Reporter Manager code on the host specified in incat's "Resource Configuration" panel and begin running the reporters you specified in the "Suite Series" panel.

5.5. Resource Access Methods

The Inca Agent can use the following access methods to stage and start Reporter Managers on resources:

• manual:

  Entering a manual resource group indicates that you want complete, direct control over Inca execution on the group. For a manual resource group you must start the Reporter Manager on the command line and restart it any time you want to change the reporter series configuration for the group. The Agent will NOT automatically start a Reporter Manager for a manual resource as it will for local, ssh, or globus2 resources. For a manual resource group, incat provides a text box for you to enter an email that should be notified when the Inca configuration on the resource needs to be updated.

• local:

  The Agent starts a Reporter Manager on the same machine where the Agent is running (localhost).

• ssh:

  The Agent starts a Reporter Manager on a remote machine using ssh to access the remote machine. Reporter Manager files are copied from the Agent to the remote machine using sftp. For ssh resource groups, incat provides text boxes for you to enter the login id, password, and path to the ssh key file on the Agent machine. For security purposes, incat displays asterisks for the password and encrypts it when you save the configuration to a file.

• globus2:

  The Agent starts a Reporter Manager on a remote machine using globus to access the remote machine. Reporter Manager files are copied from the Agent to the remote machine using GridFtp. When you select globus2 in the Access Method pull-down, incat provides text boxes for you to enter contact information for the resource's Globus Gram and GridFtp servers. If you leave these boxes blank, Inca defaults to ports 2119 and 2811, respectively, for the first host in the resource group's member list. Access to Globus hosts requires an active Globus proxy on the Agent's host. You can either create a manual proxy on the Agent machine before starting, or you can store a proxy on a myproxy server and complete the four incat proxy dialog boxes (see below) so that the Agent can obtain one as needed.

5.6. Proxies

For convenience, the Inca framework can be used to retrieve a proxy for the globus2 access method or for reporters that require an active proxy. Reporters that require a proxy should use the Inca::Reporter::GridProxy module described in Section 7.2.3.

Before configuring Inca to retrieve proxies, first store a proxy on a myproxy server. For information about setting up a myproxy server or storing proxies on a server, please see the official myproxy documentation.

The Agent can automatically retrieve a proxy from a myproxy server if the proxy information is defined in incat as follows:

The dialog boxes are the hostname of the myproxy server, the username and password used to store the proxy, and the lifetime in hours that the agent should retrieve a proxy for (the default is 12 hours).

Once proxy information is committed to the agent, it can be retrieved by reporter managers. Each time a reporter manager is ready to run a reporter that needs a proxy it:

• requests the MyProxy passphrase from the agent

• uses the MyProxy command-line client to retrieve proxy credentials from a MyProxy server

• clears the MyProxy passphrase from memory

The MyProxy passphrase is stored on the agent in the $INCA_DIST/var/resources.xml file and is encrypted with the same passphrase as the agent's private key. The MyProxy passphrase passes between the reporter manager and agent over their SSL connection.

5.7. Using Resource Macros

Resource macros provide a shorthand for defining multiple, similar series. For example, suppose you wanted to add three series to the configuration defined above to measure the ping time to three different hosts, named blue.ufo.edu, green.ufo.edu, and red.ufo.edu. One approach would be to define a series for blue, use the Copy button in the Series section of the Suites panel to make two copies, then modify them to ping green and red.

A better approach is to use a macro for the host names and let Inca replicate the series for you. In the Resource Configuration panel, click on defaultGrid in the Resource Group section. Next, press the Add button beneath the Macros section. This opens a dialog box that allows you to enter the name and value(s) of a macro associated with the current resource group. Enter "targets" in the Macro Name text box and "blue green red" in the Macro Value(s) text box, then press OK. The definition of the targets macro now appears in the Macros section of the Resource Configuration panel.

The targets macro is also defined for the other resource groups since the defaultGrid contains all other groups. As shown in Figure 17, macros appear grey if they were defined in a resource group other than the one selected. You can override an inherited macro value by selecting the macro in the Macros panel and pressing the Edit button to open the macro edit dialog. After you change the macro value and press OK, the updated macro definition will show in black in the Macros panel, indicating that the resource is no longer using the inherited value.

To make use of the macro you've defined, click the Suites tab, then press the Add button underneath the Series section to open the series edit dialog. In the dialog, set the reporter to grid.benchmark.performance.ping and the resource group to localResource.

In the host text box in the Arguments section of the dialog, enter "@targets@.ufo.edu". Macro references in incat are indicated by placing a "@" before and after the macro name. When the Inca Agent encounters a macro reference in a series, it makes one copy of the series for each value of the macro. Since the targets macro has three values--blue, green, and red--the Inca Agent will make three copies of this series, substituting a single value for the macro reference in each. In this case that means that you'll have one series with a host argument of "blue.ufo.edu", one with a host argument of "green.ufo.edu", and one with a host argument of "red.ufo.edu".

The inca web pages use the series nickname when displaying series results. If you leave the series nickname with its default value, the name of the reporter, then all three series will have the same nickname. Instead, you can enter "ping_to_@targets@" in the nickname text box. The Inca Agent will expand this reference in parallel with the reference in the host argument, so your three series will have the nicknames ping_to_blue, ping_to_green, and ping_to_red, respectively.

5.8. Series Comparison and Notification

For a particular series, the Inca system by default reports only whether or not the series reporter was able to execute successfully--whether a version reporter was able to determine a package version, a unit reporter was able to run a program, etc. Using Inca's comparison and notification feature, you can refine a series to define success more precisely and to receive notification from Inca when a series reporter detects a problem. The bottom two text boxes of the series edit dialog provide access to Inca's comparison and notification feature.

The comparison expression can test the content of the report body, the content of the report error message, or the value of any symbols defined in the report body by <ID> tags. The expression may use any of the boolean operators <, <=, >, >=, ==, and !=, plus perl's pattern match (=~) and mismatch (!~) operators. One simple test would be "body =~ /./", which would test whether the report body contained any characters. Tests can be joined together by the && and || operators. Using these, you could ignore an expected, minor error with the test "body =~ /./ || errorMessage == 'Try again later'".

As mentioned above, you can include symbols defined in the report body in your tests. The Inca system uses the content of any subsequent tag as the symbol value. For example, the body of the output of the gcc version reporter might be

  <body>
    <package>
      <ID>gcc</ID>
      <version>3.1</version>
    </package>
  </body>
  

Here, Inca will use "3.1" as the value of the symbol "gcc". With this output, the comparison test "gcc >= 3.0" would succeed, while the comparison "gcc == 3.0" would fail. If the report body contains an <ID> tag with no subsequent tag, the value of the symbol is defined to be "".

The image below illustrates how a comparison for subpackage versions would be configured.

6.1. Default Data Consumer

The default data consumer is a Jetty deployed WAR file ($INCA_DIST/etc/inca-consumers.war) that contains a set of JSP pages along with their associated files and stylesheets. Currently the WAR file cannot be deployed outside of the inca consumer server (e.g. in tomcat). The WAR's index.jsp page (http://localhost:8080/index.jsp) allows its user to choose "suiteName" and "resourceID" parameters for a second JSP page called xslt.jsp. The xslt.jsp script retrieves XML (partly from the second pre-defined query shown above) and formats it with an XSL stylesheet if the script is passed the name of a stylesheet as an input parameter. The default data consumer redirects to the xslt.jsp script and adds an input parameter with an XSL stylesheet so the result is formatted html (i.e. index.jsp redirects to something like http://localhost:8080/inca/xslt.jsp?suiteName=sampleSuite&resourceID=defaultGrid&xmlFile=swStack.xml&xsl=default.xsl).

To view the XML that is retrieved and formatted by the xslt.jsp script, remove its XSL parameter. For example, http://localhost:8080/inca/xslt.jsp?suiteName=sampleSuite&resourceID=defaultGrid&xmlFile=swStack.xml would produce something similar to:

1. <all2allSummaries> (cross-site test results calculated by the consumer):

   The default installation doesn't include cross-site tests; this section will be empty unless the Inca admin creates all2all series in incat. Cross-site, or "all to all", tests determine whether all resources in a Grid can reach all other resources (e.g. via gsissh, gram, gridftp). To be included in cross-site test calculation, a series must be assigned a nickname like "all2all:x_to_y" in incat. Cross-site failures are calculated differently than regular failures. For example, resource A will not be assigned a failure trying to reach resource B if all other resources trying to reach resource B also fail (i.e. there is a problem with resource B not resource A). Section 5.7.1 describes how to configure all2all tests in incat.

   <all2allSummaries xmlns="http://inca.sdsc.edu/dataModel/all2all_2.0"> <resources xmlns=""> <resource> <name>localResource</name> <testSummaries> <testSummary> <name>gridftp</name> <numSuccesses>15</numSuccesses> <numAtFaultFailures>0</numAtFaultFailures> <numNotAtFaultFailures>1</numNotAtFaultFailures> <failures/> </testSummary> <testSummary> <name>gram</name> <numSuccesses>13</numSuccesses> <numAtFaultFailures>1</numAtFaultFailures> <numNotAtFaultFailures>0</numNotAtFaultFailures> <failures> <failure> <nickname>all2all:gram_to_localResource</nickname> <instanceId>239352</instanceId> <seriesConfigId>172057</seriesConfigId> </failure> </failures> </testSummary> </testSummaries> </resource> </resources> </all2allSummaries>

2. <suite> (from xslt.jsp "suiteName" parameter):

   Array of report summaries for the suite. This part of the XML is retrieved from the pre-defined depot query that takes a suite name and returns summaries for the latest series instance in that suite.

   <suite> <reportSummary> <hostname>host1.name</hostname> <uri>http://repository/globus.unit.xio</uri> <nickname>gt4-xio</nickname> <seriesConfigId>115446</seriesConfigId> <instanceId>118115</instanceId> <gmt>2006-11-16T23:49:49.000-08:00</gmt> <body/> </reportSummary> <reportSummary> <hostname>host2.name</hostname> <uri>http://repository/globus.unit.xio</uri> <nickname>gt4-xio</nickname> <seriesConfigId>115466</seriesConfigId> <instanceId>219103</instanceId> <gmt>2006-12-15T01:31:53.000-08:00</gmt> <body> <unitTest> <ID>xioTest</ID> </unitTest> </body> </reportSummary> </suite>

3. <resourceConfig> (from xslt.jsp "resourceID" parameter):

   Array of all resources within a given resource group and their macros. This part of the XML is retrieved from the agent.

   <resourceConfig> <resources> <resource> <name>localResource</name> <macros> <macro> <name>__regexp__</name> <value>host.sitea.org</value> </macro> </macros> </resource> </resources> </resourceConfig>

4. extra xml (from xslt.jsp "xmlFile" parameter):

   XML from the file passed as the xslt.jsp xmlFile parameter. The default file is $INCA_DIST/etc/common/swStack.xml, but any XML file in the $INCA_DIST/etc/common directory can be passed as the xslt.jsp xmlFile parameter and it will automatically be picked up by the data consumer.

   <stack> <id>Software and Services</id> <category> <id>Math Libraries</id> <package> <id>globus</id> <version>4.0.1</version> <tests> <version> <id>gt4-version</id> </version> <unitalias> <id>gt4-xio</id> </unitalias> <unitalias> <id>all2all:gram_to_localResource</id> </unitalias> </tests> </package> </category> </stack>

To change the XML to HTML transformation, either edit the default XSL stylesheet ($INCA_DIST/etc/default.xsl for the summary page or $INCA_DIST/etc/instance.xsl for the report detail pages), or pass another XSL file in the $INCA_DIST/etc directory as the xslt.jsp "xsl" parameter (e.g. $INCA_DIST/etc/swStack.xsl). [ xsl tutorial ]

Change default CSS (Cascading Style Sheet) properties such as colors and fonts by editing the $INCA_DIST/var/jetty/webapp/css/inca.css file. [ css tutorial ]

6.2. Non-default Data Consumer Installation

You can install the data consumer in a non-default location (e.g. on a machine where the depot and agent are not running) if you:

• Copy the incaInstall.sh script to the machine where the consumer will run.

  % wget http://inca.sdsc.edu/releases/2.03/incaInstall.sh

• Install consumer on the new machine:

  % ./incaInstall.sh $INCA_DIST consumers

• Copy the consumer key, certificate, and trusted directory from the machine where the agent/depot are running (orig.machine) to the new machine:

  % scp orig.machine:$ORIG_INCA_DIST/etc/consumerkey.pem $INCA_DIST/etc/; \ scp orig.machine:$ORIG_INCA_DIST/etc/consumercert.pem $INCA_DIST/etc/; scp "orig.machine:$ORIG_INCA_DIST/etc/trusted/*" $INCA_DIST/etc/trusted/;

• Edit the $INCA_DIST/etc/common/inca.properties local file and specify the full hostname of the machine where the agent and depot are running:

  114 inca.consumer.agent=incas://agent.hostname:6323 ... 128 inca.consumer.depot=incas://depot.hostname:6324

• Start the consumer component on the new machine:

  % cd $INCA_DIST; ./bin/inca start consumer

7.1. Executing Reporters

Because they are executables, Inca reporters are independent of the rest of the Inca system. Reporters can be executed manually from a command line or automatically as part of an Inca installation. Incorporating your own reporters into a running Inca installation requires only writing the reporters (Section 7.2), including them in a repository (Section 7.3), and configuring the repository's series using incat (Section 5). Most developers will execute reporters from the command line before adding them to their Inca installation. After installing Inca, you can try executing some of the reporters that come with the distribution from the command line:

% cd $INCA_DIST/Inca-Reporter-*/bin % setenv PERL5LIB ../lib % ./cluster.compiler.gcc.version

You should now see XML output like that in Section 7.2.2.

All Inca reporters must support the command line arguments listed in the table below. In addition, a reporter may support additional command line arguments specific to that reporter's task.

Executing a reporter using different arguments:

% ./cluster.compiler.gcc.version -log=3 % ./cluster.compiler.gcc.version -help=yes -verbose=0 % ./cluster.compiler.gcc.version -version=yes

7.2. Writing Reporters

Reporters can be written in any language as long as they output XML according to the schema described in Section 7.2.1. New reporter developers may choose to write reporters in Perl since the Inca distribution includes sample Perl reporters and API modules (Section 7.2.3) for printing XML according to our schema.

<?xml version='1.0'?>
<inca:report xmlns:inca='http://inca.sdsc.edu/dataModel/report_2.1'>
  <gmt>2006-11-17T17:35:40Z</gmt>
  <hostname>jhayes-Computer.local</hostname>
  <name>cluster.compiler.gcc.version</name>
  <version>2</version>
  <workingDir>/Users/jhayes/Inca/subversion/inca/trunk/devel/reporters/bin</workingDir>
  <reporterPath>cluster.compiler.gcc.version</reporterPath>
  <args>
    <arg>
      <name>help</name>
      <value>no</value>
    </arg>
    <arg>
      <name>log</name>
      <value>0</value>
    </arg>
    <arg>
      <name>verbose</name>
      <value>1</value>
    </arg>
    <arg>
      <name>version</name>
      <value>no</value>
    </arg>
  </args>
  <body>
    <package>
      <ID>gcc</ID>
      <version>3.3</version>
    </package>
  </body>
  <exitStatus>
    <completed>true</completed>
  </exitStatus>
</inca:report>

7.3. Reporter Repositories

The Inca system retrieves reporters from external collections called repositories. A reporter repository is simply a file directory, accessed via a file: or http: URL, that contains a catalog file named Packages.gz. This gzipped file includes a sequence of name:value attribute pairs for every reporter and support package in the repository; blank lines separate the attributes for different reporters. For example, here is a portion of the Packages.gz file for the Inca standard reporter repository.

arguments: help no|yes no;log [012345]|debug|error|info|system|warn 0;verbose [0
12] 1;version no|yes no
dependencies: Inca::Reporter;Inca::Reporter::Version
description: Reports the version of tgusage
file: cluster.accounting.tgusage.version
name: cluster.accounting.tgusage.version
url: http://www.teragrid.org
version: 2

arguments: help no|yes no;log [012345]|debug|error|info|system|warn 0;verbose [0
12] 1;version no|yes no
dependencies: Inca::Reporter;Inca::Reporter::SimpleUnit
description: ant hello world test
file: cluster.admin.ant.unit
name: cluster.admin.ant.unit
version: 3

arguments: help no|yes no;log [012345]|debug|error|info|system|warn 0;verbose [0
12] 1;version no|yes no
dependencies: Inca::Reporter;Inca::Reporter::Version
description: Reports the version of Apache Ant
file: cluster.admin.ant.version
name: cluster.admin.ant.version
version: 2

Of the attributes shown, only file and name are required. The file attribute gives the relative path to the reporter file, and the name attribute specifies the unique package name of the reporter. If the reporter requires support packages to execute, it should include a dependencies attribute with a semicolon-separated list of package names. The incat administration tool uses the Packages.gz file's arguments and description attributes as part of its series edit dialog. The value of the arguments attribute is a semicolon-separated list giving the name, value pattern, and default value, if any, for each supported command-line argument.

To create a local repository for your own reporters, you only need to collect them into a directory and create a Packages.gz in that directory. The default Inca installation has a Packages.gz file in $INCA_DIST/Inca-Reporter-* that can be added in incat. Inca also supplies a web accessible repository that can be added in incat as "http://inca.sdsc.edu/repository/latest/".

The Inca distribution includes a perl script, incpack, that can create Packages.gz for you. Simply run incpack with a list of reporters that you want to include in Packages.gz, e.g.,

perl incpack jade.version f77.unit vim.version

incpack runs each of the listed reporters with --help=yes --verbose=1 to extract a standard set of attributes. If your reporters use the Inca reporter perl modules, you might need to run incpack with a -I switch to specify the location of the Inca perl library, like this.

perl incpack -I ${INCA_DIST}/lib jade.version f77.unit vim.version

7.4. Updating Reporter Repositories

The Inca agent will detect changes to your reporter repository and automatically send changes to the appropriate reporter managers if you:

1. update the reporter version number (ie. change a line like "version => 1" to "version => 2" in the body of the reporter)

2. make sure the reporter permissions are set so the agent can fetch the reporter (755 is the standard reporter permission)

3. update your Packages.gz file using incpack. The command will be something like:

   % cd $INCA_DIST/Inca-Reporter-*; ./sbin/incpack -I lib bin/<reportername>

4. wait for the agent to deploy the new reporter automatically (it looks for new reporters every four hours by default),

   *OR*

   restart the agent,

   *OR*

   go to the reporter panel in incat and delete your repository URL and commit and then readd the repository URL and commit. Readding the repository URL will force the agent to send out the new reporters. This option is usually less disruptive than restarting the agent.

If the revised reporter still isn't deployed, look for any errors in the $INCA_DIST/var/agent.log that indicate the agent was unable to fetch the reporter or skipped over updating it. Make sure there is an active series that uses the reporter with "use latest version" checked on the resource your intend it to run on incat. Look for $INCA_DIST/var/repository/repository.xml entries for the reporter with "<latestVersion>false</latestVersion>" (should be "<latestVersion>true</latestVersion>" to get the updated reporters).

12.1. Inca Component Options

Each inca component has a set of options that can be set in either the $INCA_DIST/etc/common/inca.properties file or from the command line. The inca.properties file has a list of name value pairs of the format "inca.component.property=value". For example, to start the consumer on port 8082 instead of 8080 and enter the password on the command line rather than get it from standard in, you could:

1. edit $INCA_DIST/etc/common/inca.properties and replace:

   • "#inca.consumer.port=8080" with "inca.consumer.port=8082"

   • "inca.consumer.password=stdin:password>" with "inca.consumer.password=pass:<password>" (where <password> is the password set with the createauth command)

   execute:

   % cd $INCA_DIST; ./bin/inca start consumer

2. OR execute the following command:

   % cd $INCA_DIST; ./bin/inca start consumer -p 8082 -P pass:<password>

Man pages with component options are described in Section 13.

Note: if you have more than 5 reporter managers running, increase the number of agent and depot threads in the inca.properties file to be 10 more than the number of reporter managers. For example, if running 15 reporter managers edit the inca.properties file as follows:

31 # Maximum number of threads running on the agent 32 inca.agent.numthreads=25 ... 82 # Maximum number of threads running on the depot 83 inca.depot.numthreads=25

12.2. Depot Database Configuration

The Inca depot uses Hibernate to interface to a relational database backend for storing reports and incat configuration. By default, the Inca depot uses Hibernate's HSQL database but can be configured to use any Hibernate supported database. We have tested the Inca depot with PostgreSQL and Oracle.

Steps for using a depot database other than HSQL are as follows:

1. Stop the depot

   % cd $INCA_DIST; ./bin/inca stop depot

2. Edit $INCA_DIST/etc/hibernate.properties

   • Comment out the first 5 lines which specifies for hibernate to use hsql as its backend database:

     1 #hibernate.dialect=org.hibernate.dialect.HSQLDialect 2 #hibernate.connection.driver_class=org.hsqldb.jdbcDriver 3 #hibernate.connection.url=jdbc:hsqldb:test 4 #hibernate.connection.username=sa 5 #hibernate.connection.password=

   • Uncomment the block which specifies for hibernate to use your database (i.e., for PostgreSQL uncomment 8-13, for MySQL uncomment 17-21, for Oracle uncomment 24-28).

   • Change the uncommented hibernate.connection.url, hibernate.connection.username and hibernate.connection.password property values to be the host/db name, login username and password for your database.

3. Put JDBC drivers for your database in the $INCA_DIST/lib directory. Driver download locations: PostgreSQL, MySQL, Oracle

4. Initialize the depot (set up the Inca tables):

   % cd $INCA_DIST; ./bin/inca depot -d

   You should see something like:

   Initializing c3p0 pool... ... Database Initialization Completed

5. Start the depot

   % ./bin/inca start depot

12.3. Manual Access Method

A resource administrator may prefer to have local control of the reporter manager running on their resources rather than be controlled centrally by the Inca agent (similar to Inca 1). In this case, an Inca administrator can add the resource using the access method 'manual' and changes to the configuration will be emailed to the resource administrator. The following steps will need to be taken by the Inca administrator and resource administrator:

Inca Administrator

Resource Administrator

1. The Inca administrator will add the specified resource within incat and choose 'manual' as below:

   Figure 20. Add Resource Screen

   

   The "Resource Admin Email" field should be filled with the email address of the resource administrator of the manual resource. When suite changes are committed in incat, the agent will email the suite changes to the resource administrator. Select "Agent->Commit" from the menu to commit the changes. A set of credentials (e.g., rmcert.pem, rmkey.pem, trusted) will be generated in $INCA_DIST/var/rm/<resource name>/ such as below:

   % ls var/rm/manualResource/ catalog.xml rmcert.pem rmkey.pem trusted

   These credentials will need to be given to the resource administrator in order to send reports to the depot. The rmkey.pem will be encrypted with the same password as the agent's private key. It is recommended that you change the password before giving them to the resource system administrator using the following commands:

   % openssl rsa -in rmkey.pem -out rmkey.pem2 -des read RSA key Enter PEM pass phrase: agent-passphrase writing RSA key Enter PEM pass phrase: new-passphrase Verifying password - Enter PEM pass phrase: new-passphrase % mv rmkey.pem2 rmkey.pem

   Give the reporter manager credentials to the resource system administrator and instruct them to follow steps 2 and 3.

2. The resource administrator will install the reporter manager distribution on their resource using the following steps:

   1. Create an installation directory for the reporter manager (e.g., $RM_INSTALL_DIR) and change to that directory.

   2. Download reporter manager tarball

   3. Download reporter manager build script

   4. Contact your Inca administrator for a set of credentials. You should receive files called rmcert.pem, rmkey.pem, and trusted*.pem. Place them in $RM_INSTALL_DIR as is. At this point the directory on the remote machine should look something like this:

      % ls Inca-ReporterManager.tar.gz rmcert.pem trusted0.pem buildRM.sh rmkey.pem trusted1.pem

   5. Run 'bash buildRM.sh -u false $RM_INSTALL_DIR Inca-ReporterManager.tar.gz'. When completed, the installation directory should looks something like this:

      % ls $RM_INSTALL_DIR Inca-ReporterManager-8.6279 build.log lib var Inca-ReporterManager.tar buildRM.sh man bin etc sbin % ls $RM_INSTALL_DIR/etc/ common log4j.properties rmcert.pem rmkey.pem trusted

      Next, install the initial set of reporters and their libraries. Download Inca reporters tarball. Then unpack the Inca-Reporters.tar.gz tarball and install into the reporter manager directory as follows:

      % cd $RM_INSTALL_DIR/var % tar zxvf ../Inca-Reporter.tar.gz % cd Inca-Reporter-* % perl Makefile.PL PREFIX=${RM_INSTALL_DIR}/var/reporter-packages INSTALLDIRS=perl LIB=${RM_INSTALL_DIR}/var/reporter-packages/lib/perl INSTALLSCRIPT=${RM_INSTALL_DIR}/var/reporter-packages/bin INSTALLMAN1DIR=${RM_INSTALL_DIR}/var/reporter-packages/man/man1 INSTALLMAN3DIR=${RM_INSTALL_DIR}/var/reporter-packages/man/man3 % make % make install

3. The suite and any changes to that suite are emailed to the resource administrator specified by the Inca administrator in Step 1. For example,

   % mail Mail version 8.1 6/6/93. Type ? for help. "/var/mail/ssmallen": 1 message 1 new >N 1 inca@sdsc.edu Tue Jan 30 15:01 118/3642 "[inca notification] change" & t 1 Message 1: From inca@rocks-101.sdsc.edu Tue Jan 30 15:01:03 2007 To: inca@sdsc.edu Subject: [inca notification] change to suite inca://localhost:6323/sampleSuite for resource 'manualResource' Date: Tue, 30 Jan 2007 15:01:01 -0800 (PST) <suite xmlns="http://inca.sdsc.edu/dataModel/suite_2.0"> <seriesConfigs xmlns=""> <seriesConfig> ...

   Save the message to a file called $RM_INSTALL_DIR/suite.xml and edit out the email headers until just the xml remains. E.g.,

   <suite xmlns="http://inca.sdsc.edu/dataModel/suite_2.0"> <seriesConfigs xmlns=""> <seriesConfig> ... </suite>

   Next, create a repository catalog file called $RM_INSTALL_DIR/var/reporter-packages/repository.xml to tell the reporter manager where the reporters are installed (relative to $RM_INSTALL_DIR/var/reporter-packages). The repository.xml will need to contain every reporter that is listed in suite.xml. Currently, there are 2 types of entries in the catalog: reporters and perl libraries. Each package has 4 tags: dependency, name, path, and version. You can copy the default repository catalog with the following command, but will need to update it with any non-default reporters configured in the suite.xml file:

   % cp $RM_INSTALL_DIR/var/Inca-Reporter-*/etc/common/sampleRepository.xml $RM_INSTALL_DIR/var/reporter-packages/repository.xml

   Finally, you can start up the reporter manager using the following command-line (replace "depotHost" with the hostname where the depot is running):

   % cd $RM_INSTALL_DIR; ./sbin/inca reporter-manager -d incas://depotHost:6324 -c etc/rmcert.pem -k etc/rmkey.pem -t etc/trusted -e bin/inca-null-reporter -r var/reporter-packages -R sbin/reporter-instance-manager -v var -w 1 -i manualResource -s suite.xml -L DEBUG -l var/reporter-manager.log -P true

   Enter the password for the reporter manager key. Check to make sure the reporter manager is running by doing a "ps | grep reporter-manager" and make sure there aren't errors by doing a "grep ERROR $RM_INSTALL_DIR/var/*".

   To stop the reporter manager at any time, type

   % ./sbin/inca stop reporter-manager

   Make sure all reporter-manager ps are stopped

   % ps | grep manager

   Notes about email notification:

   • The resource administrator will need to edit suite.xml with any changes that are received by email, edit the repository.xml with any new reporters, and then restart the reporter manager.

   • The <action> tag in the emailed change indicates how to edit suite.xml. For example, <action>add</action> would be an addition to the existing suite.

   • If a manual reporter manager has multiple suites, the <seriesConfigs xmlns=""> emailed in each suite can be combined and put into a single suite.xml document beginning with <suite xmlns="http://inca.sdsc.edu/dataModel/suite_2.0">.

   • Each time the agent is restarted the manual reporter manager administrator will receive an email for each suite that the agent would otherwise send directly to the reporter manager. These emails do not necessarily contain changes to the suite(s).

12.4. Manual Run Now

Oftentimes resource or system administrators will want to show that a problem has been resolved by independently executing inca tests before they are scheduled to run so that their results appear on status pages. Rather than granting resource administrators full privileges just to use incat's "run now" button, the inca administrator can provide resource administrators with a "manual run now" option - a command line script to execute tests and send results to the depot.

12.5. Source Distributions

Source distributions of the Inca components are also available. The following table lists the Inca component source distributions and shows how to build each of them. Note, that Apache Ant is needed for the Inca components implemented in Java.

13.1. Depot

% bin/inca help depot java edu.sdsc.inca.Depot P|password str Specify how to obtain encryption password V|version null Display program version a|auth boolean Authenticated (secure) connection? c|cert path Path to the authentication certificate d|dbinit null init depot DB tables h|help null Print help/usage h|hostname str Hostname the server should provide to clients i|init path Path to properties file k|key path Path to the authentication key l|logfile str Route log messages to a file n|numthreads int # threads in worker pool p|port int Server listening port r|remove null remove depot DB tables t|trusted path Path to authentication trusted certificate dir v|var path Absolute path to server temp dir

13.2. Agent

% bin/inca help agent java edu.sdsc.inca.Agent C|check str check the reporter manager stage on resources D|depot str Depot specification; host:port P|password str Specify how to obtain encryption password R|refreshPkgs int refresh period for checking for package updates S|server str Server specification; host:port S|startAttempt int period between re-start attempts of the manager V|version null Display program version a|auth boolean Authenticated (secure) connection? b|buildscript str path to reporter manager build script c|cert path Path to the authentication certificate e|email str email to send notifications of manager restarts h|help null Print help/usage h|hostname str Hostname the server should provide to clients i|init path Path to properties file k|key path Path to the authentication key l|logfile str Route log messages to a file n|numthreads int # threads in worker pool p|port int Server listening port r|rmdist str path to reporter manager tarball distribution s|stayAlive int period between stay alive pings of the manager t|trusted path Path to authentication trusted certificate dir u|upgrade str upgrade the reporter manager install on resources v|var path Absolute path to server temp dir

13.3. Reporter Manager

% sbin/inca help reporter-manager Usage: reporter-manager [-a|-s] [options] Options: a|--agent A string containing the URI to the Reporter Agent process that will be responsible for the reporter manager. Either this option or -s must be specified. Currently accepted URIs include: incas://host:port inca://host:port -c|--cert A path to a valid certificate file [default: none] -d|--depot A string containing the URI of a depot to send its reporter data to. Currently accepted URIs include: incas://host:port inca://host:port file://path This option can be specified more than once. The report will be sent to the first specified depot. If the first depot is unreacheable, the next depots in the list will be tried. -e|--error-reporter A string containing a path to the error reporter. E.g., inca-null-reporter -h|--help Print help/usage information -i|-id The resource identifier supplied by the reporter agent that the reporter manager will use to identify itself back to the reporter agent. -k|--key A path to a valid key file [default: none] -l|--logfile A string containing a path to the file where the log messages can be stored. If not specified, log messages will be printed to the console. -L|--level A string containing the log message level (i.e., print statements of this level and higher). [default: INFO] -P|--passphrase Read a passphrase for key from stdin -r|--reporter-cache A string containing the path to the local cache of reporters. -R|--rim A string containing a path to the reporter-instance-manager script. If not specified, this script will look into the directory where itself is located. -s|--suite A string containing a path to the Inca suite file containing the reporters to be executed. -t|--trusted A path to either a directory or file of trusted certificates [default: none] -v|--var A string containing a path to a temporary file space that Inca can use while executing reporters -w|--wait A positive integer indicating the period in seconds of which to check the reporter for a timeout [default: 2]

13.4. Consumer

% bin/inca help consumer java edu.sdsc.inca.Consumer P|password str Specify how to obtain encryption password V|version null Display program version a|agent str URI to the Inca agent a|auth boolean Authenticated (secure) connection? c|cert path Path to the authentication certificate d|depot str URI to the Inca depot h|help null Print help/usage i|init path Path to properties file k|key path Path to the authentication key l|logfile str Route log messages to a file m|maxWait int Max wait time a JSP tag should wait on a cached item p|port int Server listening port r|reload int Reload period for cached objects (e.g., suites) t|trusted path Path to authentication trusted certificate dir v|var path Path to temporary directory w|webapp str Path to consumer war file

13.5. Incat

% bin/inca help incat java incat A|agent str Agent specification; host:port P|password str Specify how to obtain encryption password V|version null Display program version a|auth boolean Authenticated (secure) connection? c|cert path Path to the authentication certificate f|file path Inca installation configuration file path h|help null Print help/usage i|init path Path to properties file k|key path Path to the authentication key l|logfile str Route log messages to a file t|trusted path Path to authentication trusted certificate dir

13.6. Inca Web Services

% ./bin/inca help incaws incaws [opts] depot agent --auth=yes/no --cert=path --help=yes/no --init=path --key=path --logfile=path --password=str --port=int --trusted=path --version=yes/no