Configuration and setup of Tivoli Storage Manager client API

After the installation of the Tivoli Storage Manager client software, the Tivoli Storage Manager client must be configured to communicate with the Tivoli Storage Manager server. In this section, we will only cover how to setup the communication. We assume that the configuration on the Tivoli Storage Manager server is done and validated prior to configuring the client. We assume that the Tivoli Storage Manager server configuration has already been completed and verified prior to configuring the client.

It is possible to configure different management classes for DB2 databases under the same DB2 instance. You can do this by setting the

TSM_MGMTCLASS option. This option is set from the DB2 command line using the syntax.

'db2 update db cfg for <dbname> using TSM_MGMTCLASS <mgmtclass>' (Replace <dbname> and <mgmtclass> with the desired database name and management class.)

The DB2 options that can be set for each database that relate to Tivoli Storage Manager are described in greater detail in 5.5, “Optional DB2 configurations” on page 69.

You can also configure different management classes using the client include/exclude list. This is done by specifying an INCLUDE statement for the database object that is being backed up. You can then add the desired management class to the INCLUDE statement. This works the same way as for the Tivoli Storage Manager Backup-Archive client. The only difference is that the include statement object matches the way DB2 sends the backup object rather than specifying a path and filename. This is described in greater detail in 4.5.3, “Tivoli Storage Manager client include-exclude option” on page 50.

The following information is needed before you begin to configure the client;

ask your Tivoli Storage Manager administrator to get the relevant details.

• Tivoli Storage Manager server name and IP-address

• The nodename by which the API client will be known to the Tivoli Storage Manager server

• The password of the API node

5.3.1 API client setup

Root and instance owner permissions are needed to perform the setup. It is best to create a newly dedicated directory for all Tivoli Storage Manager related configuration and logfiles. Do not use the $HOME/sqllib/adsm directory of the instance owner, because this directory is only a link to the /usr/lpp/db2_07_01/adsm directory and may be overwritten at the next DB2 upgrade. In our lab environment we created and used the directory

$HOME/sqllib/tsm for our working directory. (Also, the

$HOME/sqllib/db2dump directory could be used so that DB2 logfiles and Tivoli Storage Manager logfiles reside together under one directory.) We performed the following steps:

1. Set the environment variables for the API client.The instance owner of your database must set the following environment variables in either the

$HOME/.profile or in the $HOME/sqllib/userprofile file. Note: It is not recommended to define the environment variables in the

$HOME/sqllib/db2profile file, because this file can be overridden when installing fixpaks. These DSMI variables will be read by the Tivoli Storage Manager API client (they all start with DSMI rather than with DSM which identifies those used by the Tivoli Storage Manager Backup-Archive client). The default location for the API is the /usr/tivoli/tsm/client/api/bin directory. (The default directory for the Backup-Archive client is the /usr/tivoli/tsm/client/ba/bin directory.)

The DB2 backup command reads and uses the Tivoli Storage Manager client API configuration.

- DSMI_DIR

Identifies the directory path where the agent file, dsmtca, is located. A korn shell example is:

export DSMI_DIR=/usr/tivoli/tsm/client/api/bin - DSMI_CONFIG

Identifies the full directory path and file name of the Tivoli Storage Manager user options file, dsm.opt. This file contains the name of the server to be used. A korn shell example is:

export DSM_CONFIG=/home/db2inst1/tsm/dsm.opt - DSMI_LOG

Identifies the directory path where the error log file, dsierror.log, is to be created. A korn shell example is:

export DSMI_LOG=/home/db2inst1/tsm

2. Log out and log in again as instance owner so that the environment variables take effect.

3. Create the dsm.sys file.

The root user of your system must create or modify the Tivoli Storage Manager system options file, dsm.sys, which must be located in the /usr/tivoli/tsm/client/api/bin directory.

The sample dsm.sys.smp in the /usr/tivoli/tsm/client/api/bin directory provides the basic information needed for DB2 backup to work.

The passwordaccess parameter must be set to generate. This parameter specifies that Tivoli Storage Manager encrypts and stores the user password locally and generates a new password when the old one expires. Then DB2 is not required to supply a password each time it initializes a session with the Tivoli Storage Manager server.

Note

The following is a sample dsm.sys file. We only need to look at the first stanza. The other stanzas belong to other Tivoli Storage Manager API clients so only part of the dsm.sys file is shown.

SErvername Brazil_db2 * Name of this stanza Figure 18. Example of dsm.sys file

4. Create the dsm.opt file.

The instance owner user can create or modify dsm.opt. This file must be located in the directory specified by the DSMI_CONFIG environment variable.

The dsm.opt file only needs to have one line in it which is a reference to the server stanza in the dsm.sys file. The Servername given here is only a symbolic one and does not need to match the name of the Tivoli Storage Manager server. It is possible to have two or more API clients on the same system (for example, two instances) with different server characteristics.

Each client has its own dsm.opt file pointing to a different stanza in the dsm.sys file.

# cat dsm.opt

SErvername Brazil_db2

5. As instance owner, we stop and start the DB2 instance. This allows DB2 to read the Tivoli Storage Manager configuration performed so far. (DB2 only reads the DSMI environment variables at the time when db2start is issued.)

6. Set the Tivoli Storage Manager password.

Each Tivoli Storage Manager client must have a password to access a server. For that reason, the root user of your system must run the

executable file, dsmapipw, installed in the $HOME/sqllib/adsm directory of the instance owner, to establish and reset the Tivoli Storage Manager password. Make sure that the correct DSMI environments (that of the instance owner) are set when root user executes the dsmapipw program.

When executed, the dsmapipw program prompts you for the:

- Old password, which is the current password for the Tivoli Storage Manager node stored in the server.

- New password, which is the new password for the node.

After that you should check that a new file was created in the

/etc/security/adsm directory that contains the encrypted password. The name of this file is the same as the value specified to the servername option in the dsm.opt file.

If you receive any errors, you should look at the dsierror.log file which will show any API error messages. For a listing of API error messages, see

“Appendix D. API Return Codes with Explanation” in Tivoli Storage Manager Using the Application Program Interface V4R1, SH26-4123, at:

http://www.tivoli.com/support/public/Prodman/public_manuals/storage_mgr /admanual.html

For further help, see Appendix B, “Troubleshooting” on page 277.

If there are multiple DB2 databases under one DB2 instance all databases make use of the same Tivoli Storage Manager client API setup. That means all the database backups will go to the same (the default) management class to which this Tivoli Storage Manager node belongs.

How to configure different management classes for DB2 databases under the same DB2 instance will be covered in 4.5.3, “Tivoli Storage Manager client include-exclude option” on page 50, and 5.5, “Optional DB2 configurations” on page 69.