vxdisk(1M) VxVM 3.5 vxdisk(1M)
1 Jun 2002
NAME [Toc] [Back]
vxdisk - define and manage VERITAS Volume Manager disks
SYNOPSIS [Toc] [Back]
vxdisk [-g diskgroup] addregion region_type disk offset length
vxdisk [-g diskgroup] check disk ...
vxdisk clearimport accessname ...
vxdisk [-Bf] define accessname [attribute ...]
vxdisk getctlr accessname
vxdisk [-Bf] init accessname [attribute ...]
vxdisk [-g diskgroup] [-o alldgs] [-qs] list [disk ...]
vxdisk offline accessname ...
vxdisk -a online
vxdisk online accessname ...
vxdisk rm accessname ...
vxdisk [-g diskgroup] rmregion region_type disk offset [length]
vxdisk [-g diskgroup] set disk [attribute ...]
vxdisk scandisks
DESCRIPTION [Toc] [Back]
The vxdisk 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
VERITAS Volume Manager (VxVM).
accessname refers to the disk access name, while disk represents the
disk media name. vxdisk accesses disks based on disk access names,
which are system-specific names that relate to disk addresses. Disk
access names are in the form c#t#d#, which define a controller number
(c#), a SCSI target ID (t#), and a SCSI logical unit number (d#).
Disk access names relate directly to device node names in the /dev/dsk
and /dev/rdsk directories.
VxVM 3.2 introduced enclosure-based naming as an alternative way of
referring to disk access names. If enabled, this scheme maps disk
access names relative to their enclosure. For example, disks in the
enclosure ENC0 would be assigned access names ENC0_0, ENC0_1 and so
on.
- 1 - Formatted: January 24, 2005
vxdisk(1M) VxVM 3.5 vxdisk(1M)
1 Jun 2002
Operations that take an accessname argument (see the SYNOPSIS section)
accept only disk access names, as defined in the previous paragraph.
Operations that take a disk argument can take disk access names or
disk media names (for example, disk01). For such operations, a disk
group can be specified with -g to disambiguate disk media names that
are used in more than one disk group.
Physical disks in VxVM are assumed to be movable, and are usually
identified by a unique disk ID stored on the physical disk, rather
than by a disk device node. This allows disks to be moved to
different SCSI target IDs or to different controllers without
affecting correct operation.
VxVM maintains known disk device address information 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 vxdisk 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 VERITAS Volume Manager information. Private regions
are structured regions, and are maintained entirely by VxVM. Private
regions contain the following structures:
Disk Header
Each private region 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 causing use of the disk to be lost. The
primary copy of the disk header is stored in block zero of
the private region. The alternate copy is stored within the
first 256 sectors. If the primary copy is unreadable or
unusable, VxVM searches the first 256 sectors of the private
region for the alternate copy.
Table of Contents
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.
- 2 - Formatted: January 24, 2005
vxdisk(1M) VxVM 3.5 vxdisk(1M)
1 Jun 2002
Configuration Copies
A disk normally contains one disk group configuration copy,
according to the number specified when the disk was
initialized using the vxdisk 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 allocated 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
redundancy for recovering from simple read failures.
Disk Group Log Copies
A disk normally contains one disk group log copy. 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 performed:
transaction commits, plex detaches resulting from I/O
failures, total dirty region log (DRL) failures, the first
write to a volume, and volume close. 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 must 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 must be reinitialized.
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,
VxVM scans for disks that are stamped with the system's host ID. Each
represented disk group is imported automatically. Disks with a nonmatching
host ID are not imported automatically, and cannot be used
until the host ID is cleared with the clearimport operation.
The behavior of the vxdisk utility depends upon the keyword specified
as the first operand.
- 3 - Formatted: January 24, 2005
vxdisk(1M) VxVM 3.5 vxdisk(1M)
1 Jun 2002
KEYWORDS [Toc] [Back]
addregion Adds a new entry to the table of contents in a disk's
private region. The new entry defines a region of disk that
is relative to the public region, and that is reserved for a
particular use. The offset and length operations indicate
the location and extent of the region. Currently, the only
region type that can be defined is:
reserve Masks out a region of disk that should be reserved
for purposes other than use by VxVM. This could
be used, for example, to mask out a boot file
system that cannot be used for subdisk allocation,
or to mask out a region containing blocks that are
used for bad-block or bad-track replacement.
Adding a region fails if a subdisk or region is already
allocated over the requested region.
The addregion functionality is currently unimplemented for
any of the existing disk types.
check Determines the usability of the specified disks. A disk is
considered usable if VxVM can write and read back at least
one of the disk headers that are stored on the disk. If a
disk in a disk group is unusable, VxVM detaches it from its
disk group, and all subdisks stored on the disk become
invalid. The subdisks remain invalid until the unusable
disk is replaced or the disk media record is reassigned to a
different physical disk.
For shared disks, VxVM detaches an unusable disk only if the
disk group's detach policy is set to global. If the disk
group detach policy is local, the disk is not detached.
However, if hosts in the cluster do not indicate that a disk
is usable, the disk is detached from the entire cluster.
See vxedit(1M) for more information on setting disk group
detach policies.
clearimport
Clears 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.
define Defines a disk access record, but do not initialize it. In
order for VxVM to scan a disk, a disk access record must be
- 4 - Formatted: January 24, 2005
vxdisk(1M) VxVM 3.5 vxdisk(1M)
1 Jun 2002
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 must first make it accessible by
using vxdisk define. You can use vxdisk list to see what is
on the disk, or vxdg 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:
type=disk_type
The disk device access type. See the init
operation definition for more details.
The various disk types support additional
attributes for the define operation. See the
definition for each disk type, in the Disk Types
section.
offline If specified, the disk is created in the offline
state.
Normally, a define operation fails if the specified disk
device 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 used 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 addresses, even though they are not
usable until you shutdown and reconfigure your disks.
If specified, the -B option initializes the VERITAS Volume
Manager private region to begin at block number 2144. This
block is designated as the private region offset for a
VERITAS Volume Manager root disk. Without this option, the
private region is initialized to start at the default block
number 128.
getctlr Returns the name of the controller associated with a given
disk access name.
init Initializes regions of a disk used by VxVM. This involves
installing a disk header and writing an empty configuration
on the disk. The accessname operand identifies the disk.
Normally, this command fails if the disk already contains 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
initialized.
- 5 - Formatted: January 24, 2005
vxdisk(1M) VxVM 3.5 vxdisk(1M)
1 Jun 2002
The vxdisk init operation creates a disk access record for a
disk (if one does not already exist), and sets its state to
online. Disks can be initialized when the root
configuration is disabled, in which case the disk header is
initialized, but the disk is not added to the permanent list
of known disks until the root configuration is enabled.
Any attribute operands override default values assigned for
various disk attributes. Some attributes that can be set
are:
type=disk_type
The disk device access type, which is a systemspecific
name identifying a class of strategies
for accessing disks and for managing private and
public regions. For example, disk types could
indicate network disks or a volatile RAM disk that
may not require the storage of any private data.
The various disk types support additional
attributes for the init operation. See the
definition for each disk in the Disk Types
section.
offline Leaves the device in the offline state initially.
This is used only if this operation is defining a
new disk access record.
If specified, the -B option initializes the VERITAS Volume
Manager private region to begin at block number 2144. This
block is designated as the private region offset for a
VERITAS Volume Manager root disk. Without this option, the
private region is initialized to start at the default block
number 128.
list Lists path type and states along with the detailed
information on the specified disks. The state is listed as
enabled or disabled. If no disk arguments are specified,
then print an one-line summary for all disk access records
known to the system. If disk 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 no
disk arguments are specified, but a disk group is specified
with -g, then list only those disks added to the specified
disk group.
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 information printed with -s includes the
disk ID, the host ID (if the disk is or was imported), and
- 6 - Formatted: January 24, 2005
vxdisk(1M) VxVM 3.5 vxdisk(1M)
1 Jun 2002
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
describing output fields. This option has no effect with
the long formats generated with -s or with accessname
arguments.
When -o alldgs is specified without -s and -g, a one line
summary shows all disk to disk group associations. The disk
group column shows imported disk groups as normal and shows
all other disk groups in parentheses.
offline Declares the disk devices named by the accessname arguments
to be in the offline state. This disables checking of the
disk in searching for particular disk IDs, or for the set of
disks in a particular disk group. This operation cannot be
applied to disks that are members of an imported disk group.
Take a disk offline if the disk is not currently accessible,
and if accessing the disk has a negative impact on the
system. For example, disk drivers on a some operating
systems can cause system panics or hangs if an attempt is
made to access disks that are not accessible. In other
operating systems, attempts to access inaccessible drives
may take several seconds or minutes before returning a
failure.
online Clears 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, provided 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.
If -a is specified, re-online all online disks that are not
currently in an imported disk group. This can be used to
force VxVM to re-scan all disk headers.
rm Removes the specified disk access records, by disk access
name.
rmregion Frees a region of space that is allocated in the private or
public region for a particular use. Space that is freed
from the public region becomes usable for subdisk creation.
The arguments to rmregion must match the arguments used when
adding the region with vxdisk addregion except for the
optional length argument which can be excluded for the
remove.
- 7 - Formatted: January 24, 2005
vxdisk(1M) VxVM 3.5 vxdisk(1M)
1 Jun 2002
The rmregion functionality is currently unimplemented for
any of the existing disk types.
scandisks Initiates a rescanning of devices in OS device tree by VxVM
and triggers a DMP reconfiguration. In this manner disks can
be dynamically configured and multipathed by VxVM.
set Changes some set of attributes for a disk. The attributes
are either simple names (used to turn on an on/off
attribute), or can be of the form attrname=value, to
indicate a value for a particular attribute.
Hardware-Specific Note [Toc] [Back]
Some environments provide guidelines to optimize VxVM's interaction
with intelligent storage systems. If these guidelines are present,
VxVM follows them when initializing disks, creating volumes or
allocating space for volumes. These rules cannot be overridden.
Disk Types [Toc] [Back]
Two basic disk types are provided with VxVM. Additional types may be
added for use with particular operating systems. The default is a
simple type.
Nopriv Disks [Toc] [Back]
The simplest disk type is nopriv, which defines a disk that has no
private 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
vxdisk addregion. Because nopriv disks are not self identifying, VxVM
cannot track the movement of such disks on a SCSI chain or between
controllers.
nopriv devices are most useful for defining special devices (such as
volatile RAM disks) that you wish to use with VxVM, but that cannot
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 vxdisk 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 vxdisk init and define operations
for the nopriv device type are:
publen=length or len=length
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 is computed.
- 8 - Formatted: January 24, 2005
vxdisk(1M) VxVM 3.5 vxdisk(1M)
1 Jun 2002
puboffset=offset or offset=offset
The offset within the device for the start of the usable
region. This defaults to 1. This can be used if it is
necessary to skip over some region reserved by the operating
system. If an offset is specified, then the default disk
length is adjusted accordingly.
volatile If this attribute is specified, the disk is considered to
have volatile contents (that is, the disk contents are not
expected to remain consistent across a system reboot).
Subdisks and plexes defined on disks with the volatile
attribute inherit that attribute. The vxvol start operation
interprets volatile plexes as requiring a complete revive
from other plexes in the same volume.
The vxdisk define operation, with the nopriv device type, takes the
same attributes as the init operation. In addition, define takes the
following attribute:
diskid=newdiskid
This attribute sets the disk ID to the newdiskid value in
the disk access record for the nopriv disk.
Simple Disks [Toc] [Back]
The simple type presumes that the public and private regions are
stored on the same disk, with the public region following the private
region.
Attributes that can be defined with vxdisk define for simple are:
configlen=length
The size to reserve for each copy of the configuration
stored on the disk. The default size is based on the size
of the private area and the number of configuration copies
requested, and leaves some space free for uses other than
the configuration copies.
loglen=length
The size to reserve in the private region for each log
region. This size limits the number of kernel-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 configuration copy size.
nconfig=count
The number of configuration copies to store on the disk.
This defaults to 1. This can be set to 0 to indicate that
no configurations are to be stored on the disk. VxVM
automatically enables and disables the configuration copy.
It maintains a level of redundancy in configuration copies
- 9 - Formatted: January 24, 2005
vxdisk(1M) VxVM 3.5 vxdisk(1M)
1 Jun 2002
that allows the configuration to be recovered from the loss
of multiple disks. See the vxdg nconfig parameter for more
information.
nlogs=count
The number of log regions to allocate on the disk. Logs
regions are used for storing any plex detaches that happen
within the disk group. This number defaults to 1. VxVM
automatically enables and disables the configuration copy.
It maintains a level of redundancy in configuration copies
that allows the configuration to be recovered from the loss
of multiple disks. Refer to the vxdg(1M) nlog parameter for
more information.
publen=length or len=length
The length of the public region. If not specified, the
length of the public region is computed from available
system-specific disk size 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.
privlen=length
The length of the private region. If this is not specified,
then a default is chosen. For the simple type, the default
size is 2048 blocks. The maximum possible size of the
private region is 524288 blocks.
Auto-Configured Disks [Toc] [Back]
On some systems, VxVM can ask the operating system for a list of known
disk device addresses. On such systems, some device addresses are
auto-configured into the rootdg disk group when vxconfigd is started.
Auto-configured disks are always of type simple, with default
attributes.
Auto-configured devices can be removed, if necessary, using vxdisk rm.
When removed, explicitly defined devices can be defined to override
any auto-configured devices. When the system reboots, no autoconfigured
disk devices are added to the rootdg disk group that would
share a disk with an explicitly configured disk device.
Auto-configured devices can be disabled and re-enabled using the
offline and online operations. However, the offline state is not
stored persistently. If you need to persistently offline a device at
a particular address, convert the address to use an explicit device
record. To do this, remove the auto-configured device, and use vxdisk
define to create an explicitly configured device.
EXAMPLES [Toc] [Back]
This example sets the powerfail timeout on disk01.
- 10 - Formatted: January 24, 2005
vxdisk(1M) VxVM 3.5 vxdisk(1M)
1 Jun 2002
vxdisk set disk01 pfto=seconds
The set functionality is currently unimplemented for any of the
existing disk types.
Use the getctlr keyword to return the controller associated with a
disk that is specified by its enclosure-based disk access name.
vxdisk getctlr JBOD0_5
SEE ALSO [Toc] [Back]
pfto(7), vxconfigd(1M), vxdg(1M), vxedit(1M), vxintro(1M), vxvol(1M)
- 11 - Formatted: January 24, 2005 [ Back ] |
