voldg(8) System Manager's Manual voldg(8)
NAME
voldg - Manages Logical Storage Manager disk groups
SYNOPSIS
/sbin/voldg init groupname [medianame=] accessname... [nconfig=config-copies | all | default] [minor=base-minor]
/sbin/voldg [-g diskgroup] [-f] reminor [diskgroup] new-base-minor
/sbin/voldg [-tfC] [-nnewname] import diskgroup
/sbin/voldg [-nnewname] [-hnewhostid] deport diskgroup...
/sbin/voldg [-g diskgroup] [-k] adddisk [medianame=] accessname...
/sbin/voldg [-g diskgroup] [-k] rmdisk [medianame]...
/sbin/voldg [-q] list [diskgroup...]
/sbin/voldg [-g diskgroup] [-qa] free [medianame...]
/sbin/voldg [-g diskgroup] [-q] spare [medianame...]
/sbin/voldg flush [diskgroup...]
/sbin/voldg [-g diskgroup] [-k] repldisk unassoc-medianame=spare-medianame...
DESCRIPTION
The voldg utility performs basic administrative operations on disk groups. Operations include the creation of disk groups, the addition of
disks to a disk group, and disk group imports and deports. The behavior of the voldg utility depends upon the keyword specified as the
first operand.
A groupname argument must be a disk group name.
A diskgroup argument can be either a disk group name or a disk group ID.
An accessname argument refers to a disk access name (also referred to as a disk device name), as stored in the root configuration by the
voldisk utility (for example, dsk5). A medianame argument is an administrative name used to define a disk within a disk group (for exam-
ple, disk01).
KEYWORDS
Supported keywords for voldg are: Defines a new disk group composed of the indicated disks, identified by disk access names. This involves
assigning an internal unique ID to the group, storing a reference to the group on all of the named disks that have a disk header, and stor-
ing a disk group record in the disk group's configuration database. At least one of the disks specified must have space allocated for a
configuration copy.
If a medianame is specified for use with a particular disk, that medianame will name the disk media record used to reference the
disk within the disk group (for operations such as rmdisk and subdisk creations). If no medianame is specified, the disk media name
defaults to accessname See voldisk(8) for a discussion of definition and initialization of disk access records.
The init operation can be used to initialize a root disk group configuration, which is identified by the special name rootdg. Disks
should be initialized and added to the disk group as the first operations after creating rootdg.
If the autoconfiguration functionality of LSM is disabled, some or all disks added to the rootdg disk group should also be added to
the /etc/vol/volboot bootstrap file (see voldctl(8)).
The nconfig attribute can be used to configure the number of configuration database copies and kernel log copies that are maintained
for a disk group.
The value of config-copies is either a decimal number (including 0 or -1) or a setting of all or default.
A value of all or -1 signifies that all configuration or log copies on all disks in the disk group will be maintained. A value of
default or 0 (the default value) signifies that the Logical Storage Manager will manage copies that are distributed in a reasonable
pattern throughout the disks and controllers on the system. Any other number signifies that a particular number of copies should be
maintained (or all copies, if that number is larger than the number of available configuration or log copies on all disks).
When a specific number (or default) is requested, configuration copies are scattered approximately evenly through the disk con-
trollers on the system. If SCSI disks with multiple disks per target are found, each such target is treated similarly to a con-
troller (that is, configuration copies are evenly distributed between such targets). With the default policy, one configuration or
log copy is maintained for each controller, and one configuration or log copy is also maintained for each SCSI target that has mul-
tiple disks; if this does not result in allocating at least 4 copies, additional copies are spread through the controllers and tar-
gets.
Refer to voldisk(8) for more information on configuration and log copies, and for information on how to create them.
Note
If a policy other than all is used, some disks will not have up-to-date, online configuration and log copies. As a result, it is
possible that some number of disk failures will leave a disk group unusable, even if some disks in the disk group remain usable. The
default policy allocates a sufficient number of copies, in a sufficient spread of locations, so that such a scenario is very
unlikely to occur. Since disk groups can be moved between systems, it is desirable that device numbers used for volumes be allo-
cated in separate ranges for each disk group. That way, an administrator can choose ranges such that all disk groups in a group of
machines can be moved around without causing device number collisions. Collisions may occur because the Logical Storage Manager
stores device numbers in disk group configurations, so that the same numbers can be used after a reboot (which is necessary for use
with NFS, which requires persistency of device numbers). If two systems use the same device numbers for a set of volumes, and if a
disk group from one machine is moved to the other, the Logical Storage Manager may be forced to temporarily remap some devices.
A base volume device minor number can be set for a disk group with the minor operand. Volume device numbers for a disk group will be
chosen to have minor numbers starting at this base minor number. On Tru64 UNIX systems, minor numbers can range up to 1048576, so if
it is presumed that no more than 1000 volumes would ever be created in any one disk group, then 1048 different ranges of minor num-
bers are available for different disk groups. A reasonably sized range should be left at the end for temporary device number remap-
pings (in the event that two device numbers still conflict).
If the minor attribute is not specified on the init command line, the Logical Storage Manager chooses a random number of at least
1000 that is a multiple of 1000, and yields a usable range of 1000 device numbers. This default number is chosen such that it does
not overlap within a range of 1000 of any currently imported disk groups, and does not overlap any currently allocated volume device
numbers.
Note
The default policy is likely to ensure that a small number of disk groups can be merged successfully between a set of machines. How-
ever, in cases where disk groups will be merged automatically using fail-over mechanisms, the administrator should select ranges
that are known to avoid overlap. Changes the base minor number for a disk group, and renumbers all devices in the disk group to a
range starting at that number. If the device for a volume is open, the old device number will remain in effect until the system is
rebooted or until the disk group is deported and reimported. Also, if you close an open volume, you can execute voldg reminor again
to cause the renumbering to take effect without rebooting or reimporting.
A new device number may also overlap with a temporary renumbering for a volume device, which will also require a reboot or reimport
for the new device numbering to take effect. A temporary renumbering can happen in the following situations: when two volumes (for
example, volumes in two different disk groups) share the same permanently assigned device number, in which case one of the volumes
is renumbered temporarily to use an alternate device number; or when the persistent device number for a volume was changed, but the
active device number could not be changed to match. The active number may be left unchanged after a persistent device number change
either because the volume device was open, or because the new number was in use as the active device number for another volume.
The voldg reminor operation will fail if you try to use a range of numbers that is currently in use as a persistent (not a tempo-
rary) device number. You can force use of the number range with use of the -f option. With -f, some device renumberings may not take
effect until a reboot or a reimport (just as with open volumes). Also, if you force volumes in two disk groups to use the same
device number, one of the volumes will be temporarily renumbered on the next reboot. Which volume device will be renumbered should
be considered random, except that device numberings in the rootdg disk group take precedence over all others.
The -f option should be used only when swapping the device number ranges used by two or more disk groups. To swap the number ranges
for two disk groups, you would use -f when renumbering the first disk group to use the range of the second disk group. Renumbering
the second disk group to the first range will not require use of -f. Imports a disk group to make the specified disk group avail-
able on the local machine. This will make any configuration information stored with the disk group accessible, including any disk
and volume configurations. The disk group to import is indicated by the diskgroup argument, which can be either an administrative
disk group name or a disk group unique ID.
Normally, a disk group will not be imported if some disks in the disk group cannot be found by the local host. The -f option can be
used to force an import if, for example, one of the disks is currently unusable or inaccessible.
Note
Take care when using the -f option, since it can cause the same disk group to be imported twice from disjointed sets of disks, caus-
ing the disk group to become inconsistent.
When a disk group is imported, all disks in the disk group are stamped with the host's host ID, which is usually the host name. Nor-
mally, a disk group cannot be imported if any of its disks are stamped with a non-matching host ID. This provides a sanity check in
cases where disks can be accessed from more than one host.
If it is certain that a disk is not in use by another host (such as because a disk group was not cleanly deported), the -C option
can be used to clear the existing host ID on all disks in the disk group as part of the import. You can clear a host ID using the
voldisk clearimport command.
A new name can be given to the disk group on import using -n newname. If -n is used with the -t option (described below), the stored
name of the disk group will remain unchanged, but the disk group will be known to the importing host under the new name; otherwise,
the name change will be permanent.
The -t option imports a disk group temporarily (nonpersistent). Disk groups imported with this option will not be reimported when
the system reboots.
Normally, an imported disk group will be reimported automatically when the system is rebooted, if at least some of the disks in the
disk group remain accessible and usable. If you do not want the disk group to be reimported when the system reboots, import it with
the -t option.
As an example of the use of -n and -t, a rootdg disk group from one host can be imported on a second host, operations can be per-
formed on the second host (such as making repairs to the root volume), and the disk group can be given back to the originating host,
which can then be rebooted on the repaired disk group. To do this, identify the disk group ID for the rootdg disk group with voldisk
-s list, and use that disk group ID to import that rootdg using -C to clear import locks, -t for a temporary import, and -n to spec-
ify an alternate name (to avoid collision with the rootdg disk group on the second host). After repair, deport the disk group using
-h (described below) to restore the import lock from the first host. Disables access to the specified disk group. You cannot deport
a disk group if any volumes in the disk group are open. When you deport a disk group, the host ID, which is usually the host name,
is cleared on all disks in the disk group unless you specify a new host ID using the -h option. This is to prevent automatically
reimporting the disk group when the system reboots.
A disk group can be renamed on deport by specifying a new disk group name with the -n newname option. A lock can be assigned to an
alternate host by specifying the host ID (see voldctl(8)) of the alternate host. This allows the disk group to be auto-imported when
the alternate host reboots. For example, the -n and -h options can be combined to export a disk group to be used as the rootdg disk
group for a new machine. Adds the specified disk(s) to a disk group (rootdg by default). The disk must not already be part of an
imported disk group. The accessname component to a disk specification argument names a disk access record (essentially a device
address specification) used to access the disk. If a medianame component is specified, it names the disk media record used to
define the disk within the disk group. If no medianame component is specified, the disk media record will have the same name as the
disk access record.
Adding a disk to a disk group causes the disk group's configuration to be copied onto the disk (if the disk has regions for configu-
ration copies). Also, the disk is stamped with the system's host ID, which is usually the host name, as defined in the
/etc/vol/volboot file.
If the -k option is specified, the disk media name must represent a disk media record that was previously dissociated from its disk
access record with -k rmdisk; otherwise, a new disk media record will be created to represent the disk. With the -k option, plexes
requiring recovery will be flagged as stale. Removes the specified disk(s) from a disk group (rootdg by default). The last disk
cannot be removed from its disk group. It is not possible to remove the last disk containing a valid disk group configuration or log
copy from its disk group.
Normally, the rmdisk operation will fail if subdisk records point to the named disk media records. However, if the -k option is
specified, the disk media records will be kept, although in a removed state, and the subdisk records will still point to them. The
subdisks, and any plexes that refer to them, are unusable until the disk is re-added using the -k option to the adddisk operation.
Any volumes that become unusable, because all plexes become unusable, will be disabled.
Note
Use extra care with the -k option since this option can disable active volumes. Lists the contents of disk groups. If no diskgroup
arguments are specified, all disk groups are listed in an abbreviated one-line format. If diskgroup arguments are specified, a
longer format is used to indicate the status of the disk group, and of the specified disk group configuration.
If the -q option is specified, no header is printed describing output fields. This option has no effect with the long formats gener-
ated with diskgroup arguments. Lists free space that can be used for allocating subdisks. If a disk group is specified, the output
is limited to the indicated disk group; otherwise, space is listed from all disk groups. If disks are specified by disk media name,
the output is restricted to the indicated disks.
A region of free space is identified by disk media name, a physical device tag, an offset relative to the beginning of the public
region for the media, and a length.
The physical device tag is a reference that indicates which physical device the disk media is defined on. It appears as a truncated
disk access name. If a particular physical device is split into several Logical Storage Manager disk objects, the device tag for
each disk object will be the same. Device tags can be compared to identify space that is on the same or on different physical
disks.
If the -q option is specified, no header is printed describing output fields. If the -a option is specified, space on spare disks
(which is not really allocatable) is listed in addition to regular free space; otherwise, space on spare disks is not listed. Lists
spare space that can be used for relocating subdisks during recovery. If a disk group is specified, the output is limited to the
indicated disk group; otherwise, spare space from all disk groups is listed. If disks are specified by disk media name, the output
is restricted to the indicated disks.
A region of spare space is identified by disk media name, a physical device tag, an offset relative to the beginning of the public
region for the media, and a length.
The physical device tag is a reference that indicates which physical device the disk media is defined on. It appears as a truncated
disk access name.
If the -q option is specified, no header is printed describing output fields. Rewrites all disk on-disk structures managed by the
Logical Storage Manager for the named disk groups. This rewrites all disk headers, configuration copies, and kernel log copies.
Also, if any configuration copies were disabled (for example as a result of I/O failures), this will rewrite those configuration
copies and attempt to enable them. Dissociates the disk access record from the disk media record named by spare-medianame and reas-
sociates it with the unassociated disk media record named by unassoc-medianame. Both unassoc-medianame and spare-medianame must be
members of the disk group named by the diskgroup argument (rootdg by default). However, if the -k option is specified, the disk
media records for the spare-medianame will be kept, although in a removed state.
SEE ALSO
volintro(8), vold(8), voldisk(8), volplex(8), volume(8)
voldg(8)