vxibc

NAME

vxibc - perform VERITAS Volume Replicator In-Band Control Messaging operations

SYNOPSIS

DESCRIPTION

The vxibc utility is specific to VERITAS Volume Replicator (VVR) and requires a valid license.

The vxibc command-line utility performs In-Band Control Messaging (IBC) operations. It allows applications to inject user-defined control messages into the update stream of a Replicated Volume Group (RVG). An IBC message is delivered on the Secondary node in causal order with respect to other activity on the data volumes. Before delivery of the message on the Secondary node, any previous update activity is flushed. You have the option of either allowing subsequent updates to be applied immediately to the Secondary data volumes, or of freezing replication until released by the application.

IBC messages are guaranteed to be delivered at least once and may be delivered multiple times if an error such as network outage or machine crash occurs during the delivery. An application must tolerate multiple delivery of the same IBC message including handling the freeze-unfreeze cycle.

Typically, IBC is used to checkpoint application-level consistency within an RVG over and above the update-level consistency maintained by VVR. An application running on the Primary node can insert a freeze IBC at a point at which the application considers its raw volume contents to be consistent, such as during the database hot-backup mode. A companion application running on the Secondary node is assured that the RLINK is application-level consistent when it receives the IBC message and will remain so until it unfreezes the RLINK. The application on the Secondary node may perform a backup of the data volumes, take a snapshot, or carry out any similar function during this time period.

Each vxibc command keyword specifies an operation that can be performed. Each operation can be applied to only one disk group at a time. The rlink and rvg operands are used to determine a default local disk group according to the standard disk group selection rules described in vxintro(1M). If required, a local disk group can be specified using the -g diskgroup option.

KEYWORDS

receive

Receives the IBC message sent from the Primary RVG on the Secondary node. The application_name must be previously registered for the Secondary RVG, rvg. Secondary replication is frozen at the point in time in the RLINK's update stream at which the IBC message was inserted at the Primary RVG. Secondary replication remains frozen until an unfreeze operation is performed, or until the expiry of the freeze_timeout that was specified when the IBC message was sent. The default behavior for the receive operation is to block until an IBC message is received. The -n option makes the receive operation non-blocking, and returns if there is no message to receive. If the operation succeeds, the received message is displayed. An unsuccessful exit code indicates that messages were dropped and the drop count is displayed to the standard error output.

register

Registers the application name, application_name, for the RVG, rvg. Before being able to perform IBC operations on an RVG, you must register an application name for it. The sender and the receivers of the IBC message must register the same application_name. Multiple application names (up to a maximum of 32) can be registered for an RVG. Registration is not persistent across node crashes. Applications on rebooted nodes must be re-registered (see the VERITAS Volume Replicator Administrator's Guide).

regrecv

As a single step, this operation registers an application, receives an IBC message, runs the command with the provided arguments passed as command-line argument to the regrecv operation, unfreezes the Secondary RVG, rvg, and unregisters the application.

regsend

As a single step, this operation registers an application, sends an IBC message, and unregisters the application. regrecv operation must be started on the Secondary node before performing regsend on the Primary node, Otherwise, there is no companion registered application name on the Secondary node, and the IBC message is discarded.

send

Sends the IBC message from a Primary RVG, rvg, for which the application name, application_name, has been previously registered. The IBC message is inserted into the update stream of the specified rlinks. If no rlink is specified, the message is sent to all RLINKs currently attached to the Primary RVG. Secondary replication is frozen at the point in time in the rlink's update stream at which the IBC message is inserted at the Primary RVG. Secondary replication remains frozen until an unfreeze operation is performed or the specified freeze_timeout expires.

status

Displays the currently registered application names for the RVG, rvg.

stoprecv

Terminates a receive or regrecv operation started by another process. Normally a receive or a regrecv operation terminates when the IBC message is received from the Primary node or if no message is received within the receive timeout period. Use the stoprecv operation to prematurely terminate the receive or regrecv operation before the IBC message arrives on the Secondary node.

unfreeze

Unfreezes the Secondary rvg. This operation must be performed after receiving the IBC message using the receive operation. The unfreeze operation permits replication to continue by allowing updates that were performed on data volumes after the send operation was executed on the Primary RLINK to be applied to the Secondary RVG, rvg.

unregister

Unregisters the application name, application_name, for the RVG, rvg. The application name must have been previously registered for the RVG. No further send operations against the application name are possible after unregistering on the Primary RVG. IBC messages already introduced into the update stream before unregistering are delivered on the Secondary RVG. Unregistering on the Secondary causes the receive and the unfreeze operations for the application name to fail and any IBC messages arriving for the application name to be discarded.

OPTIONS

-D deliver_timeout

Specifies the time-out value in seconds for delivery of an IBC message after it has arrived at the Secondary RVG. When the time-out expires, the Secondary RVG discards the IBC message and continues replication. The default value for deliver_timeout is 600 (10 minutes). A deliver_timeout value of 0 means infinite time-out. The deliver_timeout value has no meaning for a Secondary RVG and is ignored.

-f filename

When used with the send or the regsend operation, the message is read from the specified file. When used with the receive or the regrecv operation, the received message is saved to the specified file. The maximum size of the file is 128 kilobytes (KB). If a file larger than 128KB is specified for the send or the regsend operation, only 128KB is read to compile the message to be sent.

-F freeze_timeout

Specifies the time-out value in seconds between delivery of an IBC message on the Secondary node and execution of an unfreeze operation against the Secondary RVG. When the time-out expires, replication continues at the Secondary RVG. The default value for freeze_timeout is 600 (10 minutes). A freeze_timeout value of 0 means infinite time-out. The -F and the -N options cannot be used together.

-g diskgroup

Specifies the disk group containing the RVG on which the IBC operation is to be performed.

-l buf_length

Specifies the maximum length in bytes of the IBC message that the user is willing to receive. If the length of the received message is greater than buf_length, then the message is truncated to buf_length bytes. Maximum value for the buf_length argument can be 131072 (128KB).

-m message

Specifies a message string to be sent with the IBC message from the Primary node and received by the application performing the receive or the regrecv operation on the Secondary RVG, rvg. If the send or the regsend operation is executed without this option, a blank message is sent to the Secondary RVG. If message consists of more than one word, it must be enclosed between quote characters. The format of the message is user-defined and can possibly be used by the application performing IBC operations to exchange values or coordinate what tasks are to be performed. To send a large message that cannot be accommodated on the command line, use the -f option instead.

-n

Indicates that the operation is non-blocking. This option is used with the receive operation. This option is invalid for regrecv operation. The default behavior is to block when receiving an IBC message. The -n and the -R options cannot be used together.

-N

Specifies that replication is not to be frozen when the IBC message arrives at the Secondary RVG. This option is used with the send or regsend operations. The -N and the -F options cannot be used together.

-R receive_timeout

Specifies the time-out value in seconds to block waiting for an IBC message when performing the receive or regrecv operations. The default value for receive_timeout is 600 (10 minutes). A receive_timeout value of 0 means infinite time-out. The -R and the -n options cannot be used together.

ARGUMENTS

application_name

Unique identifying string that is used to match the application on the Primary host that sends the IBC message with the application on the Secondary host that receives the IBC message. Maximum length of application_name string can be 31 bytes. An application_name longer than 31 bytes is silently truncated to 31 bytes.

command argument ...

A command along with its arguments that are executed when the IBC message is received on the Secondary node by the regrecv operation. The exit status of the command is displayed or if the command terminated on receiving a signal, the signal number is displayed.

rlink

Name of the RLINK on which the operation is to be performed.

rvg

Name of the RVG on which the operation is to be performed.

EXAMPLES

See the VERITAS Volume Replicator Administrator's Guide for examples.

EXIT CODES

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

See vxintro(1M) for a list of standard exit codes for VERITAS Volume Manager (VxVM). Other IBC-specific errors may be returned with values greater than or equal to 64. These are defined in vxvm/volibc.h:

EIBC_DCM_ACTIVE

IBCs invalid while DCM is active

EIBC_NOMEM

Kernel out of memory or too many appslications

EIBC_DUP_APPLICATION

Application already registered

EIBC_NO_APPLICATION

Application not registered

EIBC_RCV_PENDING

Receive request pending

EIBC_IBC_PENDING

IBC deliver or unfreeze pending

EIBC_MSG_LENGTH

IBC message too long

EIBC_NO_RLINK

No rlink or specified rlink does not exist

EIBC_NO_IBC

Receive timed out before IBC arrived

EIBC_PRIMARY

Cannot perform operation on primary

EIBC_SECONDARY

Cannot perform operation on secondary

EIBC_NO_RECEIVE

Cannot unfreeze IBC until received

EIBC_NOT_FROZEN

Cannot unfreeze - not frozen

SEE ALSO

vxintro (1M), vxprint (1M), vxrlink (1M), vxrvg (1M)

VERITAS Volume Replicator Administrator's Guide