Inca 2.2 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.

The 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 (for a description of access methods see Section 5.5). 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 gcc_hello_world 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. The Agent must have ssh key access to 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 Clone 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" in the macro value edit box, then use the "Add" button to add "green" and "red" as the second and third values of the macro. Afterwards, 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.

By default, emails sent by Inca include a short description of the series, resource, and comparison. You can customize the content and subject of the emails by setting the depot.notification property in your $INCA_DIST/etc/common/inca.properties file before starting the depot. The value of this property can mix literal text you want included in the email with macro-like references to information about the series and reporter execution. For example, the property setting that generates the default email format is:

inca.depot.notification=\ SUBJECT=Inca Notification: @nickname@ on @hostname@ @result@ED\n \ The following Inca test has @result@ED:\n\n \ RAN AT: @collected@\n\n \ RAN ON: @hostname@\n\n \ TEST: @reporterPath@\n\n \ INPUT PARAMETERS: @args@\n\n \ LOGGED COMMANDS: @log@\n\n \ ERROR MESSAGE: @errorMessage@\n\n \ STANDARD ERROR: @stderr@\n\n \ \n\n \ details at http://localhost:8080/inca/xslt.jsp?xsl=instance.xsl&instanceID=@instanceId@&configID=@configId@\n\n

As shown here, multi-line emails are specified by including newline markers ("\n") in the property value. Inca uses the line in the value that contains "SUBJECT=" as the email subject; remaining lines are the email body. Any lines that contain an undefined macro value are removed, so, in the above, the final line would not appear if the reporter execution didn't produce an error message.

These are the macro names that Inca defines for your use in constructing notification emails:

6.1. Current Data Pages

The default page header navigation contains links to tabular and map view result summaries for the sample suite. To add other current pages under this heading (e.g. result summary tables for other suites, customize the header.xsl file as described in Section 6.5.3.

          http://yourhost:8080/inca/xslt.jsp?xsl=google.xsl&xmlFile=google.xml&suiteName=sampleSuite&resourceID=defaultGrid
        

          ...
          <!-- Google key for your Inca server.  Go to the following website and put
          http://yourservername:8080 in the "My web site URL" textbox at:
          http://www.google.com/apis/maps/signup.html -->
          <key>Insert key here</key>
          ...
        

          ...
          <!-- Google key for your Inca server.  Go to the following website and put
          http://yourservername:8080 in the "My web site URL" textbox at:
          http://www.google.com/apis/maps/signup.html -->
          <key>ABQIAAAA_4IHDoSvxQqISMa1RKFLQBSSlCzupJMr-Xoh__duR37DAX9UVBRVn9-X9_4ILpmvilr4hN-QZU8pNQ</key>
          ...
        

6.2. Historical Data Pages

All reporter data collected by Inca is stored in the depot. The depot can then be queried to produce graphs of historical information. Inca's default data consumer uses Cewolf, a JSP tag library for graphing based on JFreeChart. The default consumer includes a basic graph of the historical pass/fail status of reporter series and a graph of error message counts if there are any reporter errors. The pass/fail status is either the comparitor status (if the series has a comparitor) or the reporter's exit status.

The section for historical data in the default page header is a form to select series from the sampleSuite suite. To link other historical pages under this heading (e.g. forms to select series from other suites, customize the header.xsl file as described in Section 6.5.3.

If graph.xsl is used as the xsl parameter for the xslt.jsp script that displays suite results, a form will be generated to select suite series to graph. For example, http://localhost:8080/inca/xslt.jsp?xsl=graph.xsl&suiteName=sampleSuite&resourceID=defaultGrid will generate:

After selecting the "vtk-nvgl_version" series and clicking on the "graph" button in the form above, a graph page is shown with an XY plot of the pass/fail status of the selected series, a series pass/fail summary table, a bar graph of error message frequency (if the selected series have errors), a summary table of error messages, and a form to customize the graph further (as in the image below). This graph page is generated by the graph.jsp script with Cewolf tags.

To improve query speed, only two weeks of data are returned initially. To query for all results, clear the "start date" field in the "customize graph" section and click "re-graph". Also to improve graph generate speed, data point mouseover text and links to report details are turned off for the pass/fail graph. The data points can be made interactive by choosing "show mouseovers/hyperlinks" in the "customize graph" section and clicking on "re-graph". Clicking on interactive data points will lead to report details pages, mousing over them will show collection times and any error messages.

Multiple series can also be graphed together as in the image below. A table under each graph summarizes results for each series.

Graph pages for individual series are also linked from the report details pages.

6.3. Info Pages

Currently the only informational page is a list of all running reporters in an inca deployment. To link other informational pages under this heading, customize the header.xsl file as described in Section 6.5.3.

6.4. Description of Data Consumer Files

There are four main JSP contained in the inca.war. The JSP generally return XML from depot and agent functions and apply XSL stylesheets to display HTML. If the "xsl" parameter for the JSP is removed, the JSP prints the XML returned.

The default JSP scripts retrieve XML data from the agent and depot and then use the XSL stylesheets in $INCA_DIST/webapps/xsl are used to transform the XML into HTML. The following stylesheets are installed with the default consumer:

6.5. Changing the Look

6.6. Changing the Installation Location

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.2/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

6.7. Changing the Port

By default, the consumer is started on port 8080. To change this, edit the etc/jetty.xml file and search for 'SocketListener'. To change the port to say 8085, change the following line:

      <Set name="Port"><SystemProperty name="jetty.port" default="8080"/></Set>
    

to:

      <Set name="Port">8085</Set>
    

6.8. Enabling https

By default, the consumer is configured as an http server. To disable http and enable https, edit the jetty.xml file in $INCA_DIST/etc and

1. comment out the section "Add and configure a HTTP listener to port 8080"

2. uncomment the section "Add a HTTPS SSL listener on port 8443".

Note that the example below is to disable http and enable https. However, http and https can be enabled simultaneously if both sections are left uncommented.

      <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
      <!-- Add and configure a HTTP listener to port 8080                  -->
      <!-- The default port can be changed using: java -Djetty.port=80     -->
      <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
      <!--
      <Call name="addListener">
      <Arg>
      <New class="org.mortbay.http.SocketListener">
      <Set name="Port"><SystemProperty name="jetty.port"
      default="8080"/></Set>
      <Set name="PoolName">P1</Set>
      <Set name="MinThreads">20</Set>
      <Set name="MaxThreads">200</Set>
      <Set name="lowResources">50</Set>
      <Set name="MaxIdleTimeMs">30000</Set>
      <Set name="LowResourcePersistTimeMs">2000</Set>
      <Set name="acceptQueueSize">0</Set>
      <Set name="ConfidentialPort">8443</Set>
      <Set name="IntegralPort">8443</Set>
      </New>
      </Arg>
      </Call>
      -->


      <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
      <!-- Add a HTTPS SSL listener on port 8443                           -->
      <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
      <Call name="addListener">
      <Arg>
      <New class="org.mortbay.http.SslListener">
      <Set name="Port">8443</Set>
      <Set name="PoolName">P1</Set>
      <Set name="MaxIdleTimeMs">30000</Set>
      <Set name="lowResources">30</Set>
      <Set name="LowResourcePersistTimeMs">2000</Set>
      <Set name="Keystore">etc/consumerKeystore</Set>
      <Set name="KeyPassword">OBF:1v8w1v2h1wg01z0d1z0h1wfy1v1x1v9q</Set>
      <Set name="Password">OBF:1v8w1v2h1wg01z0d1z0h1wfy1v1x1v9q</Set>
      <Set name="HttpHandler">
      <New class="org.mortbay.http.handler.MsieSslHandler">
      <Set name="UserAgentSubString">MSIE 5</Set>
      </New>
      </Set>
      </New>
      </Arg>
      </Call>
    

Then restart the consumer.

      % ./bin/inca stop consumer; ./bin/inca start consumer
    

The https server will be on port 8443.

https://hostname:8443

By default, the https server will use the credential stored in $INCA_DIST/etc/consumerKeystore. Its DN is "cn=Inca Consumer SSL, o=SDSC, l=San Diego, st=California, c=US". If you'd like to generate a certificate with a different DN, run the keytool command as follows:

% rm -f etc/consumerKeystore; keytool -keystore etc/consumerKeystore \
      -alias jetty -genkey -keyalg RSA -dname your_DN
    

It will prompt you for a keystore password and a key password. You can either make them different or use the same one. If you use the password "consumer", no further changes are needed. Otherwise, you will have to modify <Set name="KeyPassword"> and <Set name="Password"> in the "Add a HTTPS SSL listener on port 8443" section in jetty.xml. You can either put the password in there in plain text or obfuscate it using Jetty's password utility as follows:

% java -classpath lib/org.mortbay.jetty-5.1.10.jar:lib/commons-logging-1.0.4.jar \ org.mortbay.util.Password your_password

It will output two lines such as follows:

      OBF:1v8w1v2h1wg01z0d1z0h1wfy1v1x1v9q
      MD5:1005b14bd29466723ace30d26f602f5b
    

Open etc/jetty.xml and replace the string beginning with OBF in both <Set name="KeyPassword"> and <Set name="Password"> with the string provided by Jetty's password utility:

      <Set name="KeyPassword">OBF:1v8w1v2h1wg01z0d1z0h1wfy1v1x1v9q</Set>
      <Set name="Password">OBF:1v8w1v2h1wg01z0d1z0h1wfy1v1x1v9q</Set>
    

6.9. Adding Password Protection

By default, a password is not required for a user to access the status pages served by the consumer. To require a password, edit $INCA_DIST/etc/webdefault.xml and uncomment the section "Require password authentication to access Inca status pages". Note that there are two sections with that title -- one for http and the other for https. Uncomment the appropriate section such as:

      <!-- ==================================================================== -->
      <!-- Require password authentication to access Inca status pages          -->
      <!--                        (http version)                                -->
      <!-- ==================================================================== -->
      <security-constraint>
      <web-resource-collection>
      <web-resource-name>Any User</web-resource-name>
      <url-pattern>/*</url-pattern>
      </web-resource-collection>
      <auth-constraint>
      <role-name>*</role-name>
      </auth-constraint>
      </security-constraint>

      <login-config>
      <auth-method>BASIC</auth-method>
      <realm-name>Inca Status Pages</realm-name>
      </login-config>
    

By default, the username and password for the pages will be "inca". To change this, edit $INCA_DIST/etc/realm.properties and customize the username and password for your installation. If you do not want to store the password in plain text, use Jetty's password utility described in Section 6.8.

Then restart the consumer.

% ./bin/inca stop consumer; ./bin/inca start consumer

The next time you view the status pages, you should see a login like:

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.

NOTE: Because some databases won't allow queries greater than 4kB, the XML portion of the report for logging/debugging and the error message must each be smaller than 4kB in size. The body XML can be 12kB in size because it is queried in three parts. If the report XML is greater than its limit, the depot truncates the oversized section from the beginning until it is the right size.

<?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*

   Connect to the agent in incat, select the Repositories tab, then press the Refresh button under the repository panel.

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).

11.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 agent on port 5323 instead of 6323 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.agent.port=6323" with "inca.agent.port=5323"

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

   execute:

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

2. OR execute the following command:

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

Man pages with component options are described in Section 12.

Note: To change the port of the consumer, see Section 6.7.

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

11.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

11.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. INCA ADMIN: (optional -- one time only) customize the email message that gets sent to the resource administrators by editing the text in $INCA_DIST/etc/manualEmail.txt.

2. RESOURCE ADMIN: install the reporter manager distribution on your resource using the following steps.

   1. Create an installation directory for the reporter manager (e.g., $RM_INSTALL_DIR). Download the reporter manager tarball and build script:

      % cd $RM_INSTALL_DIR; \ wget http://inca.sdsc.edu/releases/2.2/Inca-ReporterManager.tar.gz; \ wget http://inca.sdsc.edu/releases/2.2/buildRM.sh

      At this point the directory on the remote machine should look something like this:

      % ls Inca-ReporterManager.tar.gz buildRM.sh

   2. Install the reporter manager and list directories to verify files unpacked correctly:

      % bash buildRM.sh -u false $RM_INSTALL_DIR Inca-ReporterManager.tar.gz % ls $RM_INSTALL_DIR Inca-ReporterManager-9.6764 build.log lib share Inca-ReporterManager.tar buildRM.sh man var bin etc sbin

      Install the default set of reporters and their libraries:

      % cd $RM_INSTALL_DIR; wget http://inca.sdsc.edu/releases/2.2/Inca-Reporter.tar.gz % cd 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. RESOURCE ADMIN: create a set of credentials for the reporter manager (i.e., private key and certificate request) using the command below.

   % cd $RM_INSTALL_DIR; ./sbin/inca createRmCertRequest -P stdin:password:

   Enter a password for your key (to use when you start up the reporter manager). Two files will be created in $RM_INSTALL_DIR/etc: an encrypted private key called rmkey.pem and a certificate request called rmreq.pem. Email rmreq.pem to your Inca administrator and they will generate a certificate for your reporter manager.

4. INCA ADMIN: upon receiving a rmreq.pem file, generate a certificate for a reporter manager using the command below. Replace "rmreq.pem" with to the path to the rmreq.pem file that you received from the resource administrator and "rmcert-resource.pem" with the path to the reporter manager certificate that will be generated by the command.

   % cd $INCA_DIST; ./bin/inca createRmCert -P stdin:password: rmreq.pem rmcert-resource.pem

   Enter the password for the inca distribution (i.e., created in Step 4 during the initial installation process). Email the reporter manager certificate, "rmcert-resource.pem", and trusted certificate to the resource administrator. The trusted certificate is the file ending with the .0 extension in your $INCA_DIST/etc/trusted directory. For example f73fee74.0 is the trusted certificate in the following directory:

   % ls etc/trusted/ agentcert.pem f73fee74.0 rocks-101.sdsc.educert.pem

5. INCA ADMIN: 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. Make sure the "Equivalent" box is checked, otherwise the depot may discard reports with "unattached to any DB config" warnings. The new "manualResource" will also need to be added to the "defaultGrid" resource in order to run the default sampleSuite.

   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.

6. RESOURCE ADMIN: install the certificate and trusted certificate from the Inca admin in your reporter manager installation. Replace "rmcert-resource.pem" and "trusted.0" with the names of the files received from your Inca administrator.

   % cd $RM_INSTALL_DIR % cp rmcert-resource.pem $RM_INSTALL_DIR/etc/rmcert.pem % mkdir $RM_INSTALL_DIR/etc/trusted % cp trusted.0 $RM_INSTALL_DIR/etc/trusted

7. RESOURCE ADMIN: The suite and any changes to that suite are emailed to the resource administrator specified by the Inca administrator in Step 5. The changes will be attached in a file called suiteChanges.xml and the updated configuration for your resource (with the changes included) will be attached in a file called updatedSuite.xml. View the add/delete changes in suiteChange.xml. Then copy the updatedSuite.xml to a file called $RM_INSTALL_DIR/suite.xml. Figure 21 shows an example of a notification mail viewed from Apple Mail.

   Figure 21. Example of Inca notification email upon suite change

   

   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 commands below. Replace "depotHost" with the hostname where the depot is running and replace "manualResource" with the manual resource group name added in step 5:

   % cd $RM_INSTALL_DIR % ./sbin/inca reporter-manager \ -a incas://agentHost:6323 \ -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 your password>

   Command will hang until the password for the reporter manager key is entered. If the private key is not password protected, don't use the -P option in the command above. 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

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

11.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.

11.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.

12.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

12.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

12.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]

12.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 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

12.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

12.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

13.1. Log Files

The agent, depot and consumer logs are located in the $INCA_DIST/var directory. Reporter manager logs are located in each manager's install directory under the var directory (e.g. ~/incaReporterManager/var).

Logging is informational by default, but can be adjusted to be more verbose ('info' to 'debug') or less verbose ('info' to 'error') by editing the $INCA_DIST/etc/common/log4j.properties file and then restarting inca components. Note that passwords are logged when 'debug' logging is turned on. Logging for the inca components can be adjusted by editing lines 26 and 27 ("log4j.rootLogger=info, stdout" and "log4j.logger.edu.sdsc.inca=info"). To log the most verbose globus error messages change line 33 in log4j.properties from "log4j.logger.org.globus=error" to "log4j.logger.org.globus=debug".

If a reporter manager is not started on a resource after you have scheduled reporters to run there, it is likely the build on that resource failed. You can confirm by looking for "Unable to stage reporter manager to " in $INCA_DIST/var/agent.log. If found, look for errors on the resource in the 2 build log files from the reporter manager build attempt: ~/incaReporterManager/build.log and ~/incaReporterManager/Inca-ReporterManager-*/build.log. The most common build failure is a bad build of the dependency Net::SSLeay which is required for secure communication; the build for Net::SSLeay will fail if it is unable to find OpenSSL on the resource. The Perl SSL modules call the same functions as "openssl verify".

13.2. Authentication Problems

If you observe that a reporter manager on a resource is having trouble connecting to either the agent or depot, there could be a problem with either the installed SSL libraries or certificates. To test, use the inca-ping-client script installed with the reporter manager as in the example below. Replace $RM_INSTALL_DIR with the path to the directory where the reporter manager is installed. Supply the appropriate hostname and port for either the depot or agent. After pressing return, type the password for the certificates.

% cd $RM_INSTALL_DIR
% env PERL5LIB=lib/perl bin/inca-ping-client \
  -c etc/rmcert.pem \
  -k etc/rmkey.pem -P true -t etc/trusted \
  -uri incas://<agent or depot hostname>:<port>
<your password>

If there are no problems contacting either the agent or depot, the exit code will be 0 and nothing will be printed to the screen. If there is an authentication problem, the exit code will be non-zero and a message such as the following will be printed to stderr:

ERROR - Unable to create Inca::IO socket: : IO::Socket::INET configuration failed
Error contacting Inca server 'incas://rocks-101:6325' at bin/inca-ping-client line 137, <STDIN> line 1.

Please email inca@sdsc.edu if you are unable to determine the cause of the authentication problem.