HFS Storage Protect command line interface

This page provides an introduction to the Storage Protect client command line interface and describes how to manually back up and restore files on the local machine.

 

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 your macOS password.

Run dsmc as root from the shell prompt (for example in Ubuntu type sudo dsmc).

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 Storage 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\Backup

macOS:

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 Storage 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 Storage 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 Storage 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 Storage 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 Storage Protect server as the one that you are restoring to.

To check which Storage Protect server is required, please go to the HFS Backup Services Portal, where the listed Storage 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

Get IT support

IT support details for Christmas 2024

Submit a suggestion, compliment or complaint