IBM Tivoli Software IBM Tivoli Software

[ | | | ]


IBM Tivoli Storage Manager for Space Management for UNIX: User's Guide


Using Commands

You can use hierarchical storage management (HSM) commands rather than the graphical user interface (GUI) to perform most space management tasks. This chapter provides information about using these commands. For information about client system options, see "Using Options".

Note:
The GUI is available for root users only. It is not available for HSM on AIX GPFS or HP-UX VxFS.

Entering Commands

When you enter commands, follow these rules:

Enter Options With Commands

Use either a standard format (the complete option name), or a short format (a one or two-letter form of the option name) to enter options. The standard format is the default. Specify the format (either standard or short) on the optionformat option in your dsm.opt file. If you do not specify a format, the default is used.

Use the Standard Format

If you set the optionformat option to standard in your dsm.opt file, enter options using the complete option name. For example, enter commands and options in this manner:

   dsmmigrate -Recursive -Detail /home/user1/file1

Follow these rules when you use options with commands:

Use the Short Format

If you set the optionformat option to short in your dsm.opt file, enter options using an abbreviation. Uppercase letters in each option description indicate the minimum abbreviation that is permitted. For example, enter commands and options in this manner:

   dsmmigrate -R -v /home/user1/file1

Follow these rules when you use options with commands:


Displaying Online Help for Commands

You can display online help for HSM commands in either of the following ways:


Hierarchical Storage Management Commands

Table 18 provides an alphabetical list of the HSM client commands, a brief description of each command, and the command page number.

Table 18. HSM Commands

Command Description Page
dsmattr Valid for AIX JFS and AIX GPFS only

Sets or displays the recall mode for a migrated file.

dsmattr
dsmautomig Starts parallel migration sessions for a file system. dsmautomig
dsmdf Displays space usage information for a file system. dsmdf
dsmdu Displays space usage information for files and directories. dsmdu
dsmls Lists files in a directory and displays file state. dsmls
dsmmigfs Adds space management to a file system, or updates space management attributes for a file system. dsmmigfs

Deactivates or reactivates space management for a file system, or removes space management from a file system. dsmmigfs

Manages recovery from partial system failure (GPFS only). dsmmigfs

Displays current space management settings for a file system. dsmmigfs

Deactivates or reactivates space management for your client node. dsmmigfs

Imports and exports the HSM management of a file system within an HACMP environment. dsmmigfs

Transfers the HSM management of a file system to a local node within the same local GPFS node set. dsmmigfs

Transfers the HSM management of a file system to the preferred node if the node is different from the current owner node. dsmmigfs
dsmmighelp Displays online help for commands. dsmmighelp
dsmmigquery Displays space management information. dsmmigquery
dsmmigrate Moves selected files from your local file system to Tivoli Storage Manager storage. dsmmigrate
dsmmigundelete Recreates deleted stub files. dsmmigundelete
dsmmode Valid on AIX JFS file systems only

Sets one or more execution modes that affect the space management-related behavior of commands.

dsmmode
dsmmonitord Starts the space monitor daemon. dsmmonitord
dsmq Displays information, including recall IDs, for all files that are currently queued for recall. dsmq
dsmrecall Moves selected files from storage to your local file system. dsmrecall
dsmrecalld Starts the recall daemon. dsmrecalld
dsmreconcile Synchronizes the client and server. dsmreconcile
dsmrm Removes a recall process from the recall queue. dsmrm
dsmrootd Starts the root daemon. dsmrootd
dsmscoutd Valid on AIX JFS, Solaris VxFs, and HP-UX VxFs file systems only

Starts the scout daemon.

dsmscoutd
dsmsetpw Changes the Tivoli Storage Manager password for your client node. dsmsetpw
dsmwatchd Valid on AIX GPFS and Linux86 GPFS file systems only

Manages failover activities for your local node.

dsmwatchd

dsmattr

Valid on AIX JFS and AIX GPFS file systems only

The dsmattr command sets or changes the recall mode for one or more migrated files. The recall mode determines how the HSM client recalls a migrated file when you access it. You can specify normal, migrate-on-close, or read-without-recall mode. You cannot set a recall mode for a resident or a premigrated file. The recall mode that you set for a migrated file remains associated with that file only as long as the file remains migrated.

See "Recalling Your Migrated Files" for more information.

Attention: Do not set the recall mode to read-without-recall for a file residing on a file system that an NFS server exported. This mode holds recalled file data in memory. It is not compatible with NFS access, which uses asynchronous reads. If you accidentally set this attribute on a file that a remote NFS client accesses, the HSM client recalls the file and automatically sets the recall attribute of the file to normal.

Syntax

                              .---------------.
                              V               |
>>-dsmattr--+--------------+------ filespec---+----------------><
            | .----------. |
            | V          | |
            '--- options-+-'
 
 

Parameters

options
Use one or both of the following options. For example, to change the recall mode to migrate-on-close (AIX JFS HSM only) for a file named /home/user1/file1, enter:
   dsmattr -rm /home/user1/file1
-RECAllmode=value or -rvalue
Sets a recall mode for one or more migrated files. If you do not use the -RECAllmode option, the HSM client displays the current recall mode for the files that you specify. The values that you can select are:
Value Description
- Indicates that the file has not migrated.
Normal (n) Recalls the migrated file to its originating file system. This is the default. If the file is not modified, it becomes a premigrated file. If the file is modified, it becomes a resident file.
Migonclose (m) (AIX JFS HSM only) Temporarily recalls a migrated file to its originating file system. If the file is not modified, the file is replaced with a stub file on your local file system. The file returns to a migrated state when it is closed.
Readwithoutrecall (r) (AIX JFS HSM only)
Note:
The Readwithoutrecall parameter is valid for a 32-bit client only.
Reads the migrated file from storage without storing it on your local file system. Information is read sequentially from your file and is cached in a memory buffer on your workstation.
Partialrecall (p) (AIX GPFS HSM only) Specifies that the file should be recalled using partial file recall, regardless of its size.
Streaming (s) (AIX GPFS HSM only) Specifies that you want to enable an asynchroneous recall of migrated files. The recalled portion of the file can be accessed while the file is recalled. This parameter is valid for read-only operations on the file.
-RECUrsive or -R
Sets or displays the recall mode for migrated files in the directory and subdirectories that you specify.
filespec

Attention: This parameter is required only when you set a new recall mode. If you do not use the -RECAllmode option, and you do not specify a path and a file name, the current recall mode displays for all files in the current directory.

The path and file name of the file for which you want to set a new recall mode, or display the current recall mode. You can specify a single file, a group of files, or a directory. If you specify a directory, the HSM client sets or displays that recall mode for each migrated file in the directory.

You can use wildcard characters to specify a group of files with similar names. You can enter more than one file specification in a command. If you enter several file specifications, separate each specification with one or more blank spaces.

Examples

Task Command
Change the recall mode to migrate-on-close for a file named /home/user1/file1. dsmattr -recall=migonclose /home/user1/file1
Change the recall mode to read-without-recall for all migrated files that begin with JAN in the/home/user1 directory. dsmattr -recall=readwithoutrecall /home/user1/JAN*
Change the recall mode to migrate-on-close for all migrated files in the /home/user1 directory and all of its subdirectories. dsmattr -recall=migonclose -R /home/user1
Change the recall mode to partial file recall for all migrated files in the /home/user2 directory and all of its subdirectories. dsmattr -recall=partialrecall -R /home/user2
Enable an asynchroneous recall of migrated files in the /home/user2/ directory. dsmattr -recall=streaming /home/user2/
Display the recall modes that are assigned to all files in the current directory. dsmattr

dsmautomig

You must have root user authority to use this command.

The dsmautomig command:

Note: If the LANG environment variable is set to C, POSIX (limiting the valid characters to those with ASCII codes less than 128), or other values with limitations for valid characters, the HSM client skips files which have file names containing invalid characters with ASCII codes higher than 127. If you are using a single-byte character set (SBCS) such as English as your language environment, all file names are valid and are migrated by the HSM client.

Multi-byte characters are interpreted as a set of single bytes all containing valid characters. If you are using multi-byte character sets (MBCS) as your language environment, the HSM client migrates file names that consist of valid characters in the current environment. For example, a file name consisting of Japanese characters may contain invalid multi-byte characters if the current language environment is a Chinese character set. Files containing invalid multi-byte characters are not migrated or recalled. If such files are found during migrate or recall no information is printed. The HSM daemons must run in the en_US language locale (or another SBCS language locale) to work properly.

Specify the number of parallel migration sessions with the maxmigrators option in your dsm.sys file. Verify that sufficient resources are available on the Tivoli Storage Manager server for parallel migration. Do not set the maxmigrators option higher than the number of sessions that the Tivoli Storage Manager server can use to store data. Start threshold migration manually to lower space usage on your file system before it reaches the high threshold that you set.

The scout daemon (dsmscoutd) should be running if you start the dsmautomig command manually. Otherwise, the dsmautomig command might not be able to complete the migration if it runs out of candidates from the candidates list.

Note:
The dsmautomig and dsmreconcile processes must be found with the PATH variable, or the dsmmonitord daemon cannot perform reconcilation and threshold migration.

Syntax

>>-dsmautomig--+---------+--+---------------------+------------><
               '- detail-'  | .-----------------. |
                            | V                 | |
                            '--- filesystemspec-+-'
 
 

Parameters

-detail or -v
Displays information about migrated files.
filesystemspec
The name of the file system for which you want to run threshold migration. The default is all file systems for which space management is active. You can specify more than one file system name, and you can use wildcard characters within a file system name. If you specify more than one file system name, separate each name with one or more blank spaces.

Examples

Task Command
Start threshold migration for all file systems for which space management is active. dsmautomig
Start threshold migration for the /home file system. dsmautomig /home
Start threshold migration for the /home and /test1 file systems. dsmautomig /home /test1

dsmdf

The dsmdf command displays the following information for one or more file systems:

Only migration and recall processes dynamically update status information for your file systems. If any other process changes the state of a file, the change is not reflected in the information that the dsmdf command displays until reconciliation is run.

For AIX GPFS and Linux86 GPFS file systems only: Migrating newly-created files of less then five minutes might display incorrect results (resident size) when you use the dsmdf and dsmdu commands. This is because GPFS is not synchronized on all nodes when you migrate files. The last block of a file is not released from the disk although the file migrated successfully. This can cause a deviation from an assumed disk usage if many small files are migrated and the block size is high.

Syntax

>>-+-dsmdf-+--+---------------------+--------------------------><
   '-ddf---'  | .-----------------. |
              | V                 | |
              '--- filesystemspec-+-'
 
 

Parameters

filesystemspec
The name of the file system for which you want to display information. The default is all file systems to which you added space management. You can specify more than one file system name, and you can use wildcard characters within a file system name. If you specify more than one file system name, separate each name with one or more blank spaces.

Examples

Task Command
Display information for all file systems to which you added space management. dsmdf
Display information for the /home file system. dsmdf /home

dsmdu

The dsmdu command displays space usage information for files and directories. For migrated files, the dsmdu command uses the actual size of the files that are stored in Tivoli Storage Manager storage to calculate space usage. In contrast, the du command (provided with your operating system) uses the size of the stub files that are stored in your local file system.

For AIX GPFS and Linux86 GPFS file systems only: Migrating newly-created files of less then five minutes might display incorrect results (resident size) when you use the dsmdf and dsmdu commands. This is because GPFS is not synchronized on all nodes when you migrate files. The last block of a file is not released from the disk although the file migrated successfully. This can cause deviation from assumed disk usage if many small files are migrated and blocksize is high.

Syntax

>>-+-dsmdu-+--+---------+--+--------------------+--------------><
   '-ddu---'  '- option-'  | .----------------. |
                           | V                | |
                           '--- directoryspec-+-'
 
 

Parameters

options
If you do not specify either of the following options, the HSM client displays the number of 1 KB blocks that the specified directory and each of its subdirectories use.
-Allfiles or -a
Displays the number of 1 KB blocks that each file in the specified directory and each of its subdirectories use.
-Summary or -s
Displays only the total of 1 KB blocks that the specified directory and its subdirectories use.
directoryspec
The directory for which you want to display information. The default is the current directory and its subdirectories. Use wildcard characters to specify more than one directory. You can enter more than one directory specification in one command. If you enter several directory specifications, separate each name with one or more blank spaces.

Examples

Task Command
Display space usage information for the current directory and all of its subdirectories. dsmdu
Display space usage information for the /migfs3/test directory and all of its subdirectories. dsmdu /migfs3/test
Display space usage information for each file in the /migfs2/test directory and in all of its subdirectories. dsmdu -a /migfs2/test
Display the total number of 1 KB blocks that the /migfs2/test directory and all of it subdirectories use. dsmdu -Summary /migfs2/test

dsmls

The dsmls command displays the following information about a list of files:

For a resident or premigrated file, the actual size and resident size are the same. For a migrated file, the actual size is the size of the original file. The resident size is the size of the stub file that remains on your local file system.

The file state for a file can be any of the following: migrated (m), premigrated (p), or resident (r). A dash (-) indicates a directory or a non-regular file; for example, a character special file or a named pipe file. For a migrated file, the dsmls command also indicates the recall mode that you set for the file:

Syntax

>>-+-dsmls-+--+--------------+--+---------------+--------------><
   '-dls---'  | .----------. |  | .-----------. |
              | V          | |  | V           | |
              '--- options-+-'  '--- filespec-+-'
 
 

Parameters

options
Use any of the following options:
-Noheader or -n
Omits column headings from the output for this command.
-Recursive or -R
Displays information about files in subdirectories of the directory.
filespec
The path name for the files that you want to list. The default is all files in the current directory. Use wildcard characters to specify a group of files or all the files in a directory. You can enter more than one file specification in a command. If you enter several file specifications, separate each specification with one or more blank spaces.

Examples

Task Command
List all files in the current directory. dsmls
List all files in the /migfs2/test directory. dsmls /migfs2/test
List all files in the /migfs2/test directory and in its subdirectories. dsmls -Recursive /migfs2/test
List all files whose names begin with tf in the /migfs2/test directory. dsmls /migfs2/test/tf*

dsmmigfs

You must have root user authority to use this command.

The dsmmigfs command adds space management to your file system, or updates space management settings for your file system.

For AIX GPFS and Linux86 GPFS file systems only: Before you run dsmmigfs add filesystemName, ensure that file system is mounted and enabled for DMAPI management. Run the following:

For AIX GPFS:
/usr/lpp/mmfs/bin/mmlsfs DevicePath
 
For Linux86 GPFS:
/opt/lpp/mmfs/bin/mmlsfs DevicePath

Search for the status of the -z flag. If DMApi is not enabled on your file system, run the following:

For AIX GPFS:
/usr/lpp/mmfs/bin/mmchfs DevicePath -z yes
 
For Linux86 GPFS:
/opt/lpp/mmfs/bin/mmchfs DevicePath -z yes

Run only one dsmmigfs command within the local GPFS node set at the same time.

In an HACMP or IBM Cluster 1350 environment: In the event of a system failure, specify the import parameter to access your data. The result permits an individual file system to specify a certain server stanza to manage your file system. Your file system can contain migrated files but it is not required to have them. The connection is made by adding an entry for the file system to /etc/tsm/SpaceMan/config/dsmmigfstab. A link is also created for the status file in /etc/tsm/SpaceMan/status. The export parameter removes the connection.

You cannot add space management to your root (/), /tmp, /usr, or /var file systems.

Syntax

>>-dsmmigfs--+- Add----+--+--------------+---------------------->
             '- Update-'  | .----------. |
                          | V          | |
                          '--- options-+-'
 
   .---------------------.
   V                     |
>------ filesystemSpec---+-------------------------------------><
 
 

Parameters

Add
Adds space management to your file systems.
Update
Updates one or more space management settings for a file system to which you added space management.

If you change the high and low thresholds or the premigration percentage, the new values take effect immediately. If you change the stub file size, the new size is used only for files that are migrated after you make the change. If you change the age or size factor, the new value is used the next time a migration candidates list is built.

If you reduce the quota, and the amount of migrated and premigrated data exceeds the new quota, the HSM client does not migrate any additional files until enough files are recalled during automatic recall or selective recall to drop the total number of megabytes for migrated and premigrated files below the new quota.

filesystemSpec
The file system name to perform the specified action. You can specify more than one file system name, and you can use wildcard characters within a file system name. If you specify more than one file system name, separate each name with one or more blank spaces.
options
Use the option settings that are provided for this command to add or update space management settings. See the table that follows for options and information.

Table 19. Space Management Option Settings

Option Short Name Description
-HThreshold=n -tn The high threshold percentage that you set for space usage on your file systems. Specify a value of zero through 100 percent. The default is 90 percent.
-Lthreshold=n -ln The low threshold percentage that you set for space usage on your file systems. Specify a value of zero through 100 percent. The default is 80 percent.
-Maxcandidates=n -mn The maximum number of migration candidates the dsmscoutd daemon searches for during one scan period. When this number is reached, dsmscoutd stops scanning. The range of values that you can enter are nine through 9999999. The default is 10000.
-MINPartialrecallsize=n (AIX GPFS HSM only) -nn Specifies the minimum size (in megabytes) that a file must have to qualify for partial file recall. The range of values is 0 to 999999999. A value of 0 disables partial file recall for all files; this is the default.
-MINStreamfilesize=n (Valid for AIX GPFS, Linux86 GPFS, and Solaris VxFs) -nn Specifies a number to enable or disable an asynchroneous recall of migrated files. This number is the number of bytes that must be recalled before HSM starts streaming data to the requesting application (to ensure a steady stream of data). The recalled portion of the file can be accessed while the file is recalled. The range of values is zero through 2147483647. The default is zero. Zero disables the asynchroneous option.
-Pmpercentage=n -pn The percentage of file system space that is available to contain premigrated files. The default is the difference between the percentage that you set for the high threshold and the percentage that you set for the low threshold. Specify a value from zero through 100 percent.
-Agefactor=n -an Assign an age factor to your files in each file system to which you added space management. The age and size factors determine the order in which eligible files migrate to Tivoli Storage Manager storage. Specify a value of zero through 999999999. The default is one.
-SIzefactor=n -in Assign a size factor to your files in each file system to which you added space management. The age and size factors determine the order in which eligible files migrate to Tivoli Storage Manager storage. Specify a value of zero through 999999999. The default is one.
-Quota=n -qn The maximum number of megabytes of data that you can migrate and premigrate from your file system to Tivoli Storage Manager storage. Specify a value from zero to 999999999. The default is the number of megabytes that are allocated for your file system.
-STubsize=n -stn The size of stub files remaining on your local file systems when files migrate to Tivoli Storage Manager storage.
  • For AIX GPFS and Linux86 GPFS file systems: Specify a value of zero or a multiple of the physical block size. The default is zero.
  • For AIX JFS file systems: Specify a value of size fragment size or a multiple of the physical block size. The default is the fragment size.
  • For Solaris VxFS and HP-UX VxFS file systems: Specify a value of one or a multiple of the physical block size. The default is the block size.
-SErver=<servername> -Sserver name Overrides the default migration server for this file system. Specify the server to contact for space managment services. Define the server in a stanza in your dsm.sys file. If you do not specify a server name, the default migration server is used. Use a dash (-) to set the server to the default migration server. After you use the import parameter, perform a reconcile to update the status file.

Examples

Task Command
Add space management to the /home file system and set the high threshold to 80 percent and the low threshold to 70 percent. dsmmigfs Add /home -t80 -l70
Add space management to more than one file system and accept the default values for all space management settings. dsmmigfs Add /home /test1 /proj*
Update the space management settings for the /home file system as follows:
  • Change the high threshold to 80 percent.
  • Change the low threshold to 70 percent.
  • Set the size factor to zero to ensure that the number of days since a file was last accessed is the only factor that determines when eligible files are prioritized for migration.
dsmmigfs Update -t80 -l70 -i0 /home
Specify the minimum size of files in the /home/user1 file system that will be recalled using partial file recall. dsmmigfs Update -minp=100 /home/user1

dsmmigfs

You must have root user authority to use this command.

Use the dsmmigfs command with the deactivate, reactivate, remove or export parameter to do the following:

Syntax

                              .---------------------.
                              V                     |
>>-dsmmigfs--+- Deactivate-+------ filesystemspec---+----------><
             +- REActivate-+
             '- REMove-----'
 
 

Parameters

Deactivate
Deactivates space management for a file system. The HSM client cannot perform migration, recall, or reconciliation for the file system. However, you can update space management settings for your file system, and access resident and premigrated files.
REActivate
Reactivates space management for a file system.
REMove
Removes space management from a file system. If you deactivated space management for your file system, reactivate it before you remove space management. If any orphaned stub files are located, the command fails. To remove space management, resolve all orphaned stub files, and enter the dsmmigfs command again.
filesystemspec
The file system name that performs the specified action. You can specify more than one file system name, and you can use wildcard characters within a file system name. If you specify more than one file system name, separate each name with one or more blank spaces.

Examples

Task Command
Deactivate space management for the /home file system. dsmmigfs Deactivate /home
Reactivate space management for the /home file system. dsmmigfs REActivate /home
Remove space management from the /home file system. dsmmigfs REMove /home

dsmmigfs

Valid on AIX JFS file systems for HACMP and Linux86 GPFS file systems for IBM Cluster 1350 environments only. You must have root user authority to use this command.

The dsmmigfs command allows an HSM-managed file system to be part of a resource group in an HACMP or IBM Cluster 1350 cluster. In the event of a system failure, you can obtain access to the data from another system.

Syntax

>>-dsmmigfs--+- EXPort-+--+--------------+---------------------->
             '- IMPort-'  | .----------. |
                          | V          | |
                          '--- options-+-'
 
   .---------------------.
   V                     |
>------ filesystemSpec---+-------------------------------------><
 
 

Parameters

Export
Removes an HSM-managed file system from the current file system without recalling the file data. When you export space management from a file system, HSM removes the entry for your file system /etc/adsm/SpaceMan/config/dsmmigfstab and unmounts the fsm-mounted file system. Enter this command before the AIX or Linux86 volume group export (exportvg).
Note:
The export command does not reconcile the file system or delete the .SpaceMan directory.
Import
When you import a file system, HSM connects a takeover file system to your local system. Use this command after the AIX or Linux86 import volume group (importvg) occurs. Run the dsmreconcile command to update the status file for your file system after you enter dsmmigfs import.
-SErver=server name option
The server to contact for space managment services. Define the server in a stanza in your dsm.sys file. If you do not specify a server name, the default migration server that is defined in your dsm.opt file is used. To set the server to the default migration server, you also can specify the string "-" for the server option.
Note:
This option applies to the import parameter only.
filesystemspec
The file system name that performs the specified action. You can specify more than one file system name, and you can use wildcard characters within a file system name. If you specify more than one file system name, separate each name with one or more blank spaces.

Examples

Task Command
Export space management for the /home file system. dsmmigfs export /home
Import the space-managed file system, /home, for server, HSMServer. dsmmigfs import /home -server=HSMServer

dsmmigfs

Valid on AIX GPFS and Linux86 GPFS file systems only. You must have root user authority to use this command.

The dsmmigfs command used with the SDRreset, SDRupdate, enableFailover, or disabledFailover parameter manages recovery from partial system failure. One HSM client can take over from an HSM client that is involved in a partial system failure if the following conditions are true:

Syntax

>>-dsmmigfs--+- SDRupdate-------+------------------------------><
             +- SDRreset--------+
             +- enableFailover--+
             '- disableFailover-'
 
 

Parameters

Note:
These SDR-related parameters also are valid for an AIX cluster (IBM Regatta pSeries 690) even if a System Data Repository is not available on those clusters.
SDRupdate
The dsm.opt file and the dsm.sys file are stored in the SDR. The set of two options files in the SDR become the single, shared set of options files for all HSM clients within the local GPFS node set. After you update your dsm.opt or dsm.sys file, use this command to synchronize all participating nodes within a GPFS node set.
SDRreset
Do not use this command during normal operation.

The HSM client attempts to reset potential locking problems in the SDR. If a command or a failover operation ended abnormally, this command will help to achieve a consistent system state.

enableFailover
Activates the local node for failover operations within the local GPFS node set.
disableFailover
Deactivates failover operations on the local node.

Examples

Task Command
Deactivate failover operations on the local node. dsmmigfs disableFailover

dsmmigfs

The dsmmigfs command used with the query parameter displays the current space management settings for a file system.

Syntax

>>-dsmmigfs--query--+--------------+--+---------------------+--><
                    | .----------. |  | .-----------------. |
                    | V          | |  | V                 | |
                    '--- options-+-'  '--- filesystemspec-+-'
 
 

Parameters

Query or -q
Displays the current space management settings for the named file system. The settings include values for the following:
Note:
These settings are only displayed if you specify -Detail or -v: maxcandidates, minpartialrecallsize, and minstreamfilesize.
options
-Detail or -v
Displays HSM settings for each file system. Displays options that the HSM client does not display in the standard format, such as the maximum number of candidates that are located during one reconciliation.

For AIX GPFS and Linux86 GPFS file systems only: The dsmmigfs -query command displays only locally-managed file systems. The dsmmigfs q -d command displays information for all space-managed file systems within the local GPFS node set. The HSM client displays the following additional information:

  • Node name for each node ID and frame ID for both the owner and the preferred nodes.
  • Preferred node ID. The preferred node defines the node where HSM was initially added to the filesystem.
  • Frame ID.
  • Current owner node ID. The owner node ID defines the node that is currently managing the filesystem.
  • GPFS node set ID.

The normal dsmmigfs query will not provide any GPFS-specific information (no node set ID).

Note:
The failover environment is active on the local node. The dsmmigfs query -detail displays the current status of the local failover environment (either active or inactive).
-failover or -f
Provides a status overview of the failover environment of all HSM-managed cluster nodes. The output displays the status for the node name, node ID and frame ID. It can be any of the following:
  • Active. The node participates in the failover environment within the local GPFS node set.
  • Deactivated by User. You disabled failover using the dsmmigfs disableFailover command.
  • Deactivated by HSM. The HSM client disabled failover because of an unrecoverable condition.
filesystemspec
The file system name that displays current space management settings. The default is all file systems to which space management has been added.

Examples

Task Command
Display the current space management settings for the /migfs2 file system. dsmmigfs query /migfs2

dsmmigfs

You must have root user authority to use this command.

Use the dsmmigfs command with the Globaldeactivate or Globalreactivate parameter to:

Syntax

>>-dsmmigfs--+- GLOBALDeactivate-+-----------------------------><
             '- GLOBALReactivate-'
 
 

Parameters

GLOBALDeactivate
Deactivates space management for all file systems on your client node. The HSM client cannot perform migration, recall, or reconciliation for any file system. However, you can update space management settings for file systems, add space management to additional file systems, or access resident and premigrated files.
GLOBALReactivate
Reactivates space management for your client node. All file systems to which you added space management return to their previous state, including that which you added while space management was globally deactivated.

Examples

Task Command
Globally deactivate space management for your client node. dsmmigfs GLOBALDeactivate
Globally reactivate space management for your client node. dsmmigfs GLOBALReactivate

dsmmigfs

Valid on AIX GPFS and Linux86 GPFS file systems only. You must have root user authority to use this command.

The dsmmigfs command transfers the HSM management of filesystem fileSpec to the local node within the same local GPFS node set.

Syntax

>>-dsmmigfs takeover-- filespec--------------------------------><
 
 

Parameters

takeover
Transfers the HSM management of filesystem filespec to the local node within the same local GPFS node set.
filespec
The path name for the files that you want to list. The default is all files in the current directory. Use wildcard characters to specify a group of files or all the files in a directory. You can enter more than one file specification in a command. If you enter several file specifications, separate each specification with one or more blank spaces.

Examples

dsmmigfs

Valid on AIX GPFS and Linux86 GPFS file systems only. You must have root user authority to use this command.

The dsmmigfs command transfers the HSM management of file systems to the preferred node if the node is different from the current owner node.

Syntax

>>-dsmmigfs rollback-------------------------------------------><
 
 

Parameters

rollback
Transfers the HSM management of file systems to the preferred node if the node is different from the current owner node. Enter this command on the preferred node.

Examples

Task Command
Transfer to the preferred node. dsmmigfs rollback

dsmmighelp

The dsmmighelp command displays online help topics from which you can select general help for commands or message information.

Syntax

>>-dsmmighelp--------------------------------------------------><
 
 

Examples

Task Command
Display online help for HSM commands. dsmmighelp

dsmmigquery

You must have root user authority to use this command.

The dsmmigquery command displays the following information for one or more file systems:

Output from this command is directed to stdout. Use redirection characters and a file name at the end of the command to redirect the output to a file.

Syntax

>>-dsmmigquery--+--------------+--+---------------------+------><
                | .----------. |  | .-----------------. |
                | V          | |  | V                 | |
                '--- options-+-'  '--- filesystemspec-+-'
 
 

Parameters

Options
Select any of these options:
-Candidatelist or -c
Displays the current prioritized list of migration candidates for your file system. This is the default option.
-SORTEDMigrated or -m
Lists all files that you migrated from the file system to Tivoli Storage Manager storage in the most efficient order for recall.
-SORTEDAll or -s
Lists all files in the file system in this order: resident files, premigrated files, migrated files. Sorts migrated files in the most efficient order for recall.
-Mgmtclass or -g
Displays information about each management class that you can assign to your files.
-Detail or -v
Use with the -Mgmtclass option to display information about each available management class. If you do not use this option, the HSM client displays the management class name and a brief description only.
-Options or -o
Displays the current settings for your client and server options.
filesystemspec
The file system for which you want to display information. The default is the current file system. You can specify more than one file system name, and you can use wildcard characters within a file system name. If you specify more than one file system name, separate each name with one or more blank spaces.

Examples

Task Command
Display a migration candidates list for the /migfs1 file system. dsmmigquery /migfs1
Display information about management classes that you can assign to files on your client node. dsmmigquery -Mgmtclass -Detail

dsmmigrate

Attention: On large file systems, selective migration can take a while.

The dsmmigrate command selects specific files from your local file system and migrates them to a Tivoli Storage Manager server.

If the file resides in a file system with a different server stanza than the last processed file, a new session starts for each file that is migrated. This can happen as a result of links from one file system to another.

Note:
If you set the tapeprompt option to yes in your dsm.opt file, and the destination for your migrated file is a storage pool that consists of removable media such as tape, you are prompted either to wait for the medium to mount, or to skip the file.

The first file migrates even if the file size exceeds the quota that you specified for the file system. When migration occurs, the ddf command displays zero migrated and premigrated bytes for your file system. If the total number of bytes exceeds the quota after the file migrates, the next file is not migrated.

Syntax

                                 .---------------.
                                 V               |
>>-dsmmigrate--+--------------+------ filespec---+-------------><
               | .----------. |
               | V          | |
               '--- options-+-'
 
 

Parameters

Options
Select any of these options:
-Recursive or -r
Migrates files in any subdirectory below the specified directory that match the file specification. If you do not use this option, only those files from the directories that you specify are migrated.
-Detail or -v
Displays the size and file name for each file that you migrate.
filespec
The path and file name of the file that you want to migrate. This parameter is required. You can use wildcard characters to specify a group of files or all files in a directory. Or, you can enter more than one file specification in one command. If you enter more than one file specification, separate each specification with one or more blank spaces.

Examples

Task Command
Migrate all files in a directory named /migfs2/test/dir1 and in all of its subdirectories. Display the information. dsmmigrate -Rv /migfs2/test/dir1
Migrate a file named tf04 from the current directory and display the information. dsmmigrate -Detail tf04

dsmmigundelete

You must have root user authority to use this command.

The dsmmigundelete command recreates deleted stub files for migrated files, and creates stub files for premigrated files for which an original file does not exist on your local file system. The file then becomes a migrated file.

When you delete a stub file or an original copy of a premigrated file from your local file system, the corresponding migrated or premigrated file is marked for expiration when reconciliation runs again.

Note:
The dsmmigundelete command does not support hardlinked files. If you attempt to recreate a stub file for a hardlinked file, a stub file is not recreated unless all of the files that are hardlinked together are deleted from your local file system. When one file in a set of hardlinked files is migrated, all of the hardlinked files in the set become stub files. When the dsmmigundelete command recreates a stub file for a hardlinked file, the stub file has the same name as the file that was originally migrated. Stub files are not recreated for any other files that were previously in the hardlinked set of files.

Syntax

>>-dsmmigundelete--+---------+--+---------------------+--------><
                   '- option-'  | .-----------------. |
                                | V                 | |
                                '--- filesystemspec-+-'
 
 

Parameters

-Expiring or -e
Recreates a stub file for a migrated file if a corresponding stub file does not exist on your local file system, whether the migrated file was marked for expiration or not. Or, it creates a stub file for a premigrated file if a corresponding original file does not exist on your local file system, whether the premigrated file was marked for expiration or not.

Enter the dsmmigundelete command with the expiring option if you ran reconciliation since the files were deleted.

If you do not use the expiring option, the HSM client recreates a stub file for a migrated file if a corresponding stub file does not exist on your local file system and the migrated file was not marked for expiration. Or, it creates a stub file for a premigrated file if a corresponding original file does not exist on your local file system, and the premigrated file was not marked for expiration.

Enter the dsmmigundelete command without the expiring option if you did not run reconciliation since the files were deleted.

filesystemspec
The name of the file system for which you want to recreate deleted stub files and create stub files for premigrated files that were deleted from your local file system. The default is all file systems for which space management is active. You can specify more than one file system name. If you specify several file system names, separate each name with one or more blank spaces.

Examples

Task Command
Recreate stub files for migrated files that are marked for expiration which were accidentally deleted from the /home file system, and for files that are not marked for expiration. Reconciliation was run since the files were deleted. dsmmigundelete -expiring /home
Recreate stub files for migrated files in the /home file system that are not marked for expiration. Reconciliation was not run since the files were deleted. dsmmigundelete /home

dsmmode

Valid for AIX JFS environments only

The dsmmode command sets one or more of the following execution modes to modify the HSM-related behavior of specific commands:

The dsmmode command also displays the current execution modes that are in effect. If you precede another command and its arguments with the dsmmode command, only the execution mode or modes that you specify remain in effect for that command and any child processes of that command. Specify valid options with the dsmmode command for any command that follows to run. If you do not specify options, any command and its associated arguments that follow are ignored.

If you enter the dsmmode command without another command, it starts a new shell and the execution mode or modes that you specify remain in effect until you exit the shell. The shell that starts is the one that you specified as your default shell in /etc/passwd. You can nest dsmmode commands within the new shell.

Syntax

>>-dsmmode--+--------------+--+---------------------------+----><
            | .----------. |  '-command and its arguments-'
            | V          | |
            '--- options-+-'
 
 

Parameters

options
Use any combination of the following options. If you do not specify any options, the current execution modes in effect display.

-Dataaccess=value or -dvalue
Determines how a migrated file appears to the next command that you entered. The values that you can specify are:
Value Description
Normal or n A migrated file appears to be resident, and the command can access the file. This is the default.
Zero-length or z A migrated file appears to be a zero-length file.
Error or e Any attempt to access a migrated file returns an EIO error.
-Timestamp=value or -tvalue
Determines whether the access time (atime) for a file is set to the current time when you access the file. Only a root user can change this mode. The values that you can specify are:
Mode Description
Normal or n The access time is set to the current time when a file is accessed. This is the default.
Preserve or p The access time and inode change time (ctime) do not change when the file is read or its attributes are changed. You can specify this value to prevent access times from changing when backup programs other than the Tivoli Storage Manager backup-archive client program back up your files.
Note:
If you enter a command, such as the shell command cat, the file you are accessing is then mapped into memory. When a file is mapped, the access time will change even if you specify the preserve option.
-Outofspace=value or -ovalue
Determines how the HSM client responds to out-of-space errors that the kernel returns. The values that you can specify are:
Value Description
Normal or n The HSM client performs demand migration to avoid returning errors to the user if possible, and attempting to recover from out-of-space conditions. This is the default.
Error or e The HSM client does not intercept out-of-space errors.
-Recall=value or -rvalue
Determines how the HSM client recalls a migrated file when it is accessed. You can set a recall mode for a process to normal or migrate-on-close. The following list defines the order of precedence for recall modes if the recall mode that you set for a process is different from the recall mode that you set for a migrated file accessing the process:
  1. Migrate-on-close
  2. Normal

The values that you can specify are:

Value Description
Normal or n When a migrated file is accessed, it is copied to its originating file system. If the file is not modified, it becomes a premigrated file. If the file is modified, it becomes a resident file. Normal is the default recall mode for a process.
Migonclose or m When a migrated file is accessed, the HSM client temporarily copies it to your local file system. If the file is not modified, the file is returned to a migrated state by replacing the file with a stub file on your local file system when it is closed. If the file is modified, it remains on your local file system as a resident file.

Use the dsmattr command to set a recall mode for a migrated file to normal, migrate-on-close, or read-without-recall. See Table 13 for the recall modes that are used.

Attention: More than one process can access a file at a time. Another process can cause a file that you are accessing in migrate-on-close or read-without-recall mode to remain on your local file system as a resident or premigrated file. For example, if the recall mode that you set for a file is normal, and you access it with a process using the migrate-on-close recall mode and you do not modify the file, you would expect the file to be in a migrated state when you close it. But if someone else accesses the file at the same time with a process using normal recall mode or with a process that modifies the file in some way, the file remains on your local file system as either a resident or premigrated file, depending on the actions that the other process takes.

command
A command and any of its valid arguments for which you want the specified execution mode to remain in effect. If you do not specify a command, the HSM client starts a new shell. The shell that is started is the one that you specified as your default shell in/etc/passwd. The execution mode that you specify remains in effect until you exit the shell.

Examples

Task Command
Display the current execution modes. dsmmode
Change the data access mode for a grep command to ensure that only resident and premigrated files are searched, and migrated files are not accessed and recalled. dsmmode -Dataaccess=z grep \ spaceman *

dsmmonitord

You must have root user authority to use this command.

The dsmmonitord command starts the HSM space monitor daemon if it has stopped. If you enter this command and the space monitor daemon is running, action is not taken.

Syntax

>>-dsmmonitord-------------------------------------------------><
 
 

dsmq

You must have root user authority to use this command.

The dsmq command displays the following information about each recall process that is queued for processing:

If you set the maxrecalldaemons option in your dsm.sys file lower than the current number of requested recalls, some recall requests will not appear in the output for this command until recall daemons are available to perform the requests. To remove a recall process from the queue, use the dsmrm command.

Note:
If the Tivoli Storage Manager server is busy, or the connection between the HSM client and the Tivoli Storage Manager server is slow, the original name of the file might display as UNKNOWN in the output for this command. Enter dsmq again to view the file name.

If the recall daemon process ID (DPID) is zero, the recall is complete. You cannot remove the recall process from the queue.

Syntax

>>-dsmq--------------------------------------------------------><
 
 

Examples

Task Command
Display the status of recall processes. dsmq

dsmrecall

Attention: On large file systems, selective recall can take a long time.

The dsmrecall command selectively recalls migrated files to your local file system. Space management must be active.

If the file resides in a file system whose server stanza is different from that of the last processed file, a new session is started for each file that is recalled. This can happen as a result of links from one file system to another.

For AIX JFS file systems: When you selectively recall a file, you override the migrate-on-close or read-without-recall modes that you set for a migrated file. The file is recalled to its originating file system.

To display a list of all your migrated files, use the dsmmigquery command. To display information about a list of migrated files from a particular file system or directory, use the dsmls command.

Syntax

                                .---------------.
                                V               |
>>-dsmrecall--+--------------+------ filespec---+--------------><
              | .----------. |
              | V          | |
              '--- options-+-'
 
 

Parameters

Options

-Recursive or -r
Recalls files that match the file specification in a directory and its subdirectories. If you do not use this option, files are recalled only for those directories that you specify.
-Detail or -v
Displays the size, path, and file name for each file that you recall.
filespec
The path and file name of the file that you want to recall. This parameter is required. You can use wildcard characters to specify a group of files or all files in a directory, or you can enter more than one file specification in one command. When you use wildcard characters in a file specification, the HSM client attempts to recall all files that match the specification. If a file matches the specification but it is not migrated, an error message displays. If you enter more than one file specification, separate each specification with at least one blank space.

Examples

Task Command
Recall a single file named /migfs1/test/tf04 and display detailed information. dsmrecall -Detail /migfs1/test/tf04
Recall all migrated files in a directory named /mfs4/user1 and all migrated files in its subdirectories. dsmrecall -Recursive /mfs4/user1/*

dsmrecalld

You must have root user authority to use this command.

The dsmrecalld command starts a recall daemon if it is not running.

If the file resides in a file system whose server stanza is different from the last processed file, a new session is started for each file that is recalled. This can happen as a result of links from one file system to another.

Note:
If you enter this command while a recall daemon is running, no action is taken.

Syntax

>>-dsmrecalld--------------------------------------------------><
 
 

dsmreconcile

You must have root user authority to use this command.

The dsmreconcile command synchronizes the file systems on your client node with the Tivoli Storage Manager server that you contact for space management services. Use this command at any time to perform some or all of the reconciliation tasks for one or more file systems. Specify how often to perform automatic reconciliation with the reconcileinterval option in your dsm.sys file.

Note:
The dsmautomig and dsmreconcile processes must be found with the PATH variable, or the dsmmonitord daemon cannot perform reconcilation and threshold migration.

If the HSM client is processing a file system whose server stanza is different from that of the last processed file system, a new session is started for each file that is migrated.

The dsmreconcile command traverses your managed file systems during the following conditions:

Note:
When you upgrade from a previous version of HSM, the next time you run dsmreconcile on a previously managed file system, it will force a full file system tree traversal. This process to update the Tivoli Storage Manager client and server databases to the new format occurs only once for each previously-managed file system.

Syntax

>>-dsmreconcile--+--------------+--+---------------------+-----><
                 | .----------. |  | .-----------------. |
                 | V          | |  | V                 | |
                 '--- options-+-'  '--- filesystemspec-+-'
 
 

Parameters

-detail or -d
Prints progress messages while receiving the list of migrated files from the server.
-fileinfo or -f
Performs reconciliation tasks of the server and premigration databases. This is the default.
-orphancheck or -o
Note: This can take a while to process.

Forces a full file system tree traversal and includes orphan checking during the reconciliation process. The HSM client verifies that a valid copy exists in the spaceman pool of the Tivoli Storage Manager server. This option overrides a no value that you set for the checkfororphans option in your dsm.sys file. When orphans are located, their names are recorded in the .SpaceMan/orphan.stubs file. In this instance, the dsmautomig command cannot run concurrently with dsmreconcile.

If you want to check for orphans but you do not want to perform full file system tree traversals, specify no on the checkfororphans option in your dsm.sys file. You can then run dsmautomig concurrently with dsmreconcile.

filesystemspec
The name of the file system to reconcile. If you do not specify a file system name, the HSM client reconciles all file systems on your workstation for which space management is active. If you enter more than one file system name, separate each name with at least one blank space.

Examples

Task Command
Start reconciliation for all file systems for which space management is active. dsmreconcile
Start reconciliation for the /migfs1 file system. dsmreconcile /migfs1
Start reconciliation for file systems /home and /test1. dsmreconcile /home /test1

dsmrm

You must have root user authority to use this command.

The dsmrm command removes a recall process from the queue. To obtain the required recall ID to remove a recall process, use the dsmq command.

Note:
After a recall process starts, enter the dsmrm command to stop the process. Do not use Ctrl C to stop a recall process.

Syntax

          .---------------.
          V               |
>>-dsmrm------ recallid---+------------------------------------><
 
 

Parameters

recallid
The recall process ID that you want to remove from the queue.

Examples

Task Command
Remove recall ID 10 from the queue. dsmrm 10
Remove recall ID 5 and recall ID 6 from the queue. dsmrm 5 6

dsmrootd

You must have root user authority to use this command.

The dsmrootd command starts a root daemon if it is not running. The root daemon provides non-root user support for HSM.

The following commands can be run as non-root:

Note:
If you enter this command while a root daemon is running, no action is taken.

Syntax

>>-dsmrootd----------------------------------------------------><
 
 

dsmscoutd

You must have root user authority to use this command.

The dsmscoutd command starts the scout daemon if it has stopped. If you enter this command while a scout daemon is running, no action is taken.

Syntax

>>-dsmscoutd---------------------------------------------------><
 
 

dsmsetpw

You must have root user authority to use this command.

The dsmsetpw command changes the Tivoli Storage Manager password for your client node. To keep your password secure, enter the dsmsetpw command without your old password and new password. The system prompts you for each one. When you are prompted to enter your old and new passwords, you eliminate the possibility that another user can display your password.

If you did not register your client node with the Tivoli Storage Manager server that you contact for services, and open registration is in effect, the Tivoli Storage Manager client prompts you for registration information.

Syntax

>>-dsmsetpw--+--------------------------+----------------------><
             '- oldpassword newpassword-'
 
 

Parameters

oldpassword
The current Tivoli Storage Manager password for your client node.
newpassword
The new Tivoli Storage Manager password to set for your client node.

Examples

Task Command
Change your current Tivoli Storage Manager password from osecret to nsecret. dsmsetpw osecret nsecret

dsmwatchd

Valid on AIX GPFS and Linux86 GPFS file systems only. You must have root user authority to use this command.

Note:
Do not use this command from the console. During installation, it is added to /etc/inittab. The dsmwatchd command requires a living PSSP cluster, AIX cluster Group Services, or IBM Cluster 1350 cluster and read/write access to shared HSM files within the SDR on a PSSP or IBM Cluster 1350 cluster system.

The dsmwatchd command manages failover activities for your local node. If failover is active on your local node, it checks the status of the dsmrecalld command, the dsmmonitord command, and the dsmscoutd command. If any of these daemons end, or becomes corrupted, dsmwatchd automatically recovers the failed daemon.

If two or more nodes within a GPFS node set participate actively in a failover environment, the dsmwatchd command either will take over the filesystems of a failed HSM node actively (remote is the same as within the local nodeset), or start the failover if the HSM client no longer can perform its operations locally. A node crash also can start failover. Unmounting a managed filesystem will not result in a failover. The failover environment is active by default. Use dsmmigfs enableFailover or dsmmigfs disableFailover to change the status.

In an active environment, the dsm.opt and dsm.sys files are shared between all nodes to guarantee that all nodes access the same Tivoli Storage Manager server. Even with a disabled failover environment, there is some communication between the different dsmwatchd commands to ensure that a GPFS filesystem is managed at least once. The dsm.opt and dsm.sys files can be different in this instance. Nodes with a different configuration no longer can participate in the failover environment. Starting failover will result in a configuration synchronization. The local dsm.opt and dsm.sys files are replaced with the corresponding SDR versions that are valid for failover. The dsmwatchd writes error messages to the /dsmerror.log. If you want dsmwatchd to use another dsmerror.log file, set the environment variable, DSM_LOG in /etc/environment accordingly. For example:

    DSM_LOG=/usr/tivoli/tsm/client/hsm/bin/dsmerror.log  

Attention: The synchronization operations within the failover group creates backup copies with a timestamp of the configuration files. These copies are stored in the backup directory located in the DSM_DIR path and in /etc/adsm/SpaceMan/config.

Syntax

>>-dsmwatchd-- import------------------------------------------><
 
 

Parameters

import
Automatically starts the following daemons on the takeover node if these daemons are not currently running: dsmrecalld, dsmmonitord, dsmscoutd.


[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]