GXHSMUtility

The GXHSMUtility is used to copy or move stub files without triggering file recall(s). The tool is also used to validate recalled files or stub files, create index cache, interfaces with Celerra to assist in setting and configuring both the filer and the agent computer. It also allows to set additional properties options and additional options for subclients and clients that are not available through the CommCell Console.

Usage

GXHSMUtility [-m] <file_src> <file_dest> [-filter <str>]

GXHSMUtility -vr [-z] [-a] <path_to_validate> [-filter <str>]

GXHSMUtility.exe [-m] [-r] –UseStubCopyEx <file_src> <file_dest>

Command Line Options:

-stubonly	Only copy stub files
-m	Move stubbed files instead of copying
-vs	Validate stub files exist in the archive for browser restore
-vr	Validate recalled stub files for correct attribute settings
-z	Check zero filled contents during validation
-a	When used with vr option, displays stub attributes
-strip	When used with V option, strips reparse and offline attributes
-fix	Fix stub attribute and compress size
-view	View stub file reparse data
-restub	Restub files
-UseStubCopyEx	Enhance scanning during copy/move operation	Option available for move/copy from: Local File System to Fpolicy Local File System to Local File System Does not support: Hardlink files Encrypted files and stubs
-r	Copy/move stubs recursively	Option available for move/copy from: Local File System to Fpolicy Local File System to Local File System Does not support: Hardlink files Encrypted files and stubs

The GXHSMUtility tool can be used for the following also:

Stubcopying

Location

The GXHSMUtility tool, available in the Base folder of the File Archiver for Windows install directory, must be run on the machine where File Archiver is installed.

Besides copying of stubs on the same platform the following cross instance platform stub copying are supported. However, Celerra is an exception, which does not support same platform or cross instance platform stub copying.

Copy from Local File System to Celerra
Copy from Local File System to Network File Share
Copy from Network File Share to Local File System
Copy from Local File System to Fpolicy
Copy from Fpolicy to Local File System
Copy from a lower Calypso version to a higher version if the two client computers are on the same CommCell.
Copy from Fpolicy to other file servers
Copy from Network File Share to other file servers

Considerations

When copying or moving stubs, UNC paths must be provided for NAS locations (Network File Share, Celerra, Fpolicy), and drive paths must be provided for Local stubs. Also, UNC paths must use the same naming convention used in the instance properties for the filer name; i.e., if the filer property is set with FQDN (Fully Qualified Domain Name), the UNC path given to the tool must use FQDN. The logon user calling the tool must have administrative privileges for both local machine and the filer.
The Access Control List's (ACL) preservation is supported for copy from Local to any NAS type. It is not guaranteed if the source is DMNAS or Celerra. No ACL support is provided for Fpolicy to local copy.

Celerra filer is a new required field in 9.0 Celerra instance properties. After upgrading the File Archiver to 9.0, you must manually populate this field before using GXHSMUtility tool.

Validation

How to use GXHSMUtility for validation

GXHSMUtility is also used to validate recalled files or stub files by using the -vr command line option. This option is only supported for stubs created by archiving subclients of Local File System Instance. Stubs created by archiving Network File Share Instance are not supported under this option.

The validation logic checks files in a given path for the correct combination of file attributes. Recalled files should not have any of the following 3 stub file attributes:

Off-Line
Reparse-Point
Sparse

Files that have been migrated, and turned into stub files, should have off-line, reparse, and sparse set. The validation logic will display any file that is found to have only one or two of the stub attributes. Incorrect file attributes are set when an AntiVirus program interferes with or triggers a recall. Quota management drivers and other file filter drivers can also interrupt the normal recall process.
The (-a) option, displays the three attribute settings for files found with incorrect attributes.
The (-z) option, limits the result to display files with incorrect stub attributes, and files containing zeros only.

Usage

Example:

GXHSMUtility.exe -vr G:\foo\

GXHSMUtility.exe -vr -z G:\foo\

GXHSMUtility.exe -vr -z -a G:\foo\

GXHSMUtility.exe -vr -a G:\foo\

GXHSMUtility.exe -vr G:\foo\ -filter *.txt

Celerra

How to set additional Celerra options

GXHSMUtility has an additional option to interface with Celerra DART 5.5 and 5.6. filer; using the XML interface. The main purpose of this options is to assist in setting and configuring both the filer and the agent computer. Since these options are mainly used for troubleshooting purposes, debug logging is always turned on when they're used.

Celerra Command Line Options:

-cel_cs	Configure filer through Celerra control station
-CelSetUsr	Set Celerra Control station user name and password
-xchk	Check if Celerra file is offline
-xstub	Stub a Celerra file
-xdirect	Direct command sent to Celerra via xml interface

GXHSMUtility.exe -xdirect [filer-ipaddr] -c ['command'] -u [user] -pw [passwrd]
GXHSMUtility.exe -xdirect [filer-ipaddr] -f ['CmdFile'] -u [user] -pw [passwrd]

Usage

Example:
GXHSMUtility -cel_cs celerraCntrlStatn usrname CelrFilerShr FsdmShare

GXHSMUtility -cel_cs celerra_cs nasadmin \\celerra_dm2\fs1 \\fsdm\celerra_proxyFsdmAgentUserId

GXHSMUtility -CelSetUsr celerra_cs nasadmin

GXHSMUtility -xchk \\filer\share\folder\file.txt

GXHSMUtility -xchkdir \\filer\share\folder\

GXHSMUtility -xstub \\flr\shr\flr\fl.txt PrxyStbFldr PrxyHttpPath

GXHSMUtility -xstub \\flr\shr\flr\fl.txt -proxy c:\proxy\f1.txt

GXHSMUtility -xGetControlStationIPAddr 172.19.69.44

GXHSMUtility -xconnect 172.19.69.44 -FileSystemNameWhereShareResides fs1

GXHSMUtility -xdirect 172.19.69.44 -c '<DHSM_GET_ATTRS PATH="nfs:/fs6/myfolder/myfile.txt" />' -u root -pw password

Subclient Options

How to set additional subclient options

GXHSMUtility can be used to set additional options on subclients. These options cannot be set from the CommCell Console from the subclient properties dialog box.
To use this feature, all subclient names must be unique, otherwise these properties will be set for multiple subclients. If the subclient name is not given on command line, then setting is applies to all subclients.

An [x] indicates the default subclient setting

Subclient Command Line Options:

ModCreate [x]	Maintain file modification and creation time on migration
AccessTimeM [x]	Maintain file access time on migration [requires ModCreate]
AccTimeMOff	Disables access time preservation during migration
AccessTimeR [x]	Maintain file access time on recall [requires ModCreate]
AccTimeROff	Disables access time preservation during recall
KeepTimeOff	Disables ALL time preservation during migration
SparseOn [?]	Enable sparse; Enabled by default for local; For fpolicy, this option is only supported on OnTap 7.3 & higher, and it's enabled by default for supported versions
SparseOff	Disable sparse
RestubOn [x]	Enables restub logic on migration per subclient
RestubOff	Disables restub logic on migration per subclient. Client level RestubOff needs to be used with subclient level restub options. The client level restub option is used in the recall phase, and applies to all sub-clients.
IgnreSparse	Ignore sparse attribute when migrating files; This is commonly used for fpolicy.
IgnrSprsOff [x]	Turn off IgnreSparse option
DontStubOn	Do not stub file in stub phase, and do not delete; Only archive
nDontStubOff [x]	Turn off DontStubOn option
NasSparse	When recalling NAS files, remove sparse
NasSprsOff [x]	Turn off NasSparse option
DisableAcls	Disables restoring ACLs during recall
EnableAcls [x]	Turn off DisableAcls option
StageRecall	Enable recalls to use staging folder (gxhsmcache)
StageOff [x]	Disables StageRecall
RmtErrMsg	Remote error message handling on. When this is set, a popup message is sent to remote users when recall error occurs
RmtErrMsgOf [x]	Disables RmtErrMsg

Usage

Example:
GXHSMUtility -ExtOption SysHid MySubClientName

GXHSMUtility -ExtOption SysHid "My Sub Client Name"

GXHSMUtility -ExtOption SysHidOff MySubClientName

GXHSMUtility -ExtOption ModCreate MySubClientName

Client Options

How to set additional client options

GXHSMUtility can be use to set additional client options. These options cannot be set from the CommCell Console from the property settings.

An [x] indicates the default setting

Client Command Line Options:

RestubOn [x]	Enables restub logic in the recall phase
RestubOff	Disables restub logic in the recall phase
OffLineAtOn [x]	Enable setting offline attribute for NAS sub clients
OffLineAOff	Disable setting offline attribute for NAS sub clients
CheckAlwaysOn	Enable recall logic to ALWAYS check sub client recall property
CheckAlwaysOff [x]	Disable recall logic to check sub client recall property

Usage

Example:

GXHSMUtility -ExtClientOption RestubOn

GXHSMUtility -ExtClientOption RestubOff

Set Properties

How to set additional properties

GXHSMUtility can be use to set additional property options. These options are not available from the CommCell Console.

GXHSMUtility -SetExtPropStr instance InstanceName ProName ProValue

GXHSMUtility -GetExtPropStr instance InstanceName ProName

GXHSMUtility -SetExtPropNum instance InstanceName ProName ProValue

GXHSMUtility -GetExtPropNum instance InstanceName ProName

Commands:

SetExtPropStr
GetExtPropStr
SetExtPropNum
GetExtPropNum

These commands must be followed by one of the following:

client
iDataAgent
Instance
Backupset
Subclient

The above value should correspond to the property level that is being set, and should follow the actual name of the property type.
For iDataAgent, only 'File Archiver' is supported by name. All other iDataAgent's need to have ID value. Incase the name is not unique, ID should be
used instead.

Usage

Example usage:
GXHSMUtility -SetExtPropStr ida idaName ProName ProValue
GXHSMUtility -GetExtPropNum ida idaName ProName
GXHSMUtility -SetExtPropNum instance InstanceName ProName ProValue
GXHSMUtility -GetExtPropStr instance InstanceName ProName
GXHSMUtility -SetExtPropStr subclient SC_Name ProName ProValue
GXHSMUtility -GetExtPropNum subclient SC_Name ProName

In above examples, ProName is the property name, and ProValue is the new value of the property.

Discover Bad/Invalid Stubs

GXHSMUtility can be use to find bad or invalid stubs in data files. These options are not available from the CommCell Console.

Options:

-CheckForZeroDataStream	Identify 0 data stream files (no reparse data and no offline)
-ListAllBadStubs	List all bad and invalid stubs

Usage

GXHSMUtility -R [-CheckForZeroDataStream] -ListAllBadStubs <folder-to-be-scanned> <bad-stub-list> <invalid-stub-list>

Example:

GXHSMUtility -R -ListAllBadStubs "C:\pd_dst" "C:\metrotest\badstublist.txt" "C:\metrotest\invalidstublist.txt"

GXHSMUtility -R -CheckForZeroDataStream -ListAllBadStubs "C:\pd_dst" "C:\metrotest\badstublist.txt" "C:\metrotest\invalidstublist.txt"