HFS Spectrum Protect command line interface
Using the Spectrum Protect command line interface for backup and restore
This page provides an introduction to the Spectrum Protect client command line interface and describes how to manually back up and restore files on the local machine.
Online help for client commands, options and error messages is available by typing help at the Protect> 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 you can run 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.
Query your scheduled backup slot
query schedule
Schedule Name: DAILY_0100 Description: Daily schedule at 01:00 Schedule Style: Classic Action: Incremental Options: -subdir=yes Objects: Priority: 5 Next Execution: 10 Hours and 38 Minutes Duration: 1 Hour Period: 1 Day Day of Week: Any Month: Day of Month: Week of Month: Expire: Never
Query files included/excluded for backup
query inclexcl
*** FILE INCLUDE/EXCLUDE *** Mode Function Pattern (match from top down) Source File ---- --------- ------------------------------ ----------------- No exclude filespace statements defined. Excl Directory /.../.TsmCacheDir IBM Spectrum Protect Excl Directory /.../.Trash /opt/tivoli/tsm/client/ba/bin/dsm.sys Excl Directory /.../.gnome2/epiphany/mozilla/epiphany/Cache /opt/tivoli/tsm/client/ba/bin/dsm.sys Excl Directory /.../.opera/Cache* /opt/tivoli/tsm/client/ba/bin/dsm.sys Excl Directory /.../.mozilla/default/.../Cache /opt/tivoli/tsm/client/ba/bin/dsm.sys Excl Directory /.../.mozilla/firefox/.../Cache /opt/tivoli/tsm/client/ba/bin/dsm.sys Excl Directory /.../.galeon/mozilla/galeon/Cache /opt/tivoli/tsm/client/ba/bin/dsm.sys Excl Directory /.../.netscape/cache /opt/tivoli/tsm/client/ba/bin/dsm.sys Exclude All /.../TSMDEDUPDB* /opt/tivoli/tsm/client/ba/bin/dsm.sys Exclude All /var/log/lastlog /opt/tivoli/tsm/client/ba/bin/dsm.sys Exclude All /.../*.vmem /opt/tivoli/tsm/client/ba/bin/dsm.sys Exclude All /.../*.vmdk /opt/tivoli/tsm/client/ba/bin/dsm.sys Exclude All /.../core /opt/tivoli/tsm/client/ba/bin/dsm.sys Exclude All /.../a.out /opt/tivoli/tsm/client/ba/bin/dsm.sys 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 in 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 the options file from the bottom up.
Query which partitions have been backed up
query filespace
Windows:
# Last Incr Date Type Replication File Space Name -------------------------------------------------------------------------------- 1 09-08-2023 12:01:02 NTFS Current \\desktop-2u0egj1\c$
macOS:
# Last Incr Date Type Replication File Space Name -------------------------------------------------------------------------------- 1 09-11-2023 13:01:52 APFS Current /
Linux:
# Last Incr Date Type File Space Name -------------------------------------------------------------------------------- 1 18-11-2023 12:42:17 EXT4 /
Querying which files have been backed up
The syntax for querying your backed-up files requires providing a file specification that is inherently specific to the operating system. If an incorrect file specification is given it may appear that you have no backups, so several examples are displayed below using the query command:
If you give just a path to a directory or folder you will only get that returned as the output.
Windows:
query backup C:\Users\hfsuser\Backup
Size Backup Date Mgmt Class A/I File
---- ----------- ---------- --- ----
0 B 14-11-2023 14:13:25 STANDARD A \\desktop-2u0egj1\c$\Users\hfsuser\BackupmacOS:
query backup /Users
Size Backup Date Mgmt Class A/I File
---- ----------- ---------- --- ----
0 B 09-11-2023 12:27:37 STANDARD A /Users
Linux:
query backup /home/hfsuser/Backup
Size Backup Date Mgmt Class A/I File ---- ----------- ---------- --- ---- 4,096 B 16-11-2023 10:31:18 STANDARD A /home/hfsuser/Backup
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:
query backup C:\Users\hfsuser\Backup\*
Size Backup Date Mgmt Class A/I File ---- ----------- ---------- --- ---- 0 B 14-11-2023 14:13:25 STANDARD A \\desktop-2u0egj1\c$\Users\hfsuser\Backup\testfolder1 0 B 14-11-2023 14:13:25 STANDARD A \\desktop-2u0egj1\c$\Users\hfsuser\Backup\testfolder2 0 B 14-11-2023 14:13:25 DEFAULT A \\desktop-2u0egj1\c$\Users\hfsuser\Backup\testfile1.txt 0 B 14-11-2023 14:13:25 DEFAULT A \\desktop-2u0egj1\c$\Users\hfsuser\Backup\testfile2.txt
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:
query backup C:\Users\hfsuser\Backup\* -subdir=yes
Size Backup Date Mgmt Class A/I File ---- ----------- ---------- --- ---- 0 B 14-11-2023 14:13:25 STANDARD A \\desktop-2u0egj1\c$\Users\hfsuser\Backup\testfolder1 0 B 14-11-2023 14:13:25 STANDARD A \\desktop-2u0egj1\c$\Users\hfsuser\Backup\testfolder2 0 B 14-11-2023 14:13:25 DEFAULT A \\desktop-2u0egj1\c$\Users\hfsuser\Backup\testfile1.txt 0 B 14-11-2023 14:13:25 DEFAULT A \\desktop-2u0egj1\c$\Users\hfsuser\Backup\testfile2.txt 0 B 14-11-2023 14:17:03 DEFAULT A \\desktop-2u0egj1\c$\Users\hfsuser\Backup\testfolder1\testfile1-in-testfolder1.txt 0 B 14-11-2023 14:17:03 DEFAULT A \\desktop-2u0egj1\c$\Users\hfsuser\Backup\testfolder1\testfile2-in-testfolder1.txt 0 B 14-11-2023 14:17:03 DEFAULT A \\desktop-2u0egj1\c$\Users\hfsuser\Backup\testfolder2\testfile1-in-testfolder2.txt 0 B 14-11-2023 14:17:03 DEFAULT A \\desktop-2u0egj1\c$\Users\hfsuser\Backup\testfolder2\testfile2-in-testfolder2.txt
File specifications with spaces in them will need to be quoted. Thus, to query all the files backed up under "C:\users\hfsuser\Backup with spaces" and any sub-directories below it, would require:
query backup "C:\users\hfsuser\Backup with spaces\*" -subdir=yes
Size Backup Date Mgmt Class A/I File ---- ----------- ---------- --- ---- 0 B 14-11-2023 14:30:16 STANDARD A \\desktop-2u0egj1\c$\Users\hfsuser\Backup with spaces\test folder 1 0 B 14-11-2023 14:30:16 STANDARD A \\desktop-2u0egj1\c$\Users\hfsuser\Backup with spaces\test folder 2 0 B 14-11-2023 14:30:16 DEFAULT A \\desktop-2u0egj1\c$\Users\hfsuser\Backup with spaces\test file 1.txt 0 B 14-11-2023 14:30:16 DEFAULT A \\desktop-2u0egj1\c$\Users\hfsuser\Backup with spaces\test file 2.txt 0 B 14-11-2023 14:30:16 DEFAULT A \\desktop-2u0egj1\c$\Users\hfsuser\Backup with spaces\test folder 1\testfile 1 in test folder 1.txt 0 B 14-11-2023 14:30:16 DEFAULT A \\desktop-2u0egj1\c$\Users\hfsuser\Backup with spaces\test folder 1\testfile 2 in test folder 1.txt 0 B 14-11-2023 14:30:16 DEFAULT A \\desktop-2u0egj1\c$\Users\hfsuser\Backup with spaces\test folder 2\testfile 1 in test folder 2.txt 0 B 14-11-2023 14:30:16 DEFAULT A \\desktop-2u0egj1\c$\Users\hfsuser\Backup with spaces\test folder 2\testfile 2 in test folder 2.txt
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:
query backup /home/hfsuser/Backup/* -subdir=yes -inactive
Size Backup Date Mgmt Class A/I File
---- ----------- ---------- --- ----
4,096 B 16-11-2023 10:31:18 STANDARD A /home/hfsuser/Backup/testfolder1
4,096 B 16-11-2023 10:31:18 STANDARD A /home/hfsuser/Backup/testfolder2
0 B 16-11-2023 10:43:47 DEFAULT A /home/hfsuser/Backup/testfile
0 B 16-11-2023 10:43:47 DEFAULT A /home/hfsuser/Backup/testfile1
0 B 16-11-2023 10:31:18 DEFAULT I /home/hfsuser/Backup/testfile1
0 B 16-11-2023 10:43:47 DEFAULT A /home/hfsuser/Backup/testfile2
0 B 16-11-2023 10:31:18 DEFAULT I /home/hfsuser/Backup/testfile2
0 B 16-11-2023 10:43:14 DEFAULT A /home/hfsuser/Backup/testfolder1/testfile1-in-testfolder1
0 B 16-11-2023 10:31:18 DEFAULT I /home/hfsuser/Backup/testfolder1/testfile1-in-testfolder1
0 B 16-11-2023 10:43:14 DEFAULT A /home/hfsuser/Backup/testfolder1/testfile2-in-testfolder1
0 B 16-11-2023 10:31:18 DEFAULT I /home/hfsuser/Backup/testfolder1/testfile2-in-testfolder1
0 B 16-11-2023 10:31:18 DEFAULT A /home/hfsuser/Backup/testfolder2/testfile1-in-testfolder2
0 B 16-11-2023 10:31:18 DEFAULT A /home/hfsuser/Backup/testfolder2/testfile2-in-testfolder2
The previous versions of files are marked by an I, for Inactive, in the A/I column.
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:
query backup /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:
query backup {/usr}/local/etc/*
Backing up local disks
The basic syntax for backing up local disk volumes is incremental <disk-volume(s)>
By default, if the disk volume is omitted, you will back up 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 of all local volumes:
Protect> incremental
To incrementally back up specific volumes:
Protect> incremental C: D: F:
To run an incremental by date backup of the above, add the -incrbydate option:
Protect> incremental C: D: F: -incrbydate
Backing up selected files
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> incremental "C:\My Documents\Word docs\*" "C:\My Documents\html docs\*" -subdir=yes
Backing up local disks
The basic syntax for backing up local disk volumes is incremental <disk-volume(s)>
By default, if the disk volume is omitted, you will back up 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 of all local volumes:
Protect> incremental
To incrementally back up specific volumes:
Protect> incremental /
To run an incremental by date backup of the above, add the -incrbydate option:
Protect> incremental / -incrbydate
Backing up selected files
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> incremental /Users/ians/* /Users/test/* -subdir=yes
Backing up local disks
The basic syntax for backing up local disk volumes is incremental <disk-volume(s)>
By default, if the disk volume is omitted, you will back up 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 of all local volumes:
Protect> incremental
To incrementally back up specific volumes:
Protect> incremental / /usr /usr/local /home
To run an incremental by date backup of the above, add the -incrbydate option:
Protect> incremental / /usr /usr/local /home -incrbydate
Backing up selected files
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> incremental /home/ians/projects/hsm41test/* /home/ians/projects/hsm41perf/* -subdir=yes
The basic syntax for restoring your data is restore <source-file> <destination-filespec> For example:
Protect> restore "C:\My Documents\Word docs\*" "C:\My Documents\restore\"
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.
If you plan to skip many files during the restoration process because they already exist in the chosen location, make sure to run the restore command with the -disablenqr=yes option. Failing to do so may lead to performance problems with the Spectrum Protect server.
Restoring multiple files and directories
In order to restore a full directory and the contents of all its sub-directories, you need to use the -subdir=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> restore "C:\My Documents\Word docs\*" "C:\My Documents\restore\" -subdir=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 query restore and will restart at the point of interruption.
Restoring entire partitions
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> restore C:\* D:\restore\ -subdir=yes
As above, since this restore is wild-carded it can be restarted if interrupted.
Restoring selected files
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> restore "C:\My Documents\Word docs\mydoc.doc" "C:\My Documents\restore\"
Or to specify a filename as the destination-filespec:
Protect> restore "C:\My Documents\Word docs\mydoc.doc" "C:\My Documents\restore\myolddoc.doc"
Restores of single files cannot be restarted if interrupted, and you will need to restore the file afresh.
Restoring old and/or deleted files
As with the graphical user interface, by default the command line interface 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> restore "C:\My Documents\projects\*" "C:\My Documents\temp\restore\" -subdir=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 restore <source-file> <destination-filespec> For example:
Protect> restore /Users/ians/projects/hsm41test/* /Users/ians/projects/restore/
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.
If you plan to skip many files during the restoration process because they already exist in the chosen location, make sure to run the restore command with the -disablenqr=yes option. Failing to do so may lead to performance problems with the Spectrum Protect server.
Restoring multiple files and directories
In order to restore a full directory and the contents of all its sub-directories, you need to use the -subdir=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> restore /Users/ians/projects/hsm41test/* /Users/ians/projects/restore/ -subdir=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 query restore and will restart at the point of interruption.
Restoring entire partitions
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> restore /Users/* /tmp/restore/ -subdir=yes
As above, since this restore is wild-carded it can be restarted if interrupted.
Restoring selected files
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> restore /Users/ians/myfile.txt /Users/ians/restore/
Or to specify a filename as the destination-filespec:
Protect> restore /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.
Restoring old and/or deleted files
As with the graphical user interface, by default the command line interface 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> restore /Users/ians/projects/* /Users/ians/temp/restore/ -subdir=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 restore <source-file> <destination-filespec> For example:
Protect> restore /home/ians/projects/hsm41test/* /home/ians/projects/restore/
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.
If you plan to skip many files during the restoration process because they already exist in the chosen location, make sure to run the restore command with the -disablenqr=yes option. Failing to do so may lead to performance problems with the Spectrum Protect server.
Restoring multiple files and directories
In order to restore a full directory and the contents of all its sub-directories, you need to use the -subdir=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> restore /home/ians/projects/hsm41test/* /home/ians/projects/restore/ -subdir=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 query restore and will restart at the point of interruption.
Restoring entire partitions
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> restore /home/* /tmp/restore/ -subdir=yes
As above, since this restore is wild-carded it can be restarted if interrupted.
Restoring selected files
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> restore /home/ians/myfile.txt /home/ians/restore/
Or to specify a filename as the destination-filespec:
Protect> restore /home/ians/myfile.txt /home/ians/restore/myoldfile.txt
Restores of single files cannot be restarted if interrupted, and you will need to restore the file afresh.
Restoring old and/or deleted files
As with the graphical user interface, by default the command line interface 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> restore /home/ians/projects/* /tmp/restore/-subdir=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.
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 command line interface 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 Spectrum Protect 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 Spectrum Protect server as the one that you are restoring to.
To check which Spectrum Protect server is required, please go to the HFS Backup Services Portal, where the listed Spectrum Protect Server will be the one needed for the ServerName field in dsm.sys (macOS and Linux) and dsm.opt. The other value which might need changing is the TcpServerAddress in dsm.sys (macOS and Linux) or dsm.opt (Windows). 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.
To access files from another machine you should then start the client with:
dsmc -virtualnodename=OLD.MACHINE (Windows / macOS / Linux)
Where OLD.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.
Get support
If you cannot find the solution you need here then we have other ways to get IT support
