Troubleshooting Content Manager and TSM Integration
Web Doc
Note: This is publication is now archived. For reference only.
Abstract
In this document we introduce various resources for troubleshooting problems with a Content Manager and TSM integration.
Contents
There are various resources for troubleshooting problems with a Content Manager and Tivoli Storage Manager (TSM) integration. By utilizing log files, traces, and the TSM Backup Archive client, you can quickly and easily resolve almost any configuration error. The following resources are discussed:
Resource Manager migrator log
The Resource Manager server contains a logging facility based upon the open source Log4J project. The logging facility consists of various XML files, each of which controls the level and location of logging for different parts of the Resource Manager server. The logging control file for the migrator process is named icmrm_migrator_logging.xml. This file is located, by default, in:
To trace the migrator process, open icmrm_migrator_logging.xml in Notepad (or equivalent), and locate the following two lines (towards the end of the file):
To obtain detailed debugging information, change the priority value from INFO to DEBUG. To send log messages to a file, change the appender-ref value from ASYNC to FILE. Restart the Resource Manager Web application and migrator process. Detailed messages concerning the migration of documents are logged in a file named icmrm.migrator.logfile. This file is located, by default, in:
TSM Client API log
While the Resource Manager logging facility is useful in determining that a problem does exist, it may not always be very helpful in telling you the exact details of what is causing the problem. For example, in certain situations, the Resource Manager logs may only contain information alluding to a connection problem with the TSM server. Details on what is causing the connection problem may not necessarily be in the Resource Manager log files.
The Resource Manager (and its processes) use the TSM Client APIs to communicate with the TSM server. By default, when an error occurs, the TSM Client APIs will log the error information in a file named dsierror.log. The information contained in this file proves invaluable in locating and resolving problems that deal solely with TSM, and have nothing to do with the Resource Manager configuration. Errors such as expired passwords and invalid management class names will be logged in this file.
Note: When troubleshooting a TSM integration problem, the dsierror.log file usually contains the cause of the error.
One common error that you may see in the dsierror.log file is that the dsm.opt file cannot be located. The TSM Client APIs use the DSMI_CONFIG variable to determine which option file to use. If there is a syntax error in the option file you specified, or if the file cannot be opened, then the TSM Client APIs will fall back to using the default option file name of dsm.opt. If you receive this type of message, you probably have a typo in your .opt file.
TSM Backup Archive Client
In some situations, the Resource Manager and TSM Client API log files may indicate that an invalid TSM server configuration is keeping documents from being migrated. One of the easiest ways to test a TSM server configuration is to use the TSM Backup Archive Client to back up a file.
The TSM Backup Archive Client also uses a set of variables to determine which client option file to use. More specifically, the DSM_CONFIG environment is used by the TSM Backup Archive Client to determine which client option file to use. This variable should point to the client option file used by the Resource Manager. Doing so will ensure that the backup client is using the same TSM configuration as the Resource Manager.
If the TSM Backup Archive Client fails to back up a file, then the Resource Manager server will also fail. (Remember, the Resource Manager server does not archive files; it backs up files.) This indicates a problem with the TSM server configuration. In this circumstance, you should check the TSM server's activity log to determine what the problem is.
TSM Server
If you are encountering errors still, there are some things that you should check on the Tivoli Storage Manager server using the administrative client.
Run the command query node nodename f=d, replacing nodename with the nodename that is being used to back up Content Manager objects. The values should be set as follows:
Using the value of Policy Domain Name, you can run some queries to see if the correct management classes for the Content Manager object backups are available. The command query mgmtclass <domain> active shows which is the DEFAULT management class for the node. The command query copygroup <domain> active tells you what the retention settings are for the management classes.
- Resource Manager migrator log
- TSM Client API log
- TSM Backup Archive Client
- TSM server
Resource Manager migrator log
The Resource Manager server contains a logging facility based upon the open source Log4J project. The logging facility consists of various XML files, each of which controls the level and location of logging for different parts of the Resource Manager server. The logging control file for the migrator process is named icmrm_migrator_logging.xml. This file is located, by default, in:
- C:\Program Files\WebSphere\AppServer\installedApps\<hostname>\icmrm.ear\icmrm.war on Windows
- /usr/WebSphere/AppServer/installedApps/<hostname>/icmrm.ear/icmrm.war on AIX
- /opt/WebSphere/AppServer/installedApps/<hostname>/icmrm.ear/icmrm.war on Solaris
To trace the migrator process, open icmrm_migrator_logging.xml in Notepad (or equivalent), and locate the following two lines (towards the end of the file):
<priority value="INFO" class="com.ibm.mm.icmrm.util.ICMRMPriority"/>
<appender-ref ref="ASYNC"/>
<appender-ref ref="ASYNC"/>
To obtain detailed debugging information, change the priority value from INFO to DEBUG. To send log messages to a file, change the appender-ref value from ASYNC to FILE. Restart the Resource Manager Web application and migrator process. Detailed messages concerning the migration of documents are logged in a file named icmrm.migrator.logfile. This file is located, by default, in:
- C:\Program Files\WebSphere\AppServer\logs on Windows
- /usr/WebSphere/AppServer/logs on AIX
- /opt/WebSphere/AppServer/logs on Solaris
TSM Client API log
While the Resource Manager logging facility is useful in determining that a problem does exist, it may not always be very helpful in telling you the exact details of what is causing the problem. For example, in certain situations, the Resource Manager logs may only contain information alluding to a connection problem with the TSM server. Details on what is causing the connection problem may not necessarily be in the Resource Manager log files.
The Resource Manager (and its processes) use the TSM Client APIs to communicate with the TSM server. By default, when an error occurs, the TSM Client APIs will log the error information in a file named dsierror.log. The information contained in this file proves invaluable in locating and resolving problems that deal solely with TSM, and have nothing to do with the Resource Manager configuration. Errors such as expired passwords and invalid management class names will be logged in this file.
Note: When troubleshooting a TSM integration problem, the dsierror.log file usually contains the cause of the error.
One common error that you may see in the dsierror.log file is that the dsm.opt file cannot be located. The TSM Client APIs use the DSMI_CONFIG variable to determine which option file to use. If there is a syntax error in the option file you specified, or if the file cannot be opened, then the TSM Client APIs will fall back to using the default option file name of dsm.opt. If you receive this type of message, you probably have a typo in your .opt file.
TSM Backup Archive Client
In some situations, the Resource Manager and TSM Client API log files may indicate that an invalid TSM server configuration is keeping documents from being migrated. One of the easiest ways to test a TSM server configuration is to use the TSM Backup Archive Client to back up a file.
The TSM Backup Archive Client also uses a set of variables to determine which client option file to use. More specifically, the DSM_CONFIG environment is used by the TSM Backup Archive Client to determine which client option file to use. This variable should point to the client option file used by the Resource Manager. Doing so will ensure that the backup client is using the same TSM configuration as the Resource Manager.
If the TSM Backup Archive Client fails to back up a file, then the Resource Manager server will also fail. (Remember, the Resource Manager server does not archive files; it backs up files.) This indicates a problem with the TSM server configuration. In this circumstance, you should check the TSM server's activity log to determine what the problem is.
TSM Server
If you are encountering errors still, there are some things that you should check on the Tivoli Storage Manager server using the administrative client.
Run the command query node nodename f=d, replacing nodename with the nodename that is being used to back up Content Manager objects. The values should be set as follows:
- Backup deleted allowed: This value should be set to YES.
- Maximum Mount Points Allowed: This value should be equal to or less than the number of drives on the Tivoli Storage Manager server.
- Locked?: This value should be set to NO.
- Policy Domain Name: This value should be checked to make sure it belongs to the correct domain. It determines which management classes are available to the node for managing the Content Manager object backups.
Using the value of Policy Domain Name, you can run some queries to see if the correct management classes for the Content Manager object backups are available. The command query mgmtclass <domain> active shows which is the DEFAULT management class for the node. The command query copygroup <domain> active tells you what the retention settings are for the management classes.
Special Notices
The material included in this document is in DRAFT form and is provided 'as is' without warranty of any kind. IBM is not responsible for the accuracy or completeness of the material, and may update the document at any time. The final, published document may not include any, or all, of the material included herein. Client assumes all risks associated with Client's use of this document.