Running the Configuration Check Utility for UDM

To run successfully, the Data Management utility must communicate with a series of supporting background applications, plug-ins, and forms. 

If a Data Management job fails because of an issue with the supporting environment, you could spend a lot of time troubleshooting the issue, adjusting the configuration parameters, and rerunning the data-load job. To significantly reduce the likelihood that jobs will fail for environment-related reasons, we strongly recommend that you run the Configuration Check utility.

In general terms, the Configuration Check utility is a AR System utility that examines how the following entities are configured, and reports any problems that it finds with them:

  • AR System configuration
  • Customizations

You can also use the Configuration Check utility to inspect the environment for Data Management. This specific use of the Configuration Check is what we describe here.

If the Configuration Check utility finds issues, it points you to information about how to correct them.

What does the Configuration Check utility look for?

When you run the Configuration Check utility for Data Management configuration, it performs the checks described in the following table:

Area checked

What it checks for

MSSQL DB performance configuration

  • Is the READ_COMMITTED_SNAPSHOT parameter on? 
    If this parameter is turned off, the configuration check utility returns a message asking you to turn it on.
  • Is the XACT_ABORT parameter turned off? 
    If this parameter is turned on, the configuration check utility returns a message asking you to turn it off.

AR System server configuration

  • Are escalations enabled?
  • Are escalations enabled on the servers configured in the ARSystemServerGroupOperationRanking form?
  • Is the maximim number of filters for an operation set to 500000?
  • Is the maximum stack size of filters set to 10000?
  • Is Filter_API_Timeout set to 300 seconds?
  • Is asynch_op_api_timeout set to 300 seconds?
  • Is max_params_retries set to 3?

  • Does the Command Automation Interface (CAI) plug-in configuration have a private RPC?
    If it does, it checks the ar.cfg (ar.conf) file for a definition of the private queue.) The Configuration Check utility checks the following settings:

    • Is the Port number set to 390693?
    • Is the min thread set to 1 and max thread set to 6?

Service Management Application Password

Can the Configuration Check utility communicate with the AR System server using the password provided for members of the server group?

Data Management load file path

  • Is the Data Management path set in SYS:System Setting?
  • Can the Configuration Check utility write to the specified directory?

Data Management plugin configuration

  • Can the Configuration Check utility communicate with the Carte server by opening a socket connection for each entry in the UDM:Config form?
  • Is the socket connection at the configured port?
  • If this environment is a server-group environment:
    • Does the UDM:Config form contain an entry for each AR System server in the group?
  • Have you enabled the Is Default check box for the servers in the UDM:Config form?
  • Is the connectivity of the default or non-default server established to the AR System server?

Messages from the Configuration Check utility

The following table lists the messages that the Configuration Check utility returns when it is run for Data Management:

Message

 Probable cause or action to take

The check could not query the server parameters.

The check could not query server parameters by using the GSI API call.

Escalations are disabled on localhost: hostName.

In a single-server environment, ensure that escalations are turned on.

Filter-Max-Total:<current value>, is set less than 500000.

The minimum value must be 500000. This value is configured in the ar.cfg file (ar.conf file in UNIX environments).

Filter-Max-Stack:<current value>, is set less than 10000.

The minimum value must be 10000. This value is configured in the ar.cfg file (ar.conf file in UNIX environments).

Filter-API-Timeout:<current value>, is less than 300.

The minimum value must be 300. This value is configured in the pluginsvr_config.xml file.

The check could not retrieve the 
asynch_op_api_timeout in the 
pluginsvr_config.xml, 
Please define the asynch_op_api_timeout 
with value 300.

Configure asynch_op_api_timeout in pluginsvr_config.xml file.

asynch_op_api_timeout:<current value>, is less than 300.

The minimum value must be 300. This value is configured in the pluginsvr_config.xml file.

The check could not retrieve the 
max_params_retries in the 
pluginsvr_config.xml, 
Please define the max_params_retries 
with value 300.

Configure max_params_retries in pluginsvr_config.xml file.

max_params_retries:<current value>, is less than 3.

The minimum value must be 3. This value is configured in the pluginsvr_config.xml file.

The plugInName plugin is not configured in 
pluginsvr_config.xml.

Ensure that the plugin is configured in the pluginsvr.xml file.

The check could not retrieve the 
PRIVATE-RPC-SOCKET from the ar.cfg file.

Configure the CAI plugin to use a private RPC socket in the ar.cfg file (ar.conf file in UNIX environments).

For the CAI plugin: plugInName, a private RPC 
is configured in the pluginsvr_config.xml file 
but not in the ar.cfg file. 

Configure the CAI plugin to use a private RPC socket in the ar.cfg file (ar.conf file in UNIX environments).

You must allocate more threads for the 
CAI plugin private RPC queue.

The number of threads that you allocate depends on your environment and the number of cores that you are using.

The check could not query the 
UDM:RAppPassword form: systemMessage.

Depending on the content of the system message, verify that the host server is running and that there are no network issues preventing communication.

The UDM:RAppPassword form has not been 
configured.

You must configure or update the contents of the UDM:RAppPassword form.

The check could not locate an entry for 
hostName in the UDM:RAppPassword form.

You must configure the host-name parameter in the UDM:RAppPassword form.

The check could not verify the password 
for: remedyApplicationService on : 
serverGroupMemeberID.

You must configure or update the password in the UDM:RAppPassword form on the indicated server.

The check could not verify the Remedy 
Application password for remedyApplicationService, 
the Password field is empty.

Open the UDM:RAppPassword form and provide a password.

The check cannot read or write to the 
Data Management Load Path: pathName.

The Data Management File Path verification failed. For troubleshooting information, see the BMC Communities posting at Unified Data Management settings.

The Data Management Load Path parameter is 
not set in the SYS:System Settings form.

You must configure the Data Management Load Path parameter in Foundation > Advanced Options > System Configuration Settings - System Settings.

The check could not query the 'SYS:System Settings'
 form: systemMessage.

The server hosting this form might not be running, or network issues might be interfering with communication to the server. The content of the message itself provides the specific details.

The check could not connect with the Carte server: 
serverName at the specified port number.

Verify that the port number of the Carte server in the UDM:Config form is correct.

Connection failed to carte server: systemMessage.

Refer to the content of the message itself for the exact nature of the connection failure, and address the problem accordingly.

Escalations are disabled on all of the server group 
members.

At least one server in the server group must have escalations turned on. For more information about this requirement, see Overview-of-the-data-load-process.

Escalations are turned on only on: serverName.

This message is informational. No action by you is needed.

Escalations are enabled on number members of 
the server group: serverNames.

This message is informational. No action by you is needed.

The check was unable to determine the status 
of the Pentaho plugin.

Either the ARDBC Pentaho plug-in is disabled in the pluginsvr_config.xml file, or an entry for the Pentaho plug-in is missing from the ar.cfg file (ar.conf in UNIX environments).

The check could not confirm the Pentaho plugin 
status; the Remedy Application Service password 
for remedyApplicationService was not found.

Check the password in the UDM:RAppPassword file for the application service named in remedyApplicationService.

The Pentaho plugin is not running on : serverNames.

Manually investigate why the Pentaho plug-in is not running. A plug-in configuration error might have occurred.

The Pentaho plugin is not running on : serverNames.

Manually investigate why the Pentaho plug-in is not running. A logon error might have occurred. Common causes of this error include the following issues:

  • A disruption occurred in the network infrastructure.
  • The hosting server is not running.
  • The Penatho plug-in is not configured in the ar.cfg file (ar.conf in UNIX environments).

Server group member serverName is 
missing from the UDM:Config form.

Add server group member serverName to the UDM:Config form.

Server Connect name serverName is 
missing from the UDM:Config form.

Add Server Connect name serverName to the UDM:Config form.

AR Server may not be up & running.
Login failed to AR server.
Could not connect to the server.

Ensure that the Is Default check box is enabled on at least one of the servers in the UDM:Config form and the connectivity of the server is successfully established to the AR System server.

The check could not log into or 
query the following forms: formNames.

Manually investigate why the Pentaho plug-in is not running. A logon error might have occurred. Common causes of this error include the following issues:

  • A disruption occurred in the network infrastructure.
  • The hosting server is not running.
  • The Penatho plugin is not configured in the  ar.cfg file (ar.conf in UNIX environments).

In what modes does the Configuration Check utility run?

The Configuration check can run in several modes:

  • GUI mode
  • Command-line mode
  • Script mode

The mode to use depends on your environment or what you are trying to achieve, as described in the following table. See How do I run the Configuration Check utility? for detailed information about each mode.

Mode

Description

Executable

GUI

GUI mode provides you with an interactive, Windows-type environment from which you can run the Configuration Check utility manually and view the results. Use GUI mode any time that you are working in a Windows environment or an emulated Windows environment and want to run the checks manually. 


configchecker-ui.bat (for Microsoft Windows)

configchecker-ui.sh (for UNIX) 

Command Line

Command-line mode provides an interactive way to run the Configuration Check utility manually from a command prompt. Use command-line mode when you are working from a terminal that does not have Windows or Windows emulation capabilities. 

configchecker.bat (for Microsoft Windows)

configchecker.sh (for UNIX) 

Script

Script mode provides you with a way to run the Configuration Check utility as part of an automated job.


configchecker.bat commandLineArguments 
(for Microsoft Windows)

configchecker.shcommandLineArguments 
(for UNIX) 

Where do I run the Configuration Check utility?

Where you run the Configuration Check utility depends on whether you are operating a single AR System server or multiple AR System servers in a server group:

Environment

Details

Server group

In a server-group environment, we recommend that you run the Configuration Check utility from the server in the group on which escalations are enabled. From the server that has escalations enabled, the utility runs against all of the servers. However, consider the following points:

  • If you configure the ranking for multiple servers, you need to address only the error or warning messages that the Configuration Check utility issues for the Carte server. You can safely ignore the messages issued for the other AR System servers in the group.
  • If you configure a default Carte server and are running load balancing in your environment, you must also pay attention to any error or warning messages related to the Pentaho plug-in that the Configuration Check utility issues for all of the AR System servers in the group.

How do I run the Configuration Check utility?

Understand how to run Configuration Check in the following modes:

Important

Before you run the utility, make sure that the environment variable, JAVA_HOME, is pointing to the jre folder.

For example,

JAVA_HOME=C:\Program Files\Java\<java_folder>\jre

or

JAVA_HOME=/usr/java/<java_folder>
export JAVA_HOME

To run the Configuration Check utility in GUI mode

  1. Run the executable appropriate to your operating system:
    • Microsoft Windows: configchecker-ui.bat   
    • UNIX: configchecker-ui.sh 
      For UNIX, provide executable permissions to configchecker-ui.sh. Use any X-Server utility such as MobaXterm to start the Configuration Check GUI.

  2. Complete the fields that require input. If you have run the Configuration Check utility previously, many of these fields might already have valid entries. For the Products field, however, ensure that you select UDM.

    Field Name

    Description

    Categories

    All checks are classified into two categories: Pre-upgrade checks and Configuration checks. These categories indicate when a particular check must be run.

    Products

    Displays a list of products for which the utility is executed. From the list, select UDM 

    DB Host

    AR System database host name

    DB Type

    AR System database type

    The following fields are displayed in the DB Type Configuration window:

    • Oracle, MS-SQL, DB2, or Sybase—Select the required database from these options.
    • Unicode—Select this option for a unicode database.
    • Windows Authentication or SQL Authentication—Select either of these options for authentication.
    • Host Name— AR System server host name
    • Port—Port number for the AR System server
    • DB Instance Name—Name of the database instance
    • AR System DB Name— AR System database name
    • User— AR System server user name
    • Password— AR System server password

    AR Server

    AR System server name

    AR User

    AR System server user name

    The following fields are displayed in the AR System server user name configuration window:

    • AR Server— AR System server name
    • Port—Port number for the AR System server
    • User— AR System server user name
    • Password— AR System server password
    • Auth String—Authentication string for AR System server

    AR Install Dir

    AR System installation directory.

    You must specify this path for a fresh installation. However, this is optional for the upgrade process, because the utility automatically finds this path by querying the AR System server.

    Temp Dir

    Location of the temporary directory.

    This input is mandatory for BMC Helix ITSM (BMC Helix ITSM) and BMC Service Request Management (BMC Service Request Management) products. If you do not provide this path, this check fails.

    Load Pre-Check Config File

    Name and location of the input configuration file that contains the framework configuration and information about the Configuration Check utility plug-ins.

    By default, the value of this field is the name and location of the out-of-the-box configuration file. Click Browse to change the file name and location.

    We recommend that you run the utility with the default configuration file.

    Load Existing Result File

    Location at which the result file is created.

    Click Browse to change the default location of the result file. The existing result file can also be loaded to see the status of the last run.


    The configuration choices for the Configuration Check utility are saved in the configchecker_config.xml file. If you change the configuration, the configuration file is saved as a new file, and subsequent changes are made to that file. The original configuration file that is shipped with AR System is backed up as a separate file.

  3. Click Next to open a window that displays all of the available checks based on the input that you provided in the previous window.
    When you click Next, the AR Server, Temp Dir, and AR Install Dir fields are validated. If an error occurs, you must resolve it before going to the next screen.
    A summary of some of the input is displayed in read-only mode at the top of this window. The Summary tab displays the precheck name, the product for which the checks will be executed, and the status of the checks. 
  4. If the prechecks are not already selected, select all of them and click Run to execute the selected checks. 

Reporting

After the checks are executed, if all of the checks pass, no messages are displayed on the Errors/Warnings tab. If errors or warnings occur, they are displayed in detail in the tab. Additionally, the Hints column contains links to helpful information about errors that occur. 

The results are stored in an XML file (configcheckResult.xml) in the configchecker folder. Even if you close the GUI session or restart the system, you can still view the status of the last Configuration Check utility run by loading this XML file. 

If you immediately rerun the utility, the system overwrites the configcheckResult.xml file. If you rerun the checks after you click Prev, or if you close the utility and reopen it, the system backs up the current result file up appending a time stamp to the  file name. 

To run the Configuration Check utility using the command-line interface

  1. Run the executable appropriate to your operating system:
    • Microsoft Windows: configchecker.bat 
    • UNIX: configchecker.sh. 
      For UNIX, provide executable permissions to configchecker.sh. 

  2. In the command-line window, provide the required inputs using the commands given in the following table:

    The [confluence_table-plus] macro is a standalone macro and it cannot be used inline.

To run the Configuration Check utility in script (silent) mode

  1. In the script that you will use to run the Configuration Check utility, type one of the following executable commands:
    • Microsoft Windows—configchecker.bat 
    • UNIX—configchecker.sh.
      For UNIX, provide executable permissions to configchecker.sh. 

  2. With the executable command, provide the run-time parameters. The following table lists the run-time parameters and describes what they do.

    Parameter

    Purpose

    configchecker.bat -x <ARSERVER> -u <ARUSER> -p <ARPASSWORD> –o <PORT> -m 2 -rid "Check MSSQL DB performance configuration"

    • Checks that the READ_COMMITTED_SNAPSHOT parameter is turned on
      If this parameter is turned off, the configuration check utility returns a message asking you to turn it on.
    • Verifies that the XACT_ABORT parameter is turned off
      If this parameter is turned on, the configuration check utility returns a message asking you to turn it off.

    configchecker.bat -x <ARSERVER> -u <ARUSER >-p <ARPASSWORD> –o <PORT> -m 2 -rid "Check AR System Server Configuration"

    • Verifies that escalations are enabled.
    • Verifies that maximum number of filters for an operation are set to 500,000.
    • Verifies that the maximum stack size of filters is set to 10,000.
    • Verifies that the CAI plug-in configuration has a private RPC. If it does,
      it checks the ar.conf file for a definition of the private queue.

    configchecker.bat -x <ARSERVER> -u <ARUSER >-p <ARPASSWORD> –o <PORT> -m 2 -rid "Check Remedy App Server Password"

    Verifies that the Configuration Check utility can communicate with the AR System server using the password provided for members of the server group.

    configchecker.bat -x <ARSERVER> -u <ARUSER >-p <ARPASSWORD> –o <PORT> -m 2 -rid "Check Data Management Load File Path"

    • Verifies that the Data Management path is set in SYS:System Setting
    • Verifies that the Configuration Check utility can write to the
      specified directory.

    configchecker.bat -x <ARSERVER> -u <ARUSER >-p <ARPASSWORD> –o <PORT> -m 2 -rid "Check UDM plugin config"

    • Verifies that the Configuration Check utility can communicate with the Carte server by opening a socket connection for each entry in the UDM:Config form. The check then verifies that the socket connection is open at the configured port.
    • In a server group environment, performs the following checks:
      • Checks for an entry in the UDM:Config form for each AR System server in the group.
      • Verifies that escalations are enabled on at least one of the AR System servers in the group.


 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*