unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (HP-UX-11.11)
Page:
Section:
Apropos / Subsearch:
optional field



 vxibc(1M)			  VxVM 3.5			   vxibc(1M)
				 1 Jun 2002



 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



				    - 1 -	  Formatted:  August 2, 2006






 vxibc(1M)			  VxVM 3.5			   vxibc(1M)
				 1 Jun 2002



      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
		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:  August 2, 2006






 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
      -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:  August 2, 2006






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



				    - 4 -	  Formatted:  August 2, 2006






 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
      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 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:  August 2, 2006






 vxibc(1M)			  VxVM 3.5			   vxibc(1M)
				 1 Jun 2002



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

      VERITAS Volume Replicator Administrator's Guide


















































				    - 6 -	  Formatted:  August 2, 2006