Recalling¶
Transparent Recall¶
With Ngenea 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 PixStor 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 --log-target=syslog'
ESCAPE '%'
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 [-r] [--no-delete-remote] [--ignore-rmtlc]
[--skip-check-hash] [--skip-check-uuid]
[--update-atime] [--update-mtime]
DMNAME1 ... DMNAMEn
ngrecall [-r] [--no-delete-remote] [--ignore-rmtlc]
[--skip-check-hash] [--skip-check-uuid]
[--update-atime] [--update-mtime]
[--filelist-format=NUL|quoted] -f FILELIST
ngrecall [-r] --delete-remote [--ignore-rmtlc] [--skip-check-hash]
[--skip-check-uuid] [--update-atime] [--update-mtime]
DMNAME1 ... DMNAMEn
ngrecall [-r] --delete-remote [--ignore-rmtlc] [--skip-check-hash]
[--skip-check-uuid] [--update-atime] [--update-mtime]
[--filelist-format=NUL|quoted] -f FILELIST
ngrecall [-r] --delete-remote --force [--ignore-rmtlc]
[--update-atime] [--update-mtime]
DMNAME1 ... DMNAMEn
ngrecall [-r] --delete-remote --force [--ignore-rmtlc]
[--update-atime] [--update-mtime]
[--filelist-format=NUL|quoted] -f FILELIST
ngrecall --delete-remote -L REMOTE_LOC
ngrecall [-r] -p [--overwrite-local|force] [--all-obj-instances]
[--skip-check-uuid] [--update-atime] [--update-mtime]
[--ignore-metadata] [--default-mode-file=MODE]
[--default-mode-dir=MODE] [--default-uid=USER]
[--default-gid=GROUP] [--path-local=PATH]
[--no-restore-acl] NAME1 ... NAMEn
ngrecall [-r] -p --restore-symlink-targets [--overwrite-local|force]
[--all-obj-instances] [--skip-check-uuid]
[--update-atime] [--update-mtime] [--ignore-metadata]
[--default-mode-file=MODE] [--default-mode-dir=MODE]
[--default-uid=USER] [--default-gid=GROUP]
[--no-restore-acl] NAME1 ... NAMEn
ngrecall [-r] -p [--overwrite-local|force] [--all-obj-instances]
[--skip-check-uuid] [--update-atime] [--update-mtime]
[--ignore-metadata] [--default-mode-file=MODE]
[--default-mode-dir=MODE] [--default-uid=USER]
[--default-gid=GROUP] [--path-local=PATH]
[--no-restore-acl] [--filelist-format=NUL|quoted] -f FILELIST
ngrecall [-r] -p --restore-symlink-targets [--overwrite-local|force]
[--all-obj-instances] [--skip-check-uuid]
[--update-atime] [--update-mtime] [--ignore-metadata]
[--default-mode-file=MODE] [--default-mode-dir=MODE]
[--default-uid=USER] [--default-gid=GROUP]
[--no-restore-acl] [--filelist-format=NUL|quoted] -f FILELIST
ngrecall -p [--overwrite-local|force] [--update-atime] [--update-mtime]
[--ignore-metadata] [--default-mode-file=MODE]
[--default-mode-dir=MODE] [--default-uid=USER]
[--default-gid=GROUP] [--path-local=PATH]
[--no-restore-acl] -L REMOTE_LOC
ngrecall -p [--overwrite-local|force] [--all-obj-instances]
[--skip-check-uuid] [--update-atime] [--update-mtime]
[--ignore-metadata] [--default-mode-file=MODE]
[--default-mode-dir=MODE] [--default-uid=USER]
[--default-gid=GROUP] [--path-local=PATH]
[--no-restore-acl] -E ALIASES[:PATHS]
ngrecall [-r] --stub [--overwrite-local|force] [--all-obj-instances]
[--skip-check-uuid] [--update-atime] [--update-mtime]
[--default-stub-size=LENGTH|--force-stub-size=LENGTH]
[--ignore-metadata] [--default-mode-file=MODE]
[--default-mode-dir=MODE] [--default-uid=USER]
[--default-gid=GROUP] [--path-local=PATH]
[--no-restore-acl] NAME1 ... NAMEn
ngrecall [-r] --stub --restore-symlink-targets
[--overwrite-local|force] [--all-obj-instances]
[--skip-check-uuid] [--update-atime] [--update-mtime]
[--default-stub-size=LENGTH|--force-stub-size=LENGTH]
[--ignore-metadata] [--default-mode-file=MODE]
[--default-mode-dir=MODE] [--default-uid=USER]
[--default-gid=GROUP]
[--no-restore-acl] NAME1 ... NAMEn
ngrecall [-r] --stub [--overwrite-local|force] [--all-obj-instances]
[--skip-check-uuid] [--update-atime] [--update-mtime]
[--default-stub-size=LENGTH|--force-stub-size=LENGTH]
[--ignore-metadata] [--default-mode-file=MODE]
[--default-mode-dir=MODE] [--default-uid=USER]
[--default-gid=GROUP] [--path-local=PATH]
[--no-restore-acl] [--filelist-format=NUL|quoted] -f FILELIST
ngrecall [-r] --stub --restore-symlink-targets
[--overwrite-local|force] [--all-obj-instances]
[--skip-check-uuid] [--update-atime] [--update-mtime]
[--default-stub-size=LENGTH|--force-stub-size=LENGTH]
[--ignore-metadata] [--default-mode-file=MODE]
[--default-mode-dir=MODE] [--default-uid=USER]
[--default-gid=GROUP]
[--no-restore-acl] [--filelist-format=NUL|quoted] -f FILELIST
ngrecall --stub [--overwrite-local|force]
[--update-atime] [--update-mtime]
[--default-stub-size=LENGTH|--force-stub-size=LENGTH]
[--ignore-metadata] [--default-mode-file=MODE]
[--default-mode-dir=MODE] [--default-uid=USER]
[--default-gid=GROUP] [--path-local=PATH]
[--no-restore-acl] -L REMOTE_LOC
ngrecall --stub [--overwrite-local|force] [--all-obj-instances]
[--skip-check-uuid] [--update-atime] [--update-mtime]
[--default-stub-size=LENGTH|--force-stub-size=LENGTH]
[--ignore-metadata] [--default-mode-file=MODE]
[--default-mode-dir=MODE] [--default-uid=USER]
[--default-gid=GROUP] [--path-local=PATH]
[--no-restore-acl] -E ALIASES[:PATHS]
ngrecall --sync-metadata [--all-obj-instances] [--skip-check-uuid]
[--default-mode-file=MODE] [--default-mode-dir=MODE]
[--default-uid=USER] [--default-gid=GROUP]
[--path-local=PATH]
[--no-restore-acl] NAME1 ... NAMEn
ngrecall --sync-metadata [--all-obj-instances] [--skip-check-uuid]
[--default-mode-file=MODE] [--default-mode-dir=MODE]
[--default-uid=USER] [--default-gid=GROUP]
[--path-local=PATH]
[--no-restore-acl] [--filelist-format=NUL|quoted] -f FILELIST
ngrecall --sync-metadata [--all-obj-instances]
[--default-mode-file=MODE] [--default-mode-dir=MODE]
[--default-uid=USER] [--default-gid=GROUP]
[--path-local=PATH]
[--no-restore-acl] -L REMOTE_LOC
ngrecall --sync-metadata [--all-obj-instances]
[--default-mode-file=MODE] [--default-mode-dir=MODE]
[--default-uid=USER] [--default-gid=GROUP]
[--path-local=PATH]
[--no-restore-acl] -E ALIASES[:PATHS]
ngrecall --fetch [--all-obj-instances] [--remote-offset-start=OFFSET]
[--remote-offset-end=OFFSET] [--keep-content]
[--ignore-metadata] [--default-mode-file=MODE]
[--default-mode-dir=MODE] [--default-uid=USER]
[--default-gid=GROUP] [--path-local=PATH]
[--no-restore-acl] NAME1 ... NAMEn
ngrecall --fetch [--all-obj-instances] [--remote-offset-start=OFFSET]
[--remote-offset-end=OFFSET] [--keep-content]
[--ignore-metadata] [--default-mode-file=MODE]
[--default-mode-dir=MODE] [--default-uid=USER]
[--default-gid=GROUP] [--path-local=PATH]
[--no-restore-acl] [--filelist-format=NUL|quoted] -f FILELIST
ngrecall --fetch [--all-obj-instances] [--remote-offset-start=OFFSET]
[--remote-offset-end=OFFSET] [--keep-content]
[--ignore-metadata] [--default-mode-file=MODE]
[--default-mode-dir=MODE] [--default-uid=USER]
[--default-gid=GROUP] [--path-local=PATH]
[--no-restore-acl] -L REMOTE_LOC
ngrecall --fetch [--all-obj-instances] [--remote-offset-start=OFFSET]
[--remote-offset-end=OFFSET] [--keep-content]
[--ignore-metadata] [--default-mode-file=MODE]
[--default-mode-dir=MODE] [--default-uid=USER]
[--default-gid=GROUP] [--path-local=PATH]
[--no-restore-acl] -E ALIASES[:PATHS]
ngrecall :FSID:INO:IGEN
where:
DMNAMEi =file name| :FSID:INO:IGEN
NAMEi= file, directory, or symbolic link name
Common options for all use cases:
[-vLEVEL] [--config-file=FILE] [--no-recursion-remote]
[ --log-target=syslog | --log-format=json ]
[ --lock-level=partial | [--lock-level=implicit] [--no-flock] ]
( -E RESTRICTION_ALIASES[:RESTRICTION_PATHS] |
--endpoint-exclude=EXCLUSION_ALIASES[:EXCLUSION_PATHS] )*
( -P ALIASES:PARAMETER=VALUE )*
Description¶
Recalls files from a Storage Target to the local GPFS file system.
Options¶
--all-obj-instances
process all object instances.
Default: find and process only latest object instances.
Compatible with: -p, --premigrate; --stub; --sync-metadata.
Conflicts with: -L, --remote-loc-xattr.
--config-file=FILE
path to a master configuration file.
Default: /opt/arcapix/etc/ngenea.conf
--default-mode=MODE
--default-mode-file=MODE
mode bits (in octal format) to set for reversely
stubbed/premigrated files if there are no mode bits
associated with remote objects.
Default: apply umask in the usual way to mode 666.
Compatible with: -p, --premigrate; --stub; --sync-metadata.
--default-mode-dir=MODE
mode bits (in octal format) to set for directories created
locally if there are no mode bits associated with
remote folders.
Default: apply umask in the usual way to mode 777.
Compatible with: -p, --premigrate; --stub; --sync-metadata.
--default-uid=USER
file owner (in NUMBER, STRING, /NUMBER, STRING/, or
STRING/NUMBER format) 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: -p, --premigrate; --stub; --sync-metadata.
--default-gid=GROUP
file group (in NUMBER, STRING, /NUMBER, STRING/, or
STRING/NUMBER format) 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: -p, --premigrate; --stub; --sync-metadata.
--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: --stub.
--delete-remote delete each successfully recalled remote object from a storage
endpoint where the object was stored or delete a remote object
corresponding to a local file (for storage endpoints
supporting object deletion).
-E, --endpoint=ALIASES[:PATHS]
restrict the set of storage endpoints for interaction to
endpoints with aliases specified by extended glob
pattern ALIASES.
Optionally, restrict remote object pathnames at those endpoints
to pathnames matching extended glob pattern PATHS.
By default, restrict remote object pathnames to the root path.
Compatible with: --no-recursion-remote.
--endpoint-exclude=ALIASES[:PATHS]
exclude remote object pathnames specified by extended glob
pattern PATHS at storage endpoints with aliases specified by
extended glob pattern ALIASES from processing.
By default, exclude remote object pathnames at the root path.
Compatible with: --no-recursion-remote.
-f FILELIST process files and directories from a filelist file.
Conflicts with: -L, --remote-loc-xattr.
--fetch download a remote object partially or in full.
--filelist-format=LF|NUL|quoted
format of a filelist file:
"LF" - filenames delimited by newlines; a filename cannot
contain newline characters;
"NUL" - filenames delimited by the NUL (0) byte;
"quoted" - filenames possibly enclosed in single or double
quotes and delimited by newlines.
Default: "LF".
Compatible with: -f FILELIST.
--force delete remote object even if deletion safety checks do not pass
or enable local file overwriting for stub and
premigrate actions.
Implies: --overwrite-local
(with `-p, --premigrate' or `--stub');
`--skip-check-hash' and `--skip-check-uuid'
(without `-p, --premigrate', `--stub', or
`--sync-metadata').
Compatible with: --delete-remote; -p, --premigrate; --stub.
Conflicts with: --no-delete-remote
(without `-p, --premigrate', `--stub', or
`--sync-metadata').
--force-stub-size=LENGTH
forcibly set file stub size.
Default: do not forcibly set the stub size.
Compatible with: --stub.
--help display this help and exit.
--ignore-metadata
do not use most of remote object and folder metadata.
Default: use remote object and folder metadata if it
is available.
Conflicts with: --sync-metadata.
--ignore-rmtlc always use local file names to deduce remote object names.
Default: read remote location xattrs to determine the names of
remote objects for recalled or metadata synced files.
--keep-content preserve the content of a file as much as possible if the file
already exists.
Default: do not preserve any part of content of an already
existing file.
Compatible with: --fetch.
Conflicts with: --overwrite-local.
--lock-level=partial|implicit
DMAPI locking level:
"partial" - explicitly request DMAPI exclusive access rights
per file block when recalling a file and
explicitly request exclusive DMAPI access rights
when updating file metadata or stubbing a file;
request shared DMAPI access rights for all file
read operations, such as hashing.
"implicit" - instruct DMAPI to self-manage access rights per
file block when recalling and also self-manage
DMAPI access rights for all other file operations.
Default: "partial"; can be specified in the configuration file
or overridden by command line.
--log-format=json
log messages in JSON format.
Conflicts with: --log-target=syslog.
--log-target=syslog
redirect all logging to the syslog.
Conflicts with: --log-format=json.
--no-delete-remote
do not delete recalled remote objects from storage endpoints
where they were stored.
--no-dmapi do not call any DMAPI- or GPFS-related functions.
A non-privileged user can run the program.
Compatible with: --fetch.
--no-flock disable using lock files.
Sets lock level to "implicit" if it is not set.
Conflicts with "partial" lock level.
--no-recursion-remote
disable recursive interpretation of restriction and exclusion
extended glob patterns for remote object pathnames.
The recursive interpretation means matching sub-directories at
all nesting levels, whereas non-recursive interpretation means
matching a single directory.
Compatible with: -E, --endpoint; --endpoint-exclude.
--no-restore-acl
do not restore file and directory ACLs.
Compatible with: -p, --premigrate; --stub; --sync-metadata.
--overwrite
--overwrite-local
overwrite local files if they already exist.
Overwrite the status of local directories if they already exist
and were specified explicitly.
Default: if a local file or directory already exists, then
report a warning and do not overwrite the local file or
local directory status.
Compatible with: -p, --premigrate; --stub.
Conflicts with: --sync-metadata.
-P, --param-endpoint=ALIASES:PARAMETER=VALUE
add a parameter with name PARAMETER and value VALUE to
parameters read from configuration files for storage endpoints
with aliases specified by extended glob pattern ALIASES.
If PARAMETER already exists in a configuration file, it takes
a new VALUE.
--path-local=PATH
--local-path=PATH
reversely stub/premigrate or metadata sync a single remote
object or folder to a local file, directory, or symbolic link
PATH or reversely stub/premigrate or metadata sync multiple
remote objects and/or folders to a local directory PATH
(ending with `/').
Compatible with: -p, --premigrate; --stub; --sync-metadata.
--perf-dstat=INTERVAL,FILE
record the following information about the running program to a
FILE every INTERVAL seconds: virtual memory size (in
megabytes), resident set size (in megabytes), thread count, and
the number of open file descriptors.
--perf-profile[=all]
dump cumulative times of executing various operations:
"all" - dump cumulative times for all operations executed at
least once (default: hide operations with
insignificant times).
-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). Restore local directories and symbolic links.
Implies the option: --no-delete-remote.
Conflicts with: --stub; --sync-metadata.
-r, --recursion-local
if program arguments specify directory names, process files in
those directories and their sub-directories recursively.
Default: process specified directories but not their content.
--remote-offset-end=OFFSET
ending offset (exclusive) of a segment of a remote
object to download.
Default: remote object size.
Compatible with: --fetch.
--remote-offset-start=OFFSET
beginning offset of a segment of a remote object to download.
Default: 0.
Compatible with: --fetch.
-L, --remote-loc-xattr=REMOTE_LOC
location of a remote object to premigrate, create a local stub
file, or delete.
Compatible with: --delete-remote; -p, --premigrate; --stub;
--sync-metadata.
--restore-symlink-targets
recursively restore the targets of symbolic links in the
components of a path if the targets are symbolic
links or directories.
Compatible with: -p, --premigrate; --stub.
Conflicts with: --path-local; -L, --remote-loc-xattr;
--sync-metadata.
--skip-check-hash
when recalling a remote object, do not verify its SHA-512 hash
and do not set a missing SHA-512 hash metadata.
When analyzing whether it is safe to delete a remote object, do
not verify its size and SHA-512 hash.
--skip-check-uuid
do not verify that the UUID xattr of a local file and the UUID
of a remote object fetched from its metadata are equal.
When recalling a remote object, do not set a missing
UUID metadata.
When reverse stubbing/premigrating a remote object or syncing
its metadata, do not verify that the UUID-like name suffix of
this object matches a UUID fetched from metadata.
When scanning storage endpoints, do not verify that the
UUID-like name suffix of a remote object matches a UUID
fetched from metadata.
When analyzing whether it is safe to delete a remote object, do
not read the UUID xattr of a local file, do not fetch the UUID
of the remote object from its metadata, and do not verify that
they are equal.
--stub create local stub files.
Restore local directories and symbolic links.
Implies the option: --no-delete-remote.
Conflicts with: -p, --premigrate; --sync-metadata.
--sync-metadata update the status of local files, directories, or symbolic
links from remote object or folder metadata.
Implies the option: --no-delete-remote.
Conflicts with: -p, --premigrate; --stub;
--update-atime; --update-mtime.
--update-atime update the access time and status change time of local files to
"now" after successful recall or reverse stubbing/premigration.
Conflicts with: --sync-metadata.
--update-mtime update the modification time and status change time of local
files to "now" after successful recall or
reverse stubbing/premigration.
Conflicts with: --sync-metadata.
-v, --verbose[=LEVEL]
verbosity level:
0 = error and warning messages (also used when this option
is absent);
1 = print the names of successfully recalled files (default);
2 = debug messages, excluding those related to file locking;
3 = enable core dump and debug messages related to file locking;
print PID and current time with microsecond precision.
-V, --version display version information and exit.
Exit Status¶
On successful completion, ngrecall returns exit status 0. If ngrecall was invoked to recall or reversely stub or reversely premigrate or delete remote objects for files not specified by fsid/ino/igen triples on the command line, the successful completion means that all those files were recalled or reversely stubbed or reversely premigrated successfully, or that all remote objects were deleted, and there were no warning messages printed.
If ngrecall was invoked to recall or delete a remote object for at least one file specified by an fsid/ino/igen triple, the completion is considered successful even in the case of warnings or if recalling or deleting remote objects for all files was skipped (for example, because files to recall were already online). This behavior was designed to simplify invoking ngrecall from a GPFS filesystem policy with passing the fsid/ino/igen triple of a file to recall and analyzing an exit status returned by ngrecall---zero exit status means that the file has correct content, and a non-zero exit status means recall failure.
On unsuccessful completion, ngrecall returns exit status 1. The unsuccessful completion means that recalling at least one file failed with an error. If ngrecall was invoked to recall files or delete remote objects for files not specified by fsid/ino/igen triples on the command line, the unsuccessful completion also means that none of the files or remote objects were processed (with error or warning messages printed).
On partially successful completion, ngrecall returns exit status 2. The partially successful completion means that processing some files specified on the command line was successful, and that processing some files failed with errors, but those errors were not file recall errors. If ngrecall was invoked to recall or reversely stub or reversely premigrate or delete remote objects for files not specified by fsid/ino/igen triples on the command line, the partially successful completion also means that all those files were recalled or reversely stubbed or reversely premigrated successfully, or that all remote objects were deleted, but there were warning messages printed.
Processing Latest Remote Object Instances¶
A remote object can have multiple instances. A stem instance of a remote object does not have a UUID suffix appended to its name. Other instances of the remote object have UUID suffixes appended to the stem name. Every remote object instance has migration time associated with it. In reverse stubbing or reverse premigration mode, ngrecall scans instances of a remote object with a given stem name, finds an instance with latest migration time, and uses this instance to create a reverse stub or download the remote object.
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).
Scanning Storage Endpoints with Reverse Stubbing/Premigrating¶
To scan a storage endpoint and create reverse stubs for remote objects found, a user passes the options --stub and -E, --endpoint / --endpoint-exclude to ngrecall without passing a list of local file names.
For example, to scan a storage endpoint with the alias "awss3" within the remote folder "test-scan-stub-premigrate", the user specifies the command:
ngrecall --stub -E awss3:test-scan-stub-premigrate/
To scan a storage endpoint and reversely premigrate remote objects found, a user passes the option -p, --premigrate instead of --stub:
ngrecall -p -E awss3:test-scan-stub-premigrate/
To prevent recursive processing of a remote folder, the user adds the option --no-recursion-remote. To allow ngrecall to overwrite files that already exist in a local folder, the user adds the option --overwrite.
It is possible to create reverse stubs for or reversely premigrate remote objects in multiple endpoints in a single invocation of ngrecall. For that, specify multiple options -E, --endpoint or specify an option -E, --endpoint with a storage endpoint alias containing wildcards.
For example, to reversely premigrate remote objects in all storage endpoints defined in a master configuration file, the user specifes the command:
ngrecall -p -E '*'
Multiple storage endpoints may contain remote objects corresponding to the same local file name. To prevent overwriting the same local file multiple times, do not pass the option --overwrite to ngrecall when creating reverse stubs for or reversely premigrating remote objects in multiple storage endpoints. Instead, a target local directory should be empty. In this case, when remote objects in multiple storage endpoints correspond to the same local file, ngrecall will set remote location xattrs for all those storage endpoints in the local file.
Deleting From Multiple Storage Endpoints¶
Remote object deletion is supported for individual and multiple storage endpoints defined in a master configuration file.
A storage endpoint can be selected for remote object deletion if the option --delete-remote is present on ngrecall command line, or the storage endpoint has the parameter DeleteOnRecall=true in its configuration file.
The effect of the option --delete-remote and the parameter DeleteOnRecall=true is negated by the option --no-delete-remote.
The latter option has a higher priority.
The options --endpoint=ALIASES[:PATHS] and --endpoint-exclude=ALIASES[:PATHS] filter a set of storage endpoints for remote object deletion and the names of deleted objects in the endpoints.
If a file specified on the command line is offline, ngrecall deletes (subject to the rules mentioned above) remote objects corresponding to the file on its successful recall. The deleted remote objects are the object in a storage endpoint ngrecall successfully recalled the file from and objects specified by other remote location xattrs of that file if they exist.
If a file specified on the command line is in the "premigrated" state, or the file does not exist locally, ngrecall called with the option --delete-remote deletes remote objects corresponding to the local file.
No local file deletion occurs.
Deleting remote objects for a locally nonexistent file requires specifying the option --force.
If a local file does not exist, ngrecall determines remote objects for the local file by matching storage endpoints described in a master configuration file (subject to filtering by the rules mentioned earlier) against an absolute name the file would have if it existed. In this case, ngrecall will not delete remote objects with UUIDs appended to their names.
Post deletion of a remote object for a local file, ngrecall removes from the local file a remote location xattr referencing the remote object. If remote object deletion succeeds, and the local file does not have any remote location xattrs, ngrecall removes all Ngenea-specific xattrs from the local file.
If a remote object has a mismatching SHA-512 hash or UUID, then 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.
Warning
When multiple overlapping storage endpoints are defined in a master configuration file, and those endpoints overlap in the same remote storage target (e.g. they have base folders "projects" and "projects/proj1" in the same S3 bucket), then on recalling a file matching to the endpoints, ngrecall will delete the remote object if at least one endpoint has DeleteOnRecall=true in its configuration file.
This behaviour will enact even if other matching overlapping endpoints have DeleteOnRecall=false.
Downloading a Segment of a Remote Object¶
The ngrecall tool supports downloading a segment of a remote object in "fetch" mode set by passing the option --fetch.
The option --remote-offset-start=OFFSET specifies the beginning byte offset of the remote object content.
By default, the beginning byte offset is 0 -- downloading starts at the beginning of the remote object content.
The option --remote-offset-end=OFFSET specifies the ending byte offset of the remote object content.
By default, the ending byte offset is equal to remote object size -- downloading finishes at the end of the remote object content.
Passing the option --fetch along with --remote-offset-start=OFFSET and/or --remote-offset-end=OFFSET, ngrecall downloads a specifed segment of the remote object and writes the segment to a local file from the beginning of the file.
To write the segment at the same byte offsets as in the remote object, additionally pass the option --keep-content.
This results in a file with interleaved sparse segments.
The option --keep-content makes ngrecall expand or shrink the local file to match the size of the remote object.
If the file is expanded, an appended file part is filled with zero bytes (sparse segment).
Passing --keep-content, file content outside of the downloaded segment is preserved.
If the entire remote object is fetched, ngrecall changes the status of the local file to PREMIGRATED. If a part of a remote object is fetched, ngrecall changes the status of the local file to NORMAL to prevent data corruption by overwriting the same remote object instance with its part on subsequent migration.
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:
Disables reading the object size xattr of the local file.
Disables checking the equality of object size specified in that xattr and the actual size of the local file.
Disables obtaining the size of the remote object.
Disables checking the equality of the obtained size of the remote object and the actual size of the local file.
Disables computing the SHA-512 hash of the local file.
Disables reading the SHA-512 hash xattr of the local file.
Disables checking the equality of a SHA-512 hash specified in that xattr and the computed hash of the local file.
Disables reading the SHA-512 hash of the remote object from its metadata.
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:
Disables reading the UUID xattr of the local file.
Disables reading the UUID of the remote object from its metadata.
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/*
Hint
See Handling a Too Long List of Arguments for information on how to get rid of "Argument list too long" error if a large number of files match glob patterns specified on the command line.
See Also¶
ACL Support¶
Ngenea supports saving and restoring the ACLs of files and directories. This behaviour is particularly applicable to 'follow-the-sun' type workflows where security of data is enforced across global sites.
To enable saving ACLs of local files and directories in a storage endpoint via ngmigrate specify the parameter ACLSave=true in the configuration file for the storage endpoint.
To disable restoration of remote ACLs to local files and directories on reverse stubbing/premigration pass the option --no-restore-acl to ngrecall.
Similarly to restoring other metadata of local directories on reverse stubbing/premigration, ngrecall does not restore (I.E. overwrite) the ACLs of local pre-existing directories.
ACL Behaviour¶
Ngenea ACL behaviour differs depending upon the ACL support of the target endpoint type.
Object Store¶
Local file ACLs are saved to the metadata of remote objects
Local directories ACLs are saved as shadow metadata remote objects
GPFS Filesystem¶
Local ACLs are copied to the ACLs of files and directories in the storage endpoint
A GPFS filesystem supports either POSIX or NFS4 ACLs.
The option -k of mmchfs provides configuration of ACL semantics for a GPFS filesystem.
Ngenea requires the ACL type configuration of a GPFS filesystem to be identical to that of the source GPFS filesystem in order to successfully restore the ACLs of local files and directories on reverse stubbing/premigration.
Where the ACL type of the destination filesystem differs from that stored in the endpoint --no-restore-acl can be passed to ngrecall to skip restoration of incompatible ACL types and successfully recall the file(s) and/or directories.
POSIX-compliant Filesystem¶
Local ACLs are saved to the metadata of remote objects and folders in the storage endpoint