vxedit

NAME

vxedit - create, remove, and modify VERITAS Volume Manager records

SYNOPSIS

DESCRIPTION

The vxedit utility sets and changes attributes for VERITAS Volume Manager (VxVM) 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. 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 the default disk group unless a disk group has been specified with the -g diskgroup option. If this option is not specified, the default disk group is determined using the rules given in the vxdg(1M) manual page.

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 VERITAS 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). The regular expression in the search string 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 \n 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:

This command also lists the resulting comment fields.

rename

Change the name of a volume, plex, subdisk, disk media, data change object (DCO), or snap object 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 is open or mounted.

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 or IP address 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.

protocol

Set the communication protocol used between the hosts: UDP (default) or TCP corresponding to UDP/IP or TCP/IP respectively.

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 SRL protection is enabled for the RLINK. SRL protection prevents an RLINK from overflowing the SRL, which causes the RLINK to disconnect. If the RLINK has SRL 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 exception to this is when the autodcm mode is set, in which case, DCM protection is enabled as soon as the SRL overflows and incoming write requests are not stalled. The field may have one of five values:

off

SRL protection is disabled

override

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

fail

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

autodcm

SRL protection is enabled. This is the default option for srlprot. If an RLINK begins to overflow the SRL, DCM protection is activated.

dcm

SRL protection is enabled. This differs from the "autodcm" protection in that the DCM protection is activated only when the RLINKs disconnect. When the RLINKs are connected, incoming writes are throttled as described above.

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.

bandwidth_limit

The maximum network bandwidth (in bits per second) that VVR can use at any instant for replication on the RLINK. The value may be qualified by the suffixes kbps or k for kilobits per second, mbps or m for megabits per second, and gbps or g for gigabits per second. The default value none removes the limit. The minimum allowed value is 56kbps.

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, VxVM 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.

specify_writecopy

If set to off, the writecopy stabilization policy for a volume is determined by the value of the writecopy flag, which may be set or cleared by VxVM.

If set to on, you are responsible for setting or clearing the writecopy policy flag.

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 (DRL) or RAID-5 logging is in effect on the volume.

Setting the writecopy flag to on causes VxVM to copy the data for a write request to a new section of memory before writing it to disk. This guarantees that the same data is written to each plex in a mirrored volume, and that data and parity are written consistently to a RAID-5 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. VxVM 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.

As DRL and RAID-5 logging prevent the need for the entire volume to be recovered, writecopy must be set to on to ensure the consistency of a mirrored (with DRL enabled) volume's plexes or of a RAID-5 volume.

ATTRIBUTE VALUES FOR PLEX RECORDS

dco_plex_rid

Set in a snapshot plex to the record ID (RID) of one of the plexes that is attached to a DCO volume.

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 VERITAS 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 offset value in VxVM. 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

dgfailpolicy

Set the disk group failure policy for the case that the master node loses connectivity to the configuration and log copies within a shared disk group. This attribute is ignored for private disk groups, and requires that the disk group version is 120 or greater.

dgdisable

The master node disables the disk group for all user or kernel-initiated transactions. First write and final close fail.

This is the default policy.

leave

The master node panics instead of disabling the disk group if a log update fails for a user or kernel-initiated transaction (including first write or final close). If the failure to access the log copies is global, all nodes panic in turn as they become the master node.

diskdetpolicy

Set the disk group detach policy, which determines the way that unusable disks are detached in a shared disk group. This 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. An I/O error results if the disk was in the final active plex of a volume.

This is the default policy.

local

If a disk fails for a single node only, the I/O failure is confined to that node. If all nodes report a problem with the failed disk, the disk is detached throughout the cluster. An I/O error results if the disk was in the final active plex of a volume.

The dgfailpolicy and diskdetpolicy attributes may also be set on a shared disk group by using the vxdg set command.

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 VERITAS 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.

-f

Force an operation that VxVM 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. If this option is not specified, the default disk group is determined using the rules given in the vxdg(1M) manual page.

-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.

SEE ALSO

chmod(1), sed(1), fstyp(1M), vxdg (1M), vxdisk (1M), vxedit (1M), vxintro (1M), vxmake (1M), vxmend (1M), vxvol (1M), regcomp(3C)