8    Advanced Volume Operations

This chapter describes advanced Logical Storage Manager (LSM) system administration using the LSM command line interface. Information is included about how to manipulate subdisks and plexes, as well as information on common LSM administration utilities.

8.1    Commands Summary

Table 8-1 introduces the commands and utilities discussed in this chapter.

Table 8-1: Subdisk and Plex Commands

8.2    Subdisk Operations

LSM volumes are composed of two types of objects, plexes and subdisks. A plex is composed of a single subdisk or a series of subdisks linked together in an address space. A subdisk is a portion of a physical disk and is defined by disk media, offset, and length. Subdisks are low-level building blocks of an LSM configuration. The following sections describe each of the operations that can be performed in relation to subdisks. These subdisk operations are:

• Creating a subdisk

• Removing a subdisk

• Displaying a subdisk

• Associating a subdisk

• Disassociating a subdisk

• Changing a subdisk

• Moving a subdisk

• Splitting a subdisk

• Joining a subdisk

8.2.1    Using volsd to Perform Subdisk Operations

The volsd utility is used to maintain subdisk-plex associations. The volsd utility can associate a subdisk with a plex or disassociate a subdisk from its associated plex, to move the contents of a subdisk to another subdisk, to split one subdisk into two subdisks that occupy the same space as the original, or to join two contiguous subdisks into one.

Note

Some volsd operations can take a considerable amount of time to complete.

For detailed information, refer to the volsd(8) reference page.

8.2.2    Creating Subdisks

The command to create LSM objects is volmake. The steps to create a subdisk include specifying the following:

1. Name of the subdisk

2. Length of the subdisk

3. Starting point (offset) of the subdisk within the disk

4. Disk media name

To create a subdisk, use either of the following commands:

#  volmake sd  name disk, offset, len

or

#  volmake sd  name len= length offset= disk_offset disk= lsm_disk

For example, use either of the following command lines to create a subdisk labeled disk02-01, that starts at the beginning of disk disk02, and has a length of 8000 blocks:

#  volmake sd disk02-01 disk02,0,8000

or

#  volmake sd disk02-01 len=8000 offset=0 disk=disk02

Note

Commands take sizes in blocks. Adding a suffix changes the unit of measure. A k suffix specifies 1024-byte blocks. To preserve (encapsulate) data that exists on the disk, a plex and volume must be created to cover that data.

8.2.3    Removing Subdisks

You can remove subdisks when they are no longer in use or needed. To remove a subdisk, use the following command:

#  voledit rm  subdisk_name

For example, the command line to remove a subdisk labeled disk02-01 looks like this:

#  voledit rm disk02-01

8.2.4    Displaying Subdisks

The volprint utility displays information about LSM objects. To display general information for all subdisks, use the following command:

#  volprint -st

The -s option instructs volprint to get information about subdisks. The -t option prints a single-line output record that depends on the type of object being listed.

To display complete information about a particular subdisk, use the following command:

#  volprint -l  subdisk_name

For example, the command line to obtain all database information on a subdisk labeled disk02-01 looks like this:

#  volprint -l disk02-01

8.2.5    Associating Subdisks

Associating a subdisk with a plex places the amount of disk space defined by the subdisk at a specific offset within the plex. In all cases, the entire area that the subdisk fills must not be occupied by any portion of another subdisk. There are several different ways that subdisks can be associated with plexes, depending on the overall state of the configuration.

If the system administrator has already created all the subdisks needed for a particular plex, subdisks are associated at plex creation by using a command similar to the following:

#  volmake plex home-1 sd=disk02-01,disk03-00,disk03-01

This command creates a plex home-1 and associates subdisks disk02-01, disk03-00, and disk03-01 with the plex home-1 during the plex creation process. Subdisks are associated in order starting at offset 0. Using a command like this one eliminates the need to specify the multiple commands necessary to create the plex and then associate each of the subdisks with that plex. In the example, the subdisks are associated with the plex in the order they are listed (after the sd=); the disk space defined as disk02-01 will be first, the disk space of disk03-00 is second, and disk03-01 is third.

This method of associating subdisks is convenient during the initial configuration. Subdisks can also be associated with a plex that already exists. any subdisks that are already associated with the plex, unless the -l option is specified with the volsd command. The -l option provides a way to associate subdisks at a specific offset within the plex.

The -l option is needed in a case where a system administrator has created a sparse plex for a particular volume, and wants to make this plex complete. To make the plex complete, it is necessary to create a subdisk of exactly the size needed to fill the hole in the sparse plex, and then associate the subdisk with the plex by specifying the offset of the beginning of the hole in the plex. Use the following command to accomplish this task:

#  volsd -l  offset assoc  sparse_plex_name exact_size_subdisk

Note

The subdisk must be exactly the right size because LSM does not allow for the space defined by two subdisks to overlap within a single plex.

8.2.6    Associating Logging Subdisks

Logging subdisks are one-block long subdisks that are defined for and added to a plex that is to become part of a volume using block-change logging. Block-change logging is enabled for a volume when the volume has at least two active plexes that include a logging subdisk. Logging subdisks are ignored as far as the usual plex policies are concerned, and are only used to hold the block-change log (described in Section 13.1.4).

Because block-change logs are one block in length, only a limited number of recent changes can be kept in the log. Older entries are removed from the log as newer I/O changes take place and are added to the log. Because all I/O must follow a log write, if no unused or completed log entries are available for use in the log block, then further I/O is delayed until some of the pending I/O completes and releases log space. This delay could adversely affect system performance.

Note

Only one logging subdisk can be associated with a plex. Because this subdisk is frequently written, care should be taken to position it on a disk that is not heavily used. Placing a logging subdisk on a heavily-used disk can result in severe degradation of system performance.

To add a logging subdisk to a plex, use the following command:

#  volsd aslog  plex subdisk

For example, the command line to associate a subdisk labeled disk02-01 with a plex labeled vol01-02 (which is already associated with volume vol01) looks like this:

#  volsd aslog vol01-02 disk02-01

8.2.7    Disassociating Subdisks

To break an established relationship between a subdisk and the plex to which it belongs, the subdisk is disassociated from the plex. A subdisk is disassociated when the subdisk is to be removed or used in another plex. To disassociate a subdisk, use the following command:

#  volsd dis  subdisk_name

To disassociate a subdisk labeled disk02-01 from the plex with which it is currently associated, use the following command:

#  volsd dis disk02-01

Subdisks can also be removed with the command:

#  volsd -orm dis  subdisk_name

8.2.8    Changing Subdisk Information

The voledit utility changes information related to subdisks. To change information relating to a subdisk use the following command:

#  voledit set  field=value ... subdisk_name ...

For example, the command line to change the comment field of a subdisk labeled disk02-01 looks like this:

#  voledit set comment= "New comment" disk02-01

The following subdisk fields can be changed using voledit:

• The putil [n] fields

• The tutil [n] fields

• The len field (only if the subdisk is disassociated)

Table 8-2 describes these fields.

Table 8-2: The putil and util Fields

Note

Entering data in the putil0 field prevents the subdisk from being used as part of a plex, if it is not already being so used.

8.2.9    Moving Subdisks

Moving a subdisk copies the disk space contents of a subdisk onto another subdisk. If the subdisk being moved is associated with a plex, then the data stored on the original subdisk is copied to the new subdisk, the old subdisk is disassociated from the plex, and the new subdisk is associated with the plex, at the same offset within the plex as the source subdisk. To move a subdisk, use the following command:

#  volsd mv  old_subdisk_name new_subdisk_name

For the subdisk move operation to perform correctly, the following conditions must be met:

• The subdisks involved must be the same size.

• The subdisk being moved must be part of an active plex on an active (ENABLED) volume.

• The new subdisk must not be associated with any other plex.

8.2.10    Splitting Subdisks

Splitting a subdisk divides an existing subdisk into two subdisks. The -s option is required to specify the size of the first of the two subdisks that will be created. To split a subdisk, use the following command:

#  volsd -s  size split  sd newsd newsd2

In this example, sd is the name of the original subdisk, newsd is the name of the first of the two subdisks that will be created, and newsd2 is the name of the second subdisk to be created.

If the existing subdisk is associated with a plex before the split operation, upon completion of the split, both of the resulting subdisks will be associated with the same plex.

8.2.11    Joining Subdisks

Joining a subdisk combines two or more existing subdisks into one subdisk. To join subdisks, the subdisks must be contiguous on the same disk; if the selected subdisks are associated, they must be associated with the same plex, and be contiguous in that plex.

To join a subdisk, use the following command:

#  volsd join  subdisk1 subdisk2 new_subdisk

8.3    Plex Operations

Plexes are logical groupings of subdisks that create an area of disk space independent of any physical disk size. Replication of disk data can be accomplished by defining multiple plexes that will be attached to one volume. The replication provided by multiple plexes prevents data loss in the event of a single-point disk-subsystem failure. Multiple plexes also provide increased data integrity and reliability.

Plex operations include:

• Creating a plex

• Removing a plex

• Associating a plex

• Disassociating a plex

• Listing all plexes

• Displaying plexes

• Changing plex attributes

• Changing plex status

• Moving plexes

• Copying plexes

8.3.1    Using volplex to Perform Plex Operations

The volplex utility performs LSM operations on plex or on volume-and-plex combinations. The first operand is a keyword that determines the specific operation to perform. The remaining operands specify the configuration objects to which the operation is to be applied. The volplex utility can attach a plex to a volume and detach a plex from a volume. A detached plex does not participate in I/O activity to the volume, but remains associated with the volume. The semantics of a detached plex are somewhat different dependent upon usage type, but in the case of the standard usage types, fsgen and gen, a detached plex is reattached when a volume is next started.

Another capability provided by volplex is disassociation of a plex from the volume with which it is associated. When a plex is disassociated, its relationship to the volume is completely broken. At that point, the plex is available for other uses and can be associated with a different volume. This functionality is useful as part of a backup procedure.

Additionally, volplex provides options to copy the contents of the specified volume onto all of the named plexes, moving the contents of one plex onto a new plex, and allows for other usage-type-dependent operations to be added.

For detailed information about how to use volplex, refer to the volplex(8) reference page.

8.3.2    Creating Plexes

Plexes are created by identifying subdisks and associating them to the plex that you want to create. The volmake command creates LSM objects. To create a plex from existing subdisks, use the following command:

#  volmake plex  plex_name sd= subdisk_name, ...

For example, the command line to create a plex labeled vol01-02 using two existing subdisks labeled disk02-01 and disk02-02 looks like this:

#  volmake plex vol01-02 sd=disk02-01,disk02-02

8.3.3    Backup Using a Plex

If a volume is mirrored, backup can be performed on that volume by taking one of the volume's plexes off line for a period of time. This eliminates the need for extra disk space for the purpose of backup only. However, it also eliminates redundancy of the volume for the duration of the time needed for the backup.

Perform a backup of a mirrored volume on an active system as follows:

1. Stop I/O activity and flush any buffers to improve the consistency of the backup. For example, Digital recommends briefly unmounting the UFS volume in order to create a complete and consistent backup.

2. Disassociate one of the volume's plexes (vol-01, for this example):

   #  volplex dis vol-01
   

   This operation should only take a few seconds. It will leave the device /dev/plex/vol-01 available as an image of the volume frozen at the time of the disassociation.

3. At this point, resume I/O activity. For example, if the volume contained UFS, it can be remounted.

4. Create a temporary volume. For example:

   #  volmake -Ufsgen vol vtmp plex=vol-01
   #  volume start vtmp
   

5. Check the temporary volume, if necessary:

   #  fsck -p /dev/rvol/vtmp
   

6. Create a backup using the temporary volume. For example:

   #  dump 0 /dev/rvol/vtmp
   

7. Reattach the plex to the volume in order to regain redundancy of the volume. For example:

   #  volplex dis vol-01
   #  volplex att  volume-name vol-01
   

8.3.4    Associating Plexes

A plex becomes a participating plex for a volume by associating the plex with the volume. To associate a plex with an existing volume, use the following command:

#  volplex att  volume_name plex_name

For example, the command line to associate a plex labeled vol01-02 with volume labeled vol01 looks like this:

#  volplex att vol01 vol01-02

Alternately, if the volume has not been created, a plex (or multiple plexes) can be associated with the volume to be created as part of the volume create command:

#  volmake -U  usetype vol  vol_name plex= plex_name1, plex_name2 ...

For example, the command line to create a mirrored, fsgen-type volume labeled home, and associate two existing plexes labeled home-1 and home-2 to the volume home looks like this:

#  volmake -Ufsgen vol home plex=home-1,home-2

8.3.5    Removing Plexes

When a plex is no longer needed, it can be removed. Examples of operations that require plexes to be removed are:

• Reducing the number of plexes in a volume to increase the length of another plex and its associated volume; the plex and subdisks are removed, then the resulting space can be added to other volumes

• Removing a temporary plex that was created to backup a volume and is no longer required

• Changing the layout of a plex from concatenated to striped, or vice versa

Caution

To save the data on a plex that is to be removed, you need to know the original configuration of that plex. Several parameters from that configuration, such as stripe width and subdisk ordering, are critical to the construction of a new plex which would contain the same data. Before such a plex is removed, its configuration should be recorded.

A plex can be disassociated from a volume and removed with the following command:

#  volplex -o rm dis  plex_name

To disassociate and remove a plex labeled vol01-02 use the following command:

#  volplex -o rm dis vol01-02

This removes the plex vol01-02 and all associated subdisks.

Note

Without the -o rm, the volplex command disassociates the plex and subdisks, but does not remove them. To remove the disassociated plex and subdisks, use the following command:

#  voledit -r rm  plex_name

Because the -r option of voledit removes multiple objects. Exercise caution when using it.

8.3.6    Listing All Plexes

Listing plexes helps identify free plexes that can be used for building volumes. Using the volprint utility with the plex (-p) option lists information about all plexes; the -t option prints a single line of information about the plex. To list free plexes, use the following command:

#  volprint -pt

8.3.7    Displaying Plexes

To display detailed information about all plexes, use the following command:

#  volprint -lp

To display detailed information about a specific plex, use the following command:

#  volprint -l  plex_name

8.3.8    Changing Plex Attributes

The comment field and the putil and tutil fields are used by the utilities after plex creation. The putil fields attributes are maintained after a reboot; the tutil fields are temporary and are not retained after a reboot. Both putil and tutil have three uses and are numbered according to those uses. These fields can be modified as needed. LSM uses the utility fields marked putil0 and tutil0; other products use those marked putil1 and tutil1. Those marked putil2 and tutil2 are user fields. Table 8-2 describes the uses for the putil and tutil fields.

To change plex attributes, use the following command:

#  voledit set  field = value ...  plex_name ...

The following steps demonstrate how you can use the voledit command to modify comment fields:

1. Set the comment field that identifies what the plex (vol01-02) is used for to my_plex.

2. Enter u in tutil2 to indicate that the subdisk is in use.

3. Use the following command to change the user ID to admin in the putil2 field:

#  voledit set comment="my plex" tutil2="u" putil2="admin" \
vol01-02

To prevent a particular plex from being associated with a volume, set the putil0 field to a non-null string as specified in the following command:

#  voledit set putil0="DO-NOT-USE" vol01-02

8.3.9    Changing Plex Status: Detaching and Attaching Plexes

Once a volume has been created and placed on line (ENABLED), LSM provides mechanisms by which plexes can be temporarily disconnected from the volume. This is useful, for example, when the hardware on which a plex resides needs repair or when a volume has been left unstartable and a source plex for the volume revive operation must be chosen manually.

Resolving a disk or system failure includes taking a volume off line and attaching and detaching its plexes. The two commands used to accomplish disk failure resolution are volmend and volplex.

To take a plex OFFLINE so that repair or maintenance can be performed on the physical disk containing that plexes' subdisks, use the following command:

#  volmend off  plex_name ...

If a disk drive suffered a head crash, the system administrator should put all plexes that have associated subdisks represented on the affected drive OFFLINE. For example, if plexes vol01-02 and vol02p1 had subdisks on a drive to be repaired, use the following command:

#  volmend off vol01-02 vol02p1

This command places vol01-02 and vol02-01 in the OFFLINE state, and they remain in that state until explicitly changed.

8.3.9.1    Detaching Plexes

To temporarily detach one plex in a mirrored volume, use the following command:

#  volplex det  plex_name ...

For example, the command line to temporarily detach a plex labeled vol01-02 and place it in maintenance mode looks like this:

#  volplex det vol01-02

This command temporarily detaches the plex, but maintains the association between the plex and its volume; however, the plex will not be used for I/O. A plex detached with the preceding command will be recovered when the system is rebooted. The plex state is set to STALE, so that if a volume start command is run on the appropriate volume (for example, after a system reboot), the plex will be revived and made ACTIVE.

When the plex is ready to return as an active part of its volume, follow this procedure:

1. If the volume is not ENABLED, start it as follows:

   #  volume start vol_name.
   

   If it is unstartable, set one of the plexes to CLEAN as follows:

   #  volmend plex clean  plex_name,
   

   Then start the volume.

2. If the plex does not yet have a kernel state of ENABLED, issue the following command:

   #  volplex att  volume_name plex_name ...
   

   As with returning an OFFLINE plex to ACTIVE, this command starts a revive operation of the plexes stated, and when each revive operation is completed, sets the plex state to ACTIVE.

8.3.9.2    Attaching Plexes

When the disk has been repaired or replaced and is again ready for use, the plexes must be put back on line (plex state set to ACTIVE). The following steps describe putting plexes back on line.

1. If the volume is currently ENABLED, use the following command:

   #  volplex att  volume_name plex_name ...
   

   For example, the command for a plex labeled vol01-02 on a volume labeled vol01 looks like this:

   #  volplex att vol01 vol01-02
   

   This starts a revive operation of the plex vol01-02 and, after the revive operation is completed, sets the plex utility state to ACTIVE.

2. If the volume is not in use (not ENABLED), use the following command:

   #  volmend on  plex_name
   

   For example, the command for a plex labeled vol01-02 looks like this:

   #  volmend on vol01-02
   

   In this case, the state of vol01-02 is set to STALE, so that when the volume is next started, the data on the plex will be revived from the other plex, and incorporated into the volume with its state set to ACTIVE.

If it becomes necessary to manually change the state of a plex, refer to Section 14.9.2. See the volmake(8) and volmend(8) reference pages for more information about these commands.

8.3.10    Moving Plexes

Moving a plex copies the data content from the original plex onto a new plex. In order for a move operation to be successful, the following criteria must be met:

• The old plex must be an active part of an active (ENABLED) volume.

• The new plex should be at least the same size or larger than the old plex.

• The new plex must not be associated with another volume.

The size of the plex has several important implications. If the new plex is smaller, or more sparse, than the original plex, an incomplete copy of the data on the original plex results. If this is the desired action, then the -o force option is required.

If the new plex is longer, or less sparse, than the original plex, then the data that exists on the original plex will be copied onto the new plex. Then, any area that was not on the original plex, but is represented on the new plex, will be filled from other complete plexes associated with the same volume. If the new plex is longer than the volume itself, then the remaining area of the new plex above the size of the volume will not be initialized.

The command to move data from one plex to another is:

#  volplex mv  original_plex new_plex

8.3.11    Copying Plexes

This operation copies the contents of a volume onto a specified plex. The volume to be copied must not be enabled. The plex must not be associated with any other volume.

To copy a plex, use the following command:

#  volplex cp  vol_name new_plex

After the copy operation is completed, new_plex will not be associated with the specified volume vol_name. The plex contains a complete copy of the volume data. The plex that is being copied should be the same size or larger than the volume, otherwise an incomplete copy of the data results. For this same reason, new_plex also should not be sparse.

8.4    Individual Utility Descriptions

The following sections describe LSM utilities that are commonly used to perform system administration and maintenance functions.

8.4.1    Using the voldctl Command

The volume configuration daemon (vold) is the interface between the LSM utilities and the kernel volconfig device driver. The volconfig device is a special device file created by LSM that interacts with vold to make LSM configuration changes.

The voldctl utility is the interface to vold. Some voldctl operations involve modifications to the volboot file, which indicates the locations of root configuration copies.

The voldctl utility is used for the following tasks:

• Performing administrative tasks related to the state of the daemon

• Managing boot information and various aspects of the LSM root configuration initialization

• Manipulating the contents of the volboot file, which contains a list of disks containing root configuration databases

For detailed information about how to use voldctl, refer to the voldctl(8) reference page.

8.4.2    Using voledit to Remove and Modify LSM Objects

The voledit utility has two functions:

1. Allows the system administrator to modify certain records in the LSM configuration databases. Only fields that are not volume usage-type-dependent can be modified.

2. Removes or renames LSM objects.

In general, LSM objects that are associated are not removable. This means that:

• A subdisk that is associated with a plex cannot be removed.

• A plex that is attached to a volume cannot be removed.

Note

Using the recursive suboption (-r) to the removal option of the voledit command removes all objects from the specified object downward. In this way, a plex and its associated subdisks, or a volume and its attached plexes and their associated subdisks, can be removed by a single invocation of this command.

Because the -r option of voledit removes multiple objects, exercise caution when using it.

For detailed information about how to use voledit, refer to the voledit(8) reference page.

8.4.3    Using volmake to Create LSM Objects

The volmake utility is used to add a new volume, plex, or subdisk to the set of objects managed by LSM. The volmake command adds a new record for that object to the LSM database. Records can be created entirely from parameters specified on the command line, or they can be created using a description file.

If operands are specified, then the first operand is a keyword that determines the kind of object to be created, the second operand is the name given to that object, and additional operands specify attributes for the object. If no operands are specified on the command line, then a description file is used to specify what records to create.

A description file is a file that contains plain text describing the objects to be created with volmake. A description file can contain several commands, and can be edited to perform a list of volmake utility operations. You can create a description file of existing LSM objects with the volprint utility, and then later recreate these LSM objects using the volmake utility. The following example shows a sample description file:

#rectyp	#name	#options
sd	3s1-01	dmname=disk03 offset=0 len=20480
sd	4s1-01	dmname=disk04
plex	db-dsk	layout=STRIPE st_width=16k sd=3s1-01,4s1-01
sd	mem1-01	dmname=memdisk01 len=640h
		comment="Hot spot for dbvol"
plex	db-mem	sd=mem1-01:40320
vol	db	use_type=gen plex=db-dsk,db-mem
		read_pol=PREFER pref_name=memdbplx
		comment="Uses mem1 for hot spot in last 5m"

By default, this description file is read from standard input. However, by using the -d option, a file name can be specified. For detailed information about how to use volmake, as well as detailed descriptions and definitions of the object-specific fields specified with volmake, refer to the volmake(8) reference page.

8.4.4    Using the volmend Utility

The volmend utility performs miscellaneous LSM usage-type-specific operations on volumes, plexes, and subdisks. These operations are used to:

• Clear utility fields

• Change the state of a volume or plex

• Take a volume or plex off line

• Place a volume or plex on line

• Perform specialized actions for objects with a particular usage type

Use the volmend utility primarily to escape from a state that was accidentally reached. The offline and online functions are also available with disk-related commands.

For detailed information about how to use volmend, refer to the volmend(8) reference page.

8.4.5    Defaults File for volassist

The volassist command provides a convenient, one-step interface to LSM and is especially useful for basic and commonly used administrative operations. The volassist command automatically finds space for and creates simple volumes or plexes for existing volumes, resizes volumes, and provides online backup of volumes.

The volassist command uses a set of tunable parameters that you can specify in defaults files or on the command line. The tunable parameters default to reasonable values if they are not defined anywhere. The tunable parameters are specified as follows:

• Internal defaults

  The built-in defaults are used when the value for a particular parameter is not specified elsewhere (on the command line or in a defaults file).

• System-wide defaults file

  The system-wide defaults file contains default values that may be altered by the system administrator. These values are used for tunable parameters that are not specified on the command line or in the user's defaults file.

• User defaults file

  The user can create a personal defaults file. If a personal defaults file exists, the values therein are used for tunable parameters that are not specified on the command line. These values override those in the system-wide defaults file.

• Command line

  The values specified on the command line override any values specified internally or in defaults files.

Tunable parameters are specified in the /etc/defaults/volassist file, which you must create. The format of the defaults file is a list of attribute=value pairs separated by new lines. These attribute=value pairs are the same as those specified as options on the command line.

The following is a sample volassist defaults file:

# LSM Vn.n
# volassist defaults file.  Use '#' for comments

 

# layout
layout=concat,noncontig,span

 

# mirroring
nmirror=2
mirror=no

 

# allocation policies
align=4k
alloc=20m

 

# striping
stripewidth=64k

 

# logging
logtype=none

 

# volume usage type
usetype=fsgen

For detailed information about how to use volassist, refer to the volassist(8) reference page.