Using the CFGGEN IR Configuration Utility This document describes how to use the CFGGEN IR Configuration Utility to create Integrated Mirroring (IM), Integrated Mirroring Enhanced (IME) and Integrated Striping (IS) volumes. CFGGEN is a command line utility that runs in the DOS, Linux, and Windows environments. CFGGEN is a minimally interactive program that can be executed from a command line prompt or a shell script. The result from invoking this utility is communicated via the program status value that is returned when the program exits. CFGGEN can be used to create IM, IME, and IS storage configurations on both SCSI controllers and SAS controllers. This document includes these topics: • Section 1, “CFGGEN Interface Description” • Section 2, “CFGGEN Commands” Section 1 CFGGEN Interface Description CFGGEN uses a command line interface. Commands are formatted as follows: cfggen The program name, controller number, command, and parameters fields must be separated by the ASCII space character. The format of the parameters is command specific, as described in Section 2, “CFGGEN Commands.” Information is passed between the user environment and CFGGEN via the command line, the standard output and standard error interfaces, and the program return value. The user can redirect the output streams as permitted by the operating environment. The program return value is returned to the user when the program exits. A value of 0 is returned if the command is successful. Otherwise, a value of 1 is returned. Section 2 CFGGEN Commands CFGGEN has the following commands: • CREATE • DEFAULTS • DISPLAY • FORMAT • HOTSPARE • STATUS • SETONLINE • SETOFFLINE CFGGEN is not case sensitive. You can type CFGGEN commands and parameters in uppercase, lowercase, or a mixture of the two. The following conventions are used in the command descriptions: • Text in italics must be entered exactly as shown on the command line. • Text surrounded by <> must be replaced with a required parameter. • Text surrounded by [ ] may be replaced by an optional parameter. • Parameters surrounded by {} must be entered one or more times, as is appropriate for the command being executed. • The command line definition characters <>, [ ], and {} must not be entered on the command line. Section 2.1 Common Command Line Parameters This section describes CFGGEN command line parameters that are common to more than one command. • The unique controller number of a PCI function found in the system, starting with controller # 0. For the LSI Logic SAS1064/1064E and SAS1068/1068E controllers the controller # corresponds to a single SAS controller. For example, in a system containing two SAS1068 controllers, controller # 0 references the first controller and controller # 1 references the other controller. Valid controller number values are 0–255 (decimal). • The SCSI bus address of a peripheral device attached to an LSI Logic controller. The maximum value of SCSI ID depends on the type of I/O controller and the maximum number of devices supported by the OS for this controller. Valid SCSI ID values are: 0–127 (decimal) per controller for SAS1064/1064E and SAS1068/1068E controllers • The Enclosure and bay/slot of a peripheral device attached to the bus. The argument must use a colon (:) as a separator and must follow the enclosure:bay format. This argument is only valid when used with the bay argument on the command line. Valid numbers are 0–127 (decimal) for SAS1064/1064E and SAS1068/1068E controllers. Section 2.2 CREATE Command The CREATE command creates IM, IME, and IS volumes on the SAS1064/1064E and SAS1068/1068E controllers. The firmware and hardware limitations for these controllers determine the number of configurations that can be created. When a disk drive is added to an IM, IME, or IS volume, its entire storage capacity may or may not be used, depending on drive capacity and volume capacity. For example, if you add a 36 Gbyte disk drive to a volume that only uses 9 Gbytes of capacity on each disk drive, the remaining 27 Gbytes of capacity on the disk drive is unusable. The disk identified by the first SCSI ID on the command line is assigned as the primary disk drive when an IM volume is created. If the controller is allowed to resync the disk drives, the data on the primary disk drive will be available when you access the newly created volume. The following rules must be observed when creating IM, IME, and IS volumes and hot spare disks: 1. IM, IME, and IS volumes are supported. 2. A maximum of two IM, IME, or IS volumes per controller can be created. 3. The total number of disks in a volume, including hot spare disks, cannot exceed eight for SAS1064/1064E and SAS1068/1068E controllers, and the total number of disks combined for two volumes cannot exceed ten. (Ten disks is a theoretical upper limit for the firmware; the SAS controller may actually support a lesser number of disks.) 4. An IM volume must have exactly two disks. 5. An IME volume can have a minimum of three disks and a maximum of eight disks as long as rules 4 and 5 are not violated. Command Line – cfggen create {} [qsync] [noprompt] cfggen create bay {} [qsync] [noprompt] Parameters – • – Number of the SAS controller targeted by this command. • – Volume type for the new volume to be created. Valid values are IM or IME or IS. • – Size of the RAID volume in Mbytes, or MAX for the maximum size available. • Bay – This option indicates that enclosure:bay values are specified instead of SCSI ID values. • – SCSI ID of a hard disk drive to be included in the RAID volume. • – The enclosure:bay value for the disk drive to be included in the RAID volume. These values can be obtained from the output of the DISPLAY command. • qsync – If this optional parameter is specified, a quick synchronization of new volume will be performed. If the volume type is IME or IS, a quick synchronization is always performed even if qsync is not specified. A quick synchronization means that the first 32 Kbytes of the drives in the volume are cleared to 0. • noprompt – Suppresses display of warnings and prompts. Program Return Value – 0x00 SUCCESS: command completed successfully. 0x01 FAILURE: bad command line arguments or operational failure. Section 2.3 DEFAULTS Command The DEFAULTS (DELETE) command deletes any IM, IME, and IS volumes and hot spare drives created by the CREATE and HOTSPARE commands. No other controller configuration parameters are changed. Command Line – cfggen defaults [noprompt] Parameters – • – Number of the SAS controller targeted by this command. • noprompt – Suppresses display of warnings and prompts. Program Return Value – 0x00 SUCCESS: command completed successfully. 0x01 FAILURE: bad command line arguments or operational failure. Section 2.4 DISPLAY Command The DISPLAY command displays configuration information for the supported controllers (SAS1064/1064E, SAS1068/1068E). The information includes controller type, firmware version, BIOS version, volume information, and physical drive information. An example of the information that will be output by this command is provided in Sample Output below. Note: 1 Mbyte = 1,048,576 bytes. All sizes displayed in Mbytes are rounded down to the nearest Mbyte. Command Line – cfggen display [filename] Parameters – • – Number of the SCSI bus or SAS controller targeted by this command. • [filename] – Optional valid filename to store output of command to a file. Program Return Value – 0x00 SUCCESS: command completed successfully. 0x01 FAILURE: bad command line arguments or operational failure. Sample Output – The following example shows the output of the CREATE command when used to create an IM configuration on a SAS1064/1064E or SAS1068/1068E controller. Note: The format and content of the DISPLAY command output varies, depending on the CFGGEN version being used. Read configuration has been initiated for controller 0 ------------------------------------------------------------------------ Controller information ------------------------------------------------------------------------ Controller type : LSI1064/1068 BIOS version : 6.05.05.00 Firmware version : 0.07.01.00 SCSI channel description : 1 Serial Attached SCSI Initiator IDs (SCSI ID) : 63 Maximum physical devices : 62 Concurrent commands supported : 511 Slot : 1 Bus : 2 Device : 2 Function : 0 ------------------------------------------------------------------------ IR Volume information ------------------------------------------------------------------------ IR volume 1 Status of volume : Okay (OKY) RAID level : 1 Size (in MB) : 34332 Physical hard disks (SCSI ID) : 10 7 -------------------------------------------------------------------------------- Enclosure information -------------------------------------------------------------------------------- Enclosure # : 1 Enlcosure WWN : 12345678:ABCDABCD Start Slot : 1 Num Slots : 4 Start SCSI ID : 0 -------------------------------------------------------------------------------- Physical device information ------------------------------------------------------------------------ Initiator at SCSI ID 63 Target on SCSI ID 7 Enlocosure # : 1 Slot # : 1 Device is a Hard disk SCSI ID : 7 State : Online (ONL) Size (in MB)/(in sectors) : 34732/71132958 Manufacturer : MAXTOR Model Number : ATLAS15K2_036SAS Firmware Revision : BG31 Serial No : E204EY1K Drive Type : SAS Target on SCSI ID 8 Enlocosure # : 1 Slot # : 2 Device is a Hard disk SCSI ID : 8 State : Hot Spare (HSP) Size (in MB)/(in sectors) : 35074/71833095 Manufacturer : MAXTOR Model Number : ATLAS15K2_36SAS Firmware Revision : BG34 Serial No : E207AY6K Drive Type : SAS Target on SCSI ID 9 Enlocosure # : 1 Slot # : 3 Device is a Hard disk SCSI ID : 9 State : Ready (RDY) Size (in MB)/(in sectors) : 34732/71132959 Manufacturer : MAXTOR Model Number : ATLAS15K2_036SAS Firmware Revision : BG31 Serial No : E204ERCK Drive Type : SAS Target on SCSI ID 10 Enlocosure # : 1 Slot # : 4 Device is a Hard disk SCSI ID : 10 State : Online (ONL) Size (in MB)/(in sectors) : 140299/287332383 Manufacturer : MAXTOR Model Number : ATLAS15K2_147SAS Firmware Revision : BG34 Serial No : E803YMCK Drive Type : SAS Logical drive status values are as follows: • Okay (OKY) – Volume is Active and drives are functioning properly. User data is protected if the volume is IM or IME. • Degraded (DGD) – Volume is Active. User data is not fully protected due to a configuration change or drive failure. • Rebuilding (RBLD) – Data resync or rebuild may be in progress. • Inactive, Okay (OKY) – Volume is inactive and drives are functioning properly. User data is protected if the current RAID level is RAID 1 (IM) or RAID 1E (IME). • Inactive, Degraded (DGD) – Volume is inactive and the user’s data is not fully protected due to a configuration change or drive failure; a data resync or rebuild may be in progress. Physical device status values are as follows: • Online (ONL) – Drive is operational and is part of a logical drive. • Hot Spare (HSP) – Drive is a hot spare that is available for replacing a failed drive in an array. • Ready (RDY) – Drive is ready for use as a normal disk drive; or it is available to be assigned to a disk array or hot spare pool. • Available (AVL) – Drive may or may not be ready, and it is not suitable for inclusion in an array or hot spare pool (i.e., it is not spun up, its block size is incorrect, or its media is removable). • Failed (FLD) – Drive was part of a logical drive or was a hot spare drive, and it failed. It has been taken offline. • Standby (SBY) – This status is used to tag all non-hard disk drive devices. Section 2.5 FORMAT Command The FORMAT command is used to perform a low-level format of a disk drive. The drive cannot be a hot spare drive or a member of an IM, IME, or IS volume. WARNING: A low-level format erases all data on the hard disk drive. The FORMAT command cannot and should not be interrupted; doing so may result in irreparable damage to the hard disk drive. Warning messages are displayed during the formatting, unless the noprompt option is included on the command line. If the user does not quickly respond to a series of prompts, the command is aborted. The answers are case sensitive and must be entered in upper case. The FORMAT command does not complete and return to a shell prompt until the format operation is complete. This may take a long time for a large disk drive. Command Line – cfggen format [noprompt] cfggen format bay [noprompt] Parameters – • – Number of the controller targeted by this command. • Bay – This option indicates that enclosure:bay values are specified instead of SCSI ID values. • – SCSI ID of the hard disk drive to be formatted. • - The enclosure:bay value for the disk drive to be formatted. These values can be obtained from the output of the DISPLAY command. • noprompt – Suppresses display of warnings and prompts. Program Return Value – 0x00 SUCCESS: command completed successfully. 0x01 FAILURE: command failed. Section 2.6 HOTSPARE Command The HOTSPARE command creates a hot spare disk drive, which is added to hot spare pool 0. The number of disk drives in an IM, IME, or IS volume, including the hot spare disk cannot exceed eight. Only one hot spare disk can be created. The capacity of the hot spare disk must be greater than or equal to the capacity of the smallest disk in the logical drive. An easy way to verify this is to use the DISPLAY command. The following rules must be observed when creating hot spare disks: 1. A hot spare disk cannot be created unless at least one IM or IME volume is already created. 2. For LSI1064/1064E and LSI1068/1068E controllers, CFGGEN does not allow adding a hot spare disk of a type (SAS/SATA) that is different from the disk types in any of the volume. Command Line – cfggen hotspare cfggen hotspare bay Parameters – • – Number of the SAS controller targeted by this command. • Bay – This option indicates that enclosure:bay values are specified instead of SCSI ID values. • – SCSI ID of the drive targeted by this command. • - The enclosure:bay value for the disk drive to use for the new hot spare disk. These values can be obtained via the output of the DISPLAY command. Program Return Value – 0x00 SUCCESS: command completed successfully. 0x01 FAILURE: bad command line arguments or operational failure. Section 2.7 STATUS Command The STATUS command displays the status of any volume synchronization operation that is currently in progress on the controller. If no such operation is in progress, CFGGEN displays a message indicating this before it exits. The STATUS command adds the flag Inactive to the Volume State field, if the controller firmware marks the volume as Inactive. Command Line – cfggen status Parameters – • – Number of the SCSI bus or SAS controller targeted by this command. Program Return Value – 0x00 SUCCESS: command completed successfully. 0x01 FAILURE: command failed. Sample Output – Here is an example of the status information returned when a volume resynchronization is in progress: Background command progress status for controller 0... IR Volume 1 Current operation : Synchronize Volume ID : 6 Volume status : Enabled Volume state : Degraded Physical disk I/Os : Not quiesced Volume size (in sectors) : 70311936 Number of remaining sectors : 68250624 Percentage complete : 2.93% Here is an example of the status information returned when no background volume operation is in progress: Background command progress status for controller 0... IR Volume 1 Current operation : None Volume ID : 6 Volume status : Enabled Volume state : Optimal Physical disk I/Os : Not quiesced The status fields in the data displayed can have the following values: Current operation – Synchronize or None Volume status – Enabled or Disabled Volume state – [Inactive] Optimal, Degraded or Failed Physical disk I/Os – Quiesced or Not quiesced Section 2.8 SETOFFLINE Command The SETOFFLINE command makes a physical disk in a volume offline. A physical disk that is taken offline changes its state to Failed (FLD), but the disk is still associated with the volume and therefore cannot be addressed by normal I/O requests. If a new disk replaces an offline disk, the new disk is automatically brought online. Otherwise, the disk remains offline until explicitly brought online by SETONLINE command. Command Line – cfggen setoffline Parameters – • – Number of the SAS controller targeted by this command. • – SCSI target ID of the drive targeted by this command. Program Return Value – 0x00 SUCCESS: command completed successfully. 0x01 FAILURE: command failed. Section 2.9 SETONLINE Command The SETONLINE command brings a physical disk in a volume online, which is required only after the physical disk has been taken offline by the SETOFFLINE command. When a physical disk is brought online, the IOC synchronizes the volume. Command Line – cfggen setonline Parameters – • – Number of the controller targeted by this command. • – SCSI target ID of the drive targeted by this command. Program Return Value – 0x00 SUCCESS: command completed successfully. 0x01 FAILURE: command failed. a volume online, which is required only after the physical disk has been taken offline by the SETOFFLINE command. When a physical disk is brought online, the IOC synchronizes the volume. Command Line – cfggen setonline Parameters – • – Number of the controller targeted by this command. • – SCSI target ID of the drive targeted by this command. Program Return Value – 0x00 SUCCESS: command completed successfully. 0x01 FAILURE: command failed. command failed.