cfl(1M)

NAME

cfl — configure a logical unit (LUN) on a SCSI disk array

SYNOPSIS

cfl [-L LUN_address] [-a -clist [,list ] [-i]] [-b block_size] [-clist [,list ]] [-d] [-f flag_word] [-k num_log_blocks] [-l sec_tenths] [-n num_log_blocks] [-p list] [-r RAID_level] [-s num_log_blocks] [-t reg|sub] [-z num_log_blocks] device_file

DESCRIPTION

cfl sets configuration parameters, and changes the status of a LUN on the HP SCSI disk array associated with device_file.

NOTE: newarray, a front-end program for cfl, is recommended for doing array configuration (see newarray(1M)).

Options

-L LUN_address

Specifies which SCSI unit address to affect.

-a -c list [,list ] [ -i ]

list is a comma-separated drive list (cXiY ,cXiY ,...) describing drives on SCSI channel X, and SCSI ID Y (where X and Y are decimal numbers). Multiple lists are delimited by space characters.

Add a LUN to the set of LUNs known by the controller. If this option is used, the runstring must also contain a value for the -c parameter, and can contain values for all other applicable parameters except -d (the delete LUN option). If only the -c parameter is supplied, a default RAID-level 0 configuration is created with the drives specified in the parameter list. The user may thus specify all the LUN characteristics in one line; create a default configuration and change a few of the parameters to desired values in one line, or create a default configuration and iteratively change its parameters to the desired values. The -i option formats the newly added LUN after configuration. If multiple LUNs are to be added and configured, each LUN must be formatted before any other LUNs can be added and configured.

-b block_size

Set the logical block size of the LUN. block_size is specified in bytes.

-c list [,list2] device_file

Assign to the LUN a configuration table that describes which drives are associated with the LUN and specifies the order each drive appears in a data stripe. One, or more tables can be assigned to each LUN, depending on the RAID level. Each table can have a maximum of five drives.

-d

Delete the LUN from the set of LUNs known by the controller. This option cannot be used simultaneously with the -a option.

-f flag_word

Assign the desired hexadecimal values, given in flag_word, to the array's two LUN flag bytes. The default flag_word is hex 0072. User-changeable bits are in Mode Page 0x2b byte 25 (the lsb): bit 4, which enables AEN polling when set; bit 5, which enables parity verification when set, and bit 6, which enables writes with parity verification when set.

-k num_log_blocks

Set the reconstruction quantity in blocks. This represents the number of blocks reconstructed in a single reconstruction command. Reconstruction commands are issued at an adjustable interval until the LUN is reconstructed (see the -l option).

-l sec_tenths

Set the reconstruction frequency, the interval between successive reconstruction commands. It is expressed in tenths of a second.

-n num_log_blocks

Set the number of logical blocks in the LUN.

-p list

Create the LUN's disk bit map, which describes the drives associated with the LUN. Either a configuration table or a disk bit map, but not both, is required to configure a LUN; use of the configuration table is recommended.

-r raid_level

Set the RAID level of the LUN; valid RAID levels are 0, 1, 3 and 5.

-s num_log_blocks

Set the number of blocks in a LUN segment, the part of a data stripe residing on a single disk.

-t reg | sub

Set the LUN type, regular or sub-LUN. A sub-LUN is a LUN that can share its physical drive(s) with another LUN; usually, its data resides on more than one drive. Configurations involving data striping or mirroring should use sub-LUNs.

-z num_log_blocks

Set the number of blocks in the first segment of the LUN.

RETURN VALUE

cfl returns the following values:

0

Successful completion.

-1

Command failed (an error occurred).

DIAGNOSTICS AND ERRORS

Errors can originate from problems with:

cfl
SCSI (device level) communications
system calls

All error information is printed to stderr.

Error messages generated by cfl:

usage: cfl -L <LUN_addr> -a <-c ...> [-i] <special>  add LUN 
 cfl -L <LUN_addr> -b <n> <special>   set logical block size 
 cfl -L <LUN_addr> -c <<cXiY,... [cXiY,...]> | none> <special> build 
                                               config table(s) 
 cfl -L <LUN_addr> -d <special>            delete LUN 
 cfl -L <LUN_addr> -f <n> <special>        set LUN flags 
 cfl -L <LUN_addr> -k <n> <special>        set reconstruction amt in 
     blocks 
 cfl -L <LUN_addr> -l <n> <special>        set reconstruction frequency 
 cfl -L <LUN_addr> -n <n> <special>        set number of blocks in LUN 
 cfl -L <LUN_addr> -p <cXiY,...> <special> build disk bit map 
 cfl -L <LUN_addr> -r <n> <special>        set RAID level 
 cfl -L <LUN_addr> -s <n> <special>        set segment size in blocks 
 cfl -L <LUN_addr> -t <reg | sub> <special>  set LUN type 
 cfl -L <LUN_addr> -z <n> <special>        set segment 0 size in blocks 

An error in command syntax has occurred. No valid tags were present, or an illegal tag was encountered. Re-enter the command with all required arguments. If a syntax error occurs in a runstring with a legal tag, only the template for that tag will be displayed.

cfl: Arg incompatible with other: One of the arguments is incompatible with another, for example, when the -a (add LUN) and -d (delete LUN) are both on the command line.
cfl: Arg out of range: One of the arguments is larger than its allowed maximum value (or smaller than its allowed minimum value), or is incorrect in form. Check the size, and form of each argument and make appropriate corrections.
cfl: device busy: To ensure that cfl does not modify a disk array that is being used by another process, cfl attempts to obtain exclusive access to the disk array. If the disk array is already opened by another process (for example, LVM — the Logical Volume Manager), a ``device busy'' error message is returned by the driver. To eliminate the ``device busy'' condition, determine what process has the device open. In the case of LVM, it is necessary to deactivate the volume group containing the array before configuring the array (see vgchange(1M)).
cfl: LUN does not exist: The addressed LUN is not known to the array controller. Only the -a option can operate on an unconfigured LUN. The -d option ignores references unconfigured LUNs (and does nothing with them).
cfl: LUN # too big: The LUN number, which is derived from the device special file name, is out of range.
cfl: Multiple args of same type: An argument occurs more than once on the command line.
cfl: Not a disk array: The device being addressed did not identify itself as a SCSI disk array product that is supported by cfl.
cfl: Not a raw file: cfl must be able to open the device file for raw access (the character device file).
cfl: Transfer length error: The amount of data actually sent to or received from the device was not the expected amount.

SCSI (device level) communication errors:

Sense data associated with the failed operation is printed.

Error messages generated by system calls:

cfl uses the following system calls:

malloc(), free(), stat(), open(), close(), read(), write(), and ioctl().

Documentation for these HP-UX system calls contains information about the specific error conditions associated with each call. cfl does not alter the value of errno. The interpretation of errno for printing purposes is performed by the system utility strerror().

EXAMPLES

To delete LUN 5 associated with /dev/rdsk/c2t0d0:

cfl -L 5 -d /dev/rdsk/c2t0d0 

To add the LUN 0 associated with /dev/rdsk/c2t0d0, which will have the following characteristics: logical block size 512 bytes, RAID level of 5, auto reconstruct disabled, reconstruction amount of 64 blocks, reconstruction frequency of .2 seconds, segment size of 64 blocks, type sub-LUN, segment zero size of 1, and drives with SCSI ID 1 on channels 1 through 5, to be striped in the channel order 3, 5, 1, 2 and 4:

cfl -L 0 -a  -b 512 -r 5 -f 0072 -k 64 -l 2 -n 123456 -s 64 
    -t sub -z 1 -c c3i1,c5i1,c1i1,c2i1,c4i1 /dev/rdsk/c2t0d0 

WARNING

Changing any configuration parameter except the reconstruction frequency and reconstruction quantity puts the affected LUN in an unusable ("dead") state. You must reformat the LUN before it can be used with the new configuration values. Formatting a LUN destroys all of its user data.

DEPENDENCIES

The HP C2425 and HP C2427 disk arrays are only supported on Series 700 systems running HP-UX version 9.0X.

The HP C2430 disk array is supported on Series 700 and 800 systems running HP-UX versions 9.0X and 10.0X.

AUTHOR

cfl was developed by HP.