*** UNIX MANUAL PAGE BROWSER ***

voldisk(8) System Manager's Manual voldisk(8) NAME voldisk - Define and manage Logical Storage Manager (LSM) disks SYNOPSIS /sbin/voldisk init accessname [ attribute ... ] /sbin/voldisk define accessname [ attribute ... ] /sbin/voldisk moddb accessname [ attribute ... ] /sbin/voldisk offline accessname ... /sbin/voldisk online accessname ... /sbin/voldisk rm accessname ... /sbin/voldisk list [ disk ... ] /sbin/voldisk clearimport accessname ... /sbin/voldisk check accessname ... DESCRIPTION The voldisk utility performs basic administrative operations on disks. Operations include initializing and replacing disks, as well as taking care of some book-keeping necessary for the disk model presented by the Logical Storage Manager. The voldisk utility accesses disks based on disk access names, which are system-specific names that relate to disk addresses. For example, SCSI disk access names are usually of the form rznp, where rz is the device mnemonic for SCSI devices, n is the SCSI unit number, and p is the partition identifier (in the range a to h). All disk access names relate directly to device node names in the /dev directory. The Logical Storage Manager maintains known disk device address infor- mation in a set of disk access records, which are stored in the rootdg disk group configuration. These records are named, based on the disk access name. These disk access records are normally used solely to identify which physical disks exist, based on disk IDs stored on the disks themselves. Operations for voldisk other than init and define require specification of defined disk access records. Physical disks contain public regions, which are used for allocating subdisks. They can also contain private regions, which are used for storing private Logical Storage Manager information. Each private re- gion contains exactly two copies of a disk header, which defines the unique disk ID, disk geometry information, and disk group association information. Two copies are created so that one copy can be lost (due to I/O failures), without losing the ability to use the disk. The pri- mary copy of the disk header is stored in block zero of the private re- gion. The alternate copy is stored within the first 256 sectors. If the primary copy is unreadable or unusable, the Logical Storage Manager will search the first 256 sectors of the private region for the alter- nate copy. The table of contents contains a linked list of blocks, pointed to by the disk header, that define additional structures in the private and public regions. The table of contents blocks define disk group configuration copy locations, log copy locations, and reserved regions carved from the public region. Each link block in the table of contents is replicated at the beginning and end of the private region. If the primary copy of any one link block is unreadable or unusable, the alternate copy of that link is used. A disk normally contains be- tween zero and two disk group configuration copies, according to the number specified when the disk was initialized using the voldisk init operation (explained later). When a disk is added to a disk group, the disk group's persistent configuration records are written to each copy. For disks that are not associated with a disk group, the space allo- cated for configuration copies is unused. Each disk group requires at least one usable configuration copy. Preferably there should be at least four copies, allocated between at least two disks. This allows one disk to be lost totally, while still preserving sufficient redun- dancy for recovering from simple read failures. A disk normally con- tains between zero and two disk group log copies. The number of log copies is set to the same as the number of configuration copies for the disk as explained in the Configuration copies section above. These logs are written by the kernel when certain types of actions are per- formed: transaction commits, plex detaches resulting from I/O failures, total block-change-log failures, the first write to a volume, and vol- ume closes. After a crash or a clean reboot, this log information is used to recover the state of a disk group just prior to the crash or reboot. Each disk group requires at least one usable disk group log copy. As with configuration copies, it is preferable to have at least four log copies, allocated between at least two disks. For a single disk, the disk header and the table of contents blocks are critical data structures. At least one copy of the disk header, and at least one copy of each table of contents block, must be readable and usable, or else the disk itself is unusable and will have to be reinitialized. Within disk groups, disk group configuration and log copies are critical data structures. At least one complete configuration copy and log copy must be readable and usable, or the disk group is unusable and will have to be reinitialized from scratch. All disk group association information is stored in the disk header within private regions. This information consists of a disk group name, disk group unique ID, and a host ID. When the system boots, the Logical Storage Manager scans for disks that are stamped with the system's host ID. Each represented disk group is imported automatically. Disks with a non-matching host ID are not imported automatically, and cannot be used until the host ID is cleared with the clearimport operation. The behavior of the voldisk utility depends upon the keyword specified as the first operand. Supported operations are: Ini- tialize regions of a disk used by the Logical Storage Manager. This involves installing a disk header and writing an empty con- figuration on the disk. The accessname operand identifies the disk. Normally, this command will fail if the disk already con- tains an apparently valid disk header. The -f option can be used to override this and to force initialization of the disk. A disk that is a member of an imported disk group cannot be ini- tialized. The voldisk init operation creates a disk access record for a disk (if one does not already exist), and sets its state to on- line. Disks can be initialized when the root configuration is disabled, in which case the disk header will be initialized, but the disk will not be added to the permanent list of known disks until the root configuration is enabled. Any attribute operands override default values assigned for var- ious disk attributes. Some attributes that can be set are: The disk device access type, which is a system-specific name identi- fying a class of strategies for accessing disks and for managing private and public regions. For example, disk type could indi- cate a volatile RAM disk that may not require the storage of any private data, or could be for a hard disk with free partitions. The various disk types support additional attributes for the init operation. See the definition for each disk type, below. The device will be left in the offline state, initially. This is used only if this operation is defining a new disk access record. Define a disk access record, but do not initialize it. In order for the Logical Storage Manager to scan a disk, a disk access record must be defined for it. Thus, if you want to see what is on a new disk or you want to move a disk with a valid disk group from one system to another, you will need to use voldisk define to make it accessible first. You can use voldisk list to see what is on the disk, or voldg import to import a disk group that is on the disk. Attributes can be specified to define the access characteristics of the disk device. Some attributes that can be set are: The disk device access type. See the init operation definition for more details. The various disk types support additional attributes for the de- fine operation. See the definition for each disk type, below. If specified, the disk will be created in the offline state. Normally, a define operation will fail if the specified disk de- vice is invalid, such as because no such disk currently exists. The -f option can be used to force definition of an unusable disk. This can be useful if, for example, the disk device could be useful after a reboot. For example, if you intend to add a new controller and intend to move some existing disks to the new controller, you may need to define the new disk device ad- dresses, even though they will not be usable until you shutdown and reconfigure your disks. Change the number of configuration copies for the disk device specified by the accessname argument. By decreasing the number of configuration copies on a disk, the size of the configuration database on that disk will be in- creased. Refer to the Logical Storage Manager manual for more information about when to use this option. Declare the disk de- vices named by the accessname arguments to be in the offline state. This disables checking of the disk in searching for par- ticular disk IDs, or for the set of disks in a particular disk group. This operation cannot be applied to disks that are mem- bers of an imported disk group. A disk should be offlined if the disk is not currently accessi- ble, and if accessing the disk has a negative impact on the sys- tem. For example, disk drivers on a few operating systems can cause system panics or hangs if an attempt is made to access disks that are not accessible. In other operating systems, at- tempts to access inaccessible drives may take several seconds or minutes before returning a failure. Clear the offline state for a disk device. This re-enables checking of the disk when searching for disk IDs, or for members of a disk group. This can be used for disks that are already in the online state, pro- vided that they are not in imported disk groups. All internal information for an already online state disk is regenerated from the disk's private region. Remove disk access records, by name. List detailed disk information on the specified disks. If no accessname arguments are specified, then print a one-line sum- mary for all disk access records known to the system. If ac- cessname arguments are specified, then print a full description of the contents of the disk header and of the table of contents for each named disk. If the -s option is specified, then list important information from the disk header. With -s, the output format is the same whether or not accessname arguments are specified. The informa- tion printed with -s includes the disk ID, the host ID (if the disk is or was imported), and the disk group ID and disk group name (if the disk is a member of a disk group). If the -q option is specified, then no header is printed de- scribing output fields. This option has no effect with the long formats generated with -s or with accessname arguments. Clear the host-specific import information stored on the indicated disks, and in the configurations stored on those disks. This command may be necessary in cases where import information stored for a disk group becomes unusable, due to host failures, or due to a disk group being moved from one machine to another. This operation cannot be applied to disks that are in imported disk groups. Check the status of a disk in LSM. If the disk is online, print the message Okay. If the disk is offline or inac- cessible, print an error message. DISK TYPES Three disk types are provided with the Logical Storage Manager. The default is a sliced type for disk access names without a partition name, such as rz3. If a partition name, such as rz3c, is supplied, then the default type becomes simple. Nopriv disks The simplest disk type is nopriv, which defines a disk that has no pri- vate region, and that consists only of space for allocating subdisks. Configuration and log copies cannot be stored on such disks, and such disks do not support reserved regions defined with voldisk addregion. Also, such disks are not self identifying. Because nopriv disks are not self identifying, the Logical Storage Manager cannot track the movement of such disks on a SCSI chain or between controllers. Do not initialize a new disk as a nopriv disk - this disk type is appropriate only for encapsulation of existing data. To add a disk with no configuration database, set the nconfig attribute to 0 when initializing the disk. nopriv devices are most useful for defining special devices (such as volatile RAM disks) that you wish to use with the Logical Storage Man- ager, but that can't store private regions. A RAM disk cannot store a meaningful private region, because data written to a RAM disk may not survive a reboot. Initializing a nopriv device with voldisk init creates a disk access record in the rootdg configuration, but does not write to the disk. The disk ID for nopriv devices is stored in the disk access record in the rootdg configuration. Attributes that can be used with the voldisk init and define operations for the nopriv device type are: The usable length of the device. This is required if there is no system-defined procedure for determining the disk length; otherwise, a suitable default will be computed. The off- set within the device for the start of the usable region. This can be used if it is necessary to skip over some region reserved by the oper- ating system. If an offset is specified, then the default disk length is adjusted accordingly. If this attribute is specified, the disk is considered to have volatile contents (i.e., the disk contents are not expected to remain consistent across a system reboot). Subdisks and plexes defined on disks with the volatile attribute will inherit that attribute. The volume start operation interprets volatile plexes as requiring a complete revive from other plexes in the same volume. The voldisk define operation, with the nopriv device type, takes the same attributes as the init operation. In addition, define takes the following attribute: This attribute will set the disk ID to the newdiskid value in the disk access record for the no- priv disk. Sliced and simple disks Two disk types are provided that support disk private regions: simple and sliced. The simple type presumes that the public and private re- gions are stored on the same disk partition, with the public region following the private region. The sliced type presumes that the public and private regions are stored on different disk partitions. For the simple type, the partition is marked with disklabel tag LSM- simp. For the sliced type, then the public and private regions are in partitions with disklabel tags LSMpubl and LSMpriv, respectively. Attributes that can be defined with voldisk define for simple or sliced types are: Define the partition number to use for the public partition. This can be used only with the sliced type. Define the partition num- ber to use for the private partition. This can be used only with the sliced type. Specify the offset from the beginning of the partition containing the private region to the beginning of the private region. This defaults to zero for both simple and sliced types. It is strongly advised that this option never be used unless absolutely necessary. Most information for disks can be determined from the disk header stored at the beginning of the private region. The private region off- set cannot be determined from the disk. As a result, specifying a pri- vate region offset adds an undesirable dependence between a disk access record and a specific physical disk. In addition to the above attributes, voldisk init takes the following attributes: Specify the length of the public region. If this is not specified, then the length of the private region is computed from available partition table information. If no such information is available, a public region length must be specified in this command. The default public region length is adjusted to account for the private region, or for any specified public or private region offsets. Specify the offset from the beginning of the partition containing the public region to the beginning of the public region. For the sliced type, this defaults to zero. For the simple type, this defaults to the first block past the end of the private region. Specify the length of the private region. If this is not specified, then a default is chosen. For the sliced type, the default is computed from available partition table information. For the simple type, the default size is 512 blocks. With the sliced type, if no partition information is avail- able, a private region length must be specified in this command. The number of configuration copies to store on the disk. The number of configuration copies should be the same as the number of log regions. This defaults to 1. This can be set to 0 to indicate that no configu- rations will be stored on the disk. It is reasonable to set this to 1 for disk groups that contain three or more disks. This would allow ei- ther more configuration records or a smaller reserved private region. In disk groups with more than 8 disks, it may be reasonable to set nconfig to zero for some disks, so that space for configuration copies is allocated only on some disks. Setting nconfig to zero improves the performance of LSM configuration updates and reduces the time required to import a disk group. The size to reserve for each copy of the con- figuration stored on the disk. The default size will be based on the size of the private area and the number of configuration copies re- quested, and will leave some space free for uses other than the config- uration copies. The number of log regions to allocate on the disk. The number of log regions should be the same as the number of configu- ration copies. Logs regions are used for storing any plex detaches that happen within the disk group. This number defaults to 1. It may be desirable to reduce this number to 0 on some disks, if you have disk groups with large numbers of disks. However, at least one valid log copy (preferably at least four, two copies each on two drives) must be usable for a disk group to be usable. The size to reserve in the pri- vate region for each log region. This size limits the number of ker- nel-initiated detach operations that can be logged against the disk group. The default is about 15% of the size of the configuration copies. It is advised that the log sizes be kept as 15% of the config- uration copy size. RELATED INFORMATION volintro(8), vold(8), voldg(8), volume(8). delim off voldisk(8)