test veritas logo


vxedit(1M)

NAME

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

SYNOPSIS

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

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

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

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

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.

Note: Master and Slave words are going to be deprecated in upcoming releases. We will refer to them using Primary and Secondary words respectively.

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(3). 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:

vxedit -s cc ’/^Henry ([A-Z])$1/Frank \1/p’
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.
Note: RVG and RLINK records cannot be renamed.
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.
nports
  Set the number of TCP/UDP socket connections. By default 16 socket connections are created.
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. For the bunker RLINK, the communication protocol can also be set to STORAGE. The STORAGE protocol can be used when Secondary diskgroup is imported on Primary host.
Note: When the protocol for the RLINK is changed, the RLINK is momentarily disconnected. There is no need to resynchronize when the RLINK is reconnected.
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.
Note: When DCM protection is activated, the DCMs are used to record the regions that change on the data volumes. The vxrvg command can be used to resynchronize the images when the RLINKs are connected. It should be noted that 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.
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.
bunker_target
  A flag that indicates that this is the RLINK from the Secondary to the bunker node.
If you have upgraded from a previous release and have an existing bunker in the configuration with the bunker_target flag not set on the RLINK from the Secondary to the bunker node, you must run the following command on the Secondary to set the bunker_target flag:

vxedit -g dg set bunker_target=on RLINK_from_secondary_to_bunker
compression
  A field that indicates whether compression is enabled or disabled. This attribute may have one of following values: on or off. To set the compression attribute, use the following command.

vxedit [-g diskgroup] set compression=on|off RLINK_name
iotimeout
  This attribute enables adaptive sync feature. This value is accepted in microseconds. If remote site doesn’t acknowledge network IO sent within this time interval, early application ack will be given and IO will be treated as asynchronous.
threshold
  Adaptive sync attribute. This value denotes percentage threshold of timed out IOs to switch replica into asynchronous mode.
interval
  Adaptive sync attribute. This value is accepted in seconds. This is a time interval used to periodically check timed out IOs and if threshold is reached or not.
switch_timeout
  Adaptive sync attribute. This value is accepted in seconds. This is a minimum time to wait before making replica switch.
threshold_monitor
  Adaptive sync attribute. Alerts of potential service deterioration will be generated when this much percentage threshold is reached.
async_bk_threshold
  Adaptive sync attribute. Alert will be given if replica runs in asynchronous mode for this much time(seconds)
autoswitch
  Adaptive sync attribute. This attribute will denote what action to take when latency threshold is reached. Value can on or off. When attribute is set to off no latency protection will be given. Replication mode will switch only when attribute is set to on.

    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 consistenly 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 loggng prevent the need for recovering the entire volume, 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. An exception is noted below.
If using Oracle and the Veritas Extension for Oracle Disk Manager (ODM) interface, writecopy may be unnecessary. Oracle does not change memory once a write is sent through ODM. If Oracle is the only application writing to a volume, and if Oracle I/O is sent to VxFS via ODM, writecopy can be turned off on the underlying VxVM volume to increase performance. For information on enabling ODM, see the Veritas InfoScaleā„¢ Storage and Availability Management for Oracle Databases guide.
Starting from Storage Foundation 5.0MP3, when VxFS receives Oracle I/O through the Veritas Extension for Oracle Disk Manager, VxFS flags the write as ODM IO and passes it to VxVM. VxVM does not perform a memory copy on ODM I/O, but does perform a memory copy on non-ODM I/O. Starting from 5.0MP3, there is no reason to manually turn off writecopy when using ODM; VxFS and VxVM coordinate to do so automatically where appropriate.
Note: If specify_writecopy is set to on, you are responsible for setting or clearing the writecopy policy flag. If specify_writecopy is set to off, VxVM sets the writecopy policy flag based on the volume type.

    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.
Note: This field must only be set for one snapshot plex in a volume. Serious errors may occur during snapshot or snapback operations if this field is set to the RID of a plex that is not in the correct DCO volume. No problems occur if the field refers to a non-existent object.

    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.
VxVM may create a DCO on a disk regardless of the reserve setting.
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 Primary 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 Primary 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 Primary 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 Primary node.
requestleave
  The Primary node exits cleanly from the cluster rather than forcing a panic.
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.
Note: The name of a shared disk group must be specified twice; once as the argument to the -g option, and again as the name argument that specifies the record to be edited as shown in this example:

vxedit -g shareddg set diskdetpolicy=local shareddg

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.
Note: This option is not currently supported for RVG and RLINK 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), Storage Foundation: Storage and Availability Management for Oracle Databases


VxVM 7.3.1 vxedit(1M)