.TH mmapplypolicy 03/23/06
mmapplypolicy Command
.SH "Name"
.PP
\fBmmapplypolicy\fR - Deletes files or migrates file data between
storage pools in accordance with policy rules.
.SH "Synopsis"
.PP
\fBmmapplypolicy\fR {\fIDevice\fR | \fIDirectory\fR} \fB[-P\fR
\fIPolicyFile\fR\fB] [-I {\fR\fB\fIyes\fR\fR \fB| defer | test}]\fR
\fB[-L\fR \fIn\fR \fB] [-D\fR
\fIyyyy-mm-dd\fR\fB[\fR\fI@hh:mm\fR\fB[:\fR\fIss\fR\fB]]]
[-s\fR \fIWorkDirectory\fR\fB]\fR
.SH "Description"
.PP
Use the \fBmmapplypolicy\fR command to manage the placement and
replication of data within GPFS storage pools. It can also be used to
delete files from GPFS. You may issue the \fBmmapplypolicy\fR
command from any node in the GPFS cluster that has the file system
mounted.
.PP
Any given file is a potential candidate for at most one \fBMIGRATE\fR or
\fBDELETE\fR operation during one invocation of the \fBmmapplypolicy\fR
command.
.PP
A file that matches an \fBEXCLUDE\fR rule is not subject to any
subsequent \fBMIGRATE\fR or \fBDELETE\fR rules. You should
carefully consider the order of rules within a policy to avoid unintended
consequences.
.PP
For detailed information on GPFS policies, see the chapter
\fIPolicy-based data management for
GPFS\fR in
\fIGeneral Parallel File
System: Advanced Administration Guide\fR.
.SH "Parameters"
.PP
.RS +3
\fB\fIDevice\fR
\fR
.RE
.RS +9
Specifies the device name of the file system from which files are to be
deleted or migrated. File system names need not be
fully-qualified. \fBfs0\fR is just as acceptable as
\fB/dev/fs0\fR. If specified, this must be the first
parameter.
.RE
.PP
.RS +3
\fB\fIDirectory\fR
\fR
.RE
.RS +9
Specifies the fully-qualified path name of a GPFS file system
subtree from which files are to be deleted or migrated. If specified,
this must be the first parameter.
.RE
.PP
.RS +3
\fB-I {\fB\fIyes\fR\fR | defer | test}
\fR
.RE
.RS +9
Specifies what actions the \fBmmapplypolicy\fR command performs on
files:
.PP
.RS +3
\fByes
\fR
.RE
.RS +9
Indicates that all applicable \fBMIGRATE\fR and \fBDELETE\fR policy
rules are run, and the data movement between pools is done during the
processing of the \fBmmapplypolicy\fR command. This is the default
action.
.RE
.PP
.RS +3
\fBdefer
\fR
.RE
.RS +9
Indicates that all applicable \fBMIGRATE\fR and \fBDELETE\fR policy
rules are run, but actual data movement between pools is deferred until the
next
\fBmmrestripefs\fR or \fBmmrestripefile\fR command.
.RE
.PP
.RS +3
\fBtest
\fR
.RE
.RS +9
Indicates that all policy rules are evaluated, but the
\fBmmapplypolicy\fR command only displays the actions that would be
performed had \fB-I defer\fR or \fB-I yes\fR 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.
.RE
.RE
.PP
.RS +3
\fB-P \fIPolicyFile\fR
\fR
.RE
.RS +9
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.
.RE
.SH "Options"
.PP
.RS +3
\fB-D
\fIyyyy-mm-dd\fR\fB[\fR\fI@hh:mm\fR\fB[:\fR\fIss\fR]]
\fR
.RE
.RS +9
Specifies a date and optionally a (UTC) time as \fIyear-month-day\fR at
\fIhour:minute:second\fR.
.PP
The \fBmmapplypolicy\fR command evaluates policy rules as if it were
running on the date and time specified by the \fB-D\fR flag.
This can be useful for planning or testing policies, to see how the
\fBmmapplypolicy\fR command would act in the future. If this flag is
omitted, the \fBmmapplypolicy\fR 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.
.RE
.PP
.RS +3
\fB-L \fIn\fR
\fR
.RE
.RS +9
Controls the level of information displayed by the \fBmmapplypolicy\fR
command. Larger values indicate the display of more detailed
information. These terms are used:
.PP
.RS +3
\fBcandidate file
\fR
.RE
.RS +9
A file that matches a \fBMIGRATE\fR or \fBDELETE\fR policy
rule.
.RE
.PP
.RS +3
\fBchosen file
\fR
.RE
.RS +9
A candidate file that has been scheduled for migration or deletion.
.RE
.PP
These are the valid values for \fIn\fR:
.PP
.RS +3
\fB0
\fR
.RE
.RS +9
Displays only serious errors.
.RE
.PP
.RS +3
\fB1
\fR
.RE
.RS +9
Displays some information as the command runs, but not for each
file. This is the default.
.RE
.PP
.RS +3
\fB2
\fR
.RE
.RS +9
Displays each chosen file and the scheduled migration or deletion
action.
.RE
.PP
.RS +3
\fB3
\fR
.RE
.RS +9
All of the above, plus displays each candidate file and the applicable
rule.
.RE
.PP
.RS +3
\fB4
\fR
.RE
.RS +9
All of the above, plus displays each explicitly \fBEXCLUDE\fR'ed
file, and the applicable rule.
.RE
.PP
.RS +3
\fB5
\fR
.RE
.RS +9
All of the above, plus displays the attributes of candidate and
\fBEXCLUDE\fR'ed files.
.RE
.PP
.RS +3
\fB6
\fR
.RE
.RS +9
All of the above, plus displays files that are not candidate files, and
their attributes.
.RE
.PP
For examples and more information on this flag, see the
section: \fIThe mmapplypolicy -L command\fR in
\fIGeneral Parallel File System: Problem
Determination Guide\fR.
.RE
.PP
.RS +3
\fB-s \fIWorkDirectory\fR
\fR
.RE
.RS +9
Specifies the directory to be used for temporary storage during
\fBmmapplypolicy\fR command processing. 
.PP
The default directory is \fB/tmp\fR. The \fBmmapplypolicy\fR
command stores lists of candidate and chosen files in temporary files within
this directory.
.RE
.SH "Exit status"
.PP
.PP
.RS +3
\fB0
\fR
.RE
.RS +9
Successful completion.
.RE
.PP
.RS +3
\fBnonzero
\fR
.RE
.RS +9
A failure has occurred.
.RE
.SH "Security"
.PP
You must have root authority to run the \fBmmapplypolicy\fR
command.
.PP
You may issue the \fBmmapplypolicy\fR command from any node in the GPFS
cluster that has the file systems mounted.
.PP
When using the \fBrcp\fR and \fBrsh\fR commands for remote
communication, a properly configured \fB.rhosts\fR file must exist
in the root user's home directory on each node in the GPFS
cluster. If you have designated the use of a different remote
communication program on either the
\fBmmcrcluster\fR
or the
\fBmmchcluster\fR command, you must
ensure:
.RS +3
.HP 3
1. Proper authorization is granted to all nodes in the GPFS cluster.
.HP 3
2. The nodes in the GPFS cluster can communicate without the use of a
password, and without any extraneous messages.
.RE
.SH "Examples"
.RS +3
.HP 3
1. This command displays the actions that would occur if a policy were
applied, but does not apply the policy at this time:
.sp
.nf
mmapplypolicy fs1 -I test
.fi
.sp
The system displays output similar to:
.sp
.nf
GPFS Current Data Pool Utilization in KB and %
sp1     2196992 140095488       1.568210%
system  444672  140095488       0.317406%
Loaded policy rules from /var/mmfs/tmp/polFile.mmapplypolicy.18754.
Evaluating MIGRATE/DELETE/EXCLUDE rules with\ 
CURRENT_TIMESTAMP = 2006-03-16@19:58:49 UTC
parsed 2 Placement Rules, 2 Migrate/Delete/Exclude Rules
Directories scan: 7 files, 2 directories, 0 other objects,
0 'skipped' files and/or errors.
Inodes scan: 7 files, 0 'skipped' files and/or errors.
Summary of Rule Applicability and File Choices:
 Rule#  Hit_Cnt Chosen  KB_Chosen  KB_Ill  Rule
  0     3       3       2097160    0\ 
RULE 'migrate to system' MIGRATE FROM POOL 'sp1' TO POOL 'system'
  1     4       4       32         0\ 
RULE 'migrate to sp1' MIGRATE FROM POOL 'system' TO POOL 'sp1'
GPFS Policy Decisions and File Choice Totals:
 Chose to migrate 2097192KB: 7 of 7 candidates;
 Chose to delete 0KB: 0 of 0 candidates;
 0KB of chosen data is illplaced or illreplicated;
Predicted Data Pool Utilization in KB and %:
sp1     99864   140095488       0.071283%
system  2541800 140095488       1.814334%
.fi
.sp
.HP 3
2. This command applies a policy immediately:
.sp
.nf
mmapplypolicy fs1 -L 2
.fi
.sp
The system displays output similar to:
.sp
.nf
GPFS Current Data Pool Utilization in KB and %
sp1     2196992 140095488       1.568210%
system  444928  140095488       0.317589%
Loaded policy rules from /var/mmfs/tmp/polFile.mmapplypolicy.19118.
Evaluating MIGRATE/DELETE/EXCLUDE rules with\ 
CURRENT_TIMESTAMP = 2006-03-16@20:06:25 UTC
parsed 2 Placement Rules, 2 Migrate/Delete/Exclude Rules
Directories scan: 7 files, 2 directories, 0 other objects,\ 
0 'skipped' files and/or errors.
Inodes scan: 7 files, 0 'skipped' files and/or errors.
Summary of Rule Applicability and File Choices:
 Rule#  Hit_Cnt Chosen  KB_Chosen  KB_Ill  Rule
  0     3       3       2097160    0\ 
RULE 'migrate to system' MIGRATE FROM POOL 'sp1' TO POOL 'system'
  1     4       4       32         0\ 
RULE 'migrate to sp1' MIGRATE FROM POOL 'system' TO POOL 'sp1'
GPFS Policy Decisions and File Choice Totals:
 Chose to migrate 2097192KB: 7 of 7 candidates;
 Chose to delete 0KB: 0 of 0 candidates;
 0KB of chosen data is illplaced or illreplicated;
Predicted Data Pool Utilization in KB and %:
sp1     99864   140095488       0.071283%
system  2542056 140095488       1.814517%
MIGRATED /fs1/file.2 TO POOL sp1
MIGRATED /fs1/file.1 TO POOL sp1
MIGRATED /fs1/mydir/tmp.0 TO POOL system
MIGRATED /fs1/mydir/file.0 TO POOL sp1
MIGRATED /fs1/file.0 TO POOL sp1
MIGRATED /fs1/tmp.2 TO POOL system
MIGRATED /fs1/tmp.1 TO POOL system
A total of 7 files have been migrated and/or deleted;\ 
0 'skipped' files and/or errors.
.fi
.sp
.HP 3
3. Additional examples of GPFS policies and using the \fBmmapplypolicy\fR
command are in the chapter
\fIPolicy-based data management for
GPFS\fR in
\fIGeneral Parallel File
System: Advanced Administration Guide\fR.
.RE
.SH "See also"
.PP
mmchpolicy Command
.PP
mmlspolicy Command
.SH "Location"
.PP
\fB/usr/lpp/mmfs/bin\fR