vxedit(1M)

NAME

vxedit — create, remove, and modify Volume Manager records

SYNOPSIS

vxedit [-dfGpPrsvV ] [-e pattern] [-g diskgroup] cc /search/replace/ [gp] [name...]

vxedit [-dpPsvV ] [-g diskgroup] rename oldname newname

vxedit [-dfGpPrsvV ] [-g diskgroup] rm name...

vxedit [-dfGpPrsvV ] [-e pattern] [-g diskgroup] set attribute=value... [name...]

DESCRIPTION

The vxedit utility sets and changes attributes for Volume Manager configuration records that do not depend upon volume usage types. See vxvol(1M) for operations that can set attributes that are dependent upon usage types. In particular, setting the length and logging type for a volume requires use of the vxvol set operation.

Each invocation can be applied to only one disk group at a time, due to internal implementation constraints. Any name or oldname operands will be used as record names to determine a default disk group, according to the standard disk group selection rules described in vxintro(1M). If no name or oldname operands are given, then the disk group defaults to rootdg. A specific disk group can be forced with -g diskgroup.

Note: Some Volume Manager usage messages, manual pages, and command output contain terms and descriptions related to the VERITAS Storage Replicator for Volume Manager (SRVM). SRVM is not supported in this release, so you should ignore options and fields that refer to RLINK, RVG, and DCM.

KEYWORDS

cc

Change a comment using a search-replacement specification similar to that used by sed in RVG, RLINK, volume, plex, subdisk, disk media, or disk group records within the selected disk group. The records to be changed are those that match the pattern specified with -e pattern option and those specified by the name operands. See vxintro(1M) for a description of Volume Manager search patterns. If no search pattern is specified with -e, and no name operands are given, then the change is made to all records whose comment field matches the search regular expression.

The search string is a regular expression, in the form accepted by the function regcomp(3C). This regular expression is used to determine which substring of the comment field is to be changed. The replace string represents the new string to use as a replacement for the matched part of the comment.

An ampersand (&) in the replace string is replaced by the substring of the comment matched by the regular expression. An occurrence of \\ in the replace string, where n is a single digit between 1 and 9, will be replaced by the substring matched by a parenthetical section of the regular expression; the regular expression is followed by $n.

The / character following the replace string is optional. If the / is given, then it can be followed by the letters g or p, or both. If a g is given, then all matches in a comment are replaced, rather than just the first match. If the letter p is given, then the resulting comment strings are written to the standard output, immediately preceded (on the same line) by the name of the record.

If the -r option is given, the operation is applied recursively to records associated with the selected records (to plexes and subdisks for selected volume records, and to subdisks for selected plex records). Recursion (when selected) applies regardless of the -p, and -s options.

Each record to be changed is changed only once, even if the record could be matched several times through combinations of name arguments, search patterns, and the -r option.

For example, the following command changes all subdisk comments that begin with ``Henry'' and a second word beginning with an uppercase letter to begin with ``Frank'' and the same second word:

vxedit -s cc '/^Henry ([A-Z])$1/Frank \\1/p' 

This command also lists the resulting comment fields.

rename

Change the name of an RVG, RLINK, volume, plex, subdisk, or disk media record from oldname to newname. A record cannot be renamed if the tutil0 field is set, which indicates that an operation is in progress that involves the record.

rm

Remove RVG, RLINK, volume, plex, or subdisk records from the selected disk group. Disk media records can be removed with vxdg rmdisk. Disk access records can be removed with vxdisk rm.

Removing a subdisk requires that the subdisk be dissociated. Removing a plex requires that the plex be dissociated and that it have no associated subdisks. Removing a volume requires that it have no associated plexes. Removing an RVG requires that it have no associated RLINKs or volumes. The -r option can be specified to recursively remove a volume and all plex and subdisk records associated with it, or to remove an RVG and all volume, RLINK, plex, and sub disk records associated with it, or to remove a plex and all subdisk records associated with it. If the -r options is provided, subvolumes are also removed. Even when removing with -r, a named plex or subdisk cannot be associated with a volume or plex, respectively.

The -f option is required to remove an enabled volume. A volume cannot be removed, even with -f, if the corresponding volume block or raw device, or if any of the volume's plex devices, is open or mounted. Likewise, a plex cannot be removed if the corresponding plex device is open.

set

Set a field within an RVG, RLINK, volume, plex, subdisk, disk media, or disk group record in the selected disk group. The records to be changed are those that match the pattern specified with the -e pattern option and those specified by the name operands.

The attribute names specify the field to set within the selected records. More than one attribute can be specified in a single invocation. The operands that indicate attribute settings end at the first operand that does not contain an equal sign. An operand of -- can be used to separate the attribute list from record names, even if the first record name contains an equal sign.

If the -r option is given, the operation is applied recursively to records associated with the selected records (to RLINKs, volumes, plexes, subdisks, and subvolumes for selected RVG records, to plexes, subdisks, and subvolumes for selected volume records, and to subdisks and subvolumes for selected plex records). Recursion applies regardless of whether the -p and -s options are specified.

Attribute Values for All Record Types

comment or c: Set the comment string for the selected records to the given value. The comment string cannot be longer than 40 characters and cannot contain a newline character.
tutil0, tutil1, tutil2: Set one of the non-persistent (temporary) utility fields in the record.

Attribute Values for RVG Records

primary: A boolean field. If true, then this RVG is considered the primary RVG and writes to this RVG will be replicated to any RLINK with which it is associated. If false (default), then this is a secondary RVG which receives writes from the primary RVG.
user: Set the user that owns an RVG record to the user given as the attribute value. The attribute value can be either a login name from the /etc/passwd database, or a numeric user ID.
group: Set the group that owns an RVG record to the group given as the attribute value. The attribute value can be either a group name from the group database, or a numeric group ID.
mode: Set the access permissions for the RVG to the permission mode given in the attribute value. The attribute value can be a symbolic permission mode or an octal mode. The format is compatible with permission modes as used by the chmod utility (see chmod(1)).

Attribute Values for RLINK Records

synchronous

A field that indicates whether the RLINK should operate in synchronous or asynchronous mode. In synchronous mode, a write request to a replicated volume does not complete until the data has been recorded on the SRL and reached the secondary node. In asynchronous mode, a write request completes as soon as the data is recorded on the SRL. The field may have one of three values:

off: mode is asynchronous
override: mode is synchronous, but will automatically switch to asynchronous if the RLINK becomes inactive due to a disconnection or administrative action
fail: mode is synchronous. If synchronous=fail is set and an administrator detaches the Primary RLINK, writes to the RVG are not failed. However, if an RLINK becomes inactive for any other reason, including an administrative detach of the Secondary RLINK, subsequent write requests are failed with an EIO error.

local_host

Set the name of the local host. Only needs to be set if a private network is used.

remote_host

Set the name of the remote host.

remote_dg

Set the name of the remote disk group.

remote_rlink

Set the name of the remote RLINK.

timeout

Set the connection timeout value. This is the number of milliseconds to wait before connections to remote nodes should timeout. It defaults to some reasonable non-zero value, but can be tailored to the local environment for improved performance.

packet_size

Set the packet_size value. This is the number of bytes in a packet that is sent to a secondary RLINK. It defaults to some reasonable non-zero value, but can be tailored to the local environment for improved performance.

latencyprot

A field that indicates whether latency protection is enabled for the RLINK. Latency protection prevents an RLINK from having more than a preset number of outstanding requests. All requests which have not been written to the remote data volume are counted as outstanding. If latency protection is enabled, then when the number of outstanding requests reaches latency_high_mark, throttling is enabled. This causes all new write requests to stall until throttling is disabled. Throttling is not disabled until the number of outstanding requests is reduced to latency_low_mark. The field may have one of three values:

off: latency protection is disabled
override: latency protection is enabled, but will automatically be disabled if the RLINK becomes inactive due to a disconnection or administrative action
fail: latency protection is enabled. If the RLINK becomes inactive for any reason, and the latency_high_mark is reached, subsequent write requests are failed with an EIO error.

srlprot

A field that indicates whether log protection is enabled for the RLINK. Log protection prevents an RLINK from overflowing the SRL, which causes it to become stale. If the RLINK has log protection enabled, and the next write request would cause the RLINK to overflow the SRL, then throttling is enabled. This causes all new write requests to stall until throttling is disabled. Throttling is not disabled until a predetermined amount of space is available on the SRL. The field may have one of four values:

off

log protection is disabled

override

log protection is enabled, but will automatically be disabled if the RLINK becomes inactive due to a disconnection or administrative action

fail

log protection is enabled. If the RLINK becomes inactive for any reason, and log overflow is imminent, subsequent write requests are failed with an EIO error.

dcm

log protection is enabled. If an RLINK begins to overflow the SRL the DCM is used to record what regions have changed on the data volumes. When the RLINK connects again the vxrvg command can be used to resynchronize the images.

Note: Using DCM to resynchronize an image makes the image inconsistent until the resynchronization completes.

latency_high_mark

Maximum number of outstanding requests when latency protection is enabled.

latency_low_mark

After throttling is enabled, the number of outstanding requests must drop to this before it is disabled.

Attribute Values for Volume Records

fstype

If a volume contains a file system, fstype can determine the file system type. Under most circumstances, if a file system type is not specified for a volume, the Volume Manager determines the usage type by running the fstyp utility (see fstyp(1M)). However, it is preferable to set fstype to avoid problems when the fstyp utility returns ambiguous results.

group

Set the group that owns a volume record to the group specified as the attribute value. The attribute value can be either a group name from the group database, or a numeric group ID.

mode

Set the access permissions for the volume to the permission mode specified in the attribute value. The attribute value can be a symbolic permission mode or an octal mode. The format is compatible with permission modes as used by the chmod utility (see chmod(1)).

primary_datavol

A name field. This field is only used with secondary replicated volumes. The value indicates the name of the primary replicated volume to which this data volume corresponds.

user

Set the user that owns a volume record to the user specified as the attribute value. The attribute value can be either a login name from the /etc/passwd database, or a numeric user ID.

writeback

Set (on) or clear (off) a volume policy that affects recovery after read failures on a mirrored volume. If the writeback flag is set (which is normally the default), then a read failure for a plex will cause data to be read from an alternate plex and then written back to the plex that got the read failure. This will usually fix the error. Only if the writeback fails will the plex be detached for having an unrecoverable I/O failure.

If this flag is clear, then data from an alternate plex will be read to satisfy the volume read operation, but the failing plex will be detached with no action taken to try to fix the problem.

There is seldom (if ever) a reason to turn off this feature.

writecopy

Set (on) or clear (off) a volume policy that affects consistency of data written to a volume when dirty region logging is in effect on the volume. When the operating system hands off a write request to the volume driver, the operating system may continue to change the memory that is being written to disk. The Volume Manager cannot detect that the memory is changing, so it can inadvertently leave plexes with inconsistent contents. This is not normally a problem, because the operating system ensures that any such modified memory is rewritten to the volume before the volume is closed, such as by a clean system shutdown. However, if the system crashes, plexes may be inconsistent. Since the dirty region logging feature prevents recovery of the entire volume, it may not ensure that plexes are entirely consistent.

Setting the writecopy flag often causes the Volume Manager to copy the data for a write request to a new section of memory before writing it to disk. Because the write is done from the copied memory, it can't change, so the data written to each plex is guaranteed to be the same. Default is writecopy off.

Attribute Values for Sub-Disk Records

failing: Set (on) or clear (off) the disk failing flag. If the failing flag is set for a disk, then the disk space is not used as free space or used by the hot-relocation facility.
len: Set the length of the subdisk to the given length. The attribute value is a standard Volume Manager length number (see vxintro(1M)). The length of a subdisk can be changed only if the subdisk is dissociated. The length of a subdisk cannot be increased to the point where it would extend past the end of the disk, or to where it would overlap a reserved disk region or another subdisk.
orig_dmname: Set the original disk media name for the selected subdisk record to the given value. The field can not be longer than 31 characters. When a subdisk is hot-relocated, the original disk media name where it used to reside will be stored in the subdisk record. A user can manually set or clear this field using vxedit.
orig_dmoffset: Set the original offset for the selected subdisk record to the given value. This field is a standard Volume Manager offset value. When a subdisk is hot-relocated, the original offset within the disk where it used to reside will be stored in the subdisk record. A user can manually set or clear this field using vxedit.

Special Attribute Values for Disk Media Records

nohotuse: Set (on) or clear (off) the disk nohotuse flag. If the nohotuse flag is set for a disk, then that disk is excluded from use by the hot-relocation facility.
reserve: Set (on) or clear (off) the disk reservation flag. If the reserve flag is set for a disk, then vxassist will not allocate a subdisk on that disk unless the disk is specified on the vxassist command line.
spare: Set (on) or clear (off) the disk spare flag. If the spare flag is set for a disk, then that disk is designated for use by the hot-relocation facility. A DM record with the spare flag set will be used only for hot-relocation. vxassist will not allocate a subdisk on that disk unless forced to by command line arguments.

Attribute Values for Disk Group Records

diskdetpolicy: Sets a disk group detach policy. These policies determine the way the Volume Manager detaches unusable disks in a shared disk group. The diskdetpolicy attribute is ignored for private disk groups.

global: For a shared disk group, if any node in the cluster reports a disk failure, the detach occurs in the entire cluster.
local: If a disk fails, the failure is confined to the node that detected the failure. An attempt is made to communicate with all nodes in the cluster to ascertain the failed disk's usability. If all nodes report a problem with the failed disk, the disk is detached throughout the cluster. local is the default policy.

OPTIONS

-d, -G, -p, -P, -s, -v, -V

Select only disk media, disk group, plex, RLINK, subdisk, volume, or RVG records, respectively. If more than one of these options are specified, records of any of the indicated types may be selected.

-e pattern

Use a Volume Manager configuration search expression to select records from the selected disk group configuration. Search patterns are limited to a selection of volume, plex, and subdisk records.

Note: This option is not currently supported for RVG and RLINK records.

-f

Force an operation that the Volume Manager considers potentially dangerous or is not a normal operation for the command. This enables a limited set of operations that would otherwise be disallowed. Some operations may be disallowed even with this flag. The vxedit operations that are allowed with this flag are changing a non-empty tutil0 or putil0 field, and removing enabled volumes.

-g diskgroup

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 name and oldname operands.

-r

Operate recursively on records associated with the selected records. For selected volume records, this affects associated plex, subdisk, and subvolumes records. For selected plex records, this affects associated subdisk and subvolume records.

EXIT CODES

vxedit exits with a non-zero status if the operation fails. A non-zero exit code is not a complete indicator of the problems encountered, but rather denotes the first condition that prevented further execution of the utility.

See vxintro(1M) for a list of standard exit codes.