Search the docs

Appendix a - General

This Appendix contains additional information regarding items or concepts referenced in this document. For additional information, consult the Hammerspace product documentation.

Hammerspace Toolkit

The HSTK is available for both Windows, Mac, and Linux, and can be downloaded from the Hammerspace HSTK GitHub repository.

Hammerspace Toolkit Sample Scripts

A collection of sample HSTK scripts are available at the Hammerspace Sample Scripts GitHub repository. These scripts are all related to filesystem reporting, some of which were reviewed in this document.

Hammerspace Metadata Plugin for Windows

You can download the Hammerspace Metadata Plugin for Windows File Explorer from the Hammerspace Licensing Portal. Once you have logged in, look for the following in the Downloads section.

hscl hammerspace metadata plugin for windows image1
Figure 1. Hammerspace metadata plugin for Windows

Unzip the downloaded package, run (double click) the HammerspaceClassicInstaller.msi file, and follow the prompts. Once the installer completes, open Windows File Explorer and navigate to a Hammerspace share. Then, right-click a file and select Open Hammerspace.

hscl hammerspace metadata plugin for windows image2
Figure 2. Hammerspace metadata plugin for Windows

You should see the main plugin screen. Note that you can use the plugin to set the most common Hammerspace custom metadata values including keywords, labels, tags, and colors. For users who will be setting these custom metadata values, this option is likely much simpler for everyday use.

hscl hammerspace metadata plugin for windows image3
Figure 3. Hammerspace metadata plugin for Windows

Applying Queries Using the Hammerspace Metadata Plugin for Windows

The Hammerspace Metadata Plugin for Windows can also be used to apply queries.

  1. In Windows Explorer, right-click on a directory, share, or mapped drive on a Hammerspace share.

  2. Click Open Hammerspace.

  3. Check the Selected checkbox and enter the expression for the query you want in the selected collection.

hscl applying queries using the hammerspace metadata plugin for windows image1
Figure 4. Applying queries using the Hammerspace metadata plugin for Windows

  1. Click Apply.

  2. Navigate within the directory on which you set the selected query and add \.collections\selected to the path in the address bar. From there as you navigate, you will see all directories, but the only files that appear will be the ones that match the expression.

Common Operators Used with Hammerscript

The following operators can be used within Hammerscript to build conditional statements that can expand or narrow the conditions of the query.

  • && (AND, true if all arguments are true)

  • || (OR, true if any argument is true)

  • ! (NOT, false if the argument is true)

  • &&! (AND NOT, true if first argument is true and second is argument false)

  • ||! (OR NOT, true if first argument is true or second is argument false)

  • == or = (equal to)

  • != or <> (not equal to)

  • > (greater than)

  • >= (greater than or equal to)

  • < (less than)

  • ⇐ (less than or equal to)

  • & (Concatenation)

When creating expressions, the AND, OR, NOT, AND NOT, and OR NOT operators can also be written in plain text or in the symbol version (&&, ||, !, &&!, and ||!).

Additional Metadata Objects and Functions

The following is a partial list of metadata that may be queried using Hammerscript. This list provides additional examples not previously listed in the Frequently Used Metadata Values - Reporting section of this document.

  • ACCESS_TIME: POSIX atime

  • ACTIVITY: current average IOPS

  • CHANGE_TIME: POSIX ctime

  • CREATE_TIME: Create time. Commonly used with SMB protocol but also set when files are created via NFS.

  • FNMATCH(<TEXT>,NAME|PATH): Match a string with input such as PATH or NAME

  • MATCH_EXTENSION(<EXT>,NAME): Match the extension of the filename

  • MODIFY_TIME: POSIX mtime

  • NOW: Current date and time

  • PARENT_SHARE: Share name the file or directory belongs to

  • SIZE: File size

  • IS_LIVE: Is the file the live version or not. True indicates the file is in the live tree and not part of a snapshot

  • IS_OPEN: Does the file have an outstanding layout, i.e. has someone opened the file

  • IS_SNAP: Is the file in a snapshot?

  • IS_UNDELETE: Is the file an undelete file? Only true of undelete files in special .snapshot/CURRENT directory

  • VERSION_NEWEST: Most recent snapshot in which this file exists

  • VERSION_OLDEST: Oldest snapshot in which this file exists

  • VERSION: Snapshot version where this file resides

  • VERSION_AGE: How old is the file compared to the live tree. Age of 0 seconds indicates it is the live version of the file

  • VERSIONS_TOTAL: Number of snapshots the file is a part of.

Various units can be expressed in easy-to-use English, such as MINUTES, HOURS, WEEKS, and so forth, for time. The same applies for capacity where both GB (gigabytes) and GiB (gibibytes) variants are available.

File Metadata Example (Full)

The following is the raw output of a file’s Hammerspace metadata that contains values for many of the conditions discussed in this document.

Obtain this information for files located on a Hammerspace share using the hs eval -e this command as shown in the following example:

$ hs eval -e this file.ext
ITEM_TABLE{
|NOW = LOCAL_TIME('2024-09-24 12:53:52'),
|INODE = INODE_NUMBER('961'),
|IS_BEING_CREATED = FALSE,
|NAME = "file-95",
|TYPE = ITEM_TYPE('FILE'),
|MODE = 0664,
|NLINK = 1,
|OWNER = USER('1000'),
|OWNER_GROUP = GROUP('1000'),
|SIZE = 4.096 KBYTES,
|SPACE_USED = 4.096 KBYTES,
|CHANGE_TIME = LOCAL_TIME('2024-09-05 17:15:31'),
|ACCESS_TIME = LOCAL_TIME('2024-09-05 16:58:05'),
|MODIFY_TIME = LOCAL_TIME('2024-09-05 17:15:31'),
|CREATE_TIME = LOCAL_TIME('2024-09-05 16:58:05'),
|LAST_USE_TIME = LOCAL_TIME('2024-09-05 17:15:31'),
|SYMLINK = #EMPTY,
RDEV = RDEV_TABLE{
|MAJOR = 0,
|MINOR = 0},
|ACTIVITY = 0 OPERATIONS / SECOND,
|ERRORS = ERROR_NONE,
|ERRORS_REFRESHED = ERROR_NONE,
|IS_MODIFIED_AFTER_SNAP = FALSE,
|VERSION = 1,
|VERSION_OLDEST = 2,
|VERSION_NEWEST = 1,
ALIGNMENT_DETAILS = ALIGNMENT_DETAILS_TABLE{
|CHANGE_TIME = LOCAL_TIME('1969-12-31 19:00:00'),
|LAST_CHECKED_TIME = LOCAL_TIME('1969-12-31 19:00:00'),
|OVERALL = ALIGNMENT('ALIGNED'),
|PLACE_ON = ALIGNMENT('ALIGNED'),
|EXCLUDE_FROM = ALIGNMENT('ALIGNED'),
|CONFINE_TO = ALIGNMENT('ALIGNED'),
|DO_NOT_MOVE = ALIGNMENT('UNKNOWN'),
|DURABILITY = ALIGNMENT('ALIGNED'),
|ONLINE_DELAY = ALIGNMENT('ALIGNED'),
|AVAILABILITY = ALIGNMENT('ALIGNED'),
|READ_BANDWIDTH = ALIGNMENT('ALIGNED'),
|READ_IOPS = ALIGNMENT('ALIGNED'),
|READ_LATENCY = ALIGNMENT('ALIGNED'),
|WRITE_BANDWIDTH = ALIGNMENT('ALIGNED'),
|WRITE_IOPS = ALIGNMENT('ALIGNED'),
|WRITE_LATENCY = ALIGNMENT('ALIGNED'),
|STATE = ALIGNMENT_STATE('WAITING_FOR_TARGET_WITH_SPACE'),
#R = 2},
ALIGNMENT_ASPECTS = {
ASPECT('OVERALL'), ALIGNMENT('ALIGNED');
ASPECT('PLACE ON'), ALIGNMENT('ALIGNED');
ASPECT('EXCLUDE FROM'), ALIGNMENT('ALIGNED');
ASPECT('CONFINE TO'), ALIGNMENT('ALIGNED');
ASPECT('DURABILITY'), ALIGNMENT('ALIGNED');
ASPECT('ONLINE DELAY'), ALIGNMENT('ALIGNED');
ASPECT('AVAILABILITY'), ALIGNMENT('ALIGNED');
ASPECT('READ BANDWIDTH'), ALIGNMENT('ALIGNED');
ASPECT('READ IOPS'), ALIGNMENT('ALIGNED');
ASPECT('READ LATENCY'), ALIGNMENT('ALIGNED');
ASPECT('WRITE BANDWIDTH'), ALIGNMENT('ALIGNED');
ASPECT('WRITE IOPS'), ALIGNMENT('ALIGNED');
ASPECT('WRITE LATENCY'), ALIGNMENT('ALIGNED')},
INSTANCES = INSTANCES_TABLE{
|CREATE_TIME = LOCAL_TIME('2024-03-20 08:37:56'),
|START_TIME = LOCAL_TIME('2024-03-20 08:37:56'),
|END_TIME = LOCAL_TIME('2024-09-24 12:53:52'),
|VOLUME = STORAGE_VOLUME('AZ2:VOL2-2'),
|START_OFFSET = 0 BYTES,
|END_OFFSET = 4.096 KBYTES,
|SPACE_USED = 4.096 KBYTES,
|ID = 9223372036854817e3,
|NSHARED = 1,
|READABLE = 1,
|WRITEABLE = 1,
|UID = 10,
|GID = 10,
|MTIME = LOCAL_TIME('2024-09-05 17:18:19'),
|ATIME = LOCAL_TIME('2024-03-20 08:37:56'),
|ERROR_COUNT = 0,
|PATH = "/PrimaryData/Instances/1/0/7624/v40-f1-8000000000009dc6",
|SIGNATURE = "000293DCC16BDFA6C58A1ECA946B140D813A4EF1F843F0FCFE6ECA0D1BBDB8D9CE5D0000000000001000",
|SHARE_PERCENTAGE = 100%,
|LENGTH = 4.096 KBYTES,
|SPARSENESS = 100%,
|ONLINE_DELAY = 0 SECONDS,
|IS_ONLINE = TRUE,
|IS_CURRENT = TRUE,
|IS_BEING_CREATED = FALSE,
|IS_BEING_MOVED = FALSE,
|PERCENTAGE_COMPLETE = 100%},
|HASH = "000293DCC16BDFA6C58A1ECA946B140D813A4EF1F843F0FCFE6ECA0D1BBDB8D9CE5D0000000000001000",
|ASSIMILATION_STATUS = #EMPTY,
SWEEP_DETAILS = SWEEP_DETAILS_TABLE{
|NUMBER = 166821,
|START_TIME = LOCAL_TIME('2024-09-24 12:53:10'),
|END_TIME = LOCAL_TIME('2024-09-24 12:53:48'),
|COUNT = 1.002 KFILES,
ERROR_COUNTS = ERROR_STATS_TABLE{
|ERROR = ERROR_NUMBER('1'),
|COUNT = 6},
|TOTAL_COUNT = 1.002 KFILES,
|RATE = 26.243 FILES / SECOND,
|PROGRESS = 100%,
|ELAPSED_TIME = 38.182 SECONDS,
|REMAINING_TIME = 0 SECONDS,
|COMPLETION_TIME = LOCAL_TIME('2024-09-24 12:53:48');

|NUMBER = 166822,
|START_TIME = LOCAL_TIME('2024-09-24 12:53:48'),
|END_TIME = LOCAL_TIME('2024-09-24 12:53:52'),
|COUNT = 79 FILES,
ERROR_COUNTS = ERROR_STATS_TABLE{
|ERROR = ERROR_NUMBER('1'),
|COUNT = 1},
|TOTAL_COUNT = 1.002 KFILES,
|RATE = 21.02 FILES / SECOND,
|PROGRESS = 7.8842%,
|ELAPSED_TIME = 3.75837 SECONDS,
|REMAINING_TIME = 43.911 SECONDS,
|COMPLETION_TIME = LOCAL_TIME('2024-09-24 12:54:36')},
|BOOT_EPOCH = 4,
REPLICATION_DETAILS = REPLICATION_DETAILS_TABLE{
|SITE = SITE('NYC-HS-A'),
|INTERVAL = 5 SECONDS,
|SEND_TIME = LOCAL_TIME('2024-09-24 12:53:44'),
|RECV_TIME = LOCAL_TIME('2024-09-24 12:53:37'),
SNAPS = REPLICATION_DETAILS_SUB_TABLE{
|SENT_REQUESTS = 76557,
|SENT_BYTES = 0 BYTES,
|SUCCEEDED_REQUESTS = 76556,
|SUCCEEDED_BYTES = 0 BYTES,
|ERRORED_REQUESTS = 1,
|ERRORED_BYTES = 0 BYTES,
|COMPLETED_REQUESTS = 76557,
|COMPLETED_BYTES = 0 BYTES,
|PENDING_REQUESTS = 0,
|PENDING_BYTES = 0 BYTES},
DIRENTS = REPLICATION_DETAILS_SUB_TABLE{
|SENT_REQUESTS = 0,
|SENT_BYTES = 0 BYTES,
|SUCCEEDED_REQUESTS = 0,
|SUCCEEDED_BYTES = 0 BYTES,
|ERRORED_REQUESTS = 0,
|ERRORED_BYTES = 0 BYTES,
|COMPLETED_REQUESTS = 0,
|COMPLETED_BYTES = 0 BYTES,
|PENDING_REQUESTS = 0,
|PENDING_BYTES = 0 BYTES},
INODES = REPLICATION_DETAILS_SUB_TABLE{
|SENT_REQUESTS = 0,
|SENT_BYTES = 0 BYTES,
|SUCCEEDED_REQUESTS = 0,
|SUCCEEDED_BYTES = 0 BYTES,
|ERRORED_REQUESTS = 0,
|ERRORED_BYTES = 0 BYTES,
|COMPLETED_REQUESTS = 0,
|COMPLETED_BYTES = 0 BYTES,
|PENDING_REQUESTS = 0,
|PENDING_BYTES = 0 BYTES},
TOTAL = REPLICATION_DETAILS_SUB_TABLE{
|SENT_REQUESTS = 76557,
|SENT_BYTES = 0 BYTES,
|SUCCEEDED_REQUESTS = 76556,
|SUCCEEDED_BYTES = 0 BYTES,
|ERRORED_REQUESTS = 1,
|ERRORED_BYTES = 0 BYTES,
|COMPLETED_REQUESTS = 76557,
|COMPLETED_BYTES = 0 BYTES,
|PENDING_REQUESTS = 0,
|PENDING_BYTES = 0 BYTES},
|SEND_AGE = 8.0824 SECONDS,
|RECV_AGE = 14.333 SECONDS},
ASSIMILATION_DETAILS = ASSIMILATION_DETAILS_TABLE{},
|HAS_PERMANENT_DATA_LOSS = FALSE,
|HAS_PERMANENT_DATA_LOSS_REFRESHED = FALSE,
|HAS_ERROR = FALSE,
|ASSIMILATION_ERROR = ERROR_NONE,
|REPLICATION_ERROR = ERROR_NONE,
VERSION_DETAILS = VERSION_DETAILS_TABLE{
|TIME = LOCAL_TIME('2024-09-24 12:53:52'),
|PATH = "./file-95";

|TIME = LOCAL_TIME('2024-09-24 12:53:52'),
|PATH = "./.snapshot/current/file-95"},
|VERSIONS_TOTAL = 2,
|VERSION_TIME = LOCAL_TIME('2024-09-24 12:53:52'),
|LAST_EXISTED_TIME = LOCAL_TIME('2024-09-24 12:53:52'),
|SPARSENESS = 100%,
|OVERALL_ALIGNMENT = ALIGNMENT('ALIGNED'),
|OVERALL_ALIGNMENT_STATE = ALIGNMENT_STATE('WAITING_FOR_TARGET_WITH_SPACE'),
|ALIGNMENT_CHANGE_TIME = LOCAL_TIME('1969-12-31 19:00:00'),
|DATA_ORIGIN_LOCAL = FALSE,
|DATA_ORIGIN_REMOTE = TRUE,
DATA_ORIGIN_SITE = PARTICIPANTS_TABLE{
|ID = 1,
|SHARE_ID = 4,
|ADDRESS = "192.200.10.175",
|PORT = 9097,
|INTERVAL = 5 SECONDS,
|SITE_PARTICIPANT_ID = 2,
|ADMIN_STATUS = ADMINISTRATIVE_STATUS('ENABLED'),
|OPER_STATUS = OPERATIONAL_STATUS('UP'),
|SITE_NAME = "NYC-HS-A"},
|IS_OPEN = FALSE,
|HAS_ONLINE_INSTANCE = TRUE,
|IS_ONLINE = TRUE,
|IS_BEING_MOVED = FALSE,
|IS_OFFLINE = FALSE,
|IS_VOLATILE = FALSE,
|IS_DURABLE = TRUE,
|IS_UNAVAILABLE = FALSE,
|IS_AVAILABLE = TRUE,
|IS_ACTIVE = FALSE,
|IS_INACTIVE = TRUE,
|IS_LIVE = TRUE,
|IS_SNAP = FALSE,
|IS_UNDELETE = 0,
|IS_DELETED = FALSE,
|IS_FILE = TRUE,
|IS_SYMLINK = FALSE,
|IS_DIRECTORY = FALSE,
|HAS_DIRECTORY_ENTRIES = FALSE,
|IS_DEVICE = FALSE,
|IS_THREAT = FALSE,
|IS_NON_THREAT = FALSE,
|IS_THREAT_UNKNOWN = TRUE,
|MAY_BE_THREAT = TRUE,
|CREATE_AGE = (18 DAYS+19:55:51),
|CHANGE_AGE = (18 DAYS+19:38:21),
|ACCESS_AGE = (18 DAYS+19:55:51),
|MODIFY_AGE = (18 DAYS+19:38:21),
|LAST_USE_AGE = (18 DAYS+19:38:21),
|ACTUAL_CREATE_AGE = (18 DAYS+19:55:51),
|ACTUAL_ACCESS_AGE = (18 DAYS+19:55:51),
|ACTUAL_MODIFY_AGE = (18 DAYS+19:38:21),
|ACTUAL_LAST_USE_AGE = (18 DAYS+19:38:21),
|VERSION_AGE = 0 SECONDS,
|DELETED_AGE = 0 SECONDS,
|ALIGNMENT_CHANGE_AGE = (54 YEARS+280 DAYS),
|ONLINE_DELAY = 0 SECONDS,
|ORIGIN_SITE = SITE('LA-HS-B'),
ATTRIBUTES = ITEM_ATTRIBUTES_TYPED_TABLE{
|VIRUS_SCAN = VIRUS_SCAN_STATE('UNSCANNED'),
MIME = MIME_TYPE_TABLE{
|STRING = "/"},
|DO_NOT_MOVE = FALSE,
|CONSIDER_VOLATILE = FALSE,
|RECENTLY_USED_DURATION = 00:05:00,
|SELECTED = FALSE,
|SELECTED2 = FALSE,
|PROMOTE = FALSE,
|DEMOTE = FALSE,
COLORS = COLORS_TABLE{},
CSI_DETAILS = CSI_DETAILS_TABLE{}},
|OBJECT = OBJECT_NUMBER('1125899906842719'),
|DEPTH = 2,
|PATH = "./file-95",
DIRECTORY_STATS = DIRECTORY_STATS_TABLE{
|FILE_COUNT = 1 FILE,
|SPACE_USED = 1.234 MBYTES,
|ACTIVITY = 0.011574 OPERATIONS / SECOND,
|LAST_USE_TIME = LOCAL_TIME('1901-05-15 20:00:00'),
|LAST_USE_AGE = (123 YEARS+162 DAYS),
|ACTIVITY_LEVEL = IOPS_LEVEL('UNDER 10 IOPS'),
|HEAT = TEMPERATURE(|ACTIVITY=0.011574 OPERATIONS / SECOND),
|HEAT_LEVEL = TEMPERATURE_LEVEL('UNDER 10 IOPS')},
|DPATH = "./file-95",
|IS_ROOT = FALSE,
ALL_LABELS = LABELS_TABLE{},
|ACTUAL_CREATE_TIME = LOCAL_TIME('2024-09-05 16:58:05'),
|ACTUAL_MODIFY_TIME = LOCAL_TIME('2024-09-05 17:15:31'),
|ACTUAL_ACCESS_TIME = LOCAL_TIME('2024-09-05 16:58:05'),
|ACTUAL_LAST_USE_TIME = LOCAL_TIME('2024-09-05 17:15:31'),
|READONLY = FALSE,
|HIDDEN = FALSE,
|SYSTEM = FALSE,
|OFFLINE = FALSE,
|DIRECTORY = FALSE,
|ARCHIVE = FALSE,
|NORMAL = TRUE,
|REPARSEPOINT = FALSE,
|NOSCRUBDATA = FALSE,
|IS_NEWBORN = FALSE,
|IS_RECENTLY_USED = FALSE,
|IS_UNUSED_SINCE_CREATION = FALSE,
|ACTIVITY_LEVEL = IOPS_LEVEL('UNDER 10 IOPS'),
|HEAT = TEMPERATURE(|LAST_USE_AGE=(18 DAYS+19:38:21)),
|HEAT_LEVEL = TEMPERATURE_LEVEL('2 TO 3 WEEKS OLD'),
|SPACE_USED_LEVEL = SIZE_LEVEL('4 TO 32 KBYTES'),
|ACCESS_AGE_LEVEL = TIMESPAN_LEVEL('2 TO 3 WEEKS OLD'),
|MODIFY_AGE_LEVEL = TIMESPAN_LEVEL('2 TO 3 WEEKS OLD'),
|CHANGE_AGE_LEVEL = TIMESPAN_LEVEL('2 TO 3 WEEKS OLD'),
|CREATE_AGE_LEVEL = TIMESPAN_LEVEL('2 TO 3 WEEKS OLD'),
|LAST_USE_AGE_LEVEL = TIMESPAN_LEVEL('2 TO 3 WEEKS OLD'),
|ACTUAL_ACCESS_AGE_LEVEL = TIMESPAN_LEVEL('2 TO 3 WEEKS OLD'),
|ACTUAL_MODIFY_AGE_LEVEL = TIMESPAN_LEVEL('2 TO 3 WEEKS OLD'),
|ACTUAL_CREATE_AGE_LEVEL = TIMESPAN_LEVEL('2 TO 3 WEEKS OLD'),
|ACTUAL_LAST_USE_AGE_LEVEL = TIMESPAN_LEVEL('2 TO 3 WEEKS OLD'),
|PARENT_SHARE = SHARE('test_kent'),
PARTICIPANTS = PARTICIPANTS_TABLE{
|ID = 0,
|SHARE_ID = 42,
|ADDRESS = "192.200.10.160",
|PORT = 9097,
|INTERVAL = 0 SECONDS,
|SITE_PARTICIPANT_ID = 0,
|ADMIN_STATUS = ADMINISTRATIVE_STATUS('ENABLED'),
|OPER_STATUS = OPERATIONAL_STATUS('UP'),
|SITE_NAME = "LA-HS-A";

|ID = 1,
|SHARE_ID = 4,
|ADDRESS = "192.200.10.175",
|PORT = 9097,
|INTERVAL = 5 SECONDS,
|SITE_PARTICIPANT_ID = 2,
|ADMIN_STATUS = ADMINISTRATIVE_STATUS('ENABLED'),
|OPER_STATUS = OPERATIONAL_STATUS('UP'),
|SITE_NAME = "NYC-HS-A"},
DIRECTORY_ENTRIES = ITEM_TABLE{}}