
	         Welcome to L.B.U, the Linux Backup Utility v1.10
		     by : Jonathan Warburton-Brown @ 1995
			     (jwb@uvo.dec.com)

	This is the complete L.B.U manual.

	PREFACE

	Ever since I first started using Linux (in 1991) I have been an 
	avid supporter of both it and the principles it upholds. I have 
	also wanted to put back into the great Internet pool some small 
	offering that would contribute to the Linux project. This is it. 

	Version 1.10 is the second incarnation of L.B.U. When I first 
	coded v1.00 it was done largely as an exercise to teach myself 
	shellscript programming but I received very favourable feedback 
	from people who have made use of it.  L.B.U is even being used 
	on at least one commercial site !!!  This feedback together with
	some great suggestions for improvements prompted me to make time 
	to code this version. Time is in short supply for me and this 
	release does not cover every suggestion I have received but it 
	does add more flexibility and usability to the utility.

	One of the enhancements requested by several people is the 
	ability to choose the 'backup engine' so that it could be either 
	tar (which it is now), cpio or afio. This would have taken more 
	time than is currently available to me, but I am thinking about 
	it for a future release. Sorry it didn't make it this time.
	
	A big thank you though to everyone who mailed me with ideas 
	(and praise as well :-) )...  THANK YOU !
	
	L.B.U does not make any attempt, at this stage, to be a full 
	or fool-proof backup solution. If you have a copy of this utility 
	it comes to you under the terms of the GNU GPL and you are free 
	to use/abuse it as you will. I take absolutely NO responsibility 
	for any consequences that arise from its use. If you make any 
	changes I would appreciate my name remaining in the credits for 
	it. After all it took me a lot of hard work to get it to where it 
	is today ;-).
	
	L.B.U is my very first attempt to put something together for use 
	in the Linux community and my first attempt at shell-script 
	programming so please don't laugh too hard. Mail is always fun to
	receive if you have any comments or suggestions or if you find some 
	use for this utility and besides, it lets me track L.B.U's 
	propagation around the globe 8-). If you do decide to mail me 
	could you include where you are from (ie geographically) because 
	its not always easy to guess from the mail address. Sadly I do not 
	always have time to respond to mail...  but it doesn't mean I 
	don't enjoy hearing from you !!
	
	I do re-iterate that this package (program, manuals, help-files 
	etc) has been put together in some haste. It seems to work okay 
	for me as far as I have tested it but never a truer saying was 
	coined than
        	'There is always at least one more bug'.
	
	There are surely bugs in the program, so let me know about them!!
	
	While I will consider seriously any suggestions for enhancements,
	I can only work on this in the spare time I find and can therefore 
	not guarantee to incorporate any changes or even release any 
	further versions. Time will tell.
	



	THIS RELEASE

     o There have been numerous tidy-ups in the code but I'll not bore
	you with the sordid details. The code is probably still a bit 
	ropy anyway since I'm still very much in the learning phase of 
	shell programming.

     o There are various flags that may be set at the top of the lbu
	script.

     o I have removed the restriction that only root could make backups. 
	L.B.U should now be pretty much mutli-user. One word of caution
	though no device/file locking is implemented which means two
	people could try to back up to the same file/device at the same
	time. This is mitigated somewhat by the fact that I have retained
	the code which disallows more than one L.B.U session to be running
	at once.

	Also, the Scheduling function is restricted to root. Whilst most
	of the code is in place for multi-user scheduling it does not work
	fully yet. Anyway, it seemed to me that users creating many
	schedules might not be a desirable thing !

	If this multi-user functionality presents a problem, I suggest for
	the moment, as system manager, that you limit L.B.U usage to root
	with permission masks and/or set the lbu_root_only flag to yes by
	editing the lbu script.

     o An oversight in version 1.00 was that the first letters of menu
	items were not unique. This has now been corrected and allows fast
	menu hopping. For example, on the main menu, to get to any item
	visible on the the screen there are three methods.

		o Use the arrow keys 
		o Use the plus (+) and minus (-) keys 
		o Type the first letter of the menu item

     o Device selection has been made a little more bullet-proof.
	Entering an asterisk (*) will now just throw you into the
	help-screen. Any spaces included (in error naturally) in the
	device name will be converted to a an underscore.

     o File/Directory selection has been made much more flexible and now
	caters for wild-carding. Note that if an item is entered without
	wild carding its validity is checked (ie does it exist). If
	wild-carding is used then checking for that item is not
	performed.

     o Under the Options sub-menu there is one additional item entitled
	Enable/Disable file exclusion. this switch activates/deactivates
	an exclusions file which L.B.U uses when performing its
	operations.  Please see the section on the Exclusion File for
	more information.

     o The date validation in the Scheduling sub-menu has been tightened
	up and now includes leap year checking.

     o There is a Compare facility which allows reporting of differences
	between a previously performed backup and the current
	file-system.

     o There is a Write function which saves the current configuration to
	disk. Details saved are :

		o Device selection 
		o File/Dir selection 
		o All options from the Options sub-menu

	If there is no save file ($HOME/.lburc) then, when invoked, L.B.U
	will proceed straight to the main menu. If however L.B.U finds a
	save file a loading screen is presented and when loading is
	complete (a few seconds) L.B.U proceeds to the main menu with the 
	previously saved selections already in force.

     o The ability to create/modify an exclusions file. This file may
	contain filenames (wild-carding allowed) which should be ignored
	by the backup. See the section on Exclusions for more
	information.

     o No credit for me here, but all credit to Savio Lam. I have
	included in the L.B.U v1.10 distribution version 0.5 of his
	smart dialog utility which allows L.B.U to look so pretty.
	Thanks Savio.




	L.B.U Usage

	By default L.B.U is kept in /usr/bin and is called lbu.

	Upon invocation, L.B.U attempts to ensure that no other L.B.U 
	backup is currently running or that the L.B.U script file is 
	being edited. It does this by grepping the process stack for 
	'lbu'. This check is primarily to minimise the risk that two 
	users backup to the same device at the same time. I did not have 
	time to put in file locking code (hopefully in the future). If 
	you do not consider this a risk, you can always disable the 
	relevant code in lbu. If you wish to limit the usage of lbu to 
	root then do so using file permissions or by setting the 
	lbu_root_only flag in the lbu script.. Doing the latter should 
	more or less eliminate the possibility of two backups to the same 
	devices assuming users with root privs know what they are all 
	doing 8-) Is life that perfect ????
	
	When L.B.U is started, if a user configuration has previously 
	been saved to disk, it is loaded and a loading screen is shown 
	with a running percentage completion figure. The user is then 
	presented with a screen showing the current directory, the current 
	date and the date of the last L.B.U action that was performed, 
	if indeed one has been, and its status. This screen is for 
	information purposes but it is important to realise that any actions 
	taken by L.B.U will be relative to the current directory. For 
	example, if doing a restore and absolute pathnames had not been 
	specified when the backup was performed, all files restored would 
	be placed relative to the current directory.
	
	The next screen presents the MAIN MENU.


	MAIN MENU

	Each item in the Main menu will be discussed in order of 
	appearance.

	Device Select bkup/rstr/cmpr device.

	This function defines the device which will be used for the 
	backup/restore/compare process. It is the device to which the 
	backup will be written or from which the restore/compare data will 
	be read. The Device menu selection will prompt the user for such 
	a  device. It may be a file, a block device (eg. /dev/fd0) or a 
	character special device such as a tapedrive (eg /dev/rmt0 or 
	/dev/st0). 

	
	NOTE there is nothing to stop you specifying /dev/hda 
	though take it from me, this would not be a sensible 
	thing to do. Specify regular files, floppy or tape 
	devices only unless you know what you are doing !!! 
	*************** YOU HAVE BEEN WARNED ***************
	

	If a regular file is selected, it will be given an extension 
	appropriate  to the compression mode selected. The default 
	compression mode is gzipped (extension = .tgz) but may be set to 
	Compress mode (extension = .tar.Z) or no compression (extension 
	= .tar). Compression will be discussed in more detail later. 

	IT IS THEREFORE NOT USUALLY NECESSARY TO SPECIFY A FILE 	
	EXTENSION

	NOTE: If a filename called backup.tgz is entered, L.B.U will use 
	a file  called backup.tgz.tgz (assuming default compression mode 
	is in force).

	If a filename that exists is specified, the user will be warned 
	that it  will be overwritten when the backup starts. If this is 
	not acceptable, the user may re-select the backup device.

	If a filename that does NOT exist is specified, the user will be 
	informed that it will be created. 

	NOTE: A RESTORE operation will fail if the filename does not exist.   

	In all cases. there MUST be a full path to the file selected. For 
	example, the file /usr/jwb/lbu/backup.tgz will only be valid if 
	/usr/jwb/lbu exists as a directory. 

	Directories, links and character special files will not be accepted 
	as backup devices. Attempting to select any of these will result 
	in an appropriate message. Also, selection of no device will abort 
	the process and throw the user back to the main menu.

	If a device has been successfully selected it is displayed on the 
	main menu as a reminder of the choice made.

	File/Dir Select data to bkup/rstr/cmpr. 

	This option specifies which files and or directories are to be 
	backed up, restored or compared. The user just has to enter the 
	full pathname for the  directories and/or files required for the 
	operation. For any directory that is specified ALL files in that 
	directory and any sub-directories  below it will be backed up.

	As of version 1.10 of L.B.U wildcarding is properly supported.

	Each entry in the list is comma (,) or space separated. List items 
	which contain wild-cards are not checked for validity but if a 
	directory or a discrete filename is specified, it will be checked. 
	If a specified file or directory is found not to exist an  
	informational message is provided. If doing a BACKUP specifying a 
	nonexistent file/directory will cause an error status to be 
	returned and shown on the Status screen when the backup is 
	completed This is despite the fact that all existing files and 
	directories specified WILL be backed up. For a RESTORE operation, 
	non-existent files and/or directories will not cause an error 
	status.

	IT IS ALWAYS ADVISABLE TO CHECK THE BKUP/RSTR/CMPR LOG 
	FOR MESSAGES. 

	This log file can optionally be automatically mailed to the user.

	Some examples of directory/file selection might be :

	/		 	for a full bkup/rstr/cmpr of all files on 
				the system.

	/use/bin/X11/*	 	bkup/rstr/cmpr just the /usr/bin/X11 files 

	/vmlinuz	 	just backup/restore the kernel

	/home,/temp 		bkup/rstr directories /home & /temp 

	If a selection has been successfully made a portion of it is 
	displayed on the Main Menu as a reminder of the choice.

	For RESTORE operations some consideration has to be made when 
	selecting directories/files. The specification of NO files or 
	directories is allowable and will cause ALL files in the backup 
	to be restored.

	If however the user specifies files or directories they require to 
	be EXACTLY as saved in the backup. This means that if absolute 
	pathnames were not preserved in the backup (ie the leading / was 
	removed) then  files/directories specified for the restore should 
	also not show an absolute path. If in doubt about the exact format 
	of the backup, use the Main Menu View option to look at the 
	contents of the backup.

	The same considerations apply to COMPARE operations.

	Options (Un)Set run-time option flags

	This menu item allows the user to set and unset options which will 
	affect the way the backup is performed. Each option will be 
	described below.

	Done 

	This concludes the (un)setting of options and returns the user to 
	the Main Menu.

	Multi 

	This option (un)sets the Multi-volume archive flag. When backing 
	up to or restoring from a removable media such as floppies / tapes 
	AND the backup is likely to span more than one unit of the 
	removable media, this option will allow the user to interactively 
	change the media when required and then continue with the backup/
	restore process.

	NOTE that the Multi-volume flag imposes some restrictions on the 		
	     backup/restore/compare process. These are as follows :

		1. They can ONLY be performed in foreground mode to 		
		   allow the user to interact with the process when media 		
		   changes are requested.					

		2. Multi-volume backups cannot have any compression
		   applied to them. This can considerably increase the
		   size of the backup archive.

	Because of the latter point, if the Multi-volume flag is set, the  		
	compression option is automatically unset.

	The following message is displayed to the user prior to L.B.U 
	performing a multi-volume backup or restore :

 		
		IMPORTANT INFORMATION. PLEASE READ CAREFULLY
		

		You have selected the 'MULTI-VOLUME' option for
		bkup/rstr/cmpr (found under Options menu item from the
		Main Menu). Because this will require interactive user
		intervention when media changes are required, it can ONLY
		be run in FOREGROUND mode rather than in
		BACKGROUND mode where media changes are not
		expected.

		When the bkup/rstr/cmpr process completes, you will be
		returned to the normal menu-ised L.B.U interface.

		Please also note the following :

		The 'MULTI-VOLUME' option is normally selected (under
		Linux) to back up system files and directories to the 
		floppy disk drive.
	
		There are two ways to backup to a floppy drive using 
		L.B.U.

		If the user selected /dev/fdn (where n = the floppy drive
		number e.g /dev/fd0) then L.B.U will write the tar archive
		DIRECTLY to the disk.

		NOTE: THIS IS NOT A FILESYSTEM AND CANNOT
		BE MOUNTED WITH THE UNIX MOUNT	
		COMMAND. IT IS NOT RECOMMENDED THAT
		YOU TRY THIS.

		The backup can later be restored using L.B.U and 
		specifying the SAME device specification (/dev/fdn) prior 
		to using the Restore Main Menu option.

		This is the CORRECT way to do a MULTI-VOLUME
		backup to a floppy.

		The other way to backup to a floppy is to mount the 
		floppy as a filesystem 

		( e.g mount -t ext2 /dev/fd0 /mnt )

		and then backup to that filesystem... ie to /mnt.

		This is fine if the backup will not occupy more than the 
		free space available on the floppy disk, in which case 
		you need not have specified MULTI-VOLUME anyway !!

	Absolute

	The Absolute flag ensures that the backup preserves absolute 		
	pathnames for files. If it is unset, then the leading / is removed 
	from the path so that any restore operation will restore files 
	relative to the directory from which the restore operation was 
	initiated.

	Mail

	If set a copy of the backup log file is mailed to the user

	Block 

	Allows a variety of blocksizes to be specified. The default is 
	quite acceptable in the majority of cases, but for backups to tape 
	other block sizes may be used.

	NOTE: If the default is changed, a note should be made of it 
	      because the same blocksize MUST be used for the restore
	      or compare operations.

	Perms

	If this option is set the files are backed up with their permission 
	masks intact and any restore operation will restore them with those
	permissions.

	Owner

	If this option is set the files are backed up with their original 
	ownership intact and any restore operation will restore them with  
	those ownerships.

	Totals

	If this option is set, a total archive byte-count will be 
	recorded at the end of the backup logfile.

	Verbose 

	With this option set, each file backed up will be recorded in 
	the  backup logfile. It is a sensible idea to leave this option 
	set.

	Compress

	This menu item will bring up a sub-menu allowing the user to 
	select the form of compression to be used. There are three 
	possible options for compression which are as follows :

		o  Gzipped. 	   This is the default and highest form of 
	    	   Extension=.tgz  compression. It is the most efficient 
				   and should normally be used.

		o Compress.	   This uses the compress command and is
	 	  Extension=.tar.Z included in case (for some reason) 
				   gzip is not available.

		3. None		   If the Multi-volume flag is set then 
	 	   Extension=.tar  no compression is permitted.

	NOTES: If the compression sub-menu is entered, the Multi-
	       volume option is automatically unset.

	       If you enter the Compress menu, a change in compression
	       mode is assumed and you will be required to re-enter 
	       the Device selection from the Main Menu so that an 
	       appropriate file extension can be included.

	Begin Start the backup procedure

	This Main menu function will actually start the backup. It is a  
	requirement that the Device and File/Dir selections be made 
	successfully  before the backup can be started.

	Under normal circumstances, upon selecting Begin there will be 
	a short pause and then the user will be returned to the Main 
	Menu. The backup has been started as a background job. This can 
	be proven by looking at the Status Screen which will indicate 
	that the backup is IN PROGRESS. Also, looking at the Backup log 
	will provide a running progress report on how far the backup has 
	proceeded assuming the verbose flag is set in the Options sub-menu 
	(default is that verbose is on).

	If, under the Options sub-menu, the Multi-volume option has been  
	selected the backup can only be run in foreground mode. In this  
	instance, selecting Begin will start the backup in foreground mode. 
	If the verbose flag is set the user will see the progress of the 
	backup echoed to screen. Only when the backup is complete will 
	the user be returned to the L.B.U menu system.

	Schedule Schedule a backup/restore for later 

	This facility is currently only available to root. Please note that 
	the discussion of scheduling below talks of both root and non-root 
	access but for now only root access is available.

	L.B.U allows the user to select all the parameters for a backup or 
	restore but then defer running the operation itself until a later 
	date/time. This  allows for a backup to be 'set up' during office 
	hours and run at two  o'clock the following morning for example 
	which is very useful in real  world environments.

	This facility is based round Vixie Cron or a functional equivalent.

	In order to provide this facility, L.B.U requires that a daemon 
	called crond be running.

	If L.B.U does not detect the crond process running on the system 
	it do one of two things. If the user is root L.B.U will warn the 
	user and attempt to start crond. A status message will be given  
	regarding the startup being successful or not.

	If not root the user will be requested to contact the system 
	administrator who should start the crond daemon.

	Similarly, if a user crontab file is not found for the user one 
	of two things will happen. If the user is root one will be 
	created and will have the 'atrun' command automatically inserted. 
	L.B.U  scheduling is driven by the 'at' command which in turn 
	is driven by atrun  which is driven by crontab which is read by 
	crond. Logical really ;-)

	If not root the user will be requested to contact the system 
	administrator who should set up a crontab file.

	Otherwise, once having selected the Back or Rest sub-menu option, 
	the user will be asked to enter date and time details about when 
	the backup or restore is to proceed. Then, after the date has 
	been validated, an appropriate entry will be will be formatted 
	and passed to 'at' (the Unix scheduling command). When the 	
	scheduled job has been  successfully submitted, the user will 
	be given a JOB NUMBER.

	IT IS IMPORTANT TO KEEP A NOTE OF THIS NUMBER IN CASE 
	THE SCHEDULED JOB REQUIRES TO BE DELETED LATER. IF THE 
	JOB NUMBER IS LOST THE JOB WILL HAVE TO BE MANUALLY 	
	REMOVED FROM THE AT QUEUE (This can be done  using the atq and 
	atrm commands).

	The L.B.U Status Screen will be updated to show the latest 
	submitted JOB NUMBER and when the scheduled backup is due to run.

	Date entry format

	The date entry requires a fixed format which is outlined below :

		HH:MM DD Mn YYYY

	Where :
	
		HH   = Hours (valid range = 00 - 23)
		MM   = Minutes (valid range = 00 - 59)
		DD   = Day (valid range = 01 - max days in month)
		Mn   = Month (valid range = 01 - 12)
		YYYY = Year (valid range = current year - current year+1)



	Other options under the Schedule sub-menu are Clear, Help and Done.

	The Clear option is used to delete a previously scheduled backup 
	or restore operation. The user will be requested to enter the job 
	number to delete. A check will be performed to ensure the job 
	number entered relates to an L.B.U  schedule. If it does the 
	schedule will be deleted. The Status Screen  will be amended to 
	show that the schedule was deleted. 

	 Restore Restore Previous Backup

	This is much the reverse of a backup. It allows a previous backup 
	or files from a previous backup to be restored to the system. 
	Specifying no file or directory information in the File/Dir Main 
	Menu function will cause all files to be restored from the 
	backup. Specifying files and/or directories will restore only 
	those which match the selection criteria.

	Look Look at the Status Screen 

	The Status Screen is one of the first screen the user sees when 
	entering L.B.U.

	It is periodically updated by actions performed by the user 
	within L.B.U and therefore a Main Menu option exists to view it 
	without having to exit and re-enter L.B.U.

	NOTE: The Status Screen is an INDICATOR of how things appear and 
	not a definitive authority. As an example, if the user performs a 
	backup having specified in the File/Dir selection : 

		/var/spool,/gobbledigook,/temp

	and /var/spool and /temp exist but /gobbledigook does not, L.B.U 
	will successfully back up all the existing files and directories 
	specified ignoring any specification which does not exist. The 
	Status Screen  however will say the backup FAILED. Only inspecting 
	the log file will provide a definitive answer.

	Compare Check for differences between backup and file-system

	The Compare function looks at files contained within the currently 
	selected backup file or device and compares then with the same 
	files on the system. Any differences are reported to the log file.

	Inspect Look at the latest backup/restore log 

	This function allows the user to look at the log of the latest 
	backup, restore or compare operation performed. This can also be 
	inspected while the operation is in underway to obtain a progress 
	report.

	View View the contents of a previous backup.

	This function simply produces a listing of the contents of the 
	currently selected backup file or device.						

	It allows the user to list the contents of the actual backup file. 
	Because the log file is transitory and will be overwritten next 
	time any backup or restore is performed, the View option is 
	present to allow inspection of old backup files. 


	Write Save currently selected details to disk  

	This option will write all the saveable configuration details 
	to disk. These details include :

		Device selection							
		File/Dir selection							
		All options from the Options sub-menu.

	Once saved, when L.B.U is invoked, it will load these details and 
	use then as start-up default values.

	Exclude Create/Modify an exclusion list

	An exclusion list allows the user to say backup up all these files 
	EXCEPT those listed in the exclusions file. It is however not 
	quite that straight-forward. Firstly, bear in mind that L.B.U 
	performs no checking on the format of the exclusions file.

	L.B.U will try to invoke the editor specified in the environment 
	variable $EDITOR. If $EDITOR is not defined then vi will be used 
	as a default.

	The format for the file is one entry per line where an entry is a 
	fully or partially qualified filename. The filename may include 
	wild-cards.

	If the exclusions file contains an entry *.o and the File/Dir 
	selection specifies just a directory ( eg / ) then every file 
	in / and all its sub directories will be backed up with the 
	exception of any files with extension .o. If however the File/Dir 
	selection was /* then all the .o files would be backed up despite 
	the exclusion file because the File/Dir selection overrides the 
	exclusion list.

	If you set up an exclusion list and it is not behaving as expected 
	it is probably due to:

		o  the File/Dir selection overriding the exclusion				
		o  An error in the exclusion list					
		o  The Enable/Disable file exclusion flag (under Options) 
		   being set to no

	It is probably best that you experiment with the exclusion list to 
	get it working right for you. 

	Help Help regarding L.B.U 

	Allows the user to view help text. There are Help Screens on 
	sub-menus as well with help relevant to those functions found 
	under the menu in question. Additionally, help can be obtained by 
	entering a question mark (?) wherever user input is required in 
	an input field.

	Quit Quit the Linux Backup Utility 

	This will take the user out of L.B.U and return control to the 
	parent shell.

	If a backup or restore operation has been started (in background) 
	or has been scheduled to run later, it it quite okay for the user 
	to quit the L.B.U utility and/or even log off the system.

