dkconfig(ADM)

dkconfig -- virtual disk configuration utility

Syntax

/etc/dkconfig -a -cdefilpsTuUy

/etc/dkconfig -b

/etc/dkconfig -cdefilpsTuUy vdisk_device ...

/etc/dkconfig -g

/etc/dkconfig -h vdisk_device ...

/etc/dkconfig -o vdisk_device ...

/etc/dkconfig -O piece_number vdisk_device ...

/etc/dkconfig -r vdisk_device ...

/etc/dkconfig -R vdisk_device ...

/etc/dkconfig -v vdisk_device ...

/etc/dkconfig -V vdisk_device ...

/etc/dkconfig -w

/etc/dkconfig -z vdisk_device ...

/etc/dkconfig -Z partition

Description

dkconfig provides control over the configuration of virtual disks based on their definitions in the /etc/dktab disk configuration file (see dktab(F)).

The Virtual Disk Manager provides a convenient graphical front-end to dkconfig. It is recommended that you use this interface to administer your virtual disks. If you need to configure more complicated nested virtual disk arrays than the Virtual Disk Manager provides, you must add the new definitions to /etc/dktab and run dkconfig manually.

dkconfig reads /etc/dktab to obtain virtual disk configuration information in the same way that mount(ADM) reads /etc/mnttab to obtain mountable filesystem information. The virtual disk definitions in /etc/dktab are used by dkconfig both to configure virtual disks and to list the current virtual disk configuration.

If you alter the definition of a virtual disk while it is configured, this initiates an online reconfiguration which rearranges the virtual disk's data to fit the new definition. If you alter a virtual disk's definition while it is offline, the virtual disk subsystem in the operating system kernel is not aware that the definition has changed. When the virtual disk is configured again, the kernel acts as if the virtual disk has always been configured in the new way, and does not attempt to rearrange the virtual disk's data to fit the new definition. In this case the former data in the virtual disk is no longer usable and any filesystem or database structures in it must be re-initialized. Therefore, you should reconfigure virtual disks while they are already configured unless the existing data is no longer wanted or the data has been backed up and can be restored under the new configuration.

When multiple virtual disks are configured (using the -a option), dkconfig checks for any overlap with the partition reserved area (including the bad track/bad block table), other virtual disk definitions in /etc/dktab, and virtual disks defined in the kernel. When defining a virtual disk, you should also check that its pieces do not overlap already existing filesystem divisions, or raw database storage areas.

Once a virtual disk is in use, care must be taken not to corrupt the disk data. For example, a virtual disk cannot be unconfigured if it contains a mounted filesystem. An EBUSY (device busy) error will be returned if any attempt is made to unconfigure a busy virtual disk.

If any virtual disks defined in /etc/dktab contain filesystems, dkconfig must be executed prior to fsck(ADM) or mount(ADM), since a virtual disk must be configured before it can be used. This happens automatically as part of the process of going to multiuser mode; the /etc/inittab script invokes dkconfig to perform disk configuration as specified in /etc/dktab. The /etc/rc2.d scripts are then executed, which performs the filesystem checking. However, to check virtual disk filesystems in single-user mode, enter dkconfig -ac to configure the virtual disk devices before invoking fsck. Attempting to execute fsck on a virtual disk filesystem before configuring it will cause an ENXIO (no such device or address) error.

Although dkconfig only accepts block device nodes (vdisk_device) as command-line arguments (as specified in /etc/dktab), the vdisk(HW) driver supports both block and character device nodes.

dkconfig understands the following options:

-?

Print a list of the available options.

-a

Apply an operation to all virtual disks defined in the /etc/dktab file. When used with the -l option, this excludes the configuration database virtual disk, vdisk0 (see ``Use of the vdisk0 virtual disk'').

-b

Back up the current configuration of virtual disks to the vdisk0 ``dktab'' piece.

-c

Configure one or more virtual disks. This option can also be used on a virtual disk that is configured and in use. If the definition of the virtual disk in /etc/dktab is altered, the utility will allow the virtual disk to be reconfigured online while the application is still running (see ``Virtual disk configuration and unconfiguration'' for more information on reconfiguration).

The -c and -u options perform virtual disk configuration and unconfiguration, analogous to the filesystem mounting and unmounting services of mount(ADM) and umount(ADM).

-d

Disable the array and mirror restore functionality. This option can be used to prevent a restore operation from being performed automatically when the system is booted.

Because most applications always perform a data read before a write, the state of the data and parity can be detected before any writing is done. In the event of a system crash, parity is presumed to be OUT-OF-DATE (OOD) as the data and parity are likely to be inconsistent. In this case, with the restore functionality enabled, consistency will be restored when the system is rebooted.

However, in a minority of situations, for example, when the swap device is being used as a mirror virtual disk, data is first written to the virtual disk before any reads are performed (after a system crash). By first performing a data write which includes a new parity calculation, the data and parity are updated and made consistent. This saves time and system resources as you do not now need to perform a full restore on the whole disk. To achieve this, you need to disable the restore functionality for this virtual disk. Also, this is only applicable where a system reboot is to be performed.

NOTE: If a piece is in the OUT-OF-SERVICE (OOS) state on a virtual disk with the restore disabled, you will need to re-enable the restore functionality before the piece can be brought back into service. Also, when an array is initially configured, the parity is always set to the OUT-OF-DATE state. Under normal circumstances, disabling the restore functionality will have the effect of changing this to the UP-TO-DATE state: disabled restore on a write-first application (swap device) as described above implies a parity update will be performed at the time of the writing. However, since this condition is only considered during system booting, the OUT-OF-DATE state remains unchanged. To change this, you will need to either reboot the system to meet the condition described earlier or use the -r option to force a restore on the whole disk.

Use the -v option (verify) to check if parity is UP-TO-DATE for the entire array (not just the parts which have been written to). If inconsistencies are found between the data and the parity, the array will be marked as having OUT-OF-DATE parity. When an array is marked as this, no parity will be generated on writes (regardless of whether the restore has been disabled or not).

-e

Enable the array and mirror restore functionality.

-f

Force the configuration of a new array and mirror configuration. This allows a new array or mirror virtual disk to be configured for the first time. When used with the -cf option, this initializes the timestamps (see ``Timestamps'') for the pieces of an array or mirror virtual disk. The -f option can also be used to re-initialize an array or mirror virtual disk that has been taken offline due to multiple drive errors. Once an array or mirror virtual disk has been forced online (initialized), it can be configured and unconfigured in the same way as any other virtual disk type.

-g

Get the last saved configuration from the database. The output is printed to the standard output in a format consistent with /etc/dktab.

-h

Halt the following actions: reconfigurations, verifying, restoring and putting a spare online. Halting a reconfiguration operation with either the configuration database not configured, or the configuration database configured but with no spool piece, will corrupt the data held on the virtual disk because not all of the data will have been modified for the new configuration. The spool piece is used to store checkpoints on the progress of a reconfiguration and also when a virtual disk is configured so that any halted reconfiguration can be restarted to modify the rest of the unmodified data. It is recommended that you always unconfigure a virtual disk after a reconfigure has been halted.

-i

Use the standard input for the /etc/dktab file.

-l

List the status of the current virtual disk configuration as defined in /etc/dktab. This status also indicates whether the array or mirror is online or offline. When an array or mirror virtual disk is offline due to pieces going OUT-OF-SERVICE, the virtual disk will no longer accept any I/O requests and data can no longer be accessed.

The I/O statistics listed by the -ls option are used to determine if I/O requests are distributed fairly evenly across physical disks. If they are not, the virtual disk cluster size should be reconfigured. The -ls option can also be used to determine the status of an array or mirror virtual disk piece. There are four possible states. If the I/O count is present the piece is ACTIVE. If a disk piece is marked OUT-OF-SERVICE, the drive needs to be repaired. If a disk piece is marked OUT-OF-DATE, parity needs to be recreated (restored), and, if a piece is marked spare, it is the configured hot spare.

If the -a option is given, dkconfig lists the status of all disks defined in /etc/dktab except the configuration database (vdisk0).

If the -s option is given, dkconfig describes each piece of the virtual disk.

-o

Force a disk piece to the OUT-OF-SERVICE state. This option can only be used with array and mirror virtual disk configurations. Forcing a piece OUT-OF-SERVICE with this option does not cause hot spares to go online. This is done only when real disk errors are encountered. This option is useful in two instances: firstly, if you wish to replace a defective physical disk which is shared by more than one virtual disk, and secondly, for mirror configurations where the parity piece can be forced OUT-OF-SERVICE and then used to take a snapshot backup. OUT-OF-SERVICE pieces are brought back into service by performing a restore with the -r flag.

-O piece_number

Force a disk piece (with piece_number) to the OUT-OF-SERVICE state.

-p

Display the usage statistics of a virtual disk(s). This option displays the read, write, and total I/O count for a virtual disk. It also displays the dominant I/O size used by the application on the virtual disk. For best performance, the dominant I/O size should be equal to or less than the cluster size used on stripe and array virtual disks.

The performance statistics may be used to identify hot spots and may also be used to determine if the virtual disk configuration should be reconfigured to another virtual disk type.

If the -a option is given, performance statistics are displayed for all disks defined in /etc/dktab.

If the -s option is given, performance statistics are also displayed for each piece of the virtual configuration.

If the -T option is given, dkconfig displays performance statistics reflecting the usage of the vdisk driver's resources. This allows you to modify the appropriate kernel tunables.

See ``Tuning virtual disk performance'' in the Performance Guide for more information.

-r
-R: Restore the data on array or mirror configurations. This option can be used to restore either parity data on a new configuration or reconstruct data on a disk that has been repaired.

: The -R option provides a slower restore mode to minimize the impact on system performance.
-s: Use verbose mode for status, states and I/O statistics.
-T: Use with the -p option to display statistics of virtual disk kernel tunable parameters.

-u
-U: Unconfigure one or more virtual disk(s).

: The -U option deletes the timestamps (see ``Timestamps'') and removes the definition from the configuration database.
See also the description of the -c (configure) option.

-v
-V: Verify that redundant data is UP-TO-DATE on array or mirror configurations. This option is provided as a means for ensuring complete data integrity.

: The -v option marks parity OUT-OF-DATE if inconsistencies are found.
The -V option provides a corrective verify operation. The verify operation repairs parity data on arrays and redundant data on mirrors automatically.
-w: Start an instance of the virtual disk daemon (vddaemon). Only one daemon per CPU can be started. Normally the maximum number of daemons is started during startup.
-y: Suppress any interactive questions.
-z: Zero the I/O count for the virtual disk(s). If the -a option is given, I/O statistics are zeroed for all virtual disks defined in /etc/dktab. Otherwise, only the statistics for the named virtual disks are zeroed. This option assists in sampling the performance of virtual disk configurations.
-Z partition: Write zeroes to the timestamp tables in the named raw partition (see ``Timestamps''). The timestamp tables should not normally need zeroing, but this option may be useful when they have become full.
The mkdev hd command uses this option when adding new hard disks to avoid the risk that random values could be used for timestamps.

Virtual disk configuration and unconfiguration

To delete a virtual disk, unconfigure it with dkconfig -U, then remove the configuration from /etc/dktab. If the unwanted disk is not configured when it is no longer needed, then dkconfig -b must be run after /etc/dktab has been edited to update the ``dktab'' piece in vdisk0. If this is is not done, the vdisk driver will restore the virtual disk definition to /etc/dktab when the system is next rebooted.

A virtual disk array or mirror will remain configured if it was taken offline while an application was still running. Before the data can be restored, the virtual disk must first be unconfigured using dkconfig -u, then configured again using dkconfig -cf to reinitialize the timestamps, and dkconfig -r to restore parity data.

When performing online reconfigurations, which includes changing the cluster size, piece size or number of pieces, the specified cluster size may not always be allowed. To simplify the reconfiguration process, select cluster sizes only from the set 2, 4, 8, 16, 32, 64 and 128, and select piece lengths which are multiples of 128 (where the cluster size is also being changed). In this case, all reconfigurations will be valid. Note that these values may not give the best I/O performance.

Some reconfiguration operations involving changing virtual disk types in the configuration may require a larger cluster size to be selected before the specified operation can be performed. If needed, another online operation can be performed to return the cluster size to its desired size.

Use of the vdisk0 virtual disk

Virtual disk vdisk0 is reserved by the configuration database and cannot be used to configure any of the specified virtual disk types. The dkconfig -la command does not display any information for vdisk0. You must specify the block device (/dev/dsk/vdisk0) to view its configuration information.

If vdisk0 is not configured, only the /etc/dktab file provides virtual disk configuration information. Because of this, its integrity must be assured at all times.

Timestamps

The vdisk driver maintains a timestamp table in each partition corresponding to the pieces of an array or mirror virtual disk that are defined for that partition. The timestamps store the status of each piece in order to maintain data integrity. When an array or mirror is configured, the driver reads the timestamps for each piece. For example, if a piece was OUT-OF-SERVICE when the array was last in use, that fact is recorded in its timestamp table. Timestamps also record if a piece is running on a spare or if parity is OUT-OF-DATE. As events happen to an array or mirror, the timestamps are updated to record the new status of the virtual disk pieces. If the -f option is used to bring new and offline arrays online, new timestamps are written to indicate that all pieces are in service and parity is OUT-OF-DATE regardless of the existing contents of the timestamp tables.

Diagnostics

Most diagnostics printed by dkconfig are accompanied by the line number of the erroneous line in the /etc/dktab file. In some cases, after encountering a warning or error, dkconfig continues with the next virtual disk in /etc/dktab.

Cluster size (n) exceeds Length (m): The cluster size of a stripe, array, or mirror virtual disk cannot exceed the length of any of the pieces of the virtual disk. The cluster size may be as small as one block and as large as the size of any piece.
Unequal Lengths (n != m): All pieces of a stripe, mirror or array virtual disk must be the same size.
Length (n) exceeds physical partition size (m): The size of a piece of a virtual disk is larger than the actual size of the physical disk partition.
Length (n) is not a multiple of 2 blocks: Since most filesystems use 1024-byte blocks (two 512-byte physical disk blocks or sectors), dkconfig recommends, but does not require, that partitions be a multiple of two disk blocks. This recommendation only applies to mirrors, stripes, and arrays.
Expected only n piece definition lines: The number of pieces specified on the virtual disk declaration line does not match the number of virtual disk piece definition lines that follow.
Invalid number of pieces (maximum is n): The virtual disk has too many pieces.
Rest of file ignored: An ignore keyword was encountered in the /etc/dktab file.

Examples

Configure all the virtual disks defined in /etc/dktab:

/etc/dkconfig -ac

Print a short summary list of all the current virtual disk configurations:

/etc/dkconfig -al

Print a detailed list of the current virtual disk configuration:

/etc/dkconfig -als

Print a detailed description of virtual disk vdisk1:

/etc/dkconfig -ls /dev/dsk/vdisk1

Print a short description of the first four virtual disks:

/etc/dkconfig -l /dev/dsk/vdisk[1-4]

Unconfigure all virtual disks defined in /etc/dktab:

/etc/dkconfig -au

Configure and initialize an array virtual disk vdisk2:

/etc/dkconfig -cf /dev/dsk/vdisk2

Force disk piece in virtual disk vdisk2 OUT-OF-SERVICE:

/etc/dkconfig -o /dev/dsk/vdisk2

Restore the parity information on an array virtual disk vdisk2:

/etc/dkconfig -r /dev/dsk/vdisk2

Unconfigure virtual disk vdisk2:

/etc/dkconfig -u /dev/dsk/vdisk2

Regenerate the /etc/dktab file from vdisk0 (the configuration database):

/etc/dkconfig -g > /etc/dktab

Warning

Unless the configuration database is configured, and has a spool piece, a reconfiguration which is interrupted by either dkconfig -h or a system crash may cause the contents of the virtual disk to become corrupted.

Limitations

The timestamp table in a partition has space for up to 31 timestamps. Therefore the maximum number of pieces in any one partition is limited to 31 for mirrors and arrays.

Files

/dev/dsk/vdisk#: block special virtual disk devices
/dev/rdsk/vdisk#: character special (raw) virtual disk devices
/etc/dktab: virtual disk configuration file