vxibc(1M) VxVM 3.5 vxibc(1M)
1 Jun 2002
NAME [Toc] [Back]
vxibc - perform VERITAS Volume Replicator In-Band Control Messaging
operations
SYNOPSIS [Toc] [Back]
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 [Toc] [Back]
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
- 1 - Formatted: January 24, 2005
vxibc(1M) VxVM 3.5 vxibc(1M)
1 Jun 2002
volume contents to be consistent, such as during the database hotbackup
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 [Toc] [Back]
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
does not persistent through 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
- 2 - Formatted: January 24, 2005
vxibc(1M) VxVM 3.5 vxibc(1M)
1 Jun 2002
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 [Toc] [Back]
-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
- 3 - Formatted: January 24, 2005
vxibc(1M) VxVM 3.5 vxibc(1M)
1 Jun 2002
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 timeout.
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
- 4 - Formatted: January 24, 2005
vxibc(1M) VxVM 3.5 vxibc(1M)
1 Jun 2002
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 [Toc] [Back]
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 [Toc] [Back]
See the VERITAS Volume Replicator Administrator's Guide for examples.
EXIT CODES [Toc] [Back]
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 system errors are returned after adding the
number 64 to them. This makes their exit status unique with respect
to the standard exit codes for VxVM. For example, if the error is
ENOENT, the exit status value is the sum of the error code for ENOENT
and 64. This behavior is specific to vxibc.
- 5 - Formatted: January 24, 2005
vxibc(1M) VxVM 3.5 vxibc(1M)
1 Jun 2002
SEE ALSO [Toc] [Back]
vxintro(1M), vxprint(1M), vxrlink(1M), vxrvg(1M)
VERITAS Volume Replicator Administrator's Guide
- 6 - Formatted: January 24, 2005 [ Back ] |
