Tivoli Storage Manager provides a command line interface (CLI) that you can
use as an alternative to the graphical user interface (GUI). This
chapter describes how to start or end a client command session and how to
enter commands. It also provides detailed information about each
command. Table 26 shows a list of tasks related to entering commands.
Command | Description | Page |
---|---|---|
archive | Archives files from a workstation to Tivoli Storage Manager storage. | Archive |
backup image | Creates an image backup of one or more file spaces. | Backup Image |
backup nas | Creates an image backup of one or more file systems belonging to an NAS file server. | Backup NAS |
cancel process | Displays a list of current NAS backup and restore processes and permits you to select one process to cancel. | Cancel Process |
cancel restore | Displays a list of restartable restore sessions and permits you to select one to cancel. | Cancel Restore |
delete access | Revokes authorization for a user to restore or retrieve files. | Delete Access |
delete archive | Deletes archived files from Tivoli Storage Manager storage. | Delete Archive |
delete filespace | Deletes file spaces in Tivoli Storage Manager storage. | Delete Filespace |
expire | Inactivates backup objects you specify. | Expire |
help | Displays online command help. | Help |
incremental | Backs up new and changed files. | Incremental |
loop | Starts an interactive command session. | Loop |
macro | Executes commands within a macro file you specify. | Macro |
monitor process | Displays a list of current NAS backup and restore processes. You can then select one process to monitor. | Monitor Process |
query access | Displays a list of current authorization rules. | Query Access |
query archive | Displays a list of archived files. | Query Archive |
query backup | Displays a list of backup versions. | Query Backup |
query backupset | Queries a backup set from the server or a local file. A backup set can also be queried from a tape device. | Query Backupset |
query filespace | Displays a list of file spaces in Tivoli Storage Manager storage. | Query Filespace |
query image | Displays information regarding backed up images. | Query Image |
query inclexcl | Displays a list of include-exclude statements in the order in which they are processed during backup and archive operations. | Query Inclexcl |
query mgmtclass | Displays information about available management classes. | Query Mgmtclass |
query node | Displays all the nodes for which a particular administrative user ID has authority to perform operations. The authorized administrative user ID should have at least client owner authority over both the NAS node and the client workstation node they are using either from command line or from the web. | Query Node |
query restore | Displays a list of your restartable restore sessions in the server database. | Query Restore |
query schedule | Displays information about scheduled events. | Query Schedule |
query session | Displays information about the current session. | Query Session |
restart restore | Displays a list of restartable restore sessions and permits you to select one to restart. | Restart Restore |
restore | Restores backup versions from Tivoli Storage Manager storage. | Restore |
restore backupset | Restores a backup set from the server or a local file. A backup set can also be restored from a tape device. | Restore Backupset |
restore image | Restores a backed up image. | Restore Image |
restore nas | Restores the image of a file system belonging to an NAS file server. | Restore NAS |
retrieve | Retrieves archived files from Tivoli Storage Manager storage. | Retrieve |
schedule | Starts the client scheduler on the workstation. | Schedule |
selective | Backs up selected files. | Selective |
set access | Authorizes another user to access your backup versions or archive copies. | Set Access |
set password | Changes the Tivoli Storage Manager password for your workstation. | Set Password |
You can start or end a client command session in either batch mode or interactive mode. Use batch mode when you want to enter a single client command. Tivoli Storage Manager processes the command and returns to the shell command prompt.
Use interactive mode when you want to enter a series of commands. Since Tivoli Storage Manager establishes connection to the server only once for interactive mode, a series of commands can process more quickly. Tivoli Storage Manager processes the commands and returns to the tsm> prompt.
When you enter a single command in batch mode, precede it with the executable program name, dsmc. Tivoli Storage Manager processes the command and returns to the shell command prompt. For example, to process the incremental command in batch mode, you would enter:
dsmc incremental
If a password is required, Tivoli Storage Manager prompts you each time you enter a command if the passwordaccess option is set to prompt, or authentication on the server is set to On. Type your password and press Enter.
You can also enter your password using the password option with a command, but your password appears on the screen. For example, if your password is secret, enter:
dsmc incremental -password=secret
If you set the passwordaccess option to generate in your dsm.opt file, you do not need to specify the password with the command. Tivoli Storage Manager only prompts you for your password if you are registering your workstation with a server or manually changing your password.
To end a batch mode session, enter quit at the prompt.
Use the interactive mode to enter a series of commands. Enter dsmc on the command line and press Enter. Do not precede each command with the executable program name, dsmc. When the tsm> command prompt displays, type the command name and press Enter. Alternatively, you can enter dsmc loop on the command line to start a client command session in interactive mode. Loop is the default command for dsmc.
If a password is required, Tivoli Storage Manager prompts you when you enter the first command. Type your user ID and password and press Enter. You can also enter your password using the password option with the loop command, but your password is displayed. For example, if your password is secret, you would enter:
dsmc loop -password=secret
To end an interactive session, enter quit at the prompt.
A client command can include one or more of these components:
The sections that follow describe each of these components.
The first part of a command is the command name. The command name consists of a single word, such as help or schedule, or an action word and an object for that action, such as query archive. Enter the full command name, or its minimum abbreviation. For example, you can enter any of the following versions of the query schedule command:
query schedule q sc q sched query sc
There are two groups of options that you can use with commands:
Commands can have required parameters, optional parameters, or no parameters at all. Required parameters provide information to perform a task. The most commonly required parameter is a file specification. For example, if you want to archive a file named budget.fin from the /project directory, you would enter:
dsmc archive /project/budget.fin
Some commands have optional parameters. If you do not enter a value for an optional parameter, Tivoli Storage Manager uses the default value. For example, the restore command includes a required parameter, sourcefilespec, that specifies the path and file name in storage that you want to restore. The optional parameter, destinationfilespec, specifies the path and file name where you want to place the restored files. If you do not specify the destinationfilespec, by default Tivoli Storage Manager restores the files to the original source path. If you want to restore the files to a different directory, enter a value for destinationfilespec. For example, to restore /project/budget.fin to /newproj/newbudg.fin, you would enter:
dsmc restore /project/budget.fin /newproj/newbudg.fin
Enter parameters in the order indicated in the command syntax diagram.
Use the following syntax rules when specifying file specification parameters, such as filespec, sourcefilespec, and destinationfilespec:
dsmc restore "/fs/dir1/*" mydir/
dsmc i /fsThe following example is not valid:
dsmc sel /fs
When entering a file specification, if the name ends with /, then it is considered a directory, otherwise it is considered a file.
The following example illustrates these two rules. Even though mydir and yourdir are directories, the command will fail because /* is implied after mydir, and yourdir is considered a file:
restore /home/mydir/ /away/yourdir
The following example illustrates the second rule. Even though mydir and yourdir are directories, the command will fail because mydir and yourdir are considered files:
restore /home/mydir /away/yourdir
dsmc set access "/fs/dir1/*/*"
Do not use wildcards for the directory path name, for example:
/home/j*asler/file1.c
Table 28 specifies the maximum file sizes for backup, restore, archive,
and retrieve operations.
Table 28. Maximum File Size for Backup, Restore, Archive, and Retrieve
Platform | Max File Size (in bytes) |
---|---|
AIX | 68,589,453,312 (64GB) |
AIX 5L | 68,589,453,312 (64GB) |
HP-UX | 1,099,511,627,775 (1TB-1) |
Linux86 and 390 | 9,223,372,036,854,775,807 (8EB-1) |
NUMA-Q DYNIX/ptx 4.5 | 1,095,216,660,480 (1TB-4GB) |
OS/390 UNIX | 4,294,967,295 (4GB) |
SGI | 18,446,744,073,709,551,615 (16EB-1) |
Solaris 2.6 or higher | 1,099,511,627,775 (1TB-1) |
Tru64 UNIX | 1,099,511,627,776 (1TB) |
If you specify the editor=yes option in your client options file dsm.opt, Tivoli Storage Manager permits you to recall and edit as many as 20 previously entered commands by using the Up arrow and Down arrow keys. If you specify the editor=no option, the feature to recall previous commands is not active. If the editor and command retrieve functions are not working on a specific workstation setting, you should turn off the editor option. For more information regarding the editor option, see Editor.
Pressing the Up arrow key displays the previous command in memory.
Pressing the Down arrow key displays the next command in memory. Table 29 lists other functions you can perform when you recall
commands.
Table 29. Command Recall and Edit Functions
Function | Press |
---|---|
Display the previous command in memory. | Up arrow |
Display the next command in memory. | Down arrow |
Move to the beginning of the command. | Home |
Move to the end of the command. | End |
Move to the left. | Left arrow |
Move to the right. | Right arrow |
Move five spaces to the left. | Tab left |
Move five spaces to the right. | Tab right |
Move to the beginning of the previous word | Ctrl-left arrow or CTRL-L |
Move to the beginning of the next word. | Ctrl-right arrow or CTRL-R |
Delete a character to the right of the cursor. | Delete |
Delete a character to the left of the cursor. | Backspace |
Insert a character. | Toggle the Insert key |
Erase to the end of the line. | Ctrl-delete or Ctrl-D |
Finish or execute the command. | Enter |
Quit the program. | F3 or Esc |
End the program. | CTRL-C |
In a command, you can use wildcard characters in the file name or file extension only. You cannot use them to specify destination files, file systems, or directories. You cannot specify a directory whose name contains an asterisk (*) or a question Mark (?). Tivoli Storage Manager recognizes these characters only as wildcard characters. Use wildcard characters when you want to specify multiple files with similar names in one command. Without wildcard characters, you must repeat the command for each file. Valid wildcard characters that you can use include:
Table 30 shows examples of each wildcard.
Pattern | Matches | Does Not Match |
---|---|---|
Asterisk (*) |
|
|
ab* | ab, abb, abxxx | a, b, aa, bb |
ab*rs | abrs, abtrs, abrsrs | ars, aabrs, abrss |
ab*ef*rs | abefrs, abefghrs | abefr, abers |
abcd.* | abcd.c, abcd.txt | abcd, abcdc, abcdtxt |
Question Mark (?) |
|
|
ab? | abc | ab, abab, abzzz |
ab?rs | abfrs | abrs, abllrs |
ab?ef?rs | abdefjrs | abefrs, abdefrs, abefjrs |
ab??rs | abcdrs, abzzrs | abrs, abjrs, abkkkrs |
Note: In batch mode, you must enclose values containing wildcards in double quotes. For example:
dsmc selective "/home/me/*.c"
Follow the general rules below when you enter commands:
The following sections contain detailed information about each of the Tivoli Storage Manager commands. These commands are arranged in alphabetical order. Information for each command includes:
The archive command archives a single file, selected files, or all files in a directory and its subdirectories on a server.
Archive files that you want to preserve in their current condition. To release storage space on your workstation, delete files as you archive them. Retrieve the archived files to your workstation whenever you need them again.
Syntax
.-----------------. V | >>-ARchive--+----------+----+- filespec---+-+------------------>< '- options-' '- "filespec"-'
Parameters
You can use the changingretries and subdir common options with the archive command. See "Setting Common Options" for information about these common options.
Examples
Command: archive /home/proj1/budget
Command: archive "/home/proj1/*.txt"
Command: archive -subdir=yes "/home/*"
The Tivoli Storage Manager client must support the raw device type on the specific platform to perform an image backup of a raw device. You can only perform an image backup on local devices. Clustered devices or file systems as well as devices or file systems shared between two or more systems are not supported. If you want to perform an image backup for a file system mounted on a raw device, the raw device must be supported. Before performing an image backup on a device, any file system on the device must be unmounted.
This command is valid for AIX, AIX 5L, HP/UX, and Solaris only.See "Devices Supported by the Backup Image Command" for specific information about supported devices for the backup image command.
The backup image command creates an image backup of one or more file spaces. Use the include.image option to include an image for backup or to assign a specific management class to an image object.
When using the backup image command, it is important to be aware of special considerations if you want to do either of the following:
To ensure that you can perform point-in-time restores of your file systems, including deleting original image files which no longer exist on the logical volume, use a combination of full image backups and the incremental command as described in the steps below:
dsmc incremental /myfilesystem
dsmc backup image /myfilesystem
dsmc incremental /myfilesystem
You must follow these steps in the order shown to ensure that the server records additions and deletions accurately. The following command restores the file system to its exact state as of the last incremental backup:
dsmc restore image /myfilesystem -incre -del
If you do not follow the steps exactly, two things can occur:
Two types of backup apply to logical volumes: mode=selective (the default) and mode=incremental. The mode=selective option creates and sends a full backup copy of the logical volume to the server. The mode=incremental option sends only those files that were added or changed since the last full image backup to the server. Tivoli Storage Manager ignores deleted files.
If you use the backup image command, first with mode=selective then followed one or more executions with mode=incremental, the incremental option restores the original image. The restore may include files that were later deleted plus the latest versions of files added or changed after the original image backup. If logical volumes are running at or near capacity, an out-of-space condition could result during the restore.
Note that the deletefiles option is allowed on the restore image command, but the server ignores it because the server is not aware of any deleted files. For more information, see "Incremental-by-Date".
If compression=yes, an image backup is compressed. However, the statistics may show 0% compression, and the progress indicator may reflect the number of bytes being passed to the compression function, not the number of bytes sent to the server after compression. To verify that compression occurred, use the administrator command, query content f=d.
Syntax
.-----------------. V | >>-Backup Image--+----------+----+-------------+-+------------->< '- options-' +- filespec---+ '- "filespec"-'
Parameters
Specify the file space over which the logical volume is mounted or the logical volume name. If there is a file system configured in the system for a given volume, you cannot back up the volume with the device name. For example, if /home is mounted on /dev/lv01 you can issue backup image /home but backup image /dev/vol1 will fail with an error: ANS1063E Invalid path specified.
For Sun systems: Specify either a file system name or a raw device name (block device type).
Examples
Command: dsmc backup image /home/test -mode=incremental
Command: dsmc backup image /dev/lv01
The backup nas command creates an image backup of one or more file systems belonging to a Network Attached Storage (NAS) file server. The NAS file server performs the outboard data movement. A server process starts in order to perform the backup.
Use the nasnodename option to specify the node name for the NAS file server. When using an interactive command line session with a non-administrative ID, Tivoli Storage Manager prompts for an administrator ID. The NAS node name identifies the NAS file server to the Tivoli Storage Manager server; the NAS node name must be registered at the server. Place the nasnodename option in your client system options file dsm.sys. The value in the client system options file is the default, but can be overridden on the command line. See Nasnodename for more information.
Use the mode option to specify whether to perform a full or differential NAS image backup. A full image backup backs up the entire file system. The default is a differential NAS image backup on files that change since the last full image backup. If an eligible full image backup does not exist, a full image backup is performed. See Mode for more information.
Use the monitor option to specify whether you want to monitor a NAS file system image backup and display processing information on your screen. See Monitor.
Use the monitor process command to display a list of current restore processes for all NAS nodes for which your administrative user ID has authority. The authorized administrative user ID should have at least client owner authority over both the NAS node and the client workstation node they are using either from command line or from the web.
Use the cancel process command to stop NAS back up processing. For more information, see Cancel Process.
The backup nas command is valid for AIX, AIX 5L, and Solaris clients only.
Regardless of client platform, NAS file system specifications use the forward slash (/) separator, as in this example: /vol/vol0.
Syntax
.---------------. V | >>-Backup NAS--+----------+------ filespec---+----------------->< '- options-'
Parameters
You can use the mode command line option with the backup nas command. For more information, see "Using Options with Commands".
If you do not specify the filespec or the domain.nas option, the default domain.nas=all-nas value is used and all file systems on the NAS file server are backed up.
Examples
Command: backup nas -mode=full -nasnodename=nas1 /vol/vol0 /vol/vol2
Command: backup nas -nasnodename=nas1
The cancel process command displays a list of current back up and restore processes for all NAS nodes. This command only displays those processes for which the administrative user has authority. From the list, the administrative user can select one process to cancel. Client owner privilege over a particular NAS node is sufficient authority to cancel the selected NAS process.
When using an interactive command line session with a non-administrative ID, Tivoli Storage Manager prompts for an administrator ID.
The cancel process command is valid for AIX, AIX 5L, and Solaris clients only.
Syntax
>>-Cancel Process----------------------------------------------><
Parameters
There are no parameters for this option.
Examples
Command: cancel process
The cancel restore command displays a list of your restartable restore sessions in the server database. You can only cancel one restartable restore session at a time. Run the cancel restore command again to cancel additional restores. To restart restartable restore sessions, use the restart restore command.
Use the cancel restore command when:
Syntax
>>-CANcel Restore--+----------+-------------------------------->< '- options-'
Parameters
Examples
Command: cancel restore
The delete access command deletes authorization rules for files or images that are stored on the server. When you delete an authorization rule, you revoke user access to any files or images specified by that rule.
Syntax
>>-Delete ACcess--+--------------+----------------------------->< | .----------. | | V | | '--- options-+-'
Parameters
Examples
Command: delete access
See the following screen example:
Index Type Node Owner Path _____ _______ ____________________________________ 1 Backup NODE1 USER1 home/dev/proja/list/ 2 Archive NODE3 LUIE home/fin/budg/depta/ 3 Backup NODE4 USER2 home/plan/exp/deptc/ 4 Archive NODE5 USER2S home/mfg/invn/parta/ Enter Index of rule(s) to delete, or quit to cancel:
To delete the authorization rules that let luie and user2s access your files or images, type: 2 4 or (2,4) and press Enter.
The delete archive command deletes archived files from server storage. Your administrator must give you authority to delete archived files.
Attention: When you delete archived files, you cannot retrieve them. Verify that the files are obsolete before you delete them.
Syntax
>>-Delete ARchive--+----------+--+- filespec---+--------------->< '- options-' '- "filespec"-'
Parameters
You can use the subdir common option with the delete archive command. For information about common options, see "Setting Common Options".
Examples
Command: del ar /user/home/proj1/budget
Command: del arch "/user/home/proj1/*.txt"
Command: d ar "/user/project/*" -pick
Authorized User
The delete filespace command deletes file spaces from server storage. A file space is a logical space on the server that contains files or images you backed up or archived. Tivoli Storage Manager assigns a separate file space on the server for each workstation file system from which you back up or archive files. The file space name is the same as the file system name. When you enter the delete filespace command, a list of your file spaces displays. From this list, select those file spaces that you want to delete.
Your administrator must give you authority to delete a file space. You need BACKDEL authority if the file space you want to delete contains backup versions, or ARCHDEL authority if the file space contains archive copies. If the file space contains both backup versions and archive copies, you need both types of authority.
You can use the delete filespace command to interactively delete NAS file spaces from server storage.
Use the nasnodename option to identify the NAS file server. When using an interactive command line session with a non-administrative ID, Tivoli Storage Manager prompts for an administrator ID. Place the nasnodename option in your client system options file dsm.sys. The value in the client system options file is the default, but this value can be overridden on the command line. If the nasnodename option is not specified in the client system options file, you must specify this option on the command line when processing NAS file systems. See Nasnodename for more information.
Use the class option to specify the class of the file space to delete. To display a list of file spaces belonging to a NAS node so that you may choose one to delete, use the -class=nas option. Using the default, -class=client, will not change the current delete filespace behavior. See Class for more information.
To delete NAS file spaces using the Web client, see "Backing Up and Restoring Files".
Attention: When you delete a file space, you delete all backup versions and archive copies within that file space. When you delete a file space, you cannot restore the files or images. Verify that the files or images are obsolete before you delete them.
Syntax
>>-Delete Filespace--+----------+------------------------------>< '- options-'
Parameters
You can use the class command line option with the delete filespace command. For more information, see Class.
Examples
Command: delete filespace
Command: del f -date=5 -time=4
Command: delete filespace -nasnodename=dagordon -class=nas
The expire command inactivates the backup objects you specify in the file specification or with the filelist option.
When working in interactive mode, a prompt notifies you before files are expired.
The expire command does not remove workstation files. If you expire a file or directory that still exists on your workstation, the file or directory is backed up again during the next incremental backup unless the object is excluded by include-exclude processing.
If you expire a directory that contains active files, those files will not appear in a subsequent query from the GUI. However, these files will display on the command line if you specify the proper query with a wildcard character for the directory.
Syntax
>>-EXPire--+----------+---- filespec--------------------------->< '- options-'
Parameters
Note: If the user specifies filelist, then pick is ignored.
Examples
Command:
expire "u/home/letter1.txt"
Command:
expire u/admin/mydir/*
The help command displays a Table of Contents of help topics for the command line client. Enter the number of the topic that you want to view. If there is more than one screen of topics, scroll backward or forward through the list. To exit, type q and press Enter.
Syntax
>>-Help--+----------+------------------------------------------>< '- options-'
Parameters
Examples
Command: help
The incremental command backs up all new or changed files or directories in the default client domain or from file systems, directories, or files you specify. The specified items must not be excluded from backup services.
To incrementally back up selected files or directories, specify the file specification in the command. The default is to back up files or directories in the default domain.
The following attributes in the management class assigned to the file or directory affect whether the data is actually backed up:
For more information on management classes, see "Understanding Storage Management Policies".
Using the include option in an include-exclude list, you can assign the default management class to a file. You can also assign a specific management class to a file.
You can perform either a full incremental backup or an incremental by date backup. The default is a full incremental backup.
You can also use the selective command to perform a selective backup that backs up only the files, directories or empty directories that you specify. For more information, see Selective.
A full incremental backs up all files or directories that are new or have changed since the last incremental backup. During a full incremental backup, the client queries the server to determine the exact condition of your storage. Tivoli Storage Manager uses this information to:
An incremental-by-date backup backs up new and changed files with a modification date later than the date of the last incremental backup stored at the server, unless the files are excluded from backup by an exclude statement.
If an incremental-by-date is performed on only part of a file system, the date of the last full incremental is not updated, and the next incremental-by-date will back up these files again. Therefore, changes to the access control lists (ACL) are not backed up during an incremental-by-date. Use the query filespace command to determine the date and time of the last incremental backup of the entire file system.
To perform an incremental-by-date backup, use the incrbydate option with the incremental command.
Unlike a full incremental, an incremental-by-date does not maintain current server storage of all your workstation files because:
For these reasons, if you have limited time during the week to perform backups, but extra time on the weekends, you can use a partial incremental backup on weekdays and a full incremental backup on weekends to maintain current server storage of your workstation files.
If the incremental command is retried because of a communication failure or session loss, the transfer statistics will display the number of bytes Tivoli Storage Manager attempted to transfer during all command attempts. Therefore, the statistics for bytes transferred may not match the file statistics, such as those for file size.
Special file systems contain dynamic information generated by the operating system; they contain no data or files. The UNIX client ignores special file systems and their contents. Special file systems include the following:
Tivoli Storage Manager provides ACL support for the UNIX client file
systems in Table 31.
Table 31. Supported UNIX File Systems and ACL Support
Platform | File System | ACL Support |
---|---|---|
AIX |
jfs gpfs afs/dfs JFS2 |
yes yes yes yes |
AIX 5L |
jfs gpfs afs/dfs JFS2 |
yes yes yes yes |
HP-UX |
hfs VxFS (JFS Veritas) VVM (Veritas Volume Manager) |
yes yes (V3.3.Layout 4) yes |
Linux86 |
ext2 reiserfs gpfs |
no no yes |
Linux/390 | ext2 | no |
PTX/NUMA-Q |
efs cfs |
yes yes |
OS/390 UNIX | hfs | no |
SGI |
efs xfs |
no yes |
Solaris |
ufs VxFS VVM (Veritas Volume Manager) |
yes yes yes |
Tru64 UNIX |
ufs advfs (Advanced FS) |
yes yes |
Beginning with Version 3.7.2, Tivoli Storage Manager provides full ACL support for GPFS file systems on the AIX client and XFS file systems on the SGI client. Files with an ACL set, backed up with a Version 3.7.1 or lower client, must be backed up again even if the files have not changed. This updates the ACL data on the server.
Attention: If you are running GPFS for AIX in a multi-node cluster, and all nodes share a mounted GPFS file system, Tivoli Storage Manager processes this file system as a local file system. Tivoli Storage Manager backs up the file system on each node during an incremental backup. To avoid this, you can do one of the following:
Syntax
.-----------------. V | >>-Incremental--+----------+----+-------------+-+-------------->< '- options-' +- filespec---+ '- "filespec"-'
Parameters
You can use the following common options with the incremental command: changingretries, domain, , memoryefficientbackup, subdir, , tapeprompt. For information about these options, see "Setting Common Options".
If a file system is specified, all new and changed files are backed up. In addition, the last incremental date for the file space is updated on the server. If a file or directory is specified, the last incremental date is not updated. This means the file or directory might be backed up again if a later backup is performed using the incrbydate option.
If a file system is specified, specify the file system without a trailing slash.
Examples
Command: Incremental
Command: Incremental /home /usr /proj
Command: Incremental /proj/test/
Command: Incremental -incrbydate /home
Command: Incremental -subdir=yes "/fs/dir1/abc*"
Command: Incremental -subdir=yes /fs/dir1/abc
Command: Incremental -subdir=yes /fs/dir1
Command: Incremental -subdir=yes /fs/dir1/
The loop command starts an interactive command line session that is maintained until you enter quit. In an interactive command line session, it is unnecessary to precede each command name with dsmc and your password, if one is required. After you start an interactive session, most of the options you enter with other commands are in effect throughout the session, unless you enter them again using a different setting.
You can enter all valid commands in interactive mode except the schedule and loop commands.
Some options cannot be used within the interactive session created by the loop command and are identified in the option description by this statement: This option is valid only on the initial command line. It is not valid in interactive mode.
See "Setting Common Options" for options that cannot be used in interactive mode.
Syntax
>>-LOOP--+----------+------------------------------------------>< '- options-'
Parameters
Examples
Command: dsmc
The macro command executes a series of commands that you specify in a macro file. By including the macro command within a macro file, you can nest as many as ten levels of commands.
Comment lines are not supported within the macro file specified for the macro command.
Syntax
>>-MAcro- macroname--------------------------------------------><
Parameters
Examples
The following is an example of how to use the macro command.
Command: macro backabc.mac
where backabc.mac contains the following statements:
Selective /devel/project/proja/ Selective /devel/project/projb/ Selective /devel/project/projc/
The monitor process command displays a list of current backup and restore processes for all NAS nodes for which the administrative user has authority. The administrative user can then select one process to monitor. Client owner privilege over a particular NAS node is sufficient authority to monitor the selected NAS process.
When using an interactive command line session with a non-administrative ID, Tivoli Storage Manager prompts for an administrator ID.
The monitor process command is valid for AIX, AIX 5L, and Solaris clients only.
Syntax
>>-MONitor Process---------------------------------------------><
Parameters
There are no parameters for this command.
Examples
Command: monitor process
The query access command displays a list of users to whom you have given access to backup versions or archive copies of specific files. Tivoli Storage Manager displays a list of authorization rules that you defined with the set access command or with User Access List on the graphical user interface (GUI) Utilities menu. The information includes:
Syntax
>>-Query ACcess--+----------+---------------------------------->< '- options-'
Parameters
Examples
Command: query access
The query archive command displays a list of your archived files, the file size, archive date, file specification, expiration date, and file description.
Syntax
>>-Query ARchive--+----------+--+- filespec---+---------------->< '- options-' '- "filespec"-'
Parameters
You can use the following common options with the query archive command: scrolllines, scrollprompt, subdir. See "Setting Common Options" for more information..
Examples
Command: q archive "*"
Command: query archive "/devel/*" -subdir=yes
Command: q ar -date=5 -time=1 "*"
Command:q ar -date=1 -time=4 "/home/proj/proj*"
The query backup command displays a list of backup versions of your files. File information includes the file specification, size, backup date, whether the file is active or inactive, and the management class asigned to the file. Only the first ten characters of the management class name appears.
You can use the query backup command to display information about file system images backed up for a NAS file server.
Use the nasnodename option to identify the NAS file server to query. When using an interactive command line session with a non-administrative ID, Tivoli Storage Manager prompts for an administrator ID. Place the nasnodename option in your client system options file dsm.sys. The value in the client system options file is the default, but this value can be overridden on the command line. See Nasnodename for more information.
Use the class option to specify the class of the file space to query. To display a list of images belonging to a NAS node, use the -class=nas option. Using the default, -class=client, will not change the current query backup behavior. See Class for more information.
Syntax
>>-Query Backup--+----------+--+- filespec---+----------------->< '- options-' '- "filespec"-'
Parameters
With the query backup command, you can use the following common options: subdir, scrolllines, nasnodename, scrollprompt. See "Setting Common Options" for information about these common options.
Examples
Command: query backup -inactive "*"
Command: q b-date=1 -time=4 "/home/proj/proj*"
Command: q b-date=5 -time=1 -ina -su=yes /home/
Command: query backup -nasnodename=nas2 -class=nas
The query backupset command queries a backup set from a local file, tape device, or server. See Location for information on how to specify supported tape devices. This command displays the backup set name, generation date, retention, and description.
You can use this command to query backup sets on a tape device with AIX, AIX 5L, Solaris, and HP clients only.
Syntax
>>-Query BACKUPSET--+---------+--+----------------+------------>< '-options-' +- backupsetname-+ '- filename------'
Parameters
You can use these common options with the query backupset command: scrolllines and scrollprompt. See "Setting Common Options" for information about these common options.
Examples
Command: query backupset "mybackupsetname" -loc=server
Command: dsmc query backupset "/home/budget /backupsetfile.name" -loc=file
Command: dsmc query backupset /dev/rmt0 -loc=tape
The query filespace command displays a list of file spaces for a node stored on the server. A file space is a logical space on the server that contains files you backed up or archived. Tivoli Storage Manager assigns a separate file space on the server for each file system at your workstation from which you back up or archive files. The file space name is the same as the file system name.
Use the nasnodename option to identify the NAS file server to query. When using an interactive command line session with a non-administrative ID, Tivoli Storage Manager prompts for an administrator ID. Place the nasnodename option in your client system options file dsm.sys. The value in the client system options file is the default, but this value can be overridden on the command line. If the nasnodename option is not specified in the client system options file, it must be specified on the command line when processing NAS file systems. See Nasnodename for more information.
Use the class option to specify the class of the object to query. To display a list of file spaces belonging to a NAS node, use the -class=nas option. Using the default, -class=client, will not change the current query filespace behavior. See Class for more information.
Syntax
>>-Query Filespace--+----------+------------------------------->< '- options-'
Parameters
You can use the nasnodename, scrolllines and scrollprompt common options with the query filespace command. See "Setting Common Options" for more information..
Examples
Command: query filespace
Command: query filespace -nasnodename=nas2 -class=nas
The query image command displays information about images backed up by a client. The options are used to determine the content and detail of the information.
This command is valid for AIX, AIX 5L, HP/UX, and Solaris only.
Syntax
>>-Query Image--+----------+--+- logicalvolumename-+----------->< '- options-' '- filespacename-----'
Parameters
You can also use the scrolllines and scrollprompt common options with the query image command. For more information about these common options, see "Setting Common Options".
Omitting logicalvolumename and filespacename causes all images to display.
Examples
Command: q image
Command: query image -fromnode=avalon -fromowner=kutras
Command: q i /usr -inactive
The query inclexcl command displays a list of include-exclude statements in the order in which they will process during backup and archive operations. The list displays the type of option, the scope of the option (archive, all, etc.), and the name of the source file.
You can test the validity of patterns you wish to use in your include-exclude list before you actually insert them in your options file. See the test pattern explanation below.
Syntax
>>-Query INCLexcl- -+--------------+--------------------------->< '-test pattern-'
Parameters
If the test pattern has no errors, the compiled pattern result is the same as the test pattern.
Examples
Command: query inclexcl
Command: query inclexcl /.../?x?/*.log
The query mgmtclass command displays information about the management classes available in your active policy set.
Your administrator defines management classes that contain attributes controlling whether a file is eligible for backup or archive services. Management classes also determine how backups and archives are managed on the server.
Your active policy set contains a default management class; it can contain any number of additional management classes. You can assign specific management classes to files using include options that are located in the client user options file dsm.opt. If you do not assign a management class to a file, Tivoli Storage Manager uses the default management class.
Syntax
>>-Query Mgmtclass--+----------+------------------------------->< '- options-'
Parameters
You can also use the scrolllines and scrollprompt common options with the query mgmtclass command. For more information about these common options, see "Setting Common Options".
Examples
Command: query mgmtclass
The query node command displays all the nodes for which an administrative user ID has authority to perform operations. The authorized administrative user ID should have at least client owner authority over both the NAS node and the client workstation node they are using either from command line or from the web.
When using an interactive command line session with a non-administrative ID, Tivoli Storage Manager prompts for an administrator ID.
Use the type option to specify the type of node to filter for. Valid values are nas, client, server and any. The default is any. See Type for more information.
Syntax
>>-Query Node-+----------+------------------------------------->< '- options-'
Parameters
Use the scrolllines and scrollprompt common options with the query node command. For more information, see "Setting Common Options".
Examples
Command: query node -type=nas
The query restore command displays a list of your restartable restore sessions in the server database. The list contains the following fields: owner, replace, subdir, preservepath, source, and destination.
Certain restore operations, called restartable restore sessions, start a special protocol within Tivoli Storage Manager. Some restore sessions can be restarted for these reasons:
Syntax
>>-Query Restore--+----------+--------------------------------->< '- options-'
Parameters
Examples
Command: query restore
The query schedule command displays the events scheduled for your node. Your administrator can set up schedules to perform automatic backups and archives for you. To plan your work, use this command to determine when the next scheduled events occur.
Syntax
>>-Query SCHedule--+----------+-------------------------------->< '- options-'
Parameters
Examples
Command: query schedule
The query session command displays information about your session, including the current node name, when the session was established, server information, and server connection information.
Syntax
>>-Query SEssion--+----------+--------------------------------->< '- options-'
Parameters
Examples
Command: query session
A sample query session display follows:
Tivoli Storage Manager Command Line Backup Client Interface - Version 3, Release 7, Level 0.0 (C) Copyright IBM Corporation, 1990, 1999 All Rights Reserved. Node Name: EPSILON3 Session established with server FIJI_0918GA: AIX-RS/6000 Server Version 3, Release 1, Level 0.0 Server date/time: 09/04/1999 15:09:52 Last access: 09/04/1999 15:09:40 Server Connection Information Server Name.............: FIJI_0918GA Server Type.............: AIX-RS/6000 Server Version..........: Ver. 3, Rel. 1, Lev. 0.0 Last Access Date........: 09/04/1999 15:09:40 Delete Backup Files.....: Yes Delete Archive Files....: Yes Node Name...............: EPSILON3 User Name...............: thompson
The restart restore command displays a list of your restartable restore sessions in the server database. You can only restart one restartable restore session at a time. Run the restart restore command again to cancel additional restores.
The restarted restore uses the same options you used in the failed restore. The restarted restore continues from the point at which the restore previously failed.
To cancel restartable restore sessions, use the cancel restore command. Use the restart restore command when:
Options from the failed session supersede new or changed options for the restarted session.
Syntax
>>-RESTArt Restore--+----------+------------------------------->< '- options-'
Parameters
For information about common options you can use with the restart restore command, see "Setting Common Options".
Examples
Command: restart restore
The restore command obtains copies of backup versions of your files from a server. To restore files, specify the directories or selected files, or select the files from a list. Restore files to the directory from which you backed them up or to a different directory. Tivoli Storage Manager uses the preservepath option with the subtree value as the default for restoring files. For more information, see Preservepath.
When you restore an entire directory or directory tree, and you do not specify the inactive, latest, pick, todate, and fromdate options on the restore command, Tivoli Storage Manager tracks which objects are restored. If the restore process is interrupted for any reason, you can restart the restore at the point of interruption by entering the restart restore command. It is possible to create more than one restartable restore session. Restores are only restartable if the filespec is fully wildcarded. For example, for a restore which is restartable, enter:
dsmc rest /home/* -sub=yes
For a restore which is not restartable, enter:
dsmc rest /home/file?.c -sub=yes
Use the query restore command to display a list of your restartable restore sessions in the server database. Further backups of the file system cannot be performed unless the restartable restore completes using the restart restore command or is cancelled using the cancel restore command.
Syntax
.- FILE-. >>-REStore--+-------+--+----------+--+- sourcefilespec---+------> '- options-' '- "sourcefilespec"-' >--+----------------------+------------------------------------>< '- destinationfilespec-'
Parameters
You can use these common options with the restore command: replace, restoremigstate, subdir. See "Setting Common Options" for information about common options.
Examples
Command: restore /home/devel/projecta/budget
Command: restore file budget
Command: restore "/home/devel/projecta/*.c"
Command: restore "/user/project/*" -pick -inactive
Command: restore "/home/devel/projecta/*.c" /home/newdevel/projectn/
Command: res -pitd=8/17/1998 -pitt=13:00:00 /home/mydir/
Command: res /home/myid/*
Command: res -filelist=/home/avi/restorelist.txt /home/NewRestoreLocation/
The restore backupset command restores a backup set from the server, a local file, or a local tape device.
If you are restoring a file space from a backup set to a system that did not perform the original backup, you may need to:
dsmc restore backupset backupsetname {/fsname}/* /destfs/ -subdir=yes
You must be a root user to restore an entire backup set from the server, otherwise only files you own are restored.A backup set can also be restored from a tape device on the AIX, AIX 5L, Solaris, and HP clients. See Location for information on supported tape devices and how to specify these devices.
If you are unable to restore a backup set from portable media, check with your Tivoli Storage Manager administrator to ensure that the portable media was created on a device using a compatible format.
Attention: If the object you want to restore is part of a backup set generated on a node, and the node name is changed on the server, any backup set objects that were generated prior to the name change will not match the new node name. Ensure that the node name is the same as the node for which the backup set was generated.
You can restore backup sets in a storage area network (SAN) in the following ways:
Syntax
>>-REStore BACKUPSET--+---------+--+- backupsetname-+-----------> '-options-' '- filename------' >--+- sourcefilespec---+--+----------------------+------------->< '- "sourcefilespec"-' '- destinationfilespec-'
Parameters
You can use these common options with the restore backupset command: quiet, replace, subdir. See "Setting Common Options" for information about these common options.
Examples
Command: dsmc restore backupset mybackupsetname -loc=server
Command: dsmc restore backupset "/home/budget/backupsetfile.name" -loc=file
Command: dsmc restore backupset "/dev/rmt0" -loc=tape
Command: dsmc restore backupset /dev/rmt0 "/home/jones/budget.dev" -loc=tape
Command: dsmc restore backupset /dev/rmt0 "/home/budget/*.txt" -loc=tape
Command: dsmc restore backupset bset01.001 -loc=server
Command: dsmc restore backupset "/home/jones/bset01.file" -loc=file
The restore image command restores a single file system image that was backed up using the backup image command. This command can restore an active base image, or a point-in-time base image, with associated incremental updates.
This command is valid for AIX, AIX 5L, HP/UX, and Solaris only.
Syntax
>>-REStore Image--+----------+--+- sourcefilespec---+-----------> '- options-' '- "sourcefilespec"-' >--+----------------------+------------------------------------>< '- destinationfilespec-'
Parameters
The restore image command does not define or mount the destination file space. The destination file space must exist, it must be mounted, and it must be large enough to hold the source. If file systems are mounted on volume images, and you restore them to a different location, be aware of the following points:
Examples
Command: dsmc rest image /home/test
Command: dsmc restore image /home/proj -incremental -deletefiles
The restore nas command restores the image of a file system belonging to a Network Attached Storage (NAS) file server. The NAS file server performs the outboard data movement. A server process performs the restore.
Use the nasnodename option to specify the node name for the NAS file server. When using an interactive command line session with a non-administrative ID, Tivoli Storage Manager prompts for an administrator ID. The NAS node name identifies the NAS file server to the Tivoli Storage Manager server. You must register the NAS node name at the server. Place the nasnodename option in your client system options file dsm.sys. The value in the client system options file is the default, but this value can be overridden on the command line. See Nasnodename for more information.
You can use the pick option to display a list of NAS images owned by the NAS node you specify. From this list you can select one or more images to restore. If you select multiple images to restore using the pick option, do not use the monitor option or you will serialize the restores. To start multiple restore processes simultaneously when restoring multiple images, do not specify monitor=yes.
Use the monitor option to specify whether you want to monitor a NAS file system image restore and display processing information on your screen. See Monitor.
Use the monitor process command to display a list of current restore processes for all NAS nodes for which your administrative user ID has authority. The authorized administrative user ID should have at least client owner authority over both the NAS node and the client workstation node they are using either from command line or from the web.
Use the cancel process command to stop NAS restore processing. For more information, see Cancel Process.
The restore nas command is valid for AIX, AIX 5L, and Solaris clients only.
Regardless of client platform, NAS file system specifications use the forward slash (/) separator, as in this example: /vol/vol0.
Syntax
>>-REStore NAS--+----------+---- sourcefilespec-----------------> '- options-' >--+----------------------+------------------------------------>< '- destinationfilespec-'
Parameters
You can use these command line options with the restore nas command: inactive, pick, pitdate, pittime. For more information, see"Using Options with Commands".
Examples
Command: restore nas -nasnodename=nas1 /vol/vol1 /vol/vol2
Command: restore nas -nasnodename=nas2 -pick -inactive
The retrieve command obtains copies of archived files from the server. You can retrieve specific files or entire directories. Use the description option to specify the descriptions assigned to the files you want to retrieve.
You can also use the pick option on the command line to display a list of your archives. From this list, you can select the desired archive to retrieve.
Place the retrieved files in the same directory from which they were archived, or in a different directory. Tivoli Storage Manager uses the preservepath option with the subtree value as the default for restoring files. For more information, see "Using Options with Commands".
Syntax
>>-RETrieve--+----------+--+- sourcefilespec---+----------------> '- options-' '- "sourcefilespec"-' >--+----------------------+------------------------------------>< '- destinationfilespec-'
Parameters
You can use these common options with the retrieve command: replace, restoremigstate, subdir, tapeprompt. See "Setting Common Options" for information about common options.
Examples
Command: retrieve /home/devel/projecta/budget
Command: retrieve "/home/devel/projecta/*.c"
Command: retrieve "/home/"
Command: retrieve "/home/devel/projecta/*.c" /home/newdevel/projectn/
Command: ret "/user/project/*" -pick
Command: retrieve "/proj/*" -desc="1999 survey results"
Command:
mkfifo fifo dd if=fifo of=/dev/rmt1& dsmc retrieve -replace=yes -description="mybudget" /home/devel/budget fifo
Authorized User
The schedule command starts the client scheduler on your workstation. The client scheduler must be running before scheduled work can start.
If the schedmode option is set to polling, when you start the client scheduler it continuously contacts the server for scheduled events based on the time you specified with the queryschedperiod option in your client user options file dsm.opt. If your administrator sets the queryschedperiod option for all nodes, that setting overrides your setting.
If you are using TCP/IP communications, the server can prompt your workstation when it is time to run a scheduled event. To do so, set the schedmode option to prompted in the client user options file dsm.opt or on the schedule command.
After you start the client scheduler, it continues to run and to start scheduled events until you press Ctrl+C, stop the scheduler process with the UNIX kill command, start the workstation again, or turn off the workstation to end it.
Syntax
>>-SCHedule--+----------+-------------------------------------->< '- options-'
Parameters
Examples
Command: tsm::once:/usr/lpp/adsm/bin/dsmc sched > /dev/null 2>&1 #TSM Scheduler
Command: nohup dsmc sched 2> /dev/null &
The selective command backs up files that you specify. If these files become damaged or lost, you can replace them with backup versions from the server. When you run a selective backup, all the files are candidates for back up unless they are excluded from backup in your include-exclude list, or they do not meet management class requirements for serialization.
During a selective backup, copies of the files are sent to the server even if they did not change since the last backup. This might result in more than one copy of the same file on the server. If this occurs, you might not have as many different down-level versions of the file on the server as you intended. Your version limit might consist of identical files. To avoid this, use the incremental command to back up only new and changed files.
You can selectively back up single files or directories. You can also use wildcard characters to back up groups of related files.
During a selective backup, a directory path may be backed up, even if the specific file that was targeted for backup is not found. For example:
selective "/dir1/dir2/bogus.txt"
still backs up dir1 and dir2 even if the file bogus.txt does not exist.
If the selective command is retried because of a communication failure or session loss, the transfer statistics will display the number of bytes Tivoli Storage Manager attempts to transfer during all command attempts. Therefore, the statistics for bytes transferred may not match the file statistics, such as those for file size.
Syntax
.-----------------. V | >>-SELective--+----------+----+- filespec---+-+---------------->< '- options-' '- "filespec"-'
Parameters
You can use these common options with the selective command: changingretries, quiet, tapeprompt, subdir, . See "Setting Common Options" for information about these common options.
Examples
Command: selective /home/devel/proja
Command: selective "/home/devel/proj*"
Command: selective "/home/devel/proj*" /user/home/budget
Command: selective /home/
The set access command gives users at other nodes access to your backup versions, archived copies, or backup images. You can give another user access to a specific file or image, multiple files or images, or all files or images in a directory. When you give access to another user, that user can restore or retrieve your objects. Specify in the command whether you are giving access to archives or backups.
Syntax
>>-SET Access--+- Archive-+--+- filespec-+-- node--+-------+----> '- Backup--' '-image-fs--' '- user-' >--+--------------+-------------------------------------------->< | .----------. | | V | | '--- options-+-'
Parameters
If you give access to a branch of the current working directory, you only need to specify the branch. If you give access to objects that are not in a branch of the current working directory, you must specify the drive and directory. The file spec to which you gave access must have at least one backup version or archive copy object (file or directory) on the server.
To give access to all objects below a certain level, use an asterisk, directory delimiter, and an asterisk at the end of your file spec. For example, to give access to all objects below home/test, use file spec home/test/*/*.
To specify all files or images in a named directory, enter home/mine/proj1/* on the command line. To specify all files or images in all directories off of the root directory, enter /*/* on the command line. Enter /* on one set access command and /*/* on another if you want another user to have complete access to your file space. The first /* gives access to all subdirectories and all files or images off of the root directory.
Examples
Command: set access backup /home/user/budget node_2
Command: set access ret "/home/devel/proja/*.c" node_3 user_c
Command: set ac archive /home/devel/proja/node_3
Command: set ac b {project} "*" "*bldgb"
Command: set ac b "/acct/paid/*/*" "*"
Command: set acc backup "home/devel/proja/*/*" node_5 serena
Authorized User
The set password command changes the Tivoli Storage Manager password for your workstation. You are prompted twice for your new password.
A password is not case-sensitive, and it can be as many as 64 characters. Valid characters are:
Syntax
>>-SET Password--+--------------+--+----------+---------------->< '- oldpw newpw-' '- options-'
Parameters
Examples
The following is an example of using the set password command.
Command: set password osecret nsecret