Update doc

[bacula/docs] / docs / manual / catmaintenance.tex

%%
%%

\section*{Catalog Maintenance}
\label{_ChapterStart12}
\index[general]{Maintenance!Catalog }
\index[general]{Catalog Maintenance }
\addcontentsline{toc}{section}{Catalog Maintenance}

Without proper setup and maintenance, your Catalog may continue to grow
indefinitely as you run Jobs and backup Files. How fast the size of your
Catalog grows depends on the number of Jobs you run and how many files they
backup. By deleting records within the database, you can make space available
for the new records that will be added during the next Job. By constantly
deleting old expired records (dates older than the Retention period), your
database size will remain constant. 

If you started with the default configuration files, they already contain
reasonable defaults for a small number of machines (less than 5), so if you
fall into that case, catalog maintenance will not be urgent if you have a few
hundred megabytes of disk space free. Whatever the case may be, some knowledge
of retention periods will be useful. 
\label{Retention}

\subsection*{Setting Retention Periods}
\index[general]{Setting Retention Periods }
\index[general]{Periods!Setting Retention }
\addcontentsline{toc}{subsection}{Setting Retention Periods}

{\bf Bacula} uses three Retention periods: the {\bf File Retention} period,
the {\bf Job Retention} period, and the {\bf Volume Retention} period. Of
these three, the File Retention period is by far the most important in
determining how large your database will become. 

The {\bf File Retention} and the {\bf Job Retention} are specified in each
Client resource as is shown below. The {\bf Volume Retention} period is
specified in the Pool resource, and the details are given in the next chapter
of this manual. 

\begin{description}

\item [File Retention = \lt{}time-period-specification\gt{}]
   \index[dir]{File Retention  }
   The  File Retention record defines the length of time that  Bacula will keep
File records in the Catalog database.  When this time period expires, and if
{\bf AutoPrune} is set to {\bf yes}, Bacula will prune (remove) File records
that  are older than the specified File Retention period. The pruning  will
occur at the end of a backup Job for the given Client.  Note that the Client
database record contains a copy of the  File and Job retention periods, but
Bacula uses the  current values found in the Director's Client resource to  do
the pruning.  

Since File records in the database account for probably 80 percent of the 
size of the database, you should carefully determine exactly what File
Retention period you need. Once the File records have been removed from
the database, you will no longer be able to restore individual files
in a Job. However, with Bacula version 1.37 and later, as long as the
Job record still exists, you will be able to restore all files in the
job.

Retention periods are specified in seconds, but as a convenience, there are
a number of modifiers that permit easy specification in terms of minutes,
hours, days, weeks, months, quarters, or years on the record.  See the
\ilink{ Configuration chapter}{Time} of this manual for additional details
of modifier specification.

The default File retention period is 60 days.  

\item [Job Retention = \lt{}time-period-specification\gt{}]
   \index[dir]{Job Retention  }
   The Job Retention record defines the length of time that {\bf Bacula}
will keep Job records in the Catalog database.  When this time period
expires, and if {\bf AutoPrune} is set to {\bf yes} Bacula will prune
(remove) Job records that are older than the specified Job Retention
period.  Note, if a Job record is selected for pruning, all associated File
and JobMedia records will also be pruned regardless of the File Retention
period set.  As a consequence, you normally will set the File retention
period to be less than the Job retention period.

As mentioned above, once the File records are removed from the database,
you will no longer be able to restore individual files from the Job.
However, as long as the Job record remains in the database, you will be
able to restore all the files backuped for the Job (on version 1.37 and 
later). As a consequence, it is generally a good idea to retain the Job
records much longer than the File records.

The retention period is specified in seconds, but as a convenience, there
are a number of modifiers that permit easy specification in terms of
minutes, hours, days, weeks, months, quarters, or years.  See the \ilink{
Configuration chapter}{Time} of this manual for additional details of
modifier specification.

The default Job Retention period is 180 days.  

\item [AutoPrune = \lt{}yes/no\gt{}]
   \index[dir]{AutoPrune  }
   If AutoPrune is set to  {\bf yes} (default), Bacula will  automatically apply
the File retention period and the Job  retention period for the Client at the
end of the Job.  

If you turn this off by setting it to {\bf no}, your  Catalog will grow each
time you run a Job. 
\end{description}

\label{CompactingMySQL}

\subsection*{Compacting Your MySQL Database}
\index[general]{Database!Compacting Your MySQL }
\index[general]{Compacting Your MySQL Database }
\addcontentsline{toc}{subsection}{Compacting Your MySQL Database}

Over time, as noted above, your database will tend to grow. I've noticed that
even though Bacula regularly prunes files, {\bf MySQL} does not effectively
use the space, and instead continues growing. To avoid this, from time to
time, you must compact your database. Normally, large commercial database such
as Oracle have commands that will compact a database to reclaim wasted file
space. MySQL has the {\bf OPTIMIZE TABLE} command that you can use, and SQLite
version 2.8.4 and greater has the {\bf VACUUM} command. We leave it to you to
explore the utility of the {\bf OPTIMIZE TABLE} command in MySQL. 

All database programs have some means of writing the database out in ASCII
format and then reloading it. Doing so will re-create the database from
scratch producing a compacted result, so below, we show you how you can do
this for MySQL, PostgreSQL and SQLite. 

For a {\bf MySQL} database, you could write the Bacula database as an ASCII
file (bacula.sql) then reload it by doing the following: 

\footnotesize
\begin{verbatim}
mysqldump -f --opt bacula > bacula.sql
mysql bacula < bacula.sql
rm -f bacula.sql
\end{verbatim}
\normalsize

Depending on the size of your database, this will take more or less time and a
fair amount of disk space. For example, if I cd to the location of the MySQL
Bacula database (typically /opt/mysql/var or something similar) and enter: 

\footnotesize
\begin{verbatim}
du bacula
\end{verbatim}
\normalsize

I get {\bf 620,644} which means there are that many blocks containing 1024
bytes each or approximately 635 MB of data. After doing the {\bf msqldump}, I
had a bacula.sql file that had {\bf 174,356} blocks, and after doing the {\bf
mysql} command to recreate the database, I ended up with a total of {\bf
210,464} blocks rather than the original {\bf 629,644}. In other words, the
compressed version of the database took approximately one third of the space
of the database that had been in use for about a year. 

As a consequence, I suggest you monitor the size of your database and from
time to time (once every 6 months or year), compress it. 
\label{RepairingMySQL}

\subsection*{Repairing Your MySQL Database}
\index[general]{Database!Repairing Your MySQL }
\index[general]{Repairing Your MySQL Database }
\addcontentsline{toc}{subsection}{Repairing Your MySQL Database}

If you find that you are getting errors writing to your MySQL database, or
Bacula hangs each time it tries to access the database, you should consider
running MySQL's database check and repair routines. The program you need to
run depends on the type of database indexing you are using. If you are using
the default, you will probably want to use {\bf myisamchk}. For more details
on how to do this, please consult the MySQL document at: 
\elink{
http://www.mysql.com/doc/en/Repair.html}
{http://www.mysql.com/doc/en/Repair.html}. 

If the errors you are getting are simply SQL warnings, then you might try
running dbcheck before (or possibly after) using the MySQL database repair
program. It can clean up many of the orphaned record problems, and certain
other inconsistencies in the Bacula database. 
\label{RepairingPSQL}

\subsection*{Repairing Your PostgreSQL Database}
\index[general]{Database!Repairing Your PostgreSQL }
\index[general]{Repairing Your PostgreSQL Database }
\addcontentsline{toc}{subsection}{Repairing Your PostgreSQL Database}

The same considerations apply that are indicated above for MySQL. That is,
consult the PostgreSQL documents for how to repair the database, and also
consider using Bacula's dbcheck program if the conditions are reasonable for
using (see above). 
\label{CompactingPostgres}

\subsection*{Performance Issues}
\index[general]{Database Performance Issues}
\index[general]{Performance!Database}
\addcontentsline{toc}{subsection}{Database Performance Issues}

There are a considerable number of ways each of the databases can be
tuned to improve the performance. Going from an untuned database to one
that is properly tuned can make a difference of a factor of 100 or more
in the time to insert or search for records.

For each of the databases, you may get significant improvements by adding
additional indexes. The comments in the Bacula make_xxx_tables give some
indications as to what indexes may be appropriate.

For MySQL, what seems to be very important is to use the examine the    
my.cnf file. You may obtain significant performances by switching to
the my-large.cnf or my-huge.cnf files that come with the MySQL source
code.

For SQLite3, one significant factor in improving the performance is
to ensure that there is a "PRAGMA synchronous = NORMAL;" statement.
This reduces the number of times that the database flushes the in memory
cache to disk. There are other settings for this PRAGMA that can 
give even further performance improvements at the risk of a database
corruption if your system crashes.

For PostgreSQL, you might want to consider turning fsync off.  Of course
doing so can cause corrupted databases in the even of a machine crash.
There are many different ways that you can tune PostgreSQL, the
following document discusses a few of them:
\elink{
http://www.varlena.com/varlena/GeneralBits/Tidbits/perf.html}
{http://www.varlena.com/varlena/GeneralBits/Tidbits/perf.html}.



\subsection*{Compacting Your PostgreSQL Database}
\index[general]{Database!Compacting Your PostgreSQL }
\index[general]{Compacting Your PostgreSQL Database }
\addcontentsline{toc}{subsection}{Compacting Your PostgreSQL Database}

Over time, as noted above, your database will tend to grow. I've noticed that
even though Bacula regularly prunes files, PostgreSQL has a {\bf VACUUM}
command that will compact your database for you. Alternatively you may want to
use the {\bf vacuumdb} command, which can be run from a cron job. 

All database programs have some means of writing the database out in ASCII
format and then reloading it. Doing so will re-create the database from
scratch producing a compacted result, so below, we show you how you can do
this for PostgreSQL. 

For a {\bf PostgreSQL} database, you could write the Bacula database as an
ASCII file (bacula.sql) then reload it by doing the following: 

\footnotesize
\begin{verbatim}
pg_dump bacula > bacula.sql
cat bacula.sql | psql bacula
rm -f bacula.sql
\end{verbatim}
\normalsize

Depending on the size of your database, this will take more or less time and a
fair amount of disk space. For example, you can {\bf cd} to the location of
the Bacula database (typically /usr/local/pgsql/data or possible
/var/lib/pgsql/data) and check the size. 

\subsection*{Compacting Your SQLite Database}
\index[general]{Compacting Your SQLite Database }
\index[general]{Database!Compacting Your SQLite }
\addcontentsline{toc}{subsection}{Compacting Your SQLite Database}

First please read the previous section that explains why it is necessary to
compress a database. SQLite version 2.8.4 and greater have the {\bf Vacuum}
command for compacting the database. 

\footnotesize
\begin{verbatim}
cd {\bf working-directory}
echo 'vacuum;' | sqlite bacula.db
\end{verbatim}
\normalsize

As an alternative, you can use the following commands, adapted to your system:


\footnotesize
\begin{verbatim}
cd {\bf working-directory}
echo '.dump' | sqlite bacula.db > bacula.sql
rm -f bacula.db
sqlite bacula.db < bacula.sql
rm -f bacula.sql
\end{verbatim}
\normalsize

Where {\bf working-directory} is the directory that you specified in the
Director's configuration file. Note, in the case of SQLite, it is necessary to
completely delete (rm) the old database before creating a new compressed
version. 

\subsection*{Migrating from SQLite to MySQL}
\index[general]{MySQL!Migrating from SQLite to }
\index[general]{Migrating from SQLite to MySQL }
\addcontentsline{toc}{subsection}{Migrating from SQLite to MySQL}

You may begin using Bacula with SQLite then later find that you want to switch
to MySQL for any of a number of reasons: SQLite tends to use more disk than
MySQL, SQLite apparently does not handle database sizes greater than 2GBytes,
... Several users have done so by first producing an ASCII "dump" of the
SQLite database, then creating the MySQL tables with the {\bf
create\_mysql\_tables} script that comes with Bacula, and finally feeding the
SQLite dump into MySQL using the {\bf -f} command line option to continue past
the errors that are generated by the DDL statements that SQLite's dump
creates. Of course, you could edit the dump and remove the offending
statements. Otherwise, MySQL accepts the SQL produced by SQLite. 

\label{BackingUpBacula}
\subsection*{Backing Up Your Bacula Database}
\index[general]{Backing Up Your Bacula Database }
\index[general]{Database!Backing Up Your Bacula }
\addcontentsline{toc}{subsection}{Backing Up Your Bacula Database}

If ever the machine on which your Bacula database crashes, and you need to
restore from backup tapes, one of your first priorities will probably be to
recover the database. Although Bacula will happily backup your catalog
database if it is specified in the FileSet, this is not a very good way to do
it, because the database will be saved while Bacula is modifying it. Thus the
database may be in an instable state. Worse yet, you will backup the database
before all the Bacula updates have been applied. 

To resolve these problems, you need to backup the database after all the backup
jobs have been run. In addition, you will want to make a copy while Bacula is
not modifying it. To do so, you can use two scripts provided in the release
{\bf make\_catalog\_backup} and {\bf delete\_catalog\_backup}. These files
will be automatically generated along with all the other Bacula scripts. The
first script will make an ASCII copy of your Bacula database into {\bf
bacula.sql} in the working directory you specified in your configuration, and
the second will delete the {\bf bacula.sql} file. 

The basic sequence of events to make this work correctly is as follows: 

\begin{itemize}
\item Run all your nightly backups  
\item After running your nightly backups, run a Catalog backup Job  
\item The Catalog backup job must be scheduled after your last nightly backup 

\item You use {\bf RunBeforeJob} to create the ASCII  backup file and {\bf
   RunAfterJob} to clean up 
   \end{itemize}

Assuming that you start all your nightly backup jobs at 1:05 am (and that they
run one after another), you can do the catalog backup with the following
additional Director configuration statements: 

\footnotesize
\begin{verbatim}
# Backup the catalog database (after the nightly save)
Job {
  Name = "BackupCatalog"
  Type = Backup
  Client=rufus-fd
  FileSet="Catalog"
  Schedule = "WeeklyCycleAfterBackup"
  Storage = DLTDrive
  Messages = Standard
  Pool = Default
  RunBeforeJob = "/home/kern/bacula/bin/make_catalog_backup"
  RunAfterJob  = "/home/kern/bacula/bin/delete_catalog_backup"
  Write Bootstrap = "/home/kern/bacula/working/BackupCatalog.bsr"
}
# This schedule does the catalog. It starts after the WeeklyCycle
Schedule {
  Name = "WeeklyCycleAfterBackup
  Run = Full sun-sat at 1:10
}
# This is the backup of the catalog
FileSet {
  Name = "Catalog"
  Include = signature=MD5 {
     @working_directory@/bacula.sql
  }
}
\end{verbatim}
\normalsize

Be sure to write a bootstrap file as in the above example. It is preferable
to write or copy the bootstrap file to another computer. It will allow
you to quickly recover the database backup should that be necessary.  If
you do not have a bootstrap file, it is still possible to recover your
database backup, but it will be more work and take longer. 

\label{BackingUPOtherDBs}
\subsection*{Backing Up Third Party Databases}
\index[general]{Backing Up Third Party Databases }
\index[general]{Databases!Backing Up Third Party }
\addcontentsline{toc}{subsection}{Backing Up Third Party Databases}

If you are running a database in production mode on your machine, Bacula will
happily backup the files, but if the database is in use while Bacula is
reading it, you may back it up in an unstable state. 

The best solution is to shutdown your database before backing it up, or use
some tool specific to your database to make a valid live copy perhaps by
dumping the database in ASCII format. I am not a database expert, so I cannot
provide you advice on how to do this, but if you are unsure about how to
backup your database, you might try visiting the Backup Central site, which
has been renamed Storage Mountain (www.backupcentral.com). In particular,
their 
\elink{ Free Backup and Recovery
Software}{http://www.backupcentral.com/toc-free-backup-software.html} page has
links to scripts that show you how to shutdown and backup most major
databases. 
\label{Size}

\subsection*{Database Size}
\index[general]{Size!Database }
\index[general]{Database Size }
\addcontentsline{toc}{subsection}{Database Size}

As mentioned above, if you do not do automatic pruning, your Catalog will grow
each time you run a Job. Normally, you should decide how long you want File
records to be maintained in the Catalog and set the {\bf File Retention}
period to that time. Then you can either wait and see how big your Catalog
gets or make a calculation assuming approximately 154 bytes for each File
saved and knowing the number of Files that are saved during each backup and
the number of Clients you backup. 

For example, suppose you do a backup of two systems, each with 100,000 files.
Suppose further that you do a Full backup weekly and an Incremental every day,
and that the Incremental backup typically saves 4,000 files. The size of your
database after a month can roughly be calculated as: 

\footnotesize
\begin{verbatim}
   Size = 154 * No. Systems * (100,000 * 4 + 10,000 * 26)
\end{verbatim}
\normalsize

where we have assumed 4 weeks in a month and 26 incremental backups per month.
This would give the following: 

\footnotesize
\begin{verbatim}
   Size = 154 * 2 * (100,000 * 4 + 10,000 * 26)
or
   Size = 308 * (400,000 + 260,000)
or
   Size = 203,280,000 bytes
\end{verbatim}
\normalsize

So for the above two systems, we should expect to have a database size of
approximately 200 Megabytes. Of course, this will vary according to how many
files are actually backed up. 

Below are some statistics for a MySQL database containing Job records for five
Clients beginning September 2001 through May 2002 (8.5 months) and File
records for the last 80 days. (Older File records have been pruned). For these
systems, only the user files and system files that change are backed up. The
core part of the system is assumed to be easily reloaded from the RedHat rpms.


In the list below, the files (corresponding to Bacula Tables) with the
extension .MYD contain the data records whereas files with the extension .MYI
contain indexes. 

You will note that the File records (containing the file attributes) make up
the large bulk of the number of records as well as the space used (459 Mega
Bytes including the indexes). As a consequence, the most important Retention
period will be the {\bf File Retention} period. A quick calculation shows that
for each File that is saved, the database grows by approximately 150 bytes. 

\footnotesize
\begin{verbatim}
      Size in
       Bytes   Records    File
 ============  =========  ===========
          168          5  Client.MYD
        3,072             Client.MYI
  344,394,684  3,080,191  File.MYD
  115,280,896             File.MYI
    2,590,316    106,902  Filename.MYD
    3,026,944             Filename.MYI
          184          4  FileSet.MYD
        2,048             FileSet.MYI
       49,062      1,326  JobMedia.MYD
       30,720             JobMedia.MYI
      141,752      1,378  Job.MYD
       13,312             Job.MYI
        1,004         11  Media.MYD
        3,072             Media.MYI
    1,299,512     22,233  Path.MYD
      581,632             Path.MYI
           36          1  Pool.MYD
        3,072             Pool.MYI
            5          1  Version.MYD
        1,024             Version.MYI
\end{verbatim}
\normalsize

This database has a total size of approximately 450 Megabytes. 

If we were using SQLite, the determination of the total database size would be
much easier since it is a single file, but we would have less insight to the
size of the individual tables as we have in this case. 

Note, SQLite databases may be as much as 50\% larger than MySQL databases due
to the fact that all data is stored as ASCII strings. That is even binary
integers are stored as ASCII strings, and this seems to increase the space
needed.