|
|
Unix Doubt
|
|
vxibc(1M) vxibc(1M) NAME
vxibc - perform Veritas Volume Replicator In-Band Control Messaging operations SYNOPSIS
vxibc [-g diskgroup] [-n | -R receive_timeout] [-f filename] [-l buf_length] receive application_name rvg vxibc [-g diskgroup] [-D deliver_timeout] register application_name rvg vxibc [-g diskgroup] [-R receive_timeout] [-f filename] [-l buf_length] regrecv application_name rvg command [argument ...] vxibc [-g diskgroup] [-D deliver_timeout] [-N | -F freeze_timeout] [-f filename | -m message] regsend application_name rvg [rlink ...] vxibc [-g diskgroup] [-N | -F freeze_timeout] [-f filename | -m message] send application_name rvg [rlink ...] vxibc [-g diskgroup] status rvg vxibc [-g diskgroup] stoprecv application_name rvg vxibc [-g diskgroup] unfreeze application_name rvg vxibc [-g diskgroup] unregister application_name rvg 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 con- tents 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 mes- sage 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 mes- sages 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 applica- tion_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 opera- tion must be started on the Secondary node before performing regsend on the Primary node, Otherwise, there is no companion regis- tered 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 per- formed 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 sto- precv 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 opera- tion 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 mes- sage 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 opera- tions 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 applica- tion on the Secondary host that receives the IBC message. Maximum length of application_name string can be 31 bytes. An appli- cation_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 opera- tion. The exit status of the command is displayed or if the command terminated on receiving a signal, the signal number is dis- played. 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 EIBC_APP_NOT_FROZEN Cannot unfreeze - rlink not frozen for this application EIBC_INVALID_BUFFER Invalid pointer to user buffer EIBC_PRI_FREEZE_IN_PROGRESS IBC primary freeze in progress EIBC_BUNKER Cannot perform this operation on bunker rvg EIBC_INVALID_IOCTL IBC command not valid for old versions of RVG EIBC_CLUSTER_MASTER_ONLY Operation must be executed on master SEE ALSO
vxintro(1M), vxprint(1M), vxrlink(1M), vxrvg(1M) Veritas Volume Replicator Administrator's Guide VxVM 5.0.31.1 24 Mar 2008 vxibc(1M)
