voldg(8)voldg(8)NAMEvoldg - Manages Logical Storage Manager disk groups
SYNOPSIS
/sbin/voldg init groupname {medianame=accessname} [nconfig=con‐
fig-copies | all | default] [minor=base-minor]
/sbin/voldg [-g diskgroup] [-f] reminor [diskgroup] new-base-minor
/sbin/voldg [-tfC] [-n newname] [-o shared | private] [-o convert_old]
import diskgroup
/sbin/voldg [-n newname] [-h newhostid] 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-medi‐
aname...
OPTIONS
Specifies the disk group for the operation, either by name or by disk
group ID. If no disk group is specified, the rootdg disk group is
implied. Clears the previous name of the specified disk group. Forces
an operation that the Logical Storage Manager (LSM) considers poten‐
tially dangerous or of questionable use. This permits a limited set of
operations that would otherwise be disallowed. Some operations might
be disallowed even with this option. Keeps (when used with rmdisk or
repldisk) or reapplies (when used with adddisk) the previous LSM disk
media records for the named disk. Typically used when replacing a
failed disk to keep the LSM structure of the affected volume or disk
group intact. This option sets any plexes requiring recovery to STALE.
Assigns a new host name to the disk group. Assigns a new name to the
disk group. Used with import. Converts the disk group's configuration
databases and kernel change logs as appropriate for the system on which
the disk group is being imported. When manually importing a disk group
to a cluster from a standalone system, use -o shared. When manually
importing a disk group to a standalone system from a cluster, use -o
private. Used with import to import disk groups deported before
upgrading the LSM software from pre-Version 5.0 to Version 5.0 or
higher. This option upgrades the disk group's metadata to the current
format and examines all volumes to determine if they use Block Change
Logging (BCL). If such volumes are found, LSM displays a message
instructing you to use the vollogcnvt utility to convert BCLs to Dirty
Region Logs (DRLs). The disk group is imported but logging is disabled
on volumes that use BCL. The volume is usable and data continues to be
written to all mirrors, but if a disk in the volume fails or the system
crashes, the entire volume will be resynchronized to recover the data.
Suppresses headers in output fields. If used with diskgroup, this
option is ignored. Displays information about space on spare disks
(which is not really allocatable) in addition to regular free space in
the disk group. Normally, spare disk information is not displayed.
Performs the operation temporarily.
When used with import, the disk group will not be reimported on
reboot. 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.
Can be used with -n newname to temporarily assign a new minor
number or name to a volume or disk group, respectively. When
used with -n newname when importing a disk group, the disk
group's stored name is retained, but the disk group is known to
the new host as newname. This allows the disk group to be reim‐
ported on the original host with its former name.
KEYWORDS
Defines a new disk group composed of the disks identified by disk
access names. This operation assigns an internal unique ID to the
group, stores a reference to the group on all of the named disks that
have a disk header, and stores 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 more information
on defining and initializing 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 right
after rootdg is created.
If the autoconfiguration functionality of LSM is disabled, add
the names of disks that have copies of the rootdg configuration
database to the /etc/vol/volboot bootstrap file. See voldctl(8).
The nconfig attribute can be used to specify the number of con‐
figuration database copies and kernel log copies that are main‐
tained for a disk group.
The value of config-copies can be one of the following: LSM
maintains the copies and their number and distribution through‐
out the disks and controllers in the disk group. All configura‐
tion and kernel log copies on all disks in the disk group are
maintained.
This policy places extra overhead on the system, because every
copy of the configuration database must be updated with every
configuration change. The specified number of copies is main‐
tained (or all copies, if the number you specify is larger than
the number of available copies on all disks).
When a specific number (or default) is requested, configuration
copies are scattered approximately evenly through the disk con‐
trollers in the disk group. If SCSI disks with multiple disks
per target are found, each such target is treated similarly to a
controller (that is, configuration copies are evenly distributed
among such targets). With the default policy, one configuration
and log copy is maintained for each controller, and one configu‐
ration and log copy is also maintained for each SCSI target that
has multiple disks; if this does not result in allocating at
least four copies, additional copies are spread through the con‐
trollers and targets.
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. However, the default policy allocates a sufficient num‐
ber of copies, in a sufficient spread of locations, so that such
a scenario is very unlikely to occur. The default policy is the
recommended policy.
Refer to voldisk(8) for more information on configuration and
log copies and for information on how to create them. Because
disk groups can be moved between systems, LSM lets you allocate
volume device numbers in separate ranges for each disk group.
That way, you can choose ranges such that all disk groups in a
group of machines can be moved without causing device number
collisions. Collisions may occur because LSM stores device num‐
bers 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, LSM can 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
are chosen to have minor numbers starting at this base minor
number. On Tru64 UNIX systems, minor numbers can range up
through 1048576. If no more than 1000 volumes would ever be cre‐
ated in any one disk group, then 1048 different ranges of minor
numbers are available for different disk groups. A reasonably
sized range should be left at the end for temporary device num‐
ber remappings (in the event that two device numbers still con‐
flict).
If the minor attribute is not specified on the init command
line, LSM chooses a random number of at least 1000 that is a
multiple of 1000 and yields a usable range of 1000 device num‐
bers. This default number is chosen such that it does not over‐
lap within a range of 1000 of any currently imported disk groups
and does not overlap any currently allocated volume device num‐
bers.
Note
The default policy is likely to ensure that a small number of
disk groups can be merged successfully between a set of
machines. However, in cases where disk groups will be merged
automatically using fail-over mechanisms, you should select
ranges that 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 sys‐
tem is rebooted or until the disk group is deported and reim‐
ported. 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 can also overlap with a temporary renumber‐
ing for a volume device, which will also require a reboot or
reimport for the new device numbering to take effect. A tempo‐
rary 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 When the persistent device number for a volume is
changed, but the active device number cannot be changed to match
The active number can 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 currently in use as a persistent (not a temporary)
device number. You can force use of the number range with the -f
option. With the -f option, some device renumberings might not
take effect until a reboot or a reimport (just as with open vol‐
umes). 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. The volume device to be renum‐
bered is selected at 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 num‐
ber ranges used by two or more disk groups. See EXAMPLES for
more information. Imports a disk group to make the specified
disk group available on the local machine. This makes any con‐
figuration information stored with the disk group accessible,
including any disk and volume configurations. You specify the
disk group to import with the diskgroup argument, which can be
either the administrative disk group name or the disk group's
unique ID.
Normally, a disk group is not imported if some disks in the disk
group cannot be found by the local host. You can force the
import with the -f option if, for example, one of the disks is
currently unusable or inaccessible.
Note
Take care when using the -f option, because it can cause the
same disk group to be imported twice from disjointed sets of
disks, causing the disk group to become inconsistent.
When a disk group is imported, all disks in the disk group are
stamped with the host's ID, which is usually the host name. Nor‐
mally, a disk group cannot be imported if any of its disks are
stamped with a nonmatching host ID. This provides a check in
cases where disks can be accessed from more than one host.
If you are certain that a disk is not in use by another host
(such as because a disk group was not cleanly deported), use the
-C option to clear the existing host ID on all disks in the disk
group as part of the import. You can also clear a host ID using
the voldisk clearimport command.
You can rename a disk group on import using the -n newname
option. If you do not want the name change to be permanent, use
the -n option with the -t option. This retains the original name
of the disk group but presents the disk group to the importing
host under the new name. 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 importing the disk group when the
system reboots.
You can rename a disk group when you deport it with the -n new‐
name option. You can also assign the disk group to an alternate
host by specifying the host ID (voldctl(8)) of the alternate
host with the -h newhostid option. This allows the disk group
to be automatically imported when the alternate host reboots.
See EXAMPLES. Adds the specified disk or disks 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 specifi‐
cation argument names a disk access record (a device address
specification) used to access the disk. If a medianame compo‐
nent 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 configura‐
tion to be copied onto the disk (if the disk has regions for
configuration copies). Also, the disk is stamped with the sys‐
tem's host ID, which is usually the host name, as defined in the
/etc/vol/volboot file. Removes the specified disk or disks 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 fails if subdisk records point to
the named disk media records. However, if the -k option is spec‐
ified, 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 again added using the -k option to the adddisk
operation. Any volumes that become unusable, because all plexes
become unusable, are disabled.
Note
Use extra care with the -k option because this option can dis‐
able active volumes. Lists the contents of disk groups. If no
diskgroup argument is specified, all disk groups are listed in
an abbreviated one-line format. If a diskgroup argument is spec‐
ified, a longer format is displayed indicating the status and
configuration of the disk group and a listing of the disks that
contain copies of its configuration database and kernel log.
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 phys‐
ical device tag, an offset relative to the beginning of the pub‐
lic region for the media, and a length.
The physical device tag is a reference that indicates which
physical device defines the disk media. It appears as a trun‐
cated 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 dif‐
ferent physical disks. Lists spare space that can be used for
relocating subdisks during recovery. If a disk group is speci‐
fied, the output is limited to the indicated disk group; other‐
wise, 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 defines the disk media. It appears as a trun‐
cated disk access name. Rewrites all 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 reassociates 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-medi‐
aname will be kept, although in a removed state.
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 admin‐
istrative name used to define a disk within a disk group (for example,
disk01).
EXAMPLES
To swap the number ranges for two disk groups, use the -f option when
renumbering the first disk group to use the range of the second disk
group. Renumbering the second disk group to the first range does not
require the -f option:
# voldg-f reminor dg-1 dg2-base-minor # voldg reminor dg-2
dg1-base-minor To move a rootdg disk group from one host to a
second host (for example, so you can make repairs to the root
volume) and then move the disk group back to the originating
host, which can then be rebooted on the repaired disk group, do
the following: Identify the disk group ID for the rootdg disk
group with voldisk -s list. On the other host, use that disk
group ID to import that rootdg using -C to clear import locks,
-t for a temporary import, and -n to specify an alternate name
(to avoid collision with the rootdg disk group on the second
host):
# voldg-tC-n tempname import rootdg_id After repair, deport
the disk group using -h to restore the first host ID:
# voldg-h orig_host_id deport tempname
To deport a disk group to be used as the rootdg disk group for a
new machine: Deport the disk group, renaming it rootdg and
assigning the new host ID: # voldg-n rootdg -h newhostid deport
diskgroup Connect the disks to the new host. Boot the new host.
The system finds the configuration automatically and imports the
new rootdg disk group. To import disk groups deported from a
pre-Version 5.0 version of LSM onto a system running Version 5.0
or higher and upgrade their metadata format, enter: # voldg-o
convert_old import diskgroup
If the disk group contains volumes that use BCL, the following
message is displayed:
lsm:voldg:WARNING:Logging disabled on volume. Need to convert to
DRL. lsm:voldg:WARNING:Run the vollogcnvt command to automati‐
cally convert logging.
SEE ALSO
Commands: vold(8), voldisk(8), vollogcnvt(8), volplex(8), volume(8)
Other: volintro(8)voldg(8)