*** UNIX MANUAL PAGE BROWSER ***

volume(8) System Manager's Manual volume(8) NAME volume - Perform Logical Storage Manager (LSM) operations on volumes SYNOPSIS /sbin/volume -Vf -g diskgroup -U usetype -o useopt init init_type vol- ume [ arg ... ] /sbin/volume -Vf -g diskgroup -U usetype -o useopt rdpol policy volume [ plex ] /sbin/volume -Vf -g diskgroup -U usetype -o useopt start volume ... /sbin/volume -Vf -g diskgroup -U usetype -o useopt startall /sbin/volume -Vf -g diskgroup -U usetype -o useopt stop volume ... /sbin/volume -Vf -g diskgroup -U usetype -o useopt stopall /sbin/volume -Vf -g diskgroup -U usetype -o useopt resync volume ... /sbin/volume -Vf -g diskgroup -U usetype -o useopt maint volume ... /sbin/volume -Vf -g diskgroup -U usetype -o useopt set at- tribute=value ... [ -- ] volume ... DESCRIPTION The volume utility performs Logical Storage Manager operations on vol- umes. The first operand is a keyword that determines the specific op- eration to perform. The remaining operands specify configuration records to which the operation is to be applied. Each operation can be applied to only one disk group at a time, due to internal implementation constraints. Any volume operands will be used to determine a default disk group, according to the standard disk group selection rules described in volintro(8). A specific disk group can be selected with -g diskgroup. The recognized operation keywords are: Perform an initialization action on a volume. This can be applied to volumes that were created by vol- make and that have not yet been initialized, or volumes that have been set to the uninitialized state with volmend fix empty. The action to perform is specified by the init_type operand, which is usage-type-de- pendent. The volume operand determines which usage type to use for performing the operation. Set the read policy for a volume based on the policy operand. These are the recognized read policies: Use a round-robin read order among the enabled, readable plexes associated with the volume. No plex operand should be specified for the round read-policy type. Read preferentially from the plex named by the plex operand. If the plex is enabled, readable, and associated with the volume, then any read operation on the volume results in a read from that plex if all blocks requested in the read are contained in the plex. The plex operand is required for the prefer read-policy type. Select a default policy based on plex associations to the volume. For a volume that contains one enabled, striped plex, the default is to prefer that plex. For any other set of plex associations, the default is to use a round-robin policy. No plex operand should be specified for the select read-policy type. Enable disabled or detached volumes named by the volume operands. The process of enabling a volume is a highly usage-type-dependent operation and may result in transfers of data between plexes associated with the volume. If the start operation is applied to an uninitialized volume (for example, a volume just created by volmake), a default ini- tialization will be used to initialize and enable the volume. If the volume is not normally started because failures and disk removals have left all associated plexes with invalid data, the -f option can be used to try to start the volume, anyway. This can be used after replacing disks to enable the volume so that its contents can be restored from backup or reinitialized. At- tempt to start all volumes that are disabled. If a -U usetype option is specified, then attempt to start all disabled volumes with the indicated usage type. This operation will not start uninitialized volumes. By default, start all volumes in the rootdg disk group. A different disk group can be specified with the -g option. Disable the enabled or detached volumes named by the volume operands. The stop operation provides an interface to the usage type of a volume for shutting down operations on a volume in a clean man- ner. The specific method for cleanly stopping a volume, and the precise meaning of ``clean'' are both highly usage-type-depen- dent. By convention, -f can be used to force stopping of a vol- ume that is in use, forcing I/O failures to be returned for any further volume device operations. Attempt to stop all volumes that are enabled. If a -o usetype option is specified, then at- tempt to stop all disabled volumes with the indicated usage type. By default, stop all volumes in the rootdg disk group. A different disk group can be specified with the -g option. Exam- ine all volumes named by the volume operands. Volumes that have possibly differing plex contents will be re-synchronized to con- tain consistent data. Any such volumes that are in the NEEDSYNC state will be recovered using a read/write-back recovery mode and then put into the ACTIVE state. Plexes in the SYNC state may already be under recovery and the volume command will take no action to recover them unless the command was invoked with the -o force option. Detach each vol- ume named by the volume operands and make the plex devices asso- ciated with those volumes accessible to regular system utili- ties. When a volume is detached, normal read and write opera- tions to the volume fail, although most volume ioctl operations can still be used. Normal reads and writes can be used on the plex devices for the associated plexes. This operation could be used, for example, before using the fsck utility to decide which of several associated plexes should be used for reviving other plexes in a volume. Change specific volume characteristics. The changes to be made are given by arguments immediately after the set keyword of the form attribute=value. The set of volumes affected by the operation are given after these operands; thus the attribute list ends with an operand that does not contain an equal sign. To allow for volume names that contain an equal sign, an operand of -- can be used to terminate the attribute list. Each usage-type represented by the list of volume operands is called once, with the set of all volumes with that usage type. The set of attribute=value attribute arguments that are recog- nized depends upon the volume usage-type. However, an attribute argument of the form len=number is expected to be interpreted (if at all) as requesting a change in the length of a volume re- gardless of the volume's usage-type. The number value is inter- preted as a standard length number (see volintro(8)). OPTIONS The following options are recognized: Specify the disk group for the operation. The disk group can be specified either by name or by disk group ID. See voldg(8) for more information on disk groups. Force the operation to be performed by the usage-type utility for this usage type. B Write a list of utilities that would be called from volume, along with the arguments that would be passed. The -V option performs a ``mock run'' so the utilities are not actually called, and no changes are made to the volume configuration database. Force an operation in some situations where the operation has questionable semantics. For example, -f may be used to reduce the length of a volume with volume set, to stop a volume that is currently open or mounted as a file sys- tem, or to attempt to start a volume that has no plexes with valid data. Pass in usage-type-specific options to the operation. By con- vention, the following usage-type-specific options should be imple- mented by all usage types: Perform any extended revive operations in background processes after the volume and one or more plexes have been enabled. A volume that is started or whose length is changed success- fully with this option will be usable immediately after the operation completes, although recovery operations may affect performance of the volume for an extended period of time. Perform up to the specified number of plex revive operations simultaneously. If no count is speci- fied, then a suitable small number is used (normally 10). Do not per- form any plex revive operations when starting a volume. Simply enable the volume and any plexes. This may leave some stale plexes, and may leave a mirrored volume in a special read-writeback (NEEDSYNC) recover state that performs limited plex recovery for each read to the volume. Reduce the system performance impact of plex recovery operations and volume length changes. Startup recovery and length change consistency operations are usually a set of short operations on small regions of the volume (normally from 16K bytes to 128K bytes). This option in- serts a delay between the recovery of each such region. A specific de- lay can be specified with iodelay as a number of milliseconds, or else a default is chosen (normally 250 milliseconds). Perform recovery op- erations in regions with the length specified by size, which is a stan- dard Logical Storage Manager length number (see volintro(8)). Specify- ing a larger number typically causes the operation to complete sooner, but with greater impact on other processes using the volume. The de- fault I/O size is typically 32 kilobytes. Print a message for each volume that is successfully started. Without this option, messages ap- pear only for volumes that fail to start. FSGEN AND GEN USAGE TYPES The fsgen and gen usage types provide the same semantics for all opera- tions of the volume utility. However, some options are provided only by the gen usage type. In addition to the standard -o options required for all usage types, the fsgen and gen usage types provide the following additional options: Force an operation that is not normally performed as part of the opera- tional model of the Logical Storage Manager and may have adverse ef- fects on data. This is the same as -f. This can only be used with the gen usage type. Prevent the start operation from recovering plexes through the volplex utility. Instead, all STALE and ACTIVE plexes are simply treated as equivalent to CLEAN plexes, and are thus enabled without being made consistent. This can be used for volumes whose con- tents are recreated for each use. An example of a possible use for this attribute is a swap area and the /tmp file system. In the case of /tmp, the model as- sumes that mkfs is used to create an empty file system after the volume has been started. Limitations and extensions for the fsgen and gen usage types consist of the following: These are the recognized uses of the volume init opera- tion: Set the state for the specified plex to CLEAN, and set all other plexes to STALE. The volume start operation can then be used to re- cover the volume from the CLEAN plex. This operation requires that the volume not be enabled. If the specified volume has only one plex, then the plex argu- ment is not required as it defaults to that plex. If specified, then the plex argument must represent a plex that is associated with the volume. Set the state for all plexes associated with volume to ACTIVE and enable the volume and its plexes. This is used to initialize a single or multiple-plex volume where all plexes are known to have identical contents. Enable the volume and its plexes but leave the volume uninitialized. This opera- tion can be used only for non-enabled volumes. It is used to temporarily enable a volume so that data can be loaded onto it to make it consistent. Once the data has been loaded, init ac- tive should be used to fully enable the volume. init active could be used, for example, if a complete image of the volume is to be loaded from a tape. Write zero blocks to all plexes in the volume, up to the length of the volume. After the writes complete, the state of each plex is set to ACTIVE and the volume and its plexes are enabled. init zero volume could be used, for example, before running mkfs A to put a file system on the vol- ume. If this operation is interrupted by a signal, then an attempt is made to restore all affected records to their original state, or to a state that is roughly equivalent to their original state. If this attempt is interrupted, such as through another signal, then the user many need to perform some cleanup. A set of com- mands to perform this cleanup are written to the standard error before the volume utility exits. Starting an uninitialized gen or fsgen volume enables the volume and its plexes, sets the plexes to the ACTIVE state, and recovers the plexes to ensure that each plex has the same contents. If the volume has only one plex, then the volume is immediately set to the ACTIVE state; otherwise, the volume is set to the SYNC state and a spe- cial read/write-back mode is set to recover regions of the vol- ume on every read operation. The volume is then read from be- ginning to end to make all plexes consistent, then the volume is set to the ACTIVE state. Starting a volume with no active block change log involves en- abling all CLEAN and ACTIVE plexes and putting them in the AC- TIVE state. If an I/O failure was logged against the plex, or if a disk replacement caused a plex to become stale, then the plex is considered STALE. If any of the subdisks for the plex reside on a removed or inaccessible disk, then the plex is ig- nored for the purposes of starting the volume. If two or more plexes were enabled, and if the volume was active at the time the system went down, then the state for the volume is set to SYNC and a special read/write-back recovery mode is used to recover consistency of the volume, segment-by-segment, on every read. A process (in the background with the -o bg op- tion) to recover consistency for the entire length of the volume is then started. If any plexes were considered STALE, then those plexes are at- tached by calling volplex att. The number of concurrent plex attach operations are limited based on the rules for -o plex- fork. Recovery of plexes with a block change log uses the same rules as for volumes without a valid block change log, except that re- covery of non-stale plexes is done in the foreground before the volume can be used, by scanning the contents of the block change log and recovering consistency for those blocks listed in the log as requiring recovery. In addition to enabling the volume and managing the recovery of plex consistency, starting a volume clears any transient opera- tions that were being applied to a volume before the system was rebooted. Starting a volume dissociates and removes temporary plexes or subdisks, and dissociates plexes that were being at- tached if the attach operation did not complete. Snapshot plexes created by volassist are also removed. If the volume is unstartable because there are no valid, non- stale plexes and the -f flag is then specified, all STALE plexes that do not contain unusable subdisks (subdisks on failed or re- moved disks) will be changed to ACTIVE. The volume will then be started and synchronized from those plexes. Stopping an fsgen or gen volume disables the volume and its associated plexes. In addition, the utility state for each ACTIVE plex is changed as follows: If the plex is detached or disabled, set the state for the plex to STALE. If all plexes are set to STALE, then the volume cannot be started until volmend is used to change the state of one or more plexes to CLEAN or ACTIVE. A plex normally becomes detached as a result of an I/O error on the plex, or a disk failure or replacement. I/O failures will not normally de- tach the last remaining enabled plex in a volume, so disk re- moval operations are the only normal operational method of mak- ing a volume unstartable. If the plex is volatile, i.e., one of the subdisks in the plex is defined on a disk with the volatile attribute (see voldisk(8)), then set the plex state to STALE. If the volume is enabled and the plex is also enabled, then set the plex state to CLEAN. If the volume is detached and the plex is enabled, then the plex state is left as ACTIVE. A volume can be left detached, with remaining valid plexes, only as a result of calling volume maint to detach an enabled volume. Normally, the stop operation fails if any extended operations are using the volume or any of its associated plexes. Such op- erations are detected as a nonempty value for the tutil0 field in a volume or plex record. If the -f option is specified, then the stop operation ignores volume and plex tutil0 fields. The -f option must also be given to force the stopping of a vol- ume that is open or mounted as a file system. In this case, a warning message is still written to the standard error, but the stop operation is not otherwise affected. Stopping an open or mounted volume is not normally advisable. The -f option is re- quired to detach an enabled volume. Also, a warning is written to the standard error for volumes that are open or mounted. The attributes that can be changed are: Change the length of each volume specified by the volume operands to be number sectors. The number is a standard Logical Storage Manager length number (see volintro(8)). Decreasing the length of a volume requires -f. If the volume is enabled, then count the number of enabled, read-write plexes that would remain complete after the length change. The operation fails if this number would become zero, but the number of sparse plexes would become greater than 1. Changing the length of a volume with one enabled plex beyond the length of the plex requires use of the -f option. If the volume is not enabled, count the number of CLEAN and AC- TIVE plexes that would remain complete after the length change, then use the algorithm mentioned above for determining whether the operation is allowed or requires use of -f. In order to ensure that the new region of the volume is consis- tent across all plexes of the volume, the volume is put into a SYNC state and read/write-back mode, and a read loop is now per- formed against the volume. Once this loop has completed, the volume is put back into the ACTIVE state. Set the type of log- ging to be used on the volume. This change can be applied only to volumes that are stopped and that have no ACTIVE plexes. Al- lowed log types are blkno (logs the blocks involved in all vol- ume writes), none (never does logging), and undef (never does logging). If the logging type is set to undef, then a future volsd aslog or volplex att operation will change it to blkno. See the fsgen and gen sections of volsd(8) and volplex(8) for more information. Set the size for logs used with the volume. If the logging type is blkno, then this value must be 1 sector. Future logging types may allow larger log sizes. The size value is a standard Logical Storage Manager length number (see volin- tro(8)). Set options that are applied to the volume every time the volume is started, independently of options specified with the volume start command. This is a set of comma-separated op- tions of the same form used with the -o option letter. At the present time, only the noattach and verbose options can be ap- plied to volumes in this manner. Unrecognized or inappropriate options are ignored. FILES The utility that performs volume operations for a particular volume us- age type. The device node that can be used for mounting a file system created on the volume named volume in the disk group named group. Vol- umes in group rootdg are also directly under the /dev/vol directory. The device node that can be used for issuing raw I/O requests and also for issuing ioctl requests to the volume named volume in disk group named group. Volumes in group rootdg are also directly under the /dev/rvol directory. The device node for accessing a plex named plex in disk group named group. A plex device is accessible only if it is not disabled and if it is associated with a volume that is not dis- abled. Plexes in group rootdg are also directly under the /dev/plex directory. EXIT CODES The volume utility exits with a nonzero status if the attempted opera- tion fails. A nonzero exit code is not a complete indicator of the problems encountered, but rather denotes the first condition that pre- vented further execution of the utility. See volintro(8) for a list of standard exit codes. RELATED INFORMATION Commands: volintro(8), volassist(8), volinfo(8), volmend(8), vol- plex(8), volrecover(8). delim off volume(8)