*** UNIX MANUAL PAGE BROWSER ***

volassist(8) System Manager's Manual volassist(8) NAME volassist - Create, mirror, backup, grow, shrink, and move Logical Storage Manager (LSM) volumes SYNOPSIS /sbin/volassist [ options ] make volume length attribute=value ... [ [!]medianame[,offset] ... ] /sbin/volassist [ options ] mirror volume attribute=value ... [ [!]me- dianame[,offset] ... ] /sbin/volassist [ options ] move volume attribute=value ... !medianame [ [!]medianame[,offset] ... ] /sbin/volassist [ options ] growto volume newlength attribute=value ... [ [!]medianame[,offset] ... ] /sbin/volassist [ options ] growby volume lengthchange attribute=value [ [!]medianame[,offset] ... ] /sbin/volassist [ options ] shrinkto volume newlength at- tribute=value ... /sbin/volassist [ options ] shrinkby volume lengthchange at- tribute=value /sbin/volassist [ options ] snapstart volume attribute=value [!]medi- aname[,offset] ... /sbin/volassist [ options ] snapshot volume newvolume /sbin/volassist [ options ] snapwait volume DESCRIPTION The volassist utility is a one-step interface that finds space for and creates simple volumes, adds simple mirrors to existing volumes, ex- tends and shrinks existing volumes, provides for the migration of data from a specified disk, and provides facilities for the backup of exist- ing volumes. The command is supplied a keyword that selects the action to perform. Each operation can be applied to only one disk group at a time, due to internal implementation constraints. For the make operation, any medi- aname operands will be used to determine a default disk group, accord- ing to the standard disk group selection rules described in volin- tro(8). For other operations, the volume operand is used. A specific disk group can be forced with -g diskgroup. With no medianame operands, the make operation defaults to using the rootdg disk group. An alternate default disk group can be specified in a defaults file (/etc/default/volassist). The medianame operands name disks to use for allocating new space for a volume. These arguments can be either a simple name for a disk media record, or they can be of the form medianame,offset to specify an off- set within the named disk. If an offset is specified, then regions from the that offset to the end of the disk are considered candidates for allocation. A specific disk can be avoided, for allocation purposes, by specifying a medianame operand with a prefix character of ! (or, \! from csh). For example, the command: /sbin/volassist make vol1 1000m !disk03 creates a 1000MB volume on any non-volatile, non-reserved disk other than disk03. KEYWORDS The recognized operation keywords are: Create a volume with the speci- fied name and the specified length. The length is specified as a stan- dard Logical Storage Manager length (see volintro(8)). If medianame operands are specified, then create the volume by allocating subdisks on the indicated disks. With no medianame operands, all non-volatile, non-reserved disks in the disk group are considered candidates for al- location. Attributes can be specified to indicate various desired properties for the created volume. Create a new mirror (plex) and at- tach it to the volume. This operation is allowed only if the volume is enabled. If medianame operands are specified, then create the new mir- ror by allocating subdisks on the indicated disks. With no medianame operands, all non-volatile, non-reserved disks in the disk group are considered candidates for allocation. Attributes can be specified to indicate various desired properties for the new plex. Move subdisks within the named volume off the exclusion disks listed on the command line. Exclusion disks are specified with a prefix of !. The move op- eration requires that at least one exclusion disk be specified. If the volume is enabled, then subdisks within detached or dis- abled plexes will be moved without recovery of data. If the volume is not enabled, then subdisks within STALE or OFFLINE plexes will be moved without recovery; if there are other sub- disks within a non-enabled volume that require moving, then the move operation will fail. For enabled plexes within an enabled volume, log subdisks will be moved to another disk and recovered. Striped plexes within the volume that have a subdisk on the volume will be moved to another disk, and the entire plex will be recovered. Subdisks within concatenated plexes that reside on other disks will be moved and recovered. Increase the length of the named volume to the length specified by newlength, or by the length specified by lengthchange. The new length or change in length is specified as standard Logical Storage Manager length (see volintro(8)). The growto operation fails if the new length is not greater than the current volume length. The length of the volume is increased by extending the length of the last subdisk in each plex of the volume, or by adding new subdisks concatenated to the end of each plex. If medianame operands are specified, then new space is allocated only from the indicated disks. With no medianame operands, all non- volatile, non-reserved disks in the disk group of the volume are considered candidates for allocation. Attributes can be speci- fied to indicate various desired properties for the new alloca- tions. A volume containing one or more striped plexes cannot be grown. Also, growing a volume requires that the volume be enabled. If the volume is mirrored, volassist will attempt to ensure consis- tency of the new allocated extensions to each plex using stan- dard means of plex recovery. File systems such as AdvFS and UFS cannot currently take advan- tage of an enlarged volume. These operations are currently dis- allowed by default to prevent their incorrect use with an exist- ing AdvFS or UFS file system. To override this default behavior and force the volume to grow, you must use the -f force option. Decrease the length of the named volume to the length specified by newlength, or by the length specified by lengthchange. The new length or change in length is specified as standard Logical Storage Manager length (see volintro(8)). The shrinkto opera- tion fails if the new length is not less than the current volume length. The length of a volume is decreased by removing and shortening subdisks to leave each plex with the desired volume length. The freed space can then be allocated for use by other volumes. A volume containing one or more striped plexes cannot be shrunk. File systems such as AdvFS and UFS cannot currently take advan- tage of a shrunk volume. These operations are currently disal- lowed by default to prevent their incorrect use with an existing AdvFS or UFS file system. To override this default behavior and force the volume to shrink, you must use the -f force option. Create a temporary mirror and attach it to the named volume. When the attach completes, the mirror will be considered a can- didate for selection by the snapshot operation. The snapshot operation takes one of these attached temporary mirrors and cre- ates a new volume with the temporary mirror as its one plex. Some usage types will attempt to synchronize any in-memory data associated with the volume (such as unwritten file modifica- tions) when the snapshot operation is done. For ufs, the syn- chronization operation consists of a call to sync(8), which will make the snapshot a better image, but which may leave some in- consistencies between in-memory file system data and the data residing on the backup image. If a snapstart mirror attach is done as a background task (such as using the -b option), it may be convenient to wait for an attached mirror to become avail- able. The snapwait operation waits for such an attach to com- plete on the named volume. When a snapshot attach has com- pleted, the operation exits. OPTIONS The following options are recognized: Specify the disk group for the operation, either by disk group ID or by disk group name. By default, the disk group is chosen based on the medianame operands (if any) for the volassist make operation, or based on the volume operands for all other operations. Limit the operation to apply to this usage type. Attempts to affect volumes with a different usage type will fail. For a volassist make operation, this indicates the usage type to use for the created volume. Otherwise, the default is used and is determined by the existence of an entry in the /etc/default/volassist file or else is set to the fsgen usage type. Pass in usage-type-specific options to the operation. A certain set of operations are expected to be imple- mented by all usage types: Reduce the system performance impact of copy operations. Copy and plex consistency recovery operations are usually a set of short operations on small regions of the volume (normally from 16 kilobytes to 128 kilobytes). This option inserts a delay between the recovery of each such region. A specific delay can be specified with iodelay as a number of milliseconds, or a default is chosen (nor- mally 250 milliseconds). Perform copy and recovery operations in re- gions with the length specified by size, which is a standard Logical Storage Manager length number (see volintro(8)). Specifying a larger number typically causes the operation to complete sooner, but with greater impact on other processes using the volume. The default I/O size is typically 32 kilobytes. Perform extended operations in back- ground. This applies to plex consistency recovery operations for volassist make, growto, and growby. This flag also applies to plex at- tach operations started by either volassist mirror and volassist snap- start. Specify a file containing defaults for various attributes re- lated to volume creation and space allocation. If not specified, this defaults to /etc/default/volassist. Force a volassist growto, growby, shrinkto, or shrinkby operation when a volume is open. ATTRIBUTES Attribute values for various purposes can be specified with arguments of the form attribute=value. Attributes can also be passed in through a defaults file. Default attribute values can be stored in the file /etc/default/volassist. Attributes are selected according to the order in which they are scanned. In general they are taken in decreasing priority of being specified on: The command line The user's defaults file, as supplied with a -d command line argument The system defaults file, as specified by /etc/default/volassist Some attributes have boolean values, which can be on or off. Boolean values can be specified as on or off or as true or false. Some attrib- utes have length values, which can be specified as standard Logical Storage Manager length numbers (see volintro(8)). Some attributes have simple numeric counts, which are specified as simple decimal numbers. Some attributes have string values, which can consist of any string, with some restrictions that depend upon the attribute. Defined attrib- utes are: The number of mirrors to create for a make operation, if mir- roring is requested. This number must be between 2 and 8. If not specified, defaults to 2. If set, create mirrored volumes with the make operation. If no other default exists and this entry is not given, then this attribute defaults to off. Set the disk group to use when creating a volume with the make operation. This option should be used only in a defaults file. The -g option should be used to specify a disk group from the command line. A disk group can be specified ei- ther by disk group ID or by disk group name. The default value for the disk group is rootdg. The usage type to use when creating a volume with the make operation. Usage type names are limited to 14 characters and cannot contain any blanks. If no usage type is specified, this de- faults to fsgen. Allocation granularity size. If set to a non-zero value, this option will force the length for all allocated subdisks to be a multiple of this size. An exception to this rule is for striped plexes. The allocation sizes for subdisks will be adjusted up to be a multiple of the stripe width for the plex. The length for volumes will also be adjusted to match the allocation granularity. Volume lengths will never be less than the size requested from the command line. Alignment boundary size. If set to a non-zero value, this will force all allocations to start on a size-multiple boundary from the start of the public region of a disk. Normally, the value for the align at- tribute should be the same as or larger than the alloc attribute. The primary purpose for align is to increase the likelihood that created subdisks are sufficiently compatible that they can be swapped and moved between disks with a reasonably small set of subdisk split, join, and move operations (see volsd(8)). Specify the layout to use for creating plexes (mirrors). There are two basic layout types: concat and stripe for simple concatenated or striped plexes. If the stripe layout is se- lected, then the nstripe and stwidth attributes will be used to define the characteristics of the striped plex. If the basic layout is concat (the default), then additional layout modifiers may be specified to control allocation of subdisks within the plex to various disks: Allow a plex to be allocated from space on multiple physical disks. Spanned plexes can have better performance in some cases than non-spanned disks, and they can also be larger than any single disk attached to the system. However, without mirroring, a plex that spans several disks will fail if any one of the disks fails, reducing the reliability of the volume. Mirroring can restore and increase the reliability of the volume. Restrict a plex to use space on a single physical disk. Re- strict a plex to a contiguous region of disk. This disables spanning, and also prevents a plex from being scattered across discontiguous sec- tions of a disk. Do not restrict plex allocation to contiguous regions of disk. The striped plex allocation policy is equivalent to allocating nstripe contiguous areas of disk space, on different physical disks, that are each 1/nstripe as large as the volume volume. The number of stripes to create when allocating a striped plex. If not specified, volassist will default the number of stripes to no less than 2, and no more than 8. If medianame operands are specified, then the default will adjust to the number of named disks. If no medianame operands are specified, then the default is half of the candidate disks, adjusted to a number between 2 and 8. This option can only be specified if layout=stripe is also specified. Set the stripe width for striped plexes to the indicated size. If not specified, defaults to 64K. This option can only be specified if layout=stripe is also specified. Set the logging type to use when creating a volume. The two log types recognized are: Do not do any special logging. Log all writes to log subdisks associated with each plex in the volume. This provides much faster volume recovery time, at the expense of degraded performance during normal volume operation. The log subdisks are each 1 block long. By default, volassist allocates log subdisks in a block immediately before the first regular subdisk in the plex. If no default log type is found, but logging is enabled, then blkno is selected as the default. Specify the type of initial- ization to use when creating a volume. If not specified, the volume will be started by calling volume start to use the de- fault initialization procedure. If specified as none, created volumes will remain unstarted and uninitialized. The possible types of initialization are specified in volume(8) under the de- scription of the init operation. NOTES ON OPERATION The volassist utility allows users to create and modify simple volumes through a single command front-end. For the make, mirror, snapstart and grow operations, volassist seeks out available disk space and tries to allocate it in the configuration that conforms to the layout speci- fications and offers the best use of free space. In order to avoid risking the loss of data availability and I/O perfor- mance, volassist will not create volumes with more than one mirror per disk, or striped mirrors with more than one stripe per disk. However, snapshot mirrors may co-reside with normal mirrors of the volume be- cause their association with the volume is temporary and snapshot mir- rors are not used for data access or recovery. volassist creates new volumes in the EMPTY state and attempts to start them. If the volume fails to start, volassist will attempt to remove it and release the space used to allocate this volume. New mirrors can be created for and attached to any enabled volume that is ACTIVE or EMPTY. If the new mirror is successfully attached to the volume, its state is changed to be compatible with the volume. If the attach operation fails, the mirror is removed and the space it occupied is released. If the attach operation is interrupted by a system crash, the mirror will be automatically removed and its space released, when the volume is started again. The snapstart, snapwait and snapshot operations provide a way to backup volumes with minimal interruption to I/O activity. The snapstart oper- ation creates a mirror which gets attached to the volume and brought up-to-date. The end of the update procedure is indicated by the new snapshot mirror changing its state to SNAPDONE. This change can be tracked by using the volassist snapwait operation, which waits until at least one of the snapshot mirrors changes its state to SNAPDONE. If the attach process fails, the snapshot plex (mirror) is removed and its space is released. Once the attach of the snapshot plex is completed, it continues being updated until it is detached. The backup operation is completed by us- ing the volassist snapshot command on a volume with a SNAPDONE mirror. This operation detaches the finished snapshot, creates a new volume, and attaches the snapshot mirror to it. The state of the snapshot is set to ACTIVE. If the snapshot procedure is interrupted, the snapshot mirror is auto- matically removed when the volume is started. FILES System default settings for volassist attributes. EXIT CODES The volassist utility exits with a nonzero status if the attempted op- eration fails. A nonzero exit code is not a complete indicator of the problems encountered, but rather denotes the first condition that pre- vented further execution of the utility. See volintro(8) for a list of standard exit codes. RELATED INFORMATION Commands: volintro(8), voledit(8), volmake(8), volmend(8), volplex(8), volsd(8), volume(8). delim off volassist(8)