vxtask(1M)																vxtask(1M)

NAME

       vxtask - list and administer Veritas Volume Manager tasks

SYNOPSIS

       vxtask abort taskid

       vxtask [-ahlpqr ] [-g dg_name [-g dg_name...]]  [[-G dg_name] -v volume [-v volume...]]	[-i taskid] list [taskid...]

       vxtask pause taskid

       vxtask resume taskid

       vxtask [-i taskid] set name=value taskid [-c count] [-t time] [-w wait_interval] [-ln ] monitor [taskid[taskid...]]

DESCRIPTION

       The  vxtask utility performs basic administrative operations on Veritas Volume Manager (VxVM) tasks that are running on the system.  Opera-
       tions include listing tasks (subject to filtering), modifying the state of a task (aborting, pausing, resuming), and modifying the rate	of
       progress of a task.

       Veritas	Volume Manager tasks represent long-term operations in progress on the system. Every task provides the time the operation started,
       the size and progress of the operation, and the operation's state and rate of progress (throttle). You can change the state of a task, giv-
       ing  coarse-grained control over an operation's progress. For those operations that support throttling, you can change the rate of progress
       of a task, giving more fine-grained control over the task.

       The majority of tasks represent I/O being performed to objects.	Operations such as read-writeback recovery for	mirrored  volumes,  parity
       recalculation for RAID-5 volumes, volume relayouts, and so forth, all involve moderate to large amounts of I/O.	Tasks that represent oper-
       ations that perform I/O directly are referred to as basic tasks. The task progress information for basic tasks consists of the starting and
       ending block of the I/O to be performed and the offset to which the I/O has currently completed.

       Some  operations, such as vxrecover and starting RAID-5 volumes, may require multiple tasks to complete the operation. vxrecover may deter-
       mine that many recoveries are required, some that must be performed serially. Starting a RAID-5 volume requires that its log  (if  any)	be
       replayed  and cleared, its parity be recalculated (if necessary), any stale subdisks be resynchronized (if needed), and that these tasks be
       performed serially. In these and similar cases, an overall task is created to keep track of the underlying basic tasks being performed, and
       these  are known as parent tasks. The progress information for parent tasks are the total number of subtasks required to complete the over-
       all operation; the number of subtasks completed; and the number of subtasks currently running.

       Every task is given a unique task identifier. This is a numeric identifier for the task that can be specified  to  the  vxtask  utility	to
       specifically identify a single task.

       Tasks also contain the following information:

       task tag  A  task's tag is a string that you can specify to make administration easier. It is usually set by the command that initiates the
		 task. For most utilities, the -t tasktag option allows a tag to be specified as a sequence of up to 16 alphanumeric characters.

       task type The task's type describes the specific operation that is being performed. For example, attaching a plex to a volume results in an
		 atomic copy loop, which is represented by an ATOMIC_COPY task.

       description
		 Describes  the  utility  operation on whose behalf the I/O is being performed. For example, both a volume start and a plex attach
		 can result in an atomic copy loop and thus an ATOMIC_COPY task. The description of the operation attempts to disambiguate between
		 tasks that are performing the same basic work.

       object	 Most tasks are related to a specific object, usually the volume within which the operation is taking place.

       parent	 Some  utilities  require multiple operations to fulfill a request. For example, the vxrecover utility may need to start many dif-
		 ferent volumes. In these cases, the subtasks list their parent.

       progress information
		 Each task has an indication of its starting point and ending point, and an indication as to what point it has progressed so  far.
		 Combined with the work time, this allows the amount of time remaining until completion to be estimated for some tasks.

       state	 Each task has one of three states: RUNNING, PAUSED or ABORTING.

       time	 Each task notes its starting time and the total amount of time spent doing work.

KEYWORDS

       abort|pause|resume
		 These three operations request that the specified task change its state.  pause puts a running task in the paused state, suspend-
		 ing its operation. resume continues the operation of a paused task.  abort stops the operation of the specified.  In most  cases,
		 the operations "back out" in a manner similar to when an I/O error occurs, reversing as much as possible what's been done so far.

       list	 List  tasks running on the system in one-line summaries.  The value displayed for percentage task progress takes into account all
		 intermediate steps that are required to accomplish a specific task.

		 By default, all tasks running on the system are printed.  If a taskid argument is supplied, the output is limited to those  tasks
		 whose taskid or task tag match taskid. The remaining options filter and limit the listed tasks as follows:

		 -a	   Limits the output to tasks in the aborting state.

		 -g dg_name
			   Limits the listed tasks to those tasks running on objects in the diskgroup dg_name.

		 -G	   Distinguishes between volumes with the same name in different diskgroups; see vxintro(1M).

		 -h	   Prints tasks hierarchically with a task's child tasks following the parent task.

		 -l	   Prints tasks in long format.

		 -p	   Limits the output to tasks in the paused state.

		 -q	   Suppresses printing of column headings.

		 -r	   Limits the output to tasks in the running state.

		 -v volume Limits the output to tasks whose object is volume.

		 Any  task  meeting any of the criteria specified are printed. That is, if -v foovol and -p are specified, then any task operating
		 on foovol or that is paused are printed. If -h were also specified, then those tasks and all their children would be listed.

       monitor	 The monitor operation continuously prints information about a task or group of tasks as the task  information	changes.   The	-l
		 option specifies printing a long listing.  The default is to print  one-line listings.

		 The monitor command accepts the following options:

		 -c count  Prints count sets of task information, then exits.

		 -n	   Monitors  not  only	the  tasks specified on the command line, but also any tasks newly registered while the program is
			   running.

		 -t time   Exits after time seconds.

		 -w interval
			   Prints the string "waiting..." when interval seconds pass with no output activity.

		 In addition to printing task information when a task state changes, output is also generated when the task completes.	When  this
		 occurs, the task state is printed as EXITED (see the OUTPUT section).

       set	 The set operation changes modifiable parameters of a task.  There is only one modifiable parameter for tasks: the slow attribute,
		 which represents a throttle on the task progress.  The larger the slow value, the slower the progress of the task and	the  fewer
		 system resources it consumes in a given time. (The slow attribute is the same attribute that many commands, such as vxplex, vxvol
		 and vxrecover, accept.)

OUTPUT

       There are two output formats printed by vxtask: a short, one-line summary format per task, and a  long  task  listing.  The  short  listing
       attempts to provide the most used task information for quick perusal, displaying the following fields from left to right:

	    1. The task ID for the task.

	    2. The task ID of the task's parent, if any. If the task has no parent, this field is left blank.

	    3. The task type and state, separated by a slash (/). The type field is a description of the work being performed, such as ATOMIC COPY
	       for atomic copy I/O and RELAYOUT for an online relayout operation. The state is a single letter representing the task state: R  for
	       running,  P  for paused, and K for aborting.  In the special case of the completion of a task that is being monitored, the state is
	       printed as EXITING.

	    4. The percentage of the operation that has been completed to this point.

	    5. The task's progress information. For basic tasks, this is the starting offset, ending offset and current offset for the	operation,
	       separated  by  slashes  (/). For parent tasks, this is the starting number of child tasks, total number of child tasks required for
	       the operation to complete, and the number of child tasks already completed to this point, separated by  slashes,  followed  by  the
	       number of children currently running in parentheses.

	    6. A  description  of  the	command  for which the task is performing work. This is normally a single word, such as START for a volume
	       start operation or RELAYOUT for an online relayout, followed by object names, indicating what the arguments were for  the  command.
	       See EXAMPLES below.
       The  long  output format prints all available information for a task, spanning multiple lines. If more than one task is printed, the output
       for different tasks is separated by a single blank line. Each line in the long output format contains a title for the line, followed  by  a
       colon (:), followed by the information. The possible information printed for a task includes:

       Operation:
		 A description of the operation on whose behalf the work is being performed. This is essentially a description of the command exe-
		 cuted along with the Veritas Volume Manager objects specified as arguments.

       Progress: A description of the progress of the task. The progress is stated as a percentage of completion, along with the  actual  progress
		 values for the task.

       Started:  The time that the task was started.

       Task:	 General  information  for  the  task.	The task's ID, followed by its parent's ID (if any) in parentheses, followed by the task's
		 state, either RUNNING, PAUSED or ABORTING.

       Throttle  The throttle value for the task, if applicable.

       Type:	 The task type, describing the work being performed.

       Work time:
		 States how much time has been spent performing the work, and a rough estimate of the time remaining for the task to complete.

       As a special case, when a task being monitored completes only the Task: line is printed for the task, with the task  state  represented	by
       EXITED.

EXAMPLES

       To list all tasks currently running on the system:

	      vxtask list

       To trace all tasks in the diskgroup foodg that are currently paused, as well as any tasks with the tag sysstart:

	      vxtask -g foodg -p -i sysstart list

       To list all tasks on the system that are currently paused:

	      vxtask -p list

       To monitor all tasks with the tag myoperation:

	      vxtask monitor myoperation

       To cause all tasks tagged with recovall to exit:

	      vxtask abort recovall

FILES

       /dev/vx/info		     Used to get task information from the kernel.

       /dev/vx/taskmon		     Task monitoring device.

SEE ALSO

       vxintro(1M), vxplex(1M), vxrecover(1M), vxsd(1M), vxvol(1M)

VxVM 5.0.31.1							    24 Mar 2008 							vxtask(1M)