Configuration
-------------

The mount point of the memory card used to save and restore data to and
from is read from the environment variable MMC_MOUNTPOINT. 

The location of user data is specified by the environment variable
MYDOCSDIR.

The application also looks in <sysconfdir>/osso-backup/osso-backup.conf
for a number of configuration keys. The file is a simple XML format:

<backup-configuration>

  <memory-card>
    <mountpoint>/mnt/memcard</mountpoint>
  </memory-card>

  <gconf-dir>/etc/osso-af-init/gconf-dir</gconf-dir>

  <documents-path>$HOME/MyDocs</documents-path>

</backup-configuration>

The configuration consists of the mount point for the memory card used,
the location of gconf settings to be backed up, the location of the
documents on the device, and the delay in seconds to wait after asking
the application killer to kill applications.

The paths must be absolute, unless they start with the special string
$HOME, which indicates that the directory is relative to the home
directory.

Note that the value in MMC_MOUNTPOINT overrides any mountpoint
configuration, and likewise with MYDOCSDIR.


Application configuration
-------------------------

The backup application will backup data in the documents-path
automatically. This is handled by the category/MIME type mapping
maintained by the osso_mime_* API in the libossomime package (source
package name osso-gnomevfs-extra). See the API documentation for for
more information on how to setup this mapping.

For other data residing outside that directory, the so-called locations
configuration is used.


*** IMPORTANT***: 

    The locations configuration paths MUST NOT overlap with the
    documents path.


The locations configuration lets applications install a configuration
file with a list of files and directories that should be included in the
backup. The files should be installed into

  <sysconfdir>/osso-backup/applications/, 

be named <application>.conf and consist of a simple XML format.

The paths must be absolute, unless they start with the special string
$HOME, which indicates that the directory is relative to the home
directory.

The format is as follows:

<backup-configuration>
  <locations>
    <location type="TYPE" category="CATEGORY">PATH</location>
    <location type="TYPE" category="CATEGORY" auto="AUTO">PATH</location>
    <exclusion type="TYPE" category="CATEGORY">PATH</exclusion>
    ...
  </locations>
</backup-configuration>

Where TYPE is "file" or "dir" for a file or directory. 

CATEGORY is one of:
emails
documents 
media
contacts
bookmarks
settings

AUTO is true or false (this does not apply to the "exclusion" tag).

PATH is the path to the specified file or directory.  This is an
absolute file or directory when specified in the "location" tag,
however, the "exclusion" tag has simple pattern matching, so it will
allow "?" and "*". For example "/somedir/*.png" would be perfectly
acceptable. 

The property category is used for handling selective backup and
restore.

The property auto is used to tell the backup application not to
request a user response in case of a conflict, but automatically
replace the file or files inside that directory or any
subdirectory. It may be omitted, in which case it defaults to false. 


An example of a file installed by an email application:

<backup-configuration>
  <locations>
    <location type="dir" 
              category="emails">/home/user/email/folders</location>
    <location type="dir" 
              category="emails">/home/user/email/other-folders</location>
    <location type="file"
              category="contacts">/home/user/email/Addressbook.xml</location>
    <exclusion type="dir" 
	      category="settings">$HOME/.osso/test</exclusion>
    <exclusion type="file" 
	      category="settings">$HOME/.osso/*.txt</exclusion>
  </locations>
<backup-configuration>

An example for a browser application:

<backup-configuration>
  <locations>
    <location type="file" category="bookmarks">/opera/opera.adr</location>
    <location type="file" category="settings">/opera/opera.ini</location>
  </locations>
<backup-configuration>


Third-party applications
------------------------

For third-party applications, there is an additional location that is
searched for configuration. This location is specified by the platform
environment variable INSTALLHOME or the fallback /var/lib/install. In
this location, the subdirectory etc/osso-backup/applications is used as
mentioned above.


Setting up a test environment
-----------------------------

The commandline option --config-dir can be used to point the application
to another directory for configuration. This is useful when testing. To
use this feature, setup a configuration directory somewhere with a
osso-backup.conf and applications/ directory as described above.

To create a mountable "fake" memory card:


 dd if=/dev/zero of=/path/to/fake-diskimage bs=1024 count=65536

 mkfs.vfat /path/to/fake-diskimage (ignore any warning about not being a block device)

 Add to /etc/fstab:

 /path/to/fake-diskimage  /mnt/fake   vfat    rw,user,noauto,loop=/dev/loop0  0 0

The path to the mountpoint should also be set in the used configuration file.


Note that this does not always work (depending on OS/version/etc). It it
does not work, try this instead:

For /etc/fstab:

/dev/loop0 /mnt/fake vfat rw,user,noauto 0 0

And setup a loop device (as root):

losetup /dev/loop0 /path/to/fake-diskimage

(Might need to run modprobe loop before if it doesn't work).

Then you should be able to mount.

