# man vxintro Reformatting page. Wait... done Maintenance Commands vxintro(1M) NAME vxintro - introduction to Volume Manager utilities SYNOPSIS vxassist, vxconfigd, vxdctl, vxdg, vxdisk, vxedit, vxinfo, vxiod, vxmake, vxmend, vxplex, vxprint, vxrecover, vxsd, vxstat, vxtrace, vxvol DESCRIPTION The Volume Manager utilities provide a shell-level interface for use by system administrators and high-level applications and scripts to query and manipulate objects managed through the VERITAS Volume Manager (VxVMO). GLOSSARY concatenated plex A plex whose subdisks are associated at specific offsets within the address range of the plex, and extend into the plex address range for the length of the subdisk. This layout allows regions of one or more disks to create a plex, rather than a sin- gle big region. disk Disks exist as two entities. One is the physical disk on which all data is ultimately stored and which exhibits all the behaviors of the underlying technology. The other is the Volume Manager presentation of disks which, while mapping one- to-one with the physical disks, are just presenta- tions of units from which allocations of storage are made. As an example, a physical disk presents the image of a device with a definable geometry with a definable number of cylinders, heads etc. whereas a Volume Manager disk is simply a unit of allocation with a name and a size. disk access record A configuration record that defines a pathway to a disk. The disk access records most commonly name a particular controller number, target ID, and logical unit number. The list of all disk access records stored in a system is used to find all disks attached to the system. Disk access records do not identify particular physical disks. Disk access records are identified by their disk access names (also known as DA names). Through the use of disk IDs, the Volume Manager allows disks to be moved between controllers, or to different locations on a controller. When a disk is moved, a different disk access record will VxVM 3.0 Last change: 11 Dec 1998 1 Maintenance Commands vxintro(1M) be used when accessing the disk, although the disk media record will continue to track the actual physical disk. On some systems, the Volume Manager will build a list of disk access records automatically, based on the list of all devices attached to the system. On these systems, it is not necessary to define disk access records explicitly. On other systems, disk access records must be defined explicitly with the vxdisk define operation. Specialty disks (such as RAM disks or floppy disks) are likely to require explicit vxdisk define operations on all systems. disk group A group of disks that share a common configura- tion. A configuration consists of a set of records describing objects (including disks, volumes, plexes, and subdisks) that are associated with one particular disk group. Each disk group has an administrator-assigned name that can be used by the administrator to reference that disk group. Each disk group has an internally defined unique disk group ID, which is used to differen- tiate two disk groups with the same administrator-assigned name. Disk groups provide a method to partition the con- figuration database, so that the database size is not too large and so that database modifications do not affect too many drives. They also allow the Volume Manager to operate with groups of phy- sical disk media that can be moved between sys- tems. Disks and disk groups have a circular relation- ship: disk groups are formed from disks, and disk group configurations are stored on disks. All disks in a disk group are stamped with a disk group ID, which is a unique identifier for naming disk groups. Some or all disks in a disk group also store copies of the configuration database of the disk group. disk group configuration A disk group configuration is a small database that contains all volume, plex, subdisk, and disk media records. These configurations are repli- cated onto some or all disks in the disk group, usually with one copy on each disk. Because these databases are stored within disk groups, record VxVM 3.0 Last change: 11 Dec 1998 2 Maintenance Commands vxintro(1M) associations cannot span disk groups. Thus, a subdisk defined on a disk in one disk group cannot be associated with a volume in another disk group. disk header A block stored in a private region of a disk and that defines several properties of the disk. The disk header defines the size of the private region, the location and size of the public region, the unique disk ID for the disk, the disk group ID and disk group name (if the disk is currently associated with a disk group), and the host ID for a host that has exclusive use of the disk. disk ID A 64-byte universally unique identifier that is assigned to a physical disk when its private region is initialized with the vxdisk init opera- tion. The disk ID is stored in the disk media record so that the physical disk can be related to the disk media record at system startup. disk media record A reference to a physical disk or a disk partition This record can be thought of as a physical disk identifier for the disk or partition Disk media records are configuration records that provide a name (known as the disk media name or DM name) that you can use to reference a particular disk, independent of its location on the system's vari- ous disk controllers. Disk media records refer- ence particular physical disks through a disk ID, which is a unique identifier that is assigned to a disk when it is initialized for use with the Volume Manager. Operations are provided to set or remove the disk ID stored in a disk media record. Such operations have the effect of removing or replacing disks, with any associated subdisks being removed or replaced along with the disk. host ID A name, usually assigned by the administrator, that identifies a particular host. Host IDs are used to assign ownership to particular physical disks. When a disk is part of a disk group that is in active use by a particular host, the disk is stamped with that host's host ID. If another sys- tem attempts to access the disk, it will detect that the disk has a non-matching host ID and will disallow access until the first system discontin- ues use of the disk. To allow for system failures VxVM 3.0 Last change: 11 Dec 1998 3 Maintenance Commands vxintro(1M) that do not clear the host ID, the vxdisk clearim- port operation can be used to clear the host ID stored on a disk. If a disk is a member of a disk group and has a host ID that matches a particular host, then that host will import the disk group as part of system startup. kernel log A log kept in the private region on the disk and that is written by the Volume Manager kernel. The log contains records describing the state of volumes in the disk group. This log provides a mechanism for the kernel to persistently register state changes so that vxconfigd can be guaranteed to detect the state changes even in the event of a system failure. plex A copy of a volume's logical data address space, also called a mirror. A volume can have up to 32 plexes associated with it. Each plex is, at least conceptually, a copy of the volume that is main- tained consistently in the presence of volume I/O and reconfigurations. Plexes represent the pri- mary means of configuring storage for a volume. Plexes can have a striped, concatenated, or RAID-5 organization (layout). plex consistency If the plexes of a volume contain different data, then the plexes are said to be inconsistent. This is only a problem if the Volume Manager is unaware of the inconsistencies, as the volume can return differing results for consecutive reads. Plex inconsistency is a serious compromise of data integrity. This inconsistency can be caused by write operations that start around the time of a system failure, if parts of the write complete on one plex but not the other. Plexes can also be inconsistent after creation of a mirrored volume, if the plexes are not first synchronized to con- tain the same data. An important part of Volume Manager operation is ensuring that consistent data is returned to any application that reads a volume. This may require that plex consistency of a volume be ``recovered'' by copying data between plexes so that they have the same contents. Alternatively, the volume can be put into a state such that reads from one plex are automatically written back to the other plexes, thus making the data consistent for that volume offset. VxVM 3.0 Last change: 11 Dec 1998 4 Maintenance Commands vxintro(1M) private region Disks used by the Volume Manager contain two spe- cial regions: a private region and a public region. Usually, each region is formed from a com- plete partition of the disk; however, the private and public regions can be allocated from the same partition. The private region of a disk contains various on- disk structures that are used by the Volume Manager for various internal purposes. Each private region begins with a disk header which identifies the disk and its disk group. Private regions can also contain copies of a disk group's configuration, and copies of the disk group's ker- nel log. public region The public region of a disk is the space reserved for allocating subdisks. Subdisks are defined with offsets that are relative to the beginning of the public region of a particular disk. Only one contiguous region of disk can form the public region for a particular disk. root disk group Each system requires one special disk group, named rootdg, which is generally the default for most utilities. In addition to defining the regular disk group information, the configuration for the root disk group (rootdg) contains local informa- tion that is specific to a disk group and that is not intended to be movable between systems. striped plex A plex that scatters data evenly across each of its associated subdisks. A plex has a charac- teristic number of stripe columns (consisting of associated subdisks) and a characteristic stripe unit size. The stripe unit size defines how data with a particular address is allocated to one of the associated subdisks. Given a stripe unit size of 128 blocks, and two stripe columns, the first group of 128 blocks would be allocated to the first subdisk, the second group of 128 blocks would be allocated to the second subdisk, the third group to the first subdisk, again, and so on. subdisk A region of storage allocated on a disk for use with a volume. Subdisks are associated to volumes through plexes. One or more subdisks are laid out VxVM 3.0 Last change: 11 Dec 1998 5 Maintenance Commands vxintro(1M) to form plexes based on the plex layout (striped, concatenated, or RAID-5). Subdisks are defined relative to disk media records. volboot file The volboot file is a special file (usually stored in /etc/vx/volboot) that is used to bootstrap the root disk group and to define a system's host ID. In addition to a host ID, the volboot file con- tains a list of disk access records. On system startup, this list of disks is scanned to find a disk that is a member of the rootdg disk group and that is stamped with this system's host ID. When such a disk is found, its configuration is read and is used to get a more complete list of disk access records that are used as a second-stage bootstrap of the root disk group, and to locate all other disk groups. volume A virtual disk device that looks to applications and file systems like a regular disk partition device. Volumes present block and raw device interfaces that are compatible in their use with disk partition devices. However, a volume is a virtual device that can be mirrored, spanned across disk drives, moved to use different storage, and striped using administrative com- mands. The configuration of a volume can be changed, using the Volume Manager utilities, without causing disruption to applications or file systems that are using the volume. CONVENTIONS The VERITAS Volume Manager employs certain conventions to provide a degree of similarity between various operations. The conventions are used in the following areas: o Disk Group Selection o Standard Length Numbers o Command Syntax Disk Group Selection Most commands operate upon only one disk group per invoca- tion. Each disk group has a separate configuration from VxVM 3.0 Last change: 11 Dec 1998 6 Maintenance Commands vxintro(1M) every other disk group and it is possible for two disk groups to contain two objects that have the same name. This can happen, in particular, if a disk group is moved from one system to another. However, most utilities make no attempt to ensure that names between disk groups are unique, so name collisions can occur. System administrators who try to avoid name collisions should be able to use most of the utilities without having to specify disk groups except when creating objects. Administrators cannot use single-command invocations that reference objects in more than one disk group, but disk groups will be selected automatically, based on objects specified in the command. The standard rules that most commands use for selecting the disk group for a command are as follows: o Given a particular set of object names specified on the command, look for the disk group of each object. If all objects are in the same disk group, use that disk group. If any named object is not unique between all disk groups, and if one of those object names is not in the rootdg disk group, then fail. o To force use of a particular disk group, use -g diskgroup to indicate the group. Non-unique names do not cause errors when a disk group is specified explicitly. The diskgroup specification is either a disk group ID or a disk group name. o A special case is provided for the rootdg disk group. Any set of objects in the rootdg disk group can be speci- fied without specifying -g rootdg, even if the given object name is used in another disk group. If a set of object names is given on the command line, and if some are unique but some are not unique, then the command will still fail according to the rules listed above. Standard Length Numbers Many basic properties of objects that are managed by the Volume Manager require specification of lengths, either as a pure object length or as an offset relative to some other object. The Volume Manager supports volume lengths up to 2,147,483,647 disk sectors (one terabyte on most systems). Typing such large numbers, or even much smaller numbers, can VxVM 3.0 Last change: 11 Dec 1998 7 Maintenance Commands vxintro(1M) be annoying. The Volume Manager provides a uniform syntax for representing such numbers, and uses suffixes to provide convenient multipliers. Numbers can be specified in decimal, octal, or hexadecimal. Also, numbers can be speci- fied as a sum of several numbers, as a convenience to avoid using a calculator. A hexadecimal (base 16) number is introduced using a prefix of 0x. For example, 0xfff is the same as decimal 4095. An octal (base 8) number is introduced using a prefix of 0. For example, 0177777 is the same as decimal 65535. A number can be followed by a suffix character to indicate a multiplier for the number. A length number with no suffix character represents a count of standard disk sectors. The length of a standard disk sector can vary between systems; it is commonly 512 bytes or 1024 bytes. On systems where disks can have different sector sizes, one of the sector sizes will be chosen as the ``standard'' size. Supported suffix characters are: b Multiply the length by 512 bytes (blocks) s Multiply the length by the standard sector size (default) k Multiply the length by 1024 bytes (Kilobytes) m Multiply the length by 1,048,576 (1024K) bytes (Megabytes) g Multiply the length by 1,073,741,824 (1024M) bytes (Gigabytes) Numbers are represented internally as an integer number of sectors. As a result, if the standard disk sector size is larger than 512 bytes, numbers can be specified that will need to be rounded to a sector. Rounding is always done to the next lowest, not the nearest, multiple of the sector size. Because the letter b is a valid hexadecimal character, there is a special case for the b suffix where a single blank character can separate a number from the b suffix character. Use of a blank within a number, when invoking commands from the shell, usually requires quoting the number. For exam- ple: vxassist make vol01 "0x1000 b" Numbers can be added or subtracted by separating two or more numbers by a plus or minus sign, respectively. A plus sign VxVM 3.0 Last change: 11 Dec 1998 8 Maintenance Commands vxintro(1M) is optional. As an example, the largest allowed number that can be represented on a system with a 512 byte sector size can be entered as: 1023g+1023m+1023k+1 Note that 1024g-1 cannot be used, because the implementation cannot handle the intermediate representation of 1024g (which is greater than the largest number that can be represented) internally. In output, the Volume Manager reports length numbers as a simple count of sectors, with no suffix character. Case is ignored in length specification. Hexadecimal numbers and suffix characters can be specified using any reasonable combination of uppercase and lowercase letters. Utility Syntax Most utilities in the Volume Manager provide more than one operation, with operations grouped into utilities primarily by object type. Utilities that provide multiple operations are typically invoked with the following form: utility_name [ options ] keyword [ operands ] utility_name is the name of the Volume Manager command and keyword specifies the specific operation to perform. Any options that are introduced in the standard -letter form precede the operation keyword. This is in keeping with standard System V UNIX utility syntax, which provides for a set of options as the first arguments to a command, followed by any non-option operands. The keyword is considered an operand under standard System V syntax. All of the utilities provide an extended usage message that lists all the options and operation keywords supported by the utility. For utilities that are keyword-based, this extended usage message can be displayed using the keyword help. Utilities that use operands for purposes other than operation selection provide a reserved option of -H to display the extended usage information. RECORD TYPES Disk group configurations contain six types of records: o Disk Access Records o Disk Group Records VxVM 3.0 Last change: 11 Dec 1998 9 Maintenance Commands vxintro(1M) o Disk Media Records o Plex Records o Subdisk Records o Volume Records Disk access records are specific to the root disk group and are stored in configurations only because there is no other convenient place to store them; otherwise, they are logi- cally separate from all disk groups. Because they are specific and meaningful to the local system only, the logi- cal place for their storage is the rootdg since that is the only disk group guaranteed to exist on the system. Disk Access Records Disk access records define an address, or access path, that can be used to access a disk. The list of all disk access records defines the list of all disk addresses that the Volume Manager can use to locate physical disks. Disk access records do not define specific physical disks, since physical disks can be moved on a system. When a physical disk is moved, a different disk access record may be neces- sary to locate it. Disk access records are stored in the rootdg disk group con- figuration. Unlike all other record types, the names of disk access records can conflict with the names of other records. For example, a specialty disk (such as a RAM disk) can use the same name for both the disk access record and the disk media record that points to it. It is typically advisable to use different names for the access and media records, to avoid additional confusion if disks are moved. Disk access records can be defined explicitly. Some (some- times all) disk access records may be configured automati- cally by the Volume Manager, based on available information in the operating system. Such automatically-configured disks are not stored persistently in the on-disk root disk group configuration, but are instead regenerated every time the Volume Manager starts up. VxVM 3.0 Last change: 11 Dec 1998 10 Maintenance Commands vxintro(1M) Disk access records have the following fundamental attri- butes: disk access name The name of the disk access record is typically a disk address. Disk access names are usually of the form c#t#d#s2, indicating use of the entire disk on controller c#, with SCSI target ID t#, and logical unit d#. The s2 suffix is used as a con- vention indicating the use of standard partition- ing. Other systems are likely to have different conventions for the disk access name. type Each disk access record has a type, which identi- fies key characteristics of the Volume Manager's interaction with the disk. Available types are: sliced, simple, and nopriv. See vxdisk(1M) for more information on disk types. Typically, most or all of the disks will be of type sliced. It may be desirable to create specialty disks (such as RAM disks) with type nopriv. If the physical disk represented by the disk access record is associated with a disk media record, then the following fields are defined: disk group name The name of the disk group containing the disk media record. disk media name The name of the disk media record that points to the physical disk. Additional attributes can be added, arbitrarily, by disk types. See vxdisk(1M) for a list of additional attributes defined by the standard disk types. Disk Group Records Disk group records define several different types of names for a disk group. The different types of names are: alias name This is the standard name that the system uses when referencing the disk group. References to the disk group name usually mean the alias name. Volume directories are structured into subdirec- tories based on the disk group alias name. Typi- cally, the disk group's alias name and real name are identical. A local alias can be useful for gaining access to a disk group with a name that conflicts with other disk groups in the system, or VxVM 3.0 Last change: 11 Dec 1998 11 Maintenance Commands vxintro(1M) that conflicts with records in the rootdg disk group. disk group ID A 64-byte identifier that represents the unique ID of the disk group. All disk groups on all systems should have a different disk group ID, even if they have the same real name. This identifier is stored in the disk headers of all disks in the disk group. It is used to ensure that the Volume Manager does not confuse two disk groups which were created with the same name. real name This is the name of the disk group, as defined on disk. This name is stored in the disk group con- figuration, and is also stored in the disk headers of all disks in the disk group. Disk Media Records Disk media records define a specific disk within a disk group. The name of a disk media record (the disk media name) is assigned when a disk is first added to a disk group (using the vxdg adddisk operation). Disk media records can be assigned to specific physical disks by associating the disk media record with the current disk access record for the physical disk. Disk media records have the following fundamental attri- butes: disk access name The disk access name that is currently used to access the physical disk referenced by the disk ID. If the disk ID is defined, but no physical disk with that ID could be found, the disk access name will be clear. A disk where the physical disk could not be found is considered to be in the NODAREC, or inaccessible, state. A disk can become inaccessible either because the indicated disk is not currently attached to the system, or because I/O failures on the physical disk prevented the Volume Manager from identifying or using the physical disk. disk ID A 64-byte unique identifier representing the phy- sical disk to which the media record is associ- ated. This can be cleared to indicate that the disk is considered in the removed state. A removed disk has no current association with any physical disk. VxVM 3.0 Last change: 11 Dec 1998 12 Maintenance Commands vxintro(1M) A disk media record that has an active association with a physical disk (both the disk ID and the disk access name attributes are defined), inherits several properties from the underlying physical disk. These attributes are taken from the disk header, which is stored in the private region of the the disk. These inherited attributes are: atomic I/O size This is the fundamental I/O size for the disk, in bytes, also known as the sector size. All I/Os destined for this disk must be multiples of this size. Currently, the Volume Manager requires that all disks have the same sector size. On most sys- tems, this size is 512 bytes. private length The length of the region of the physical disk that is reserved for storing private Volume Manager information. public length The length of the region of the physical disk that is available for subdisk allocations. Plex Records Plex records define the characteristics of a particular plex of a volume. A plex can be in either an associated state or a dissociated state. In the dissociated state, the plex is not a part of a volume. A dissociated plex cannot be accessed in any way. An associated plex can be accessed through the volume. Plexes have the following fundamental attributes: comment An administrator-assigned string of up to 40 char- acters that can be set and changed using the vxedit utility. The Volume Manager does not interpret the comment field. The comment cannot contain newline characters. condition flags Various condition flags are defined for the plex that define state which is recognized automati- cally, rather than managed by the volume usage type. Defined flags are: IOFAIL The plex was detached as a result of an I/O failure detected during normal volume I/O. The plex is out-of-date with respect to the volume, and in need of complete recovery. However, this condition also indicates a likelihood VxVM 3.0 Last change: 11 Dec 1998 13 Maintenance Commands vxintro(1M) that one of the disks in the system should be replaced. NODAREC No physical disk could be found corresponding to the disk ID in the disk media record for one of the subdisks associated with the plex. The plex can- not be used until the condition is fixed or the affected subdisk is dissociated. RECOVER A disk for one of the disk media records was replaced or was reattached too late to prevent the plex from becoming out- of-date with respect to the volume. The plex requires complete recovery from another plex in the volume to synchron- ize the plex with the correct contents of the volume. REMOVED One of the disk media records was put into the removed state through explicit administrative action. The plex cannot be used until the disk is replaced or the affected subdisk is dissociated. contiguous length The offset of the first block in the plex address space that is not backed by a subdisk. If the plex has no holes, the contiguous length matches the plex length. If the contiguous length is equal to or greater than the length of the associ- ated volume, the plex is considered complete, oth- erwise it is sparse. I/O mode Each plex is in read-write, read-only, or write- only mode. This mode affects read and write operations directed to the volume, if the plex is enabled. For read-write and read-only modes, volume read operations can be directed to the plex. For read-write and write-only modes, volume write operations are directed to the plex. Plexes are normally in read-write mode. Write- only mode is used to recover a plex that failed, and whose contents have thus become out-of-date with respect to the volume. It is also used when attaching a new plex to a volume. In write-only mode, writes to the volume will update the plex, causing written regions to be up-to-date. Typi- cally, a set of special copy operations will be used to update the remainder of the plex. VxVM 3.0 Last change: 11 Dec 1998 14 Maintenance Commands vxintro(1M) layout The organization of associated subdisks with respect to the plex address space. The layout is striped, concatenated, or RAID-5. length The length of a plex is the offset of the last subdisk in the plex plus the length of that sub- disk. In other words, the length of the plex is defined by the last block in the plex address space that is backed by a subdisk. This value may or may not relate to the length of the volume, depending on whether the plex is completely con- tiguously allocated. log subdisk Each plex can have at most one associated log sub- disk. A log subdisk is used with the dirty region logging feature to improve the time required to recover consistency of a volume after a system failure. plex state Each plex is either enabled, disabled, or detached. When enabled, normal read and write operations from the volume can be directed to the plex. When disabled, no I/O operations will be applied to the plex. When detached, normal volume I/O will not be directed to the plex. I/O failures encountered during normal volume I/O may move the enabled state for a plex directly from enabled to detached. See the description of volume exception policies (earlier in this manual page) for more information. subdisks Each plex has zero or more associated subdisks. Subdisks are associated at offsets relative to the beginning of the plex address space. Subdisks for concatenated plexes may not cover the entire length of the plex, in which case they leave holes in the plex. A plex that is not as long as the volume to which it is associated is considered to have a hole extending from the end of the plex to the end of the volume. A plex with a hole is con- sidered incomplete, and is sometimes called sparse. usage-type state Volume usage types maintain a private state field related to the the operations that have been per- formed on the plex, or to failure conditions that have been encountered. This state field contains a string of up to 14 characters. VxVM 3.0 Last change: 11 Dec 1998 15 Maintenance Commands vxintro(1M) volatile state A plex is considered to have ``volatile'' contents if the disk for any of the plex's subdisks is con- sidered to be volatile. The contents of a vola- tile disk are not presumed to survive a system reboot. The contents of a volatile plex are always considered out-of-date after a recovery and in need of complete recovery from another plex. Subdisk Records Subdisk records define a region of disk, allocated from a disk's public region. Subdisks have very little state asso- ciated with them, other than the configuration state that defines which region of disk the subdisk occupies. Subdisks cannot overlap each other, either in their associations with plexes, or in their arrangement on disk public regions. Subdisks have the following fundamental attributes: comment An administrator-assigned string of up to 40 char- acters that can be set and changed using the vxedit utility. The Volume Manager does not interpret the comment field. The comment cannot contain newline characters. disk media name The name of the disk media record that the subdisk is defined on. disk offset The offset, from the beginning of the disk's pub- lic region, to the start of the subdisk. length The length of the subdisk. plex offset For associated subdisks, this is the offset (from the beginning of the plex) of the subdisk associa- tion. For subdisks associated with striped plexes, the plex offset defines relative ordering of subdisks in the plex, rather than actual offsets within the plex address space. Volume Records Volume records define the characteristics of particular volume devices. The name of a volume record defines the node name used for files in the /dev/vx/dsk and /dev/vx/rdsk directories. The block device for a particular volume (which can be used as an argument to the mount command (see mount(1M)) has the path: VxVM 3.0 Last change: 11 Dec 1998 16 Maintenance Commands vxintro(1M) /dev/vx/dsk/groupname/volume where groupname is the name assigned by the administrator to the disk group containing the volume. The raw device for a volume, typically used for application I/O and for issuing I/O control operations (see ioctl(2)), has the path: /dev/vx/rdsk/groupname/volume For convenience, volumes assigned to the root disk group are accessible under the rootdg subdirectories of /dev/vx/dsk and /dev/vx/rdsk, but are also under /dev/vx/dsk/volume and /dev/vx/rdsk/volume. Reads to a volume device are directed to one of the read- write or read-only plexes associated with the volume. Writes to the volume are directed to all of the enabled read-write and write-only plexes associated with the volume. During a write operation, two plexes of a volume may become out of sync with each other, due to the fact that writes directed to two disks can complete at different times. This is not normally a problem. However, if the system were to crash or lose power during a write operation, the two plexes could have different contents. Most applications and file systems are not written with the presumption that two separate reads of a device can return different contents without an intervening write operation. Since plexes with different contents could cause such a situation where two read operations of a block return dif- ferent contents, the Volume Manager expends considerable effort to ensure that this is avoided. Volumes have the following fundamental attributes: comment An administrator-assigned string of up to 40 char- acters that can be set and changed using the vxedit utility. The Volume Manager does not interpret the comment field. The comment cannot contain newline characters. exception policy There are several modes that can be set on the volume, by utilities according to the usage type of the volume. These modes affect operation of a volume in the presence of I/O failures. Currently only one of these policies, called GEN_DET_SPARSE is ever used. This policy tracks complete and incomplete plexes in a volume (an incomplete plex does not have a backing subdisk for all blocks in the volume). If an unrecoverable error occurs on VxVM 3.0 Last change: 11 Dec 1998 17 Maintenance Commands vxintro(1M) an incomplete plex, the plex is detached (disabled from receiving regular volume I/O requests). If an unrecoverable error occurs on a complete plex, the plex is detached unless it is the last com- plete plex. If the plex is the last complete read-write plex, any incomplete plexes that over- lap with the error will be detached but the plex with the error will remain attached. This default policy is chosen to ensure that an I/O that fails on one plex will not, in the future, be directed to that plex again unless that plex is the last complete plex remaining attached to the volume. In that case, the policy ensures that the volume will return the error con- sistently, even in the presence of incomplete plexes. length Each volume has a length, which defines the limit- ing offset of read and write operations. The length is assigned by the administrator, and may or may not match the lengths of the associated plexes. log type A policy to use for logging changes to the volume, which can be assigned by the administrator. Poli- cies that can be specified are: none Do not perform any special actions when writing to the volume. Just write the requested data to all read-write or write-only plexes. dirty-region-log A volume is divided into regions. A bit- map where each bit corresponds to a region is maintained. When a write to a particular region occurs, the respective bit is set to on. When the system is restarted after a crash, this region bitmap is used to limit the amount of data copying that is required to recover plex consistency for the volume. The region changes are logged to special log subdisks associated with each of the plexes associated with the volume. Use of dirty region logging can greatly speed recovery of a volume, but it also degrades performance of the volume under normal operation. plexes Each volume has between zero and 32 associated VxVM 3.0 Last change: 11 Dec 1998 18 Maintenance Commands vxintro(1M) plexes. read policy A configurable policy for switching between plexes for volume reads. When a volume has more than one enabled associated plex, the Volume Manager can distribute reads between the plexes to distribute the I/O load and thus increase total possible bandwidth of reads through the volume. The read policy can be set by the administrator. Possible policies are: preferred plex This read policy specifies a particular named plex that is used to satisfy read requests. In the event that a read request cannot be satisfied by the pre- ferred plex, this policy changes to round-robin. round-robin For every other read operation, distri- bute the operation across all of the available plexes. Given three plexes, this will switch between each of the three plexes, so each plex gets one third of the read requests. select This read policy is the default policy, and adjusts to use an appropriate read policy based on the set of plexes asso- ciated with the volume. If exactly one enabled read-write striped plex is asso- ciated with the volume, then that plex is chosen automatically as the preferred plex; otherwise, the round-robin policy is used. If a volume has one striped plex and one non-striped plex, prefer- ring the striped plex often yields better throughput. read/write-back recover mode This is a mode that applies to the volume, which is managed by utilities as part of plex con- sistency recovery. When this mode is enabled, each read operation will recover plex consistency for the region covered by the read. Plex con- sistency is recovered by reading data from blocks of one plex and writing that data to all other writable plexes. This ensures that a future read operation covering the same range of blocks will read the same data. VxVM 3.0 Last change: 11 Dec 1998 19 Maintenance Commands vxintro(1M) start options This is a string that is organized as a set of usage-type options to apply when starting (ena- bling) a volume. See vxvol(1M) for details. usage type Each volume has a usage type, which defines a par- ticular class of rules for operating on the volume, typically based on the expected content of the volume. Several utilities can apply exten- sions or limitations that apply to volumes with a particular usage type. Several usage types are included with the base release of the Volume Manager: fsgen, for use with volumes that contain file systems; gen, for use with volumes that are used as swap devices or for other applications that do not use file systems; and special root and swap usage types which are specifically for use with the root file system volume and the primary swap device. usage-type state Usage types maintain a private state field related to the volume that relate to operations that have been performed on the volume, or to failure condi- tions that have been encountered. This state field contains a string of up to 14 characters. user|group|mode These attributes are the user, group, and file permission modes used for the volume device nodes. The user and group are normally root. The mode usually allows read and write permission to the owner, and no access by other users. volume state Each volume is either enabled, disabled, or detached. When enabled, normal read and write operations are allowed on the volume, and any file system residing on the volume can be mounted, or used in the usual way. When disabled, no access to the volume or any of its associated plexes is allowed. write-back-on-read-failure mode This is a mode that applies to the volume, which can be enabled or disabled by the administrator using vxedit. If this mode is enabled, then a read failure for a plex will cause data to be read from an alternate plex and then written back to the plex that got the read failure. This will usually fix the error. Only if the writeback VxVM 3.0 Last change: 11 Dec 1998 20 Maintenance Commands vxintro(1M) fails will the plex be detached for having an unrecoverable I/O failure. writecopy mode This is a mode that applies to the volume, which can be enabled or disabled by the administrator using vxedit. This mode takes affect only if dirty region logging is in effect. When the operating system hands off a write request to the volume driver, the operating system may continue to change the memory that is being written to disk. The Volume Manager cannot detect that the memory is changing, so it can inadvertently leave plexes with inconsistent contents. This is not normally a problem, because the operating system ensures that any such modified memory is rewritten to the volume before the volume is closed (such as by a clean system shutdown). However, if the sys- tem crashes, plexes may be inconsistent. Since the dirty region logging feature prevents recovery of the entire volume, it may not ensure that plexes are entirely consistent. Turning on the writecopy mode (which is normally set by default) often causes the Volume Manager to copy the data for a write request to a new section of memory before writing it to disk. Because the write is done from the copied memory, it cannot change and so the data written to each plex is guaranteed to be the same if the write completes. VOLUME USAGE TYPES The usage type of a volume represents a class of rules for operating on a volume. Each usage type is defined by a set of executables under the directory /etc/vx/type/usage_type, where usage_type is the name given to the usage type. The required executables are: vxinfo, vxmake, vxmend, vxplex, vxsd, and vxvol. These executables are invoked by the Volume Manager administrative utilities with the same names. The executables under /etc/vx/type should not, normally, be executed directly. Five usage types are provided with the Volume Manager: gen, fsgen, root, swap, and raid5. It is possible for third- party products to install additional usage types. The usage types provided with the Volume Manager store state information in the volume and plex usage-type state fields. The state fields defined for volumes are: ACTIVE The volume has been started and is running nor- mally, or was running normally when the system was VxVM 3.0 Last change: 11 Dec 1998 21 Maintenance Commands vxintro(1M) stopped. If the system crashes in this state, then the volume may require plex consistency recovery. CLEAN The volume has been stopped and the contents for all plexes are consistent. EMPTY The volume is not yet initialized. This is the initial state for volumes created by vxmake. NEEDSYNC The volume requires recovery. This is typically set after a system failure to indicate that the plexes in the volume may be inconsistent, so that they require recovery (see the resync operation in vxvol(1M)). SYNC Plex consistency recovery is currently being done on the volume. vxvol resync sets this state when it starts to recovery plex consistency on a volume that was in the NEEDSYNC state. The state fields defined for plexes are: ACTIVE The plex is running normally on a started volume. The plex condition flags (NODAREC, REMOVED, RECOVER, and IOFAIL) may apply if the system is rebooted and the volume restarted. CLEAN The plex was running normally when the volume was stopped. The plex will be enabled without requir- ing recovery when the volume is started. EMPTY The plex is not yet initialized. This state is set when the volume state is also EMPTY. OFFLINE The plex was disabled by the vxmend off operation. See vxmend(1M) for more information. SNAPATT This is a snapshot plex that is being attached by the vxassist snapstart operation. When the attach is complete, the state for the plex will be changed to SNAPDONE. If the system fails before the attach completes, the plex and all of its sub- disks will be removed. SNAPDIS This is a snapshot plex created by vxplex snapstart that is fully attached. A plex in this state can be turned into a snapshot volume with vxplex snapshot. See vxplex(1M) for more informa- tion. If the system fails before the attach com- pletes, the plex will be dissociated from the volume. VxVM 3.0 Last change: 11 Dec 1998 22 Maintenance Commands vxintro(1M) SNAPDONE This is a snapshot plex created by vxassist snapstart that is fully attached. A plex in this state can be turned into a snapshot volume with vxassist snapshot. See vxassist(1M) for more information. If the system fails before the attach completes, the plex and all of its subdisks will be removed. SNAPTMP This is a snapshot plex being attached by the vxplex snapstart operation. When the attach is complete, the state for the plex will be changed to SNAPDIS. If the system fails before the attach completes, the plex will be dissociated from the volume. STALE The plex was detached, either by vxplex det or by an I/O failure. vxvol start will change the state for a plex to STALE if any of the plex condition flags are set. STALE plexes will be reattached automatically, when starting a volume, by calling vxplex att. TEMP This is a plex that is being associated and attached to a volume with vxplex att. If the sys- tem fails before the attach completes the plex will be dissociated from the volume. TEMPRM This is a plex that is being associated and attached to a volume with vxplex att. If the sys- tem fails before the attach completes the plex will be dissociated from the volume and removed. Any subdisks in the plex will be kept. TEMPRMSD This is a plex that is being associated and attached to a volume with vxplex att. If the sys- tem fails before the attach completes, the plex and its subdisks will be dissociated from the volume and removed. EXIT CODES The majority of the Volume Manager utilities use a common set of exit codes, which can be used by shell scripts or other types of programs to react to specific problems detected by the utilities. For C programmers, these exit status codes are defined in the include file volclient.h. The number and macro name for each distinct exit code is described below. Shell script writers must directly compare against the numbers specified. (0) VEX_OK The utility is not reporting any error through the exit code. VxVM 3.0 Last change: 11 Dec 1998 23 Maintenance Commands vxintro(1M) (1) VEX_USAGE Some command line arguments to the utility were invalid. (2) VEX_SYNTAX A syntax error occurred in a command or descrip- tion, or a specified record name is too long or contains invalid characters. This code is returned only by utilities that implement a com- mand or description language. This code may also be returned for errors in search patterns. (3) VEX_NOVOLD The volume daemon does not appear to be running. (4) VEX_IPC An unexpected error was encountered while communi- cating with the volume daemon. (5) VEX_OSERR An unexpected error was returned by a system call or by the C library. This can also indicate that the utility ran out of memory. (6) VEX_LOST The status for a commit was lost because the volume daemon was killed and restarted during the commit of a transaction, but after restart the volume daemon did not know whether the commit suc- ceeded or failed. (7) VEX_UTILERR The utility encountered an error that it should not have encountered. This generally implies a condition that the utility should have tested for but did not, or a condition that results from the volume daemon returning a value that did not make sense. (8) VEX_TIMEOUT The time required to complete a transaction exceeded 60 seconds, causing the transaction locks to be lost. As most utilities will reattempt the transaction at least once if a timeout occurs, this usually implies that a transaction timed out two or more times. (9) VEX_NODG No disk group could be identified for an opera- tion. This results either from naming a disk group that does not exist, or from supplying names on a command line that are in different disk VxVM 3.0 Last change: 11 Dec 1998 24 Maintenance Commands vxintro(1M) groups or in multiple disk groups. (10) VEX_CHANGED A change made to the database by another process caused the utility to stop. This code is also returned by a usage-type-dependent utility if it is given a record that is associated with a dif- ferent usage type. If this situation occurs when the usage-type-dependent utility is called from a switchout utility, then the database was changed after the switchout utility determined the proper usage type to invoke. (11) VEX_NOENT A requested subdisk, plex, or volume record was not found in the configuration database. This may also mean that a record was an inappropriate type. (12) VEX_EXIST A name used to create a new configuration record matches the name of an existing record. (13) VEX_BUSY A subdisk, plex, or volume is locked against con- current access. This code is used for inter- transaction locks associated with usage type util- ities. The code is also used for the dissociated plex or subdisk lock convention, which writes a non-blank string to the tutil[0] field in a plex or subdisk structure to indicate that the record is being used. (14) VEX_NOUSETYPE No usage type could be determined for a utility that requires a usage type. (15) VEX_BADUSETYPE An unknown or invalid usage type was specified. (16) VEX_ASSOC A plex or subdisk is associated, but the operation requires a dissociated record. (17) VEX_DISASSOC A plex or subdisk is dissociated, but the opera- tion requires an associated record. This code can also be used to indicate that a subdisk or plex is not associated with a specific plex or volume. (18) VEX__LAST A plex or subdisk was not dissociated because it was the last record associated with a volume or VxVM 3.0 Last change: 11 Dec 1998 25 Maintenance Commands vxintro(1M) plex. (19) VEX_TOOMANY Association of a plex or subdisk would surpass the maximum number that can be associated to a volume or plex. (20) WVEX_INVAL A specified operation is invalid within the param- eters specified. For example, this code is returned when an attempt is made to split a sub- disk on a striped plex, or to use a split size that is greater than the size of the plex. (21) VEX_IOERR An I/O error was encountered that caused the util- ity to abort an operation. (22) VEX_NOPLEX A volume involved in an operation did not have any associated plexes, although at least one was required. (23) VEX_NOSUBDISK A plex involved in an operation did not have any associated subdisks, although at least one was required. (24) VEX_UNSTARTABLE A volume could not be started by the vxvol start operation, because the configuration of the volume and its plexes prevented the operation. (25) VEX_STARTED A specified volume was already started. (26) VEX_UNSTARTED A specified volume was not started. For example, this code is returned by the vxvol stop operation if the operation is given a volume that is not started. (27) VEX_DETACHED A volume or plex involved in an operation is in the detached state, thus preventing a successful operation. (28) VEX_DISABLED A volume or plex involved in an operation is in the disabled state, thus preventing a successful operation. VxVM 3.0 Last change: 11 Dec 1998 26 Maintenance Commands vxintro(1M) (29) VEX_ENABLED A volume or plex involved in an operation is in the enabled state, thus preventing a successful operation. (30) VEX_UNKNOWN An unknown error was encountered. This code may be used, for example, when the volume daemon returns an unrecognized error number. (31) VEX_OPEN An operation failed because a volume device was open or mounted, or because a subdisk was associ- ated with an open or mounted volume or plex. Exit codes greater than 32 are reserved for use by usage types. Codes greater than 64 can be reserved for use by specific utilities. SEE ALSO mount(1M), vxassist(1M), vxconfigd(1M), vxdctl(1M), vxdg(1M), vxdisk(1M), vxdiskadd(1M), vxdiskadm(1M), vxdisksetup(1M), vxdmpadm(1M), vxedit(1M), vxencap(1M), vxevac(1M), vxinfo(1M), vxiod(1M), vxlicense(1M), vxmake(1M), vxmend(1M), vxmirror(1M), vxnotify(1M), vxplex(1M), vxprint(1M), vxr5check(1M), vxreattach(1M), vxrecover(1M), vxrelayout(1M), vxrelocd(1M), vxresize(1M), vxrootmir(1M), vxsd(1M), vxsparecheck(1M), vxstat(1M), vxtask(1M), vxtrace(1M), vxunroot(1M), vxvol(1M), vxwatch(1M), plexrec(4), sdrec(4), vxrec(4), vxmake(4) For information about other aspects of the Volume Manager, see: vxintro(3X), vxio(7), vxinfo(7) VxVM 3.0 Last change: 11 Dec 1998 27 #