Recalling

Transparent Recall

With Ngenea HSM Transparent Recall, files are recalled from external storage when opened for reading or writing by any application.

See Transparent Recall file system policy for details of the required policy configuration.

Policy Based Recall

Files may be recalled programmatically using a Spectrum Scale/GPFS policy. A policy will select candidates for recall based on specified criteria, and then call ngrecall in the execution phase to recall files from external storage.

Example Recall Policy

This example policy will recall all offline files in the /mmfs1/policytest/ folder tree.

/* Set the default filesystem storage pool */
define(targetpool,'sas1')

RULE EXTERNAL POOL 'NGENEA_DEFAULT'
    EXEC '/var/mmfs/etc/mmpolicyExec-ngenea-hsm'
    OPTS '-v1'

RULE 'ngenea_recall' MIGRATE FROM POOL 'NGENEA_DEFAULT' TO POOL targetpool

/* Select offline files only */
WHERE XATTR('dmapi.APXguuid') IS NOT NULL AND CountSubstr(MISC_ATTRIBUTES,'V')>0

/* Recall files in the policytest folder */
AND PATH_NAME LIKE '/mmfs1/policytest/%'

A more comprehensive example can be found here.

ngrecall

Synopsis

ngrecall [-vLEVEL] [--no-delete-remote] FILE1 ... FILEn
ngrecall [-vLEVEL] --delete-remote
        [--skip-check-uuid] [--skip-check-hash] FILE1 ... FILEn
ngrecall [-vLEVEL] --delete-remote --force FILE1 ... FILEn
ngrecall [-vLEVEL] --delete-remote -L REMOTE_LOC
ngrecall [-vLEVEL] --premigrate [--overwrite|force]
        [--default-mode=MODE] [--default-uid=USER]
        [--default-gid=GROUP] FILENAME1 ... FILENAMEn
ngrecall [-vLEVEL] --premigrate [--overwrite|force]
        [--default-mode=MODE] [--default-uid=USER]
        [--default-gid=GROUP] -L REMOTE_LOC
ngrecall [-vLEVEL] --stub [--overwrite|force]
        [--default-stub-size=LENGTH|--force-stub-size=LENGTH]
        [--default-mode=MODE] [--default-uid=USER]
        [--default-gid=GROUP] FILENAME1 ... FILENAMEn
ngrecall [-vLEVEL] --stub [--overwrite|force]
        [--default-stub-size=LENGTH|--force-stub-size=LENGTH]
        [--default-mode=MODE] [--default-uid=USER]
        [--default-gid=GROUP] -L REMOTE_LOC
ngrecall [-v2|3] [--config-file=FILE] [--log-target=syslog]
        :FSID:INO:IGEN
where:
    FILEi = FILENAME | :FSID:INO:IGEN

Common options for all use cases:
    [--config-file=FILE] [-E PATTERN1] [--endpoint-exclude=PATTERN2]

Description

Recalls files from a Storage Target to the local GPFS file system.

Options

--config-file=FILE
                path to a configuration file to use.
                Default: /opt/arcapix/etc/ngenea.conf
--default-mode=MODE
                file mode bits (in octal format) to set for a
                stubbed/premigrated file if there are no file mode bits
                associated with a remote object.
                Default: apply umask in the usual way to file mode 666.
                Compatible with the options: -p, --premigrate; --stub
--default-uid=USER
                file owner (a numeric user ID or a non-numeric user name) to
                set for a stubbed/premigrated file if there is no file owner
                associated with a remote object.
                Default: use the effective user ID as a file owner.
                Compatible with the options: -p, --premigrate; --stub
--default-gid=GROUP
                file group (a numeric group ID or a non-numeric group name) to
                set for a stubbed/premigrated file if there is no file group
                associated with a remote object.
                Default: use the effective group ID as a file group.
                Compatible with the options: -p, --premigrate; --stub
--default-stub-size=LENGTH
                default approximate length of a file stub. This setting can be
                overridden in a configuration file.
                Default: 0 (do not retrieve file content).
                Compatible with the option: --stub
--delete-remote delete each successfully recalled remote object from a storage
                endpoint where the object was stored (for storage endpoints
                supporting object deletion).
                See below for a description (Deleting From Multiple Storage Endpoints).
--no-delete-remote
                do not delete recalled remote objects from storage endpoints
                where they were stored.
--skip-check-hash
                This option disables the check for the equality of SHA-512 hashes
                of an online local file and a remote object performed before
                deleting the remote object for the local file.
                See description below.
--skip-check-uuid
                This option disables the check for the equality of UUIDs of an online
                local file and a remote object performed before deleting the remote
                object for the local file.
                See description below.
--force
                In reverse stubbing and reverse premigration modes, this option
                implicitly activates the option --overwrite to overwrite local
                files if they exist.
                In other modes, a user should specify the option --force along
                with the option --delete-remote.
                In this case, the option --force does the following:
                    1. Makes it possible to delete a remote object for a
                       locally non-existent file.
                    2. Implicitly activates the option --skip-check-hash.
                    3. Implicitly activates the option --skip-check-uuid.
                    4. For an online local file, disables the check that the
                       file is still online after locking it.
--force-stub-size=LENGTH
                forcibly set file stub size.
                Default: do not forcibly set the stub size.
                Compatible with the option: --stub
-E, --endpoint=PATTERN
                restrict the set of endpoints to include those endpoints which
                match the extended glob pattern.
--endpoint-exclude=PATTERN
                restrict the set of endpoints to exclude those endpoints which
                match the extended glob pattern.
--help          display this help and exit.
--log-target=syslog
                redirect all logging to the syslog.
--overwrite     overwrite local files if they already exist.
                Default: if a local file already exists, then report an error
                         and do not overwrite the local file.
                Compatible with the options: -p, --premigrate; --stub
-p, --premigrate
                retrieve content of local files and make them reference
                locations at storage endpoints where those files were stored
                (i.e. make each file premigrated just after retrieving its
                content).
                       Implies the option: --no-delete-remote
                Conflicts with the option: --stub
-L, --remote-loc-xattr=REMOTE_LOC
                location of a remote object to premigrate or create a local stub
                file.
                Compatible with the options: -p, --premigrate; --stub
--stub          create local stub files.
                       Implies the option: --no-delete-remote
                Conflicts with the option: -p, --premigrate
-v, --verbose[=LEVEL]
                verbosity level:
                0 = standard messages (also used when this option is absent);
                1 = additional informational and warning messages (default);
                2 = debug messages;
                3 = enable core dump and messages related to file locking;
                    print PID and current time with microsecond precision.
-V, --version   display version information and exit.

Matching Storage Endpoints

The options --endpoint / --endpoint-exclude are used to include / exclude some endpoints. See description of this option in Matching Storage Endpoints (ngmigrate).

Deleting From Multiple Storage Endpoints

The --delete-remote option will also operate against multiple Storage Targets, if multiple targets are defined in the configuration file.

If a file specified on the command line is offline, then delete remote objects corresponding to the file on its successful recall. The program ngrecall deletes the remote object from a storage endpoint ngrecall successfully recalled the file from and deletes remote objects specified by other remote location xattrs of that file if they exist (matching storage endpoints described in a master configuration file are subject to filtering by the options --endpoint=PATTERN and --endpoint-exclude=PATTERN).

If a file specified on the command line is online or the file does not exist locally, then delete remote objects corresponding to the local file without deleting the file itself. Deleting remote objects for a locally non-existent file requires specifying the option --force.

If a local file is online and does not have any remote location xattrs (a file can be online and have remote location xattrs if it is in the "premigrated" state), or the local file does not exist, then ngrecall determines remote objects for the local file by matching storage endpoints described in a master configuration file (subject to filtering by the options --endpoint=PATTERN and --endpoint-exclude=PATTERN) against the resolved absolute name of that local file if it exists or against such supposed name if the file does not exist. In this case, ngrecall will not delete remote objects with UUIDs appended to their names.

The program ngrecall removes from a local file remote location xattrs specifying successfully deleted remote objects. If deletion of remote objects succeeded, and it turns out that the local file does not have any remote location xattrs, then ngrecall removes all Ngenea-specific xattrs from the local file.

If a remote object does not fully correspond to a local file, then to disable two particular checks to make it possible to delete the remote object, a user can pass the options --skip-check-hash and --skip-check-uuid to ngrecall. These two options are implicitly active if a user specifies the option --force.

The effect of the option --delete-remote is negated by the option --no-delete-remote. The latter option has a higher priority.

Option --skip-check-hash

This option disables the check for the equality of SHA-512 hashes of an online local file and a remote object performed before deleting the remote object for the local file.

Currently, ngrecall does not support disabling a similar safety check performed when recalling offline files or deleting remote objects for them.

In more detail, this option does the following:

  1. Disables reading the object size xattr of the local file.
  2. Disables checking the equality of object size specified in that xattr and the actual size of the local file.
  3. Disables obtaining the size of the remote object.
  4. Disables checking the equality of the obtained size of the remote object and the actual size of the local file.
  5. Disables computing the SHA-512 hash of the local file.
  6. Disables reading the SHA-512 hash xattr of the local file.
  7. Disables checking the equality of a SHA-512 hash specified in that xattr and the computed hash of the local file.
  8. Disables reading the SHA-512 hash of the remote object from its metadata.
  9. Disables checking the equality of a SHA-512 hash obtained from the metadata and the computed hash of the local file.

Option --skip-check-uuid

This option disables the check for the equality of UUIDs of an online local file and a remote object performed before deleting the remote object for the local file.

Currently, ngrecall does not support disabling a similar safety check performed when recalling offline files or deleting remote objects for them.

In more detail, this option does the following:

  1. Disables reading the UUID xattr of the local file.
  2. Disables reading the UUID of the remote object from its metadata.
  3. Disables checking the equality of a UUID specified in the xattr and a UUID obtained from the metadata.

Examples

To recall a file from the associated Storage Target:

ngrecall /mmfs1/data/file1 /mmfs1/data/file2

To recall all files starting with name file from the associated Storage Target:

ngrecall /mmfs1/data/file*

To recall all files starting with name file and name newfile from the associated Storage Target:

ngrecall /mmfs1/data/file* /mmfs1/data/newfile*

To recall all files, except hidden ("dot") files, within a directory from the associated Storage Target:

ngrecall /mmfs1/data/*

To recall all files, including hidden ("dot") files, within a directory from the associated Storage Target:

ngrecall /mmfs1/data/{.??,}*

To recall all files, except hidden ("dot") files, within two different directories from their associated Storage Target(s):

ngrecall /mmfs1/data/dir1/* /mmfs1/data/dir2/*

To recall all files in a directory (except hidden "dot" files) from a storage target, temporarily replacing the default config with a custom storage target:

ngrecall --config-file=/path/to/custom.conf /mmfs1/data/delivery/*

See Also