test veritas logo


fsppadm(1M)

NAME

fsppadm - VxFS placement policy administration utility

AVAILABILITY

VRTSvxfs

SYNOPSIS

fsppadm assign [ -p io_nice ] [ -f ] [ mount_point ... ] policy_file

fsppadm analyze [ -F policy_file ] [ -p io_nice ] [ -P ]
[ -S action ... ] [ -i ] [ -T class. ... ] [ -C ]
[ path ... ]

fsppadm enforce [ -p io_nice ] [ -P ] [ -S action ... ]
[ [ -a ] -r file ] [ { -c .[ class. ] ... mount_point } |
{ [ -F policy_file ] [ -s size_count | -n file_count |
-t hours ] [ -T .[ class. ] ... ] [ -C ] path ... } ]

fsppadm query [ -p io_nice ] [ -P ] [ -S action ... ]
[ -l | { [ -a ] [ -w ] } ] [ -i ] [ -T class. ... ] [ -C ] [ -F policy_file ]
[ path ... ]

fsppadm unassign [ mount_point ... ]

fsppadm list [ -w ] [ mount_point ... ]

fsppadm print mount_point

fsppadm validate [ mount_point ... ] policy_file

fsppadm dump mount_point file

fsppadm subfilemove -f list_file mount_point

DESCRIPTION

The fsppadm utility performs administrative tasks, such as assigning, analyzing, enforcing, unassigning, and validating placement policies on the specified mount points.

The path argument specifies a mount point, subdirectory in a mount point, or a single file. If a subdirectory or mount point is specified, the command recursively applies to all subdirectories within the specified subdirectory or mount point.

The policy_file argument specifies the path of the XML file that contains the rules of the placement policy. See the FILES section for the file placement policy DTD file to see XML format of a placement policy.

The file argument specifies the file into which to send output from a dump or enforce operation.

Sample placement policy files are located in the /opt/VRTSvxfs/etc directory.

Cluster File System Issues

No cluster issues; command operates the same on cluster file systems.

KEYWORDS

analyze Analyzes the impact of enforcing the assigned placement policy and displays the amount of free space that will be on the volume set before and after any files are relocated. No files are actually relocated by this operation.
If path is not specified, fsppadm sweeps all mounted VxFS file systems that have disk layout Version 7 or later and have active placement policies.
The analysis only provides the approximate impact. An exact analysis is not possible because accurate space accounting for each file requires intensive computing. However, the enforce keyword does calculate accurate space accounting.
assign Creates a new active placement policy or replaces an existing placement policy for one or more mount points. The fsppadm command parses and validates the specified placement policy before assigning the placement policy. If errors are found, fsppadm displays the diagnosis and does not apply the placement policy. Some errors can simply be warnings, and the assign operation will succeed. Once the placement policy passes validation, fsppadm configures the specified VxFS file systems so that all future file creations and relocations are governed as per the placement policy. If the placement policy uses IOTEMP, fiostats collections, File Change Log and I/O statistics are turned on automatically if they were not already turned on. For information on IOTEMP, see the SmartTier chapter in the Storage Foundation Administrator’s Guide.
If mount_point is not specified, fsppadm sweeps all mounted VxFS file systems that have disk layout Version 7 or later and have active placement policies.
dump Dumps the contents of the active placement policy to the specified file. The dump should be used to backup the placement policy.
enforce Enforces the assigned placement policy on one or more mount points, subdirectories in a mount point, or files. Enforcing the placement policy adjusts placement behavior if necessary, and relocates or deletes files as per the placement policy.
Enforce operations are logged in a hidden file, .__fsppadm_enforce.log, in the lost+found directory of the mount point. This log file contains details such as files’ previous locations, files’ new locations, and the reasons for the files’ relocations. The enforce operation creates the .__fsppadm_enforce.log file if the file does not exist. The enforce operation appends the file if the file already exists. The log file can be backed up or removed as with a normal file.
If path is not specified, fsppadm sweeps all mounted VxFS file systems that have disk layout Version 7 or later and have active placement policies, except Storage Checkpoints. To prevent fsppadm from sweeping a file system, unmount the file system, unassign the file system’s active placement policy, or specify the file systems to be swept when running the enforce operation.
list Displays the name of the active placement policy assigned to the specified mount points. Mount point and placement policy names are printed in pairs. Specifying -w allows for easier parsing of the output.
If mount_point is not specified, fsppadm sweeps all mounted VxFS file systems that have disk layout Version 7 or later and have active placement policies.
print Displays the contents of the active placement policy file of the specified mount point.
query Displays where files on one or more specified mount points, files under one or more specified subdirectories, or one or more specified files were created, where they reside now, and where they will be moved if the placement policy is enforced. Also displays the criteria by which the files will be moved.
If path is not specified, fsppadm sweeps all mounted VxFS file systems that have disk layout Version 7 or later and have active placement policies.
subfilemove
  Relocates the ranges of the files listed in the file specified by list_file to the specified target tiers. Only one instance is allowed at a time on a given node for a given mount.
The application using this framework calls this command periodically via some external scheduling mechanism at desired intervals, to effect relocations. The application might need to call subfilemove on each node of a cluster, in case of a cluster file system, if you want to distribute the load. The application also must arrange for initiating this relocation for new mounts and reboots, if the application needs sub-file relocations on those nodes or mounts.
In a cluster situation, since enforcement can happen from multiple nodes even if each node is scheduled to collect statistics at the same intervals, each node’s persistence into the database can be slightly out of sync with each other on each node. Since enforcement should follow statistics collection, Veritas recommends that you schedule enforcements on each node with a few minutes of lag so that all nodes can complete the statistics synchronizing by that time. A lag time of 5 minutes suffices in most cases.
unassign Removes the active placement policy assigned to the specified mount points.
validate Checks the syntax and grammar of the specified placement policy. The fsppadm validate command validates the directories specified in the <DIRECTORY> element, the storage classes specified in the <CLASS> element with respect to the specified mount points, the users specified in the <USER> element, and the group names specified in the <GROUP> element of the placement policy with respect to the target host. If errors are found, fsppadm displays the diagnosis of the validation. Veritas recommends that you validate a placement policy before assigning the policy.
If mount_point is not specified, fsppadm sweeps all mounted VxFS file systems that have disk layout Version 7 or later and have active placement policies, except Storage Checkpoints.

OPTIONS

-a For the enforce and query keywords, the fsppadm command includes the access time, modification time, and file size of the specified paths in the report generated by -r. The -a option also includes IOTEMP if the active placement policy uses IOTEMP.
Without the -a option, the fsppadm command loads distribute enforcement among the mounted nodes by default on a cluster file system.
-C The fsppadm command processes only those files that have some activity statistics logged in the File Change Log file during the period specified in the policy. This can be used only if the policy’s ACCESSTEMP or IOTEMP use the Prefer criteria. If specified, such files are processed before any other files. This is particularly useful to process active files, such as files in solid state disk (SSD) tiers.
-c .[ class. ] ... mount_point
  Specifies a list of placement classes to which files must be relocated. A placement class is a specific subset of a file system’s volume set in which a placement policy causes affected files to be created and extended. A null list, indicated by a period (.), can be specified; see the -l option. A non-null list must begin with a period (.), and is period-separated. Non-null lists of placement classes ignore any placement class information provided in the file list piped from the -l option. See EXAMPLES. If a non-null list is specified, the list of files to be relocated, as specified by the path argument, should not include files that will be deleted. Any such files will instead be relocated along with the files that are intended to be relocated.
If -c is specified, the assigned placement policy is ignored and the list of files to be relocated must be passed via standard input. Subsequent runs of the enforce operation without the -c option enforces the active placement policy once again.
-F policy_file
  Forces the placement policy specified by policy_file to be used on the specified path or mount point, bypassing the existing active placement policy. This option can be used to analyze and enforce the rules given in the specified placement policy for maintenance purposes, such as for reclaiming a LUN from the file system.
-f Tunes fcl_keeptime to the largest period of interest in the placement policy if the placement policy uses IOTEMP. See the vxtunefs(1M) manual page. This preserves I/O statistics for that period.
-i Rebuilds the IOTEMP database. If the placement policy uses IOTEMP, the enforce operation automatically builds the IOTEMP database. Without specifying -i, the query operation uses the existing IOTEMP database, if any. To obtain meaningful results with the fsppadm query command, Veritas recommends that you rebuild the database if significant time passed since you last ran the enforce operation.
-l Lists the pathnames of the files that would be selected to be relocated or deleted when the enforce operation is run. The list is generated such that the output can be piped to another instance of fsppadm as the list of files to be relocated or deleted with the -c option. However, see the EXAMPLES section for a way to accomplish this with only one instance of fsppadm. If -l is not specified, fsppadm query displays the pathnames of all the files under the specified subdirectory or path.
-n file_count
  Specifies the maximum number of files that an enforce operation can relocate or delete in a given instance. An enforce operation that reaches the specified maximum can be restarted from the point at which the operation ended due to this limit.
-P Private files used by the fsppadm command, such as .__fsppadm_enforce.log, are not picked by the assigned placement policy. The enforce operation will not relocate the private files. The query operation will not list the private files. The analyze operation will not consider the private files for space impact analysis.
-p io_nice Specifies the number of concurrent threads to be used to perform the fsppadm operation. The io_nice parameter can be specified as an integer between 1 and 100. The default value is 50. A value of 1 specifies 1 slave and 1 master thread per mount. A value of 50 specifies 16 slaves and 1 master thread per mount. A value of 100 specifies 32 slaves and 1 master thread per mount.
-r file Generates a report and dumps the output to the specified file. Reports include which files were picked up by which rule, if a given file path was relocated or deleted, and so on. Specify an absolute pathname for the file.
-S action Specifies up to 32 RELOCATE or DELETE actions to be skipped. These actions are supplied by giving the Name attribute of the RELOCATE and DELETE actions that are to be skipped. Once you specify the actions, if the SELECT element of the RULE element that contains the RELOCATE and DELETE actions catches a given file, the corresponding RELOCATE or DELETE action is not performed.
-s size_count
  Specifies the maximum number of megabytes of data that an enforce operation can relocate in a given instance. An enforce operation that reaches the specified maximum can be restarted from the point at which the operation ended due to this limit.
-T { class. | .[ class. ] } ...
  Specifies the placement classes that contain files for the fsppadm command to sweep and relocate selectively. The -T option is applicable only if the policy uses the Prefer criteria for ACCESSTEMP or IOTEMP. If you specify the enforce keyword, you can specify a period (.) to indicate an empty list of tiers. In this case, fsppadm does not enforce the placement policy and instead creates a tier-to-file mapping. This mapping is updated as relocations, deletions, and creations happen over a period of time, and is used to identify quickly the files in a given tier.
For best results, specify the -T option in conjunction with the -C option for solid state disk (SSD) tiers. Specifying both the -T option and -C option causes the fsppadm command to first evacuate any cold files to create room in SSD to accommodate any active files that will be moved into the SSD tier via the -C option. Specifying -C in conjunction with -T confines the scope of the scan, which consumes less time and resources, and thus allows frequent scans to meet the dynamic needs of data placement.
-t hours Specifies the maximum number of hours that an enforce operation can run. An enforce operation that times out can be restarted from the point at which the process was ended due to the time limit.
-w Suppresses headings.

FILES

/opt/VRTSvxfs/etc/placement_policy.dtd
  File placement policy DTD

EXAMPLES

To assign the placement policy iotemp.xml to the mounted VxFS file system /mount1:

# fsppadm assign /mount1 /tmp/iotemp.xml

To assign the placement policy iotemp.xml to all mounted VxFS file systems:


# fsppadm assign /tmp/iotemp.xml

To remove the active placement policy previously assigned to /mount1:


# fsppadm unassign /mount1

To remove the active placement policy from all mounted VxFS file systems:


# fsppadm unassign

To analyze the space impact if the enforce operation was run on /mount1:


# fsppadm analyze /mount1

To analyze the impact if the enforce operation were run on /mount1 and build the IOTEMP database if necessary:


# fsppadm analyze -i /mount1

To generate a list of affected files, which provides details about where the files currently reside, to where the files would be relocated, and which rule in the placement policy applies to the files:


# fsppadm query /mount1/dir1/dir2 /different_mount /mount1/dir3

To generate a list of affected files, which provides details about where the files currently reside, to where the files would be relocated, which rule in the placement policy applies to the files, and the reasons for taking such action:


# fsppadm query -a /mount1/dir1/dir2 /different_mount /mount1/dir3

In the above query operations, specify the -i option if the active placement policy on those file sytems use IOTEMP and the enforce operation has not been run recently.

To enforce the policy and generate a report:


# fsppadm enforce -r /tmp/report /mount1

To generate a report with additional details, such as IOTEMP information:


# fsppadm enforce -a -r /tmp/report /mount1

To generate a list of files and target classes to where the files would be relocated, of which the list can be piped to another fsppadm enforce operation directly:


# fsppadm query -l /mount1/dir1

The following list indicates that /mount1/dir1 has three files to which the placement policy applies. This list indicates that file1 is a candidate to be relocated to tier3 and tier4, while file2 is a candidate to be relocated to tier2. file3 is a candidate to be removed. The files to be removed will have a special target placement class of "." (a period). The period indicates that the enforce operation will delete the file. The output of the previous example could be as follows:


/mount1/dir1/file1 tier3 tier4 /mount1/dir1/file2 tier2 /mount1/dir1/file3 .

The above output can be piped to an enforce operation to move file1 to tier3 or to tier4 if moving to tier3 is not possible, to move file2 to tier2, and to delete file3:


# fsppadm query -l /mount1/dir1 | fsppadm enforce -c . /mount1

The same result as above can be achieved more directly with the following command:


# fsppadm enforce /mount1/dir1

However, if the same list is piped to an enforce operation that specifies -c .tier4.tier1, the operation will move file1 as well as file2 to tier4 if possible, or to tier1 if moving to tier4 is not possible:


# fsppadm query -l /mount1/dir1 | fsppadm enforce \ -c .tier4.tier1 /mount1

As a side effect, file3 will also be moved to tier4 if possible, or to tier1 if moving to tier4 is not possible. Thus, if alternate non-null target placement classes are specified via the -c option, fsppadm cannot be used to delete files.

If the target classes for relocation are specified with the -c option as well as on each input line following the file path, the target classes specified on each line of the input are ignored. As such, you need not specify file-specific targets on each line of the input if the target classes are specified with the -c option.

As the above example specifies placement classes with the -c option, any files that are to be deleted are instead relocated. The above list indicates that file3 is to be deleted since it has a target placement class of ".". file3 will instead be relocated to tier4 if possible, or to tier1 if moving to tier4 is not possible as specified by the argument for -c.

The file list could also be constructed manually, similar to the following list:


/mount1/dir1/file1 /mount1/dir2/file2

To validate the placement policy policy.xml against the mounted VxFS file system /mount1:


# fsppadm validate /mount1 /tmp/policy.xml

To validate the placement policy policy.xml against all mounted VxFS file systems:


# fsppadm validate /tmp/policy.xml

To read the FCL file to identify the files that were active during the period when the policy used ACCESSTEMP or IOTEMP, and enforce the assigned placement policy on only those files:


# fsppadm enforce -C /mount1

To process and relocate all of the files in tier1 according to the current placement policy, instead of processing the entire file system:


# fsppadm enforce -T tier1 /mount1

To move a total of 32 MB in the file test.dbf from the offset 64 MB through 96 MB from its existing tier to tier2:


# cat /var/tmp/list test.dbf 67108864 100663296 tier2 # fsppadm subfilemove -f /var/tmp/list /mount1

SEE ALSO

fcladm(1M), vxadm(1M), vxassist(1M), vxtunefs(1M), vxvset(1M)

Storage Foundation Administrator’s Guide


VxFS 7.4.1 fsppadm(1M)