11. Advanced Configuration

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.