Using the TSM command line
UNIX Server Command Line
To start a TSM server command line in AIX, you use the dsmadmc command with an optional servername. The command line is useful if you want to do bulk upgrades, as you can then do them with a script. For example, if you want to register 10 new nodes, rather than go through the tedium of adding 10 nodes through a panel, it is much easier to set this up as 10 commands within a UNIX script, then just execute the script. A typical script could look like
dsmadmc -se=servername -id=youruserid -pa=yourpassword register node nodename nodepassword passe=9999 con=\"This server contact details\" do=policy-set clo=cloptset userid=none comp=no archdel=no backdel=no etc.
you obviously need to substitute your own values for the parameters, and note how special characters like quotes are escaped out with a forward
Other dsmadmc options
The command can also be very useful if you want to start up a session to a TSM server in different modes. for example, if you want to run some queries that you want to feed into an excel spreadsheet or maybe programs, and you do not want the screen titles displayed you would use the following. -comma means comma delimited output, the dataonly switch suppresses the headers.
dsmadmc -se=servername -dataonly=yes -comma
an alternate option is -tab for tab delimited. These commands can be usefully argumented with the -out parameter, which writes the console output into an external file. For example if you start a server session as below, then the output of any commands you issue will be placed in sqlout.txt
dsmadmc -se=servername -dataonly=yes -comma -out="c:\program files\tivoli\tsm\sqlout.txt"
Three other useful options are
The first one starts a server session in console mode, so all the console messages automatically scroll past your terminal. This is useful if you are waiting for a process to complete, as it saves you from keep typing q actlog or q pr commands.
The second option is similar, but instead of displaying all the console messages, it just displays tape mount messages. This one was intended for a media librarian that had to mount tapes manually
The Third option suppresses the 'do you really want to do this' type messages, for example if you run a query that will produce a lot of output, you will see a message like, 'Do you wish to proceed? (Yes (Y)/No (N))'. -noconfirm will suppress these messages, but obviously you need to use it with care as the messages can be very useful. For example, if you start to delete objects, the confirmation message gives you a second chance to check that you are not deleting items by accident.
Logging into a remote TSM server
With TSM servers running on Windows, you can log into any remote TSM server, provided you have the dsmadmc command code loaded with your TSM client, and provided your firewall rules permit remote access. If you have a remote server on a Windows box with IP address 22.214.171.124 and with a DNS name of WSTSM01, you can start a session by navigating to \program files\tivoli\tsm\baclient and running either
If you get a message like "dsmadmc not found" then you've got a basic client install and you need to install the server management component.
This works on the IP address of the Windows box that is hosting TSM. What if you are running more than one TSM server on that box? By default you will get TSM Server1. To reach the other servers you need to add a -tcpp switch that specifies the port of the other server
dsmadmc -tcps=WSTSM01 -tcpp=1502
back to top
Canceling sessions and processes
To cancel server processes like migration you need to know the process number, which you get with the Q PROCESS command. However note that if you cancel a migration session then a new one will start unless you also reset the pool thresholds.
CANCEL PROCESS process-number
To cancel tape mount requests use the command
CANCEL REQUEST request-number
CANCEL REQUEST ALL
To cancel active sessions you either need to know the session numbers, which you get with the Q SESSION command, or you can cancel all active sessions
CANCEL SESSION request-number
To prevent new sessions or processes from starting use
DISABLE SESSION client
DISABLE SESSION Server
DISABLE SESSION Admin
These commands just prevent new sessions from starting. All active session will run to completion unless you cancel them with the cancel command. The disable session server command will stop new server to server sessions from starting, it will not stop expiration or migration.
To do an emergency cancel of all sessions use the command
DISABLE SESSION ALL
CANCEL SESSION ALL
back to top
How to determine when TSM will expire a backup
The key to understanding TSM backup retention is to understand the difference between 'active' and 'inactive' backups. The 'active' backup is the most recent backup while all the older backups are 'inactive backups'. However, once a file is deleted from the client, it becomes inactive after the next incremental backup. The active backup of a file is never deleted, as it is needed to recreate a disk
TSM uses 4 parameters to retain backups.
- 'Versions Data Exists' is used to determine the maximum number of backup versions that will be retain for files that currently exist on the client.
- 'Versions Data Deleted' is used to determine the maximum number of retained backups for files that have been deleted from the client.
- 'Retain Extra Versions' specifies the number of days that inactive backups are kept.
- 'Retain Only Version' controls how long to keep the last backup of a file that has been deleted from the client.
The version parameters and the retain extra parameter can take a value of 1-9999 or NOLIMIT, while the retain only parameter can take these values and also take a value of 0.
There is a fundamental difference between the versions parameters and the retain parameters. The versions parameters are controlled by the backup function, so changes to versions will not take effect until the next backup runs. The retain parameters are controlled by expiration, so changes to retention parameters take effect immediately.
The pecking order goes like
If the file is deleted, then the most recent backup is kept for the number of days specified in 'retain only version', while older backups are retained by whichever of 'retain extra versions' and 'versions data deleted' is met first
If the file is not deleted, then the most recent or 'active' backup is kept forever, while older backups are retained by whichever of 'retain extra versions' and 'versions data deleted' is met first
For example, you have RETEXTRA=31 and VEREXISTS=31. If you create 31 versions in the same day, and then (still on the same day) you create version 32, version 1 will expire, regardless of RETEXTRA, because the VEREXISTS criterion has been exceeded. Likewise, if you create version 1 today, then create version 2 a week later, then never create another version after that, then version 1 will expire 31 days after the creation
of version 2, since the RETEXTRA criterion has been exceeded.
If you need to GUARANTEE data retention for 31 days you would need to code the parameters as below, but be aware that you could end up keeping a lot of backups.
Versions Data Exists = NOLIMIT
Versions Data Deleted = NOLIMIT
Retain Extra Versions = 31
Retain Only Version = 31
back to top
How to list out backups that are marked for expiration
How can you find out which backups have been marked for deletion?
Backups and Archives are marked for deletion when their expiry date or version limit is reached, or if they are deleted manually, but they are not purged from the TSM database until the next Expire Inventory is run.
TSM flags files that are eligible by giving them a special deactivation date, which is 1900-01-01. Then when an Expire Inventory process runs, any objects which have deactivate_date of 1900-01-01 are removed from the database.
It is possible to generate a list of these files with SQL queries, but be aware that the file listing might be very large and generating it might degrade your server performance. The date format is slightly different between TSM 5.x and TSM 6.x servers. Suitable SQL queries are:
select node_name,state,backup_date,hl_name,ll_name from backups where deactivate_date='1900-01-01 00:00:00.000000' AND type='FILE'
TSM 6.x onwards
select node_name,state,deactivate_date,backup_date,hl_name,ll_name from backups where deactivate_date='1956-09-05-00.00.00.000000' and type='FILE'
The query output will still return a deactivation_date of '1900-01-01 00:00:00.000000' even though you specified '1956-09-05-00.00.00.000000' on the SQL query. That's just the way TSM stores the date.
back to top
MAXSESSIONS and MAXSCHEDSESSIONS
TSM limits the maximum number of sessions it will run at any time to try to prevent performance issues by runnng too many tasks at once. This is controlled by the MAXSESSIONS server option, but the default value is quite low at 25 client sessions. If you have it set too low you will see errors like
ANR0429W Session xxx refused maximum server sessions exceeded.
You can update this server option without stopping and restarting the server by using a SETOPT command like this
The value you would use depends on how many sessions you are trying to run and how much resources you have available. There is no definite rule here, it very much depends on your environmeent. IBM states that 'the maximum value is limited only by available virtual storage size or communication resources'. So how do you know if you have increased it too far and you are getting performance issues? Check that your database cache hit is at least 98% by running the q db f=d command.
There are two types of session, scheduled and unscheduled. Unscheduled includes things like restores and retrieves. You can limit the number of sessions available to scheduled operations, to ensure that unscheduled operations can run, using the set maxschedsessions command. The command to do this is set maxschedsessions followed by a percentage. It may be a better option to increase maxschedsessions rather than maxsessions if maxschedsessions is set too low.
You may often see the number of active client sessions exceeding the maxschedsessions value. A scheduled session is a type 5 session, a generated session is a type 4 session. When a node starts a scheduled backup to the storage manager server, only the initial session is opened as a type 5 session. All other sessions opened as part of the node's scheduled operation are of type 4. Only type 5 sessions count when calculating the number of scheduled sessions.
To find out what MAXSCHEDSESSIONS is set to, run the 'SHOW CSVARS' command. Output looks like
ANS8000I Server command: 'show csvars'
Max %% Scheduled Sessions : 50
Max Scheduled Sessions : 100
The command output shows that there are 100 type 5 sessions available for schedule backups. The 'SHOW SESSIONS' command will then tell you what type of sessions are active. Output typically looks like
ANS8000I Server command: 'show sessions'
Session 73568: Type=Node, Id=TSM_PRW51120_ORA
Platform=AIX, NodeId=537, Owner=
SessType=5, Index=0, TermReason=0
Session 73867: Type=Node, Id=TSM_PRW51120_ORA
Platform=AIX, NodeId=537, Owner=
SessType=4, Index=6, TermReason=0
Now count all the 'SessType=5' sessions in the SHOW SESSIONS output and see how close you are to the maxschedsession limit. If you are still getting ANR0429W errors and you cannot increase maxsessions further, consider increasing the maxschedsession limit, and if you cannot do that your only other option is to spread your backup schedules out to reduce the load at any one time.
back to top
Running processes in parallel
It is mentioned in the Administrator's Guide manual that running multiple processes simultaneously might lead to process termination and it is recommended to avoid the situation if possible. If you run data movement or delete operations, like pool migration, simultaneously with data access operations like storage pool backup, they can contend and one process may terminate early but report completion without errors.
You need to run such processes serially to avoid this happening. Examples include running 'storage pool backup' alongside 'reclaim storage pool' and running 'copy activedata' alongside 'reclaim stgpool'
back to top
Which IP ports does TSM need open on a firewall?
This is a list of listener ports that various Tivoli Storage Manager products expect other hosts to connect to, and may be useful in firewall setup. This applies to Tivoli Storage Manager version 6.2.2 and higher
Tivoli Storage Manager server configurable listener ports
Operating system ports which the Tivoli Storage Manager server might use
Tivoli Storage Manager client configurable listener ports
(*)WEBPORTS: If a firewall is used with the dsmcad scheduler and/or webclient, the WEBPORTS option MUST be manually set. Typically WEBPOTS will use 1552 and 1553.
Tivoli Storage Manager Administration Center version 6.1 listens on http ports 9043 or 9044.
Tivoli Storage Manager Administration Center version 6.2 listens on http port 16310 and https port 16316. Connecting to 16310 simply redirects the connection to the https port.
back to top
The TSM team introduced a new function in version 6.3, the ability to replicate TSM nodes, or client backups, between TSM servers. This means that you can have two active copies of your backups in two different locations, giving you an instant ability to recover servers in a disaster. You can also recover data from the replicated site to the live site.
The easiest way to manage this is to combine similar nodes into node groups, so you work with groups of nodes rather than hundreds of individual nodes.
Assuming you have 2 servers called PROD_SERVER and DR_SERVER with IP addresses 126.96.36.199 and 188.8.131.52 then you would set replication us like this:
Define the production TSM server to DR TSM server ..
define server PROD_SERVER SERVERPA=password hla=200.100.100. lla=1500
set replserver PROD_SERVER
.. and the DR TSM server to the Production TSM Server
define server DR_SERVER SERVERPA=password hla=184.108.40.206 lla=1500
set replserver DR_SERVER
Create a TSM node group on both TSM servers and add some nodes to it
define nodegroup repl_group desc="Node Group for Replication"
define nodegroupmember repl_group node1
define nodegroupmember repl_group node2
define nodegroupmember repl_group node2
On the production TSM server, enable replication for each node:
update node node1 replstate=enabled
update node node2 replstate=enabled
update node node3 replstate=enabled
On the production TSM server, add an admin schedule to run the replication:
define schedule replicate_nodes type=admin cmd="replicate node repl_group wait=yes" desc="3 Hourly Node Replication Schedule" dayofweek=any period=3 perunits=hours active=yes starttime=00:00
Now all 3 nodes will replicate their backup data to the DR server every three hours. You can check the progress of replication with the Query Process command.
Note that if the nodes are deduplicated then the 'Amount Transferred' represents the deduplicated bytes sent. Also, if you keep issuing the Query Process command you will notice that the replication statistics keep changing. This is normal. When older releases of TSM started to run processes like replication they would sit for a long time while they worked out what to do. This could be a bit worrying as it looked like the process had hung. Now, TSM will batch the work up and start processing as soon as it determines the first batch. Filespaces can be in 4 states as shown in the output above.
Identifying: means the server is still looking at the objects in the file space and have not yet dispatched any batches for replication.
Identifying and Replicating: means the server is still looking at the objects (Identifying) but is also moving objects (Replicating).
Replicating: means the server is done looking at the objects (in the file space) and is just replicating.
Complete: means the server finished the file space.
If you try to use the QUERY OCCUPANCY command to check that your replication is working, by looking to see if your target node has the same amount of data as your source node, then you will get confusing results. This is because the QUERY OCCUPANCY command includes data residing in copy storage pools and active-date storage pools and this data is not replicated. You would need to use a SELECT command that just looked at the file count and data in the primary pools, something like this;
select sum(a.NUM_FILES) as "# of files", sum(a.LOGICAL_MB) as "Logical(MB)" from occupancy a, stgpools b where a.stgpool_name=b.stgpool_name and b.pooltype='PRIMARY'
By default the REPLICATE NODE command uses the "DATATYPE=ALL" parameter. If you use a different value for this parameter, then you will need to adjust your SELECT command by using the 'type' parameter in your 'where' clause for the occupancy column.
back to top
Investigating install problems
If you have problems when installing either a TSM server or the Admin centre, both installs create a log.zip file that can be used to work out what went wrong. log.zip contains a collection of log files for the TSM server, the DB2 Database and the Admin Centre. The location of these files depends on the operating system, and can be found in :
C:\IBM\AC\logs.zip ...Admin center logs
C:\Program Files\Tivoli\TSM\logs.zip ...TSM server logs
back to top
Synchronising your TSM server with the OS
If your TSM server is out of step with your hosting server, possibly due to a daytime savings change, you can easily change TSM to match the OS server by entering the following command at the admin command line
back to top
Setting up an Enterprise Server
Controlling and managing several TSM servers with hundreds of clients can be a headache, if only when working out which client is managed by which server. TSM offers the Enterprise Configuration facility to make this easier. This lets you create and distribute settings and configurations from one configuration TSM server to several managed TSM servers.
You start with the TSM server that is going to be the configuration server.
From the Object view, select Server - Server Groups, then 'Define New Server Group' from the drop down menu. Give this group a meaningful name and description, add it, then select 'Server Group Members' and add the TSM servers that you want to be associated with this group.
On that server GUI, open Operational View; Configuration Manager Operations option and select 'Establish this server as a configuration manager', set the configuration manager drop down window to 'ON' and press the Finish button (or use console command SET CONFIGMANAGER ON)
Next, you need to select the 'managed server operations' menu
The configuration manager works on profiles, which are used to collect the objects that are to be managed together, so they can be managed with a single command.
You select the 'define a new Configuration Profile' option from the drop down menu, then you will be presented with a list of objects that can be managed by this profile. The available objects are:
- Managed administrators
- Managed policy domains
- Managed command schedules
- Managed scripts
- Managed option sets
- Managed server definitions
- Managed server groups
You can then define which of these objects will be managed centrally. However it is not as simple as this, as, for example, if you decide to centrally manage all your command schedules, then they need to be identical on every server in the group. Installing an Enterprise Configuration is a good opportunity to clean up and standardise your TSM estate
Once you get the configuration manager setup, you then need to log onto each of your managed servers, and subscribe each one to the profile that you just created. Suppose you called it WINDOWS-PROD and your Configuration Manager server was called CONF-MAN, then you would issued the command
define subscription WINDOWS-PROD server=CONF-MAN
What does this all mean?
Suppose that you defined a server group called WINDOWS that contains all your Windows TSM servers. You can now send commands to all your Windows TSM servers by prefixing your command with WINDOWS:
WINDOWS: Q DB
WINDOWS: upd stg cartpool reclaim=40
Suppose you defined your WINDOWS-PROD profile to control administrators, client schedules and admin schedules. They are all centrally managed by the CONF-MAN server now and you can only make changes to your managed servers by applying the updates to CONF-MAN then distributing the changes out to the managed servers by issuing the command
NOTIFY SUBSCRIBERS PROFILE=*
From the CONF-MAN server. This both simplifies management and maintains consistency across all TSM servers.
back to top
How to Configure a TSM Server on a Windows 2008 R2 Cluster
IBM recommends that you use the configuration wizard, but if you can't use it, here is how to configure a TSM server manually.
You need to run through the process below as a domain user, and you need a windows 2008 R2 cluster with mscs cluster enabled, shared disk resources under a resource group and a dedicated IP address with a corresponding DNS entry for the TSM server itself.
Install the server software
First, install the Tivoli Storage Manager server package on all cluster nodes. As always, we will make up some names to make the examples below more meaningful, but
these are our names, you should use names that fit your site standards. The TSM instance will be called tsm_server1 and the db2 user account will be tsm_user1. The instance location will be d:\tsm\tsm_server1
Create a server instance on all cluster nodes, using the db2icrt command. You will be prompted for the password for user ID tsm_user1, and we will just use 'passw0rd'.
db2icrt -u tsm_user1 tsm_server1
Update DB2 Parameters
Change the default path for the database to be the drive where the instance directory for the server is located. Open up a DB2 command line from
Start - Programs - IBM DB2 - DB2TSM1 -Command Line Tools - Command Line Processor.
Enter quit to exit the command-line processor and a window with a command prompt should now be open, with the environment properly set up to successfully issue the commands in the next steps.
From the command prompt in that window, issue the following commands to set the environment variable for the server instance that you are working with, change the default drive, then set the DB2 code page
db2 update dbm cfg using dftdbpath d:
db2set -i tsm_server1 DB2CODEPAGE=819
Create a new server options file as described in the Configuring server and client communications section of the manual, then on each node do the following steps:
- cd /d c:\windows\cluster
- regsvr32.exe /s /u TsmSvrRscExX64.dll
- cluster resourcetype "TSM Server" /delete
- copy ...\program files\tivoli\tsm\console\TsmSvrRscX64.dll c:\windows\cluster
- copy ...\program files\tivoli\tsm\console\TsmSvrRscExX64.dll c:\windows\cluster
- regsvr32.exe /s TsmSvrRscExX64.dll
- Create the TSM server service by issuing the following command:
sc create "TSM tsm_server1" -
binPath="d:\program files\tivoli\tsm\server\dsmsvc.exe -
-k tsm_server1" start= demand obj= "test\tsm_user1" password=passw0rd
On the primary node only, issue the following command to create the cluster definitions for DB2. This command creates the definitions by reading a configuration file which by default is called db2mscs.cfg and is located in subdirectory /CFG in the DB2 install directory
Run db2mscs - ie db2mscs -f:db2mscs.cfg
The db2mscs.cfg fille contains various parameters that are explained here
Now stop the db2 resource with the following command
cluster resource tsm_server1 /offline
Format the database
ONLY if you are setting up a new instance, format the TSM server database with the following command, which you run from the TSM server instance directory. Adjust the names shown to fit your site.
dsmserv -k tsm_server1 format dbdir=d:\tsm\db001 activelogsize=8192 activelogdirectory=e:\tsm\activelog archlogdirectory=f:\tsm\archlog archfailoverlogdirectory=g:\tsm\archfaillog mirrorlogdirectory=h:\tsm\mirrorlog
If you want to know more about the DSMSERV FORMAT command, check out the TSM Server Administration manual.
Copy the Registry Key
Export the registry key below and import it on all secondary nodes
Sort out the cluster resources
Issue the following commands to create the TSM server resource - again, substitute your names in the commands below
cluster resourcetype "TSM Server" /create /DLL:tsmsvrrscX64.dll /type:"TSM Server"
cluster resource "TSM tsm_server1 Server" /create /group:"TSM tsm_server1 Group" /type:"TSM Server"
cluster resource "TSM tsm_server1 Server" /adddep:"tsmclustsrv1"
cluster resource "TSM tsm_server1 Server" /adddep:"tsm_server1"
Add dependencies for each shared disk resource, starting with the disk where the instance is found:
cluster resource "TSM tsm_server1 Server" /adddep:"disk_name"
cluster resource "TSM tsm_server1 Server" /adddep:"disk_name"
.. repeat for all shared disk resources
Issue the following to set the location for the console log. If the TSM server resource will not come online you need this log to find out what the problem is.
cluster resource "TSM tsm_server1 Server" /privprop service="TSM tsm_server1"
Set password and start server
Run dsmsutil on all nodes including the primary node to set the $$_TSMDBMGR_$$ password.
UPDATEPW /NODE:$$_TSMDBMGR_$$ /PASSWORD:passw0rd /VALIDATE:NO /OPTFILE:
Bring the cluster resource online with the following command.
cluster resource "TSM tsm_server1 Server" /online
Now log into your server and run some of your favourite commands to check that all is well.
Scheduling - controlling the start time
Ever been in the situation where you have a tight backup window (and if you haven't, how do you get a job like that?) You schedule 8 backups to start at midnight, but some of them don't start until 01:00? Frustrating or what?
The problem is that by default, TSM tries to spread backups out in a schedule, unless you tell it not to. Issue the command QUERY STATUS on your TSM server, and look for the parameter Schedule Randomisation Percentage. By default, this will be set to 25, which means TSM will spread the start times of all the backups in a schedule, over the first 25% of the schedule window.
If you want all your backups to fire in right at the start of the schedule, then change this parameter to 0.
If you get a problem with the schedule, the error will be either 'failing' or being 'missed'. 'Failed' means that the scheduled event began, but encountered an error condition that prevented it from completing successfully. 'Missed' means that the scheduled event never began. For example, if the scheduler is not running on the client, then of course it can not execute its scheduled events; nor can it report that it did not run.
On the client machines that missed their schedule, verify that the scheduler service is started. Check the dsmsched.log and dsmerror.log to verify that the scheduler was able to successfully contact the server and query its next scheduled event.
back to top
Scheduling - choosing specific weekdays
If you define your client schedules using the GUI interface, you can chose to run a backup every day, weekdays only, or on a specific day of the week. You can only chose one of these options. If you use a command line, you can be more selective. Say you want to define a schedule to run every Monday, Wednesday and Friday. Use a command like the one below. Note the SCHEDS=E parameter, which means use enhanced schedule style. You need enhanced style to pick out individual weekdays.
DEF SCH domain_name schedule_name T=C ACT=I STARTT=22:00:00 DUR=1 SCHEDS=E DAY=Monday,Wednesday,Friday
Another possible option is to schedule a backup to run on the last Sunday of the month. An appropriate command is
DEF SCH domain_name schedule_name T=C ACT=I STARTT=22:00:00 DUR=1 SCHEDS=E DAY=Sunday WEEK=LAST
back to top
Scheduling a one-off backup
If you want to run an immediate, one-off scheduled backup of a client, the easiest way to do this is to use the DEFINE CLIENTACTION command. The basic syntax is
define clientaction 'node_name' domain='domain_name' action=incremental
where you substitute your own node and domain names. TSM will then define a one-off schedule and associate the client node with that schedule. TSM will generate the schedule name, and return that name to the server console with messages ANR2500I and ANR2510I. You can use most of the parameters that are available to the define schedule command, like the 'OPTIONS' and 'OBJECTS' parameters, if you need to expand on this command.
The term 'immediate' should not be taked too literally, as what happens next depends on how your client scheduling mode is defined. If the schedule mode is PROMPTED, then the schedule is added to the list of schedules waiting to execute, and will normally run within 5 minutes or so.
If the client scheduling mode is POLLING, then the schedule will run next time the client scheduler polls the server to see if a schedule is waiting and that could take some time. The best action, is to recycle the DSMCAD or the scheduler daemon/service at the client end once you run the define clientaction command at the server, and that should immediately trigger the schedule.
back to top
Incremental backup of multiple directories using the objects field
To perform an incremental backup for several directories, code them in the
objects field in the schedule like this.
OBJECTS='/path1/ /path2/ /etc/'
The terminating slash at the end of the directory name backs up the files within the directories, and they need to be separated by spaces. If you wish to back up subdirectories within these directories, then you also need
back to top
Which nodes are associated with each schedule
The command syntax is 'query association domain-name schedule-name'. You can query all associations by using
q assoc * *
If you want to query a specific schedule, but do not know the domain, use
q assoc * sched-name
back to top