iprutils/iprconfig.8

.\" (C) Copyright 2000, 2009
.\" International Business Machines Corporation and others.
.\" All Rights Reserved. This program and the accompanying
.\" materials are made available under the terms of the
.\" Common Public License v1.0 which accompanies this distribution.
.TH IPRCONFIG 8 "August 2009"
.SH NAME
iprconfig \- IBM Power RAID storage adapter configuration/recovery utility
.SH SYNOPSIS
.BI "iprconfig [-e editor] [-k dir] [-c command]"
.sp
.BI "iprconfig --version --debug --force"
.SH DESCRIPTION
.B iprconfig
is used to configure IBM Power RAID storage adapters, display information
about them, and to perform adapter and disk unit recovery. 
The menu options are: 
.PP
.B 1. Display hardware status.
.br
This option can be used to display various information regarding
the IBM Power RAID adapters attached to the system and the disk 
units controlled by them. For each adapter and disk unit, their 
/dev name, physical location, description, vendor/product ID, and
hardware status will be available. Beside each resource is an OPT 
field. By entering a 1 beside any resource, detailed information 
about that resource can be obtained. For an adapter resource, this 
will display the adapter firmware version and the physical location 
amongst other things.
.PP
.B 2. Work with Disk Arrays
.br
This option will present a second menu containing disk array related
commands. 
.PP
.B Display disk array status
is used to display the status of disk arrays on the system. 
.PP
.B Create a disk array
is used to create a disk array.
.PP
.B Delete a disk array
is used to delete disk arrays. Selecting this option will provide you 
with a list of disk arrays which can be deleted.
.PP
.B Add a device to a disk array
is used to include devices of similar capacity into an existing disk 
array. This function is currently only supported for RAID 5 and RAID 6 
disk arrays.
.PP
.B Format device for advanced function
is used to format disks to 522 bytes/sector so that they may be used in
a disk array. Only disks which are not formatted for advanced function
or are formatted for advanced function but are not known to be zeroed will
be available for selection for this function.
.PP
.B Format device for JBOD function (512)
is used to format disks to 512 bytes/sector so that they may be used 
as standalone disks. Only disks which are not formatted for JBOD function
or are formatted for JBOD function and are in the Format Required state
will be available for this function.
.PP
.B Work with hot spares
is used to create a hot spare which designates a device as a dedicated hot
spare.  It is also used to delete a hot spare which unconfigures a previously
configured hot spare.
.\".B Create a hot spare
.\"is used to designate a device as a dedicated hot spare.
.\".PP
.\".B Delete a hot spare
.\"is used to unconfigure a previously configured hot spare.
.PP
.B Work with asymmetric access
is used to select which path of a disk array will be the primary path in a dual
controller environment.  Asymmetric Access must be enabled on the adapter first.
Not all adapters support asymmetric access and adapters that do provide support
may require updated microcode.
.PP
.B Force RAID Consistency Check
is used to force a consistency check on a RAID array. All ipr adapters 
continually perform background consistency checking when idle. This 
option can be used to force a consistency check to be performed.
.PP
.B Migrate disk array protection
is used to change the RAID protection level for an array to another supported
level.  In some cases, this will require adding more disks to the array.  In
other cases, disks will be freed.
.PP
.B 3. Work with disk unit recovery
is used to perform the following disk unit recovery actions:
.PP
.B Concurrent add device
is used to concurrently add a new disk to a running system. This feature
is only supported with SES (SCSI Enclosure Services) packaging.
.PP
.B Concurrent remove device
is used to concurrently remove a disk from a running system.
This feature is only supported with SES (SCSI Enclosure Services) packaging.
.PP
.B Initialize and format disk unit
is used to issue a SCSI format command to attached devices. A format
unit command has special meaning to the adapter and is used as a service
action for certain error conditions. Formatting a disk unit will lose
all data on that drive. If the disk is attached to an ipr adapter that
does not support RAID, the drive will be formatted to 512 bytes/sector.
If the disk is attached to an ipr RAID adapter, the block size will not
be changed. To change the block size, use the format menu options under
the disk arrays menu.
.PP
.B Reclaim IOA cache storage
is used to repair cache error conditions. 
.B ATTENTION:
Use this option with care. This is used to discard data from the cache
and may result in data loss. This option is designed to be used by
authorized IBM hardware customer engineers.
.PP
.B Rebuild disk unit data
is generally used following concurrent maintenance. Select this option after
a failing array member device has been replaced to reconstruct the device as 
an active array member.
.PP
.B Work with resources containing cache battery packs
is used to display information regarding rechargeable cache battery packs 
and to force rechargeable cache battery packs into an error state so that
they can be replaced prior to failure. 
.B ATTENTION:
Once an error has been forced on a rechargeable cache battery pack write
caching will be disabled until the battery pack is replaced.
.PP
.B 4. Work with SCSI bus configuration
is used to change configurable SCSI bus attributes, such as maximum SCSI
bus speed, SCSI initiator ID, etc.
.PP
.B 5. Work with driver configuration
is used to change driver configurable attributes, such as log_level.
.PP
.B 6. Work with disk configuration
is used to change configurable disk attributes, such as queue depth.
.PP
.B 7. Work with adapter configuration
is used to change configurable adapter attributes, such as dual adapter
settings.  Refer to the following command line options: primary, secondary,
query-ha-mode, set-ha-mode, set-ioa-asymmetric-access and
set-array-asymmetric-access for more information regarding these settings.
.PP
.B 8. Download microcode
is used to download microcode to ipr adapters and attached SCSI disks.
.PP
.B 9. Analyze Log
is an option available to analyze /var/log/messages* files. By default
it will use vi as the editor to open the concatenated error log files.
This can be changed by using option 6 on the
.B Kernel Messages Log 
menu. Selecting
option 1 on the Kernel Messages Log menu will display only the most recent 
errors logged by the ipr device driver and may be useful to filter out 
some of the clutter. Option 2 will display all recorded errors logged by the
ipr device driver. Option 3 will display all kernel messages. Option 4 will
display errors logged by the iprconfig utility. This may be useful for
debugging problems. Option 5 can be used to change where the tool looks
to find the kernel messages files. The default is to look in /var/log.
.SH OPTIONS
.TP
.B \-e editor
Default editor for viewing error logs. The default editor is vi, but can be 
changed with this parameter.
.TP
.B -k directory
Kernel messages root directory. Root directory to look for kernel messages.
Default is /var/log.
.TP
.B -c command
Command line, non-interactive commands. Currently supported commands include:
.RS
.TP
.B show-config
.br
Show ipr configuration.
.TP
.B show-alt-config
.br
Show alternate ipr configuration information.
.TP
.B show-ioas
.br
Show all ipr adapters.
.TP
.B show-arrays
.br
Show all ipr arrays.
.TP
.B show-battery-info [IOA]
.br
Show cache battery information for specified IOA. Example:
.br
.B iprconfig -c show-battery-info sg5
.TP
.B show-details [device]
.br
Show device details for specified device. Example:
.br
.B iprconfig -c show-details sda
.TP
.B show-hot-spares
.br
Show all configured hot spares.
.TP
.B show-af-disks
.br
Show disks formatted for Advanced Function that are not
configured in an array or as a hot spare.
.TP
.B show-all-af-disks
.br
Show all disks formatted for Advanced Function
.TP
.B show-jbod-disks
.br
Show all disks formatted for JBOD Function.
.TP
.B status [device]
.br
Show the status of the specified device. This is the same status as which shows
up in the last column of the Display hardware status menu. Can specify either a 
/dev/sdX name or a /dev/sgX name. Example:
.br
.B iprconfig -c status /dev/sda
.br
.TP
.B alt-status [device]
.br
Show the status of the specified device. This is the same status as above with
the exception of when a long running command is executing to the device, in
which case the percent complete for the long running command is printed.
.br
.TP
.B query-raid-create [IOA]
.br
Show all devices attached to the specified IOA that are candidates for being
used in a RAID array. Example:
.br
.B iprconfig -c query-raid-create sg5
.TP
.B query-raid-delete [IOA]
.br
Show all RAID arrays attached to the specified IOA that can be deleted.
.br
.B iprconfig -c query-raid-delete sg5
.TP
.B query-hot-spare-create [IOA]
.br
Show all devices attached to the specified IOA that are candidates for being
hot spares.
.TP
.B query-hot-spare-delete [IOA]
.br
Show all hot spares attached to the specified IOA that can be deleted.
.TP
.B query-raid-consistency-check
.br
Show all RAID arrays that are candidates for a RAID consistency check.
.TP
.B query-format-for-jbod
.br
Show all disks that can be reformatted for JBOD function.
.TP
.B query-reclaim
.br
Show all IOAs that may need a reclaim cache storage.
.TP
.B query-arrays-raid-include
.br
Show all RAID arrays that can have disks included in them to increase
their capacity.
.TP
.B query-devices-raid-include [array]
.br
Show all disks that can be added to the specified array to increase its
capacity.
.TP
.B query-supported-raid-levels [IOA]
.br
Show all RAID levels supported by the specified adapter.
.TP
.B query-include-allowed [IOA] [raid level]
.br
Some RAID levels allow for adding additional disks to existing disk
arrays to increase their capacity. Prints "yes" to stdout if the specified
RAID level supports this function, else prints "no".
.TP
.B query-max-devices-in-array [IOA] [raid level]
.br
Print the maximum number of devices allowed in a RAID array of the specified
RAID level for the specified RAID adapter.
.TP
.B query-min-devices-in-array [IOA] [raid level]
.br
Print the minimum number of devices allowed in a RAID array of the specified
RAID level for the specified RAID adapter.
.TP
.B query-min-mult-in-array [IOA] [raid level]
.br
Print the minimum multiple of devices required in a RAID array of the specified
RAID level for the specified RAID adapter.
.TP
.B query-supp-stripe-sizes [IOA] [raid level]
.br
Print all supported stripe sizes supported for RAID arrays of the specified
RAID level on the specified RAID adapter. Stripe sizes are printed in
units of KB.
.TP
.B query-recommended-stripe-size [IOA] [raid level]
.br
Print the default/recommended stripe size for RAID arrays of the specified
RAID level on the specified RAID adapter. Stripe size is in units of KB.
.TP
.B query-recovery-format
.br
Show all disks that can be formatted for error recovery purposes.
.TP
.B query-raid-rebuild
.br
Show all disks in RAID arrays that can be rebuilt.
.TP
.B query-format-for-raid
.br
Show all disks that can be formatted such that they can be used
in a RAID array or as a hot spare.
.TP
.B query-ucode-level [device]
.br
Show the microcode level that is currently loaded on the specified device.
Note: The device specified may be the sg device associated with an IOA,
in which case the IOA's microcode level will be shown.
.TP
.B query-format-timeout [device]
.br
Show the current format timeout to be used when formatting the specified disk.
This value is only applicable when the device is currently in Advanced Function
format.
.TP
.B query-qdepth [device]
.br
Show the queue depth currently being used for the specified disk.
.TP
.B query-tcq-enable [device]
.br
Print 1 to stdout if tagged queuing is enabled for the specified device,
else print 0 to stdout.
.TP
.B query-log-level [IOA]
.br
Print the current log level being used for the specified IOA. Can be a number
from 0 to n.
.TP
.B query-add-device
.br
Show all empty disk slots that can have a disk concurrently added.
.TP
.B query-remove-device
.br
Show all disk slots which are either empty or have disks in them which can
be concurrently removed from the running system.
.TP
.B query-initiator-id [IOA] [busno]
.br
Show the current SCSI initiator ID used by the IOA for the specified SCSI bus.
.TP
.B query-bus-speed [IOA] [busno]
.br
Show the current maximum SCSI bus speed allowed on the specified SCSI bus.
.TP
.B query-bus-width [IOA] [busno]
.br
Show the current SCSI bus width in units of bits for the specified SCSI bus.
.TP
.B query-path-status [IOA]
.br
Show the current dual path state for the SAS devices attached specified IOA.
.TP
.B query-path-details [device]
.br
Show the current dual path details for the specified SAS device.
.TP
.B query-arrays-raid-migrate
.br
Show the arrays that can be migrated to a different protection level.
.TP
.B query-devices-raid-migrate [array]
.br
Show the AF disks that are candidates to be used in a migration for a given
array.
.TP
.B query-raid-levels-raid-migrate [array]
.br
Show the protection levels to which the given array can be migrated.
.TP
.B query-stripe-sizes-raid-migrate [array] [raid level]
.br
Given an array and a protection level, show the valid stripe sizes to which
the array can be migrated.
.TP
.B query-devices-min-max-raid-migrate [array] [raid level]
.br
Show the number of devices that will be removed for a migration to a protection
level that requires fewer devices.  Or, show the minmum number of devices
required, the maximum number of devices allowed and the multiple of the number
of devices required for a migration that requires more devices.
.TP
.B query-ioas-asymmetric-access
.br
Show the IOAs that support asymmetric access.
.TP
.B query-arrays-asymmetric-access
.br
Show the disk arrays that are candidates for setting their asymmetric access
mode to Optimized or Non-Optimized.
.TP
.B query-ioa-asymmetric-access-mode [IOA]
.br
Show the current asymmetric access mode for the given IOA.
.TP
.B query-array-asymmetric-access-mode [array]
.br
Show the current asymmetric access mode for the given disk array.
.TP
.B query-ioa-caching [IOA]
.br
Show whether or not the user requested caching mode for the given IOA is set to
default or disabled.
.TP
.B raid-create [-r raid_level] [-s stripe_size_in_kb] [devices...]
Create a RAID array. RAID level can be any supported RAID level for the given
adapter, such as 0, 10, 5, 6. Currently supported stripe sizes in kb 
include 16, 64, and 256. If raid_level is not specified, it will default to
RAID 5. If stripe size is not specified, it will default to the recommended
stripe size for the selected RAID level. Devices are specified with their full
name, either the /dev/sd name or the /dev/sg name is acceptable. Example array
creation:
.br
.B iprconfig -c raid-create -r 5 -s 64 /dev/sda /dev/sdb /dev/sdc
.br
This would create a RAID 5 array with a 64k stripe size using the specified
devices.
.TP
.B raid-delete [RAID device]
Delete the specified RAID array. Specify either the /dev/sd name or the /dev/sg
name. Only 1 array can be deleted with a single command. Example:
.br
.B iprconfig -c raid-delete /dev/sda
.br
This would delete the disk array represented by /dev/sda
.TP
.B raid-include [array] [disk] ... [disk]
.br
Add the specified devices to the specified disk array to increase its capacity.
Example:
.br
.B iprconfig -c raid-include sda sg6 sg7
.TP
.B raid-migrate -r raid_level [-s stripe_size_in_kb] array [disk] ... [disk]
.br
Migrate an existing RAID array to a new RAID protection level.  Optionally,
a new stripe size can be given.  In some cases one or more new disks must be
added for the migration to succeed.
Example:
.br
.B iprconfig -c raid-migrate -r 10 -s 64 sda sg5 sg6
.TP
.B format-for-raid [disk] ... [disk]
.br
Format the specified disks for Advanced Function so they can be used in
a RAID array or as a hot spare.
.TP
.B format-for-jbod [disk] ... [disk]
.br
Format the specified disks for JBOD Function so they can be used as
standalone disks.
.TP
.B recovery-format [disk] ... [disk]
.br
Format the specified disks as directed by the reference guide for error
recovery purposes.
.TP
.B hot-spare-create [disk]
.br
Create a hot spare using the specified Advanced Function disk.
.TP
.B hot-spare-delete [disk]
.br
Delete the specified hot spare.
.TP
.B disrupt-device [disk]
.br
Force the specified Advanced Function device failed.
.TP
.B reclaim-cache [IOA]
.br
Reclaim the specified IOA's write cache.
.B ATTENTION:
Use this option with care. This is used to discard data from the cache
and may result in data loss. This option is designed to be used by
authorized IBM hardware customer engineers.
.TP
.B reclaim-unknown-cache [IOA]
.br
Reclaim the specified IOA's write cache and allow unknown data loss.
.B ATTENTION:
Use this option with care. This is used to discard data from the cache
and WILL result in data loss. This option is designed to be used by
authorized IBM hardware customer engineers.
.TP
.B raid-consistency-check [array]
.br
Force a full RAID consistency check on the specified array. This command
will return before the RAID consistency check has completed. Use the 
.B status
command to check the status of the command.
.TP
.B raid-rebuild [disk]
.br
Following a disk replacement for a failed disk in a RAID array, use
this command to rebuild the failed disk's data onto the new disk and
return the disk array to the 
.B Active
state.
.TP
.B update-ucode [device] [microcode file]
.br
Update the microcode on the specified device (IOA or disk) with
the specified microcode file. 
.B ATTENTION:
Limited checking of the microcode image is done. Make sure the
specified microcode file is the correct file for the specified device.
.TP
.B set-format-timeout [disk] [timeout in hours]
.br
Set the format timeout to be used when formatting the specified disk.
.TP
.B set-qdepth [device] [queue depth]
.br
Set the queue depth for the specified device or disk array.
.TP
.B set-tcq-enable [device] [0 = disable, 1 = enable]
.br
Enable/disable tagged command queueing for the specified device.
.TP
.B set-log-level [IOA] [log level]
.br
Set the error logging verbosity to use for the specified IOA.
Default is 2.
.TP
.B identify-disk [disk] [0 = turn off identify LED, 1 = turn on identify LED]
.br
Turn on/off the disk identify LED for the specified disk. This function
may or may not be available depending on the hardware packaging.
.TP
.B identify-slot [location] [0 = turn off identify LED, 1 = turn on identify LED]
.br
Turn on/off the disk identify LED for the specified location. This function
may or may not be available depending on the hardware packaging. Example:
.br
.B iprconfig -c identify-slot 0000:d8:01.0/0:1:1: 1
.TP
.B remove-disk [disk] [0 = turn off identify LED, 1 = turn on identify LED]
.br
Turn on/off the disk remove identify LED for the specified device. When 1
is specified as the second argument, the specified disk is set to the remove
state. When in this state, the disk may be removed. Once the disk has been
physically removed, iprconfig must be invoked again with the second argument
set to 0. This turns off the slot identifier light and logically removes
the disk from the host operating system.
.TP
.B remove-slot [location] [0 = turn off identify LED, 1 = turn on identify LED]
.br
Turn on/off the disk remove identify LED for the specified location. When 1
is specified as the second argument, the specified location is set to the remove
state. When in this state, the disk may be removed. Once the disk has been
physically removed, iprconfig must be invoked again with the second argument
set to 0. This turns off the slot identifier light and logically removes
the disk from the host operating system. Example:
.br
.B iprconfig -c remove-slot 0000:d8:01.0/0:1:1: 1
.TP
.B add-slot [location] [0 = turn off identify LED, 1 = turn on identify LED]
.br
Turn on/off the disk insert identify LED for the specified location. When 1
is specified as the second argument, the specified location is set to the insert
state. When in this state, the disk may be inserted. Once the disk has been
physically inserted, iprconfig must be invoked again with the second argument
set to 0. This turns off the slot identifier light and logically adds
the disk to the host operating system. Example:
.br
.B iprconfig -c add-slot 0000:d8:01.0/0:1:1: 1
.TP
.B set-initiator-id [IOA] [busno] [initiator id]
.br
Set the IOA's SCSI initiator ID for the specified bus. Must be a value
between 0 and 7 and must not conflict with any other device on the SCSI bus.
.TP
.B set-bus-speed [IOA] [busno] [speed in MB/sec]
.br
Set the maximum SCSI bus speed allowed on the specified SCSI bus.
.TP
.B set-bus-width [IOA] [busno] [bus width in # bits]
.br
Set the SCSI bus width to use for the specified SCSI bus. Example:
.br
.B iprconfig -c set-bus-width sg5 0 16
.TP
.B primary [IOA]
.br
Set the adapter as the 
.B preferred primary 
adapter. This is used in dual initiator RAID configurations to indicate
which adapter should be the 
.B primary
adapter. The 
.B primary 
adapter should be the adapter receiving the majority of the I/O. Example:
.br
.B iprconfig -c primary sg5
.TP
.B secondary [IOA]
.br
Set the adapter to indicate it is not the  
.B preferred primary 
adapter. See the notes for the 
.B preferred primary
for additional information. Example:
.br
.B iprconfig -c secondary sg5
.TP
.B set-all-primary
.br
Set all attached ipr adapters as the 
.B preferred primary 
adapter. This can be used when running a dual initiator RAID HA configuration.
This command can be run on the 
.B primary 
system to quickly enable the 
.B preferred primary 
mode for all attached adapters. Refer to /etc/ha.d/resource.d/iprha for
an example of how this might be used. Example:
.br
.B iprconfig -c set-all-primary
.TP
.B set-all-secondary
.br
Set all attached ipr adapters to indicate they are not the 
.B preferred primary 
adapter. Example:
.br
.B iprconfig -c set-all-secondary
.TP
.B query-ha-mode [IOA]
.br
When an adapter is configured in a highly available dual adapter configuration,
it may be able to be configured in one of two ways. The default mode is
.B Normal. 
This mode is used for all SCSI adapters and many SAS adapters. 
Some SAS adapters also support a
.B JBOD 
dual adapter configuration. This mode is to be used when the dual adapter
configuration is to consist of JBOD disks rather than RAID arrays. If the adapter
is
.B NOT 
going to be used in a dual adapter configuration, this mode 
.B MUST 
be set to 
.B Normal.
Example:
.br
.B iprconfig -c query-ha-mode sg5
.TP
.B set-ha-mode [IOA] [Normal | RAID]
Used to set the high-availability mode of the adapter. Refer to the
.B query-ha-mode 
command for more information regarding these settings. Example:
.br
.B iprconfig -c set-ha-mode sg5 Normal
.TP
.B set-array-asymmetric-access-mode [array] [Optimized | Non-Optimized]
Used to set the asymmetric access mode of the disk array.  Example:
.br
.B iprconfig -c set-array-asymmetric-access-mode sda Optimized
.TP
.B set-ioa-asymmetric-access-mode [IOA] [Enabled | Disabled]
Used to set the asymmetric access mode of the IOA.
.br
Example:
.br
.B iprconfig -c set-ioa-asymmetric-access-mode sg5 Enabled
.TP
.B set-ioa-caching [IOA] [Default | Disabled]
Used to set the requested caching mode of the IOA.
.br
Example:
.br
.B iprconfig -c set-ioa-caching sg5 Disabled
.TP
.B get-live-dump [IOA]
Dump the IOA's implementation unique critical information. The dump data
will be saved in the /var/log/ directory with the pattern
ipr-CCIN-PCI_ADDRESS-dump-TIMESTAMP.
.br
Example:
.br
.B iprconfig -c get-live-dump sg5
.RE
.TP
.B \-\-version
Print version number of 
.B iprconfig
.TP
.B \-\-debug
Enable additional error logging. Enabling this will result in additional 
errors logging to /var/log/messages.
.TP
.B \-\-force
Disable safety checks. Use this to disable safety checks in iprconfig. 
This will allow you to format devices that are not at the appropriate 
code levels. Only use this option if you really know what you are doing. 
.SH AUTHOR
Brian King <brking@us.ibm.com>
.SH NOTES
.TP
.B Notes on using under iSeries 5250 telnet
.PP
Only use this utility across 5250 telnet when there are no other options
available to you. Since there may be occasions when 5250 telnet is your only
option to access your iSeries Linux console, every attempt has been made to 
make this utility usable under 5250 telnet. By following a few guidelines,
you can make your 5250 telnet experience more productive and much less
frustrating.
.PP
1. First of all, it will be helpful to know how the keys are mapped under
5250 telnet. From the 5250 telnet window, hit ESC. This will get you to the 
.B Send TELNET Control Functions
menu. Take option 6 to display the keyboard map. Take note of how TAB, ESC, 
CTLC, and SENDWOCR are bound. They will be useful in the future.
.PP
2. When selecting menu options, enter the menu number, followed by the
enter key, same as usual.
.PP
3. When typing single character commands (eg. r=Refresh), type the single
character followed by the SENDWOCR key (F11 by default).
.PP
4. When on a device/array/IOA selection screen (eg. Display Disk Unit Details),
do NOT use the arrow keys to navigate. Instead use the TAB key (F7 by default)
to navigate these screens.
.PP
5. Beware of the backspace and delete keys. As a rule do NOT use them. 
.PP
6. When editing the root kernel message log directory or the default editor,
you may use the arrow keys, but not the backspace and delete keys. Use the 
space bar to remove already typed characters.