mmapplypolicy command

Availability

Available with IBM Spectrum Scale™ Standard Edition or higher. 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: Advanced 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: Advanced 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: Advanced 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 directory to be used for temporary storage during mmapplypolicy command processing. The specified directory must exist within a shared file system. It must also be mounted and available for writing and reading from each of the nodes specified by the -N option. When both -N and -g are specified, mmapplypolicy uses high performance and fault-tolerant protocols during execution.

Note: The -g option should specify a directory (for temporary or work files) within a GPFS file system that is accessible from each node specified with the -N option. The directory can either be in the file system being operated upon by mmapplypolicy or in another file system.

There is no default value for -g.

If the -g option is specified, but not the -s option, the directory specified by -g is used for all temporary files required by mmapplypolicy. If both the -g and -s options are specified, temporary files may be stored in each. In general, temporary files that are only written and read by a single node are stored in the local work directory specified by the -s option, while temporary files that must be accessed by more than one node are stored in the global work directory specified by the -g option.

-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: Advanced 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 the list of nodes that will run parallel instances of policy code in the GPFS home cluster. This command supports all defined node classes. The default is to run on the node where the mmapplypolicy command is running or the current value of the defaultHelperNodes parameter of the mmchconfig command.

For general information on how to specify node names, see Specifying nodes as input to GPFS commands in the IBM Spectrum Scale: Administration and Programming Reference.

-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: Advanced Administration Guide.

-S SnapshotName

Specifies the name of a global snapshot for file system backup operations. 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 migration or deletion rules with -S SnapshotName.

-s LocalWorkDirectory

Specifies the directory to be used for temporary storage during mmapplypolicy command processing.

The default directory is /tmp. The mmapplypolicy command stores lists of candidate and chosen files in temporary files within this directory.

When you execute mmapplypolicy, it creates several temporary files and file lists. If the specified file system or directories contain many files, this can require a significant amount of temporary storage. The required storage is proportional to the number of files (NF) being acted on and the average length of the path name to each file (AVPL). To make a rough estimate of the space required, estimate NF and assume an AVPL of 80 bytes. With an AVPL of 80, the space required is roughly (300 X 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.

--max-merge-files

Specifies the maximum number of files to be passed as input to the sort/merge command.

--max-sort-bytes

Specifies the maximum number of bytes to be passed as one or more input files to the sort command. This does not apply to merges, when each of the input files has already been sorted.

--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.

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.

fileset

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

--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 in the IBM Spectrum Scale: Administration and Programming Reference. 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) in the IBM Spectrum Scale: Advanced Administration Guide.

--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

Limits the memory usage of any sort subprocesses executed by mmapplypolicy. The Size value is passed to the sort command on operating systems that support the --buffer-size option and can be specified in any syntax that is accepted by --buffer-size (for example, 20% or 1M).

--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 the topic about improving the performance of mmapplypolicy with the --sort-command parameter in IBM Spectrum Scale: Advanced Administration Guide.

--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 file system in IBM Spectrum Scale: Administration and Programming Reference.

See also

Location