Troubleshooting

This topic provides troubleshooting information, including information about error messages and frequently asked questions related to PATROL for IBM DB2.

How do I configure WinRM?

You can use one of the following commands to configure the WinRM:

Note

If you are logged in on a non-Administrator account, you must either right-click the Command Prompt icon in the Start Menu and select Run as Administrator, or use the Runas command at the command prompt.

The winrm quickconfig command creates a firewall exception only for the current user profile. If the firewall profile is changed for any reason, you must run the winrm quickconfig command again to enable the firewall exception for the new profile.

WinRM automatically configures the ports that it uses. The port number might be different, depending on the version of WinRM that you install.

For WinRM 1.1:

  • The default HTTP port used is 80.
  • The default HTTPS port used is 443.

For WinRM 2.0 or later:

  • The default HTTP port used is 5985.
  • The default HTTPS port used is 5986.

The winrm quickconfig command also performs following tasks:

  • Starts the WinRM service.
  • Sets the WinRM service type to auto start.
  • Creates a listener to accept requests on any IP address.
  • Enables a firewall exception for WS-Management traffic (HTTP only).

Tip

  • If WinRM reports that it is unable to verify the status of the firewall, start the firewall service and run the winrm quickconfig command again. You can stop the firewall service after configuring WinRM, if desired.
  • If WinRM reports that it is unable to create a WinRM listener on HTTPS because the WinRM Server does not have a valid SSL certificate, check whether the SSL certificate is valid and ensure that it meets all requirements.

For an SSL certificate to be valid, its CN value must match the host name, it must not be expired, revoked, or self-signed, and it should be valid for server authentication.

How do I view the WinRM configuration?

You can use the following commands to display WinRM configuration details:

  • For the WinRM configuration:
    winrm get winrm/config
  • For the WinRM Client configuration:
    winrm get winrm/config/client
  • For the WinRM Server configuration:
    winrm get winrm/config/service
  • For Winrs configuration:
    winrm get winrm/config/winrs
  • For listener information:
    winrm enumerate winrm/config/listener
  • For the WinRM version details:
    winrm id

Can I change the WinRM configuration as a standard user?

By default, an Administrator user has permissions to change the WinRM configuration. In addition, a standard user who is a member of administrator group can also change the WinRM configuration.

How do I start and stop the WinRM service?

You can use the following command to start and stop the WinRM service:

sc <start|stop> winrm

You can use SCM to start and stop the Windows Remote Management service (WSManagement).

How do I verify the WinRM connection for a specific remote host?

You can use the following commands to verify the WinRM connection with a remote host.

  • To verify a remote host connection via HTTP or HTTPS using a domain account:
    • winrm id -r:http://<hostname>:<port> -u:<domain\username> -p:<password>
    • winrm id -r:https://<hostname>:<port> -u:<domain\username> -p:<password>
      OR
    • winrs -r:http://<hostname>:<port> -u:<domain\username> -p:<password><sys_command>
    • winrs -r:https://<hostname>:<port> -u:<domain\username> -p:<password><sys_command>

  • To verify a remote host connection via HTTP or HTTPS using a local account:

    • winrm id -r:http://<hostname>:<port> -u:<username> -p:<password>
    • winrm id -r:https://<hostname>:<port> -u:<username> -p:<password>
      OR
    • winrs -r:http://<hostname>:<port> -u:<username> -p:<password> <sys_command>
    • winrs -r:https://<hostname>:<port> -u:<username> -p:<password> <sys_command>

    Note

    <sys_command> refers to any Microsoft Windows operating system command, such as DIR or SYSTEMINFO.

How do I resolve connectivity issues for the WinRM command?

You might encounter one of the following scenarios while verifying the remote host connection with the winrm command.

Scenario 1

WinRM displays the following error message:

The client cannot connect to the remote host specified in the request. Verify that the service on the remote host is running and is accepting requests. You may use the following command to analyze the state of the WinRM service and to configure the service, if necessary: "winrm quickconfig".

To resolve the issue

  1. Verify that WinRM is configured properly.
  2. Configure WinRM again, using the winrm qc command.
  3. Check the status of the WinRM service on the remote host.
  4. Verify that the port number is valid.

Scenario 2

WinRM displays the following error message:

Logon failure: unknown user name or bad password.

To resolve the issue

  1. Verify that the username and password are valid.
  2. Verify that user name is associated with a valid domain name if a domain account is provided.
  3. Verify that the hostname has been added to the Trusted Host list if local credentials are provided.
  4. Check the Event Viewer for events related to authentication.

Scenario 3

WinRM displays the following error message:

Access is denied

To resolve the issue

  1. Verify that the username and password are valid.
  2. Verify that the user exists on the remote host.
  3. Verify the status of the WinRM service on the remote host.
  4. Verify that Kerberos and Negotiate authentications are enabled on the remote host.

Scenario 4

WinRM displays the following error message:

A security error occurred.

To resolve the issue

  1. Verify that the SSL certificate is valid on the remote host.
  2. Verify that the port number is valid.

Scenario 5

WinRM displays the following error message:

The WinRM client sent a request to an HTTP server and got a response saying the requested HTTP URL was not available. This is usually returned by a HTTP server that does not support the WS-Management protocol.

To resolve the issue

  1. Verify that the port number is valid.
  2. Configure the WinRM listener again.

Scenario 6

WinRM displays the following error message:

An internal error occurred.

To resolve the issue

  1. Verify the status of the WMI client on the remote host.
  2. Verify the status of the WinRM service on the remote host.

Scenario 7

WinRM displays the following error message:

The WinRM client cannot process the request because the server name cannot be resolved.

To resolve the issue

  1. Verify that the remote host is alive.
  2. Verify that the remote host is on the network, and added listed the DNS correctly.

Scenario 8

WinRM displays the following error message:

The WinRM client cannot complete the operation within the time specified. Check if the machine name is valid and is reachable over the network and firewall exception for Windows Remote Management service is enabled.

To resolve the issue

  1. Verify that the firewall exception for the Windows Remote Management service is enabled.
  2. Verify that the machine name is valid and is can be reached over the network.

Incorrect configuration information

  • Incorrect username or password
  • Incorrect host or port

Remote DB2 on Windows:

Remote db2 on Windows.png

Windows incorrect port.png

Remote DB2 on UNIX:

Remote db2 on unix.png

Unix incorrect port.png

To resolve the issue

Click No, fix the problematic field and click OK.

Cannot view data for some parameters or you would like to bring a new set of parameters

To resolve the issue

Run the DB2 Diagnostic Report by as below,

  1. Right click the DB2_ENVIRONMENT > KM Commands > KM Administration > DB2 Diagnostic Report. 
  2. For each running DB2 server,  a text file will be created at $PATROL_HOME/pso/diag. This file contains all the customer environment data which can be used to resolve the issue.

Patrol instance names contain number in the name

For example:

scenario11.png

This is done to make the instances short as PATROL reports issues with long instance names.

To resolve the issue

Add JVM argument -DLongInstanceMapping=true

Perform the following steps to add the JVM argument:

  1. Right click the DB2_ENVIRONMENT > KM Commands > KM Administration > Define JVM Arguments
  2. Enter DLongInstanceMapping=true

scenario11- part 2.png

Stop monitoring one of the configured DB2 environments

You want to stop monitoring one of the configured DB2 environments without deleting the environment from the pconfig or using Blackout.

To resolve the issue

 Set disableInstance pconfig environment variable to true. Restart the PATROL Agent. The configured environment will not be monitored.

scenario12.png

Change default collection

The default collection is as below:

  • DB2 Availability each 1 min
  • DB2 Data each 10 min
  • Diaglog each 5 min

If you want to change the default parameters, perform the steps as below.

Go to Administration commands from the CMA Policy.

scenario13.png

Availability change: Change the pconfig under the DB2 environment the variable

"/PSO/DB2/<<environment name>>/collectors/availabilityCollector/Cycle" = {REPLACE =“<cycle in sec>>”}

 Data change: Change the pconfig under the DB2 environment the variable:

"/PSO/DB2/<<environment name>>/collectors/dataCollector/Cycle" = {REPLACE =“<cycle in sec>>”}

 Diaglog change: Change the pconfig under the DB2 environment the variable

"/PSO/DB2/<<environment name>>/collectors/diagLogCollector/Cycle" = {REPLACE =“<cycle in sec>>”}

JAVA collector process consumes high memory

The JAVA collector process consumes high memory when monitoring a large-scale DB2 server environment.

To resolve the issue

Add JVM argument Xmx512m

Perform the following steps to add the JVM argument:

  1. Right click the DB2_ENVIRONMENT > KM Commands > KM Administration > Define JVM Arguments
  2. Enter Xmx512m

DB2 User does not have permissions to run the DB2 commands

scenario15.png

To resolve the issue

  1. Check if the HOME Installation PATH is correct
  2. Check the minimal authentication needed for DB2 user:
    1. For Remote/Local UNIX and Windows user, SYSMON user with DATAACCESS privilege
      1. You can grant DATACCESS privilege to SYSMON by executing db2 GRANT DATAACCESS ON DATABASE TO GROUP <sysmon group> command
      2. The user should succeed executing the following UNIX commands:
        1. uname
        2. df -g <DB cfg logpath file or DB_PATH of SYSIBMADM.SNAPDB file> (hp)
        3. df -k <DB cfg logpath file or DB_PATH of SYSIBMADM.SNAPDB file> (unix not hp)
      3. The user should succeed executing the following Windows commands:

        1. fsutil volume diskfree <drive>

        2. dir <file>

        3. type <db2 instance home>\<db2 instance name>\db2nodes.cfg

    2. JDBC user, SYSMON user with DATAACCESS privilege

      1. You can grant DATACCESS privilege to SYSMON by executing db2 GRANT DATAACCESS ON DATABASE TO GROUP <sysmon group> command

Filter instances from the monitor environment

You want to filter instances from the monitor environment. For example, you want to only db2inst1 and db2inst2 instances.

scenario16.png

To resolve the issue

Edit the environment by adding the required monitor instances in the Monitored DB instances field.

scenario16 part 2.png

scenario16 part 3.png

Filter databases from monitoring

You want to filter databases from monitoring.

scenario17.png

To resolve the issue

Add pconfig variable and restart the PATROL agent.

"/PSO/DB2/<<environment name>>/<<DB2 instance name>>/excludedDatabases" = {REPLACE = "<< >>"}

This variable will contain a list of the databases that will not be collected. If includedDatabases pconfig variable is defined then this pconfig variable is not relevant.

scenario17 part 2.png

scenario17 part 3.png

Filter partitions from monitoring

You want to filter partitions from monitoring.

scenario18.png

To resolve the issue

Add pconfig variable and restart the PATROL agent.

"/PSO/DB2/<<environment name>>/<<DB2 instance name>>/excludedPartitions" = {REPLACE = "<< >>”}

This variable will contain a list of the partitions numbers that will not be collected. If includedPartitions pconfig variable of the instance is defined then this pconfig variable is not relevant.

scenario18 part 2.png

scenario18 part 3.png

Configure SQL queries to monitor data

You need to configure SQL queries to monitor data in your database.

To resolve the issue

Add the SQL query configuration details. For example:

Field

Value

SQL name

test

Instance Name

DB2

Database Name

SAMPLE

SQL Query

select TOTAL_LOG_USED from SYSIBMADM.SNAPDB

Collection time

1

scenario19.png

If the query returns a single value as stated in the example, Value monitoring attribute will be created.

scenario19 part 2.png

Activate self-monitoring

To activate the self-monitoring of the response time of the DB2 KM running queries, right click the DB2_ENVIRONMENT > KM Commands > KM Administration > Queries Response Time 

Enable PSL and JAVA debug

You can enable the debug from the TrueSight console, PATROL console, or by using PCM rulesets. 

Enabling debug from the TrueSight console

Enabling JAVA debug
  1. In the Environment Configurations, open the Administration panel.

  2. In Java log level field, select Finest log level.

    Java_log_level.PNG
  3. Save the policy. Ensure that the changes are reflected in the pconfig variables.
Enabling PSL debug

Currently, the KM does not contain an option to activate the PSL debug by using the TrueSight console. You must use the PCM rulesets to enable PSL debug.

Enabling debug in the PATROL consoles

  1. To enable the JAVA log debug, right click the DB2 environment >  KM Commands > KM Administration > Java log level > Finest
  2. To enable the PSL debug, right click the DB2 node >  KM Commands > Debug PSL > Enable

Enabling debug by using PCM rulesets


Enabling JAVA debug

Set the log level for the DB2 Java collector by using the /PSO/DB2/<<environment name>>/javaDebugLevel pconfig variable. Valid values are:

  • 3 = Info (default) 
  • 4 = Fine
  • 5 = Finest
Enabling PSL debug

Enable the PSL debug by using the /PSO/Default/logLevel" = { REPLACE = "<<INFO|DEBUG>> pconfig variable.

After you enable the debug by using any of the consoles, follow these steps:

  1. Stop the PATROL Agent
  2. Delete the Java folder located in Patrol3/pso/logs directory  
  3. Delete the PSL log file located at <Patrol Agent>\Patrol3\log\pso-<Name of the agent:port>.kmlog directory
  4. Open the pso.properties file located at Patrol3/pso/conf/pso.properties 
  5. Set the javaDebugLevel property to value 5 (javaDebugLevel=5)
  6. Set the PrintCollectionDataToDebugLog property to value 1 (PrintCollectionDataToDebugLog=1)
  7. Save and close the file.
  8. Restart the PATROL Agent

Server Socket Port still not initialized

You get the following message in your KM log file - 

StartShutdownInstanceCollector:[openSocketChannel]: Server Socket Port still not initialized

This message is a warning message and it is shown after restarting Java because Java has not yet sent the port socket. You do not have an action item when such a message is shown in your logs.


 

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