10.15.2 Running the backup tool

10.15.2.1 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.

10.15.2.2 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>][-q]
 -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
 -q,--quiet-restore                                   Suppress confirmation dialog while
                                                      restoring an existing backup
 -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 in case 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

10.15.2.3 Compulsory options

10.15.2.3.1 -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.

10.15.2.3.2 -l <backup-path>

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

10.15.2.3.3 -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.

10.15.2.4 Facultative options

10.15.2.4.1 -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.

10.15.2.4.2 -f <from-address>

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

10.15.2.4.3 -s <smtp-server>

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

10.15.2.4.4 -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>

10.15.2.4.5 -q

Suppress the confirmation dialog prior to restoring an existing backup. This might be useful if you would like to restore a backup inside a batch file that has to run without manual intervention.

10.15.2.4.6 -v

Prints the version

10.15.2.4.7 -h

Shows the help

10.15.2.5 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:

10.15.2.5.1 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.

10.15.2.5.2 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).