This page provides an introduction to the HFS Spectrum Protect client command line interface (CLI) and describes how to manually back up and restore files on the local machine. The descriptions may refer to older TSM clients, but with the exception of the file specifications, the syntax is the same for all platforms.
From the Windows Start menu search for backup, then launch Backup-Archive Command Line.
Open Applications > Utilities > Terminal and type sudo dsmc, then provide tour Mac password.
Run dsmc as root from the shell prompt (for example in Ubuntu type sudo dsmc).
Type load dsmc at the console.
Online help for client commands, options and error messages is available by typing help at the Protect> or tsm> prompt.
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 on a Netware machine you can run load dsmc q fi to just run a query of the current partitions backed up. More complex queries and commands can be similarly run in the same manner.
The following query commands, illustrate typical command syntax and the resulting output.
q sched
Schedule Name: WEEKLY_ITSERV Description: ITSERV 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 Month: Day of Month: Week of Month: Expire: Never
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.
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 is the order in which these directives are applied by the software. 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, the software reads the directives listed in options file from the bottom up.
q fi
Windows:
# Last Incr Date Type File Space Name --- -------------- ---- --------------- 1 01-05-2012 19:46:59 NTFS \\tentacles.oucs\c$
Mac:
# Last Incr Date Type File Space Name --- -------------- ---- --------------- 1 02-05-2012 02:13:13 HFS / 2 25-07-2011 12:26:09 HFS /Volumes/Disk 2
Linux:
# Last Incr Date Type File Space Name --- -------------- ---- --------------- 1 02-05-2013 02:13:13 EXT4 / 2 25-07-2014 12:26:09 EXT3 /home
Netware:
# Last Incr Date Type File Space Name --- -------------- ---- --------------- 1 02-05-2012 00:23:46 NTW:LONG NSMS1\SYS: 2 02-05-2012 00:22:42 NDS NSMS1\NDS: 3 02-05-2012 00:25:33 NTW:LONG NSMS1\USR: 4 02-05-2012 00:25:11 NTW:LONG NSMS1\APPS:
The syntax for querying what files you have backed up involves giving a file specification which is necessarily OS specific.
If an incorrect file specification is given it may appear that you have no backups, so several examples are displayed below.
If you give just a path to a directory or folder you will only get that returned as the output.
Windows:
q ba c:\Downloads
Size Backup Date Mgmt Class A/I File ---- ----------- ---------- --- ---- 0 B 03-04-2012 19:57:54 STANDARD A \\tentacles.oucs\c$\Downloads
Mac:
q ba /Users
Size Backup Date Mgmt Class A/I File
---- ----------- ---------- --- ----
72 B 24-04-2012 02:52:09 STANDARD A /UsersLinux:
q ba /home/ians/projects
Size Backup Date Mgmt Class A/I File ---- ----------- ---------- --- ---- 512 B 24-04-2012 02:52:09 STANDARD A /home/ians/projects
Netware:
q ba USR:/ians
Size Backup Date Mgmt Class A/I File
---- ----------- ---------- --- ----
0 B 02-05-2012 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.
Adding a trailing * wildcard in the above query will only return those files and directories backed up immediately below the directory path given in the query
q ba /home/ians/projects/*
Size Backup Date Mgmt Class A/I File ---- ----------- ---------- --- ---- 512 12-09-2011 19:57:09 STANDARD A /home/ians/projects/hfs0106 1,024 08-12-2011 02:46:53 STANDARD A /home/ians/projects/hsm41perf 512 12-09-2011 19:57:09 STANDARD A /home/ians/projects/hsm41test 512 24-04-2012 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:
q ba /home/ians/projects/* -subdir=yes
Size Backup Date Mgmt Class A/I File ---- ----------- ---------- --- ---- 512 12-09-2011 19:57:09 STANDARD A /home/ians/projects/hfs0106 1,024 08-12-2011 02:46:53 STANDARD A /home/ians/projects/hsm41perf 512 12-09-2011 19:57:09 STANDARD A /home/ians/projects/hsm41test 512 24-04-2012 00:22:56 STANDARD A /home/ians/projects/hsm42upg 1,024 12-09-2011 19:57:09 STANDARD A /home/ians/projects/hfs0106/test 1,024 12-09-2011 19:57:09 STANDARD A /home/ians/projects/hfs0106/test/test2 12,048 04-12-2011 02:01:29 STANDARD A /home/ians/projects/hsm41perf/tables 50,326 30-04-2012 01:35:26 STANDARD A /home/ians/projects/hsm42upg/PMR70023 50,326 27-04-2012 00:28:15 STANDARD A /home/ians/projects/hsm42upg/PMR70099 11,013 24-04-2012 00:22:56 STANDARD A /home/ians/projects/hsm42upg/md5check
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, would require:
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:
q ba /home/ians/projects/* -subdir=yes -inactive
Size Backup Date Mgmt Class A/I File ---- ----------- ---------- --- ---- 512 12-09-2011 19:57:09 STANDARD A /home/ians/projects/hfs0106 1,024 08-12-2011 02:46:53 STANDARD A /home/ians/projects/hsm41perf 512 12-09-2011 19:57:09 STANDARD A /home/ians/projects/hsm41test 512 24-04-2012 00:22:56 STANDARD A /home/ians/projects/hsm42upg 1,024 12-09-2011 19:57:09 STANDARD A /home/ians/projects/hfs0106/test 1,024 12-09-2011 19:57:09 STANDARD A /home/ians/projects/hfs0106/test/test2 12,048 04-12-2011 02:01:29 STANDARD A /home/ians/projects/hsm41perf/tables 8,448 03-12-2011 01:31:18 STANDARD I /home/ians/projects/hsm41perf/tables 50,326 30-04-2012 01:35:26 STANDARD A /home/ians/projects/hsm42upg/PMR70023 50,326 27-04-2012 00:28:15 STANDARD A /home/ians/projects/hsm42upg/PMR70099 11,013 24-04-2012 00:22:56 STANDARD A /home/ians/projects/hsm42upg/md5check 11,013 23-04-2012 17:10:08 STANDARD I /home/ians/projects/hsm42upg/md5check
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 files in nested file spaces are stored. This can arise in situations such as when a user backs up the 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:
q ba /usr/local/etc/*
will not list the myconf.txt file because the software 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 the software to look for a file in latter filespace you must specify the filespace explicitly using braces:
q ba {/usr}/local/etc/*
The basic syntax for backing up local disk volumes is dsmc backup-type disk-volumes,
Backing up local disk volumes can be either incremental or selective. We recommend incremental backups only as selective backups cause data to be sent even if it already exists on the HFS.
By default, if the disk volume is omitted, you will backup those volumes specified by the Domain option in the dsm.opt options file.
If Domain is set to All-Local, then to do an incremental backup all local volumes:
Protect> incr
To incrementally back up specific volumes:
Protect> incr C: D: F:
To run an incremental by date backup of the above, add the -incrbydate option:
Protect> 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:
Protect> sel C:\* D:\* F:\* -su=yes
The basic syntax for backing up selected files is similar to that for backing up disk partitions, though you cannot use wildcards in directory/folder names. However, several file specifications can be provided on the command line:
Protect> incr "C:\My Documents\Word docs\*" "C:\My Documents\html docs\*" -su=yes
The basic syntax for backing up local disk volumes is dsmc backup-type disk-volumes,
Backing up local disk volumes can be either incremental or selective. We recommend incremental backups only as selective backups cause data to be sent even if it already exists on the HFS.
By default, if the disk volume is omitted, you will backup those volumes specified by the Domain option in the dsm.opt options file.
If Domain is set to All-Local, then to do an incremental backup all local volumes:
Protect> incr
To incrementally back up specific volumes:
Protect> incr /
To run an incremental by date backup of the above, add the -incrbydate option:
Protect> incr / -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:
Protect> sel /* -su=yes
The basic syntax for backing up selected files is similar to that for backing up disk partitions, though you cannot use wildcards in directory/folder names. However, several file specifications can be provided on the command line:
Protect> incr /Users/ians/* /Users/test/* -su=yes
The basic syntax for backing up local disk volumes is dsmc backup-type disk-volumes,
Backing up local disk volumes can be either incremental or selective. We recommend incremental backups only as selective backups cause data to be sent even if it already exists on the HFS.
By default, if the disk volume is omitted, you will backup those volumes specified by the Domain option in the dsm.opt options file.
If Domain is set to All-Local, then to do an incremental backup all local volumes:
Protect> incr
To incrementally back up specific volumes:
Protect> incr / /usr /usr/local /home -incrbydate
To run an incremental by date backup of the above, add the -incrbydate option:
Protect> sel /* /usr/* /home/* -su=yes
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:
Protect> sel /* -su=yes
The basic syntax for backing up selected files is similar to that for backing up disk partitions, though you cannot use wildcards in directory/folder names. However, several file specifications can be provided on the command line:
Protect> incr /home/ians/projects/hsm41test/* /home/ians/projects/hsm41perf/* -su=yes
The basic syntax for backing up local disk volumes is dsmc backup-type disk-volumes,
Backing up local disk volumes can be either incremental or selective. We recommend incremental backups only as selective backups cause data to be sent even if it already exists on the HFS.
By default, if the disk volume is omitted, you will backup those volumes specified by the Domain option in the dsm.opt options file.
If Domain is set to All-Local, then to do an incremental backup all local volumes:
Protect> incr
To incrementally back up specific volumes:
Protect> incr NDS: USR: SYS: APPS:
To run an incremental by date backup of the above, add the -incrbydate option:
Protect> incr NDS: USR: SYS: APPS: -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:
Protect> sel USR:* SYS:* APPS:* -su=yes
The basic syntax for backing up selected files is similar to that for backing up disk partitions, though you cannot use wildcards in directory/folder names. However, several file specifications can be provided on the command line:
tsm> incr USR:ians/projects/tsm/* "USR:ians/projects/new html/*" -su=yes
The basic syntax for restoring your data is dsmc restore source-file destination-filespec.
If the destination-filespec is omitted then the files will be restored to their original location. As with backup, you cannot use wildcards in directory/folder names.
By default, the software will restore the most current active version of a file.
In order to restore a full directory and the contents of all its sub-directories, you need to use the -su=yes option. It is always good practice to terminate the destination-filespec with a trailing \ (backslash) if the element in the destination-filespec is a directory.
Protect> rest "C:\My Documents\Word docs\*" "C:\My Documents\restore\" -su=yes
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 with q rest and will restart at the point of interruption.
Essentially, 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.
Protect> rest C:\* D:\restore\ -su=yes
As above, since this restore is wild-carded it can be restarted if interrupted.
In order to specify a directory as a destination, you need a trailing \ at the end of the destination-filespec, otherwise the software may overwrite a file of the same name:
Protect> rest "C:\My Documents\Word docs\mydoc.doc" "C:\My Documents\restore\"
Or to specify a filename as the destination-filespec:
Protect> rest "C:\My Documents\Word docs\mydoc.doc" "C:\My Documents\restore\myolddoc.doc"
Restores of single files cannot be restarted if interrupted, you will need to restore the file afresh.
As with the GUI, by default the CLI does not list or restore old and deleted inactive versions of files and directories. If you need to restore such a file, you need to use the -inactive option.
The -pick option, while not strictly necessary, causes the software to display a list of files from which to pick, allowing you to select individual files to restore using a number to the files left.
The following restore command will also provide the pick interface:
Protect> rest "C:\My Documents\projects\*" "C:\My Documents\temp\restore\" -su=yes -inactive -pick
Remember to issue the destination-filespec with the original restore command if you want to prevent overwriting current versions of files with older versions.
The basic syntax for restoring your data is dsmc restore source-file destination-filespec.
If the destination-filespec is omitted then the files will be restored to their original location. As with backup, you cannot use wildcards in directory/folder names.
By default, the software will restore the most current active version of a file.
In order to restore a full directory and the contents of all its sub-directories, you need to use 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.
Protect> rest /Users/ians/projects/hsm41test/* /Users/ians/projects/restore/ -su=yes
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 with q rest and will restart at the point of interruption.
Essentially, 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.
Protect> rest /Users/* /tmp/restore/ -su=yes
As above, since this restore is wild-carded it can be restarted if interrupted.
In order to specify a directory as a destination, you need a trailing / at the end of the destination-filespec, otherwise the software may overwrite a file of the same name:
Protect> rest /Users/ians/myfile.txt /Users/ians/restore/
Or to specify a filename as the destination-filespec:
Protect> rest /Users/ians/myfile.txt /Users/ians/restore/myoldfile.txt
Restores of single files cannot be restarted if interrupted, you will need to restore the file afresh.
As with the GUI, by default the CLI does not list or restore old and deleted inactive versions of files and directories. If you need to restore such a file, you need to use the -inactive option.
The -pick option, while not strictly necessary, causes the software to display a list of files from which to pick, allowing you to select individual files to restore using a number to the files left.
The following restore command will also provide the pick interface:
Protect> rest /Users/ians/projects/* /Users/ians/temp/restore/ -su=yes -inactive -pick
Remember to issue the destination-filespec with the original restore command if you want to prevent overwriting current versions of files with older versions.
The basic syntax for restoring your data is dsmc restore source-file destination-filespec.
If the destination-filespec is omitted then the files will be restored to their original location. As with backup, you cannot use wildcards in directory/folder names.
By default, the software will restore the most current active version of a file.
In order to restore a full directory and the contents of all its sub-directories, you need to use 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.
rotect> rest /home/ians/projects/hsm41test/* /home/ians/projects/restore/ -su=yes
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 with q rest and will restart at the point of interruption.
Essentially, 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.
Protect> rest /home/* /tmp/restore/ -su=yes
As above, since this restore is wild-carded it can be restarted if interrupted.
In order to specify a directory as a destination, you need a trailing / at the end of the destination-filespec, otherwise the software may overwrite a file of the same name:
Protect> rest /home/ians/myfile.txt /home/ians/restore/
Or to specify a filename as the destination-filespec:
Protect> rest /home/ians/myfile.txt /home/ians/restore/myoldfile.txt
Restores of single files cannot be restarted if interrupted, you will need to restore the file afresh.
As with the GUI, by default the CLI does not list or restore old and deleted inactive versions of files and directories. If you need to restore such a file, you need to use the -inactive option.
The -pick option, while not strictly necessary, causes the software to display a list of files from which to pick, allowing you to select individual files to restore using a number to the files left.
The following restore command will also provide the pick interface:
Protect> rest /home/ians/projects/* /tmp/restore/-su=yes -inactive -pick
Remember to issue the destination-filespec with the original restore command if you want to prevent overwriting current versions of files with older versions.
The basic syntax for restoring your data is dsmc restore source-file destination-filespec.
If the destination-filespec is omitted then TSM will restore the files to their original location. As with backup, you cannot use wildcards in directory/folder names.
By default, TSM will restore the most current active version of a file.
In order to restore a full directory and the contents of all its sub-directories, you need to use 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.
tsm> rest USR:ians/projects/tsm/* "USR:ians/projects/restore/" -su=yes
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 with q rest and will restart at the point of interruption.
Essentially, 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.
tsm> rest USR:* USR:restore/ -su=yes
As above, since this restore is wild-carded it can be restarted if interrupted.
In order to specify a directory as a destination, you need a trailing / at the end of the destination-filespec, otherwise TSM may overwrite a file of the same name:
tsm> rest USR:ians/myfile.txt* "USR:ians/restore/"
Or to specify a filename as the destination-filespec:
tsm> rest USR:ians/myfile.txt* "USR:ians/restore/myoldfile.txt"
Restores of single files cannot be restarted if interrupted, you will need to restore the file afresh.
As with the GUI, by default TSM does not list or restore old and deleted inactive versions of files and directories. If you need to restore such a file, you need to use the -inactive option.
The -pick option, while not strictly necessary, causes TSM to display a list of files from which to pick, allowing you to select individual files to restore using a number to the files left.
The following restore command will also provide the pick interface:
tsm> rest USR:ians/projects/* "USR:ians/temp/restore/" -su=yes -inactive -pick
Remember to issue the destination-filespec with the original restore command if you want to prevent overwriting current versions of files with older versions.
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. A restore of an NTFS partition to a Windows machine with just FAT support may succeed, but the file permissions will be lost.
Please do not attempt cross-platform restores, such as trying to restore files onto a Windows machine that have previously been backed up with a non-Windows one. Using the CLI 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 client 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.
To check which HFS server is required, please go to the HFS Backup Services Portal, where the listed HFS Server will be the one needed for the Servername field in dsm.sys (Mac and Linux) and dsm.opt. If you do need to edit these files, it is recommended that you initially 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 and Linux) or dsm.opt (Windows and Netware).
To access files from another machine you should then start the client with:
dsmc -virtualnodename=DEAD.MACHINE (Windows / Mac / 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 backup client password for this machine.
Querying and restoring the filestore is then as in the section on 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.
Every HFS Spectrum Protect password is set to expire every 90 days, and a new one is then autonegotiated by the client and the server.
For further information please see our FAQ items Why do backup client passwords expire? and How do I change my backup client password?.
If you cannot find the solution you need here then we have other ways to get IT support
