Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
BUTC(5)			      AFS File Reference		       BUTC(5)

NAME
       butc - Defines Tape Coordinator instructions for	automated tape devices

DESCRIPTION
       The CFG_device_name file	includes instructions that configure a Tape
       Coordinator (butc) for use with automated backup	devices	such as	tape
       stackers	and jukeboxes, enable the Tape Coordinator to dump and restore
       data to a backup	data file on a local disk device, and enable greater
       automation of other aspects of the backup process.

       There is	a separate configuration file for each tape device or backup
       data file. Creating the file is optional, and unnecessary if none of
       the instructions	it can include pertain to a given tape device. The
       ASCII-format file must reside in	the /var/openafs/backup	directory on
       the Tape	Coordinator machine if it exists.

       The CFG_device_name file	does not replace the
       /var/openafs/backup/tapeconfig file, a single copy of which still must
       exist on	every Tape Coordinator machine.

       To enable the Tape Coordinator to locate	the configuration file,
       construct the variable part of the filename, device_name, as follows:

       o   For a tape device, strip off	the initial "/dev/" string from	the
	   device name,	and replace any	other slashes in the name with
	   underscores.	For example, CFG_rmt_4m	is the appropriate filename
	   for a device	called /dev/rmt/4m.

       o   For a backup	data file, strip off the initial slash ("/") and
	   replace any other slashes in	the name with underscores. For
	   example, CFG_var_tmp_FILE is	the appropriate	filename for a backup
	   data	file called /var/tmp/FILE.

       The CFG_device_name file	lists one or more of the following
       instructions, each on its own line. All are optional, and they can
       appear in any order. A more detailed description	of each	instruction
       follows the list:

       ASK Controls whether the	Tape Coordinator prompts for guidance when it
	   encounters error conditions.

       AUTOQUERY
	   Controls whether the	Tape Coordinator prompts for the first tape.

       BUFFERSIZE
	   Sets	the size of the	memory buffer the Tape Coordinator uses	when
	   transferring	data.

       FILE
	   Controls whether the	dump is	written	to a tape device or a file.

       MOUNT
	   Identifies the file that contains routines for inserting tapes into
	   the device's	drive.

       NAME_CHECK
	   Controls whether the	Tape Coordinator verifies that a tape's	AFS
	   tape	name matches the dump being written.

       UNMOUNT
	   Identifies the file that contains routines for removing tapes from
	   the device's	drive.

   The ASK Instruction
       The "ASK" instruction takes a boolean value as its argument, in the
       following format:

	  ASK (YES | NO)

       When the	value is "YES",	the Tape Coordinator generates a prompt	in its
       window, requesting a response to	the error cases	described in the
       following list. This is the default behavior if the "ASK" instruction
       does not	appear in the CFG_device_name file.

       When the	value is "NO", the Tape	Coordinator does not prompt in error
       cases, but instead uses the automatic default responses described in
       the following list. The Tape Coordinator	also logs the error in the
       TE_device_name file. Suppressing	the prompts enables the	Tape
       Coordinator to run unattended, though it	still prompts for insertion of
       tapes unless the	"MOUNT"	instruction is used.

       The error cases controlled by this instruction are the following:

       o   The Backup System is	unable to dump a volume	while running the
	   backup dump command.	With a "YES" value, the	Tape Coordinator
	   prompts to offer three choices: try to dump the volume again
	   immediately,	omit the volume	from the dump but continue the
	   operation, or terminate the operation. With a "NO" value, the Tape
	   Coordinator omits the volume	from the dump and continues the
	   operation.

       o   The Backup System is	unable to restore a volume while running the
	   backup diskrestore, backup volrestore, or backup volsetrestore
	   command. With a "YES" value,	the Tape Coordinator prompts to	offer
	   two choices:	omit the volume	and continue restoring the other
	   volumes, or terminate the operation.	With a "NO" value, it
	   continues the operation without prompting, omitting the problematic
	   volume but restoring	the remaining ones.

       o   The Backup System cannot determine if the dump set includes any
	   more	tapes, while running the backup	scantape command (the
	   reference page for that command discusses possible reasons for this
	   problem).  With a "YES" value, the Tape Coordinator prompts to ask
	   if there are	more tapes to scan. With a "NO"	value, it proceeds as
	   though there	are more tapes and invokes the routine named by	the
	   "MOUNT" instruction in the configuration file, or prompts the
	   operator to insert the next tape.

       o   The Backup System determines	that the tape contains an unexpired
	   dump	while running the backup labeltape command. With a "YES"
	   value, the Tape Coordinator prompts to offer	two choices: continue
	   or terminate	the labeling operation.	With a "NO" value, it
	   terminates the operation without relabeling the tape.

   The AUTOQUERY Instruction
       The "AUTOQUERY" instruction takes a boolean value as its	argument, in
       the following format:

	  AUTOQUERY (YES | NO)

       When the	value is "YES",	the Tape Coordinator checks for	the "MOUNT"
       instruction in the configuration	file when it needs to read the first
       tape involved in	an operation. As described for that instruction, it
       then either prompts for the tape	or invokes the specified routine to
       mount the tape. This is the default behavior if the "AUTOQUERY"
       instruction does	not appear in the configuration	file.

       When the	value is "NO", the Tape	Coordinator assumes that the first
       tape required for an operation is already in the	drive. It does not
       prompt the operator or invoke the "MOUNT" routine unless	there is an
       error in	accessing the first tape. This setting is equivalent in	effect
       to including the	-noautoquery flag to the butc command.

       Note that the setting of	the "AUTOQUERY"	instruction controls the Tape
       Coordinator's behavior only with	respect	to the first tape required for
       an operation. For subsequent tapes, the Tape Coordinator	always checks
       for the "MOUNT" instruction. It also refers to the "MOUNT" instruction
       if it encounters	an error while attempting to access the	first tape.

   The BUFFERSIZE Instruction
       The "BUFFERSIZE"	instruction takes an integer value, and	optionally
       units, in the following format:

	  BUFFERSIZE <size>[(k | K | m | M | g | G)]

       where <size> specifies the amount of memory the Tape Coordinator
       allocates to use	as a buffer during both	dump and restore operations.
       The default unit	is bytes, but use "k" or "K" to	specify	kilobytes, "m"
       or "M" for megabytes, and "g" or	"G" for	gigabytes. There is no space
       between the <size> value	and the	units letter.

       By default, the Tape Coordinator	uses a 16 KB buffer during dump
       operations. As it receives volume data from the Volume Server, the Tape
       Coordinator gathers 16 KB of data in the	buffer before transferring the
       entire 16 KB to the tape	device or backup data file. Similarly, during
       a restore operation the Tape Coordinator	by default buffers 32 KB of
       data from the tape device or backup data	file before transferring the
       entire 32 KB to the Volume Server for restoration into the file system.
       Buffering makes the volume of data flowing to and from a	tape device
       more even and so	promotes tape streaming, which is the most efficient
       way for a tape device to	operate.

       In a normal network configuration, the default buffer sizes are usually
       large enough to promote tape streaming. If the network between the Tape
       Coordinator machine and file server machines is slow, it	can help to
       increase	the buffer size.

   The FILE Instruction
       The "FILE" instruction takes a boolean value as its argument, in	the
       following format:

	  FILE (NO | YES)

       When the	value is "NO", the Tape	Coordinator writes to a	tape device
       during a	dump operation and reads from one during a restore operation.
       This is the default behavior if the "FILE" instruction does not appear
       in the configuration file.

       When the	value is "YES",	the Tape Coordinator writes volume data	to a
       backup data file	on the local disk during a dump	operation and reads
       volume data from	a file during a	restore	operation. If the file does
       not exist when the Tape Coordinator attempts to access it to write a
       dump, the Tape Coordinator creates it. For a restore operation to
       succeed,	the file must exist and	contain	volume data previously written
       to it by	a backup dump operation.

       When the	value is "YES",	the backup data	file's complete	pathname must
       appear (instead of a tape drive device name) in the third field of the
       corresponding port offset entry in the local
       /var/openafs/backup/tapeconfig file. If the field instead refers	to a
       tape device, dump operations appear to succeed but are inoperative. It
       is not possible to restore data that was	accidently dumped to a tape
       device while the	"FILE" instruction was set to "YES". (In the same way,
       if the "FILE" instruction is set	to "NO", the tapeconfig	entry must
       refer to	an actual tape device.)

       Rather than put an actual file pathname in the third field of the
       tapeconfig file,	however, the recommended configuration is to create a
       symbolic	link in	the /dev directory that	points to the actual file
       pathname, and record the	symbolic link in this field. This
       configuration has a couple of advantages:

       o   It makes the	device_name portion of the CFG_device_name,
	   TE_device_name, and TL_device_name names as short as	possible.
	   Because the symbolic	link is	in the /dev directory as though	it
	   were	a tape device, the device configuration	file's name is
	   constructed by stripping off	the entire /dev/ prefix, instead of
	   just	the initial slash. If, for example, the	symbolic link is
	   called /dev/FILE, the device	configuration file name	is CFG_FILE,
	   whereas if the actual pathname /var/tmp/FILE	appears	in the
	   tapeconfig file, the	file's name must be CFG_var_tmp_FILE.

       o   It provides for a more graceful, and	potentially automated,
	   recovery if the Tape	Coordinator cannot write a complete dump into
	   the backup data file	(because the partition housing the backup data
	   file	becomes	full, for example). The	Tape Coordinator's reaction to
	   this	problem	is to invoke the "MOUNT" script, or to prompt the
	   operator if the "MOUNT" instruction does not	appear in the
	   configuration file.

	   o   If there	is a "MOUNT" routine, the operator can prepare for
	       this situation by adding	a subroutine that changes the symbolic
	       link to point to	another	backup data file on a partition	where
	       there is	space available.

	   o   If there	is no "MOUNT" instruction, the prompt enables the
	       operator	manually to change the symbolic	link to	point to
	       another backup data file, then press Return to signal that the
	       Tape Coordinator	can continue the operation.

       If the third field in the tapeconfig file names the actual file,	there
       is no way to recover from exhausting the	space on the partition that
       houses the backup data file. It is not possible to change the
       tapeconfig file in the middle of	an operation.

       When writing to a backup	data file, the Tape Coordinator	writes data at
       16 KB offsets. If a given block of data (such as	the marker that
       signals the beginning or	end of a volume) does not fill the entire 16
       KB, the Tape Coordinator	still skips to the next	offset before writing
       the next	block. In the output of	a backup dumpinfo command issued with
       the -id option, the value in the	"Pos" column is	the ordinal of the
       16-KB offset at which the volume	data begins, and so is not generally
       only one	higher than the	position number	on the previous	line, as it is
       for dumps to tape.

   The MOUNT Instruction
       The "MOUNT" instruction takes a pathname	as its argument, in the
       following format:

	  MOUNT	<filename>

       The referenced executable file must reside on the local disk and
       contain a shell script or program that directs an automated tape
       device, such as a jukebox or stacker, to	mount a	tape (insert it	into
       the tape	reader).  The operator must write the routine to invoke	the
       mount command specified by the device's manufacturer; AFS does not
       include any scripts, although an	example	appears	in "EXAMPLES".	The
       script or program inherits the Tape Coordinator's AFS authentication
       status.

       When the	Tape Coordinator needs to mount	a tape,	it checks the
       configuration file for a	"MOUNT"	instruction. If	there is no "MOUNT"
       instruction, the	Tape Coordinator prompts the operator to insert	a tape
       before it attempts to open the tape device. If there is a "MOUNT"
       instruction, the	Tape Coordinator executes the routine in the
       referenced file.	The routine invoked by the "MOUNT" instruction
       inherits	the local identity (UNIX UID) and AFS tokens of	the butc
       command's issuer.

       There is	an exception to	this sequence: if the "AUTOQUERY NO"
       instruction appears in the configuration	file, or the -noautoquery flag
       was included on the butc	command, then the Tape Coordinator assumes
       that the	operator has already inserted the first	tape needed for	a
       given operation.	It attempts to read the	tape immediately, and only
       checks for the "MOUNT" instruction or prompts the operator if the tape
       is missing or is	not the	required one.

       When the	Tape Coordinator invokes the routine indicated by the "MOUNT"
       instruction, it passes the following parameters to the routine in the
       indicated order:

       o   The tape device or backup data file's pathname, as recorded in the
	   /var/openafs/backup/tapeconfig file.

       o   The tape operation, which (except for the exceptions	noted in the
	   following list) matches the backup command operation	code used to
	   initiate the	operation:

	   o   "appenddump" (when a backup dump	command	includes the -append
	       flag).

	   o   "dump" (when a backup dump command does not include the -append
	       flag).

	   o   "labeltape"

	   o   "readlabel"

	   o   "restore" (for a	backup diskrestore, backup volrestore, or
	       backup volsetrestore command).

	   o   "restoredb"

	   o   "savedb"

	   o   "scantape"

       o   The number of times the Tape	Coordinator has	attempted to open the
	   tape	device or backup data file. If the open	attempt	returns	an
	   error, the Tape Coordinator increments this value by	one and	again
	   invokes the "MOUNT" instruction.

       o   The tape name. For some operations, the Tape	Coordinator passes the
	   string "none", because it does not know the tape name (when running
	   the backup scantape or backup readlabel, for	example), or because
	   the tape does not necessarily have a	name (when running the backup
	   labeltape command, for example).

       o   The tape ID recorded	in the Backup Database.	As with	the tape name,
	   the Backup System passes the	string "none" for operations where it
	   does	not know the tape ID or	the tape does not necessarily have an
	   ID.

       The routine invoked by the "MOUNT" instruction must return an exit code
       to the Tape Coordinator:

       o   Code	0 (zero) indicates that	the routine successfully mounted the
	   tape. The Tape Coordinator continues	the backup operation.  If the
	   routine invoked by the "MOUNT" instruction does not return this
	   exit	code, the Tape Coordinator never calls the "UNMOUNT"
	   instruction.

       o   Code	1 (one)	indicates that the routine failed to mount the tape.
	   The Tape Coordinator	terminates the operation.

       o   Any other code indicates that the routine was not able to access
	   the correct tape. The Tape Coordinator prompts the operator to
	   insert the correct tape.

       If the backup command was issued	in interactive mode and	the operator
       issues the backup kill command while the	"MOUNT"	routine	is running,
       the Tape	Coordinator passes the termination signal to the routine; the
       entire operation	terminates.

   The NAME_CHECK Instruction
       The "NAME_CHECK"	instruction takes a boolean value as its argument, in
       the following format:

	  NAME_CHECK (YES | NO)

       When the	value is "YES" and the tape does not have a permanent name,
       the Tape	Coordinator checks the AFS tape	name when dumping a volume in
       response	to the backup dump command. The	AFS tape name must be "<NULL>"
       or match	the tape name that the backup dump operation assigns based on
       the volume set and dump level names. This is the	default	behavior if
       the "NAME_CHECK"	instruction does not appear in the configuration file.

       When the	value is "NO", the Tape	Coordinator does not check the AFS
       tape name before	writing	to the tape.

       The Tape	Coordinator always checks that all dumps on the	tape are
       expired,	and refuses to write to	a tape that contains unexpired dumps.

   The UNMOUNT Instruction
       The "UNMOUNT" instruction takes a pathname as its argument, in the
       following format:

	  UNMOUNT <filename>

       The referenced executable file must reside on the local disk and
       contain a shell script or program that directs an automated tape
       device, such as a jukebox or stacker, to	unmount	a tape (remove it from
       the tape	reader).  The operator must write the routine to invoke	the
       unmount command specified by the	device's manufacturer; AFS does	not
       include any scripts, although an	example	appears	in "EXAMPLES".	The
       script or program inherits the Tape Coordinator's AFS authentication
       status.

       After closing a tape device, the	Tape Coordinator checks	the
       configuration file for an "UNMOUNT" instruction,	whether	or not the
       close operation succeeds. If there is no	"UNMOUNT" instruction, the
       Tape Coordinator	takes no action, in which case the operator must take
       the action necessary to remove the current tape from the	drive before
       another can be inserted.	If there is an "UNMOUNT" instruction, the Tape
       Coordinator executes the	referenced file. It invokes the	routine	only
       once, passing in	the following parameters:

       o   The tape device pathname (as	specified in the
	   /var/openafs/backup/tapeconfig file).

       o   The tape operation (always unmount).

PRIVILEGE REQUIRED
       The file	is protected by	UNIX mode bits.	Creating the file requires the
       "w" (write) and "x" (execute) permissions on the	/var/openafs/backup
       directory. Editing the file requires the	"w" (write) permission on the
       file.

EXAMPLES
       The following example configuration files demonstrate one way to
       structure a configuration file for a stacker or backup dump file. The
       examples	are not	necessarily appropriate	for a specific cell; if	using
       them as models, be sure to adapt	them to	the cell's needs and
       equipment.

   Example CFG_device_name File	for Stackers
       In this example,	the administrator creates the following	entry for a
       tape stacker called "stacker0.1"	in the /var/openafs/backup/tapeconfig
       file. It	has port offset	0.

	  2G   5K   /dev/stacker0.1   0

       The administrator includes the following	five lines in the
       /var/openafs/backup/CFG_stacker0.1 file.	To review the meaning of each
       instruction, see	"DESCRIPTION".

	  MOUNT	/var/openafs/backup/stacker0.1
	  UNMOUNT /var/openafs/backup/stacker0.1
	  AUTOQUERY NO
	  ASK NO
	  NAME_CHECK NO

       Finally,	the administrator writes the following executable routine in
       the /var/openafs/backup/stacker0.1 file referenced by the "MOUNT" and
       "UNMOUNT" instructions in the CFG_stacker0.1 file.

	  #! /bin/csh -f

	  set devicefile = $1
	  set operation	= $2
	  set tries = $3
	  set tapename = $4
	  set tapeid = $5

	  set exit_continue = 0
	  set exit_abort = 1
	  set exit_interactive = 2

	  #--------------------------------------------

	  if (${tries} > 1) then
	     echo "Too many tries"
	     exit ${exit_interactive}
	  endif

	  if (${operation} == "unmount") then
	     echo "UnMount: Will leave tape in drive"
	     exit ${exit_continue}
	  endif

	  if ((${operation} == "dump")	   |\
	      (${operation} == "appenddump")	 |\
	      (${operation} == "savedb"))  then

	      stackerCmd_NextTape ${devicefile}
	      if (${status} != 0)exit${exit_interactive}
	      echo "Will continue"
	      exit ${exit_continue}
	  endif

	  if ((${operation} == "labeltape")    |\
	      (${operation} == "readlabel")) then
	     echo "Will	continue"
	     exit ${exit_continue}
	  endif

	  echo "Prompt for tape"
	  exit ${exit_interactive}

       This routine uses two of	the parameters passed to it by the Backup
       System: "tries" and "operation".	It follows the recommended practice of
       prompting for a tape if the value of the	"tries"	parameter exceeds one,
       because that implies that the stacker is	out of tapes.

       For a backup dump or backup savedb operation, the routine calls the
       example "stackerCmd_NextTape" function provided by the stacker's
       manufacturer. Note that the final lines in the file return the exit
       code that prompts the operator to insert	a tape;	these lines are
       invoked when either the stacker cannot load a tape or a the operation
       being performed is not one of those explicitly mentioned	in the file
       (such as	a restore operation).

   Example CFG_device_name File	for Dumping to a Data File
       In this example,	the administrator creates the following	entry for a
       backup data file	called HSM_device in the
       /var/openafs/backup/tapeconfig file. It has port	offset 20.

	  1G   0K   /dev/HSM_device   20

       The administrator includes the following	lines in the
       /var/openafs/backup/CFG_HSM_device file.	To review the meaning of each
       instruction, see	"DESCRIPTION".

	  MOUNT	/var/openafs/backup/file
	  FILE YES
	  ASK NO

       Finally,	the administrator writes the following executable routine in
       the /var/openafs/backup/file file referenced by the "MOUNT" instruction
       in the CFG_HSM_device file, to control how the Tape Coordinator handles
       the file.

	  #! /bin/csh -f
	  set devicefile = $1
	  set operation	= $2
	  set tries = $3
	  set tapename = $4
	  set tapeid = $5

	  set exit_continue = 0
	  set exit_abort = 1
	  set exit_interactive = 2

	  #--------------------------------------------

	  if (${tries} > 1) then
	     echo "Too many tries"
	     exit ${exit_interactive}
	  endif

	  if (${operation} == "labeltape") then
	     echo "Won't label a tape/file"
	     exit ${exit_abort}
	  endif

	  if ((${operation} == "dump")	 |\
	      (${operation} == "appenddump")   |\
	      (${operation} == "restore")   |\
	      (${operation} == "savedb")    |\
	      (${operation} == "restoredb")) then

	     /bin/rm -f	${devicefile}
	     /bin/ln -s	/hsm/${tapename}_${tapeid} ${devicefile}
	     if	(${status} != 0) exit ${exit_abort}
	  endif

	  exit ${exit_continue}

       Like the	example	routine	for a tape stacker, this routine uses the
       "tries" and "operation" parameters passed to it by the Backup System.
       The "tries" parameter tracks how	many times the Tape Coordinator	has
       attempted to access the file. A value greater than one indicates	that
       the Tape	Coordinator cannot access it, and the routine returns exit
       code 2 ("exit_interactive"), which results in a prompt for the operator
       to load a tape. The operator can	use this opportunity to	change the
       name of the backup data file specified in the tapeconfig	file.

       The primary function of this routine is to establish a link between the
       device file and the file	to be dumped or	restored. When the Tape
       Coordinator is executing	a backup dump, backup restore, backup savedb,
       or backup restoredb operation, the routine invokes the UNIX "ln -s"
       command to create a symbolic link from the backup data file named in
       the tapeconfig file to the actual file to use (this is the recommended
       method).	It uses	the value of the "tapename" and	"tapeid" parameters to
       construct the file name.

SEE ALSO
       tapeconfig(5), backup_diskrestore(8), backup_dump(8),
       backup_restoredb(8), backup_savedb(8), backup_volrestore(8),
       backup_volsetrestore(8)

COPYRIGHT
       IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.

       This documentation is covered by	the IBM	Public License Version 1.0.
       It was converted	from HTML to POD by software written by	Chas Williams
       and Russ	Allbery, based on work by Alf Wachsmann	and Elizabeth Cassell.

OpenAFS				  2016-12-14			       BUTC(5)

NAME | DESCRIPTION | PRIVILEGE REQUIRED | EXAMPLES | SEE ALSO | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=butc&sektion=5&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help