Making backups

Introduction

For backing up Daisy there is an application which will help you create and restore backups. You can find it in

<DAISY_HOME>/bin/daisy-backup-tool

This tool in its current form can backup :

daisy-repository

repository database
blobstore
indexstore
configuration

activemq database (ActiveMQ is the JMS system)
daisy-wiki

cocoon.xconf
web.xml
skins
sites
you name it (this will be elaborated on further in this document)

Your backup will contain database dumps of the configured databases and zip files containing the content of directories or files.

Running the backup tool

Prerequisites

The following DBMS can be backed up :

MySQL (binaries used : mysql, mysqldump, mysqladmin)

MySQL 4.0 users will have to manually edit the database dump. First unzip the dump file. Add "SET FOREIGN_KEY_CHECKS=0;" in the beginning of the dump and "SET FOREIGN_KEY_CHECKS=1;" at the end. Rezip the dump file. Then run backup-tool with option -R to rehash the backup entries.
PostgreSQL (binaries used : psql, pg_dump, dropdb)

For successful completion of a backup it is required that the binaries can be found in the environments PATH variable.

PostgreSQL backup and/or restore has not been tested yet. Feedback on this subject is always welcome.

Running

Running the tool without any parameters will just display the help which should look something like this:

usage: daisy-backup-tool [-d <daisydata-path>] -R <backup-name> | -r
       <backup-name> | -h | -b | -v [-a <entry-configuration-file>]   [-f
       <from-address>] [-l <backup-path>]  [-s <smtp-server>] [-e
       <email-address>]
 -d,--daisy-data-dir <daisydata-path>                 Daisy data directory
 -a,--additional-entries <entry-configuration-file>   Path to
                                                      configuration of additional backup entries
 -s,--smtp-server <smtp-server>                       Smtp server
 -R,--rehash <backup-name>                            Rehash files from an
                                                      existing backup
 -b,--backup                                          Create a new backup
 -e,--emailaddress <email-address>                    Where emails will be
                                                      sent to incase of an exception
 -f,--fromaddress <from-address>                      Sender address to
                                                      use for exception emails
 -h,--help                                            Show this message
 -l,--backuplocation <backup-path>                    Location where
                                                      backups are stored
 -r,--restore <backup-name>                           Restore an existing
                                                      backup
 -v,--version                                         Print version info

Compulsory options

-b, -r <backup-name> or -R <backup-name>

The -b option is used to create a backup.
Specifying the -r <backup-name> option will allow you to restore a backup. The name of the backup can be found in the backup location directory. You will be looking for a directory name of the form <DATE>_<SEQUENCE> or YYYYMMDD_### (e.g. 20051124_001), the directory name is thus the same name as the backup.
-R <backup-name> rehashes the backup entries. This is used when a user wishes to modify a file before restoring it. Some versions of mysql for example do not switch off foreign key checks prior to restoring the database. The user should then switch of the checks at the beginning of the database dump and turn them on again at the end. This will modify the file which in turn will cause the tool to complain at restore time saying that a file has been tampered with. Rehashing will then recreate hashes for the modified files allowing the tool to restore without complaining.

Minimally the Daisy repository will be backed up or restored. By specifying different options you are able to backup or restore also files of the Daisy Wiki.

-l <backup-path>

Specifies where the backups will be created in, restored from, or rehashed.

-d <daisydata-path> (when using -b or -r)

This option is mandatory when using -b or -r. The daisydata-path is where your blobstore, indexstore, configuration and logs are stored.

The -d option is required for -r (restore) starting from Daisy 1.5-M2. This is because from that release on, the myconfig.xml does not contain the absolute location to the data directory anymore (but instead ${daisy.datadir}), so the restore wouldn't know where to create the data directory. This also means it is possible to restore the backup to another location then where it was originally.

If you were previously using older Daisy versions (< 1.5-M2), this of course requires that you updated the myconfig.xml to replace the absolute paths with ${daisy.datadir}, because the data is still restored to the locations specified in the myconfig.xml, the only difference is that ${daisy.datadir} is replaced with the path specified via the -d option.

Facultative options

-e <email-address>

Should exceptions occur during backup, notification emails can be sent to the specified address. These emails will contain the stacktrace of the exception. Do not forget to set the SMTP server using the next option.

-f <from-address>

This option allows users to specify the address sending exception notification emails.

-s <smtp-server>

Configures the smtp server to use to send emails in case of exceptions.

-a <entry-configuration-file>

If you want to backup other files you can create a configuration file to pass to the backup tool. In essence the configuration file contains a list of paths (files or directories) relative to a base directory. The content of these paths will be stored in a zip file in the backup directory.
Here is what the configuration file should look like:

<backup-entries>
  <backup-entry name="..." basedir="...">
    <paths>
      <path>...</path>
      ...
    </paths>
  </backup-entry>
  ...
</backup-entries>

And here is an example you might use to backup the Daisy Wiki files:

We don't simply backup the whole wikidata directory, as this would include the logs, which can become large. (a future feature might add an excludepath-option)

<?xml version="1.0" encoding="UTF-8"?>
<backup-entries>
  <backup-entry name="daisywiki" basedir="/home/daisy_user">
    <paths>
      <path>wikidata/books</path>
      <path>wikidata/bookstore</path>
      <path>wikidata/resources</path>
      <path>wikidata/sites</path>
      <path>wikidata/daisy.xconf</path>
      <path>wikidata/external-include-rules.xml</path>
    </paths>
  </backup-entry>
</backup-entries>

-v

Prints the version

-h

Shows the help

Postgresql notes

Supplying the Postgresql command line tools with a database password is not possible, therefore the Postgresql command line tools will prompt for a password when needed. However, there are some ways of bypassing the password prompt:

Password file

This password file is only used for the password prompt during a database dump. This means that it is only useful when you only want to automate backups. If you want to restore a database you will be prompted for a password twice, once for dropping the database and again for creating/restoring it. The password file is found here:

$HOME/.pgpass

This file MUST have the following permissions -rw------- (chmod 600)

It has this format :

host:port:databasename:username:password

Here is an example

localhost:*:daisyrepository:daisy:daisy

More information on the .pgpass file can be found here.

Trusted users

If you trust certain users they will not be prompted for passwords either. This is interesting when you couldn't be bothered to supply passwords to the command line during backup or restore. Information can be found here.
Example :

#TYPE   DATABASE    	USER    IP-ADDRESS        IP-MASK           METHOD
host    daisyrepository daisy   127.0.0.1         255.255.255.255   trust
host    template1       daisy   127.0.0.1         255.255.255.255   trust
host    all         	all     127.0.0.1         255.255.255.255   md5

Be sure to place the users you trust before the users you do not (md5)

The database 'template1' must also be added because during the restore of a database a connection must be made with the Postgresql server and some database (the template1 database is sure to exist).

Restoring a backup

If you need to restore a backup on a blank system, you first need to:

Install MySQL and create the daisyrepository and activemq databases and database users (see install instructions)
Download the Daisy version corresponding to the backup, and extract it somewhere. Define the DAISY_HOME environment variable to point to this location.
Install Java and let JAVA_HOME point to the location of your Java installation.

These items are described in more detail in the installation instructions.

What you don't need to do is running the installation scripts (daisy-repository-init, daisy-wiki-init, daisy-wiki-add-site), as these only serve to initialiase the database and configuration files, and when restoring a backup this is not needed since all this data and configuration comes from the backup.

Once this is done, use the backup tool with the -r option as described earlier.

Comments (0)