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

FreeBSD Manual Pages


home | help
fbackup(1M)							   fbackup(1M)

       fbackup - selectively back up files

       device device] ...  path] path] graph] path] path] path]	config]

       device device] ...  restart] path] path]	path] config]

       combines	 features of and to provide a flexible,	high-speed file	system
       backup mechanism	(see dump(1M)  and  ftio(1)).	selectively  transfers
       files  to an output device.  For	each file transferred, the file's con-
       tents and all the relevant information necessary	to restore  it	to  an
       equivalent  state  are  copied to the output device.  The output	device
       can be a	raw magnetic tape drive	(for example, a	DLT tape  drive),  the
       standard	output,	a rewritable magneto-optical disk, or a	file.

       The  selection  of  files  to  back up is done by explicitly specifying
       trees of	files to be included or	excluded from an  session.   The  user
       can  construct  an  arbitrary graph of files by using the or options on
       the command line, or by using the option	with a graph file.  For	 back-
       ups being done on a regular basis, the option provides an easier	inter-
       face for	controlling the	backup graph.  selects files  in  this	graph,
       and  attempts  to  transfer them	to the output device.  The selectivity
       depends on the mode (full or incremental) in which is being used.

       When doing full backups,	all files in the graph are selected.  When do-
       ing  incremental	 backups, only files in	the graph that have been modi-
       fied since a previous backup of that graph are selected.	 If an	incre-
       mental  backup  is  being  done	at level 4 and the option is used, the
       database	file is	searched for the most recent previous backup at	levels
       0-3.   If  a  file's modification time is before	the time when the last
       appropriate session began and the i-node	change time is before the time
       that  same  session  ended, the file is not backed up.  All directories
       lying on	the path to a file that	qualifies for the  incremental	backup
       will  also be on	the backup media, even if the directories do not qual-
       ify on their own	status.

       If is used for incremental backups, a database of past backups must  be
       kept.   maintains this data in the text file by default.	 Note that the
       directory must be created prior to the first time is used for incremen-
       tal  backups.   The option can be used to specify an alternate database
       file.  The user can specify to update this file when  an	 session  com-
       pletes successfully.  Entries for each session are recorded on separate
       pairs of	lines.	The following four items appear	on the first  line  of
       each pair: the graph file name, backup level, starting time, and	ending
       time (both in time(2) format).  The second line of each	pair  contains
       the  same  two  times, but in strftime(3C) format.  These lines contain
       the local equivalent of the start time, the local equivalent of and the
       ending time.  These second lines	serve only to make the dates file more
       readable; does not use them.  All fields	are separated by white	space.
       Graph  file names are compared character-by-character when checking the
       previous-backup database	file to	ascertain when a previous session  was
       run  for	that graph.  Caution must be exercised to ensure that, for ex-
       ample, and are not used to specify the same graph file  because	treats
       them as two different graph files.

       The  general structure of an volume is the same,	no matter what type of
       device is used.	There are some small specific differences due to  dif-
       fering capabilities of devices.	The general structure is as follows:

	      o	 reserved space	for ASCII tape label (1024 bytes)
	      o	 volume	header (2048 bytes)
	      o	 session index (size in	field of volume	header)
	      o	 data

       Each  file entry	in the index contains the file size, the volume	number
       and the pathname	of the file.  At the beginning of  every  volume,  as-
       sumes  that all files not already backed	up will	fit on that volume, an
       erroneous assumption for	all but	the last volume.  Indices are accurate
       only for	the previous volumes in	the same set.  Hence, the index	on the
       last volume may indicate	that a file resides on that volume, but	it may
       not  have actually been backed up (for example, if it was removed after
       the index was created, but before attempted to back it up).   The  only
       index  guaranteed  to  be correct in all	cases is the on-line index op-
       tion), which is produced	after the last volume has been written.

       Specific	differences in the structure of	volumes	are listed below:

	      o	 When using magnetic tape devices, the main blocks of informa-
		 tion  (tape  label, volume header, index, data) are separated
		 by EOF	marks.	also checkpoints the media periodically	to en-
		 hance error recovery.	If a write error is detected, the user
		 normally has two options: (1) a new volume can	be mounted and
		 that volume rewritten from the	beginning; or, (2) if the vol-
		 ume is	not too	severely damaged, the good data	before the er-
		 ror  can be saved, and	the write error	is treated as a	normal
		 end-of-media condition.  The blocks of	data with their	check-
		 point	records	are also separated by EOF marks.  In addition,
		 for DDS tape drives, if are supported,	these will be used  to
		 enhance  selective  recovery  speed  by  placing them between
		 blocks	of files.  Similarly on	DLT tape drives, faster	selec-
		 tive recovery is achieved using the EOF marks used for	check-
		 pointing in conjunction with the file sizes given in the  in-

	      o	 For  a	 magneto-optical  device,  a disk, a file, or standard
		 output, there are no special marks separating the information
		 pieces; the backup is always a	single file (volume).

       provides	the ability to use UCB-mode tape drives.  This makes it	possi-
       ble to overlap the tape rewind times if two or  more  tape  drives  are
       connected to the	system.

       There are several things	the user will want to consider when setting up
       for regular use.	 These include type of device and media,  full	versus
       incremental  frequency,	amount of logging information to keep on-line,
       structure of the	graph file, and	on-line	versus off-line	backup.

       The type	of device used for backups can affect such things as media ex-
       penses, ability to do unattended	backups, and speed of the backup.  Us-
       ing 36-track tapes will probably	result in the highest performance, but
       require	user  intervention  for	 changing tapes.  Both DLT and DDS au-
       tochangers and libraries	can provide unattended backups.	 A magneto-op-
       tical  autochanger  can	also  provide an unattended backup for a large
       system and long life media, however the media cost is high.  Lower cost
       and  good performance can be achieved with a single DLT tape drive, but
       multi-volume backups must be attended.

       It is also important to consider	how often full backups should be made,
       and  how	 many  incremental backups to make between full	backups.  Time
       periods can be used, such as a full backup every	Friday	and  incremen-
       tals  on	 all  other days.  Media capacities can	be used	if incremental
       backups need to run  unattended.	  The  availability  of	 personnel  to
       change  media  can also be an important factor as well as the length of
       time needed for the backup.  Other factors may affect the need for full
       and  incremental	 backup	 combinations such as contractual or legal re-

       If backup information (output from the or options) is kept on-line, the
       required	 storage  space	must also be considered.  Index	file sizes are
       hard to predict in advance because they depend on system	configuration.
       Each volume header file takes less than 1536 bytes.  Of course the more
       information that	is kept	on-line, the faster locating  a	 backup	 media
       for a recovery will be.

       There  are  several ways	to structure the graph file or files used in a
       system backup.  The first decision involves whether to use one or  more
       than  one  graph	 file  for the backup.	Using one file is simpler, but
       less flexible.  Using two or  more  graph  files	 simplifies  splitting
       backups into logical sets.  For example,	one graph file can be used for
       system disks where changes tend to be less frequent, and	another	 graph
       file  for  the  users  area.  Thus two different	policies can be	imple-
       mented for full and incremental backups.

       was designed to allow backups while the system is in use	 by  providing
       the capability to retry an active file.	When absolute consistency on a
       full backup is important, the system should probably be in  single-user
       mode.   However,	incremental backups can	be made	while the system is in
       normal use, thus	improving system up-time.

       config	      is the name of the configuration file, and  can  contain
		      values for the following parameters:

			 o  Number of 1024-byte	blocks per record.
			 o  Number of records of shared	memory to allocate.
			 o  Number  of records between checkpoints.  Since the
			    EOF	marks between checkpoints are  also  used  for
			    fast  searching  on	 DLT tape drives, changing the
			    checkpoint frequency may also affect selective re-
			    covery speed (see WARNINGS section).
			 o  Number of file-reader processes.
			 o  Maximum  number  of	 times	is  to retry an	active
			 o  Maximum number of bytes  of	 media	to  use	 while
			    retrying the backup	of an active file.
			 o  Maximum number of times a magnetic tape volume can
			    be used.
			 o  Name of a file to be executed when a volume	change
			    occurs.  This file must exist and be executable.
			 o  Name  of  a	file to	be executed when a fatal error
			    occurs.  This file must exist and be executable.
			 o  The	number of files	between	the on DDS tapes.  The
			    cost  of  these  marks  are	negligible in terms of
			    space on the DDS tape.  Not	all DDS	 tape  devices

		      Each  entry  in  the  configuration file consists	of one
		      line of text in the following format: identifier,	 white
		      space,  argument.	 In the	following sample configuration
		      file, the	number of blocks per record is set to 16;  the
		      number of	shared memory records is set to	16; the	check-
		      point frequency is set to	256; the number	of file	reader
		      processes	 is set	to 2; the maximum number of retries of
		      an active	file is	set to 5; the maximum retry space  for
		      active files is set to 5,000,000 bytes; the maximum num-
		      ber of times a magnetic tape volume can be used  is  set
		      to 100; the file to be executed at volume	change time is
		      the file to be executed when a fatal error occurs	is and
		      the number of files between on DDS tapes is set to 200.

			   blocksperrecord   16
			   records	     16
			   checkpointfreq    256
			   readerprocesses   2 (maximum	of 6)
			   maxretries	     5
			   retrylimit	     5000000
			   maxvoluses	     100
			   chgvol	     /var/adm/fbackupfiles/chgvol
			   error	     /var/adm/fbackupfiles/error
			   filesperfsm	     200

		      Each  value listed is also the default value, except and
		      which default to null values.

       This specifies a	path to	a database for use with	incremental backups.
		      It overrides the default database	file

       path	      specifies	a tree to be excluded from the	backup	graph.
		      This tree	must be	a subtree of part of the backup	graph.
		      Otherwise, specifying it will not	exclude	any files from
		      the  graph.  There is no limit on	how many times the op-
		      tion can be specified.

       device	      specifies	the name of an output file.  If	 the  name  of
		      the  file	is writes to the standard output.  There is no
		      default output file; at least one	must be	specified.  If
		      more  than  one  output file is specified, uses each one
		      successively and then repeats  in	 a  cyclical  pattern.
		      Patterns	can be used in the device name in a manner re-
		      sembling file name expansion as done by the  shell  (see
		      sh(1)  and  other	 shell	manual entries).  The patterns
		      must be protected	from expansion by the shell by quoting
		      them.   The  expansion  of  the  pattern	results	in all
		      matching names being in the list of devices used.

		      There is slightly	different behavior if  remote  devices
		      are  used.  A device on the remote machine can be	speci-
		      fied in the form creates a server	process	 from  on  the
		      remote  machine  to access the tape device.  If does not
		      exist on the remote system,  creates  a  server  process
		      from  on	the  remote machine to access the tape device.
		      Only magnetic tapes can be remote	devices.  When	remote
		      DDS tape devices are used, the capability	is not used.

       graph	      defines  the  graph file.	 The graph file	is a text file
		      containing the list of file names	of  trees  to  be  in-
		      cluded  or  excluded from	the backup graph.  These trees
		      are interpreted in the same  manner  as  when  they  are
		      specified	with the and options.  Graph file entries con-
		      sist of a	line beginning	with  either  or  followed  by
		      white  space,  and  then the path	name of	a tree.	 Lines
		      not beginning with or are	treated	as an error.  There is
		      no  default  graph file.	For example, to	back up	all of
		      except for the subtree a file could be created with  the
		      following	two records:

       path	      specifies	 a  tree  to  be included in the backup	graph.
		      There is no limit	on how many times the  option  can  be

       Cross	      NFS  mount points.  By default, does not cross NFS mount
		      points, regardless of paths specified by the or options.

       Includes	LOFS files specified by	the backup graph.
		      By default, does not cross LOFS  mount  points.	If  is
		      specified, and the backup	graph includes files which are
		      also in an LOFS directory	that is	in the	backup	graph,
		      then those files will be backed up twice.

       Back up the object that a symbolic link refers to.
		      The default behavior is to back up the symbolic link.

       Update the database of past backups
		      so  that	it  contains the backup	level, the time	of the
		      beginning	and end	of the session,	 and  the  graph  file
		      used  for	 this session.	For this update	to take	place,
		      the following conditions must exist: Neither the nor the
		      option can be used; the option must be specified exactly
		      once (see	below);	the must complete successfully.

       Run in verbose mode.
		      Generates	status messages	that are otherwise not seen.

       Automatically answer
		      to any inquiries.

       Do not back up optional entries of access control lists
		      (ACLs) for files.	 Normally,  all	 mode  information  is
		      backed  up including the optional	ACL entries.  With the
		      option, the summary mode information (as returned	by  is
		      backed up.  Use this option when backing up files	from a
		      system that contains ACLs	to be recovered	 on  a	system
		      that does	not understand ACLs (see acl(5)).

       Do not back up extent attributes.
		      Normally,	 all  extent attributes	that have been set are
		      included with the	file.  This  option  only  applies  to
		      file systems which support extent	attributes.

       path	      specifies	 the name of the on-line index file to be gen-
		      erated.  It consists of one line for each	file backed up
		      during  the  session.  Each line contains	the file size,
		      the volume number	on which that file  resides,  and  the
		      file  name.   If the option is omitted, no index file is

       The volume header information is	written	to
		      path at the end of a successful session.	The  following
		      fields  from  the	 header	are written in the format with
		      one pair per line.

		      On a valid	     media it contains the value  (HP-
					     UX	 release  10.20	 and  beyond).
					     Before HP-UX  release  10.20,  it
					     contained the value
		      This field contains the result of
		      This field contains the result of
		      This field contains the result of
		      This field contains the result of
		      This field contains the result of
					     (see cuserid(3S)).
		      This  field  contains  the  maximum length in bytes of a
		      data record.
		      This field contains the clock time when
					     was started.
		      This field contains the number of	times
					     the  media	 has  been  used   for
					     backup.  Since the	information is
					     actually on the media, this field
					     will always contain the value 0.
		      This field contains a  character	followed  by 3 digits,
					     and identifies the	number of vol-
					     umes in the backup.
		      This  field  contains the	number of data records between
		      This field contains the size of the index.
		      This field is composed of	two items: the process
					     ID	(pid) and the  start  time  of
					     that process.
		      This  field  contains  the  language  used  to  make the

       Restart an     session from where it was	previously  interrupted.   The
		      restart  file  contains all the information necessary to
		      restart the interrupted session.	None  of  the  options
		      can be used together with	the restart option.

       This single-digit number	is the backup level.
		      Level indicates a	full backup.  Higher levels are	gener-
		      ally used	to perform incremental backups.	 When doing an
		      incremental backup of a particular graph at a particular
		      level, the database of past backups is searched to  find
		      the  date	 of  the  most recent backup of	the same graph
		      that was done at a lower level.  If  no  such  entry  is
		      found,  the  beginning of	time is	assumed.  All files in
		      the graph	that have been modified	since  this  date  are
		      backed up.

   Access Control Lists	(ACLs)
       If  a  file  has	optional ACL entries, the option is required to	enable
       its recovery on a system	where the ACL capability is not	present.

   Environment Variables
       determines the order in which files are stored on the backup device and
       the order of output by the option.

       determines the format and contents of date and time strings.

       determines the language in which	messages are displayed.

       If and are not all specified in the environment,	or if either is	set to
       the empty string, the value of is used as a default for	each  unspeci-
       fied  or	 empty	variable.   If is not specified	or is set to the empty
       string, a default of "C"	(see lang(5)) is used instead of If any	inter-
       nationalization variable	contains an invalid setting, behaves as	if all
       internationalization variables are set to "C".  See environ(5).

   International Code Set Support
       Single- and multi-byte character	code sets are supported.

       returns one of the following values:

       upon normal completion.

       if it is	interrupted but	allowed
	  to save its state for	possible restart.

       if any error conditions
	  prevent the session from completing.

       if any warning conditions are encountered.

       If warnings occur, the operator should check the	fbackup	logs to	verify
       the sanity of the backup.

       In  the	following two examples,	assume the graph of interest specifies
       all of except (as described for the option above).

       The first example is a simple case where	a full backup is done but  the
       database	file is	not updated.  This can be invoked as follows:

       The  second  example is more complicated, and assumes the user wants to
       maintain	a database of past sessions so that  incremental  backups  are

       If sufficient on-line storage is	available, it may be desirable to keep
       several of the most recent index	files on disk.	 This  eliminates  the
       need  to	 recover  the  index from the backup media to determine	if the
       files to	be recovered are on that set.  One method of  maintaining  on-
       line  index  files is outlined below.  The system administrator must do
       the following once before is run	for the	first time (creating  interme-
       diate level directories where necessary):

	      o	 Create	a suitable configuration file called in	the directory

	      o	 Create	a graph	file called in the directory

	      o	 Create	a directory called in the directory

       A  shell	script that performs the following tasks could be run for each

	      o	 Build an index	file path name based on	both  the  graph  file
		 used (passed as a parameter to	the script) and	the start time
		 of the	session	(obtained from the system).  For example:

		      (for Nov 28, 1987	at 3:17	PM)

	      o	 Invoke	with this path name as its index file name.  For exam-

       When  the  session  completes  successfully, the	index is automatically
       placed in the proper location.

       consists	of multiple executable objects,	all of which are  expected  to
       reside in directory

       does  not  require  special  privileges.	 However, if the user does not
       have access to a	given file, the	file is	not backed up.

       For security reasons, configuration files and the and executable	 files
       should only be writable by their	owners.

       With  release  10.20, HP-UX supports large files	(greater than 2GB) and
       increased UID/GIDs (greater than	60,000).   Archives  containing	 files
       with  these  attributes	would cause severe problems on systems that do
       not support the increased sizes.	 For this reason, creates tapes	with a
       new  magic  number ("FBACKUP_LABEL").  This prevents tape archives from
       being restored on pre-10.20 HP-UX systems.  still reads both tape  for-
       mats  so	 that  tape archives created on	pre-10.20 HP-UX	systems	can be

       EOF marks are used for checkpointing on all magnetic tape devices.   On
       DLT tape	devices, these EOF marks are also used for fast	searching on a
       selective recovery; "fast searching" in this case means spacing to  the
       nearest	checkpoint before the desired file, and	then reading until the
       file is found.  With this dual purpose for checkpoints, caution	should
       be used when changing the checkpoint frequency parameter.

       Starting	with HP-UX Release 8.0,	does not back up network special files
       because RFA networking is obsolete.  A warning message is issued	 if  a
       network special file is encountered in the backup graph and the file is

       The use of for backing up NFS mounted file systems is not guaranteed to
       work  as	 expected if the backup	is done	as a privileged	user.  This is
       due to the manner in which NFS handles privileged-user access  by  map-
       ping  user and uid to user usually uid thus disallowing root privileges
       on the remote system to a root user on the local	system.

       The utility set comprised of and	was originally	designed  for  use  on
       systems	equipped  with not more	than one gigabyte of total file	system
       storage.	 Although the utilities	have no	programming  limitations  that
       restrict	 users	to  this size, complete	backups	and recoveries of sub-
       stantially larger systems can cause a large amount of  system  activity
       due  to the amount of virtual memory (swap space) used to store the in-
       dices.  Users who want to use these utilities, but  are	noticing  poor
       system-wide  performance	 due to	the size of the	backup,	are encouraged
       to back up their	systems	in multiple smaller sessions, rather than  at-
       tempting	to back	up the entire system at	one time.

       Due to present file-system limitations, files whose inode data, but not
       their contents, are modified while a backup is  in  progress  might  be
       omitted from the	next incremental backup	of the same graph.  Also, does
       not reset the inode change times	of files to their original values.

       should not be used with no-rewind devices, for example,

       allocates resources that	are not	returned to the	system if it is	killed
       in an ungraceful	manner.	 If it is necessary to kill send it a not a

       If  sparse  files  are backed up	without	using data compression,	a very
       large amount of media can be consumed.

       creates volumes with a format that makes	duplication of volumes by  im-
       possible	 (see  dd(1)).	Copying	an volume created on one media type to
       another media type does not produce a valid volume on the new media be-
       cause  the  formats of volumes on raw magnetic tape, on a regular file,
       and on rewritable optical disks are not identical.

       When configuring	the parameter (see option), the	record size is limited
       by the maximum allowed for the tape drive.  Common record sizes include
       128 blocks for DLT and DDS tape drives, and 60 blocks for  the  HP7980.
       Note  also that the blocksize used in earlier releases (7.0 and before)
       was 512 bytes, whereas it is now	1024 bytes.  This means	that the  same
       value specified in blocksperrecord in an	earlier	release	creates	blocks
       twice their earlier  size  in  the  current  release;  for  example,  a
       blocksperrecord parameter of 32 would create 16-Kbyte blocks at Release
       7.0, but	now creates 32-Kbyte blocks.  If blocksperrecord  exceeds  the
       byte count allowed by the tape drive, the tape drive rejects the	write,
       causing an error	to be communicated to which interprets as a bad	 tape.
       The resulting write error message resembles the following:


       Access  control lists of	networked files	are summarized (as returned in
       by but not copied to the	new file (see stat(2)).

       does not	support	QIC-120	and QIC-150 formats on QIC devices.  If	is at-
       tempted for these formats, fails	and the	following message is displayed

       was developed by	HP.

       database	of past	backups

       cpio(1),	 ftio(1),  dump(1M),   frecover(1M),   restore(1M),   rmt(1M),
       stat(2),	acl(5),	mt(7).



Want to link to this manual page? Use this URL:

home | help