SPIFFA DOCUMENTATION
Save Precious Information For Future Access - A spiffing program!
A Linux
backup and restore
application
By David M. Balean
linprogs at balean dot net
linprogs at balean dot net
Introduction
The
purpose of spiffa is
to back up and restore selected computer data locally to a directory
either on a
second internal disk drive or an external disk drive such as a Maxtor
external 300 G USB hard drive. It is not designed to be used
over a network or directly to a device. There are many
programs available
for this; try clicking HERE
to see a rather confusing selection of backup programs. I
couldn't find exactly what I was looking for so here is spiffa.
It includes the following:-
- Can be used by an ordinary user if root gives permission.
- Can be used with or without a graphical user interface (GTK 2).
- Does in fact perform the backup or restore. Surprisingly many programs don't!
- Can update (i.e. incremental backup) an existing backup.
- If the GUI is used it gives the user an indication of what is happening.
- Can be used with cron and similar scheduling daemons.
- The backup can be viewed easily, retaining a representation of the original tree.
- Files may be compressed (gzip, bzip2 or both).
- Configurable from the GUI or manually.
- GUI has numerous tooltips to help the user.
- Added the ability to restore a selection from a backup for version 1.3 (GUI only).
This
program prohibits backing up /proc, /sys and
the directory that is the destination of the backup, any of which
could lead to disaster. It can back up to a directory on the
the same drive as the
data but this is probably inadvisable because if that disk fails the
backup is probably not recoverable.
Installing
First cd to the directory containing the .tar.gz file then extract the compressed tar file with something like:-
[david@octopus ~]$ tarzx spiffa-1.3.tar.gz
or
[david@octopus ~]$ tar xvzf spiffa-1.3.tar.gz
Note that I have the following added into my .bashrc file:-
This has been very useful over the years since I first came across the
idea. The command should result in a directory containing the
uncompressed version. The following assumes that the base for installing spiffa is /usr/local.
Now change to the top directory:-
[david@octopus ~]$ cd spiffa-1.3
then:-
[david@octopus ~]$ ./configure
Now either use a direct install or an rpm install.
A Direct Install...
After ./configure as per the above:-
[david@octopus ~]$ make
To perform the actual install you have to be root so use the su command mentioned above then:-
[david@octopus ~]# make install
To uninstall it is also necessary to be root:-
[david@octopus ~]# make uninstall
That should be all there is to it but included in the distribution is autogen.sh if it is necessary to experiment. If so, read up about the Gnu Build Tools first! Here are a few:-
Useful Packaging Links
Maximum RPM
Using Automake and Autoconf with C+
GNU Autoconf Automake and Libtool
Introduction to GNU Build Tools
A search with google reveals numerous other helpful sites.
An RPM Install...
After ./configure as per the above, first make a new copy of spiffa-1.3.tar.gz.
[david@octopus ~]$ make dist
This will create a copy of spiffa-1.3.tar.gz in the spiffa-1.3 (i.e. top) directory.
Now become root using the su command mentioned above then to create the rpm:-
[david@octopus ~]# make rpm
This creates an rpm file of which the full pathname will be something like /usr/src/redhat/RPMS/i386/spiffa-1.3-1.i386.rpm depending on how the system is arranged. It will also create debuginfo in the same directory and an srpm file in the appropriate SRPMS directory. To install the rpm file first cd to its directory:-
[david@octopus ~]# cd /usr/src/redhat/RPMS/i386
Make sure that you are still root!
Now to install spiffa issue the following command:-
[david@octopus i386]# rpm -ivh spiffa-1.3-1.i386.rpm
OR if an older version is already installed:-
[david@octopus i386]# rpm -Uvh spiffa-1.3-1.i386.rpm
To remove it again, as root issue the following command:-
[david@octopus ~]# rpm -e spiffa
Simpler method of creating the rpm
An alternative method for creating the rpm file is to change directories to the directory containing the downloaded file spiffa-1.3.tar.gz. Then, as root, issue the following command:-
[david@octopus spiffa-1.3]# rpmbuild -ta spiffa-1.3.tar.gz
The disadvantage is that it is only possible to install to /usr/local, the default directory. See the next section.
Install to a different directory
For a direct install the appropriate information will have to be passed to configure, for example:-
[david@octopus spiffa-1.3]$ ./configure --bindir=/ --datadir=/usr/share --sysconfdir=/etc --localstatedir=/var --mandir=/usr/share/man
For an rpm type of install it is necessary to modify the file spiffa.spec in the top directory prior to using the command make rpm. To obtain a similar result to above change the appropriate lines to:-
Prefix: /
%define bindir %{prefix}/bin
%define datadir %{prefix}/usr/share
%define sysconfdir %{prefix}/etc
%define localstatedir %{prefix}/var
%define mandir %{prefix}/usr/share/man
This places everything into the places normally used by Fedora Core and Red Hat Linux. However, normally files and programs that are not part of a distribution are placed in /usr/local. The distribution contains the file spiffa.specX for a Fedora istall and the names of this file and spiffa.spec can be swapped to make life easier.
Description of GUI
To start spiffa with the GUI, enter the command spiffa alone at the command line:-
[david@octopus ~]$ spiffa
Initially an ordinary user, i.e. a user other than root, won't have permission to use spiffa. An attempt to run spiffa results in a small window telling the user to start spiffa as root.
Permission denied!
Here, the configuration file is probably missing. It hasn't been written yet! If the file was invalid the user is similarly informed.
Permission denied!
Here, the configuration file was read in and user "david" isn't in the users list.
Also, only one instance of spiffa is allowed to run at a time. An attempt to run a second copy results in a similar informative window.
Already running!
Another problem that is possible on startup is that spiffa may not be able to allocate a message queue in which case a similar small window will appear to inform the user. The easiest way to rectify this is to reboot the computer but it is possible to examine the message queues with:-
[david@octopus ~]$ ipcs -q
and remove queue ids with
[david@octopus ~]$ ipcrm -q ###
where ### is the queue id. Check out the ipcs and ipcrm manpages for more details. Hopefully this is a rare occurence but it is as well to understand what can happen.
So the best plan is to start spiffa as the root user, i.e. the superuser.
In order to become the root user:-
[david@octopus ~]$ su
Password: (enter root's pasword)
Now start spiffa.
[david@octopus ~]# spiffa
Note that in this case the root user has # as the prompt instead of $. The following window should appear.
Main window (root user)
The first thing to do is to add your user name to the user list, so click on the Users tab and the next window should be seen.
Users Page
Enter your login name in the New User entry widget the click the ADD New User button to add your name to the list. To remove an unwanted name, click on it in the list to highlight it then click DELETE Selected User.
Now while still the root user, click on the Pathnames tab.
Pathnames page
Check that these are all correct for your system. They should be right for most versions of Linux I think... Not sure why bzip2 is in /usr/bin instead of /bin.
NOW make sure everything is saved. Click the SAVE button at the lower left of the whole window. If preferred, you can click on the SAVE THIS PAGE button as each page is processed. At this stage, terminate spiffa by clicking on QUIT and restart as an ordinary user with the login name that was specified in the Users Page. The rest of the configuration can be completed as an ordinary user. The SAVE button and the SAVE THIS PAGE button save to the default configuration file /usr/local/etc/spiffa.conf. To save to a non-default location or name use the SAVE AS button.
Backup Options Page
The backup options page includes many choices. On the left, there is a choice of compression to be used, which may be no compression. Beneath that is the number of backups to retain in addition to the current one. If this is -1 then all backups are retained. The centre panel is a list of files and directories to be backed up and this can't be edited directly. Use the New Source entry widget to the right then click on the ADD New Source button to place it in the list. To delete a source, click on it in the list to highlight it then click on DELETE Selected User. It is also necessary to choose the destination directory for the backup. In the screenshot above, this is /media/MAXTOR which is an external hard drive. It could be a sub-directory such as /media/MAXTOR/mybackup. Optionally the mount point of the destination can be inserted in the mount point entry widget. This has been added to this version to permit a primitive check as to whether the destination is actually mounted. A permanent mount point may be written to even if not mounted which isn't what is wanted!
Other Options Page
The Other Options Page is mainly concerned with the restore process with a few extras. To the left the user can choose the log type, none, new or append. The log's pathname is /usr/local/var/log/spiffa.log. The new option means over-write. In the centre is the list of files and directories to be omitted. The omissions take precedence over the backup sources. As with other pages, a new omission is enterred into the entry widget at the right and the ADD New Omission button has to be clicked to place that ommission into the list. If only a directory's contents are to be omitted but the directory name itself is to be permitted then the directory name should have a trailing slash ("/"). Similarly, to delete an ommission, click on it in the list to highlight it then click on DELETE Selected Omission. Beneath that are two check boxes. When a file is restored it will normally replace an already existing file. If it is required to keep such files select Save existing files on restore which will cause copies of such files to be saved if different from the replacing file. In the above example such files are saved. Note that this causes a comparison of the files to take place and this can take a long time if many files are involved. The lower check box, if selected, causes orphaned files to be restored as well as the normal ones. If a file was present in the original restore but missing from a later incremental (update) backup it is an orphaned file. In the above screenshot such files will be restored.
Ensure that all the data are saved!
Main window (backing up)
This is a view of the "Actions" page of the main window during a backup. It is a new backup using the default cofiguration with gzip compression. The destination directory is /media/MAXTOR/TEST and the destination itself is spiffa_backup_octopus_2006_12_10_21_41_26. This is the restore point when restoring. The name is made from "spiffa_backup", the hostname of the computer (octopus in this case), and YYYY_MM_DD_hh_mm_ss where YYYY is the year, MM the month, DD the day of the month, hh is the hour, mm the minute and ss the second. The next line down shows the directory which is currently being backed up and the line below that displays the name of the current file being backed up. The window's icon has changed to a flashing left-pointing arrow coloured green and a rotating "rainbow world" appears to the left of the central logo. If the window is minimized the flashing green arrow should still be visible giving a cue as to what is happening. If the operation is an incremental backup i.e. an update of a pre-existing backup, then the flashing left-pointing arrow is yellow instead of green. New backups and incremental backups may use a selected configuration file in place of the default but ignore a selected restore point. An incremental backup updates the latest backup found in the destination directory specified in the configuration file. The default configuration file is /usr/local/etc/spiffa.conf.
Main window (end of backup)
This is a view of the main window at the end of a short backup. It gives the user some details about the backup. If the action had been an update it would also have displayed the number of names skipped because they were not newer than those already in the backup.
Main window (restoring)
This is a view of the "Actions" page of the main window during a restore. In this case the restore is using the default configuration and using the latest backup. The window's icon is a flashing red right-pointing arrow and the rotating "rainbow world" appears to the right of the central logo.
Restoring a selection
This is a view of the requester for restoring a selection. To obtain it, right or middle click on the restore point's BROWSE button. After a pause while data is being loaded, the requester should appear. In the above, the file F2.gz is selected. Its parent directories are automatically included. From this representation it is not possible to see whether or not any files in the directory Tabitha Birds Squirrel In Jean's Garden have been selected. To make sure, click on the right arrow to its left. When satisfied, click the OK button. If a directory is unchecked, all its contents are removed from the selection so uncheck root to clear the selection completely. If a selection has been made, the window will contain Restore Selection in red in place of "Restore Point".
A Selection will be used for Restore
This is a view of the "Actions" page when a selection has been made. To undo the selection, right click on the BROWSE button and uncheck root to clear the selection completely then click the OK button.
Main window (fatal error)
This is a view of the "Actions" page of the main window when a fatal error occurred. In this case the optional mount point was specified but it was in disagreement with the destination directory.
Adding to the Gnome or KDE Menu
To add an entry to menu for spiffa use the program "alacarte" for Gnome and "kmenuedit" for KDE. If the installation was to the default directories there should be some images available at "/usr/local/share/spiffa/doc/images" one of which may be used as an icon if so desired.
From the Command Line
A normal user, if permitted, runs a default backup as follows:-
[david@octopus ~]$ spiffa -b
or
[david@octopus ~]$ spiffa --backup
and a default restore:-
[david@octopus ~]$ spiffa -r
or
[david@octopus ~]$ spiffa --restore
and a default incremental backup:-
[david@octopus ~]$ spiffa -i
or
[david@octopus ~]$ spiffa --incremental
or
[david@octopus ~]$ spiffa -u
or
[david@octopus ~]$ spiffa -update
One can also choose to restore from a different restore point with -prestorepoint or if preferred, --point=restorepoint. For all three it is possible to select a different configuration file from the default with -ffile or if preferred, --file=file. If a restore point is selected for a backup or incremental backup it is ignored. Both the restore point and the file should be specified as the full path name.
The command line version is what is used to invoke spiffa from a scheduler such as cron and anacron. If cron.daily and cron.weekly are set up and anacron is also set up then add entries in each for, say, incremental backups daily and a new backup each week. If the computer is only turned on during the day anacron should pick up anything that cron misses because of the downtime. A new full backup can take a long time, so be warned! Also remember that it is wise to use full pathnames e.g. /usr/local/bin/spiffa not just spiffa alone.
NOTE: restoring from a selection is not available from the command line.
How It Works
There are two programs, a backend (spiffaslave) and the frontend (spiffa). The backend, spiffaslave, has to be started by spiffa and runs suid which means that spiffaslave has root priveleges. The slave creates a file /usr/local/var/run/spiffaslave.pid which is checked for presence on startup. If present it refuses to start because it is dangerous to attempt two backups/restores simultaneously. In order to run the GUI, the user david enters as follows at the command line:-
[david@octopus ~]$ spiffa
In order to change to the root user to get the full works:-
[david@octopus ~]$ su
Password: (enter root's pasword)
THEN issue the spiffa command as above. The $ is usually changed to # when the user has become root i.e. the superuser.
The slave runs suid and communicates with spiffa. All the work is done by the slave, spiffa merely telling it what to do. If the login user is not a permitted user then everything aborts. The first time that spiffa is run it is best to be root so that the GUI is available. Add your login name to the user list in the Users page. Also, while root, check that the Pathnames page gives the correct full pathnames. The defaults should be correct in most cases. Go through all the pages and view the tooltips to decide what should be entered and save each page. The result, assuming the data is saved, is the file /usr/local/etc/spiffa.conf which provides the default configuration. If this has been created manually it must be made read/write for root and no-one else.
One difficulty is that even root can't access certain files if their permissions are unsuitable or the permissions of their parent directory or parent directories. This is overcome by temporarily altering permissions. If a breakdown occurs while this is in progress it may result in a problem. It may be possible to use restore to return to the status quo if lucky. Make sure there is an adequate number of backups! If spiffa stops this is detected by spiffaslave. The permissions are restored before spiffaslave quits.
The Structure of the Backup
The backup is a directory e.g. spiffa_backup_octopus_2006_12_10_21_41_26 on the destination disk drive. This contains a sub-directory called root a this is the root of the actual backup. There are also two or three files in the backup directory. The file named data contains information about all the files that have been saved within root. The file named errors contains details of any errors which may have been detected during the backup. If an incremental backup occurs this file may have more information appended to it. If the backup is a compressed backup there is a third file which is empty but its name represents the type of compression used. The root sub-directory has a normal file structure and if compression is used the files are compressed individually so that it is easier to see where files belong. In theory one could copy a single file and extract it to correct just one file if the correct file was known. Having done that it would be necessary to inspect the data directory and change the ownership and permissions as required. As these are in hexadecimal it could be tricky but perfectly possible. The order in which the data appears is:-
name owner group permissions atime mtime
This may be preceded by ORPHAN if appropriate. The name is always in quotes.
The Configuration File
Assuming that everything has been installed in the default locations, the configuration file is /usr/local/etc/spiffa.conf. The following is an example for a very large backup with comments:-
# Configuration file for spiffa
# Source files and directories for backup
BACKUP_SOURCE = "/boot"
BACKUP_SOURCE = "/dev"
BACKUP_SOURCE = "/etc"
BACKUP_SOURCE = "/home"
BACKUP_SOURCE = "/OLD_root"
BACKUP_SOURCE = "/public"
BACKUP_SOURCE = "/root"
BACKUP_SOURCE = "/sbin"
BACKUP_SOURCE = "/selinux"
BACKUP_SOURCE = "/usr"
BACKUP_SOURCE = "/var"
# Source files and directories NOT for backup
# If the contents of a directory are to be omitted
# use a trailing slash with the directory name.
# The directory name will then be included but not
# its contents. Without the trailing slash the directory
# name and its contents are omitted.
BACKUP_DENY = "/proc"
BACKUP_DENY = "/sys"
# Only the following ordinary users are permitted to use spiffa
# The superuser "root" doesn't need to be in this list
USER = david
# If the destination directory for the backup
# is mounted on a permanent mount point that is present
# even when it is not mounted, such as used with "/etc/fstab",
# specify it here so that spiffa won't write to it unless mounted.
MOUNT_POINT = "/media/MAXTOR"
# The destination directory for the backup
# This is also the source directory for a restore
BACKUP_DESTINATION = "/media/MAXTOR"
# The type of compression to use
# This can be GZ BZ2 GZ_BZ2 or NONE
COMPRESSION = GZ
# The number of old backups to retain in addition to the current one.
# The value should be from -1 to 100.
# If this is -1 then all old backups are retained.
KEEP_NUMBER = 2
# Save copies of old files
# If this is YES or TRUE or 1 then files that would be overwritten
# during a restore are retained with XXX.spiffasave as a suffix
# where XXX is a decimal number.
SAVE_EXISTING_FILES = NO
# Restore orphan files
# When an incremental backup is performed,
# files that have been deleted in the source since the initial backup
# are marked as orphans. If this is YES or TRUE or 1 then these files
# will be restored in addition to the rest, otherwise they are ignored.
RESTORE_ORPHANS = NO
# Pathnames of commands etc. used by spiffa and/or slave
SH_PATHNAME = "/bin/sh"
CAT_PATHNAME = "/bin/cat"
GZIP_PATHNAME = "/bin/gzip"
BZIP2_PATHNAME = "/usr/bin/bzip2"
LN_PATHNAME = "/bin/ln"
MTAB_PATHNAME = "/etc/mtab"
BROWSER_PATHNAME = "htmlview %s"
# Options for spiffa.log
# This can be NEW, APPEND or NONE
# The file "/usr/local/etc/spiffa.log" can be opened as a new file
# or it can be appended to the existing file if present. Alternatively
# it may be preferred to have no file at all.
LOG_TYPE = NEW
In this configuration the mount point is specified and is identical to the destination. The destination could be a sub-directory of the destination. The directory (mount point) /mnt is not specified in the directories to be backed up and it is not a sub-directory of any of those entries so it is omitted although not mentioned in the omissions.
NOTE that the first non-blank line MUST be the comment:-
# Configuration file for spiffa
as this provides the check that it is a valid spiffa configuration file.
Installing
First cd to the directory containing the .tar.gz file then extract the compressed tar file with something like:-
[david@octopus ~]$ tarzx spiffa-1.3.tar.gz
or
[david@octopus ~]$ tar xvzf spiffa-1.3.tar.gz
Note that I have the following added into my .bashrc file:-
Now change to the top directory:-
[david@octopus ~]$ cd spiffa-1.3
then:-
[david@octopus ~]$ ./configure
Now either use a direct install or an rpm install.
A Direct Install...
After ./configure as per the above:-
[david@octopus ~]$ make
To perform the actual install you have to be root so use the su command mentioned above then:-
[david@octopus ~]# make install
To uninstall it is also necessary to be root:-
[david@octopus ~]# make uninstall
That should be all there is to it but included in the distribution is autogen.sh if it is necessary to experiment. If so, read up about the Gnu Build Tools first! Here are a few:-
Useful Packaging Links
Maximum RPM
Using Automake and Autoconf with C+
GNU Autoconf Automake and Libtool
Introduction to GNU Build Tools
A search with google reveals numerous other helpful sites.
An RPM Install...
After ./configure as per the above, first make a new copy of spiffa-1.3.tar.gz.
[david@octopus ~]$ make dist
This will create a copy of spiffa-1.3.tar.gz in the spiffa-1.3 (i.e. top) directory.
Now become root using the su command mentioned above then to create the rpm:-
[david@octopus ~]# make rpm
This creates an rpm file of which the full pathname will be something like /usr/src/redhat/RPMS/i386/spiffa-1.3-1.i386.rpm depending on how the system is arranged. It will also create debuginfo in the same directory and an srpm file in the appropriate SRPMS directory. To install the rpm file first cd to its directory:-
[david@octopus ~]# cd /usr/src/redhat/RPMS/i386
Make sure that you are still root!
Now to install spiffa issue the following command:-
[david@octopus i386]# rpm -ivh spiffa-1.3-1.i386.rpm
OR if an older version is already installed:-
[david@octopus i386]# rpm -Uvh spiffa-1.3-1.i386.rpm
To remove it again, as root issue the following command:-
[david@octopus ~]# rpm -e spiffa
Simpler method of creating the rpm
An alternative method for creating the rpm file is to change directories to the directory containing the downloaded file spiffa-1.3.tar.gz. Then, as root, issue the following command:-
[david@octopus spiffa-1.3]# rpmbuild -ta spiffa-1.3.tar.gz
The disadvantage is that it is only possible to install to /usr/local, the default directory. See the next section.
Install to a different directory
For a direct install the appropriate information will have to be passed to configure, for example:-
[david@octopus spiffa-1.3]$ ./configure --bindir=/ --datadir=/usr/share --sysconfdir=/etc --localstatedir=/var --mandir=/usr/share/man
For an rpm type of install it is necessary to modify the file spiffa.spec in the top directory prior to using the command make rpm. To obtain a similar result to above change the appropriate lines to:-
Prefix: /
%define bindir %{prefix}/bin
%define datadir %{prefix}/usr/share
%define sysconfdir %{prefix}/etc
%define localstatedir %{prefix}/var
%define mandir %{prefix}/usr/share/man
This places everything into the places normally used by Fedora Core and Red Hat Linux. However, normally files and programs that are not part of a distribution are placed in /usr/local. The distribution contains the file spiffa.specX for a Fedora istall and the names of this file and spiffa.spec can be swapped to make life easier.
Description of GUI
To start spiffa with the GUI, enter the command spiffa alone at the command line:-
[david@octopus ~]$ spiffa
Initially an ordinary user, i.e. a user other than root, won't have permission to use spiffa. An attempt to run spiffa results in a small window telling the user to start spiffa as root.
Permission denied!
Here, the configuration file is probably missing. It hasn't been written yet! If the file was invalid the user is similarly informed.
Permission denied!
Here, the configuration file was read in and user "david" isn't in the users list.
Also, only one instance of spiffa is allowed to run at a time. An attempt to run a second copy results in a similar informative window.
Already running!
Another problem that is possible on startup is that spiffa may not be able to allocate a message queue in which case a similar small window will appear to inform the user. The easiest way to rectify this is to reboot the computer but it is possible to examine the message queues with:-
[david@octopus ~]$ ipcs -q
and remove queue ids with
[david@octopus ~]$ ipcrm -q ###
where ### is the queue id. Check out the ipcs and ipcrm manpages for more details. Hopefully this is a rare occurence but it is as well to understand what can happen.
So the best plan is to start spiffa as the root user, i.e. the superuser.
In order to become the root user:-
[david@octopus ~]$ su
Password: (enter root's pasword)
Now start spiffa.
[david@octopus ~]# spiffa
Note that in this case the root user has # as the prompt instead of $. The following window should appear.
Main window (root user)
The first thing to do is to add your user name to the user list, so click on the Users tab and the next window should be seen.
Users Page
Enter your login name in the New User entry widget the click the ADD New User button to add your name to the list. To remove an unwanted name, click on it in the list to highlight it then click DELETE Selected User.
Now while still the root user, click on the Pathnames tab.
Pathnames page
Check that these are all correct for your system. They should be right for most versions of Linux I think... Not sure why bzip2 is in /usr/bin instead of /bin.
NOW make sure everything is saved. Click the SAVE button at the lower left of the whole window. If preferred, you can click on the SAVE THIS PAGE button as each page is processed. At this stage, terminate spiffa by clicking on QUIT and restart as an ordinary user with the login name that was specified in the Users Page. The rest of the configuration can be completed as an ordinary user. The SAVE button and the SAVE THIS PAGE button save to the default configuration file /usr/local/etc/spiffa.conf. To save to a non-default location or name use the SAVE AS button.
Backup Options Page
The backup options page includes many choices. On the left, there is a choice of compression to be used, which may be no compression. Beneath that is the number of backups to retain in addition to the current one. If this is -1 then all backups are retained. The centre panel is a list of files and directories to be backed up and this can't be edited directly. Use the New Source entry widget to the right then click on the ADD New Source button to place it in the list. To delete a source, click on it in the list to highlight it then click on DELETE Selected User. It is also necessary to choose the destination directory for the backup. In the screenshot above, this is /media/MAXTOR which is an external hard drive. It could be a sub-directory such as /media/MAXTOR/mybackup. Optionally the mount point of the destination can be inserted in the mount point entry widget. This has been added to this version to permit a primitive check as to whether the destination is actually mounted. A permanent mount point may be written to even if not mounted which isn't what is wanted!
Other Options Page
The Other Options Page is mainly concerned with the restore process with a few extras. To the left the user can choose the log type, none, new or append. The log's pathname is /usr/local/var/log/spiffa.log. The new option means over-write. In the centre is the list of files and directories to be omitted. The omissions take precedence over the backup sources. As with other pages, a new omission is enterred into the entry widget at the right and the ADD New Omission button has to be clicked to place that ommission into the list. If only a directory's contents are to be omitted but the directory name itself is to be permitted then the directory name should have a trailing slash ("/"). Similarly, to delete an ommission, click on it in the list to highlight it then click on DELETE Selected Omission. Beneath that are two check boxes. When a file is restored it will normally replace an already existing file. If it is required to keep such files select Save existing files on restore which will cause copies of such files to be saved if different from the replacing file. In the above example such files are saved. Note that this causes a comparison of the files to take place and this can take a long time if many files are involved. The lower check box, if selected, causes orphaned files to be restored as well as the normal ones. If a file was present in the original restore but missing from a later incremental (update) backup it is an orphaned file. In the above screenshot such files will be restored.
Ensure that all the data are saved!
Main window (backing up)
This is a view of the "Actions" page of the main window during a backup. It is a new backup using the default cofiguration with gzip compression. The destination directory is /media/MAXTOR/TEST and the destination itself is spiffa_backup_octopus_2006_12_10_21_41_26. This is the restore point when restoring. The name is made from "spiffa_backup", the hostname of the computer (octopus in this case), and YYYY_MM_DD_hh_mm_ss where YYYY is the year, MM the month, DD the day of the month, hh is the hour, mm the minute and ss the second. The next line down shows the directory which is currently being backed up and the line below that displays the name of the current file being backed up. The window's icon has changed to a flashing left-pointing arrow coloured green and a rotating "rainbow world" appears to the left of the central logo. If the window is minimized the flashing green arrow should still be visible giving a cue as to what is happening. If the operation is an incremental backup i.e. an update of a pre-existing backup, then the flashing left-pointing arrow is yellow instead of green. New backups and incremental backups may use a selected configuration file in place of the default but ignore a selected restore point. An incremental backup updates the latest backup found in the destination directory specified in the configuration file. The default configuration file is /usr/local/etc/spiffa.conf.
Main window (end of backup)
This is a view of the main window at the end of a short backup. It gives the user some details about the backup. If the action had been an update it would also have displayed the number of names skipped because they were not newer than those already in the backup.
Main window (restoring)
This is a view of the "Actions" page of the main window during a restore. In this case the restore is using the default configuration and using the latest backup. The window's icon is a flashing red right-pointing arrow and the rotating "rainbow world" appears to the right of the central logo.
Restoring a selection
This is a view of the requester for restoring a selection. To obtain it, right or middle click on the restore point's BROWSE button. After a pause while data is being loaded, the requester should appear. In the above, the file F2.gz is selected. Its parent directories are automatically included. From this representation it is not possible to see whether or not any files in the directory Tabitha Birds Squirrel In Jean's Garden have been selected. To make sure, click on the right arrow to its left. When satisfied, click the OK button. If a directory is unchecked, all its contents are removed from the selection so uncheck root to clear the selection completely. If a selection has been made, the window will contain Restore Selection in red in place of "Restore Point".
A Selection will be used for Restore
This is a view of the "Actions" page when a selection has been made. To undo the selection, right click on the BROWSE button and uncheck root to clear the selection completely then click the OK button.
Main window (fatal error)
This is a view of the "Actions" page of the main window when a fatal error occurred. In this case the optional mount point was specified but it was in disagreement with the destination directory.
Adding to the Gnome or KDE Menu
To add an entry to menu for spiffa use the program "alacarte" for Gnome and "kmenuedit" for KDE. If the installation was to the default directories there should be some images available at "/usr/local/share/spiffa/doc/images" one of which may be used as an icon if so desired.
From the Command Line
A normal user, if permitted, runs a default backup as follows:-
[david@octopus ~]$ spiffa -b
or
[david@octopus ~]$ spiffa --backup
and a default restore:-
[david@octopus ~]$ spiffa -r
or
[david@octopus ~]$ spiffa --restore
and a default incremental backup:-
[david@octopus ~]$ spiffa -i
or
[david@octopus ~]$ spiffa --incremental
or
[david@octopus ~]$ spiffa -u
or
[david@octopus ~]$ spiffa -update
One can also choose to restore from a different restore point with -prestorepoint or if preferred, --point=restorepoint. For all three it is possible to select a different configuration file from the default with -ffile or if preferred, --file=file. If a restore point is selected for a backup or incremental backup it is ignored. Both the restore point and the file should be specified as the full path name.
The command line version is what is used to invoke spiffa from a scheduler such as cron and anacron. If cron.daily and cron.weekly are set up and anacron is also set up then add entries in each for, say, incremental backups daily and a new backup each week. If the computer is only turned on during the day anacron should pick up anything that cron misses because of the downtime. A new full backup can take a long time, so be warned! Also remember that it is wise to use full pathnames e.g. /usr/local/bin/spiffa not just spiffa alone.
NOTE: restoring from a selection is not available from the command line.
How It Works
There are two programs, a backend (spiffaslave) and the frontend (spiffa). The backend, spiffaslave, has to be started by spiffa and runs suid which means that spiffaslave has root priveleges. The slave creates a file /usr/local/var/run/spiffaslave.pid which is checked for presence on startup. If present it refuses to start because it is dangerous to attempt two backups/restores simultaneously. In order to run the GUI, the user david enters as follows at the command line:-
[david@octopus ~]$ spiffa
In order to change to the root user to get the full works:-
[david@octopus ~]$ su
Password: (enter root's pasword)
THEN issue the spiffa command as above. The $ is usually changed to # when the user has become root i.e. the superuser.
The slave runs suid and communicates with spiffa. All the work is done by the slave, spiffa merely telling it what to do. If the login user is not a permitted user then everything aborts. The first time that spiffa is run it is best to be root so that the GUI is available. Add your login name to the user list in the Users page. Also, while root, check that the Pathnames page gives the correct full pathnames. The defaults should be correct in most cases. Go through all the pages and view the tooltips to decide what should be entered and save each page. The result, assuming the data is saved, is the file /usr/local/etc/spiffa.conf which provides the default configuration. If this has been created manually it must be made read/write for root and no-one else.
One difficulty is that even root can't access certain files if their permissions are unsuitable or the permissions of their parent directory or parent directories. This is overcome by temporarily altering permissions. If a breakdown occurs while this is in progress it may result in a problem. It may be possible to use restore to return to the status quo if lucky. Make sure there is an adequate number of backups! If spiffa stops this is detected by spiffaslave. The permissions are restored before spiffaslave quits.
The Structure of the Backup
The backup is a directory e.g. spiffa_backup_octopus_2006_12_10_21_41_26 on the destination disk drive. This contains a sub-directory called root a this is the root of the actual backup. There are also two or three files in the backup directory. The file named data contains information about all the files that have been saved within root. The file named errors contains details of any errors which may have been detected during the backup. If an incremental backup occurs this file may have more information appended to it. If the backup is a compressed backup there is a third file which is empty but its name represents the type of compression used. The root sub-directory has a normal file structure and if compression is used the files are compressed individually so that it is easier to see where files belong. In theory one could copy a single file and extract it to correct just one file if the correct file was known. Having done that it would be necessary to inspect the data directory and change the ownership and permissions as required. As these are in hexadecimal it could be tricky but perfectly possible. The order in which the data appears is:-
name owner group permissions atime mtime
This may be preceded by ORPHAN if appropriate. The name is always in quotes.
The Configuration File
Assuming that everything has been installed in the default locations, the configuration file is /usr/local/etc/spiffa.conf. The following is an example for a very large backup with comments:-
# Configuration file for spiffa
# Source files and directories for backup
BACKUP_SOURCE = "/boot"
BACKUP_SOURCE = "/dev"
BACKUP_SOURCE = "/etc"
BACKUP_SOURCE = "/home"
BACKUP_SOURCE = "/OLD_root"
BACKUP_SOURCE = "/public"
BACKUP_SOURCE = "/root"
BACKUP_SOURCE = "/sbin"
BACKUP_SOURCE = "/selinux"
BACKUP_SOURCE = "/usr"
BACKUP_SOURCE = "/var"
# Source files and directories NOT for backup
# If the contents of a directory are to be omitted
# use a trailing slash with the directory name.
# The directory name will then be included but not
# its contents. Without the trailing slash the directory
# name and its contents are omitted.
BACKUP_DENY = "/proc"
BACKUP_DENY = "/sys"
# Only the following ordinary users are permitted to use spiffa
# The superuser "root" doesn't need to be in this list
USER = david
# If the destination directory for the backup
# is mounted on a permanent mount point that is present
# even when it is not mounted, such as used with "/etc/fstab",
# specify it here so that spiffa won't write to it unless mounted.
MOUNT_POINT = "/media/MAXTOR"
# The destination directory for the backup
# This is also the source directory for a restore
BACKUP_DESTINATION = "/media/MAXTOR"
# The type of compression to use
# This can be GZ BZ2 GZ_BZ2 or NONE
COMPRESSION = GZ
# The number of old backups to retain in addition to the current one.
# The value should be from -1 to 100.
# If this is -1 then all old backups are retained.
KEEP_NUMBER = 2
# Save copies of old files
# If this is YES or TRUE or 1 then files that would be overwritten
# during a restore are retained with XXX.spiffasave as a suffix
# where XXX is a decimal number.
SAVE_EXISTING_FILES = NO
# Restore orphan files
# When an incremental backup is performed,
# files that have been deleted in the source since the initial backup
# are marked as orphans. If this is YES or TRUE or 1 then these files
# will be restored in addition to the rest, otherwise they are ignored.
RESTORE_ORPHANS = NO
# Pathnames of commands etc. used by spiffa and/or slave
SH_PATHNAME = "/bin/sh"
CAT_PATHNAME = "/bin/cat"
GZIP_PATHNAME = "/bin/gzip"
BZIP2_PATHNAME = "/usr/bin/bzip2"
LN_PATHNAME = "/bin/ln"
MTAB_PATHNAME = "/etc/mtab"
BROWSER_PATHNAME = "htmlview %s"
# Options for spiffa.log
# This can be NEW, APPEND or NONE
# The file "/usr/local/etc/spiffa.log" can be opened as a new file
# or it can be appended to the existing file if present. Alternatively
# it may be preferred to have no file at all.
LOG_TYPE = NEW
In this configuration the mount point is specified and is identical to the destination. The destination could be a sub-directory of the destination. The directory (mount point) /mnt is not specified in the directories to be backed up and it is not a sub-directory of any of those entries so it is omitted although not mentioned in the omissions.
NOTE that the first non-blank line MUST be the comment:-
# Configuration file for spiffa
as this provides the check that it is a valid spiffa configuration file.
<<-- END OF DOCUMENT -->>