mirscan Command

Purpose

Search for and correct physical partitions that are stale or unable to perform I/O operations.

Syntax

mirscan -v vgname | -l lvname | -p pvname | -r reverse_pvname [ -a ] [ -o ] [ -q nblks ] [ -c lvcopy ] [ -s strictness ] [ -u upperbound ]

Description

The mirscan command examines each allocated partition on the specified device. A report is generated that lists whether the partition is stale or fresh, and lists whether it is capable of performing I/O operations. The LVM device driver is queried to determine whether the partition is stale or fresh. Regardless of whether the partition is stale or fresh, it is read to determine whether it is capable of performing I/O operations. By default the entire partition is read, but if the -q flag is specified, the nblks value determines how much of the partition will be read. If the -a flag is not specified, the report is printed and execution ends after all partitions are read.

If the -a flag is used, corrective action is taken after all the partitions have been examined. Stale partitions will be synced. If a partition is not capable of performing I/O, mirscan attempts to trigger bad block relocation or hardware relocation with a forced sync operation, which should write a good copy of the data to the block that is incapable of performing I/O operations. If the partition is still unreadable, the mirscan command attempts to migrate that partition to a new location. By default, the new location that is selected adheres to the strictness and upperbound policies for the logical volume that contains the partition. Using the -s flag causes the strictness value specified on the command line to override the natural strictness value of the logical volume that contains the partition. Similarly, using the -u flag causes the upperbound value specified on the command line to override the natural upperbound value of the logical volume that contains the partition.

The mirscan command prints (to standard output) a status report for the partitions scanned. If the -a flag is specified, the mirscan command also prints (to standard output) a status report containing each corrective action that is taken. If the -o flag is specified, the report will be in colon-separated output format. If the -o flag is not specified, the default behavior is to print the report in human-readable format.

Partitions on nonmirrored logical volumes are scanned and included in all reports, but no sync or migration operation is possible for such partitions. Partitions on striped logical volumes can be synced but cannot be migrated. Partitions on paging devices cannot be migrated, because this would result in a system hang if the mirscan process were to be paged out. Partitions on the boot logical volume cannot be migrated. Partitions on an active firmware-assisted dump logical volume cannot be migrated. An informative error message is generated in the corrective action report for each of the preceding cases.

By default, the mirscan command does not take any lock on the volume group. This should allow the mirscan command to run in the background without interfering with other lvm commands. If the -a flag is specified and there are partitions that need to be migrated, the volume group is locked, all the migration operations are performed, and the volume group lock is released. Therefore, if the -a flag is specified, the impact to other lvm commands is minimized because the volume group is only locked during the migration operations, which are all performed at once just before the end of execution.

Flags

Item	Description
-a	Specifies that corrective action should be taken.
-c lvcopy	Identifies a particular copy of the logical volume. The -c flag can only be specified in conjunction with the -l flag. The -c flag is ignored if it is used in conjunction with the -p, -r, or -v flag.
-l lvname	Specifies the logical volume to be scanned.
-o	Specifies colon-separated output format should be used for the report. If this option is not used, the default behavior is to print a report in human-readable format.
-p pvname	Specifies the physical volume to be scanned.
-q nblks	Specifies which portions of the partition should be read. If the nblks value is `0`, only the first, middle, and last 512 bytes of each partition are read to determine whether the partition is capable of performing I/O operations. A nonzero nblks value indicates that only the first nblks 512 byte blocks of each partition should be read to determine whether the partition is capable of performing I/O operations. If the -q flag is not specified, the entire partition is read.
-r reverse_pvname	Specifies that any partitions in the volume group should be scanned if they do not reside on pvname but they do have a mirror copy on pvname. This could be run prior to removing pvname from the system, in case pvname somehow has the last good copy of a partition.
-s strictness (`y`, `n`, `s`)	Specifies a strictness value that should override the natural strictness value. Legal values are `y`, `n`, and `s`, where `y` enables strictness, `n` disables strictness, and `s` enables "superstrictness." By default, when mirscan has to perform a migration operation on a partition it will adhere to the natural strictness value of the logical volume that contains that partition. If the -s flag is used, the override strictness value will be used. If the -s flag is used in conjunction with the -p, -r, or -v flags, the override strictness value could override the natural strictness of multiple logical volumes.
-u upperbound	Specifies an upperbound value that should override the natural upperbound value. The upperbound value should be between `1` and the total number of physical volumes in the volume group. By default, when mirscan has to perform a migration operation on a partition it will adhere to the natural upperbound value of the logical volume that contains the partition. If the -u flag is used, the override upperbound value will be used. If the -u flag is used in conjunction with the -p, -r, or -v flags, the override upperbound value could override the natural upperbound value of multiple logical volumes.
-v vgname	Specifies the volume group to be scanned.

Exit Status

An exit code of 0 indicates that mirscan was able to complete its execution and was able to correct any error conditions that were encountered along the way. An exit code of 1 indicates that mirscan was able to complete its execution, but it was unable to correct every error that it found; further corrective action is still required. For example, if corrective actions would be required but the -a flag was not specified, an exit code of 1 is used. An exit code of 2 indicates that mirscan was unable to complete its execution. For example, if the target device is not listed in the ODM, an exit code of 2 is used.

Item	Description

Security

Attention RBAC users and Trusted AIX users: This command can perform privileged operations. Only privileged users can run privileged operations. For more information about authorizations and privileges, see Privileged Command Database in AIX® Version 7.1 Security. For a list of privileges and the authorizations associated with this command, see the lssecattr command or the getcmdattr subcommand.

Examples

To scan logical volume lv33, report the status of each partition, and have every block of each partition read to determine whether it is capable of performing I/O operations, type:
```
mirscan -l lv33
```
To scan logical volume lv33, report the status of each partition, and have only the first two blocks of each partition read to determine whether it is capable of performing I/O operations, type:
```
mirscan -l lv33 -q 2
```
To scan logical volume lv33, report the status of each partition, sync any stale partitions found, and migrate any partitions that are not capable of performing I/O operations, type:
```
mirscan -l lv33 -a
```
To scan every allocated logical partition on hdisk4 and report the status of each partition, type:
```
mirscan -p hdisk4
```
To find every allocated partition in the volume group that resides on hdisk4, and scan and report the status of all partitions that do not reside on hdisk4 but are mirror copies of a partition that resides on hdisk4, type:
```
mirscan -r hdisk4
```
This would be useful to run before removing hdisk4 from the system.
To scan volume group vg05, report the status of each allocated partition, and have the first, middle, and last 512 bytes of each partition read to determine whether that partition is capable of performing I/O operations, type:
```
mirscan -v vg05 -q 0
```

Restrictions

Unmirrored partitions and striped partitions are not eligible for migration. Partitions on paging devices will not be migrated by mirror scan because it would result in a system hang if the mirscan process happened to get paged out. Partitions from the boot logical volume cannot be migrated.

Location

/usr/sbin/mirscan

Standard Output

Each line in the report corresponds to an operation on a physical partition. There are 4 types of operation that mirscan can perform. A scan operation determines whether the partition is synced and whether it is capable of performing I/O operations. A resync operation is a corrective action performed on stale partitions that attempts to return them to synced state. A force resync operation is a corrective action performed on partitions that are not capable of performing I/O operations, in an attempt to trigger bad block relocation or hardware relocation. At the end of the force resync operation, the partition is read again to determine whether it is capable of performing I/O operations. A migration operation is a corrective action performed on partitions that are not capable of performing I/O operations, in an attempt to move the data to a physical location that is capable of performing I/O.

The default format for the reports contains the following column headings. If the -o flag is specified, no header is displayed and the output report is printed in colon-separated output format. The columns and their meanings are as follows:

Item	Description
OP	The valid values for this field are s, r, f, and m. A value of s signifies a scan operation. A value of r signifies a resync operation. A value of f signifies a force resync operation, which is performed in an effort to trigger bad block relocation or hardware relocation. A value of m signifies a migration operation.
STATUS	The valid values for this field are SUCCESS or FAILURE. For a scan operation, FAILURE is indicated if the partition being scanned is stale or incapable of performing I/O. For a resync operation, FAILURE is indicated if the partition was not synchronized. For a force resync operation, FAILURE is indicated if the partition is still incapable of performing I/O operations. For a migration operation, FAILURE is indicated if the migration operation was not completed.
PVNAME	Identifies the name of the physical volume where the partition being operated on resides. For a migration operation, PVNAME refers to the source physical volume and TARGETPV refers to the destination physical volume.
PP	Identifies the physical partition number of the partition being operated on. The first partition on a particular physical volume has a PP value of `1`, not `0`.
SYNC	The valid values for this field are `synced` or `stale`. The value indicated refers to the state of the partition after the operation has been completed. For example, if a resync operation succeeds, a value of `synced` will be displayed.
IOFAIL	The valid values for this field are `yes` or `no`. The value indicated refers to the state of the partition after the operation has been completed. For example, if a migration operation succeeds then a value of `no` is displayed to indicate that the partition no longer has a problem performing I/O operations.
LVNAME	Identifies the name of the logical volume where the partition being operated on resides.
LP	Identifies the logical partition number of the partition being operated on. The first partition on a particular logical volume has an LP value of `1`, not `0`.
CP	Identifies the logical copy number of the partition being operated on. The first logical copy of a logical volume has a CP value of `1`, not `0`.
TARGETPV	Identifies the name of the physical volume that was used as the target for a migration operation. For any type of operation other than a migration operation, this field is left blank.
TARGETPP	Identifies the physical partition number of the partition that was used as the target for a migration operation. For any type of operation other than a migration operation, this field is left blank. The first partition on a particular physical volume has a TARGETPP value of `1`, not `0`.