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

FreeBSD Manual Pages

  
 
  

home | help
BACKUP_DUMP(8)		     AFS Command Reference		BACKUP_DUMP(8)

NAME
       backup_dump - Creates a dump (dumps a volume set	at a particular	dump
       level)

SYNOPSIS
       backup dump [-volumeset <volume set name>]
	   [-dump <dump	level name>]
	   [-portoffset	<TC port offset>]
	   [-at	<date/time to start dump>+]
	   [-append] [-n]
	   [-file <load	file>] [-localauth]
	   [-cell <cell	name>] [-help]

       backup dump [-v <volume set name>]
	   [-d <dump level name>]
	   [-p <TC port	offset>]
	   [-at	<Date/time to start dump>+] [-ap] [-n]
	   [-f <load file>] [-l] [-c <cell name>]
	   [-h]

DESCRIPTION
       The backup dump command either dumps the	volume set specified by	the
       -volumeset argument at the dump level specified by the -dump argument
       and creates a Backup Database dump record about it, or executes the
       dump instructions listed	in the file named by the -file argument. The
       Tape Coordinator	indicated by the -portoffset argument (or on each
       command in the file) executes the operation.

       (If the "FILE YES" instruction appears in the
       /var/openafs/backup/CFG_device_name file	on the Tape Coordinator
       machine associated with the specified port offset, then the Backup
       System dumps data to the	backup data file listed	for that port offset
       in the Tape Coordinator's /var/openafs/backup/tapeconfig	file, rather
       than to tape. For the sake of clarity, the following text refers	to
       tapes only, but the Backup System handles backup	data files in much the
       same way.)

       The term	dumping	refers to copying a collection of data to tape or a
       backup data file, and the resulting collection is termed	a dump.	The
       set of tapes that contain one or	more dumps is called a dump set. The
       first dump in a dump set	is its initial dump, and any dumps
       subsequently added to the dump set (by use of the -append argument) are
       appended	dumps.	Creating appended dumps	is optional, and appended
       dumps can be of different volume	sets, and at different dump levels,
       than the	initial	dump.

       A full dump, created at a full dump level in the	dump hierarchy,
       contains	all of the data	that existed at	the time of the	dump in	the
       volumes belonging to the	volume set. An incremental dump, created at an
       incremental dump	level, contains	only data that has changed since the
       volume set was dumped at	the incremental	level's	parent dump level (the
       dump level immediately above the	incremental level in the hierarchy),
       which can be a full or incremental level. More specifically, an
       incremental dump	includes only the files	and directories	that have
       modification timestamps later than the clone date of the	volume
       included	at the parent dump level. For backup and read-only volumes,
       the clone date is the time at which the volume was cloned from its
       read/write source before	being included in the parent dump; for
       read/write volumes, it represents the time at which the volume was
       locked for inclusion in the parent dump.	The clone date appears in the
       clone date field	of the output from the backup volinfo command. As an
       example,	an incremental dump at the "/full/week1/thursday" level
       includes	only files and directories that	have changed since the volume
       set was dumped at the "/full/week1" level.

   Initiating different	types of dump operations
       To initiate a dump operation that is to start as	soon as	the relevant
       Tape Coordinator	is available, provide only the -volumeset, -dump,
       -portoffset, and	optionally -append options. To schedule	a single
       backup dump command to execute in the future, also include the -at
       argument	to specify the start time.

       To append a dump	to an existing dump set, include the -append flag. The
       Backup System imposes the following conditions on appended dumps:

       o   If writing to tape, the Tape	Coordinator checks that	it is the
	   final one in	a dump set for which there are complete	and valid tape
	   and dump records in the Backup Database. If not, it rejects the
	   tape	and requests an	acceptable one.	The operator can use the
	   -dbadd argument to the backup scantape command to insert the
	   necessary records into the database.

       o   The most recent dump	on the tape or in the backup data file must
	   have	completed successfully.

       o   The dump set	must begin with	an initial dump	that is	recorded in
	   the Backup Database.	If there are no	dumps on the tape, then	the
	   Backup System treats	the dump operation as an initial dump and
	   imposes the relevant	requirements (for example, checks the AFS tape
	   name	if appropriate).

       To schedule multiple dump operations, list the operations in the	file
       named by	the -file argument. Optionally include the -at argument	to
       specify when the	backup command interpreter reads the file; otherwise
       it reads	it immediately.	Do not combine the -file argument with the
       command's first three arguments or the -append or -n flags. The
       commands	in the file can	include	any of the backup dump command's
       arguments, including the	-at argument to	schedule them to run even
       later in	the future.

       To generate a list of the volumes included in a dump, without actually
       dumping them, combine the -n flag with the options to be	used on	the
       actual command.

   How the Backup System executes a dump operation
       Before beginning	a dump operation, the Backup System verifies that
       there is	a Backup Database entry	for the	volume set, dump level,	and
       port offset. If the command is correctly	formed and issued in
       interactive mode, it is assigned	a job number and added to the jobs
       list. List jobs in interactive mode by using the	backup jobs command;
       terminate them with the backup kill command.

       After obtaining the list	of volumes to dump from	the Volume Location
       (VL) Server, the	Backup System sorts the	list by	site (server and
       partition). It groups volumes from the same site	together in the	dump
       to minimize the number of times the operator must change	tapes during
       restore operations.

       The dependence of an incremental	dump on	its parent means that a	valid
       parent dump must	already	exist for the Backup System to create its
       child incremental dump. If the Backup System does not find a record of
       a dump created at the immediate parent dump level, it looks in the
       Backup Database for a dump created at one level higher in the
       hierarchy, and so on, up	to the full dump level if necessary. It
       creates an incremental dump at the level	one below the lowest valid
       parent dump set that it finds. If it fails to find even a full dump, it
       dumps the volume	set at the full	dump level.

       If the Backup System is unable to access	a volume during	a dump
       operation, it skips the volume and dumps	the remaining volumes from the
       volume set. Possible reasons a volume is	inaccessible include server
       machine or process outages, or that the volume was moved	between	the
       time the	Volume Location	(VL) Server generated the list of sites	for
       the volume in the volume	set and	the time the Backup System actually
       attempts	to dump	the data in it.	After the first	dumping	pass, the
       Backup System attempts to dump each volume it skipped. If it still
       cannot dump a volume and	the "ASK NO" instruction does not appear in
       the CFG_device_name file, it queries the	operator as to whether it
       needs to	attempt	to dump	the volume again, omit the volume from the
       dump, or	halt the dump operation	altogether. When prompted, the
       operator	can attempt to solve whatever problem prevented	the Backup
       System from accessing the volumes. If the "ASK NO" instruction appears
       in the CFG_device_name file, the	Backup System omits the	volume from
       the dump.

       Before scheduling a dump	operation, the Backup System verifies that the
       date specified by the -at argument is in	the future, and	checks the
       validity	of the volume set, dump	level and port offset as for a regular
       dump operation. It checks the validity of the parameters	again just
       before actually running the scheduled operation.

       Before writing an initial dump to a tape	that does not have a permanent
       name on the label, the Backup System checks that	the AFS	tape name on
       the label is acceptable.	If desired, disable name checking by including
       the "NAME_CHECK NO" instruction in the CFG_device_name file.

       If AFS tape name	checking is enabled, the Backup	System accepts the
       following three types of	values for the AFS tape	name. If the name on
       the label does not conform, the Backup System obtains a tape with an
       acceptable label	by invoking the	"MOUNT"	instruction in the
       CFG_device_name file or prompting the operator.

       o   A name of the form volume_set_name.dump_level_name.tape_index,
	   where volume_set_name matches the value of the -volumeset argument,
	   dump_level_name matches the last element in the pathname value of
	   the -dump argument, and tape_index reflects the tape's place	in a
	   multitape dump set. As an example, the first	tape in	a dump set for
	   which the initial dump is of	volume set "user" at the dump level
	   "/sunday2/monday" has AFS tape name "user.monday.1".	If the label
	   records this	type of	AFS tape name, the Backup System retains the
	   AFS tape name and writes the	dump to	the tape.

       o   The string "<NULL>",	which usually indicates	that a backup operator
	   has used the	backup labeltape command to write a label on the tape,
	   but did not include the -name argument to assign an AFS tape	name.
	   Presumably, the operator did	include	the -pname argument to assign
	   a permanent name. If	the label records a "<NULL>" value, the	Backup
	   System constructs and records on the	label the appropriate AFS tape
	   name, and writes the	dump on	the tape.

       o   No value at all, because the	tape has never been labeled or used in
	   the Backup System. As when the AFS tape name	is "<NULL>", the
	   Backup System constructs and	records	on the label the appropriate
	   AFS tape name, and writes the dump on the tape.

       To determine how	much data it can write to a tape, the Tape Coordinator
       reads the capacity recorded on the tape's label (placed there by
       including the -size argument to the backup labeltape command). If the
       label's capacity	field is empty,	the Tape Coordinator uses the capacity
       recorded	for the	specified port offset in the local tapeconfig file. If
       the capacity field in the tapeconfig file is also empty,	the Tape
       Coordinator uses	the maximum capacity of	2 TB.

       During a	dump operation,	the Tape Coordinator tracks how	much data it
       has written and stops shortly before it reaches what it believes	is the
       tape's capacity.	If it is in the	middle of writing the data for a
       volume when it reaches that point, it writes a special marker that
       indicates an interrupted	volume and continues writing the volume	on the
       next tape. It can split a volume	this way during	both an	initial	and an
       appended	dump, and the fact that	the volume resides on multiple tapes
       is automatically	recorded in the	Backup Database.

       If the tape is actually larger than the expected	capacity, then the
       Tape Coordinator	simply does not	use the	excess tape. If	the tape is
       smaller than the	expected capacity, the Tape Coordinator	can reach the
       end-of-tape (EOT) unexpectedly while it is writing data.	If the Tape
       Coordinator is in the middle of the writing data	from a volume, it
       obtains a new tape and rewrites the entire contents of the interrupted
       volume to it. The data from the volume that was written to the previous
       tape remains there, but is never	used.

       The Backup System allows	recycling of tapes (writing a new dump set
       over an old dump	set that is no longer needed), but imposes the
       following conditions:

       o   All dumps in	the old	dump set must be expired. The Backup System
	   always checks expiration dates, even	when name checking is
	   disabled.

       o   If the tape to be recycled does not have a permanent	name and name
	   checking is enabled,	then the AFS tape name derived from the	new
	   initial dump's volume set name and dump level name must match the
	   AFS tape name already recorded on the label.

       o   The tape cannot already have	data on	it that	belongs	to the dump
	   currently being performed, because that implies that	the operator
	   or automated	tape device has	not removed the	previous tape from the
	   drive, or has mistakenly reinserted it. The Tape Coordinator
	   generates the following message and attempts	to obtain another
	   tape:

	      Can't overwrite tape containing the dump in progress

       o   The tape cannot contain data	from a parent dump of the current
	   (incremental) dump, because overwriting a parent dump makes it
	   impossible to restore data from the current dump. The Tape
	   Coordinator generates the following message and attempts to obtain
	   another tape:

	      Can't overwrite the parent dump I<parent_name> (I<parent_dump_ID>)

       To recycle a tape before	all dumps on it	have expired or	if the AFS
       tape name is wrong, use the backup labeltape command to overwrite the
       tape's label and	remove all associated tape and dump records from the
       Backup Database.

       The Tape	Coordinator's default response to this command is to access
       the first tape by invoking the "MOUNT" instruction in the
       CFG_device_name file, or	by prompting the backup	operator to insert the
       tape if there is	no "MOUNT" instruction.	 However, if the "AUTOQUERY
       NO" instruction appears in the CFG_device_name file, or if the issuer
       of the butc command included the	-noautoquery flag, the Tape
       Coordinator instead expects the tape to be in the device	already. If it
       is not, the Tape	Coordinator invokes the	"MOUNT"	instruction or prompts
       the operator. It	also invokes the "MOUNT" instruction or	prompts	for
       any additional tapes needed to complete the dump	operation; the issuer
       must arrange to provide them.

CAUTIONS
       If a dump operation is interrupted or fails for any reason, data	from
       all volumes written to tape before the interrupt	are valid can be used
       in a restore operation. The Backup Database includes an entry for the
       failed dump and for each	volume that was	successfully dumped. See the
       OpenAFS Administration Guide for	information on dealing with
       interrupted dumps.

       If dumping to tape rather than a	backup data file, it is	best to	use
       only compatible tape devices (ones that can read	the same type of
       tape).  Using compatible	devices	greatly	simplifies restore operations.
       The -portoffset argument	to the backup diskrestore and backup
       volsetrestore commands accepts multiple port offset numbers, but	the
       Backup System uses the first listed port	offset when restoring all full
       dumps, the second port offset when restoring all	level 1	dumps, and so
       on. At the very least, use compatible tape devices to perform dumps at
       each level. If compatible tape devices are not used, the	backup
       volrestore command must be used to restore one volume at	a time.

       Valid (unexpired) administrative	tokens must be available to the	backup
       command interpreter both	when it	reads the file named by	the -file
       argument	and when it runs each operation	listed in the file.
       Presumably, the issuer is scheduling dumps for times when no human
       operator	is present, and	so must	arrange	for valid tokens to be
       available on the	local machine. One option is to	issue all commands (or
       run all scripts)	on file	server machines	and use	the -localauth flag on
       the backup and vos commands. To protect against improper	access to the
       machine or the tokens, the machine must be physically secure (perhaps
       even more protected than	a Tape Coordinator machine monitored by	a
       human operator during operation). Also, if an unattended	dump requires
       multiple	tapes, the operator must properly configure a tape stacker or
       jukebox and the device configuration file.

       When the	command	is issued in regular (non-interactive) mode, the
       command shell prompt does not return until the dump operation
       completes. To avoid having to open additional connections, issue	the
       command in interactive mode, especially when including the -at argument
       to schedule dump	operations.

OPTIONS
       -volumeset <volume set name>
	   Names the volume set	to dump. The -dump argument must be provided
	   along with this one;	do not combine them with the -file argument.
	   If using a temporary	volume set, the	vos dump command must be
	   issued within the interactive session in which the backup addvolset
	   command was issued with the -temporary flag.

       -dump <dump level name>
	   Specifies the complete pathname of the dump level at	which to dump
	   the volume set. The -volumeset argument must	be provided along with
	   this	one; do	not combine them with the -file	argument.

       -portoffset <TC port offset>
	   Specifies the port offset number of the Tape	Coordinator handling
	   the tapes for this operation. It must be provided unless the
	   default value of 0 (zero) is	appropriate; do	not combine it with
	   the -file argument.

       -at <date/time to start dump>
	   Specifies the date and time in the future at	which to run the
	   command, or to read the file	named by the -file argument. Provide a
	   value in the	format mm/dd/yyyy [hh:MM], where the month (mm), day
	   (dd), and year (yyyy) are required. Valid values for	the year range
	   from	1970 to	2037; higher values are	not valid because the latest
	   possible date in the	standard UNIX representation is	in February
	   2038. The Backup System automatically reduces any later date	to the
	   maximum value.

	   The hour and	minutes	(hh:MM)	are optional, but if provided must be
	   in 24-hour format (for example, the value "14:36" represents	2:36
	   p.m.). If omitted, the time defaults	to midnight (00:00 hours).

	   As an example, the value 04/23/1999 20:20 schedules the command for
	   8:20	p.m. on	23 April 1999.

       -append
	   Appends the dump onto the end of a tape that	already	contains data
	   from	another	dump. However, if the tape is not in fact part of an
	   existing dump set, the Backup System	creates	a new dump set using
	   the parameters of this dump.	If the tape is not the last tape in
	   the dump set, the Tape Coordinator prompts for insertion of the
	   appropriate tape. Do	not combine this argument with the -file
	   argument.

       -n  Displays the	names of volumes to be included	in the indicated dump,
	   without actually performing the dump	operation. Do not combine this
	   argument with the -file argument.

       -file <load file>
	   Specifies the local disk or AFS pathname of a file containing
	   backup commands. The	Backup System reads the	file immediately, or
	   at the time specified by the	-at argument if	it is provided.	A
	   partial pathname is interpreted relative to the current working
	   directory.

	   Place each backup dump command on its own line in the indicated
	   file, using the same	syntax as for the command line,	but without
	   the word backup at the start	of the line. Each command must include
	   a value for the -volumeset and -dump	arguments, and for the
	   -portoffset argument	unless the default value of 0 is appropriate.
	   Commands in the file	can also include any of	the backup dump
	   command's optional options. In the following	example	file, the
	   first command runs as soon as the Backup System reads the file,
	   whereas the other commands are themselves scheduled;	the specified
	   date	and time must be later than the	date and time at which the
	   Backup System reads the file.

	      dump user	/sunday1/wednesday -port 1
	      dump sun4x_56 /sunday1/friday -port 2 -at	04/08/1999
	      dump sun4x_55 /sunday1/friday -port 2 -at	04/08/1999 02:00 -append

	   Do not combine this argument	with the -volumeset, -dump,
	   -portoffset,	-append, or -n options.

       -localauth
	   Constructs a	server ticket using a key from the local
	   /usr/local/etc/openafs/server/KeyFile file. The backup command
	   interpreter presents	it to the Backup Server, Volume	Server and VL
	   Server during mutual	authentication.	Do not combine this flag with
	   the -cell argument. For more	details, see backup(8).

       -cell <cell name>
	   Names the cell in which to run the command. Do not combine this
	   argument with the -localauth	flag. For more details,	see backup(8).

       -help
	   Prints the online help for this command. All	other valid options
	   are ignored.

OUTPUT
       The command interpreter first generates a list of the volumes to	be
       included	in the dump by matching	the entries in the volume set against
       the volumes listed in the Volume	Location Database (VLDB). It prints
       the list	following the header:

	  Preparing to dump the	following volumes:

       The following message then indicates that the command interpreter has
       passed the dump request to the appropriate Tape Coordinator for
       processing:

	  Starting dump.

       If the issuer includes the -n flag, the output is of the	following
       form:

	  Starting dump	of volume set '<volume set>' (dump set '<dump level>')
	  Total	number of volumes : <number dumped>
	  Would	have dumped the	following volumes:
	  <list_of_volumes>

       where list_of_volumes identifies	each volume by name and	volume ID
       number.

       If the Tape Coordinator is unable to access a volume, it	prints an
       error message in	its window and records the error in its	log and	error
       files.

EXAMPLES
       The following command dumps the volumes in the volume set called	"user"
       at the dump level "/full/sunday2/monday". The issuer places the
       necessary tapes in the device with port offset 5.

	  % backup dump	-volumeset user	-dump /full/sunday2/monday -portoffset 5
	  Preparing to dump the	following volumes:
	  user.jones.backup   387623900
	  user.pat.backup     486219245
	  user.smith.backup   597315841
		 .		  .
		 .		  .
	  Starting dump.

       The following command displays the list of volumes to be	dumped when
       the user	dumps the "sys_sun" volume set at the "/full" dump level.

	  % backup dump	-volumeset sys_sun -dump /full -n
	  Starting dump	of volume set 'sys_sun'	(dump set '/full')
	  Total	number of volumes: 24
	  Would	have dumped the	following volumes:
	  sun4x_56	124857238
	  sun4x_56.bin	124857241
	      .		   .
	      .		   .
	  sun4x_55	124857997
	      .		   .
	      .		   .

       The following command schedules a dump of the volumes in	the volume set
       "user" at the dump level	"/sunday2/monday1" for 11:00 p.m. on 14	June
       1999. The appropriate Tape Coordinator has port offset 0	(zero),	so
       that argument is	omitted.

	  % backup dump	-volumeset user	-dump /sunday2/monday1 -at 06/14/1999 23:00

PRIVILEGE REQUIRED
       The issuer must be listed in the	/usr/local/etc/openafs/server/UserList
       file on every machine where the Backup Server or	Volume Location	(VL)
       Server is running, and on every file server machine that	houses an
       affected	volume.	If the -localauth flag is included, the	issuer must
       instead be logged on to a server	machine	as the local superuser "root".

SEE ALSO
       butc(5),	backup(8), backup_adddump(8), backup_addvolentry(8),
       backup_addvolset(8), backup_diskrestore(8), backup_labeltape(8),
       backup_volrestore(8), butc(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			BACKUP_DUMP(8)

NAME | SYNOPSIS | DESCRIPTION | CAUTIONS | OPTIONS | OUTPUT | EXAMPLES | PRIVILEGE REQUIRED | SEE ALSO | COPYRIGHT

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

home | help