=============================================================================== QDES56 Utility Copyright (c) IBM Corporation, 2006 This utility is intended to help you determine whether your data might be affected by APAR IC49621. If you have not reviewed the flash for IC49621, then you should do so before proceeding further. The recommended sequence is: 1. Read and understand the flash for IC49621. Based on the information in the flash, you might not need to take any further action. The flash can be found at: http://www-1.ibm.com/support/docview.wss?uid=swg21242033 2. After you have read the flash, if you have determined that your data might be affected by this problem, then read and understand the information in this README file. 3. Use the utility as described in this README file to determine if you have data that might be affected by IC49621. 4. If the results indicate that you have data that might be affected by IC49621, contact IBM technical support for further assistance, as described in this README file below. Use of this utility outside the scope of its stated purpose is unsupported, and thus at your own risk. =============================================================================== =============================================================================== CONTENTS =============================================================================== - ABOUT THE QDES56 UTILITY - WHAT TO DO IF YOUR DATA MIGHT BE AFFECTED - INSTALLATION - USING THE UTILITY - QDES56 UTILITY SYNTAX - UNDERSTANDING THE BRIEF (SUMMARY) OUTPUT - UNDERSTANDING THE VERBOSE (DETAILED) OUTPUT =============================================================================== ABOUT THE QDES56 UTILITY =============================================================================== QDES56 ("Query DES-56") is a specialized Tivoli Storage Manager (TSM) API utility that scans your TSM API file spaces and reports the number of objects (files or other data objects) that are encrypted with the Data Encryption Standard (DES-56) algorithm. The utility can also provide detailed information about each DES-56 encrypted object. The utility only reads information from the TSM database; it does not store any information in the database. If selected, the detailed information is written to your computer screen and to files on disk. The disk files are in a tab-delimited text format that can be imported into a spreadsheet or database application for easier viewing. As stated above, the utility is intended to aid in determining whether you have any data that might be affected by APAR IC49621. While this problem affects only DES-56 encrypted objects, not all DES-56 encrypted objects are affected. =============================================================================== WHAT TO DO IF YOUR DATA MIGHT BE AFFECTED =============================================================================== After reviewing the flash and running the qdes56 utility, if you think your data might be affected or if you are not sure whether your data might be affected, contact IBM technical support for further assistance. Be sure to say that you are calling about APAR IC49621. IBM technical support will work with you to: * Help you determine whether your data might be affected. * Help you determine which objects, if any, are affected. * Help you recover any affected objects. In order to assist you, technical support will need the detailed output from the qdes56 utility. =============================================================================== INSTALLATION =============================================================================== Download the utility for the operating systems on which you run applications that use the TSM API. The utility is comprised of one file: Microsoft Windows: qdes56.exe UNIX, Linux: qdes56 OS/400: QDES56.SAVF NOTES: * Version 5.3.x of the TSM API must be installed on the same system where you run the utility. * For all operating systems except OS/400, you can put the utility in a directory of your choosing. It is recommended that you choose a directory that is not full or nearly full. * For OS/400, you must install the utility as follows: 1. Download QDES56.SAVF 2. Create a savefile on your system named QDES56: CRTSAVF FILE(QGPL/QDES56) 3. Use FTP to send QDES56.SAVF in binary to OS/400 4. Install the utility: RSTOBJ OBJ(QDES56) SAVLIB(QANSAPI) DEV(*SAVF) SAVF(QGPL/QDES56) 5. The qdes56 utility is now available in /qsys.lib/qansapi.lib/qdes56.pgm. You can run this program from any directory by typing its full name, or link to it in any directory by entering (in QShell) ln -s /qsys.lib/qansapi.lib/qdes56.pgm qdes56 When you run the qdes56 program, it is recommended that you choose a directory that is not full or nearly full. * When generating detailed output, the resulting disk files will consume some disk space. The required disk space for the detailed output files can be estimated as follows: required space = n(x + 40) where n is the number of objects that are DES-56 encrypted, and x is the average length, in bytes, of the file space name, high-level name, and low- level name of each object. For example, suppose that there are 2,000,000 objects. The sum of each object's file space name, high-level name, and low-level name is, on average, 150 bytes. The required disk space is approximately: 2,000,000(150 + 40) = 38,000,000 bytes, or about 38 MB. * The utility for a given UNIX or Linux operating system can be used for all nodes on your other UNIX and Linux systems. For example, the AIX version of the utility can be used to query information for AIX, HP-UX, Solaris, Linux, and USS nodes. * The Windows version of the utility runs on x32 processors. However, the utility can be used to query information for nodes that are used on both 32-bit and 64-bit processors. =============================================================================== USING THE UTILITY =============================================================================== 1. Identify nodes that use the TSM API. One method for doing this is to issue the following SELECT statement from the TSM administrative command line interface: select node_name, filespace_name, filespace_type \ from filespaces \ where filespace_type like 'API:%' 2. Identify the applications used by each node. Then consult the flash for a list of TSM API applications that are not affected by IC49621. The utility should only be run for nodes that are used with a TSM API application that does NOT appear in the list. If the node is used ONLY by applications that appear in the list, then that node's data is unaffected. The node can be removed from the list of nodes for which the utility must be run. If you are able to eliminate all nodes that use the TSM API, then your data is unaffected by IC49621, and no further action is required. 3. The utility is limited to processing nodes that have up to 512 API file spaces. You should determine whether any nodes have more than 512 API file spaces. One method for doing this is to run the following SELECT statement: select node_name, count(filespace_name) as num_fs \ from filespaces \ where filespace_type like 'API:%' \ group by node_name \ having count(filespace_name)> 512 \ order by num_fs desc The above SELECT will tell you which nodes have more than 512 API file spaces, along with the actual number of API file spaces. If no results are returned, then you have no nodes that are subject to this limitation. For those nodes that have more than 512 API file spaces, you will need to run the utility multiple times, using different file space naming patterns that yield 512 or fewer API file spaces. 4. Open a command prompt and change into the directory where qdes56 resides. 5. Configure the TSM API environment variables DSMI_CONFIG and DSMI_DIR. Consult the manual "IBM Tivoli Storage Manager: Using the Application Programming Interface" for further information. The manual can be found at: http://publib.boulder.ibm.com/infocenter/tivihelp/v1r1/index.jsp?topic=/com.ibm.itsmc.doc/ansa0000.htm 6. Run the utility for each node. Make sure to run the utility on an operating system that is compatible with the operating system where the node is used: * If the node is used on Windows, you must run the utility on Windows. * If the node is used on OS/400, you must run the utility on OS/400. * If the node is used on UNIX or Linux, you must run the utility on UNIX or Linux. If the node is used on multiple operating systems (NOT recommended!), you must run the utility on each type of operating system where the node is used, per the above rules. Run the utility with the verbose flag set to N. Examine the counts of DES-56 encrypted files. For a given file space, if the count for both backup and archive files is 0 (zero), then that file space's data is unaffected by IC49621. If all file spaces for the node are unaffected, then that node is unaffected. If all nodes are unaffected, then no further action is required since your data is unaffected by IC49621. If any file space shows a nonzero DES-56 encrypted file count, then run the utility again with the verbose flag set to Y. This will create detailed output files on disk that can be sent to IBM technical support to help you determine which of these object, if any, are affected by IC49621. For large file counts, consider redirecting the qdes56 output to a file. If a node has more than 512 API file spaces, then you will need to run the utility multiple times. For example, suppose there are 600 API file spaces such that 500 file space names begin with API:FS1 and 100 file space names begin with API:FS2. You will need to run the utility twice as follows: 1. Run the utility with file space naming pattern API:FS1* qdes56 yournode youradmin youradminpw y "API:FS1*" 2. Rename the resuling detailed output files to something else, so they will not be overwritten by the next step. 3. Run the utility again with the second file space naming pattern: qdes56 yournode youradmin youradminpw y "API:FS2*" =============================================================================== QDES56 UTILITY SYNTAX =============================================================================== The syntax for the utility is as follows: qdes56 As indicated by the syntax, the utility accepts five (5) parameters. All parameters are required. The parameters are: The name of the node you want to query Your TSM administrator ID Your TSM administrator password This is a indicates whether you want brief or verbose output: N = brief (summary) output Y = verbose (detailed) output The file space name or pattern you want to query. Use an asterisk (*) as a wildcard. On Unix and Linux, place double quotes around file space name patterns that contain wildcards. On Windows, double quotes can be used, but are not required. This parameter is case sensitive. The following examples assume that your TSM administrator ID is "tsmadmin" and your password is "secretpw". a. This example checks whether node "xyzarch" has any data that might be affected by APAR IC49621: qdes56 xyzarch tsmadmin secretpw n "*" b. Suppose the output indicates that node xyzarch has files that are DES-56 encrypted in the file space named /dataarch2. The following example displays detailed output that includes the high-level and low-level names of each DES-56 encrypted object: qdes56 xyzarch tsmadmin secretpw y /dataarch2 NOTE: When verbose output is selected, the utility will create two files in the current directory: qdes56_bkup_detail_.txt qdes56_arch_detail_.txt is the name of the node you specified as the first parameter to the utility. In this example, is "xyzarch". Thus when you run the above command, these two files will be created: qdes56_bkup_detail_xyzarch.txt This file contains detailed information for any DES-56 encrypted backup objects. qdes56_arch_detail_xyzarch.txt This file contains detailed information for any DES-56 encrypted archive objects. If there are no DES-56 encrypted objects, then the above files will contain only column headers. The files are tab-delimited, and thus are suitable for loading into a spreadsheet or database application. =============================================================================== UNDERSTANDING THE BRIEF (SUMMARY) OUTPUT =============================================================================== The summary output from qdes56 includes the following elements: Program header The program header displays the program name and API version that you have installed. File space list A list of file spaces stored on the TSM server for the node. The output includes the file space name, file space type, and "YES" or "NO" to indicate whether it is a Unicode file space. DES-56 encrypted object counts For each file space listed in the file space list, the number of DES-56 encrypted backup objects and the number of DES-56 encrypted archive objects is shown. Here is an example of a command and its output. The output is annotated to indicate the different elements. Annotations begin with "==>". ------------------------------------------------------------------------------- BEGIN SAMPLE COMMAND AND OUTPUT ------------------------------------------------------------------------------- ==> Display summary information for node storman_api. In particular, check file ==> spaces whose names end with "ata". C:\IC49621>qdes56 storman_api storman xxxxx n "*ata" ==> Program header ****************************************************************** QDES56 - TSM API utility for finding DES-56 encrypted files API Library Version = 5.3.4 (unicode) Copyright (c) IBM Corporation, 2006 ****************************************************************** ==> File space list ------------------------------------------------------------------------------ FILE SPACE NAME TYPE UNICODE ------------------------------------------------------------------------------ \\storman\more_test_data API:Sample NO ArchivedData API:Sample NO ==> DES-56 encrypted file counts for file space "\\storman\more_test_data". ==> Note that the file space has 9 DES-56 encrypted backup objects, and 0 ==> DES-56 encrypted archive objects. ------------------------------------------------------------------------------ FSNAME: >\\storman\more_test_data< Total DES-56 Encrypted Backup files : 9 ------------------------------------------------------------------------------ ------------------------------------------------------------------------------ FSNAME: >\\storman\more_test_data< Total DES-56 Encrypted Archive files : 0 ------------------------------------------------------------------------------ ==> DES-56 encrypted file counts for file space "ArchivedData". ------------------------------------------------------------------------------ FSNAME: >ArchivedData< Total DES-56 Encrypted Backup files : 0 ------------------------------------------------------------------------------ ------------------------------------------------------------------------------ FSNAME: >ArchivedData< Total DES-56 Encrypted Archive files : 200 ------------------------------------------------------------------------------ C:\IC49621> ------------------------------------------------------------------------------- END SAMPLE COMMAND AND OUTPUT ------------------------------------------------------------------------------- =============================================================================== UNDERSTANDING THE VERBOSE (DETAILED) OUTPUT =============================================================================== The detailed output from qdes56 includes the following elements: Program header The program header displays the program name and API version that you have installed. File space list A list of file spaces stored on the TSM server for the node. The output includes the file space name, file space type, and "YES" or "NO" to indicate whether it is a Unicode file space. Information for each DES-56 encrypted object For each file space, detailed information for each DES-56 encrypted object is shown. The details include file space name, high-level name, low-level name, object ID, encryption type (should indicate DES-56), "YES" or "NO" to indicate whether the object is compressed, and the size estimate used when the object was stored. For backup objects, an "A" or "I" will also be shown to indicate whether the object is active or inactive. DES-56 encrypted backup objects are shown first, followed by DES-56 encrypted archive object. DES-56 encrypted object counts Following the detailed object information, the number of DES-56 encrypted backup objects and the number of DES-56 encrypted archive objects is shown. List of output files At the end of the output, the file names containing the detailed output in tab-delimited format are shown. Here is an example of a command and its output. The output is annotated to indicate the different elements. Annotations begin with "==>". ------------------------------------------------------------------------------- BEGIN SAMPLE COMMAND AND OUTPUT ------------------------------------------------------------------------------- ==> Display detailed information for node storman_api. In particular, check ==> file spaces whose names end with "ata". C:\IC49621>qdes56 storman_api storman xxxxx y "*ata" ==> Program header ****************************************************************** QDES56 - TSM API utility for finding DES-56 encrypted files API Library Version = 5.3.4 (unicode) Copyright (c) IBM Corporation, 2006 ****************************************************************** ==> File space list ------------------------------------------------------------------------------ FILE SPACE NAME TYPE UNICODE ------------------------------------------------------------------------------ \\storman\more_test_data API:Sample NO ArchivedData API:Sample NO ==> Start of detailed information for each DES-56 encrypted object. This is ==> the detailed information for the "\\storman\more_test_data" file space. ------------------------------------------------------------------------------ FSNAME: >\\storman\more_test_data< ------------------------------------------------------------------------------ ==> Here is the detail for each DES-56 encrypted backup object. DES-56 ENCRYPTED BACKUP FILES HL LL OBJID ENCR COMP SIZE EST STATE ------------------------------------------------------------------------------ \IC49621\testbed \test_file_0 0 249865719 DES_56BIT NO 0 1024 A \IC49621\testbed \test_file_1 0 249865720 DES_56BIT NO 0 1024 A \IC49621\testbed \test_file_2 0 249865721 DES_56BIT NO 0 1024 A \IC49621\testbed \test_file_3 0 249865722 DES_56BIT NO 0 1024 A \IC49621\testbed \test_file_4 0 249865723 DES_56BIT NO 0 1024 A \IC49621\testbed \test_file_5 0 249865724 DES_56BIT NO 0 1024 A \IC49621\testbed \test_file_6 0 249865725 DES_56BIT NO 0 1024 A \IC49621\testbed \test_file_7 0 249865726 DES_56BIT NO 0 1024 A \IC49621\testbed \test_file_8 0 249865727 DES_56BIT NO 0 1024 A ==> DES-56 encrypted file counts for file space "more_test_data". Note that the ==> file space has 9 DES-56 encrypted backup objects, and 0 DES-56 encrypted ==> archive objects. ------------------------------------------------------------------------------ FSNAME: >\\storman\more_test_data< Total DES-56 Encrypted Backup files : 9 ------------------------------------------------------------------------------ ==> Here is the detail for each DES-56 encrypted archive object. For this file ==> space, there are no DES-56 encrypted archive objects. DES-56 ENCRYPTED ARCHIVE FILES HL LL OBJID ENCR COMP SIZE EST ------------------------------------------------------------------------------ ------------------------------------------------------------------------------ FSNAME: >\\storman\more_test_data< Total DES-56 Encrypted Archive files : 0 ------------------------------------------------------------------------------ ==> Start of detailed information for the "ArchivedData" file space. ------------------------------------------------------------------------------ FSNAME: >ArchivedData< ------------------------------------------------------------------------------ ==> Here is the detail for each DES-56 encrypted backup object. For this file ==> space, there are no DES-56 encrypted backup objects. DES-56 ENCRYPTED BACKUP FILES HL LL OBJID ENCR COMP SIZE EST STATE ------------------------------------------------------------------------------ ------------------------------------------------------------------------------ FSNAME: >ArchivedData< Total DES-56 Encrypted Backup files : 0 ------------------------------------------------------------------------------ ==> Here is the detail for each DES-56 encrypted archive object. Note that this ==> file space contains 200 DES-56 encrypted archive objects, but most of the ==> repetitive output has been removed. DES-56 ENCRYPTED ARCHIVE FILES HL LL OBJID ENCR COMP SIZE EST ------------------------------------------------------------------------------ \Documents and Settings\Administrator\Local Settings\Application Data\MyApplication\Data \workspace_0 0 249865846 DES_56BIT NO 0 30000 \Documents and Settings\Administrator\Local Settings\Application Data\MyApplication\Data \workspace_1 0 249865847 DES_56BIT NO 0 30000 \Documents and Settings\Administrator\Local Settings\Application Data\MyApplication\Data \workspace_10 0 249865856 DES_56BIT NO 0 30000 ... \Documents and Settings\Administrator\Local Settings\Application Data\MyApplication\Data \workspace_98 0 249865944 DES_56BIT NO 0 30000 \Documents and Settings\Administrator\Local Settings\Application Data\MyApplication\Data \workspace_99 0 249865945 DES_56BIT NO 0 30000 ------------------------------------------------------------------------------ FSNAME: >ArchivedData< Total DES-56 Encrypted Archive files : 200 ------------------------------------------------------------------------------ ==> These messages tell you the file names that contain the detailed output in ==> tab-delimited format. Detailed backup object information written to: qdes56_bkup_detail_storman_api.txt Detailed archive object information written to: qdes56_arch_detail_storman_api.txt ------------------------------------------------------------------------------- END SAMPLE COMMAND AND OUTPUT ------------------------------------------------------------------------------- Below are the contents of the file qdes56_bkup_detail_storman_api.txt. The first line is a column header, and the remaining lines are the tab-delimited details for each DES-56 encrypted backup object. The file can be loaded into a spreadsheet or database application for easier viewing. ------------------------------------------------------------------------------- BEGIN SAMPLE DETAIL FILE OUTPUT ------------------------------------------------------------------------------- FILE SPACE NAME HL NAME LL NAME OBJECT ID (HIGH) OBJECT ID (LOW) ENCRYPTION TYPE COMPRESSED SIZE ESTIMATE (HIGH) SIZE ESTIMATE (LOW) STATE \\storman\more_test_data \IC49621\testbed \test_file_0 0 249865719 DES_56BIT NO 0 1024 A \\storman\more_test_data \IC49621\testbed \test_file_1 0 249865720 DES_56BIT NO 0 1024 A \\storman\more_test_data \IC49621\testbed \test_file_2 0 249865721 DES_56BIT NO 0 1024 A \\storman\more_test_data \IC49621\testbed \test_file_3 0 249865722 DES_56BIT NO 0 1024 A \\storman\more_test_data \IC49621\testbed \test_file_4 0 249865723 DES_56BIT NO 0 1024 A \\storman\more_test_data \IC49621\testbed \test_file_5 0 249865724 DES_56BIT NO 0 1024 A \\storman\more_test_data \IC49621\testbed \test_file_6 0 249865725 DES_56BIT NO 0 1024 A \\storman\more_test_data \IC49621\testbed \test_file_7 0 249865726 DES_56BIT NO 0 1024 A \\storman\more_test_data \IC49621\testbed \test_file_8 0 249865727 DES_56BIT NO 0 1024 A ------------------------------------------------------------------------------- END SAMPLE DETAIL FILE OUTPUT ------------------------------------------------------------------------------- Similarly, here is a partial listing of the qdes56_arch_detail_storman_api.txt file: ------------------------------------------------------------------------------- BEGIN SAMPLE DETAIL FILE OUTPUT ------------------------------------------------------------------------------- FILE SPACE NAME HL NAME LL NAME OBJECT ID (HIGH) OBJECT ID (LOW) ENCRYPTION TYPE COMPRESSED SIZE ESTIMATE (HIGH) SIZE ESTIMATE (LOW) ArchivedData \Documents and Settings\Administrator\Local Settings\Application Data\MyApplication\Data \workspace_0 0 249865846 DES_56BIT NO 0 30000 ArchivedData \Documents and Settings\Administrator\Local Settings\Application Data\MyApplication\Data \workspace_1 0 249865847 DES_56BIT NO 0 30000 ArchivedData \Documents and Settings\Administrator\Local Settings\Application Data\MyApplication\Data \workspace_10 0 249865856 DES_56BIT NO 0 30000 ... ArchivedData \Documents and Settings\Administrator\Local Settings\Application Data\MyApplication\Data \workspace_97 0 249865943 DES_56BIT NO 0 30000 ArchivedData \Documents and Settings\Administrator\Local Settings\Application Data\MyApplication\Data \workspace_98 0 249865944 DES_56BIT NO 0 30000 ArchivedData \Documents and Settings\Administrator\Local Settings\Application Data\MyApplication\Data \workspace_99 0 249865945 DES_56BIT NO 0 30000 ------------------------------------------------------------------------------- END SAMPLE DETAIL FILE OUTPUT -------------------------------------------------------------------------------