1. Introduction
This section will first provide an introduction to the TSM Command Line Interface (CLI) and then describe how to manually back up and restore files on the local machine. The screen shots and descriptions that follow may refer to older TSM clients, but with the exception of the file specifications the syntax is generic to all platforms.
2. Starting the TSM Command Line client
2.1. Windows
Run [Backup-Archive Client Command Line] from [Start] | [All Programs] | [Tivoli Storage Manager]. The TSM command line interface will open in a DOS window on the Windows desktop. This window will be small but you can toggle between that and a full screen by typing Alt + Enter.
2.2. Mac
Open [Terminal] from [Applications] | [Utilities] and type sudo dsmc. You should see a prompt of the form:
IBM Tivoli Storage Manager
Command Line Backup/Archive Client Interface
Client Version 5, Release 5, Level 2.0
Client date/time: 18-06-2009 11:36:37
(c) Copyright by IBM Corporation and other(s) 1990, 2008. All Rights Reserved.
Node Name: ABCD1234-LAPTOP-OUCS
Session established with server OX_HFS_B3: AIX-RS/6000
Server Version 5, Release 5, Level 1.1
Server date/time: 18-06-2009 11:36:37 Last access: 18-06-2009 02:51:30
tsm>
2.3. Unix/Linux
Run dsmc as root from the shell prompt (e.g., in Ubuntu, run sudo dsmc). You should see a prompt of the form:
IBM Tivoli Storage Manager
Command Line Backup/Archive Client Interface
Client Version 5, Release 5, Level 2.0
Client date/time: 18-06-2009 11:36:37
(c) Copyright by IBM Corporation and other(s) 1990, 2008. All Rights Reserved.
Node Name: ABCD1234-LAPTOP-OUCS
Session established with server OX_HFS_B3: AIX-RS/6000
Server Version 5, Release 5, Level 1.1
Server date/time: 18-06-2009 11:36:37 Last access: 18-06-2009 02:51:30
tsm>
2.4. Netware
Type load dsmc at the console.
3. Accessing Help
Online help for TSM commands, options and error messages is available by typing help at the tsm> prompt. The result will be similar to below:
The following help topics are available.
Enter the number of the desired help topic or 'q' to quit,
'd' to scroll down, 'u' to scroll up.
0 - Summary of Changes
1 - Using Commands
2 - Select from the commands listed below:
3 - ARCHIVE
4 - BACKUP DB2UDB
5 - BACKUP GROUP
6 - BACKUP IMAGE
7 - BACKUP NAS
8 - BACKUP WAS
9 - CANCEL PROCESS
10 - CANCEL RESTORE
11 - DELETE ACCESS
12 - DELETE ARCHIVE
13 - DELETE BACKUP
14 - DELETE FILESPACE
15 - DELETE GROUP
16 - EXPIRE
17 - HELP
18 - INCREMENTAL
Note that commands and options may be abbreviated to a short form as indicated by capitalisation of words in the syntax entry for a command. Thus, for example, query filespace can be abbreviated to q fi. Options and commands can also be included on the original command line so, using the above example, on a Netware machine you can run load dsmc q fi to just run a query of the current partitions backed up. Obviously, more complex queries and commands can be similarly run in the same manner.
4. Querying the server
On starting the TSM CLI, no information about your current configuration settings or filestore is displayed. By default, the TSM CLI will output the results of a query in one, uninterrupted stream, with the result that much of the output scrolls off-screen. This is particularly inconvenient when querying the backup for a list of files. To manage this and ensure query results are returned one screen at a time edit the dsm.opt file, add the following two lines and then restart the CLI:
ScrollPrompt Yes
Scrolllines 30 * where this number equates to your window size
The following query commands illustrate typical command syntax and output.
4.1. Querying your scheduled backup slot
To query your scheduled backup slot enter q sched (which is short for query schedule). The output should look similar to that below:
tsm> q sched
Schedule Name: WEEKLY_OUCS
Description: OUCS weekly incremental backup
Schedule Style: Classic
Action: Incremental
Options:
Objects:
Priority: 5
Next Execution: 149 Hours and 35 Minutes
Duration: 15 Minutes
Period: 1 Week
Day of Week: Wednesday
Expire: Never
4.2. Querying what files are included / excluded for backup
At the tsm> prompt enter q inclexcl to list output similar to the following:
tsm> q inclexcl
*** FILE INCLUDE/EXCLUDE ***
Mode Function Pattern (match from top down) Source File
---- --------- ------------------------------ -----------------
Excl Filespace /var/run /opt/tivoli/tsm/client/ba/bin/incl.excl
Excl Filespace /tmp /opt/tivoli/tsm/client/ba/bin/incl.excl
Excl Directory /.../.opera/.../cache4 /opt/tivoli/tsm/client/ba/bin/incl.excl
Excl Directory /.../.mozilla/.../Cache /opt/tivoli/tsm/client/ba/bin/incl.excl
Excl Directory /.../.netscape/.../cache /opt/tivoli/tsm/client/ba/bin/incl.excl
Excl Directory /var/tmp /opt/tivoli/tsm/client/ba/bin/incl.excl
Excl All /.../dsmsched.log /opt/tivoli/tsm/client/ba/bin/incl.excl
Excl All /.../core /opt/tivoli/tsm/client/ba/bin/incl.excl
Excl All /.../a.out /opt/tivoli/tsm/client/ba/bin/incl.excl
No DFS include/exclude statements defined.
Note that the include / exclude directives are listed at the partition level first, then the directory / folder level and finally at the file level. The order they are displayed above is the order in which these directives are applied by TSM. You will note that the order of the directives at any one level is the opposite of the order in which they appear in the options file. That is, TSM reads the directives listed in options file from the bottom up.
4.3. Querying what partitions have been backed up
At the tsm> prompt enter q fi to list which partitions have been backed up:
** Windows **
# Last Incr Date Type File Space Name
--- -------------- ---- ---------------
1 01-05-2002 19:46:59 NTFS \\tentacles.oucs\c$
** Mac **
tsm> q fi
# Last Incr Date Type File Space Name
--- -------------- ---- ---------------
1 02-05-2002 02:13:13 HFS /
2 25-07-2001 12:26:09 HFS /Volumes/Disk 2
** Unix/Linux **
tsm> q fi
# Last Incr Date Type File Space Name
--- -------------- ---- ---------------
1 02-05-2002 02:13:13 UFS /
2 25-07-2001 12:26:09 UFS /export/home
3 02-05-2002 02:13:26 UFS /home
4 16-01-2002 11:26:37 UFS /scratch
5 02-05-2002 02:13:54 UFS /usr/local
6 12-02-2002 02:52:41 UFS /var
** Netware **
# Last Incr Date Type File Space Name
--- -------------- ---- ---------------
1 02-05-2002 00:23:46 NTW:LONG NSMS1\SYS:
2 02-05-2002 00:22:42 NDS NSMS1\NDS:
3 02-05-2002 00:25:33 NTW:LONG NSMS1\USR:
4 02-05-2002 00:25:11 NTW:LONG NSMS1\APPS:
4.4. Querying what files have been backed up
The syntax for querying what files you have backed up involves giving a file specification which is necessarily OS specific. Also, if an incorrect file specification is given it may appear that you have no backups. Consequently, several worked examples are displayed below for Windows, Mac, Unix/Linux and Netware environments.
If you give just a path to a directory / folder you will only get the folder returned as the output:
** Windows **
tsm> q ba c:\Downloads
Size Backup Date Mgmt Class A/I File
---- ----------- ---------- --- ----
0 B 03-04-2002 19:57:54 STANDARD A \\tentacles.oucs\c$\Downloads
** Mac **
tsm> q ba /Users
Size Backup Date Mgmt Class A/I File
---- ----------- ---------- --- ----
72 B 24-04-2002 02:52:09 STANDARD A /Users
** Unix/Linux **
tsm> q ba /home/ians/projects
Size Backup Date Mgmt Class A/I File
---- ----------- ---------- --- ----
512 B 24-04-2002 02:52:09 STANDARD A /home/ians/projects
** Netware **
tsm> q ba USR:/ians
Size Backup Date Mgmt Class A/I File
---- ----------- ---------- --- ----
0 B 02-05-2002 00:25:32 STANDARD A USR:/ians
Note that the Windows client lists the directory in UNC format. This format can also be used for the file specification in the query.
If you just add a trailing * (star) as a wildcard in the above query, TSM will only return those files and directories backed up immediately below the directory path given in the query
tsm>q ba /home/ians/projects/*
Size Backup Date Mgmt Class A/I File
---- ----------- ---------- --- ----
512 12-09-2001 19:57:09 STANDARD A /home/ians/projects/hfs0106
1,024 08-12-2001 02:46:53 STANDARD A /home/ians/projects/hsm41perf
512 12-09-2001 19:57:09 STANDARD A /home/ians/projects/hsm41test
512 24-04-2002 00:22:56 STANDARD A /home/ians/projects/hsm42upg
If you want to query all the current files and directories backed up under a directory and all its subdirectories you need to add the -subdir=yes option as below:
tsm> q ba /home/ians/projects/* -subdir=yes
Size Backup Date Mgmt Class A/I File
---- ----------- ---------- --- ----
512 12-09-2001 19:57:09 STANDARD A /home/ians/projects/hfs0106
1,024 08-12-2001 02:46:53 STANDARD A /home/ians/projects/hsm41perf
512 12-09-2001 19:57:09 STANDARD A /home/ians/projects/hsm41test
512 24-04-2002 00:22:56 STANDARD A /home/ians/projects/hsm42upg
1,024 12-09-2001 19:57:09 STANDARD A /home/ians/projects/hfs0106/test
1,024 12-09-2001 19:57:09 STANDARD A /home/ians/projects/hfs0106/test/test2
12,048 04-12-2001 02:01:29 STANDARD A /home/ians/projects/hsm41perf/tables
50,326 30-04-2002 01:35:26 STANDARD A /home/ians/projects/hsm42upg/PMR70023
50,326 27-04-2002 00:28:15 STANDARD A /home/ians/projects/hsm42upg/PMR70099
11,013 24-04-2002 00:22:56 STANDARD A /home/ians/projects/hsm42upg/md5check
Note that file specifications with spaces in them will need to be quoted. Thus to query all the files backed up under C:\My Documents and any sub-directories below it, the following input would be required:
tsm> q ba "C:\My Documents\*" -subdir=yes
By default only the current versions of files are listed. In order to query both current active and previous inactive versions of files, add the -inactive option to the query:
tsm> q ba /home/ians/projects/* -subdir=yes -inactive
Size Backup Date Mgmt Class A/I File
---- ----------- ---------- --- ----
512 12-09-2001 19:57:09 STANDARD A /home/ians/projects/hfs0106
1,024 08-12-2001 02:46:53 STANDARD A /home/ians/projects/hsm41perf
512 12-09-2001 19:57:09 STANDARD A /home/ians/projects/hsm41test
512 24-04-2002 00:22:56 STANDARD A /home/ians/projects/hsm42upg
1,024 12-09-2001 19:57:09 STANDARD A /home/ians/projects/hfs0106/test
1,024 12-09-2001 19:57:09 STANDARD A /home/ians/projects/hfs0106/test/test2
12,048 04-12-2001 02:01:29 STANDARD A /home/ians/projects/hsm41perf/tables
8,448 03-12-2001 01:31:18 STANDARD I /home/ians/projects/hsm41perf/tables
50,326 30-04-2002 01:35:26 STANDARD A /home/ians/projects/hsm42upg/PMR70023
50,326 27-04-2002 00:28:15 STANDARD A /home/ians/projects/hsm42upg/PMR70099
11,013 24-04-2002 00:22:56 STANDARD A /home/ians/projects/hsm42upg/md5check
11,013 23-04-2002 17:10:08 STANDARD I /home/ians/projects/hsm42upg/md5check
Note how the previous versions of files are marked by an I (for Inactive) in the A/I column.
Unix and Linux users should be aware of potential confusion of how TSM stores files in nested file spaces. This can arise in the following situation: A user backs-up a file myconf.txt on the /usr partition in the /usr/local/etc directory. Subsequently, a new disk partition is mounted at /usr/local, or it is defined as a virtualmountpoint. Running the command:
tsm> q ba /usr/local/etc/*
will not list the myconf.txt file. This is because TSM always looks for a file in the filespace (partition) with the longest name that matches the file specification you include in the command. In the above example, the file was not backed up under the /usr/local filespace but under the /usr filespace. To tell TSM to look for a file in latter filespace you must specify the filespace explicitly using braces, as below:
tsm> q ba {/usr}/local/etc/*
5. Backing up your data
5.1. Backing up local disksThe basic syntax for backing up local disk volumes is dsmc backup-type disk volume(s), where backup-type is one of incremental or selective - see File versions and types of backup for the differences between these. By default, if the disk volume is omitted, TSM will backup those volumes specified by the Domain option in the dsm.opt options file. If Domain is set to All-Local, then to backup all local volumes enter:
tsm> incr
where incr is an abbreviation for incremental.
To incrementally back up specific volumes enter:
tsm> incr C: D: F: ** Windows
tsm> incr / ** Mac
tsm> incr / /usr /usr/local /home ** Unix/Linux
tsm> incr NDS: USR: SYS: APPS: ** Netware
To run an incremental by date backup of the above, add the -incrbydate option, as in:
tsm> incr C: D: F: -incrbydate
To back up entire disk volumes irrespective of whether files have changed since the last backup, use the selective command with a wildcard and -subdir=yes as below:
tsm> sel C:\* D:\* F:\* -su=yes ** Windows
tsm> sel /* -su=yes ** Mac
tsm> sel /* /usr/* /home/* -su=yes ** Unix/Linux
tsm> sel USR:* SYS:* APPS:* -su=yes ** Netware
5.2. Backing up selected filesThe basic syntax for backing up selected files is similar to that for backing up disk partitions. Be aware, however, that you cannot use wildcards in directory / folder names:
tsm> incr /home/ians/projects/hsm*/* -su=yes
ANS1071E Invalid domain name entered: '/home/ians/projects/hsm*/*'
tsm> sel /home/ians/projects/hsm*/* -su=yes
Selective Backup function invoked.
ANS1081E Invalid search file specification '/home/ians/projects/hsm*/*' entered
You can, however, enter several file specifications on the command line, as below:
** Windows **
tsm> incr "C:\My Documents\Word docs\*" "C:\My Documents\html docs\*" -su=yes
** Mac **
tsm> incr /Users/ians/* /Users/test/* -su=yes
** Unix/Linux **
tsm> incr /home/ians/projects/hsm41test/* /home/ians/projects/hsm41perf/* -su=yes
** Netware **
tsm> incr USR:ians/projects/tsm/* "USR:ians/projects/new html/*" -su=yes 6. Restoring your data The basic syntax for restoring your data is dsmc restore source-file destination-file. If the destination-file is omitted then TSM will restore the file(s) to their original location. Be aware that, as with backup, you cannot use wildcards in directory / folder names. By default, TSM will restore the most current active version of a file. 6.1. Restoring selected files ** Windows **
tsm> rest "C:\My Documents\Word docs\mydoc.doc" "C:\My Documents\restore\"
tsm> rest "C:\My Documents\Word docs\mydoc.doc" "C:\My Documents\restore\myolddoc.doc"
** Mac **
tsm> rest /Users/ians/myfile.txt /Users/ians/restore/
tsm> rest /Users/ians/myfile.txt /Users/ians/restore/myoldfile.txt
** Unix/Linux **
tsm> rest /home/ians/myfile.txt /home/ians/restore/
tsm> rest /home/ians/myfile.txt /home/ians/restore/myoldfile.txt
** Netware **
tsm> rest USR:ians/myfile.txt* "USR:ians/restore/"
tsm> rest USR:ians/myfile.txt* "USR:ians/restore/myoldfile.txt"
Note from the first example of each restore above that in order to specify a directory as a destination, you need a trailing / (slash) at the end of the destination-filespec. Otherwise TSM may overwrite a file of the same name. The second example demonstrates a filename in the destination-filespec.
Restores of single files cannot be restarted if interrupted. In this case you will need to restore the file afresh. 6.2. Restoring multiple files and directories ** Windows **
tsm> rest "C:\My Documents\Word docs\*" "C:\My Documents\restore\" -su=yes
** Mac **
tsm> rest /Users/ians/projects/hsm41test/* /Users/ians/projects/restore/ -su=yes
** Unix/Linux **
tsm> rest /home/ians/projects/hsm41test/* /home/ians/projects/restore/ -su=yes
** Netware **
tsm> rest USR:ians/projects/tsm/* "USR:ians/projects/restore/" -su=yes
Note that in order to restore a full directory and the contents of all its sub-directories you need the -su=yes option. It is always good practice to terminate the destination-filespec with a trailing / (slash) if the element in the destination-filespec is a directory.
As this restore is wild-carded, it can be restarted if interrupted due to user input (Ctrl-C), server error or communications error. Restartable restores can be queried via q rest and will restart at the point of interruption. 6.3. Restoring entire partitionsEssentially, the syntax is the same as in 'Restoring multiple files and directories' above. However, the obvious caveats are to ensure enough space in the destination partition and to allow enough time - see Restoring your data - considerations.
** Windows **
tsm> rest C:\* D:\restore\" -su=yes
** Mac **
tsm> rest /Users/* /tmp/restore/ -su=yes
** Unix/Linux **
tsm> rest /home/* /tmp/restore/ -su=yes
** Netware **
tsm> rest USR:* USR:restore/ -su=yes
As with 'Restoring multiple files and directories' above, this restore is wild-carded and thus can be restarted if interrupted. 6.4. Restoring old and/or deleted filesAs with the GUI, TSM does not, by default, list or restore old and deleted inactive versions of files and directories. If you need to restore such a file, you need the -inactive -pick options. The -pick option, while not strictly necessary, causes TSM to display a list of files from which to pick. Issuing a restore as below will display the following pick window:
tsm> rest /home/ians/projects/* /tmp/restore/ -su=yes -inactive -pick
TSM Scrollable PICK Window - Restore
# Backup Date/Time File Size A/I File
--------------------------------------------------------------------------------------------------
170. | 12-09-2001 19:57:09 650 B A /home/ians/projects/hsm41test/inclexcl.test
171. | 12-09-2001 19:57:09 2.74 KB A /home/ians/projects/hsm41test/inittab.ORIG
172. | 12-09-2001 19:57:09 2.74 KB A /home/ians/projects/hsm41test/inittab.TEST
173. | 12-09-2001 19:57:09 1.13 KB A /home/ians/projects/hsm41test/md5.out
174. | 30-04-2002 01:35:26 512 B A /home/ians/projects/hsm42125upg/PMR70023
175. | 26-04-2002 01:02:08 512 B I /home/ians/projects/hsm42125upg/PMR70023
176. | 27-04-2002 00:28:15 512 B A /home/ians/projects/hsm42125upg/PMR70099
177. | 24-04-2002 19:17:34 512 B I /home/ians/projects/hsm42125upg/PMR70099
178. | 24-04-2002 00:22:56 1.35 KB A /home/ians/projects/hsm42125upg/dsm.opt
179. | 24-04-2002 00:22:56 4.17 KB A /home/ians/projects/hsm42125upg/dsm.sys
180. | 24-04-2002 00:22:56 1.13 KB A /home/ians/projects/hsm42125upg/dsmmigfstab
181. | 24-04-2002 00:22:56 7.30 KB A /home/ians/projects/hsm42125upg/filesystems
182. | 24-04-2002 00:22:56 1.25 KB A /home/ians/projects/hsm42125upg/inclexcl
183. | 24-04-2002 00:22:56 198 B A /home/ians/projects/hsm42125upg/inclexcl.dce
184. | 24-04-2002 00:22:56 291 B A /home/ians/projects/hsm42125upg/inclexcl.ox_sys
185. | 24-04-2002 00:22:56 650 B A /home/ians/projects/hsm42125upg/inclexcl.test
186. | 24-04-2002 00:22:56 670 B A /home/ians/projects/hsm42125upg/inetd.conf
187. | 24-04-2002 00:22:56 2.71 KB A /home/ians/projects/hsm42125upg/inittab
188. | 24-04-2002 00:22:56 1.00 KB A /home/ians/projects/hsm42125upg/md5check
189. | 24-04-2002 00:22:56 79.23 KB A /home/ians/projects/hsm42125upg/mkreport.020423.out
190. | 24-04-2002 00:22:56 4.27 KB A /home/ians/projects/hsm42125upg/ssamap.020423.out
191. | 26-04-2002 01:02:08 12.78 MB A /home/ians/projects/hsm42125upg/PMR70023/70023.tar
192. | 25-04-2002 16:33:36 12.78 MB I /home/ians/projects/hsm42125upg/PMR70023/70023.tar
0---------10--------20--------30--------40--------50--------60--------70--------80--------90--
You are now in the pick interface and can select individual files to restore via the number to the left, scroll up or down via U and D as described at the bottom of each listing of files.
Remember to issue the destination-filespec with the original restore command if you want to prevent overwriting current versions of files with older versions.
7. Restoring your data to another machine
In certain circumstances, it may be necessary to restore some, or all, of your data onto a machine other than the original from which it was backed up. Ideally the machine platform should be identical to that of the original machine. Where this is not possible or practical please note that restores are only possible for partition types that the operating system supports.
Thus a restore of an NTFS partition to a Windows 9x machine with just FAT support may succeed but the file permissions will be lost. Please do not attempt cross-platform restores, e.g. by trying to restore files onto a Windows machine that have previously been backed up with a non-Windows one: using TSM for Windows to try to access backups sent by other OS platforms can cause those backups to become inaccessible from the host system.
To restore your data to another machine you will need the TSM software installed on the target machine. Entries in dsm.sys and/or dsm.opt will need to be edited if the node that you are restoring from does not reside on the same HFS server as the one that you are restoring to. Please see our help page section on TSM configuration files for their locations for your operating system. To check which HFS server is required, please go to View TSM Client Details, where the listed HFS Server will be the one needed for the Servername field in both dsm.sys (Mac/Unix/Linux only) and dsm.opt (all operating systems). If you do need to edit these files, it is recommended that you first of all make copies so that you can get your old settings back later. The other two values which need to be changed are TCPServer and TCPPort, in dsm.sys (Mac/Unix/Linux) or dsm.opt (Windows/Netware): these can be got from our page on connecting to the HFS through a firewall, where the relevant fields are in the 'DNS Name' and 'Port' columns respectively.
To access files from another machine you should then start the TSM client as below:
dsmc -virtualnodename=DEAD.MACHINE ** Windows, Mac, Unix/Linux
load dsmc -virtualnodename=DEAD.MACHINE ** Netware
where DEAD.MACHINE should be substituted for the nodename of the machine to be restored. You will then be prompted for the TSM password for this machine.
Querying and restoring the filestore is then as in the previous section, 6. Restoring your data. You will probably want to restore to a different destination to the original files to prevent overwriting files on the local machine, as below:
tsm> rest D:\* D:\RESTORE\ -su=yes ** Windows
tsm> rest /home/* /scratch/ -su=yes ** Mac, Unix/Linux
tsm> rest SOURCE-SERVER\USR:* USR:restore/ -su=yes ** Netware
8. Authorizing another machine to restore your files
If you are responsible for a number of TSM client machines, you can protect against the loss of one machine by authorizing a different machine(s) to restore backup versions of your files. The basic syntax for this is set access backup filespec node username. Thus to grant the root user on machine ANOTHER.NODE access to restore the /home filespace, you would issue the following:
tsm> set acc backup /home/*/* another.node root The equivalent commands on Windows and Netware machines would look like:
tsm> set acc backup c:\* another.pc system ** Windows
tsm> set acc backup USR:* another.svr root ** Netware The current access list can be queried and deleted using the query acc and delete acc commands.
Once access has been granted from another machine, you can query and restore files from that machine to your local machine using the -fromnode option, as below:
tsm> q files -fromnode=ANOTHER.NODE
tsm> rest -fromnode=ANOTHER.NODE /home/*/* /home/restore/
9. Changing your TSM password
The TSM password is set to expire approximately one year after registration and at one-yearly intervals after that. Prior to this automatic expiry, you will be contacted to remind you to re-set this password. Note that even if you have the option PASSWORDACCESS Generate set in your options file, it is recommended you manually re-set your TSM password. To do this at the tsm> prompt enter:
tsm> set password oldpassword newpassword
