mmapplypolicy command

Availability

Available on all IBM Spectrum Scale editions. Available on AIX® and Linux®.

Description

You can run the mmapplypolicy command from any node in the cluster that has mounted the file system.

The mmapplypolicy command does not affect placement rules (for example, the SET POOL and RESTORE rule) that are installed for a file system by the mmchpolicy command. To display the currently installed rules, issue the mmlspolicy command.

A given file can match more than one list rule, but will be included in a given list only once. ListName provides the binding to an EXTERNAL LIST rule that specifies the executable program to use when processing the generated list.

The EXTERNAL POOL rule defines an external storage pool. This rule does not match files, but serves to define the binding between the policy language and the external storage manager that implements the external storage.

Any given file is a potential candidate for at most one MIGRATE or DELETE operation during one invocation of the mmapplypolicy command. That same file may also match the first applicable LIST rule.

A file that matches an EXCLUDE rule is not subject to any subsequent MIGRATE, DELETE, or LIST rules. You should carefully consider the order of rules within a policy to avoid unintended consequences.

For detailed information on GPFS policies, see the IBM Spectrum Scale: Administration Guide.

This command cannot be run from a Windows node. The GPFS API, documented functions in gpfs.h are not implemented on Windows, however the policy language does support the Windows file attributes, so you can manage your GPFS Windows files using the mmapplypolicy command running on an AIX or Linux node.

kill -s SIGTERM -- -3813

mmdsh -N all ps auxw | grep policy

root     31666  0.0  0.0  84604  2328 ?        Sl   07:29   0:00 /usr/lpp/mmfs/bin/mmhelp-apolicy na -X
     10.222.4.12 -s /tmp -Y -x 36845 -m 24 -n 24 -a 2 -L 1 -d 00 -z 15
root      3813  0.3  0.1  68144  4792 pts/1    S    07:29   0:00 /bin/ksh /usr/lpp/mmfs/bin/mmapplypolicy
     /mak/millions -P /ghome/makaplan/policies/1p.policy -N all
root      3847  127  0.1 455228  5808 pts/1    Sl   07:29   0:38 /usr/lpp/mmfs/bin/tsapolicy /mak/millions
     -P /ghome/makaplan/policies/1p.policy -I yes -L 1 -X 10.222.4.12 -N all
root      3850  0.0  0.0  84832  1620 pts/1    Sl   07:29   0:00 /usr/lpp/mmfs/bin/tsapolicy /mak/millions
     -P /ghome/makaplan/policies/1p.policy -I yes -L 1 -X 10.222.4.12 -N all
root      3891  0.0  0.0  61156   768 pts/2    S+   07:29   0:00 grep policy

Parameters

Device

Specifies the device name of the file system from which files will have the policy rules applied. File system names need not be fully-qualified. fs0 is just as acceptable as /dev/fs0. If specified, this must be the first parameter.

Directory

Specifies the fully-qualified path name of a GPFS file system subtree from which files will have the policy rules applied. If specified, this must be the first parameter.

-A IscanBuckets

Specifies the number of buckets of inode numbers (number of inode/filelists) to be created by the parallel directory scan and processed by the parallel inode scan. Affects the execution of the high-performance protocol that is used when both -g and -N are specified.

Tip: Set this parameter to the expected number of files to be scanned divided by one million. Then each bucket will have about one million files.

-a IscanThreads

Specifies the number of threads and sort pipelines each node will run during the parallel inode scan and policy evaluation. It affects the execution of the high-performance protocol that is used when both -g and -N are specified. The default is 2. Using a moderately larger number can significantly improve performance, but might "strain" the resources of the node. In some environments a large value for this parameter can lead to a command failure.

Tip: Set this parameter to the number of CPU "cores" implemented on a typical node in your GPFS cluster.

-B MaxFiles

Specifies how many files are passed for each invocation of the EXEC script. The default value is 100.

If the number of files exceeds the value specified for MaxFiles, mmapplypolicy invokes the external program multiple times.

For more information about file list records, refer to the IBM Spectrum Scale: Administration Guide.

-D yyyy-mm-dd[@hh:mm[:ss]]

Specifies a date and optionally a (UTC) time as year-month-day at hour:minute:second.

The mmapplypolicy command evaluates policy rules as if it were running on the date and time specified by the -D flag. This can be useful for planning or testing policies, to see how the mmapplypolicy command would act in the future. If this flag is omitted, the mmapplypolicy command uses the current date and (UTC) time. If a date is specified but not a time, the time is assumed to be 00:00:00.

-e

Causes mmapplypolicy to re-evaluate and revalidate the following conditions immediately before executing the policy action for each chosen file:

• That the PATH_NAME still leads to the chosen file, and that the INODE and GENERATION values are the same.
• That the rule (iRule) still applies to, and is a first matching rule for, the chosen file.

Note: The -e option is particularly useful with -r, but can be used apart from it. It is useful because in the time that elapses after the policy evaluation and up to the policy execution, it is possible that the chosen pathname no longer refers to the same inode (for example the original file was removed or renamed), or that some of the attributes of the chosen file have changed in some way so that the chosen file no longer satisfies the conditions of the rule. In general, the longer the elapsed time, the more likely it is that conditions have changed (depending on how the file system is being used). For example, if files are only written once and never renamed or erased, except by policy rules that call for deletion after an expiration interval, then it is probably not necessary to re-evaluate with the -e option.

For more information about -r, see IBM Spectrum Scale: Administration Guide.

-f FileListPrefix

Specifies the location (a path name or file name prefix or directory) in which the file lists for external pool and list operations are stored when either the -I defer or -I prepare option is chosen. The default location is LocalWorkDirectory/mmapplypolicy.processid.

-g GlobalWorkDirectory

Specifies a global work directory in which one or more nodes can store temporary files during mmapplypolicy command processing. For more information about specifying more than one node to process the command, see the description of the -N option. For more information about temporary files, see the description of the -s option.

The global directory can be in the file system that mmapplypolicy is processing or in another file system. The file system must be a shared file system, and it must be mounted and available for reading and writing by every node that will participate in the mmapplypolicy command processing.

If the -g option is not specified, then the global work directory is the directory that is specified by the sharedTmpDir attribute of the mmchconfig command. For more information, see mmchconfig command. If the sharedTmpDir attribute is not set to a value, then the global work directory depends on the file system format version of the target file system:

• If the target file system is at file system format version 5.0.1 or later (file system format number 19.01 or later), then the global work directory is the directory .mmSharedTmpDir at the root level of the target file system.
• If the target file system is at a file system format version that is earlier than 5.0.1 then the command does not use a global work directory.

If the global work directory that is specified by -g option or by the sharedTmpDir attribute begins with a forward slash (/) then it is treated as an absolute path. Otherwise it is treated as a path that is relative to the mount point of the file system.

If both the -g option and the -s option are specified, then temporary files can be stored in both the specified directories. In general, the local work directory contains temporary files that are written and read by a single node. The global work directory contains temporary files that are written and read by more than one node.

Note: The mmapplypolicy command uses high-performance, fault-tolerant protocols in its processing whenever both of the following conditions are true:

• The command is configured to run on multiple nodes.
• The command is configured to use a global work directory.

If the target file system is at file system format version 5.0.1 or later, then the command always uses high-performance, fault-tolerant protocols. The reason is that in this situation the command provides default values for running on multiple nodes (the node class managerNodes) and for sharing a global directory (.mmSharedTmpDir) if no explicit parameters are specified. For more information, see the following descriptions:

• The command runs on multiple nodes if any of the following circumstances are true:
  • The -N option on the command line specifies a set of helper nodes to run parallel instances of the policy code.
  • The defaultHelperNodes attribute of the mmchconfig command is set. This attribute specifies a list of helper nodes to be employed if the -N option is not specified.
  • The target file system is at file system format version 5.0.1 or later (file system format number 19.01 or later). If neither the -N option nor the defaultHelperNodes attribute is set, the members of the node class managerNodes are the helper nodes.
• The command uses a global work directory if any of the following circumstances are true:
  • The -g option on the command line specifies a global work directory.
  • The sharedTmpDir attribute of the mmchconfig command is set. This attribute specifies a global work directory to be used if the -g option is not specified.
  • The target file system is at file system format version 5.0.1 or later (file system format number 19.01 or later). If neither the -g option nor the sharedTmpDir attribute is set, the directory .mmSharedTmpDir at the root level of the target file system is the global work directory.

-I {yes | defer | test | prepare}

Specifies what actions the mmapplypolicy command performs on files:

yes

Indicates that all applicable policy rules are run, and the data movement between pools is done during the processing of the mmapplypolicy command. All defined external lists will be executed. This is the default action.

defer

Indicates that all applicable policy rules are run, but actual data movement between pools is deferred until the next mmrestripefs or mmrestripefile command. See also -f FileListPrefix.

test

Indicates that all policy rules are evaluated, but the mmapplypolicy command only displays the actions that would be performed had -I defer or -I yes been specified. There is no actual deletion of files or data movement between pools. This option is intended for testing the effects of particular policy rules.

prepare

Indicates that all policy execution is deferred and that mmapplypolicy only prepares file lists that are suitable for execution with the –r option. Records are written for each of the chosen files and are stored in one or more file lists, under a path name that is specified by the -f option or in the default local work directory. The actual data movement occurs when the command is rerun with the -r option.

-i InputFileList

Specifies the path name for a user-provided input file list. This file list enables you to specify multiple starter directories or files. It can be in either of the following formats:

simple format file list

A list of records with the following format:

PATH_NAME

Each record represents either a single file or a directory. When a directory is specified, the command processes the entire subtree that is rooted at the specified path name

File names can contain spaces and special characters; however, the special characters '\' and '\n' must be escaped with the '\' character similarly to the way mmapplypolicy writes path names in file lists for external pool and list operations.

The end-of-record character must be \n.

Example:

/mak/ea
/mak/old news
/mak/special\\stuff 

/usr/lpp/mmfs/samples/ilm/mmglobexpf.sample is an example of a script that can be used to generate simple format file lists.

expert format file list

A list of records with the following format:

INODE:GENERATION:path-length!PATH_NAME end-of-record-character

Each record represents exactly one file.

The INODE and GENERATION values must be specified in hexadecimal format (%11x). If you do not know the generation number or inode number, specify 0 and GPFS will look it up for you.

The path-length value must be specified in decimal format (%d). The path-length value is followed by the delimiter !.

The end-of-record character must be \n or \0.

Example (the end-of-record characters are invisible):

00009a00:0:8!d14/f681
00009a01:1002:8!d14/f682

When you use an expert format file list, the directory scan phase is skipped and only the files that are specified with the InputFileList parameter are tested against the policy rules.

For more information, see the IBM Spectrum Scale: Administration Guide.

With either format, if a path name is not fully qualified, it is assumed to be relative to one of the following:

• the Directory parameter on the mmapplypolicy command invocation

Or

• the mount point of the GPFS file system, if Device is specified as the first argument

-L n

Controls the level of information displayed by the mmapplypolicy command. Larger values indicate the display of more detailed information. These terms are used:

candidate file

A file that matches a MIGRATE, DELETE, or LIST policy rule.

chosen file

A candidate file that has been scheduled for action.

These are the valid values for n:

0

Displays only serious errors.

1

Displays some information as the command runs, but not for each file. This is the default.

2

Displays each chosen file and the scheduled migration or deletion action.

3

Displays the same information as 2, plus each candidate file and the applicable rule.

4

Displays the same information as 3, plus each explicitly EXCLUDEed or LISTed file, and the applicable rule.

5

Displays the same information as 4, plus the attributes of candidate and EXCLUDEed or LISTed files.

6

Displays the same information as 5, plus non-candidate files and their attributes.

For examples and more information on this flag, see the section: The mmapplypolicy -L command in the IBM Spectrum Scale: Problem Determination Guide.

-M name=value...

Indicates a string substitution that will be made in the text of the policy rules before the rules are interpreted. This allows the administrator to reuse a single policy rule file for incremental backups without editing the file for each backup.

-m ThreadLevel

The number of threads that are created and dispatched within each mmapplypolicy process during the policy execution phase. The default value is 24.

-N {all | mount | Node[,Node...] | NodeFile | NodeClass}

Specifies a set of nodes to run parallel instances of policy code for better performance. The nodes must be in the same cluster as the node from which the mmapplypolicy command is issued. All node classes are supported. For more information about these options, see Specifying nodes as input to GPFS commands.

If the -N option is not specified, then the command runs parallel instances of the policy code on the nodes that are specified by the defaultHelperNodes attribute of the mmchconfig command. For more information, see the topic mmchconfig command. If the defaultHelperNodes attribute is not set, then the list of helper nodes depends on the file system format version of the target file system. If the target file system is at file system format version 5.0.1 or later (file system format number 19.01 or later), then the helper nodes are the members of the node class managerNodes. Otherwise, the command runs only on the node where the mmapplypolicy command is issued.

-n DirThreadLevel...

The number of threads that will be created and dispatched within each mmapplypolicy process during the directory scan phase. The default is 24.

-P PolicyFile

Specifies the name of the file containing the policy rules to be applied. If not specified, the policy rules currently in effect for the file system are used. Use the mmlspolicy command to display the current policy rules.

-q

When specified, mmapplypolicy dispatches bunches of files from the file lists specified by the -r option in a round-robin fashion, so that the multithreaded (-m) and node parallel (-N) policy execution works on all the file lists "at the same time." When -q is not specified, policy execution works on the file lists sequentially. In either case bunches of files are dispatched for parallel execution to multiple threads (-m) on each of the possibly multiple nodes (-N).

-r FileListPathname...

Specifies one or more file lists of files for policy execution. The file lists that were used as input for -r were created by issuing mmapplypolicy with the -I prepare flag. You can specify several file lists by doing one of the following:

• Provide the path name of a directory of file lists, or
• Specify the -r option several times, each time with the path name of a different file list.

You can use this parameter to logically continue where mmapplypolicy left off when you specified the -I prepare option. To do this, invoke mmapplypolicy with all the same parameters and options (except the -I prepare option), and now substitute the -r option for -f. In between the invocations, you can process, reorder, filter, or edit the file lists that were created when you invoked -I prepare. You can specify any or all of the resulting file lists with the -r option.

The format of the records in each file list file can be expressed as:

iAggregate:WEIGHT:INODE:GENERATION:SIZE:iRule:resourceId:attr_flags:
path-lengthl!PATH_NAME:pool-length!POOL_NAME
[;show-length>!SHOW]end-of-record-character

For more information about file list records, refer to the IBM Spectrum Scale: Administration Guide.

-S SnapshotName

Specifies the name of a global snapshot for file system backup operations or for migrating snapshot data. The name appears as a subdirectory of the .snapshots directory in the file system root and can be found with the mmlssnapshot command.

Note: GPFS snapshots are read-only. Do not use deletion rules with -S SnapshotName.

Note: Do not use the -S option to scan files in a fileset snapshot. Instead, specify the full path of a directory in the snapshot as the first parameter of the command, as in the following example:

mmapplypolicy <directory_path> -P policyfile ...

-s LocalWorkDirectory

Specifies a local directory in which one or more nodes can store temporary files during mmapplypolicy command processing. The default local work directory is /tmp. For more information about specifying more than one node to process the command, see the -N option of mmapplypolicy.

The temporary files contain lists of candidate files and lists of files that are selected to be processed. If the file system or directory that mmapplypolicy is processing contains many files, then the temporary files can occupy a large amount of storage space. To make a rough estimate of the size of the storage that is required, apply the formula K * AVLP * NF, where:

K

Is 3.75.

AVLP

Is the average length of the full path name of a file.

NF

Is the number of files that the command will process.

For example, if AVLP is 80, then the storage space that is required is roughly (300 * NF) bytes of temporary space.

--choice-algorithm {best | exact | fast}

Specifies one of the following types of algorithms that the policy engine is to use when selecting candidate files:

best

Chooses the optimal method based on the rest of the input parameters.

exact

Sorts all of the candidate files completely by weight, then serially considers each file from highest weight to lowest weight, choosing feasible candidates for migration, deletion, or listing according to any applicable rule LIMITs and current storage-pool occupancy. This is the default.

fast

Works together with the parallelized -g /shared-tmp -N node-list selection method. The fast choice method does not completely sort the candidates by weight. It uses a combination of statistical, heuristic, and parallel computing methods to favor higher weight candidate files over those of lower weight, but the set of chosen candidates may be somewhat different than those of the exact method, and the order in which the candidates are migrated, deleted, or listed is somewhat more random. The fast method uses statistics gathered during the policy evaluation phase. The fast choice method is especially fast when the collected statistics indicate that either all or none of the candidates are feasible.

--maxdepth MaxDirectoryDepth

Specifies how deeply in the hierarchy of the starting directory to apply policies to files. If this parameter is omitted, the command applies the policies to all the subdirectories of the starting directory. A value of 0 causes the policies to be applied only to the files in the starting directory.

--max-merge-files MaxFiles

Specifies the maximum number of files to be passed as input to the sort command for sorting and merging.

The mmapplypolicy command must do multiple, potentially large sorts and merges of temporary files as part of its processing. The --max-merge-files parameter specifies the maximum number of files that the mmapplypolicy command passes as input to a single sort command for sorting and merging.

If you set this value too high, the result can be excessive memory usage. The operating system can respond by terminating some of the sort processes, which causes the mmapplypolicy command to run for a longer time or to return with an error.

The default value of this parameter is 12. In general, it is a good practice to accept the default value of this parameter or to test carefully if you specify an overriding value.

See the related parameters --max-sort-bytes and --sort-buffer-size.

--max-sort-bytes MaxBytes

Specifies the maximum number of bytes to be passed as input files to the sort command. This parameter does not apply to merges in which each of the input files has already been sorted.

The mmapplypolicy command must do multiple, potentially large sorts and merges of temporary files as part of its processing. The --max-sort-bytes parameter specifies the maximum number of bytes that the mmapplypolicy command can pass to a single instance of the sort command in one or more files.

If you set this value too high, the result can be excessive memory usage. The operating system can respond by terminating some of the sort processes, which causes the mmapplypolicy command to run for a longer time or to return with an error.

The default value of this parameter is 411 MB. In general, it is a good practice to accept the default value of this parameter or to test carefully if you specify an overriding value.

See the related parameters --max-merge-files and --sort-buffer-size.

--scope {filesystem | inodespace | fileset}

If Device is specified, the directory traversal starts at the root of the file system. --scope indicates one of the following levels of scope to be applied to the policy scan:

filesystem

The scan will involve the objects in the entire file system subtree pointed to by the Directory parameter. This is the default.

fileset

The scope of the scan is limited to the objects in the same fileset as the directory pointed to by the Directory parameter.

inodespace

The scope is limited to objects in the same single inode space from which the directory pointed to by the Directory parameter is allocated. The scan may span more than one fileset, if those filesets share the same inode space.

--qos QOSClass

Specifies the Quality of Service for I/O operations (QoS) class to which the instance of the command is assigned. If you do not specify this parameter, the instance of the command is assigned by default to the maintenance QoS class. This parameter has no effect unless the QoS service is enabled. For more information, see the topic mmchqos command. Specify one of the following QoS classes:

maintenance

This QoS class is typically configured to have a smaller share of file system IOPS. Use this class for I/O-intensive, potentially long-running GPFS commands, so that they contribute less to reducing overall file system performance.

other

This QoS class is typically configured to have a larger share of file system IOPS. Use this class for administration commands that are not I/O-intensive.

For more information, see the topic Setting the Quality of Service for I/O operations (QoS).

--other-sort-options SortOptions

Passes options to the sort command (either the default sort command provided with the operating system, or an alternative sort command specified by the --sort-command parameter).

--single-instance

Ensures that, for the specified file system, only one instance of mmapplypolicy invoked with the --single-instance option can execute at one time. If another instance of mmapplypolicy invoked with the --single-instance option is currently executing, this invocation will do nothing but terminate.

--sort-buffer-size Size

Sets the sort-buffer size that is passed to the sort command. This parameter limits memory usage by the sort commands that the mmapplypolicy command calls to do sorts and merges.

The mmapplypolicy command must do multiple, potentially large sorts and merges of temporary files as part of its processing. It calls the operating-system sort command each time that it must do a sort. It can have multiple instances of the sort command running at the same time. If the numbers of items to be sorted are very large, the result can be excessive memory usage. The operating system can respond by terminating some of the sort processes, which causes the mmapplypolicy command to run for a longer time or to return with an error.

To prevent excessive memory consumption, you can set the --sort-buffer-size parameter to a lower value than its default. The --sort-buffer-size parameter is the value that the mmapplypolicy command passes to the sort command in the buffer-size parameter. The default value is 8%. If you need a lower value, you might set it to 5%.

You can specify the --sort-buffer-size parameter in any format that the sort program's buffer-size parameter accepts, such as "5%" or "1M".

In general, accept the default value of this parameter unless the system has excessive memory consumption that is attributable to large sort operations by the mmapplypolicy command.

See the related parameters --max-merge-files and max-sort-bytes.

--sort-command SortCommand

Specifies the fully-qualified path name for a Posix-compliant sort command to be used instead of the default, standard command provided by the operating system.

Before specifying an alternative sort command (and for information about a suggested sort command), see Improving performance with the --sort-command parameter.

--split-filelists-by-weight

Specifies that each of the generated file lists contain elements with the same WEIGHT value. This can be useful in conjunction with the LIST rule and the WEIGHT (DIRECTORY_HASH) clause. In this case, each generated list will contain files from the same directory.

Note: If you want all of the files from a given directory to appear in just one list, you might have to specify a sufficiently large -B value.

--split-margin n.n

A floating-point number that specifies the percentage within which the fast-choice algorithm is allowed to deviate from the LIMIT and THRESHOLD targets specified by the policy rules. For example if you specified a THRESHOLD number of 80% and a split-margin value of 0.2, the fast-choice algorithm could finish choosing files when it reached 80.2%, or it might choose files that bring the occupancy down to 79.8%. A nonzero value for split-margin can greatly accelerate the execution of the fast-choice algorithm when there are many small files. The default is 0.2.

Exit status

0

Successful completion.

nonzero

A failure has occurred.

Security

You must have root authority to run the mmapplypolicy command.

The node on which the command is issued must be able to execute remote shell commands on any other node in the cluster without the use of a password and without producing any extraneous messages. For more information, see Requirements for administering a GPFS file system.

See also

Location