
-----------------------------------------------------------------------
Backup plugin for J-Pilot

by Jason Day <jasonday@worldnet.att.net>
http://jasonday.home.att.net
-----------------------------------------------------------------------

REQUIREMENTS

- J-Pilot version 0.99.2 or greater, available from http://www.jpilot.org

- GDBM - The GNU database manager.  This comes with most linux
  distributions, but if for some reason you don't have it, get it from any
  GNU mirror (http://www.fsf.org/software/gdbm/gdbm.html).


-----------------------------------------------------------------------
INSTALLING

Extract jpilot-backup_x-xx.tar.gz, change to the jpilot-backup_x.xx
directory and the standard:
    ./configure
    make
should build libbackup.so.  At this point, you can install the plugin
locally by typing "make local_install" (without the quotes, of course).  Or,
you can install it system-wide by becoming root and typing "make install".
The first method will copy libbackup.so to your ~/.jpilot/plugins directory,
while the second will copy it to the system-wide plugins directory, usually
/usr/lib/jpilot/plugins.  Of course, you could also just copy libbackup.so
to the appropriate location, if you wish.

NOTE: If you run 'make install' or 'make local_install', libtool will issue
a message similar to the following:

libtool: install: warning: remember to run libtool --finish
/usr/lib/jpilot/plugins

It is safe to ignore this message.


-----------------------------------------------------------------------
GDBM AND LOCKING

The configure script now checks for the GDBM_NOLOCK flag and if found it
disables GDBM locking.  From a user perspective, this makes no difference, but
it fixes a problem with /home mounted via NFS.  See README.NFS for more
details.

If, for whatever reason, you wish to enable GDBM locking, just pass
--force-gdbm-lock to ./configure.


-----------------------------------------------------------------------
USAGE

Usage is pretty straightforward.  After installing jpilot-backup you should
have a new menu item in the "Plugins" menu called "Backup".  Selecting this
menu item will display the Backup preferences.  From here, you can configure
which Palm apps/databases to backup, how often to backup, how many archives
to keep, and whether to backup new databases or not.  Changes take place
immediately and are saved automatically.

TIP: The first time you use jpilot-backup, it will by default backup every
application and database on your Palm.  Depending on what you have installed
on your Palm, this can take quite a long time.  To avoid this, uncheck the
"Backup new databases" checkbox before your first sync; this will store all
of your Palm apps and databases in the inactive list without actually
retrieving them.  You can then decide which databases you want to backup
and which to ignore, then sync again.

PERSISTENT ARCHIVE: New in jpilot-backup 0.50, the persistent archive option
keeps an additional archive of all databases that have ever been backed up, in
one place.  Think of it as the union of all the archive directories.  There is
also a perl script contributed by Peter Williams, jpilot_archive.pl, in the
contrib directory that may be used to create a persistent archive directory
from an existing set of archive directories.


-----------------------------------------------------------------------
RESTORING A RESET PALM

This is why you make backups right?  It's not difficult to restore your
data, but it's not quite as straightforward as it could be, either.  In
order to restore your data, you will have to use the pilot-link tools
pilot-xfer and install-user.

First, open your favorite terminal window and cd to ~/.jpilot/Backup .
Hopefully, there are some archive directories there.  There should also be a
symlink called "LatestArchive", which points to the most recent archive
directory.  This will most likely be what you want to restore, unless
you're a developer or you like mucking around with Palm databases.  Once you
determine which directory contains the data you want, put your Palm in the
cradle and type the following command:
   pilot-xfer -r <directory>
replacing <directory> with the directory name, then press the hotsync
button.  If you have a USB cradle, you will need to press the hotsync button
first, then run pilot-xfer.  This should restore all of your apps and data
on your Palm.

Next, you will need to restore your Palm user ID, or you won't be able to
sync.  To do this, first open up your ~/.jpilot/jpilot.rc file in any text
editor, or just cat it:
   cat ~/.jpilot/jpilot.rc
and look for the user and user_id values.  These will be on two lines that
look something like this:
   user John_Doe
   user_id 1968049313
Then run install-user, using the values in your ~/.jpilot/jpilot.rc file as
parameters.  e.g.
   install-user /dev/pilot John_Doe 1968049313

That's it, you should now have a fully restored and working Palm.


-----------------------------------------------------------------------
TROUBLESHOOTING

If configure gives the following message:

checking for JPilot plugin headers... no
configure: error: Could not find the JPilot plugin headers

Then you need to help it find the J-Pilot header files.  Do this by passing
the location to configure like so:
   ./configure --with-plugin-prefix=/path/to/jpilot-x.xx
   
The /path/to/jpilot-x.xx directory should contain libplugin.h and prefs.h.


-----------------------------------------------------------------------
BUGS

If you find a bug, please send a message to jasonday@worldnet.att.net .
It would also be helpful to start J-Pilot in debug mode (jpilot -d),
reproduce the bug, and send the contents of ~/.jpilot/jpilot.log in the
message.

-----------------------------------------------------------------------


Thank you for using jpilot-backup!
Jason Day <jasonday@worldnet.att.net>
