HFS Spectrum Protect command line interface

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.

 

Expand All

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.

Query your scheduled backup slot

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 

Query files included/excluded for backup

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.


Query which partitions have been backed 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: 

Querying which 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.

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  /Users

Linux:

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/*

Backing up local disks

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

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> incr "C:\My Documents\Word docs\*" "C:\My Documents\html docs\*" -su=yes

Backing up local disks

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

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> incr /Users/ians/* /Users/test/* -su=yes

Backing up local disks

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

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> incr /home/ians/projects/hsm41test/* /home/ians/projects/hsm41perf/* -su=yes

Backing up local disks

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

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:

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.

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 -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.

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> rest C:\* D:\restore\ -su=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> 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.

Restoring old and/or deleted files

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.

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 -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.

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> rest /Users/* /tmp/restore/ -su=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> 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.

Restoring old and/or deleted files

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.

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 -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.

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> rest /home/* /tmp/restore/ -su=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> 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.

Restoring old and/or deleted files

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.

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 -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.

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.

tsm> rest USR:* USR:restore/ -su=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 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.

Restoring old and/or deleted files

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?.

Get support


If you cannot find the solution you need here then we have other ways to get IT support

Get IT support