Inca 2.1 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 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. 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 Web ARchive (WAR) file that contains a collection of JavaServer Pages (JSP) and their associated files. The WAR file is initially installed as $INCA_DIST/webapps/inca.war and is deployed with Jetty when the consumer is started (e.g. ./bin/inca start consumer). The default consumer creates a Jetty directory like $INCA_DIST/var/jetty*/webapp for each WAR file in $INCA_DIST/webapps - custom WAR files can be dropped into the $INCA_DIST/webapps directory and deployed by restarting the consumer. Currently Inca WAR files cannot be deployed outside of the Inca consumer server (e.g. in Apache Tomcat). The consumer will start on port 8080 unless the $INCA_DIST/etc/jetty.xml is edited as described in Section 6.4.

There are three main JSP contained in the inca.war:

1. index.jsp:

   Lists an installation's configured suites and resource names in an HTML form whose action is to display results for the selected suite and resource. The consumer initially redirects to this page (http://localhost:8080/inca/index.jsp).

   The index.jsp uses JSP tag libraries to retrieve current suite configuration from the depot's queryGuids() function and cached resource configuration information from the agent's getConfig() function.

   The XML returned by the depot and agent functions is transformed into an HTML form for selecting a suite and resource to view results for. The stylesheet that does the XML to HTML transformation is $INCA_DIST/etc/index.xsl - if it does not exist the JSP will display the depot/agent XML.

2. config.jsp:

   Prints description of deployed suites and series. This page is linked at the bottom of index.jsp (http://localhost:8080/inca/config.jsp?xsl=config.xsl).

   The config.jsp uses JSP tag libraries to retrieve current catalog configuration from the agent's getCatalogAsXml() function and cached suite configuration infomation from the agent's getConfig() function.

   The XML returned by the agent functions is transformed into HTML by the stylesheet passed via the "xsl" parameter. By default the "xsl" parameter is "config.xsl", which translates to the $INCA_DIST/etc/config.xsl file, but it can be set to any XSL file in $INCA_DIST/etc. If the "xsl" parameter is not passed to the script (http://localhost:8080/inca/config.jsp), the XML returned from the agent functions is displayed.

3. xslt.jsp:

   Displays results for a set of suites or reporter details. This page is the action of the index.jsp form to display a single suite's results. (http://localhost:8080/inca/xslt.jsp?suiteName=sampleSuite&resourceID=defaultGrid&xsl=default.xsl).

   • Suite results:

     In order to display results for a set of suites, the xslt.jsp requires the "suiteName" and "resourceID" parameters. The JSP uses these parameters to retrieve cached results from the depot. The "suiteName" and "resourceID" parameters may contain a single value (e.g. "suiteName=sampleSuite&resourceID=defaultGrid") or multiple comma-separated values (e.g. "suiteName=sampleSuite,myNewSuite&resourceID=defaultGrid,newSuiteResources"). If multiple suites and resources are used, the JSP will return results for each suite/resource pair in the order they are entered. If multiple suites and a single resource are used, the JSP will return results for each suite using the same resource.

     An optional "xmlFile" parameter (e.g. "xmlFile=swStack.xml") adds the content of an XML file in $INCA_DIST/etc/common to the cached depot results. This can be useful for advanced data display. An example stylesheet to use with this parameter is located in $INCA_DIST/etc/swStack.xsl (e.g. "xmlFile=swStack.xml&xsl=swStack.xsl").

     The XML returned from the depot cache and optional "xmlFile" parameter is transformed into HTML by the stylesheet passed via the "xsl" parameter. By default the "xsl" parameter is "default.xsl", which translates to the $INCA_DIST/etc/default.xsl file, but it can be set to any XSL file in $INCA_DIST/etc. If the "xsl" parameter is not set (http://localhost:8080/inca/xslt.jsp?suiteName=sampleSuite&resourceID=defaultGrid), the XML returned from the depot cache and "xmlFile" parameter is displayed:

     • <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>

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

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

       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>

   • Reporter detail results:

     In order to display reporter detail results, the xslt.jsp requires a "configID" parameter for the series. The JSP uses this parameter to retrieve reporter results from the depot. If an "instanceID" parameter is not also supplied, the JSP returns a history of XML results for the series. If an "instanceID" parameter is supplied, the JSP returns XML results for a the specified instance of the series.

     The XML reporter results are transformed into HTML by the stylesheet passed via the "xsl" parameter. By default the "xsl" parameter is "instance.xsl", which translates to the $INCA_DIST/etc/instance.xsl file, but it can be set to any XSL file in $INCA_DIST/etc. If the "xsl" parameter is not set, the XML reporter results are displayed:

     <reportDetails> <suiteId>1</suiteId> <seriesConfigId>5</seriesConfigId> <seriesId>5</seriesId> <reportId>1</reportId> <instanceId>73</instanceId> <seriesConfig> <series> ... </series> <nickname>java_hello_world</nickname> <resourceHostname>localResource</resourceHostname> <schedule> ... </schedule> <action>add</action> </seriesConfig> <report> ... </report> <sysusage> ... </sysusage> <stderr/> </reportDetails>

6.2. Changing the Look

6.3. 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.1/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.4. 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.5. 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.6. 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.5.

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

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. (optional)To customize the email message that gets sent to the resource administrators, edit the text in $INCA_DIST/etc/manualEmail.txt.

2. 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 3 and 4.

3. 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). Download the reporter manager tarball and build script:

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

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

   3. 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 % ls $RM_INSTALL_DIR/etc common log4j.properties rmcert.pem rmkey.pem trusted

      Install the default set of reporters and their libraries:

      % cd $RM_INSTALL_DIR; wget http://inca.sdsc.edu/releases/2.1/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

4. The suite and any changes to that suite are emailed to the resource administrator specified by the Inca administrator in Step 2. 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 2:

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

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.

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.