11. Advanced Configuration

This section describes advanced configuration options such as installing components in non-default locations and changing other default properties.

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

Step 1: (optional -- one time only) Customize email message sent to resource administrators.
Step 4: Generate a certificate for the reporter manager.
Step 5: Add resource in incat with access method 'manual'

Resource Administrator

Step 2: Install reporter manager
Step 3: Generate private key and certificate request
Step 6: Install certificate and trusted certificate.
Step 7: Start and manually manage reporter manager

  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.4.1. Configuring the Manual Run Now Script

The instructions below need to be done *once* by the Inca administrator on each resource where the resource administrator would like to manually run tests.

  1. To allow system administrators or others to execute tests with their own password, copy the reporter manager key and cert for them and change the password. The old password is the same as the password used in the createauth step of installing inca.
    % cd $INCA_DIST/etc; cp rmkey.pem adminkey.pem
    % cp rmcert.pem admincert.pem
    % chmod 600 adminkey.pem
    % ssh-keygen -p
    
    Enter file in which the key is (/home/.ssh/id_rsa):
      /home/incaReporterManager/etc/adminkey.pem
    Enter old passphrase: 
    Key has comment '/home/incaReporterManager/etc/adminkey.pem'
    Enter new passphrase (empty for no passphrase): 
    Enter same passphrase again: 
    Your identification has been saved with the new passphrase.

  2. Create a custom wrapper script for $INCA_DIST/bin/inca-run-now called $INCA_DIST/bin/admin-run-now using the script below as an example. Use the agent and depot URIs for your installation as AGENT and DEPOT and the agent's name for the resource as RESOURCE. You may need to add the "-u" parameter for the appropriate user if the reporter manager is not running as inca. Run the script with the "-h" flag for more information about its input parameters:
    % setenv PERL5LIB lib/perl:$PERL5LIB; bin/inca-run-now -h

    Example wrapper script:
    #!/bin/sh
    
    AGENT=incas://localhost:6323
    DEPOT=incas://localhost:6324
    RESOURCE=localResource
    
    if ( test -z "${PERL5LIB}" ); then
    PERL5LIB=lib/perl
    else
    PERL5LIB=lib/perl:${PERL5LIB}
    fi
    export PERL5LIB
    
    ./bin/inca-run-now -a $AGENT -c etc/admincert.pem -d $DEPOT \
      -k etc/adminkey.pem -P "stdin:password:" \
      -t etc/trusted -i $RESOURCE $* 

  3. (optional)The command to use the admin-run-now script could be added to the reporter details status pages. This would require editing the $INCA_DIST/etc/instance.xsl file on the machine where the consumer is running and adding the xsl required to print a command like:
     % cd /home/inca/inca2install; ./bin/admin-run-now ant-unit 
    The xsl would be similar to:
    <tr>
      <td colspan="2" class="header">
        <xsl:text>Run now command (system admins only):</xsl:text>
      </td>
    </tr>
    <tr>
      <td colspan="2">
        <xsl:variable name="repPath" select="$report/reporterPath"/>
        <xsl:variable name="incaloc" select=
          "replace($report/reporterPath, '/var/reporter-packages/bin/.*', '')" />
        <p class="code"> <xsl:text>% cd </xsl:text>
        <xsl:value-of select="$incaloc"/>
        <xsl:text>; ./bin/admin-run-now </xsl:text>
        <xsl:value-of select="$nickName"/></p>
      </td>
    </tr>

11.4.2. Using the Manual Run Now Script

  1. Log into the inca account on the desired resource and change to the $INCA_DIST directory.
    % cd $INCA_DIST

  2. Execute admin-run-now script using the series nickname as the input parameter and the password from your inca administrator:
    % ./bin/admin-run-now ant_version
    password:*********
    Started Inca reporter-manager
    You can also print the XML result that gets sent to the Inca server in $INCA_DIST/var/run-now.log by using the "-L DEBUG" flag:
    % ./bin/admin-run-now -L DEBUG ant_version
    password:*********
    Started Inca reporter-manager

  3. Check for errors in $INCA_DIST/var/run-now.log. Wait about 10-15 minutes to view the result on your inca status page (data is cached and takes a few minutes to update).

  4. (optional)Execute multiple tests: in order to specify that more than one test be executed, use a Perl regex expression instead of the test name like:
    % ./bin/admin-run-now <perl regex>

    For example, to execute all ant tests
    % ./bin/admin-run-now "ant.*"

    In order to check your regular expression, you can use the "-l" flag. This option will list the tests but will NOT execute them. For example, to display all ant tests that would be executed:
    % ./bin/admin-run-now -l "ant.*"
    Suite:  sampleSuite (2 series)
    ant_helloworld_compile_test
    ant_version

    To view all tests, use the regular expression ".*" as below:
    % ./bin/admin-run-now -l ".*"

    You will notice that test names are listed under a "Suite: <name>" header. You can also use that suite name to execute all of the tests included in it. For example, the following shows the tests available in the sampleSuite kit:
    Suite:  sampleSuite (10 series)
    ant_helloworld_compile_test
    ant_version
    gcc_hello_world
    gcc_version
    java_hello_world
    java_version
    openssh_version
    openssl_version
    vtk-nvgl_version
    wget_page_test

    To execute all test in a kit using the suite name, type:
    % ./bin/admin-run-now sampleSuite

Run the script with the "-h" flag for help information:
% ./bin/admin-run-now -h

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.

Table 8. Inca component source distributions

Component

Build

agent

ant -Dinstalldir=$INCA_DIST install

common (used by all Inca Java components)

ant -Dinstalldir=$INCA_DIST install

consumer

ant -Dinstalldir=$INCA_DIST install

depot

ant -Dinstalldir=$INCA_DIST install

incat

ant -Dinstalldir=$INCA_DIST install

reporters

perl Makefile.PL <options>

reporter manager

perl Makefile.PL <options>

web services

perl Makefile.PL <options>