admvdisk(1M) DG/UX R4.11MU05 admvdisk(1M)
NAME
admvdisk - administer virtual disks
SYNOPSIS
admvdisk -o { list | remove | link | unlink | rename | extract |
specify | modify } { options } vdisk ...
admvdisk -o { copy | move } { options } -s source_vdisk
-d destination_vdisk
admvdisk -o { create | insert } [ -t { partition | aggregation |
cache | mirror } ] { options } ... vdisk
admvdisk -o { expand | shrink } { options } ... vdisk
admvdisk -o { fracture | sync | throttle_sync | terminate_sync }
{ mirror-specific options } mirror_vdisk ...
DESCRIPTION
The admvdisk command manages virtual disks. A virtual disk is an
abstraction that presents some lower-level storage for use as if it
were a single sequential collection of disk blocks. For example, a
virtual disk may conceal a variety of implementation features, such
as:
· Partitioning of large virtual disks into smaller virtual disks.
· Aggregation of virtual disks to create a single large virtual
disk or improve performance.
· Mirroring of virtual disks to provide increased reliability or
performance.
· Caching of a large and relatively slow virtual disk on a small
and relatively fast virtual disk, to improve performance.
· Mapping of bad blocks on physical devices to provide the
appearance of an error-free physical device.
Virtual Disk Types
Each specific virtual disk has a particular type, such as partition
or aggregation. Virtual disks of all types can be arranged in
hierarchies to provide the desired combination of characteristics.
For example, a virtual disk that aggregates two partitions is
actually an aggregation virtual disk with two child virtual disks,
each of which is a partition virtual disk.
Each virtual disk type is implemented by a separate piece of kernel
software called a subdriver. For example, there is a partitioning
subdriver, an aggregation subdriver, etc. Thus, an aggregation is
the same thing as a virtual disk of type aggregation, and the
subdriver that implements it is actually called vdmaggr().
New virtual disk types (new subdrivers) may be created by Data
General or others. The following admvdisk operations may be used on
virtual disks whose type is not recognized by admvdisk: remove, link,
unlink, rename, extract, copy, move, and specify. The list operation
will list such virtual disks, but will not list any type-specific
attributes of the virtual disk.
Volumes
In order for a virtual disk to be accessible by application programs
or for mounting as a file system, the virtual disk must be a volume.
Virtual disks that are volumes have device node entries such as
/dev/dsk/foo and/dev/rdsk/foo; it is via these nodes that virtual
disks are accessed. Usually, virtual disks at the top of a virtual
disk hierarchy ("top-level" virtual disks) are volumes, and those
lower in the hierarchy are not, although there can be exceptions.
For example, our aggregation might be a volume and be used to hold a
file system, while there would be little sense in having the two
partitions that make up the aggregation be volumes. Directly
accessing either the first or second half of the file system wouldn't
be useful. Correspondingly, a top-level virtual disk that isn't a
volume couldn't be accessed at all (either directly or through any
other virtual disk) and would be useless until in that form. Any
virtual disk can be made to be a volume or to not be a volume at any
time, even while open.
If there are two virtual disks with the same name (for example, foo)
that are both volumes, only one can be referred to as /dev/dsk/foo.
However, both will have nodes with names of the form
/dev/dsk/vdm(foo,generation_number,machine_ID,duplicate_number) (see
the section on Names and ID Numbers, below). The specify operation
can be useful in determining which such node to use.
On-line Management
The virtual disk system has been designed to allow most management
activities to be performed on-line, that is, while the concerned
virtual disks are open. A virtual disk is said to be open if it is:
· mounted as a file system, or
· opened by an application program (such as a database management
system), or
· being used for swapping (paging) by the kernel, or
· a child of some other virtual disk.
In general, most operations described here can be performed on any
virtual disk, whether or not it is open. Those that cannot be
performed on virtual disks that are open are identified below.
Compatibility with Higher Level Software
Many operations that are legal strictly from the perspective of
managing virtual disks could cause problems for higher level software
that uses the affected virtual disk. For example, the DG/UX file
system code is not prepared to shrink a file system while the file
system is in use. Moreover, in order to correctly shrink the file
system off-line, the contents of the virtual disk (the file system
headers, etc.) must be properly manipulated. Merely shrinking the
virtual disk, even if done off-line, would, from the perspective of
the file system code, corrupt the file system and possibly even
destroy data.
To change the size of a virtual disk that contains a DG/UX file
system, admfilesystem should be used instead of admvdisk.
admfilesystem will take care of changing the size of both the file
system data structure and the enclosing virtual disk.
Similar issues exist for other software that uses virtual disks, such
as database management systems. In general, before performing any
manipulation of a virtual disk that contains data, you must consider
the ramifications of that change on the software that uses the data.
In some cases, the manipulation may be safe only when the virtual
disk is off-line.
Names and ID Numbers
Each virtual disk has a name, although the name may be null,
effectively making the virtual disk have no name. There is no
restriction against multiple virtual disks having the same name,
although managing such name conflicts can be troublesome. In this
document, we sometimes refer to a virtual disk's name as its short
name.
Names must be 31 or fewer bytes and must not include any of the
following characters:
\\0000 through \\0037 ASCII Control Characters
Space
" Double Quote
' Single Quote
( Left Parenthesis
) Right Parenthesis
, Comma
/ Slash
: Colon
@ Commercial At
\\0177 ASCII DEL
\\0200 through \\0237 Undefined Characters
In addition, each virtual disk has a two-part ID number. The first
part is the generation number, which is intended to be unique among
all the virtual disks created on the same machine. The second part
is the machine ID, which distinguishes the virtual disk from any
other virtual disk created on a different machine that received the
same generation number when it was created. These numbers are always
expressed in hexadecimal, with no leading "0x".
Each virtual disk has a long name, as follows:
name,generation_number,machine_ID,duplicate_number
If the virtual disk has "no name", then the name part of the long
name is null, and the long name starts with a comma. The duplicate
number is needed only in the very special case of virtual disks with
identical ID numbers (identical generation numbers and machine IDs).
This will be the case if a physical disk is copied and both the
original and the copy are registered. This can also happen if a
virtual disk is created on a hardware mirror (in a H.A.D.A.
subsystem) and the hardware mirror is subsequently broken into its
constituent images and the images are separately registered. When
the virtual disk is created, its ID number is stored on the hardware
mirror and, consequently, identically on the images of the hardware
mirror. When the images are separately registered, the otherwise-
identical virtual disks are assigned different "duplicate" numbers to
disambiguate them. Full long names are absolutely guaranteed to be
unique on any given system at any given time.
When specifying a virtual disk on the admvdisk command line, you may
use either the normal (short) name or the long name. When using a
long form name, you are free to leave out any field(s) that are not
necessary to uniquely identify a virtual disk, and you can leave out
any trailing commas. Thus, a short name is a special case of a long
name, with the generation number, machine ID, and duplicate number,
along with all commas, left out. In contexts where a list of virtual
disk names is acceptable, a name (long or short) that does not
uniquely identify one virtual disk can be used, and it will be
interpreted to mean the set of all virtual disks that match the name.
In some cases this is acceptable (e.g., with the list operation), in
other cases, it is treated as an error (e.g., with the rename
operation).
As a special case, "," is interpreted as identifying all virtual
disks with null short names.
Parent-child relationships are maintained between virtual disks on
the basis of the child's ID number, not its name. This means that
renaming a virtual disk will not change its relationship to its
parent or children virtual disks. However, if a virtual disk is a
volume, then renaming it will change the name associated with its
node under /dev.
In addition to long and short names, you may use a string of the form
name@physical_device_specification
The physical device is specified in Common Device Specification
Format. This is useful for disambiguating virtual disks that have
the same name. This can be particularly useful in conjunction with
the specify operation, for generating the name of the entry under
/dev/dsk that is associated with a particular physical device (disk).
For example,
dd if=/dev/dsk/`admvdisk -o specify foo@'sd(insc(),0)'` of=...
will cause dd to read from the virtual disk named foo that resides on
physical device sd(insc(),0).
If an operation would cause there to be two virtual disks with the
same short name, admvdisk will, by default, ask the user to verify
the creation of the duplicate name before performing the operation.
This can be suppressed with the -Q (very quiet) option.
Physical Device Names
All virtual disks are associated (either directly or through their
descendent virtual disks) with one or more physical devices (usually
disks). A virtual disk is said to "reside upon" a given physical
device if that device provides the storage for any data blocks
accessible through the virtual disk (including any of its children).
Physical devices are identified by their common device specification
(e.g., "sd(insc(),0)"); for a description of these, see Managing the
DG/UX System. These names are derived from the way the device is
connected to the machine, i.e., the name and number of the
controller, and the setting of switches in the device. Thus if the
drive is moved to a different bus position, controller, or machine,
its common device specification will generally change.
On a DG/UX cluster (see Clustered Physical Disks, below), a physical
disk located on a shared bus will have multiple common device
specifications, one for each node. For this reason, a cluster-wide
device name is provided for each physical disk residing on a shared
bus. Cluster-wide device names replace the node-specific information
within the common device specification (e.g., the name and number of
controller) with the shared_bus(shared bus number) component (e.g.,
"sd(shared_bus(0),0,0)"). Cluster-wide device names are therefore
consistent across all nodes. On a DG/UX cluster, admvdisk uses
cluster-wide device names in listings by default (see the list
operation).
Cluster-wide device names are generated and interpreted based on
information in the Membership Manager database; see the manual
Managing a DG/UX Cluster.
When a physical device is formatted for use with virtual disks (see
admpdisk(1M)), a special type of virtual disk is created on the
physical device. This virtual disk is of type physical and is used
as an interface between the other virtual disks and the physical
device. By default, this physical virtual disk does not have a name,
but you are free to give it one with the rename operation. When you
do so, this name is recorded on the medium of the device. If the
device is moved to a different bus position, controller, or machine,
the name of the physical virtual disk stays with the device. For
this reason, it is strongly recommended that you do not give the
physical virtual disk a name derived from the device's common device
specification or cluster-wide device name. Use, instead, a name
related to the role played by the device.
You may need to cite a physical device by name with the -P option
(see below). When doing so, you may use either the common device
specification of the physical device, cluster-wide device name, or
the name of the physical virtual disk.
Clustered Physical Disks
A clustered physical disk is a physical disk that resides on a shared
bus (e.g., SCSI bus) and is enabled for concurrent access by all
nodes within a DG/UX cluster. Clustered disks is an additional
feature provided by the DG/UX Cluster package, which must be
purchased separately from the DG/UX® System product. Clusters is an
optional DG/UX add-on that will automate many features of system
resource management, failover, and high availability. A DG/UX
cluster is a group of two or more interconnected computer systems
(referred to as nodes) acting together in a closely coordinated way.
A cluster does what a server in a client/server environment does:
manages computing resources and provides services to clients.
NOTE: The following information about clustered disks applies to
your use of admvdisk only if you have this feature.
Physical disks may be clustered using the admpdisk command.
Restrictions apply to many of the operations described here when
targeting virtual disks that reside upon clustered physical disks.
The modify operation is limited to making a virtual disk a volume or
not. On-line copy and move operations are not supported. Both the
source and destination virtual disks must be taken off-line (or
unmounted) before performing the copy or move.
Clustered physical disks have some restrictions in the virtual disk
types they may contain. In general, you can create partitions
(including bad block remapping) and build aggregations. Aggregations
cannot span both clustered and non-clustered physical disks. Such an
aggregation would have parts (residing on non-clustered disks) that
would be inaccessible by other nodes, defeating the purpose of having
clustered disks. Software mirrors and caches are not allowed on
clustered physical disks. You can neither create nor insert such
virtual disks on clustered physical disks.
Note that when physical disks are not clustered, there are no
mechanisms that prevent you from building a configuration that is not
allowed on clustered disks, for example a mirrored virtual disk.
Appropriate errors are reported when the attempt is made to cluster
such physical disks.
The admvdisk command allows the creation and management of all types
of virtual disks on physical disks that are not clustered at the time
of the operation. Note, however, that the admpdisk command will
refuse to cluster a physical disk that contains a type of virtual
disk not supported or that contains an aggregation in which a part
does not reside on a clustered disk.
The -P (Partition) Option
When creating, expanding, or linking children to a virtual disk, it
is sometimes convenient to create an unnamed partition and link it to
the parent virtual disk in one operation. The -P (partition) option
is provided to do this. The syntax of this option is:
-P device_spec:starting_block:block_count
device_spec
may be the name of a virtual disk or a DG/UX common device
specification for a physical device upon which the
partition is to be created. In the latter case, the device
must be formatted for virtual disks and registered. Note
that it cannot be formatted for logical disks and
registered in compatibility mode.
starting_block
may be either a block number (in decimal) or a single '*'
character. In the latter case, an appropriate starting
block will be chosen automatically.
block_count
is the number of blocks (in decimal) the partition is to
have.
There is no way to explicitly control whether or not bad-block
mapping is enabled for the unnamed partition (see the section on
creation of partitions, below). If the unnamed partition is created
on a physical disk for which a bad-block mapping facility has been
established (see admpdisk(1M)), then the partition will get bad-block
mapping; otherwise it will not.
If device_spec identifies a virgin virtual disk (one that isn't
already partitioned), the user will be asked to confirm the creation
of the first partition on the virtual disk. This confirmation
request can be suppressed with the -Q (very quiet) option. Note that
virgin virtual disks are exceptional; when a physical device is
formatted, at least one partition is created on it as part of the
formatting operation.
Persistence
Virtual disks have a characteristic called persistence. The
persistence of a virtual disk is one of persistent, floating, or
temporary. Most virtual disks are persistent, which means that a
record of the virtual disks is stored on the physical device(s) with
which the virtual disk is associated, and that record is kept up to
date as modifications are made to the virtual disk. This record
includes information about how the virtual disk is connected to its
children virtual disks. Thus, when the machine is shut down and
rebooted, the virtual disk will continue to exist and be connected
into its hierarchy of virtual disks as it was before.
Occasionally, it is useful to create temporary virtual disks. The
existence of a temporary virtual disk is not recorded on the physical
device, although user data will be written to the appropriate blocks
of the physical device. As a consequence, if the machine goes down
and comes back up, all temporary virtual disks will have vanished.
The floating state can be thought of as "temporarily temporary". The
existence of such a virtual disk is recorded on physical disk,
including a description of the state of the virtual disk as of the
instant just before it was made floating. However, changes to the
state of the virtual disk are not recorded to the physical disk until
such time as the virtual disk is made persistent again. The floating
state is useful for constructing temporary virtual disk hierarchies
involving (normally) persistent virtual disks, where it is desired
that the hierarchy disappear should the system go down unexpectedly.
When the system comes back up, the virtual disks are back in the
configuration they were in before they were made floating.
If a temporary or floating virtual disk is made persistent, its
current state and connections to its children are immediately stored
on the appropriate physical device(s), as are all subsequent
modifications to the virtual disk.
In general, if you don't understand why one would want a virtual disk
to be floating or temporary, then you should make all your virtual
disks be persistent.
Missing Virtual Disks
It is possible to have a virtual disk that contains a reference to a
"child" virtual disk that no longer exists. This can happen if the
physical device that contains the child virtual disk is removed from
the system. It can also happen if a virtual disk is persistent and
has a child that is non-persistent, and the machine is rebooted (for
this reason, having a persistent parent virtual disk with a non-
persistent child is generally not recommended). Such a reference is
in the form of an ID number (not a name). It shows up in the output
of admvdisk -o list without a name. Instead, it is listed as a
missing virtual disk, and its ID number is given. Such a reference
will be listed only in the context of being the child of another
listed virtual disk, never by itself. There is no way to even
determine the (short) name of the now-lost child, as the name is one
of the items that is normally stored on the physical device and now
isn't available. There is also no way to create a new virtual disk
with the old child's ID number, so the dangling reference must be
excised using the unlink operation, specifying the child by its ID
number. There is no need to remove the child virtual disk; it
doesn't exist.
Confirmation
By default, admvdisk asks for confirmation before performing any
potentially destructive operation. In some contexts, such as
invoking admvdisk from an idl(4) script or from a shell script being
run in the background, such requests for confirmation may be
inappropriate. Requests for confirmation can be broken down into two
categories: "standard" ones that are predictable, such as with
removing a virtual disk; and "exceptional" ones that may or may not
be issued, depending upon factors that are determined dynamically.
An example of the latter is when a -P option specifies a virtual disk
to partition that is not already partitioned. The requests for
confirmation that may be generated by any particular operation are
documented below with the operations. To manage this issue, the
following options are provided:
-q Quiet. Standard confirmation requests are suppressed.
Admvdisk behaves as if the request were generated, and the
user gave confirmation. Exceptional confirmation requests
are still generated. This option is appropriate when
admvdisk invoked from an idl(4) script or by a user who is
confident that the requested operation is correct.
-Q Very quiet. Absolutely all requests for confirmation are
suppressed. Admvdisk behaves as if the request were
generated, and the user gave confirmation. This option is
appropriate when admvdisk is invoked from a script that
will be run in the background, so there is no way for a
user to interact with it.
Both the -q and -Q options are legal with all operations, although
they will not have any effect on those operations that don't generate
requests for confirmation. This is to allow one to write shell and
idl(4) scripts that will continue to work correctly even if admvdisk
is changed in the future to have more confirmation queries.
In addition, certain specific confirmation requests may be suppressed
with specific command lines options; for example, the -f option to -o
expand.
OPERATIONS
Generic Operations
These operations can be applied to virtual disks of any type and have
few or no type-specific options.
admvdisk -o list [ -adflLmNpPqQRsv ] [ vdisk ] ...
Lists information about the specified virtual disks.
Virtual disks that are unusable (generally because one or more
of their children are missing or unusable) are listed with their
names enclosed in square brackets ( [ ] ), unless the -q or -Q
option has been specified.
Five basic listing styles are supported: short (-s), medium
(-m), long (-l), recursive (-R), and partition (-p or -f). Two
other styles, physical device (-d) and parent (-P), are also
supported, but they are intended mainly for use by other
software. Only one of these styles may be specified on the
command line. The first three styles produce progressively more
information per virtual disk. The recursive option produces a
short listing per virtual disk listed, but lists whole
hierarchies of virtual disks. The partition style is completely
different.
If none of these options is specified, the default behavior
depends upon whether or not any virtual disk names are specified
on the command line. If no virtual disks are specified, a short
listing is produced for all interesting virtual disks (see
below). If one or more virtual disks are specified to be
listed, a medium listing is produced for the specified virtual
disks.
A "dangling reference" to a child virtual disk that doesn't
exist will appear in medium, long, and recursive listings as a
single line that says that the virtual disk is missing, and
gives its ID number.
By default, certain virtual disks that are deemed
"uninteresting" are left out of certain listings. In the short,
medium, long, and recursive styles, virtual disks with no name
or whose name starts with a period are listed only if they
appear as children of some other virtual disk or are specified
explicitly on the command line. An exception is that virtual
disks of type physical are included and, if they have no name,
are tagged with the Common Device Specification of their
underlying physical device. On a DG/UX cluster, the default
behavior is to list unnamed virtual disks of type physical using
the cluster-wide device name of the underlying physical device
if it has one; otherwise, the common device specification is
listed. The listing can be modified to force the listing of the
common device specification as known on the local node (see the
-N option). Virtual disks whose name starts with a period are
not listed even as children of another virtual disk. In the
partition listing style, virtual disks whose name starts with a
period are grouped together (when adjacent) and listed under a
single entry as "<Various System Partitions>". The -a or -L
option can be used to override this and cause all virtual disks
to be listed.
-a All. Includes "uninteresting" virtual disks in the
listing. Also causes child virtual disks that have no name
to be listed by ID number, rather than <no name>. Also
causes medium, long, and recursive listings of partition
virtual disks to include the remap virtual disk that is a
child of the partition virtual disk (if there is one).
-d Physical devices. Lists the DG/UX Common Device
Specification(s) of all the physical devices that are
associated with the virtual disk(s) listed. On a DG/UX
cluster, the cluster-wide device names are listed unless
modified by the -N option.
-f Free space. If no virtual disks are specified on the
command line, limits listing to those virtual disks upon
which it is plausible to attempt to create a new partition.
Specifically, virtual disks that are full, are not
partitioned but are busy, or reside upon physical devices
that are unwritable, for which writability cannot be
determined, or are registered in compatibility mode are
excluded. Virtual disks that are virgin (are not already
partitioned or otherwise in use) and virtual disks that
reside upon clustered physical disks are included with an
appropriate notation.
In conjunction with -p (below), causes the partition
listing to be limited to free areas (no actual partitions
are listed).
-l Long listing. For each virtual disk listed, everything
that can be listed, including type-specific information, is
listed.
-L Long names. Each virtual disk listed is identified by its
long name, which includes the name, two-part ID number, and
duplicate number. Implies -a.
-m Medium. Several lines of information are produced per
virtual disk listed, including type-specific information,
the names of the virtual disk's children virtual disks (if
any), and type-specific information about the roles played
by the children in the parent virtual disk.
-N Node private names. On a DG/UX cluster, the default
behavior is to list the cluster-wide device names for
unnamed virtual disks of type physical. This option forces
the listings to use of the common device specification for
such virtual disks. This option has no effect on non-
cluster systems.
-p Partitions. Causes listing to be in the partition style.
This is interesting only with virtual disks that are
partitioned or could be partitioned. By default, this
listing includes both the partitions and free space on the
virtual disk. If -f is also specified, only the free areas
are listed. With this option, if no virtual disk names are
specified on the command line, all virtual disks that
contain partitions (i.e., are the children of one or more
partition virtual disks), or upon which it would be
possible to create a partition, are listed.
For each virtual disk listed, the listing includes a
"Comments" field which, if not empty, contains a
description of why the virtual disk is not a good candidate
for being partitioned. This same information will be
represented in the partition/free-space listing as well.
The possible comments and their meanings are:
Main Free Space
Comment Comment Meaning
-------------------------------------------------
busy Virtual disk is not
partitioned and is
in use.
unwritable unwritable Underlying physical
device(s) cannot be
written, or
underlying physical
virtual disk has
writing disabled.
maybe maybe Cannot determine if
unwritable unwritable underlying physical
device(s) can be
written.
compatibility unusable Underlying physical
mode device is
registered in
compatibility mode
not virgin Virtual disk has no
partitioned partitions on it
and is not in use.
full Virtual disk is
partitioned but has
no free space.
small Virtual disk is
small enough that
space will not be
allocated on it
automatically (this
is to prevent
allocation of space
on NVRAMs and
floppy diskettes).
clustered clustered Underlying physical
device is
clustered.
Only those disks that appear with none of these comments
will be considered when allocating space to satisfy a -n
nblocks option as part of a create or expand operation.
However, there are two exceptions, as follows:
· An operation with the -d option will consider all free
space on the specified virtual disk, and no space on any
other virtual disk. (See the descriptions of the create
and expand operations for details about the -d option.)
· When creating a virtual disk (with no -d option speci
fied), clustered free space can be requested via the -F
clustered option. (See the descriptions of the create
operation for details about the -F option.) Expanding a
virtual disk that resides upon a clustered physical disk
is not currently supported.
-P Parents. The parent virtual disk(s) of each virtual disk
specified are listed. Currently valid only in conjunction
with the -Q (very quiet) option; this may change in the fu
ture.
-q Quiet. Output is in a format appropriate for parsing by
other software: no headers, fields are separated by colons
instead of white space.
-Q Very Quiet. Lists only the names of the virtual disks. In
conjunction with -f, lists only virtual disks that have
some free space available for allocation.
-R Recursive. All descendent virtual disks (including those
with null names, but by default not including those with
names that start with a period) are listed hierarchically.
The information listed per virtual disk is the same as with
the -s option.
-s Short. One line of output is produced per virtual disk
listed. The line includes the name of the virtual disk, an
indication of whether or not it is a volume (V for a normal
volume, L for a vdisk that is a volume but has only long-
name entries under /dev/dsk because of a name conflict,
blank for non-volume), an indication of its persistence (T
for temporary, F for floating, blank for persistent), the
size of the virtual disk in blocks, and a short type-
specific description of the virtual disk.
-v Verbose. The same as -alL.
admvdisk -o remove [ -p ] [ -q ] [ -Q ] vdisk ...
Removes the specified virtual disk(s). The virtual disk(s) must
not be open.
-p Preserve. By default, descendents of the specified virtual
disk(s) that have null names, have no other parent virtual
disks, and are not in use in any other way are also re
moved; the -p option prevents this.
-q Quiet. Suppress asking user to confirm removing vdisk.
-Q Very quiet. Suppress asking the user to confirm anything.
admvdisk -o link [ -q ] [ -Q ] { -c child_vdisk |
-P device_spec:starting_block:block_count } ... parent_vdisk
Links the specified children virtual disk(s) or newly created
unnamed partitions to the parent virtual disk. A virtual disk
that is to be made the child must not be open.
If parent_vdisk is a cache, and the child to be linked to it is
not already formatted for use as a cache front end, it will be
so formatted before it is linked to parent_vdisk. Unless the -Q
option is specified, the user will be asked to confirm before
this is done.
The treatment of newly linked children depends upon the type of
the parent virtual disk to which the child is linked:
Partition, Physical, and Remap
You cannot link additional children to virtual disks of
these types.
Aggregation
Additional children are linked to the end of the aggrega
tion (i.e., after the highest-numbered existing child of
the aggregation), making the aggregation larger. No mecha
nism is provided for linking a new child to an aggregation
ahead of existing children. If the aggregation resides on
clustered physical disks, then any newly linked children
must also reside on clustered physical disks.
Do not use this operation to expand an aggregation that
contains a file system, as this will not correctly update
the file system data within the virtual disk. Use the adm
filesystem(1M) command to expand such virtual disks.
Cache
Additional children are used as front-end (small, fast) de
vices. Virtual disks that are being used as front-end de
vices may be dynamically shared between multiple cache vir
tual disks.
Mirror
Additional children are made images of the mirror. When
linked, they are marked as "corrupt"; a sync operation must
be performed on them before they will be put into use. A
mirror virtual disk can have no more than three images, but
any of those images could be mirrors themselves, thus al
lowing more images in total. The new image must be the
same size as the mirror.
-q Quiet. Suppress any standard requests for confirmation.
Currently there are none.
-Q Very quiet. Suppress asking the user to confirm anything.
admvdisk -o unlink [ -p ] [ -q ] [ -Q ] { -c child_vdisk } ... par
ent_vdisk
admvdisk -o unlink -m miss
ing_child_generation_num,missing_child_system_id parent_vdisk
Unlinks the specified children virtual disk(s) from the parent
virtual disk.
In the first form shown above, this operation unlinks
child_vdisk(s) from the parent virtual disk.
-p Preserve. By default, if child_vdisk is unnamed and has no
other parent virtual disk and is not in use in any other
way, it and any unnamed descendents it has are removed af
ter child_vdisk is unlinked from parent_vdisk. The -p op
tion prevents this.
-q Quiet. Suppress any standard requests for confirmation.
Currently there are none.
-Q Very quiet. Suppress asking the user to confirm anything.
By default, the user is prompted to confirm removal of un
named children; this option suppresses confirmation.
The effect on parent_vdisk depends on its type:
Partition, Physical, and Remap
You cannot unlink children from virtual disks of these
types.
Aggregation
The aggregation is reduced in size by the size of the
child. If the aggregation has only one child, you cannot
unlink that child.
Do not use this operation to shrink an aggregation that
contains a file system, as this will not correctly update
the file system data within the virtual disk. Use the adm
filesystem(1M) command to shrink such virtual disks.
Cache
You may unlink only front-end virtual disk from a cache;
the back-end virtual disk cannot be unlinked. The contents
of the front end are flushed to the back end before the
front end is unlinked.
Mirror
The number of images is reduced. If the mirror is in use,
it must be left with at least one in-sync image.
In the second form above, this operation removes a dangling ref
erence to a non-existent virtual disk from parent_vdisk. The
generation number and system ID of the missing child must be ex
pressed in hexadecimal, as they are shown by the list operation.
admvdisk -o rename [ -q ] [ -Q ] -n new_name vdisk
Gives the specified virtual disk the name specified with the -n
option.
If the virtual disk is listed in /etc/fstab as containing a file
system to be mounted, the reference in /etc/fstab will not be
automatically updated to reflect the new name. See admfilesys
tem(1M).
-q Quiet. Suppress any standard requests for confirmation.
Currently there are none.
-Q Very quiet. Suppress asking the user to confirm anything.
By default, the user is prompted to confirm the name change
when there is already a virtual disk named new_name; this
option suppresses confirmation.
-n New name. Name to give to the specified virtual disk. To
make a virtual disk have no name, specify -n "". New_name
must be just a short name; it cannot include any other com
ponents of a long name.
admvdisk -o expand [ -B ] [ -f ] [ -q ] [ -Q ] { { -c child_vdisk |
-P device_spec:starting_block:block_count } ... | -n nblocks }
vdisk
Expands vdisk so that it has more usable blocks.
In general, virtual disks that contain file systems should not
be expanded with this operation, as this will not correctly up
date the file system data within the virtual disk. Use the adm
filesystem(1M) command to expand such virtual disks.
The way the expansion is done depends upon whether -c, -P or -n
option(s) are used, and on the type of vdisk. In some cases,
expansion will simply make an existing partition longer. In
other cases, expansion will either insert a new aggregation or
link a child into an existing aggregation. See the option de
scriptions below for details.
Adding an aggregation to clustered physical disk is not a prob
lem as aggregations are supported; however, any newly linked
children must also reside on clustered physical disks.
-c child_vdisk
Child virtual disk specification. The child must be a par
tition (so that -o shrink can handle it later). This is
handled according to the type of vdisk:
Partition
An aggregation is inserted at vdisk, so that the first
child of the aggregation is the existing partition
(now unnamed), and the aggregation is expanded as de
scribed below.
Aggregation
For each -c option, the child is linked to the aggre
gation.
-P device_spec:starting_block:block_count
Partition specification. This is handled according to the
type of vdisk:
Partition
If the space designated follows immediately after
vdisk, or if no starting_block is specified and
block_count blocks are available immediately following
vdisk, then vdisk is simply made longer. Otherwise,
an aggregation is inserted at vdisk, so that the first
child of the aggregation is the existing partition
(now unnamed), and the aggregation is expanded as de
scribed below.
Aggregation
For each -P option, an unnamed partition is created
according to the values accompanying the -P option and
is linked to the aggregation. This may be optimized
by expanding the last child of the aggregation, if do
ing so is compatible with the parameters of the first
-P option.
-n nblocks
Number of blocks to add to vdisk. Space is automatically
selected from all the available free space (as defined in
the list operation). This is handled according to the type
of vdisk:
Partition
If there is empty space following the partition, it is
made longer. If that isn't sufficient, an aggregation
is inserted at vdisk, so that the first child of the
aggregation is the existing partition (now unnamed),
and the aggregation is expanded as described below.
Aggregation
If there is empty space following the last child of
vdisk, then that child is expanded. If that isn't
sufficient, more unnamed partitions are created and
linked to vdisk.
-B Bootable. Enforce that the resulting virtual disk is one
that can be booted from, i.e., that an executable image
such as /dgux or /usr/stand/sysadm could be loaded from.
Currently, the requirements are that the virtual disk be
either a partition on a physical device (technically, a
partition on a physical virtual disk), or an aggregation of
such partitions, all on the same physical device. These
requirements may be relaxed in the future.
-q Quiet. Suppress any standard requests for confirmation.
Currently there are none.
-Q Very quiet. Suppress asking the user to confirm anything.
-f Filesystem. Suppress asking user for confirmation when ex
panding a virtual disk that appears to contain a DG/UX file
system.
Currently, the expand operation is supported only for partitions
and aggregations of partitions; this may change in the future.
Striped aggregations cannot be expanded.
admvdisk -o shrink [ -q ] [ -Q ] [ -f ] -n nblocks vdisk
Shrinks the specified virtual disk by nblocks. Nblocks must be
less than the number of blocks in vdisk.
Shrinking cannot be done on-line, i.e., the virtual disk to be
shrunk cannot be opened by an application, mounted as a file
system, or be swapped on by the kernel; nor can any of the vir
tual disk's ancestors. However, it is acceptable for the virtu
al disk that is being shrunk to be the child of another virtual
disk (that is not currently being accessed).
Shrinking is handled according to the type of vdisk:
Partition
The partition is made smaller.
Aggregation
The aggregation's children must all be partitions. Pro
ceeding from the end towards the beginning of the aggrega
tion, children are either unlinked, or if that would make
the aggregation too small, shrunk (a maximum of one child
will be shrunk). Unlinked children are deleted if their
names are null. If deleting a child leaves the aggregation
with one unnamed child, the aggregation is extracted, leav
ing the partition with the aggregation's name in its place
(see the extract operation).
Currently, the shrink operation is supported only for partitions
and aggregations of partitions; this may change in the future.
Striped aggregations cannot be shrunk.
In general, virtual disks that contain DG/UX file systems should
not be shrunk with this operation, as this will not correctly
update the file system data within the virtual disk. Use the
admfilesystem(1M) command to shrink such virtual disks.
-q Quiet. Suppress any standard requests for confirmation.
Currently there are none.
-Q Very quiet. Suppress asking the user to confirm anything.
-f Filesystem. Suppress asking user for confirmation when
shrinking a virtual disk that appears to contain a DG/UX
file system.
admvdisk -o extract [ -q ] [ -Q ] parent_vdisk
Reverses the effect of an insert operation (see below).
This operation collapses the parent and child into one virtual
disk that has the name and unique ID of the parent but the type
and type-specific attributes of the child.
-q Quiet. Suppress any standard requests for confirmation.
Currently there are none.
-Q Very quiet. Suppress asking the user to confirm anything.
admvdisk -o copy [ -q ] [ -Q ] [ -f ] [ -T throttle_value ] -s
source_vdisk -d destination_vdisk
Copies source_vdisk to destination_vdisk. Destination_vdisk
must be the same size as source_vdisk and must not be open. If
source_vdisk or destination_vdisk resides upon clustered physi
cal disks, then source_vdisk must not be mounted or otherwise
opened. The user is asked to confirm the operation before it
proceeds.
-q Quiet. Do not ask the user to confirm overwriting of des
tination_vdisk.
-Q Very Quiet. Do not ask the user to confirm anything.
-f Filesystem. Suppress asking user for confirmation when
copying a virtual disk that appears to contain a DG/UX file
system to a larger virtual disk.
-T Throttle_value
Slows down the operation so as to reduce interference with
other disk operations. Throttle_value milliseconds of de
lay are inserted between succeeding I/O operations. Larger
values lead to slower copying of data; the default is 0
(full speed). The throttle_sync operation can be used to
adjust this value after the copy has started.
admvdisk -o move [ -n new_source_name ] [ -q ] [ -Q ] [ -f ]
[ -T throttle_value ] -s source_vdisk -d destination_vdisk
Copies the contents of source_vdisk to destination_vdisk. Also,
it restructures the virtual disks so that destination_vdisk as
sumes the role previously held by source_vdisk (either as the
child of another vdisk(s), or as a volume, or both), and renam
ing destination_vdisk to "source_vdisk". Note that renaming af
fects only the short name; even if a long name is specified on
the command line, each virtual disk retains its original ID num
ber.
If a new_source_name is specified, then the old source_vdisk is
renamed to new_source_name. New_source_name must be just a
short name, it cannot include any other components of a long
name. If no new_source_name is specified, the source disk is
removed.
Destination_vdisk must not be open and must be the same size as
source_vdisk. If source_vdisk or destination_vdisk resides upon
clustered physical disks, then source_vdisk must not be mounted
or otherwise opened. The user is asked to confirm before the
operation proceeds.
-q Quiet. Do not ask the user to confirm overwriting of des
tination_vdisk.
-Q Very Quiet. Do not ask the user to confirm anything.
-f Filesystem. Suppress asking user for confirmation when
moving a virtual disk that appears to contain a DG/UX file
system to a larger virtual disk.
-T Throttle_value
Slows down the operation so as to reduce interference with
other disk operations. Throttle_value milliseconds of de
lay are inserted between succeeding I/O operations. Larger
values lead to slower movement of data; the default is 0
(full speed). The throttle_sync operation can be used to
adjust this value after the move has started.
admvdisk -o specify [ -q ] [ -Q ] vdisk
Displays the DG/UX Common Device Specification for the virtual
disk (see Managing the DG/UX System). This will have the form
vdm(longname). This is useful in conjunction with
name@physical_device_spec syntax when there are virtual disks
with duplicate names, to determine which entry under /dev/dsk
resides on a particular physical device. For example,
mount /dev/dsk/`admvdisk -o specify 'foo@sd(insc(),0)'` /foo
will cause the virtual disk named foo that resides on physical
disk sd(insc(),0) to be mounted as /foo, even if there are mul
tiple virtual disks named foo.
The vdisk expression, be it of the form vdisk_name@pdisk_spec,
short vdisk name, or long vdisk name, must uniquely identify a
single virtual disk. If it is ambiguous, it is considered to be
an error.
-q Quiet. Suppress any standard requests for confirmation.
Currently there are none.
-Q Very quiet. Suppress asking the user to confirm anything.
Create, Insert, and Modify Operations
These three operations share a set of type-specific options, de
scribed below. The create operation can create partition and aggre
gation virtual disks upon clustered physical disks, but will not cre
ate cache, or mirror virtual disks upon such physical disks. The in
sert operation will not create cache, or mirror virtual disks that
reside on clustered physical disks. Virtual disks that reside on
clustered physical disks can only be changed via the modify operation
to be and not to be a volume.
There are two ways to cause a new virtual disk to come into exis
tence: the create operation and the insert operation. Each can be
used in ways that the other cannot.
The create operation is the more straightforward of the two. There
are two ways to use the create operation: normal and short-cut. With
the normal method, you specify the type (e.g., partition), optional
generic and type-specific information, zero or more child virtual
disk (-c) or partition-creation (-P) options, and the name to give to
the new virtual disk. Virtual disk(s) specified with -c option(s)
must not be open at the time of the creation. Depending upon the
type of the virtual disk being created, there may be other restric
tions on what must be specified; see below. The new virtual disk is
created with the type, attributes, children and name specified.
With the short-cut create operation, you do not specify the type of
the virtual disk, any type-specific options, or the names of any
children. You do specify either one or more partition creation (-P)
options or a number of blocks, optional generic characteristics, and
the name to give to the new virtual disk. Either a single partition
or an aggregation of unnamed partitions is created.
The insert operation is designed to allow on-line modification of the
virtual disk hierarchy, while the virtual disks are open. Another
way to look at this is as changing the type of a virtual disk. The
name "insert" is actually a little bit misleading. In fact what hap
pens is that an existing virtual disk is split into two virtual
disks, of different types and different names, related as parent and
child. These two partially defined virtual disks are each then com
pleted with information supplied with the insert operation. Specifi
cally, the existing virtual disk's name, unique identifier number and
generic characteristics (see below) are assigned to the parent virtu
al disk, while the child virtual disk gets the existing virtual
disk's type (e.g., partition) and type-specific attributes. Con
versely, the new name and generic characteristics specified with the
insert operation are assigned to the child virtual disk, and the par
ent virtual disk is given the type and type-specific attributes spec
ified with the operation.
The result of an insertion is a child-parent virtual disk pair, the
parent having only the one child. If you want the parent to then
have other children, you must link them to the parent separately.
The generic characteristics mentioned above include:
· Name.
· ID number.
· Whether or not the virtual disk is a volume.
· The virtual disk's persistence.
The syntax for the normal and short-cut versions of the create opera
tion are:
admvdisk -o create -t type [ -q ] [ -Q ] [ -v { y | n } ]
[ -p { p | t } ] { -P device_spec:starting_block:block_count |
-c child_vdisk } ... { type-specific options } new_vdisk
admvdisk -o create [ -q ] [ -Q ] [ -v { y | n } ] [ -p { p | t } ]
{ { -P device_spec:starting_block:block_count } ... |
-n nblocks [ -d dest_device | -F disk_set ] } new_vdisk
-q Quiet. Suppress any standard requests for confirmation.
Currently there are none.
-Q Very quiet. Suppress asking the user to confirm anything.
-v y/n
do/don't make vdisk a volume. Default for create is y.
-p p/t
persistence: persistent or temporary (a new virtual disk
cannot be created in the floating state). Default for cre
ate is persistent.
-c child_vdisk
Specifies a virtual disk to use as a child of the new vir
tual disk. In general, multiple children may be specified;
exceptions are identified below.
-P device_spec:starting_block:block_count
Partition specification, as described above. An unnamed
partition is created and linked to vdisk.
In general, -c and -P options may be intermixed. Excep
tions are identified below.
-n nblocks
Number of blocks to give to new_vdisk. Space is automati
cally selected from all the available free space (as de
fined in the list operation). On a DG/UX cluster, space is
selected based on the -F disk_set option (see below). One
or more partitions are created; if more than one, an aggre
gation is created as their parent.
-d dest_device
Virtual disk upon which to allocate blocks specified by -n
nblocks. This may be any virtual disk, but in general will
be a physical disk. If this option is used, space will be
allocated only from dest_device, and, moreover, dest_device
will be considered acceptable even if it would otherwise
not have been chosen for use in conjunction with the -n op
tion (due, for example, to it being previously unparti
tioned). Only one -d option may be given.
-F disk_set
On a DG/UX cluster, this option specifies which set of
physical disks upon which to allocate blocks specified by
-n blocks. Valid values for disk-set are
· clustered, meaning to look only on clustered physical
disks;
· unclustered, meaning to look only on physical disks
which are not clustered; or
· all, meaning to look on all physical disks.
On a DG/UX cluster, the default is clustered. On non-cluster
systems, the default is unclustered.
new_vdisk
The name to assign to the new virtual disk. This must be
just a short name, it cannot include any other components
of a long name.
admvdisk -o insert -t type [ -q ] [ -Q ] [ -v { y | n } ]
[ -p { p | t } ] [ -n new_name ] { type-specific options } ex
isting_vdisk
-q Quiet. Suppress any standard requests for confirmation.
Currently there are none.
-Q Very quiet. Suppress asking the user to confirm anything.
-v y/n
Volume. This applies to the child virtual disk that will
result from this operation. If no -v option is specified,
and if -n new_name is specified, the child will be made a
volume; if new_name is not specified, the child will not be
made a volume.
-p p/t
persistence: persistent or temporary (a new virtual disk
cannot be inserted in the floating state). If no -p option
is specified, the child virtual disk is given the same per
sistence that existing_vdisk has, unless that was floating,
in which case the child will be temporary.
-n new_name
Name to give to the resulting child virtual disk; if not
specified, the child will have no name. New_name must be
just a short name; it cannot include any other components
of a long name.
existing_vdisk
The virtual disk whose name gets assigned to the parent and
whose type gets assigned to the child.
admvdisk -o modify [ -q ] [ -Q ] [ -v { y | n } ]
[ -p { p | f | t } ] { type-specific options } existing_vdisk
-q Quiet. Suppress any standard requests for confirmation.
Currently there are none.
-Q Very quiet. Suppress asking the user to confirm anything.
-v y/n
Volume yes/no. Make the virtual disk be or not be a vol
ume.
-p p/f/t
Persistence: persistent, floating, or temporary. A per
sistent virtual disk may be modified to be either floating
or temporary. However, a virtual disk in either the float
ing or temporary state cannot be modified to the other of
these two states; its persistence can be modified only to
persistent.
existing_vdisk
The virtual disk to modify. Only the -v option is support
ed for virtual disks that reside on a clustered physical
disk.
The type-specific options available with the create, insert, and mod
ify operations are:
partition: [ -m { y | n } ] vdisk
Partitions may be created and modified, but insertion of parti
tions is not supported.
-m y/n
Do/don't perform bad-block mapping. Bad-block mapping is
available only on partitions of physical devices (techni
cally, partitions of a virtual disk of type physical).
There is no need to provide bad-block mapping on physical
devices that do their own error correction, such as non-
volatile RAM "disks", hardware disk mirrors, etc.
By default, if the device has a remap virtual disk associ
ated with it, then partitions created on the device are
given bad-block mapping; otherwise, they are not. The de
vice must have a remap virtual disk for partitions on the
device to have mapping performed on them; see admpdisk(1M).
The following options to the create operation that are ostensi
bly not type-specific are treated specially with -t partition as
described here:
-c child_vdisk
Not allowed.
-P device_spec:starting_block:block_count
Exactly one -P option must be specified. It is used to
specify the one partition to create. No unnamed partition
is created.
aggregation: [ -s stripe_size_in_blocks ] vdisk
-s stripe_size_in_blocks
Causes the aggregation to be striped, so that succeeding
stripes are stored round-robin on the children of the ag
gregation. Optional with create, not allowed with insert
or modify. All children must be the same size. The size
of each child must be an integral multiple of the stripe
size. If the aggregation will contain a DG/UX file system,
best performance will be obtained if the stripe size is a
power of 2 (2, 4, 8, 16, etc.) blocks. We recommend 16
blocks.
cache: [ -r { y | n } ] [ -w { y | n } ] [ -m { y | n } ]
[ -T { 0 | 1 | a } ] [ -D { y | n } ]
[ -W { weight | rread_weight | wwrite_weight } ]
[ -s search_percentage ] [ -f { 0 | c } ] vdisk
For a discussion of caching policies, see vdmcache(7). The
first child of a cache is the "back-end device" (slow and
large), all other children are "front-end devices" (fast and
small). A cache may have zero, one, or many front-end devices.
A front-end device may be dynamically shared by more than one
cache virtual disk, or the underlying device may be partitioned
and the partitions used as separate front-end devices for dif
ferent cache virtual disks.
Front-end devices are added to a cache with the link operation
and removed with the unlink operation. Currently, the front-end
devices may not be defined with the create operation. Instead,
the cache must be created and then the front-end devices con
nected to it with the link operation.
Software caches are not supported upon clustered physical disks.
With the create operation, the child (-c or -P option) must not
reside upon a clustered physical disk. With the insert and mod
ify operations, the existing_vdisk must not reside upon a clus
tered physical disk.
Note that you cannot cluster a physical disk (via the admpdisk
command) if that physical disk contains a cache virtual disk.
The options listed here can be used only with the modify opera
tion, not create or insert.
-r y/n
Do/don't do cache reads. When a new cache is created or
inserted, caching of reads is enabled.
-w y/n
Do/don't do cache writes. When a new cache is created or
inserted, caching of writes is enabled.
-m y/n
Do/don't do cache only file system metadata. When a new
cache is created or inserted, caching is not limited to
file system metadata.
-T 0/1/a
Asynchronous write ("write through") policy. In addition
to any writing to the cache back-end device caused by nor
mal cache flushing, schedule an asynchronous write (to the
back-end device) of each block written to the cache:
0 Never
1 The first time a block is written to the cache. This
is the default when creating or inserting a new cache.
a On all writes to the cache.
-D y/n
Enable/disable use of Direct Memory Access. When creating
or inserting a new cache, admvdisk will attempt to choose
an appropriate value.
-Wweight
-Wrread_weight
-Wwwrite_weight
Set the retention weight for all, or just the read or
write, operations. Setting the read and write weights to
gether is useful when a front-end device is shared between
cache virtual disks (that are caching different back-end
devices), to give one cache greater priority in allocation
of front-end device buffers. When a new cache is created
or inserted, both weight values are 1. The weight values
must be non-negative integers. The read weight is meaning
ful only if reads are being cached; the write weight is
meaningful only if writes are being cached.
Note that there must not be a space between the r or w and
the subsequent weight string.
-s search_percentage
Percentage of the front-end device(s) to search when look
ing for a buffer. When a new cache is created or inserted,
the search_percentage is 10%.
-f 0/c
Flusher type: none/cyclic. When a new cache is created or
inserted, the flusher type is cyclic.
The following options to the create operation that are ostensi
bly not type-specific are treated specially with -t cache as de
scribed here:
-c child_vdisk
-P device_spec:starting_block:block_count
Back end (big/slow) virtual disk. When creating a cache,
exactly one -c or -P option must be specified. There is no
way to change the back-end device of an existing cache.
When inserting a cache, the existing_vdisk becomes the back
end of the cache.
mirror: [ -a { y | n } ] [ -m min_images ] [ -M Max_images_lost ]
[ -T Throttle_default ]
As many as three children (-c or -P options) may be specified;
to have more images in a mirror, more than one mirror virtual
disk must be used, with one of the mirrors being an image of the
other. The images must all be the same size.
Software mirrors are not supported on clustered physical disks.
With the create operation, the children (-c or -P options) must
not reside upon clustered physical disks. With the insert and
modify operations, the existing_vdisk must not reside on a clus
tered physical disk.
Note that you cannot cluster a physical disk (via the admpdisk
command) if that physical disk contains a mirror virtual disk.
-a y/n
Do/don't automatically start synchronization operation(s)
when system is booted and image(s) are out of sync. De
fault for create and insert is y.
-m min_images
Minimum images that must be present and either in sync or
being synced before the mirror will allow anything else to
open it. When creating or inserting a new mirror, the de
fault value is 1.
-M Max_images_lost
When system is booted, the number of images that were pre
sent the last time the mirror was in a usable state is re
trieved. Until the number of images present (but not nec
essarily in sync) is equal to that old value, less the
max_images_lost parameter, no decisions about auto-
synchronizing are made (in particular, no master image is
chosen), and the mirror is not made usable. When creating
or inserting a new mirror, the default value for
max_images_lost is 2, which means that as soon as a corrupt
and a non-corrupt image are registered, an automatic syn
chronization may be started (if auto-sync is enabled), and
as soon as the minimum images count is satisfied, the mir
ror will be declared usable -- despite the fact that one or
two images that may be more up-to-date than those in use
may be about to be registered.
-T throttle_default
Throttle value for automatically started synchronizations
(at boot time), and default throttle value for manually in
voked synchronizations. See the sync operation. When cre
ating or inserting a new mirror, the default value is 0
(full speed).
The following options to the create operation that are ostensi
bly not type-specific are treated specially with -t mirror, as
described here:
-c child_vdisk
-P device_spec:starting_block:block_count
From one to three -c and -P options (combined) must be
specified. Mirrors cannot have more than three children
(images), although a child may itself be a mirror virtual
disk, effectively allowing an unlimited number of images in
such a cascaded mirror.
physical: [ -w { y | n } ]
Virtual disks of type physical are created with the initialize
-m or install -m operations of the admpdisk command. All you
can do with a physical virtual disk using admvdisk is to modify
the write-enabled attribute. You cannot create or insert a
physical virtual disk.
-w y/n
Do/don't allow writing through the physical virtual disk.
When a physical virtual disk is created, writing is al
lowed. When writing is disallowed, neither data within any
virtual disk nor virtual disk management meta-data may be
written to the disk. This means that no virtual disk asso
ciated with the physical disk may be modified, unless it is
first put into the floating state. Note that one cannot
even make a virtual disk be temporary, because that would
involve erasing it from the physical disk. The sole excep
tion is that if the physical virtual disk is modified to
allow writing, that one modification is written to the
meta-data area -- whereupon anything else can be written.
Note that this does not directly control access to the un
derlying physical disk. In other words, even if the physi
cal virtual disk is set to have writing disallowed, it will
not prevent accessing the physical disk through
/dev/pdsk/physical_disk_name.
The following options to the create operation that are ostensi
bly not type-specific are treated specially with -t physical, as
described here:
-c child_vdisk
-P device_spec:starting_block:block_count
Not allowed.
Type-Specific Operations
The following operations are specific to mirror virtual disks.
Therefore, they cannot be successfully applied to virtual disks re
siding upon clustered physical disks, since it is impossible to cre
ate software mirrors upon clustered physical disks.
admvdisk -o fracture { -c child_image_vdisk } ... [ -g granularity ]
[ -q ] [ -Q ]
Fractures a mirror image. At least one child_image_vdisk must
be specified.
The fracture operation makes the child_image_vdisk unavailable
for I/O operations. Write operations to the fractured mirror
image(s) are logged by the kernel. When the child_image_vdisk
is resynchronized with the mirror vdisk using the -o sync opera
tion, only those blocks modified since the fracture operation
are updated (see the -g granularity option). The fracture oper
ation is useful for taking mirror image(s) off-line temporarily
for back-up. Once the back-up is complete, the mirror image(s)
can then be efficiently resynchronized. There are some restric
tions. You cannot fracture the last in-sync mirror image, and
you cannot fracture an out-of-sync mirror image. If the system
goes down while a mirror image is fractured, the logged informa
tion is lost. When the system comes back up, a complete sync
must be performed on the mirror image.
-g granularity
To understand how to use the granularity option, it is im
portant to understand how the kernel keeps track of modi
fied blocks while a mirror image is fractured. For each
mirror image fractured, the kernel uses a bitmap to log
modifications to the mirrored vdisk. Consider the case
where granularity is one. In this case, each bit repre
sents one block. If a block on the mirror vdisk is modi
fied, the corresponding bit in the bitmap is set. When the
mirror image is synced, the bitmap is used to determine
which blocks need to be copied. The granularity refers to
the number of blocks or range of blocks represented by each
bit in the bitmap. A granularity of 128 means that each
bit represents a range of 128 blocks on the mirror vdisk.
If any block in a range is modified, the bit representing
the range is set. When a sync is performed, the entire
range is copied, because at this granularity it isn't known
which block was modified, only that at least one was modi
fied. There is a trade-off between using large and small
granularity values. Larger values use less kernel re
sources (smaller bitmap); however, the sync is not as effi
cient. Smaller values use more kernel resources but pro
vide a more efficient sync. The granularity and size of
the mirrored vdisk determine the amount of kernel resources
(size of bitmap) required to log the modified blocks, so
care should be taken when selecting a value. The default
value is 128 and is a suitable place to begin when deter
mining a value. In general, if little data will be modi
fied while a mirror image is fractured, then smaller values
should be used. Conversely, if large amounts of data will
be modified, then a larger value should be used. Another
consideration is the type of data on the mirrored vdisk.
If there is a database on the vdisk, then the database page
size may be a more appropriate granularity value. Note
that the granularity value will be taken by admvdisk as a
'hint'. This means that if the kernel resources don't ex
ist (due to system load, size of mirrored vdisk, etc.) to
support the user-supplied value (or the default), the ker
nel will try larger values (which require less kernel re
sources) until it succeeds. This behavior provides greater
flexibility for unattended back-ups. The user is notified
if a different granularity value is used.
-q Quiet. Suppress any standard requests for confirmation.
Currently there are none.
-Q Very quiet. Suppress asking the user to confirm anything.
admvdisk -o sync [ -q ] [ -Q ] [ -T throttle_value ]
[ -s source_image ] { { -d dest_image_vdisk } ... |
mirror_vdisk ... }
Initiates synchronization of mirror image(s). Either a mir
ror_vdisk or one or more dest_image_vdisk(s) must be specified
(but not both). If you specify more than one dest_image_vdisk,
they must all be images of the same mirror. If one or more mir
ror_vdisk(s) are specified, all corrupt images of the mirror(s)
are synced. One sync operation to multiple destination images
of the same mirror is more efficient than multiple sync opera
tions.
-s source_image
Image to use as the source. The -s option must be supplied
when there are no in-sync images. Not required when there
is at least one in-sync image; one of the in-sync images is
selected as the source image automatically. A corrupt im
age cannot be specified when there is at least one in-sync
image. If the -s option is used, source_image must be an
image in the same mirror as mirror_vdisk or
dest_image_vdisk(s) specified.
-T Throttle_value
Slows down the operation so as to reduce interference with
other disk operations. Throttle_value milliseconds of de
lay are inserted between succeeding I/O operations. Larger
values lead to slower synchronization. If no Throt
tle_value is provided, the default throttle value associat
ed with the mirror is used. Earlier implementations of
software mirroring offered a single "slow" value that was
roughly comparable to a throttle value of 100.
-q Quiet. Suppress any standard requests for confirmation.
Currently there are none.
-Q Very quiet. Suppress asking the user to confirm anything.
admvdisk -o terminate_sync [ -q ] [ -Q ]
{ { -d dest_image_vdisk } ... | mirror_vdisk ... }
Terminates a synchronize operation. Either dest_image_vdisk or
mirror_vdisk must be specified. If the latter is specified, all
synchronize operations involving images of that mirror are ter
minated.
If a single synchronize operation is being used to update two
destinations simultaneously, terminating the synchronize for one
destination will not affect the synchronization of the other
destination.
-q Quiet. Suppress any standard requests for confirmation.
Currently there are none.
-Q Very quiet. Suppress asking the user to confirm anything.
admvdisk -o throttle_sync -T throttle_value [ -q ] [ -Q ]
{ { -d dest_image_vdisk } ... | mirror_vdisk ... }
Throttles (sets the speed of) a synchronize operation. Either
dest_image_vdisk or mirror_vdisk must be specified. If the lat
ter is specified, all synchronize operations involving images of
that mirror are throttled.
If a single synchronize operation is being used to update two
destinations simultaneously, throttling the synchronize for ei
ther destination will result in the whole synchronize operation
being throttled, for both destinations.
-q Quiet. Suppress any standard requests for confirmation.
Currently there are none.
-Q Very quiet. Suppress asking the user to confirm anything.
FILES
/dev/dsk/* block special virtual disk devices
/dev/rdsk/* character special virtual disk devices
DIAGNOSTICS
Exit Codes
0 The operation was successful.
1 The operation was unsuccessful.
2 The operation failed due to access restrictions.
3 There was an error in the command line.
SEE ALSO
admpdisk(1M), admfilesystem(1M), vdm(7), vdmaggr(7), vdmcache(7), vd
mmirr(7), vdmpart(7), vdmphys(7), vdmremap(7).
Licensed material--property of copyright holder(s)