Storage agent options file

Edit online

The storage agent options file contains the name of the server with which the storage agent communicates, along with other options. Normally, do not change the options file unless your IBM Storage Protect server changes.

The options file for the storage agent is named dsmsta.opt. The dsmsta.opt file is located where the storage agent program was installed. The options file is stored in the following default path:

/usr/tivoli/tsm/StorageAgent/bin
/opt/tivoli/tsm/StorageAgent/bin
c:\program files\tivoli\tsm\StorageAgent

Required options

DEVCONFig file_name

The name of the device configuration file for the storage agent. A typical name for the file is devconfig.

SERVERName server_name

The name of the IBM Storage Protect server with which the storage agent communicates. The DSMSTA SETSTORAGESERVER command inserts this option.

TCPPort number

Specifies the port number on which the server TCP/IP communication driver is to wait for requests for client sessions.

Use different port numbers for the options TCPPORT and TCPADMINPORT to create one set of firewall rules for client sessions and another set for other session types (administrative sessions, server-to-server sessions, SNMP subagent sessions, storage agent sessions, library client sessions, managed server sessions, and event server sessions). If the two port numbers are different, separate threads are used to service client sessions and the other session types. If you allow the two options to use the same port number (by default or by explicitly setting them to the same port number), a single server thread is used to service all session requests.

Additional options

ADMINONClientport

Specifies whether the TCPPORT can be used by administrative sessions. You can specify one of the following values:

YES (default): If the option is set to YES, or if the TCPPORT and TCPADMINPORT are the same value (the default), then the administrative sessions can use the TCPPORT.
NO: If the option is set to NO, and if the TCPADMINPORT value is different from the TCPPORT value, then administrative sessions cannot use TCPPORT.

CHECKTAPEPOS

Specifies whether the IBM Storage Protect server validates the position of data blocks on tape. The CHECKTAPEPOS option applies only to operations by using tape drives. It does not apply to non-tape, sequential-access device classes such as FILE. If the server information about the position does not match the position that is detected by the drive, an error message is displayed, the transaction is rolled back, and the data is not committed to the database.

The default is YES.

The following options are available:

Yes: Specifies that the IBM Storage Protect server validates data position on tape. For drives that support append-only mode, this parameter specifies that IBM Storage Protect enables the drive to also validate the data position during each WRITE operation to prevent data overwrite.
No: Specifies that all data position validation is turned off.
TSMonly: Specifies that the IBM Storage Protect server validates data position on tape. The server does not use append-only mode even if the drive supports the feature.
DRIVEonly: Specifies that the IBM Storage Protect server enables append-only mode for drives that support this feature. The server does not validate the data position on tape.

COMMTimeout seconds

Specifies the maximum number of seconds that the server waits for an expected client message during an operation that causes a database update. The default value is 60. The minimum value is 1. If the length of time exceeds the timeout, the server ends the session with the client. You might want to increase the timeout value to prevent clients from timing out. Clients might time out if there is a heavy network load in your environment or when they are backing up large files.

IDLETimeout minutes

Specifies the maximum number of minutes that a client session can be idle before the server cancels the session. The default value is 15 minutes. The minimum value is 1 minute. You might want to increase the timeout value to prevent clients from timing out if there is a heavy network load in your environment. Note, however, that many idle sessions might prevent other users from connecting to the server.

MAXSessions number_of_sessions

Specifies the maximum number of simultaneous client sessions that can connect with the server. The default value is 25 client sessions. The minimum value is 2 client sessions. The maximum value is limited only by available virtual memory size or communication resources.

MSGSTACKTRACE on|off

Specifies that a list of functions will be shown on the server console, and will also be directed to the activity log after specific messages are issued. The output helps the IBM Storage Protect service team to diagnose specific problems quicker. It is best practice that this option is set to ON.

RESOURCETimeout minutes

Specifies the maximum number of minutes that a storage agent waits for a resource on the server. The default value is 60 minutes. The minimum value is 1 minute.

For database resources and sessions on the storage agent, the IBM Storage Protect resource monitor picks the shortest timeout value to start a recovery process.

In contrast, in the case of library sharing, the resource monitor picks the longest time for both the library manager and library client to recover. For more efficient management of shared library resources, consider setting resource timeouts at the same limit for all participants in a shared configuration. In any case of error recovery, IBM Storage Protect always defers to the longest timeout limit.

You should also specify this option in the server options file. The server uses this option to monitor some of the storage agent sessions and resources and cancel sessions that are based on the value you specify.

Important: If this option is specified in the server options file, that value overrides the value that is specified in the storage agent's options file.

SANDISCOVERY

Specifies whether the IBM Storage Protect SAN discovery function is enabled. When set to ON, the storage agent uses SAN discovery in the following instances:

During storage agent initialization
When the device path is changed and there is a conflict between the device serial number and the device path that is provided by the server

SANDISCOVERY OFF is the default value for AIX, Linux, HP-UX, Oracle Solaris, and 64-bit Microsoft Windows.

The following options are available:

ON: Specifies that the server uses SAN discovery when the device path is changed, or when the QUERY SAN command is issued.
OFF: Disables the SAN discovery function but does not take the device path offline. Set the SANDISCOVERY option to OFF if the HBA used by the storage agent does not support SAN device mapping.
UNSCANNEDPATHOFF: Disables the SAN discovery function and takes the device path offline if the server is unable to open it.

Using SAN discovery, the storage agent can automatically correct the special file name of the device if it is changed. If the HBA used by the storage agent does not support SAN device mapping, set the SANDISCOVERY option to OFF.

For information about IBM Storage Protect supported HBAs for SAN device mapping, see the IBM Storage Protect for Storage Area Networks support site.

The storage agent does not require persistent binding with the SAN discovery function enabled.

Linux operating systems AIX operating systems To help with problem determination, you can use the dsmsanlist module to obtain information about devices on a storage area network (SAN). The dsmsanlist module is installed by default when the Tivoli Storage Manager storage agent is installed.

AIX operating systems SAN-discovery functions on AIX require root user authority. To allow root and non-root users to use SAN discovery, a special utility module, dsmqsan, is started when a SAN-discovery function is started. The module uses the SAN-discovery function as root. Non-root users that start a SAN-discovery function get root privileges specifically for SAN discovery. While SAN discovery is in progress, dsmqsan runs as root.

AIX operating systems The dsmqsan module is installed by default when the IBM Storage Protect server is installed. It is installed with owner root, group system, and mode 4755. The value of the SETUID bit is on. If, for security reasons, you do not want non-root users to run SAN-discovery functions, set the bit to off. If non-root users have problems with SAN-discovery functions, check the following settings and access:

The SETUID bit. It must be set to on.
Device special file permissions and ownership. Non-root users need read/write access to device special files, for example, to tape and library devices.
The SANDISCOVERY option in the server options file. This option must be set to ON

AIX operating systems The dsmqsan module works only for SAN-discovery functions, and does not provide root privileges for other IBM Storage Protect functions.

SSLTCPADMINPORT

Specifies the port address on which the server TCP/IP communication driver waits for requests for sessions that are enabled by Secure Sockets Layer (SSL). The sessions are for the command-line administrative client.

When you use the SSLTCPADMINPORT or SSLTCPPORT option and start the server, a key database file cert.kdb is created. The key database file is created in the server instance directory and is initialized with a self-signed certificate.

The following types of sessions do not use SSL:

NDMP (Network Data Management Protocol)
ACSLS (Automated Cartridge System Library Software)
SNMP (Simple Network Management Protocol) subagent

If the ADMINONCLIENTPORT option is set to NO, SSL-enabled sessions for the administrative client require SSLTCPADMINPORT with a port number other than one specified by the SSLTCPPORT option. The SSLTCPADMINPORT option does not affect the TCPPORT or TCPADMINPORT options and their interaction with the ADMINONCLIENTPORT option.

The TCP/IP communications driver must be enabled with COMMMETHOD TCPIP or COMMMETHOD V6TCPIP.

SSLTCPPORT

Specifies the Secure Sockets Layer (SSL) port number. The server TCP/IP communication driver waits for requests on this port for SSL-enabled sessions from the client.

The following types of sessions do not use SSL:

NDMP (Network Data Management Protocol)
ACSLS (Automated Cartridge System Library Software)
SNMP (Simple Network Management Protocol) subagent
Database restore operations

If the ADMINONCLIENTPORT option is set to NO, SSL-enabled sessions for the administrative client require the SSLTCPADMINPORT option with a port number different from one specified by the SSLTCPPORT option. The SSLTCPPORT option does not affect the TCPPORT or TCPADMINPORT options and their interaction with the ADMINONCLIENTPORT option.

The TCP/IP communications driver must be enabled in the appropriate client options file with COMMMETHOD TCPIP option or COMMMETHOD V6TCPIP option. The backup-archive client supports either the COMMMETHOD TCPIP option or the COMMMETHOD V6TCPIP option, but not both at the same time.

STAKEYDBPW

Specifies the password that is used to verify and control access to the SSL key database. The user cannot edit the value of STAKEYDBPW.

STAMaxpooledsessions number

Specifies the number of individual sessions that are allowed to start and stop between the storage agent and the IBM Storage Protect server. The range of values is 0 - 150, with a default of 25. Each session is governed by the IDLETIMEOUT option and is stopped when the timeout value is exceeded. If the storage agent needs more sessions than specified, extra sessions are allowed. Although the default value is typically sufficient, setting this option with a low number can adversely affect performance. If the storage agent has multiple client sessions, increasing the value of this option helps to support these sessions.

TCPADMINPORT number

Specifies the port number on which the server TCP/IP communication driver is to wait for requests for sessions other than client sessions. Non-client sessions include administrative sessions, server-to-server sessions, SNMP subagent sessions, storage agent sessions, library client sessions, managed server sessions, and event server sessions. The default is the value of TCPPORT.

Use different port numbers for the options TCPPORT and TCPADMINPORT to create one set of firewall rules for client sessions and another set for the other non-client session types. By using the SESSIONINITIATION parameter of REGISTER NODE and UPDATE NODE, you can close the port that is specified by TCPPORT at the firewall, and specify nodes whose scheduled sessions are started from the server. If the two port numbers are different, separate threads are used to service client sessions and the session types. If you allow the two options to use the same port number (by default or by explicitly setting them to the same port number), a single server thread is used to service all session requests.

Client sessions that attempt to use the port that is specified by TCPADMINPORT is terminated (if TCPPORT and TCPADMINPORT specify different ports). Administrative sessions are allowed on either port, (unless the ADMINONCLIENTPORT option is set to NO) but by default uses the port that is specified by TCPADMINPORT.

THROUGHPUTDatathreshold kilobytes_per_second

Specifies the throughput that client sessions must achieve to prevent cancellation after THROUGHPUTTIMETHRESHOL minutes elapses. The default value of 0 prevents examining client sessions for insufficient throughput. Throughput is computed by adding the send and receive byte counts and dividing by the length of the session. The length does not include time that is spent waiting for media mounts and starts at the time a client sends data to the server for storage. The minimum value is 0; the maximum is 99999999.

THROUGHPUTTimethreshold minutes

Specifies the threshold for examining client sessions and canceling them if the data throughput threshold is not met (see THROUGHPUTDATATHRESHOLD). This threshold does not include time that is spent waiting for media mounts. The time threshold starts when a client begins sending data to the server for storage (as opposed to set up or session housekeeping data). The default value of 200 prevents examining client sessions for low throughput. The minimum value is 0; the maximum is 99999999.

USELARGEBUFFERS yes|no

Specifies that large buffers are used for client/server communications. The default of YES specifies that large buffers are used; NO specifies that they are not used.