# @(#)10 1.3.1.1 src/ssaraid/usr/lpp/ssaraid/bin/ssaraid.README, ssaraid, ssa42G 9/17/97 04:53:11 ######################################################################### # # # COMPONENT_NAME: SSARAID # # # # FUNCTIONS: ssaraid readme file # # # # ORIGINS: 27 # # # # Licensed Materials - Property of IBM # # # # (C) COPYRIGHT International Business Machines Corp. 1995 # # All Rights Reserved # # # # US Government Users Restricted Rights - Use, duplication or # # disclosure restricted by GSA ADP Schedule Contract with IBM Corp. # # # ######################################################################### NAME ssaraid ========================================================================= SYNOPSIS ssaraid -? ssaraid -M ssaraid -l RaidManager [[-n Name [-m|-p|-x]] | [-t ObjectType]] ssaraid -I [-o|-z] -l RaidManager [[-n Name [-m|-p|-x]] | [-t ObjectType]] [-a Attribute=Value] ssaraid -C -l RaidManager -t CreateType -s Member [Member]... [-a Attribute=Value]... [-d [-k DeviceName]] ssaraid -D -l RaidManager -n Name [-u] ssaraid -H -l RaidManager -n Name [-u|-d [-k DeviceName]] [-a Attribute=Value] ssaraid -A -l RaidManager -n Name -i InstructType [-a Attribute=Value] ssaraid -Y[c|a|o] -l RaidManager ========================================================================= DESCRIPTION The 'ssaraid' command is used to configure and manage SSA RAID arrays. It can be used to perform the following tasks: * List all RAID managers in a system. * List RAID objects. - list all objects of a given type (e.g. RAID 5 arrays). - give the preferred name for an object. - list all objects which are members of an object. - list all objects which are parents of an object. * Give information about an object. - give information in colon separated format. - give information in a summary format. - give information for a specified device, its members or parents. - give information for all objects of a certain type. - limit the objects listed to those with certain attribute values. * Create an object. - create a particular type of object that is built from the specified members. - assign values for attributes of the created object. - create AIX customized device objects for the new object, optionally specifying the AIX device name to use. * Delete an object. - delete the named RAID object. - optionally also delete the AIX device associated with it. * Change an object. - specify new values for attributes of an object. * Perform an action on an object. - perform an object specific action on an object (swap, remove or add disks in an array). * List the objects supported by a particular RAID manager. - list all the types of array objects. - list all the types of creatable objects. - list all types of object. ========================================================================= OPTIONS -? Prints a brief usage message. -A Perform an action on an object. -C Create an object. -D Delete an object. -H Change an object. -I Report information on an object. -M List all the available SSA RAID managers on the system. -Ya List all array types. -Yc List all create types. -Yo List all objects. -a An attribute and its desired value. -d Create the AIX device for the specified RAID object. -i The instruct action to perform. -k The AIX device name to use. -l The name of the SSA RAID manager to use. -n The name of an object, for example a RAID array, or member disk. -m List the member objects for the named object. -x List exchange candidates for the named object. -o Information is presented in colon separated format. -p List the parent objects for the named object. -s The disks which are to become members of the array. -t The type of the object to list or create. -u Remove the AIX device for the specified RAID object. -z Information is presented in summary format. ========================================================================= NOTES * RAID object names (arrays or member disks) can be specified as either the AIX device name, or the 15 character connection location. * The preferred name is the 15 character connection location. This is the same as the SSA serial number for the device. * Boolean attribute values can be specified as: 0 1 f t false true n y no yes off on The attributes must be in lowercase. ========================================================================= RAID 5 Creation and Change Attributes ------------------------------------- The following attributes can be specified with the '-a' option when using 'ssaraid' with the '-C' or '-H' options to create or change a RAID 5 array: * spare=true/false (default=true) If the array is exposed, and a write is attempted to it, the array will become degraded. This can be prevented by enabling the 'spare' attribute of the array, and providing a suitable hot spare disk to the RAID manager which is controlling the array. When this attribute is enabled, and a write to an exposed array is attempted, the RAID manager will look for an available hot spare disk to incorporate into the array, to replace the failing disk drive thus preventing the array from becoming degraded. * spare_exact=true/false (default=false) When used in conjunction with the 'spare' attribute, this attribute modifies the RAID manager's behavior when hot spare takeover is attempted for the array. Instead of using any hot spare disk which is large enough to replace the failing disk, the RAID manager will only use a hot spare which the exact size required for the array. The size of the hot spare disk is determined by the size of the other member disks in the array. The sizes of all the member disks are logically truncated to be the size of the smallest member disk. It is this size which the hot spare which must be in order for it to be incorporated into the array as a replacement for the failing disk. * read_only_when_exposed=true/false (default=false) When set to false, if the array enters the exposed state, and write operations are made to the array: The first write operation causes the array to enter the degraded state. The written data is not protected. If another disk drive in the array fails or the power fails during a write operation, data might be lost. While the array is in the degraded state, however, operations to the array continue. The rebuilding operation that runs on the replacement disk drive takes a long time to complete. When set to true: If the array enters the exposed state and hot spare disks are not enabled, the array operates in read-only mode until the failing disk drive is exchanged for a replacement drive. If the array enters the exposed state and host spare disks are enabled, a hot spare disk is added to the array when the first write operation to that array is attempted. If no suitable hot spare disk is available, the array operates in read-only mode. * allow_page_splits=true/false (default=true) Setting this attribute to 'true' will allow data being written to the array in large blocks to be internally split up into 4096 byte blocks and the blocks written in parallel to the member disks of the array. This greatly enhances write performance for the array, at the cost of not guaranteeing the order in which the blocks are written. With the attribute set to 'false' the blocks will be written sequentially to the member disks in the array, which will impact write performance. The order in which the data is written to the array may be critical to the application using the data, in the event of an error occurring during the write. * fastwrite=on/off (default=off) This attribute enables and disables the use of the fast write cache. When using the fast write cache, the following attributes can be used to control the operation of the cache: * fw_start_block (default=0) See the definition for fw_end_block. * fw_end_block (default=array size) This attribute and the fw_start_block attribute control the range of blocks for which the fast write cache is enabled. Write operations that are outside the default range of 0 through array size write data directly to the array, and do not use the fast write cache. * fw_max_length (default=128) This attribute sets the maximum size, in blocks, of write operations to the cache. Write operations that are larger than the specified value write data directly to the array, and do not use the fast write cache. ========================================================================= RAID 5 Change Attributes ------------------------ The following attributes can be specified with the '-a' option only when using 'ssaraid' with the '-H' option to change a RAID 5 array: * use=system/free By setting this attribute to 'system', the RAID array is made usable by the AIX operating system. If the '-d' option is also specified, a corresponding AIX hdisk device is created for the array. Setting this attribute to 'free' will mean that the array will have no use assigned to it, and AIX will not be able to use it as an hdisk. Specifying the '-u' option will ensure that there is no corresponding AIX device for the array. * force=yes/no If an array is using a fast write cache that is failing, this attribute must be specified as "yes" to allow the fast write cache to be disabled. ========================================================================= Physical Disk Change Attributes ------------------------------- The following attributes can be specified using the '-a' option when using 'ssaraid' with the '-H' option to change a physical disk drive: * use=system/spare/free By setting this attribute to 'system', the physical disk is made directly usable by the AIX operating system. If the '-d' option is also specified, a corresponding AIX hdisk device is created for it. Setting this attribute to 'spare' will mean that the physical disk will become a hot spare, and hence available to be incorporated into any exposed arrays on the RAID manager. The '-u' option should also be specified in this case, to ensure that there is no corresponding AIX hdisk device for the disk. Setting this attribute to 'free' will mean that the disk will have no use assigned to it, and hence be available to be used in any new arrays which are going to be created. The '-u' option should also be specified in the case. When using 'ssaraid' with the '-I' option to display information on a physical disk, the following values for the 'use' attribute may also be displayed: * member The disk is currently a member of a RAID array. * rejected The disk used to be a member of an array, but it has been rejected from the array because it was experiencing problems. Rejected disks may have a new uses assigned to them, but the disks should be checked to locate the source of the trouble. Member disks cannot have their use changed. They must first be removed from the array they are in by either deleting the array, or swapping them out of the array with the '-A -i exchange' options to 'ssaraid'. * fastwrite=on/off (default=off) This attribute enables and disables the use of the fast write cache. When using the fast write cache, the following attributes can be used to control the operation of the cache: * fw_start_block (default=0) See the definition for fw_end_block. * fw_end_block (default=disk size) This attribute and the fw_start_block attribute control the range of blocks for which the fast write cache is enabled. Write operations that are outside the default range of 0 through disk size write data directly to the disk, and do not use the fast write cache. * fw_max_length (default=128) This attribute sets the maximum size, in blocks, of write operations to the cache. Write operations that are larger than the specified value write data directly to the disk, and do not use the fast write cache. * force=yes/no If a disk is using a fast write cache that is failing, this attribute must be specified as "yes" to allow the fast write cache to be disabled. ========================================================================= Instruct Types -------------- The following instruct types can be given as an argument to the '-i' option when used in conjunction with the '-A' option: * exchange Add, remove or swap member disks in an array. ========================================================================= Action Attributes ----------------- The following attributes can be specified using the '-a' option when using 'ssaraid' with the '-A' and '-i exchange' options to perform actions on an array: * new_member=disk This specifies the disk which is to be introduced into the array, either to replace a disk which has failed, leaving the array exposed, or to directly replace the disk specified by the 'old_member' attribute. * old_member=disk This specifies the member disk in the array which is to be removed. This can be used on its own, to remove the disk from the array, or together with the 'new_member' attribute, to swap the drive in one action. Whether the swap can be performed in one action, or as two separate remove and add operations depends on whether there is a spare drive bay for the new disk. If there is not, then the swap has to be performed in four steps: 1. Logically remove the failing disk, using 'ssaraid' with just the 'old_member' attribute specified. 2. Physically remove the disk from the drive bay. 3. Physically add the new disk to the slot left by the old disk. 4. Logically add the new disk to the array, using 'ssaraid' with just the 'new_member' attribute specified. Notes: 1. By specifying both 'new_member' and 'old_member' an in place swap is attempted, replacing the 'old_member' disk with the 'new_member' disk in one operation. 2. Drives can only be removed from unexposed arrays. Removing one drive will cause the array to become exposed, until a new disk is added. 3. RAID 5 arrays cannot operate if they lose more than one drive at a time. 4. To generate a list of suitable exchange candidates, use the -x flag with the list command. ========================================================================= RETURN CODES 0 Success. 1 Some changes made but ultimately unsuccessful. 2 General problem accessing ODM. 3 Specified object (file, record, ODM object) not found. 4 Heap allocation failed. 5 Open/ioctl failure for RAID manager. 6 Bad Transaction result. 7 Array already known to AIX cfgmgr. 8 System call failed. 9 Internal logic error. 10 Method not found, not executable or not correct. 11 Problem communicating with back-end method. 12 Problem with environment variable, message catalog etc. 100 Problem with self-defining structure for RDV's. 101 Invalid argument in command line given to back end. 102 Problem with FC_CandidateList transaction. 103 Problem with FC_ResrcList transaction. 104 Problem with FC_ResrcView transaction. =========================================================================