--- /dev/null
+#
+#
+# Makefile for LaTeX
+#
+# To build everything do
+# make tex
+# make web
+# make html
+# make dvipdf
+#
+# or simply
+#
+# make
+#
+# for rapid development do:
+# make tex
+# make show
+#
+#
+# If you are having problems getting "make" to work, debugging it is
+# easier if can see the output from latex, which is normally redirected
+# to /dev/null. To see it, do the following:
+#
+# cd docs/manual
+# make tex
+# latex bacula.tex
+#
+# typically the latex command will stop indicating the error (e.g. a
+# missing \ in front of a _ or a missing { or ] ...
+#
+# The following characters must be preceded by a backslash
+# to be entered as printable characters:
+#
+# # $ % & ~ _ ^ \ { }
+#
+
+IMAGES=../../../images
+
+DOC=catalog
+
+first_rule: all
+
+all: tex web dvipdf mini-clean
+
+.SUFFIXES: .tex .html
+.PHONY:
+.DONTCARE:
+
+
+tex:
+ @./update_version
+ @echo "Making version `cat version.tex`"
+ @cp -fp ${IMAGES}/hires/*.eps .
+ @touch ${DOC}i-dir.tex ${DOC}i-fd.tex ${DOC}i-sd.tex \
+ ${DOC}i-console.tex ${DOC}i-general.tex
+ latex -interaction=batchmode ${DOC}.tex
+ makeindex ${DOC}.idx -o ${DOC}.ind 2>/dev/null
+ latex -interaction=batchmode ${DOC}.tex
+
+pdf:
+ @echo "Making pdfm"
+ @cp -fp ${IMAGES}/hires/*.eps .
+ dvipdfm -p a4 ${DOC}.dvi
+
+dvipdf:
+ @echo "Making dvi to pdf"
+ @cp -fp ${IMAGES}/hires/*.eps .
+ dvipdf ${DOC}.dvi ${DOC}.pdf
+
+html:
+ @echo " "
+ @echo "Making html"
+ @cp -fp ${IMAGES}/*.eps .
+ @rm -f next.eps next.png prev.eps prev.png up.eps up.png
+ @(if [ -f imagename_translations ] ; then \
+ ./translate_images.pl --from_meaningful_names ${DOC}.html; \
+ fi)
+ latex2html -white -no_subdir -split 0 -toc_stars -white -notransparent \
+ -init_file latex2html-init.pl ${DOC} >tex.out 2>&1
+ ./translate_images.pl --to_meaningful_names ${DOC}.html
+ @echo "Done making html"
+
+web:
+ @echo "Making web"
+ @mkdir -p ${DOC}
+ @cp -fp ${IMAGES}/*.eps .
+ @rm -f next.eps next.png prev.eps prev.png up.eps up.png
+ @cp -fp ${IMAGES}/*.eps ${DOC}/
+ @cp -fp ${IMAGES}/*.eps ${IMAGES}/*.png ${DOC}/
+ @rm -f ${DOC}/xp-*.png
+ @rm -f ${DOC}/next.eps ${DOC}/next.png ${DOC}/prev.eps ${DOC}/prev.png ${DOC}/up.eps ${DOC}/up.png
+ @rm -rf ${DOC}/*.html
+ latex2html -split 3 -local_icons -t "Bacula Catalog Database Guide" -long_titles 4 \
+ -toc_stars -contents_in_nav -init_file latex2html-init.pl -white -notransparent ${DOC} >tex.out 2>&1
+ ./translate_images.pl --to_meaningful_names ${DOC}/Bacula_Catalo*.html
+ @echo "Done making web"
+show:
+ xdvi ${DOC}
+
+texcheck:
+ ./check_tex.pl ${DOC}.tex
+
+main_configs:
+ pic2graph -density 100 <main_configs.pic >main_configs.png
+
+mini-clean:
+ @rm -f 1 2 3 *.tex~
+ @rm -f *.gif *.jpg *.eps
+ @rm -f *.aux *.cp *.fn *.ky *.log *.pg
+ @rm -f *.backup *.ilg *.lof *.lot
+ @rm -f *.cdx *.cnd *.ddx *.ddn *.fdx *.fnd *.ind *.sdx *.snd
+ @rm -f *.dnd *.old *.out
+ @rm -f ${DOC}/*.gif ${DOC}/*.jpg ${DOC}/*.eps
+ @rm -f ${DOC}/*.aux ${DOC}/*.cp ${DOC}/*.fn ${DOC}/*.ky ${DOC}/*.log ${DOC}/*.pg
+ @rm -f ${DOC}/*.backup ${DOC}/*.ilg ${DOC}/*.lof ${DOC}/*.lot
+ @rm -f ${DOC}/*.cdx ${DOC}/*.cnd ${DOC}/*.ddx ${DOC}/*.ddn ${DOC}/*.fdx ${DOC}/*.fnd ${DOC}/*.ind ${DOC}/*.sdx ${DOC}/*.snd
+ @rm -f ${DOC}/*.dnd ${DOC}/*.old ${DOC}/*.out
+ @rm -f ${DOC}/WARNINGS
+
+
+clean:
+ @rm -f 1 2 3 *.tex~
+ @rm -f *.png *.gif *.jpg *.eps
+ @rm -f *.pdf *.aux *.cp *.fn *.ky *.log *.pg
+ @rm -f *.html *.backup *.ps *.dvi *.ilg *.lof *.lot
+ @rm -f *.cdx *.cnd *.ddx *.ddn *.fdx *.fnd *.ind *.sdx *.snd
+ @rm -f *.dnd imagename_translations
+ @rm -f *.old WARNINGS *.out *.toc *.idx
+ @rm -f ${DOC}i-*.tex
+ @rm -rf ${DOC}
+
+
+distclean: clean
+ @rm -f images.pl labels.pl internals.pl
+ @rm -f Makefile version.tex
--- /dev/null
+#
+#
+# Makefile for LaTeX
+#
+# To build everything do
+# make tex
+# make web
+# make html
+# make dvipdf
+#
+# or simply
+#
+# make
+#
+# for rapid development do:
+# make tex
+# make show
+#
+#
+# If you are having problems getting "make" to work, debugging it is
+# easier if can see the output from latex, which is normally redirected
+# to /dev/null. To see it, do the following:
+#
+# cd docs/manual
+# make tex
+# latex bacula.tex
+#
+# typically the latex command will stop indicating the error (e.g. a
+# missing \ in front of a _ or a missing { or ] ...
+#
+# The following characters must be preceded by a backslash
+# to be entered as printable characters:
+#
+# # $ % & ~ _ ^ \ { }
+#
+
+IMAGES=../../../images
+
+DOC=catalog
+
+first_rule: all
+
+all: tex web dvipdf mini-clean
+
+.SUFFIXES: .tex .html
+.PHONY:
+.DONTCARE:
+
+
+tex:
+ @./update_version
+ @echo "Making version `cat version.tex`"
+ @cp -fp ${IMAGES}/hires/*.eps .
+ @touch ${DOC}i-dir.tex ${DOC}i-fd.tex ${DOC}i-sd.tex \
+ ${DOC}i-console.tex ${DOC}i-general.tex
+ latex -interaction=batchmode ${DOC}.tex
+ makeindex ${DOC}.idx -o ${DOC}.ind 2>/dev/null
+ latex -interaction=batchmode ${DOC}.tex
+
+pdf:
+ @echo "Making pdfm"
+ @cp -fp ${IMAGES}/hires/*.eps .
+ dvipdfm -p a4 ${DOC}.dvi
+
+dvipdf:
+ @echo "Making dvi to pdf"
+ @cp -fp ${IMAGES}/hires/*.eps .
+ dvipdf ${DOC}.dvi ${DOC}.pdf
+
+html:
+ @echo " "
+ @echo "Making html"
+ @cp -fp ${IMAGES}/*.eps .
+ @rm -f next.eps next.png prev.eps prev.png up.eps up.png
+ @(if [ -f imagename_translations ] ; then \
+ ./translate_images.pl --from_meaningful_names ${DOC}.html; \
+ fi)
+ latex2html -white -no_subdir -split 0 -toc_stars -white -notransparent \
+ -init_file latex2html-init.pl ${DOC} >tex.out 2>&1
+ ./translate_images.pl --to_meaningful_names ${DOC}.html
+ @echo "Done making html"
+
+web:
+ @echo "Making web"
+ @mkdir -p ${DOC}
+ @cp -fp ${IMAGES}/*.eps .
+ @rm -f next.eps next.png prev.eps prev.png up.eps up.png
+ @cp -fp ${IMAGES}/*.eps ${DOC}/
+ @cp -fp ${IMAGES}/*.eps ${IMAGES}/*.png ${DOC}/
+ @rm -f ${DOC}/xp-*.png
+ @rm -f ${DOC}/next.eps ${DOC}/next.png ${DOC}/prev.eps ${DOC}/prev.png ${DOC}/up.eps ${DOC}/up.png
+ @rm -rf ${DOC}/*.html
+ latex2html -split 3 -local_icons -t "Bacula Catalog Database Guide" -long_titles 4 \
+ -toc_stars -contents_in_nav -init_file latex2html-init.pl -white -notransparent ${DOC} >tex.out 2>&1
+ ./translate_images.pl --to_meaningful_names ${DOC}/Bacula_Catalo*.html
+ @echo "Done making web"
+show:
+ xdvi ${DOC}
+
+texcheck:
+ ./check_tex.pl ${DOC}.tex
+
+main_configs:
+ pic2graph -density 100 <main_configs.pic >main_configs.png
+
+mini-clean:
+ @rm -f 1 2 3 *.tex~
+ @rm -f *.gif *.jpg *.eps
+ @rm -f *.aux *.cp *.fn *.ky *.log *.pg
+ @rm -f *.backup *.ilg *.lof *.lot
+ @rm -f *.cdx *.cnd *.ddx *.ddn *.fdx *.fnd *.ind *.sdx *.snd
+ @rm -f *.dnd *.old *.out
+ @rm -f ${DOC}/*.gif ${DOC}/*.jpg ${DOC}/*.eps
+ @rm -f ${DOC}/*.aux ${DOC}/*.cp ${DOC}/*.fn ${DOC}/*.ky ${DOC}/*.log ${DOC}/*.pg
+ @rm -f ${DOC}/*.backup ${DOC}/*.ilg ${DOC}/*.lof ${DOC}/*.lot
+ @rm -f ${DOC}/*.cdx ${DOC}/*.cnd ${DOC}/*.ddx ${DOC}/*.ddn ${DOC}/*.fdx ${DOC}/*.fnd ${DOC}/*.ind ${DOC}/*.sdx ${DOC}/*.snd
+ @rm -f ${DOC}/*.dnd ${DOC}/*.old ${DOC}/*.out
+ @rm -f ${DOC}/WARNINGS
+
+
+clean:
+ @rm -f 1 2 3 *.tex~
+ @rm -f *.png *.gif *.jpg *.eps
+ @rm -f *.pdf *.aux *.cp *.fn *.ky *.log *.pg
+ @rm -f *.html *.backup *.ps *.dvi *.ilg *.lof *.lot
+ @rm -f *.cdx *.cnd *.ddx *.ddn *.fdx *.fnd *.ind *.sdx *.snd
+ @rm -f *.dnd imagename_translations
+ @rm -f *.old WARNINGS *.out *.toc *.idx
+ @rm -f ${DOC}i-*.tex
+ @rm -rf ${DOC}
+
+
+distclean: clean
+ @rm -f images.pl labels.pl internals.pl
+ @rm -f Makefile version.tex
--- /dev/null
+/* Century Schoolbook font is very similar to Computer Modern Math: cmmi */
+.MATH { font-family: "Century Schoolbook", serif; }
+.MATH I { font-family: "Century Schoolbook", serif; font-style: italic }
+.BOLDMATH { font-family: "Century Schoolbook", serif; font-weight: bold }
+
+/* implement both fixed-size and relative sizes */
+SMALL.XTINY { font-size : xx-small }
+SMALL.TINY { font-size : x-small }
+SMALL.SCRIPTSIZE { font-size : smaller }
+SMALL.FOOTNOTESIZE { font-size : small }
+SMALL.SMALL { }
+BIG.LARGE { }
+BIG.XLARGE { font-size : large }
+BIG.XXLARGE { font-size : x-large }
+BIG.HUGE { font-size : larger }
+BIG.XHUGE { font-size : xx-large }
+
+/* heading styles */
+H1 { }
+H2 { }
+H3 { }
+H4 { }
+H5 { }
+
+/* mathematics styles */
+DIV.displaymath { } /* math displays */
+TD.eqno { } /* equation-number cells */
+
+
+/* document-specific styles come next */
--- /dev/null
+%%
+%%
+%% The following characters must be preceded by a backslash
+%% to be entered as printable characters:
+%%
+%% # $ % & ~ _ ^ \ { }
+%%
+
+\documentclass[11pt,a4paper]{book}
+\usepackage{html}
+\usepackage{float}
+\usepackage{graphicx}
+\usepackage{bacula}
+\usepackage{longtable}
+\usepackage{makeidx}
+\usepackage{index}
+\usepackage{setspace}
+\usepackage{hyperref}
+\usepackage{url}
+
+
+\makeindex
+\newindex{general}{idx}{ind}{General Index}
+
+\sloppy
+
+\begin{document}
+\sloppy
+
+\newfont{\bighead}{cmr17 at 36pt}
+\parskip 10pt
+\parindent 0pt
+
+\title{\includegraphics{./bacula-logo.eps} \\ \bigskip
+ \Huge{Bacula Catalog Database Guide}
+ \begin{center}
+ \large{It comes in the night and sucks
+ the essence from your computers. }
+ \end{center}
+}
+
+
+\author{Kern Sibbald}
+\date{\vspace{1.0in}\today \\
+ This manual documents Bacula version \input{version} \\
+ \vspace{0.2in}
+ Copyright \copyright 1999-2007, Free Software Foundation Europe
+ e.V. \\
+ \vspace{0.2in}
+ Permission is granted to copy, distribute and/or modify this document under the terms of the
+ GNU Free Documentation License, Version 1.2 published by the Free Software Foundation;
+ with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+ A copy of the license is included in the section entitled "GNU Free Documentation License".
+}
+
+\maketitle
+
+\clearpage
+\tableofcontents
+\clearpage
+\listoffigures
+\clearpage
+\listoftables
+\clearpage
+
+\include{catmaintenance}
+\include{mysql}
+\include{postgresql}
+\include{sqlite}
+\include{internaldb}
+\include{fdl}
+
+
+% The following line tells link_resolver.pl to not include these files:
+% nolinks developersi baculai-dir baculai-fd baculai-sd baculai-console baculai-main
+
+% pull in the index
+\clearpage
+\printindex[general]
+
+\end{document}
--- /dev/null
+%%
+%%
+
+\chapter{Catalog Maintenance}
+\label{CatMaintenanceChapter}
+\index[general]{Maintenance!Catalog }
+\index[general]{Catalog Maintenance }
+
+Without proper setup and maintenance, your Catalog may continue to grow
+indefinitely as you run Jobs and backup Files, and/or it may become
+very inefficient and slow. 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}
+
+\section{Setting Retention Periods}
+\index[general]{Setting Retention Periods }
+\index[general]{Periods!Setting Retention }
+
+{\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[general]{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[general]{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[general]{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}
+\section{Compacting Your MySQL Database}
+\index[general]{Database!Compacting Your MySQL }
+\index[general]{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 mysqldump}, 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 six months or year), compress it.
+
+\label{DatabaseRepair}
+\label{RepairingMySQL}
+\section{Repairing Your MySQL Database}
+\index[general]{Database!Repairing Your MySQL }
+\index[general]{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.
+
+A typical cause of MySQL database problems is if your partition fills. In
+such a case, you will need to create additional space on the partition or
+free up some space then repair the database probably using {\bf myisamchk}.
+Recently my root partition filled and the MySQL database was corrupted.
+Simply running {\bf myisamchk -r} did not fix the problem. However,
+the following script did the trick for me:
+
+\footnotesize
+\begin{verbatim}
+#!/bin/sh
+for i in *.MYD ; do
+ mv $i x${i}
+ t=`echo $i | cut -f 1 -d '.' -`
+ mysql bacula <<END_OF_DATA
+set autocommit=1;
+truncate table $t;
+quit
+END_OF_DATA
+ cp x${i} ${i}
+ chown mysql:mysql ${i}
+ myisamchk -r ${t}
+done
+\end{verbatim}
+\normalsize
+
+I invoked it with the following commands:
+
+\footnotesize
+\begin{verbatim}
+cd /var/lib/mysql/bacula
+./repair
+\end{verbatim}
+\normalsize
+
+Then after ensuring that the database was correctly fixed, I did:
+\footnotesize
+\begin{verbatim}
+cd /var/lib/mysql/bacula
+rm -f x*.MYD
+\end{verbatim}
+\normalsize
+
+\section{MySQL Table is Full}
+\index[general]{Database!MySQL Table is Full}
+\index[general]{MySQL Table is Full}
+
+If you are running into the error {\bf The table 'File' is full ...},
+it is probably because on version 4.x MySQL, the table is limited by
+default to a maximum size of 4 GB and you have probably run into
+the limit. The solution can be found at:
+\elink{http://dev.mysql.com/doc/refman/5.0/en/full-table.html}
+{http://dev.mysql.com/doc/refman/5.0/en/full-table.html}
+
+You can display the maximum length of your table with:
+
+\footnotesize
+\begin{verbatim}
+mysql bacula
+SHOW TABLE STATUS FROM bacula like "File";
+\end{verbatim}
+\normalsize
+
+If the column labeled "Max\_data\_length" is around 4Gb, this is likely
+to be the source of your problem, and you can modify it with:
+
+\footnotesize
+\begin{verbatim}
+mysql bacula
+ALTER TABLE File MAX_ROWS=281474976710656;
+\end{verbatim}
+\normalsize
+
+Alternatively you can modify your /etc/my.conf file before creating the
+Bacula tables, and in the [mysqld] section set:
+
+\footnotesize
+\begin{verbatim}
+set-variable = myisam_data_pointer_size=6
+\end{verbatim}
+\normalsize
+
+The above myisam data pointer size must be made before you create your
+Bacula tables or it will have no effect.
+
+The row and pointer size changes should already be the default on MySQL
+version 5.x, so making these changes should only be necessary on MySQL 4.x
+depending on the size of your catalog database.
+
+\section{MySQL Server Has Gone Away}
+\index[general]{Database!MySQL Server Has Gone Away}
+\index[general]{MySQL Server Has Gone Away}
+If you are having problems with the MySQL server disconnecting or with
+messages saying that your MySQL server has gone away, then please read
+the MySQL documentation, which can be found at:
+
+\elink{http://dev.mysql.com/doc/refman/5.0/en/gone-away.html}
+{http://dev.mysql.com/doc/refman/5.0/en/gone-away.html}
+
+
+\label{RepairingPSQL}
+\section{Repairing Your PostgreSQL Database}
+\index[general]{Database!Repairing Your PostgreSQL }
+\index[general]{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{DatabasePerformance}
+\section{Database Performance Issues}
+\index[general]{Database Performance Issues}
+\index[general]{Performance!Database}
+
+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. Please see below
+for specific instructions on checking indexes.
+
+For MySQL, what is very important is to use the examine the
+my.cnf file (usually in /etc/my.cnf).
+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 event 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}.
+
+There is also a PostgreSQL FAQ question number 3.3 that may
+answer some of your questions about how to improve performance
+of the PostgreSQL engine:
+\elink{
+http://www.postgresql.org/docs/faqs.FAQ.html\#3.3}
+{http://www.postgresql.org/docs/faqs.FAQ.html\#3.3}.
+% TODO: verify above is correct. is this okay for book?
+
+Also for PostgreSQL, look at what "effective\_cache\_size". For a 2GB memory
+machine, you probably want to set it at 131072, but don't set it too high.
+In addition, for a 2GB system, work\_mem = 256000 and
+maintenance\_work\_mem = 256000 seem to be reasonable values. Make
+sure your checkpoint\_segments is set to at least 8.
+
+
+
+\section{Performance Issues Indexes}
+\index[general]{Database Performance Issues Indexes}
+\index[general]{Performance!Database}
+One of the most important considerations for improving performance on
+the Bacula database is to ensure that it has all the appropriate indexes.
+Several users have reported finding that their database did not have
+all the indexes in the default configuration. In addition, you may
+find that because of your own usage patterns, you need additional indexes.
+
+The most important indexes for performance are the three indexes on the
+{\bf File} table. The first index is on {\bf FileId} and is automatically
+made because it is the unique key used to access the table. The other
+two are the JobId index and the (Filename, PathId) index. If these Indexes
+are not present, your performance may suffer a lot.
+
+\subsection{PostgreSQL Indexes}
+On PostgreSQL, you can check to see if you have the proper indexes using
+the following commands:
+
+\footnotesize
+\begin{verbatim}
+psql bacula
+select * from pg_indexes where tablename='file';
+\end{verbatim}
+\normalsize
+
+If you do not see output that indicates that all three indexes
+are created, you can create the two additional indexes using:
+
+\footnotesize
+\begin{verbatim}
+psql bacula
+CREATE INDEX file_jobid_idx on file (jobid);
+CREATE INDEX file_fp_idx on file (filenameid, pathid);
+\end{verbatim}
+\normalsize
+
+\subsection{MySQL Indexes}
+On MySQL, you can check if you have the proper indexes by:
+
+\footnotesize
+\begin{verbatim}
+mysql bacula
+show index from File;
+\end{verbatim}
+\normalsize
+
+If the indexes are not present, especially the JobId index, you can
+create them with the following commands:
+
+\footnotesize
+\begin{verbatim}
+mysql bacula
+CREATE INDEX file_jobid_idx on File (JobId);
+CREATE INDEX file_jpf_idx on File (Job, FilenameId, PathId);
+\end{verbatim}
+\normalsize
+
+Though normally not a problem, you should ensure that the indexes
+defined for Filename and Path are both set to 255 characters. Some users
+reported performance problems when their indexes were set to 50 characters.
+To check, do:
+
+\footnotesize
+\begin{verbatim}
+mysql bacula
+show index from Filename;
+show index from Path;
+\end{verbatim}
+\normalsize
+
+and what is important is that for Filename, you have an index with
+Key\_name "Name" and Sub\_part "255". For Path, you should have a Key\_name
+"Path" and Sub\_part "255". If one or the other does not exist or the
+Sub\_part is less that 255, you can drop and recreate the appropriate
+index with:
+
+\footnotesize
+\begin{verbatim}
+mysql bacula
+DROP INDEX Path on Path;
+CREATE INDEX Path on Path (Path(255);
+
+DROP INDEX Name on Filename;
+CREATE INDEX Name on Filename (Name(255));
+\end{verbatim}
+\normalsize
+
+
+\subsection{SQLite Indexes}
+On SQLite, you can check if you have the proper indexes by:
+
+\footnotesize
+\begin{verbatim}
+sqlite <path>bacula.db
+select * from sqlite_master where type='index' and tbl_name='File';
+\end{verbatim}
+\normalsize
+
+If the indexes are not present, especially the JobId index, you can
+create them with the following commands:
+
+\footnotesize
+\begin{verbatim}
+mysql bacula
+CREATE INDEX file_jobid_idx on File (JobId);
+CREATE INDEX file_jfp_idx on File (Job, FilenameId, PathId);
+\end{verbatim}
+\normalsize
+
+
+
+\label{CompactingPostgres}
+\section{Compacting Your PostgreSQL Database}
+\index[general]{Database!Compacting Your PostgreSQL }
+\index[general]{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 -c 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.
+
+There are certain PostgreSQL users who do not recommend the above
+procedure. They have the following to say:
+PostgreSQL does not
+need to be dumped/restored to keep the database efficient. A normal
+process of vacuuming will prevent the database from every getting too
+large. If you want to fine-tweak the database storage, commands such
+as VACUUM FULL, REINDEX, and CLUSTER exist specifically to keep you
+from having to do a dump/restore.
+
+Finally, you might want to look at the PostgreSQL documentation on
+this subject at
+\elink{http://www.postgresql.org/docs/8.1/interactive/maintenance.html}
+{http://www.postgresql.org/docs/8.1/interactive/maintenance.html}.
+
+\section{Compacting Your SQLite Database}
+\index[general]{Compacting Your SQLite Database }
+\index[general]{Database!Compacting Your SQLite }
+
+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.
+
+\section{Migrating from SQLite to MySQL}
+\index[general]{MySQL!Migrating from SQLite to }
+\index[general]{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; when the database is corrupted it is often more catastrophic than
+with MySQL or PostgreSQL.
+Several users have succeeded in converting from SQLite to MySQL by
+exporting the MySQL data and then processing it with Perl scripts
+prior to putting it into MySQL. This is, however, not a simple
+process.
+
+\label{BackingUpBacula}
+\section{Backing Up Your Bacula Database}
+\index[general]{Backing Up Your Bacula Database }
+\index[general]{Database!Backing Up Your Bacula }
+
+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
+ # WARNING!!! Passing the password via the command line is insecure.
+ # see comments in make_catalog_backup for details.
+ 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 = Level=Full sun-sat at 1:10
+}
+# This is the backup of the catalog
+FileSet {
+ Name = "Catalog"
+ Include {
+ Options {
+ signature=MD5
+ }
+ File = \lt{}working_directory\gt{}/bacula.sql
+ }
+}
+\end{verbatim}
+\normalsize
+
+Be sure to write a bootstrap file as in the above example. However, 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{BackingUpBaculaSecurityConsiderations}
+\section{Security considerations}
+\index[general]{Backing Up Your Bacula Database - Security Considerations }
+\index[general]{Database!Backing Up Your Bacula Database - Security Considerations }
+
+We provide make\_catalog\_backup as an example of what can be used to backup
+your Bacula database. We expect you to take security precautions relevant
+to your situation. make\_catalog\_backup is designed to take a password on
+the command line. This is fine on machines with only trusted users. It is
+not acceptable on machines without trusted users. Most database systems
+provide a alternative method, which does not place the password on the
+command line.
+
+The make\_catalog\_backup script contains some warnings about how to use it. Please
+read those tips.
+
+To help you get started, we know PostgreSQL has a password file,
+\elink{
+.pgpass}{http://www.postgresql.org/docs/8.2/static/libpq-pgpass.html}, and
+we know MySQL has
+\elink{ .my.cnf}{http://dev.mysql.com/doc/refman/4.1/en/password-security.html}.
+
+Only you can decide what is appropriate for your situation. We have provided
+you with a starting point. We hope it helps.
+
+
+\label{BackingUPOtherDBs}
+\section{Backing Up Third Party Databases}
+\index[general]{Backing Up Third Party Databases }
+\index[general]{Databases!Backing Up Third Party }
+
+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}
+
+\section{Database Size}
+\index[general]{Size!Database }
+\index[general]{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 four 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 Red Hat 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.
--- /dev/null
+#!/usr/bin/perl -w
+# Finds potential problems in tex files, and issues warnings to the console
+# about what it finds. Takes a list of files as its only arguments,
+# and does checks on all the files listed. The assumption is that these are
+# valid (or close to valid) LaTeX files. It follows \include statements
+# recursively to pick up any included tex files.
+#
+#
+#
+# Currently the following checks are made:
+#
+# -- Multiple hyphens not inside a verbatim environment (or \verb). These
+# should be placed inside a \verb{} contruct so they will not be converted
+# to single hyphen by latex and latex2html.
+
+
+# Original creation 3-8-05 by Karl Cunningham karlc -at- keckec -dot- com
+#
+#
+
+use strict;
+
+# The following builds the test string to identify and change multiple
+# hyphens in the tex files. Several constructs are identified but only
+# multiple hyphens are changed; the others are fed to the output
+# unchanged.
+my $b = '\\\\begin\\*?\\s*\\{\\s*'; # \begin{
+my $e = '\\\\end\\*?\\s*\\{\\s*'; # \end{
+my $c = '\\s*\\}'; # closing curly brace
+
+# This captures entire verbatim environments. These are passed to the output
+# file unchanged.
+my $verbatimenv = $b . "verbatim" . $c . ".*?" . $e . "verbatim" . $c;
+
+# This captures \verb{..{ constructs. They are passed to the output unchanged.
+my $verb = '\\\\verb\\*?(.).*?\\1';
+
+# This captures multiple hyphens with a leading and trailing space. These are not changed.
+my $hyphsp = '\\s\\-{2,}\\s';
+
+# This identifies other multiple hyphens.
+my $hyphens = '\\-{2,}';
+
+# This identifies \hyperpage{..} commands, which should be ignored.
+my $hyperpage = '\\\\hyperpage\\*?\\{.*?\\}';
+
+# This builds the actual test string from the above strings.
+#my $teststr = "$verbatimenv|$verb|$tocentry|$hyphens";
+my $teststr = "$verbatimenv|$verb|$hyphsp|$hyperpage|$hyphens";
+
+
+sub get_includes {
+ # Get a list of include files from the top-level tex file. The first
+ # argument is a pointer to the list of files found. The rest of the
+ # arguments is a list of filenames to check for includes.
+ my $files = shift;
+ my ($fileline,$includefile,$includes);
+
+ while (my $filename = shift) {
+ # Get a list of all the html files in the directory.
+ open my $if,"<$filename" or die "Cannot open input file $filename\n";
+ $fileline = 0;
+ $includes = 0;
+ while (<$if>) {
+ chomp;
+ $fileline++;
+ # If a file is found in an include, process it.
+ if (($includefile) = /\\include\s*\{(.*?)\}/) {
+ $includes++;
+ # Append .tex to the filename
+ $includefile .= '.tex';
+
+ # If the include file has already been processed, issue a warning
+ # and don't do it again.
+ my $found = 0;
+ foreach (@$files) {
+ if ($_ eq $includefile) {
+ $found = 1;
+ last;
+ }
+ }
+ if ($found) {
+ print "$includefile found at line $fileline in $filename was previously included\n";
+ } else {
+ # The file has not been previously found. Save it and
+ # recursively process it.
+ push (@$files,$includefile);
+ get_includes($files,$includefile);
+ }
+ }
+ }
+ close IF;
+ }
+}
+
+
+sub check_hyphens {
+ my (@files) = @_;
+ my ($filedata,$this,$linecnt,$before);
+
+ # Build the test string to check for the various environments.
+ # We only do the conversion if the multiple hyphens are outside of a
+ # verbatim environment (either \begin{verbatim}...\end{verbatim} or
+ # \verb{--}). Capture those environments and pass them to the output
+ # unchanged.
+
+ foreach my $file (@files) {
+ # Open the file and load the whole thing into $filedata. A bit wasteful but
+ # easier to deal with, and we don't have a problem with speed here.
+ $filedata = "";
+ open IF,"<$file" or die "Cannot open input file $file";
+ while (<IF>) {
+ $filedata .= $_;
+ }
+ close IF;
+
+ # Set up to process the file data.
+ $linecnt = 1;
+
+ # Go through the file data from beginning to end. For each match, save what
+ # came before it and what matched. $filedata now becomes only what came
+ # after the match.
+ # Chech the match to see if it starts with a multiple-hyphen. If so
+ # warn the user. Keep track of line numbers so they can be output
+ # with the warning message.
+ while ($filedata =~ /$teststr/os) {
+ $this = $&;
+ $before = $`;
+ $filedata = $';
+ $linecnt += $before =~ tr/\n/\n/;
+
+ # Check if the multiple hyphen is present outside of one of the
+ # acceptable constructs.
+ if ($this =~ /^\-+/) {
+ print "Possible unwanted multiple hyphen found in line ",
+ "$linecnt of file $file\n";
+ }
+ $linecnt += $this =~ tr/\n/\n/;
+ }
+ }
+}
+##################################################################
+# MAIN ####
+##################################################################
+
+my (@includes,$cnt);
+
+# Examine the file pointed to by the first argument to get a list of
+# includes to test.
+get_includes(\@includes,@ARGV);
+
+check_hyphens(@includes);
--- /dev/null
+#
+# Avoid that @VERSION@ and @DATE@ are changed by configure
+# This file is sourced by update_version
+#
+echo "s%@VERSION@%${VERSION}%g" >${out}
+echo "s%@DATE@%${DATE}%g" >>${out}
--- /dev/null
+% TODO: maybe get rid of centering
+
+\chapter{GNU Free Documentation License}
+\index[general]{GNU Free Documentation License}
+\index[general]{License!GNU Free Documentation}
+
+\label{label_fdl}
+
+ \begin{center}
+
+ Version 1.2, November 2002
+
+
+ Copyright \copyright 2000,2001,2002 Free Software Foundation, Inc.
+
+ \bigskip
+
+ 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
+
+ \bigskip
+
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+\end{center}
+
+
+\begin{center}
+{\bf\large Preamble}
+\end{center}
+
+The purpose of this License is to make a manual, textbook, or other
+functional and useful document "free" in the sense of freedom: to
+assure everyone the effective freedom to copy and redistribute it,
+with or without modifying it, either commercially or noncommercially.
+Secondarily, this License preserves for the author and publisher a way
+to get credit for their work, while not being considered responsible
+for modifications made by others.
+
+This License is a kind of "copyleft", which means that derivative
+works of the document must themselves be free in the same sense. It
+complements the GNU General Public License, which is a copyleft
+license designed for free software.
+
+We have designed this License in order to use it for manuals for free
+software, because free software needs free documentation: a free
+program should come with manuals providing the same freedoms that the
+software does. But this License is not limited to software manuals;
+it can be used for any textual work, regardless of subject matter or
+whether it is published as a printed book. We recommend this License
+principally for works whose purpose is instruction or reference.
+
+
+\begin{center}
+{\Large\bf 1. APPLICABILITY AND DEFINITIONS}
+\end{center}
+
+This License applies to any manual or other work, in any medium, that
+contains a notice placed by the copyright holder saying it can be
+distributed under the terms of this License. Such a notice grants a
+world-wide, royalty-free license, unlimited in duration, to use that
+work under the conditions stated herein. The \textbf{"Document"}, below,
+refers to any such manual or work. Any member of the public is a
+licensee, and is addressed as \textbf{"you"}. You accept the license if you
+copy, modify or distribute the work in a way requiring permission
+under copyright law.
+
+A \textbf{"Modified Version"} of the Document means any work containing the
+Document or a portion of it, either copied verbatim, or with
+modifications and/or translated into another language.
+
+A \textbf{"Secondary Section"} is a named appendix or a front-matter section of
+the Document that deals exclusively with the relationship of the
+publishers or authors of the Document to the Document's overall subject
+(or to related matters) and contains nothing that could fall directly
+within that overall subject. (Thus, if the Document is in part a
+textbook of mathematics, a Secondary Section may not explain any
+mathematics.) The relationship could be a matter of historical
+connection with the subject or with related matters, or of legal,
+commercial, philosophical, ethical or political position regarding
+them.
+
+The \textbf{"Invariant Sections"} are certain Secondary Sections whose titles
+are designated, as being those of Invariant Sections, in the notice
+that says that the Document is released under this License. If a
+section does not fit the above definition of Secondary then it is not
+allowed to be designated as Invariant. The Document may contain zero
+Invariant Sections. If the Document does not identify any Invariant
+Sections then there are none.
+
+The \textbf{"Cover Texts"} are certain short passages of text that are listed,
+as Front-Cover Texts or Back-Cover Texts, in the notice that says that
+the Document is released under this License. A Front-Cover Text may
+be at most 5 words, and a Back-Cover Text may be at most 25 words.
+
+A \textbf{"Transparent"} copy of the Document means a machine-readable copy,
+represented in a format whose specification is available to the
+general public, that is suitable for revising the document
+straightforwardly with generic text editors or (for images composed of
+pixels) generic paint programs or (for drawings) some widely available
+drawing editor, and that is suitable for input to text formatters or
+for automatic translation to a variety of formats suitable for input
+to text formatters. A copy made in an otherwise Transparent file
+format whose markup, or absence of markup, has been arranged to thwart
+or discourage subsequent modification by readers is not Transparent.
+An image format is not Transparent if used for any substantial amount
+of text. A copy that is not "Transparent" is called \textbf{"Opaque"}.
+
+Examples of suitable formats for Transparent copies include plain
+ASCII without markup, Texinfo input format, LaTeX input format, SGML
+or XML using a publicly available DTD, and standard-conforming simple
+HTML, PostScript or PDF designed for human modification. Examples of
+transparent image formats include PNG, XCF and JPG. Opaque formats
+include proprietary formats that can be read and edited only by
+proprietary word processors, SGML or XML for which the DTD and/or
+processing tools are not generally available, and the
+machine-generated HTML, PostScript or PDF produced by some word
+processors for output purposes only.
+
+The \textbf{"Title Page"} means, for a printed book, the title page itself,
+plus such following pages as are needed to hold, legibly, the material
+this License requires to appear in the title page. For works in
+formats which do not have any title page as such, "Title Page" means
+the text near the most prominent appearance of the work's title,
+preceding the beginning of the body of the text.
+
+A section \textbf{"Entitled XYZ"} means a named subunit of the Document whose
+title either is precisely XYZ or contains XYZ in parentheses following
+text that translates XYZ in another language. (Here XYZ stands for a
+specific section name mentioned below, such as \textbf{"Acknowledgements"},
+\textbf{"Dedications"}, \textbf{"Endorsements"}, or \textbf{"History"}.)
+To \textbf{"Preserve the Title"}
+of such a section when you modify the Document means that it remains a
+section "Entitled XYZ" according to this definition.
+
+The Document may include Warranty Disclaimers next to the notice which
+states that this License applies to the Document. These Warranty
+Disclaimers are considered to be included by reference in this
+License, but only as regards disclaiming warranties: any other
+implication that these Warranty Disclaimers may have is void and has
+no effect on the meaning of this License.
+
+
+\begin{center}
+{\Large\bf 2. VERBATIM COPYING}
+\end{center}
+
+You may copy and distribute the Document in any medium, either
+commercially or noncommercially, provided that this License, the
+copyright notices, and the license notice saying this License applies
+to the Document are reproduced in all copies, and that you add no other
+conditions whatsoever to those of this License. You may not use
+technical measures to obstruct or control the reading or further
+copying of the copies you make or distribute. However, you may accept
+compensation in exchange for copies. If you distribute a large enough
+number of copies you must also follow the conditions in section 3.
+
+You may also lend copies, under the same conditions stated above, and
+you may publicly display copies.
+
+
+\begin{center}
+{\Large\bf 3. COPYING IN QUANTITY}
+\end{center}
+
+
+If you publish printed copies (or copies in media that commonly have
+printed covers) of the Document, numbering more than 100, and the
+Document's license notice requires Cover Texts, you must enclose the
+copies in covers that carry, clearly and legibly, all these Cover
+Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
+the back cover. Both covers must also clearly and legibly identify
+you as the publisher of these copies. The front cover must present
+the full title with all words of the title equally prominent and
+visible. You may add other material on the covers in addition.
+Copying with changes limited to the covers, as long as they preserve
+the title of the Document and satisfy these conditions, can be treated
+as verbatim copying in other respects.
+
+If the required texts for either cover are too voluminous to fit
+legibly, you should put the first ones listed (as many as fit
+reasonably) on the actual cover, and continue the rest onto adjacent
+pages.
+
+If you publish or distribute Opaque copies of the Document numbering
+more than 100, you must either include a machine-readable Transparent
+copy along with each Opaque copy, or state in or with each Opaque copy
+a computer-network location from which the general network-using
+public has access to download using public-standard network protocols
+a complete Transparent copy of the Document, free of added material.
+If you use the latter option, you must take reasonably prudent steps,
+when you begin distribution of Opaque copies in quantity, to ensure
+that this Transparent copy will remain thus accessible at the stated
+location until at least one year after the last time you distribute an
+Opaque copy (directly or through your agents or retailers) of that
+edition to the public.
+
+It is requested, but not required, that you contact the authors of the
+Document well before redistributing any large number of copies, to give
+them a chance to provide you with an updated version of the Document.
+
+
+\begin{center}
+{\Large\bf 4. MODIFICATIONS}
+\end{center}
+
+You may copy and distribute a Modified Version of the Document under
+the conditions of sections 2 and 3 above, provided that you release
+the Modified Version under precisely this License, with the Modified
+Version filling the role of the Document, thus licensing distribution
+and modification of the Modified Version to whoever possesses a copy
+of it. In addition, you must do these things in the Modified Version:
+
+\begin{itemize}
+\item[A.]
+ Use in the Title Page (and on the covers, if any) a title distinct
+ from that of the Document, and from those of previous versions
+ (which should, if there were any, be listed in the History section
+ of the Document). You may use the same title as a previous version
+ if the original publisher of that version gives permission.
+
+\item[B.]
+ List on the Title Page, as authors, one or more persons or entities
+ responsible for authorship of the modifications in the Modified
+ Version, together with at least five of the principal authors of the
+ Document (all of its principal authors, if it has fewer than five),
+ unless they release you from this requirement.
+
+\item[C.]
+ State on the Title page the name of the publisher of the
+ Modified Version, as the publisher.
+
+\item[D.]
+ Preserve all the copyright notices of the Document.
+
+\item[E.]
+ Add an appropriate copyright notice for your modifications
+ adjacent to the other copyright notices.
+
+\item[F.]
+ Include, immediately after the copyright notices, a license notice
+ giving the public permission to use the Modified Version under the
+ terms of this License, in the form shown in the Addendum below.
+
+\item[G.]
+ Preserve in that license notice the full lists of Invariant Sections
+ and required Cover Texts given in the Document's license notice.
+
+\item[H.]
+ Include an unaltered copy of this License.
+
+\item[I.]
+ Preserve the section Entitled "History", Preserve its Title, and add
+ to it an item stating at least the title, year, new authors, and
+ publisher of the Modified Version as given on the Title Page. If
+ there is no section Entitled "History" in the Document, create one
+ stating the title, year, authors, and publisher of the Document as
+ given on its Title Page, then add an item describing the Modified
+ Version as stated in the previous sentence.
+
+\item[J.]
+ Preserve the network location, if any, given in the Document for
+ public access to a Transparent copy of the Document, and likewise
+ the network locations given in the Document for previous versions
+ it was based on. These may be placed in the "History" section.
+ You may omit a network location for a work that was published at
+ least four years before the Document itself, or if the original
+ publisher of the version it refers to gives permission.
+
+\item[K.]
+ For any section Entitled "Acknowledgements" or "Dedications",
+ Preserve the Title of the section, and preserve in the section all
+ the substance and tone of each of the contributor acknowledgements
+ and/or dedications given therein.
+
+\item[L.]
+ Preserve all the Invariant Sections of the Document,
+ unaltered in their text and in their titles. Section numbers
+ or the equivalent are not considered part of the section titles.
+
+\item[M.]
+ Delete any section Entitled "Endorsements". Such a section
+ may not be included in the Modified Version.
+
+\item[N.]
+ Do not retitle any existing section to be Entitled "Endorsements"
+ or to conflict in title with any Invariant Section.
+
+\item[O.]
+ Preserve any Warranty Disclaimers.
+\end{itemize}
+
+If the Modified Version includes new front-matter sections or
+appendices that qualify as Secondary Sections and contain no material
+copied from the Document, you may at your option designate some or all
+of these sections as invariant. To do this, add their titles to the
+list of Invariant Sections in the Modified Version's license notice.
+These titles must be distinct from any other section titles.
+
+You may add a section Entitled "Endorsements", provided it contains
+nothing but endorsements of your Modified Version by various
+parties--for example, statements of peer review or that the text has
+been approved by an organization as the authoritative definition of a
+standard.
+
+You may add a passage of up to five words as a Front-Cover Text, and a
+passage of up to 25 words as a Back-Cover Text, to the end of the list
+of Cover Texts in the Modified Version. Only one passage of
+Front-Cover Text and one of Back-Cover Text may be added by (or
+through arrangements made by) any one entity. If the Document already
+includes a cover text for the same cover, previously added by you or
+by arrangement made by the same entity you are acting on behalf of,
+you may not add another; but you may replace the old one, on explicit
+permission from the previous publisher that added the old one.
+
+The author(s) and publisher(s) of the Document do not by this License
+give permission to use their names for publicity for or to assert or
+imply endorsement of any Modified Version.
+
+
+\begin{center}
+{\Large\bf 5. COMBINING DOCUMENTS}
+\end{center}
+
+
+You may combine the Document with other documents released under this
+License, under the terms defined in section 4 above for modified
+versions, provided that you include in the combination all of the
+Invariant Sections of all of the original documents, unmodified, and
+list them all as Invariant Sections of your combined work in its
+license notice, and that you preserve all their Warranty Disclaimers.
+
+The combined work need only contain one copy of this License, and
+multiple identical Invariant Sections may be replaced with a single
+copy. If there are multiple Invariant Sections with the same name but
+different contents, make the title of each such section unique by
+adding at the end of it, in parentheses, the name of the original
+author or publisher of that section if known, or else a unique number.
+Make the same adjustment to the section titles in the list of
+Invariant Sections in the license notice of the combined work.
+
+In the combination, you must combine any sections Entitled "History"
+in the various original documents, forming one section Entitled
+"History"; likewise combine any sections Entitled "Acknowledgements",
+and any sections Entitled "Dedications". You must delete all sections
+Entitled "Endorsements".
+
+\begin{center}
+{\Large\bf 6. COLLECTIONS OF DOCUMENTS}
+\end{center}
+
+You may make a collection consisting of the Document and other documents
+released under this License, and replace the individual copies of this
+License in the various documents with a single copy that is included in
+the collection, provided that you follow the rules of this License for
+verbatim copying of each of the documents in all other respects.
+
+You may extract a single document from such a collection, and distribute
+it individually under this License, provided you insert a copy of this
+License into the extracted document, and follow this License in all
+other respects regarding verbatim copying of that document.
+
+
+\begin{center}
+{\Large\bf 7. AGGREGATION WITH INDEPENDENT WORKS}
+\end{center}
+
+
+A compilation of the Document or its derivatives with other separate
+and independent documents or works, in or on a volume of a storage or
+distribution medium, is called an "aggregate" if the copyright
+resulting from the compilation is not used to limit the legal rights
+of the compilation's users beyond what the individual works permit.
+When the Document is included in an aggregate, this License does not
+apply to the other works in the aggregate which are not themselves
+derivative works of the Document.
+
+If the Cover Text requirement of section 3 is applicable to these
+copies of the Document, then if the Document is less than one half of
+the entire aggregate, the Document's Cover Texts may be placed on
+covers that bracket the Document within the aggregate, or the
+electronic equivalent of covers if the Document is in electronic form.
+Otherwise they must appear on printed covers that bracket the whole
+aggregate.
+
+
+\begin{center}
+{\Large\bf 8. TRANSLATION}
+\end{center}
+
+
+Translation is considered a kind of modification, so you may
+distribute translations of the Document under the terms of section 4.
+Replacing Invariant Sections with translations requires special
+permission from their copyright holders, but you may include
+translations of some or all Invariant Sections in addition to the
+original versions of these Invariant Sections. You may include a
+translation of this License, and all the license notices in the
+Document, and any Warranty Disclaimers, provided that you also include
+the original English version of this License and the original versions
+of those notices and disclaimers. In case of a disagreement between
+the translation and the original version of this License or a notice
+or disclaimer, the original version will prevail.
+
+If a section in the Document is Entitled "Acknowledgements",
+"Dedications", or "History", the requirement (section 4) to Preserve
+its Title (section 1) will typically require changing the actual
+title.
+
+
+\begin{center}
+{\Large\bf 9. TERMINATION}
+\end{center}
+
+
+You may not copy, modify, sublicense, or distribute the Document except
+as expressly provided for under this License. Any other attempt to
+copy, modify, sublicense or distribute the Document is void, and will
+automatically terminate your rights under this License. However,
+parties who have received copies, or rights, from you under this
+License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
+
+\begin{center}
+{\Large\bf 10. FUTURE REVISIONS OF THIS LICENSE}
+\end{center}
+
+
+The Free Software Foundation may publish new, revised versions
+of the GNU Free Documentation License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns. See
+http://www.gnu.org/copyleft/.
+
+Each version of the License is given a distinguishing version number.
+If the Document specifies that a particular numbered version of this
+License "or any later version" applies to it, you have the option of
+following the terms and conditions either of that specified version or
+of any later version that has been published (not as a draft) by the
+Free Software Foundation. If the Document does not specify a version
+number of this License, you may choose any version ever published (not
+as a draft) by the Free Software Foundation.
+
+
+\begin{center}
+{\Large\bf ADDENDUM: How to use this License for your documents}
+% TODO: this is too long for table of contents
+\end{center}
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and
+license notices just after the title page:
+
+\bigskip
+\begin{quote}
+ Copyright \copyright YEAR YOUR NAME.
+ Permission is granted to copy, distribute and/or modify this document
+ under the terms of the GNU Free Documentation License, Version 1.2
+ or any later version published by the Free Software Foundation;
+ with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+ A copy of the license is included in the section entitled "GNU
+ Free Documentation License".
+\end{quote}
+\bigskip
+
+If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
+replace the "with...Texts." line with this:
+
+\bigskip
+\begin{quote}
+ with the Invariant Sections being LIST THEIR TITLES, with the
+ Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
+\end{quote}
+\bigskip
+
+If you have Invariant Sections without Cover Texts, or some other
+combination of the three, merge those two alternatives to suit the
+situation.
+
+If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of
+free software license, such as the GNU General Public License,
+to permit their use in free software.
+
+%---------------------------------------------------------------------
--- /dev/null
+#!/usr/bin/perl -w
+# Fixes various things within tex files.
+
+use strict;
+
+my %args;
+
+
+sub get_includes {
+ # Get a list of include files from the top-level tex file.
+ my (@list,$file);
+
+ foreach my $filename (@_) {
+ $filename or next;
+ # Start with the top-level latex file so it gets checked too.
+ push (@list,$filename);
+
+ # Get a list of all the html files in the directory.
+ open IF,"<$filename" or die "Cannot open input file $filename";
+ while (<IF>) {
+ chomp;
+ push @list,"$1.tex" if (/\\include\{(.*?)\}/);
+ }
+
+ close IF;
+ }
+ return @list;
+}
+
+sub convert_files {
+ my (@files) = @_;
+ my ($linecnt,$filedata,$output,$itemcnt,$indentcnt,$cnt);
+
+ $cnt = 0;
+ foreach my $file (@files) {
+ # Open the file and load the whole thing into $filedata. A bit wasteful but
+ # easier to deal with, and we don't have a problem with speed here.
+ $filedata = "";
+ open IF,"<$file" or die "Cannot open input file $file";
+ while (<IF>) {
+ $filedata .= $_;
+ }
+ close IF;
+
+ # We look for a line that starts with \item, and indent the two next lines (if not blank)
+ # by three spaces.
+ my $linecnt = 3;
+ $indentcnt = 0;
+ $output = "";
+ # Process a line at a time.
+ foreach (split(/\n/,$filedata)) {
+ $_ .= "\n"; # Put back the return.
+ # If this line is less than the third line past the \item command,
+ # and the line isn't blank and doesn't start with whitespace
+ # add three spaces to the start of the line. Keep track of the number
+ # of lines changed.
+ if ($linecnt < 3 and !/^\\item/) {
+ if (/^[^\n\s]/) {
+ $output .= " " . $_;
+ $indentcnt++;
+ } else {
+ $output .= $_;
+ }
+ $linecnt++;
+ } else {
+ $linecnt = 3;
+ $output .= $_;
+ }
+ /^\\item / and $linecnt = 1;
+ }
+
+
+ # This is an item line. We need to process it too. If inside a \begin{description} environment, convert
+ # \item {\bf xxx} to \item [xxx] or \item [{xxx}] (if xxx contains '[' or ']'.
+ $itemcnt = 0;
+ $filedata = $output;
+ $output = "";
+ my ($before,$descrip,$this,$between);
+
+ # Find any \begin{description} environment
+ while ($filedata =~ /(\\begin[\s\n]*\{[\s\n]*description[\s\n]*\})(.*?)(\\end[\s\n]*\{[\s\n]*description[\s\n]*\})/s) {
+ $output .= $` . $1;
+ $filedata = $3 . $';
+ $descrip = $2;
+
+ # Search for \item {\bf xxx}
+ while ($descrip =~ /\\item[\s\n]*\{[\s\n]*\\bf[\s\n]*/s) {
+ $descrip = $';
+ $output .= $`;
+ ($between,$descrip) = find_matching_brace($descrip);
+ if (!$descrip) {
+ $linecnt = $output =~ tr/\n/\n/;
+ print STDERR "Missing matching curly brace at line $linecnt in $file\n" if (!$descrip);
+ }
+
+ # Now do the replacement.
+ $between = '{' . $between . '}' if ($between =~ /\[|\]/);
+ $output .= "\\item \[$between\]";
+ $itemcnt++;
+ }
+ $output .= $descrip;
+ }
+ $output .= $filedata;
+
+ # If any hyphens or \item commnads were converted, save the file.
+ if ($indentcnt or $itemcnt) {
+ open OF,">$file" or die "Cannot open output file $file";
+ print OF $output;
+ close OF;
+ print "$indentcnt indent", ($indentcnt == 1) ? "" : "s"," added in $file\n";
+ print "$itemcnt item", ($itemcnt == 1) ? "" : "s"," Changed in $file\n";
+ }
+
+ $cnt += $indentcnt + $itemcnt;
+ }
+ return $cnt;
+}
+
+sub find_matching_brace {
+ # Finds text up to the next matching brace. Assumes that the input text doesn't contain
+ # the opening brace, but we want to find text up to a matching closing one.
+ # Returns the text between the matching braces, followed by the rest of the text following
+ # (which does not include the matching brace).
+ #
+ my $str = shift;
+ my ($this,$temp);
+ my $cnt = 1;
+
+ while ($cnt) {
+ # Ignore verbatim constructs involving curly braces, or if the character preceding
+ # the curly brace is a backslash.
+ if ($str =~ /\\verb\*?\{.*?\{|\\verb\*?\}.*?\}|\{|\}/s) {
+ $this .= $`;
+ $str = $';
+ $temp = $&;
+
+ if ((substr($this,-1,1) eq '\\') or
+ $temp =~ /^\\verb/) {
+ $this .= $temp;
+ next;
+ }
+
+ $cnt += ($temp eq '{') ? 1 : -1;
+ # If this isn't the matching curly brace ($cnt > 0), include the brace.
+ $this .= $temp if ($cnt);
+ } else {
+ # No matching curly brace found.
+ return ($this . $str,'');
+ }
+ }
+ return ($this,$str);
+}
+
+sub check_arguments {
+ # Checks command-line arguments for ones starting with -- puts them into
+ # a hash called %args and removes them from @ARGV.
+ my $args = shift;
+ my $i;
+
+ for ($i = 0; $i < $#ARGV; $i++) {
+ $ARGV[$i] =~ /^\-+/ or next;
+ $ARGV[$i] =~ s/^\-+//;
+ $args{$ARGV[$i]} = "";
+ delete ($ARGV[$i]);
+
+ }
+}
+
+##################################################################
+# MAIN ####
+##################################################################
+
+my @includes;
+my $cnt;
+
+check_arguments(\%args);
+die "No Files given to Check\n" if ($#ARGV < 0);
+
+# Examine the file pointed to by the first argument to get a list of
+# includes to test.
+@includes = get_includes(@ARGV);
+
+$cnt = convert_files(@includes);
+print "No lines changed\n" unless $cnt;
--- /dev/null
+# This module does multiple indices, supporting the style of the LaTex 'index'
+# package.
+
+# Version Information:
+# 16-Feb-2005 -- Original Creation. Karl E. Cunningham
+# 14-Mar-2005 -- Clarified and Consolodated some of the code.
+# Changed to smoothly handle single and multiple indices.
+
+# Two LaTeX index formats are supported...
+# --- SINGLE INDEX ---
+# \usepackage{makeidx}
+# \makeindex
+# \index{entry1}
+# \index{entry2}
+# \index{entry3}
+# ...
+# \printindex
+#
+# --- MULTIPLE INDICES ---
+#
+# \usepackage{makeidx}
+# \usepackage{index}
+# \makeindex -- latex2html doesn't care but LaTeX does.
+# \newindex{ref1}{ext1}{ext2}{title1}
+# \newindex{ref2}{ext1}{ext2}{title2}
+# \newindex{ref3}{ext1}{ext2}{title3}
+# \index[ref1]{entry1}
+# \index[ref1]{entry2}
+# \index[ref3]{entry3}
+# \index[ref2]{entry4}
+# \index{entry5}
+# \index[ref3]{entry6}
+# ...
+# \printindex[ref1]
+# \printindex[ref2]
+# \printindex[ref3]
+# \printindex
+# ___________________
+#
+# For the multiple-index style, each index is identified by the ref argument to \newindex, \index,
+# and \printindex. A default index is allowed, which is indicated by omitting the optional
+# argument. The default index does not require a \newindex command. As \index commands
+# are encountered, their entries are stored according
+# to the ref argument. When the \printindex command is encountered, the stored index
+# entries for that argument are retrieved and printed. The title for each index is taken
+# from the last argument in the \newindex command.
+# While processing \index and \printindex commands, if no argument is given the index entries
+# are built into a default index. The title of the default index is simply "Index".
+# This makes the difference between single- and multiple-index processing trivial.
+#
+# Another method can be used by omitting the \printindex command and just using \include to
+# pull in index files created by the makeindex program. These files will start with
+# \begin{theindex}. This command is used to determine where to print the index. Using this
+# approach, the indices will be output in the same order as the newindex commands were
+# originally found (see below). Using a combination of \printindex and \include{indexfile} has not
+# been tested and may produce undesireable results.
+#
+# The index data are stored in a hash for later sorting and output. As \printindex
+# commands are handled, the order in which they were found in the tex filea is saved,
+# associated with the ref argument to \printindex.
+#
+# We use the original %index hash to store the index data into. We append a \002 followed by the
+# name of the index to isolate the entries in different indices from each other. This is necessary
+# so that different indices can have entries with the same name. For the default index, the \002 is
+# appended without the name.
+#
+# Since the index order in the output cannot be determined if the \include{indexfile}
+# command is used, the order will be assumed from the order in which the \newindex
+# commands were originally seen in the TeX files. This order is saved as well as the
+# order determined from any printindex{ref} commands. If \printindex commnads are used
+# to specify the index output, that order will be used. If the \include{idxfile} command
+# is used, the order of the original newindex commands will be used. In this case the
+# default index will be printed last since it doesn't have a corresponding \newindex
+# command and its order cannot be determined. Mixing \printindex and \include{idxfile}
+# commands in the same file is likely to produce less than satisfactory results.
+#
+#
+# The hash containing index data is named %indices. It contains the following data:
+#{
+# 'title' => {
+# $ref1 => $indextitle ,
+# $ref2 => $indextitle ,
+# ...
+# },
+# 'newcmdorder' => [ ref1, ref2, ..., * ], # asterisk indicates the position of the default index.
+# 'printindorder' => [ ref1, ref2, ..., * ], # asterisk indicates the position of the default index.
+#}
+
+
+# Globals to handle multiple indices.
+my %indices;
+
+# This tells the system to use up to 7 words in index entries.
+$WORDS_IN_INDEX = 10;
+
+# KEC 2-18-05
+# Handles the \newindex command. This is called if the \newindex command is
+# encountered in the LaTex source. Gets the index ref and title from the arguments.
+# Saves the index ref and title.
+# Note that we are called once to handle multiple \newindex commands that are
+# newline-separated.
+sub do_cmd_newindex {
+ my $data = shift;
+ # The data is sent to us as fields delimited by their ID #'s. We extract the
+ # fields.
+ foreach my $line (split("\n",$data)) {
+ my @fields = split (/(?:\<\#\d+?\#\>)+/,$line);
+
+ # The index name and title are the second and fourth fields in the data.
+ if ($line =~ /^</ or $line =~ /^\\newindex/) {
+ my ($indexref,$indextitle) = ($fields[1],$fields[4]);
+ $indices{'title'}{$indexref} = $indextitle;
+ push (@{$indices{'newcmdorder'}},$indexref);
+ }
+ }
+}
+
+
+# KEC -- Copied from makeidx.perl and modified to do multiple indices.
+# Processes an \index entry from the LaTex file.
+# Gets the optional argument from the index command, which is the name of the index
+# into which to place the entry.
+# Drops the brackets from the index_name
+# Puts the index entry into the html stream
+# Creates the tokenized index entry (which also saves the index entry info
+sub do_real_index {
+ local($_) = @_;
+ local($pat,$idx_entry,$index_name);
+ # catches opt-arg from \index commands for index.sty
+ $index_name = &get_next_optional_argument;
+ $index_name = "" unless defined $index_name;
+ # Drop leading and trailing brackets from the index name.
+ $index_name =~ s/^\[|\]$//g;
+
+ $idx_entry = &missing_braces unless (
+ (s/$next_pair_pr_rx/$pat=$1;$idx_entry=$2;''/e)
+ ||(s/$next_pair_rx/$pat=$1;$idx_entry=$2;''/e));
+
+ if ($index_name and defined $idx_entry and
+ !defined $indices{'title'}{$index_name}) {
+ print STDERR "\nInvalid Index Name: \\index \[$index_name\]\{$idx_entry\}\n";
+ }
+
+ $idx_entry = &named_index_entry($pat, $idx_entry,$index_name);
+ $idx_entry.$_;
+}
+
+# Creates and saves an index entry in the index hashes.
+# Modified to do multiple indices.
+# Creates an index_key that allows index entries to have the same characteristics but be in
+# different indices. This index_key is the regular key with the index name appended.
+# Save the index order for the entry in the %index_order hash.
+sub named_index_entry {
+ local($br_id, $str, $index_name) = @_;
+ my ($index_key);
+ # escape the quoting etc characters
+ # ! -> \001
+ # @ -> \002
+ # | -> \003
+ $* = 1; $str =~ s/\n\s*/ /g; $* = 0; # remove any newlines
+ # protect \001 occurring with images
+ $str =~ s/\001/\016/g; # 0x1 to 0xF
+ $str =~ s/\\\\/\011/g; # Double backslash -> 0xB
+ $str =~ s/\\;SPMquot;/\012/g; # \;SPMquot; -> 0xC
+ $str =~ s/;SPMquot;!/\013/g; # ;SPMquot; -> 0xD
+ $str =~ s/!/\001/g; # Exclamation point -> 0x1
+ $str =~ s/\013/!/g; # 0xD -> Exclaimation point
+ $str =~ s/;SPMquot;@/\015/g; # ;SPMquot;@ to 0xF
+ $str =~ s/@/\002/g; # At sign -> 0x2
+ $str =~ s/\015/@/g; # 0xF to At sign
+ $str =~ s/;SPMquot;\|/\017/g; # ;SMPquot;| to 0x11
+ $str =~ s/\|/\003/g; # Vertical line to 0x3
+ $str =~ s/\017/|/g; # 0x11 to vertical line
+ $str =~ s/;SPMquot;(.)/\1/g; # ;SPMquot; -> whatever the next character is
+ $str =~ s/\012/;SPMquot;/g; # 0x12 to ;SPMquot;
+ $str =~ s/\011/\\\\/g; # 0x11 to double backslash
+ local($key_part, $pageref) = split("\003", $str, 2);
+
+ # For any keys of the form: blablabla!blablabla, which want to be split at the
+ # exclamation point, replace the ! with a comma and a space. We don't do it
+ # that way for this index.
+ $key_part =~ s/\001/, /g;
+ local(@keys) = split("\001", $key_part);
+ # If TITLE is not yet available use $before.
+ $TITLE = $saved_title if (($saved_title)&&(!($TITLE)||($TITLE eq $default_title)));
+ $TITLE = $before unless $TITLE;
+ # Save the reference
+ local($words) = '';
+ if ($SHOW_SECTION_NUMBERS) { $words = &make_idxnum; }
+ elsif ($SHORT_INDEX) { $words = &make_shortidxname; }
+ else { $words = &make_idxname; }
+ local($super_key) = '';
+ local($sort_key, $printable_key, $cur_key);
+ foreach $key (@keys) {
+ $key =~ s/\016/\001/g; # revert protected \001s
+ ($sort_key, $printable_key) = split("\002", $key);
+ #
+ # RRM: 16 May 1996
+ # any \label in the printable-key will have already
+ # created a label where the \index occurred.
+ # This has to be removed, so that the desired label
+ # will be found on the Index page instead.
+ #
+ if ($printable_key =~ /tex2html_anchor_mark/ ) {
+ $printable_key =~ s/><tex2html_anchor_mark><\/A><A//g;
+ local($tmpA,$tmpB) = split("NAME=\"", $printable_key);
+ ($tmpA,$tmpB) = split("\"", $tmpB);
+ $ref_files{$tmpA}='';
+ $index_labels{$tmpA} = 1;
+ }
+ #
+ # resolve and clean-up the hyperlink index-entries
+ # so they can be saved in an index.pl file
+ #
+ if ($printable_key =~ /$cross_ref_mark/ ) {
+ local($label,$id,$ref_label);
+ # $printable_key =~ s/$cross_ref_mark#(\w+)#(\w+)>$cross_ref_mark/
+ $printable_key =~ s/$cross_ref_mark#([^#]+)#([^>]+)>$cross_ref_mark/
+ do { ($label,$id) = ($1,$2);
+ $ref_label = $external_labels{$label} unless
+ ($ref_label = $ref_files{$label});
+ '"' . "$ref_label#$label" . '">' .
+ &get_ref_mark($label,$id)}
+ /geo;
+ }
+ $printable_key =~ s/<\#[^\#>]*\#>//go;
+ #RRM
+ # recognise \char combinations, for a \backslash
+ #
+ $printable_key =~ s/\&\#;\'134/\\/g; # restore \\s
+ $printable_key =~ s/\&\#;\`<BR> /\\/g; # ditto
+ $printable_key =~ s/\&\#;*SPMquot;92/\\/g; # ditto
+ #
+ # $sort_key .= "@$printable_key" if !($printable_key); # RRM
+ $sort_key .= "@$printable_key" if !($sort_key); # RRM
+ $sort_key =~ tr/A-Z/a-z/;
+ if ($super_key) {
+ $cur_key = $super_key . "\001" . $sort_key;
+ $sub_index{$super_key} .= $cur_key . "\004";
+ } else {
+ $cur_key = $sort_key;
+ }
+
+ # Append the $index_name to the current key with a \002 delimiter. This will
+ # allow the same index entry to appear in more than one index.
+ $index_key = $cur_key . "\002$index_name";
+
+ $index{$index_key} .= "";
+
+ #
+ # RRM, 15 June 1996
+ # if there is no printable key, but one is known from
+ # a previous index-entry, then use it.
+ #
+ if (!($printable_key) && ($printable_key{$index_key}))
+ { $printable_key = $printable_key{$index_key}; }
+# if (!($printable_key) && ($printable_key{$cur_key}))
+# { $printable_key = $printable_key{$cur_key}; }
+ #
+ # do not overwrite the printable_key if it contains an anchor
+ #
+ if (!($printable_key{$index_key} =~ /tex2html_anchor_mark/ ))
+ { $printable_key{$index_key} = $printable_key || $key; }
+# if (!($printable_key{$cur_key} =~ /tex2html_anchor_mark/ ))
+# { $printable_key{$cur_key} = $printable_key || $key; }
+
+ $super_key = $cur_key;
+ }
+ #
+ # RRM
+ # page-ranges, from |( and |) and |see
+ #
+ if ($pageref) {
+ if ($pageref eq "\(" ) {
+ $pageref = '';
+ $next .= " from ";
+ } elsif ($pageref eq "\)" ) {
+ $pageref = '';
+ local($next) = $index{$index_key};
+# local($next) = $index{$cur_key};
+ # $next =~ s/[\|] *$//;
+ $next =~ s/(\n )?\| $//;
+ $index{$index_key} = "$next to ";
+# $index{$cur_key} = "$next to ";
+ }
+ }
+
+ if ($pageref) {
+ $pageref =~ s/\s*$//g; # remove trailing spaces
+ if (!$pageref) { $pageref = ' ' }
+ $pageref =~ s/see/<i>see <\/i> /g;
+ #
+ # RRM: 27 Dec 1996
+ # check if $pageref corresponds to a style command.
+ # If so, apply it to the $words.
+ #
+ local($tmp) = "do_cmd_$pageref";
+ if (defined &$tmp) {
+ $words = &$tmp("<#0#>$words<#0#>");
+ $words =~ s/<\#[^\#]*\#>//go;
+ $pageref = '';
+ }
+ }
+ #
+ # RRM: 25 May 1996
+ # any \label in the pageref section will have already
+ # created a label where the \index occurred.
+ # This has to be removed, so that the desired label
+ # will be found on the Index page instead.
+ #
+ if ($pageref) {
+ if ($pageref =~ /tex2html_anchor_mark/ ) {
+ $pageref =~ s/><tex2html_anchor_mark><\/A><A//g;
+ local($tmpA,$tmpB) = split("NAME=\"", $pageref);
+ ($tmpA,$tmpB) = split("\"", $tmpB);
+ $ref_files{$tmpA}='';
+ $index_labels{$tmpA} = 1;
+ }
+ #
+ # resolve and clean-up any hyperlinks in the page-ref,
+ # so they can be saved in an index.pl file
+ #
+ if ($pageref =~ /$cross_ref_mark/ ) {
+ local($label,$id,$ref_label);
+ # $pageref =~ s/$cross_ref_mark#(\w+)#(\w+)>$cross_ref_mark/
+ $pageref =~ s/$cross_ref_mark#([^#]+)#([^>]+)>$cross_ref_mark/
+ do { ($label,$id) = ($1,$2);
+ $ref_files{$label} = ''; # ???? RRM
+ if ($index_labels{$label}) { $ref_label = ''; }
+ else { $ref_label = $external_labels{$label}
+ unless ($ref_label = $ref_files{$label});
+ }
+ '"' . "$ref_label#$label" . '">' . &get_ref_mark($label,$id)}/geo;
+ }
+ $pageref =~ s/<\#[^\#>]*\#>//go;
+
+ if ($pageref eq ' ') { $index{$index_key}='@'; }
+ else { $index{$index_key} .= $pageref . "\n | "; }
+ } else {
+ local($thisref) = &make_named_href('',"$CURRENT_FILE#$br_id",$words);
+ $thisref =~ s/\n//g;
+ $index{$index_key} .= $thisref."\n | ";
+ }
+ #print "\nREF: $sort_key : $index_key :$index{$index_key}";
+
+ #join('',"<A NAME=$br_id>$anchor_invisible_mark<\/A>",$_);
+
+ "<A NAME=\"$br_id\">$anchor_invisible_mark<\/A>";
+}
+
+
+# KEC. -- Copied from makeidx.perl, then modified to do multiple indices.
+# Feeds the index entries to the output. This is called for each index to be built.
+#
+# Generates a list of lookup keys for index entries, from both %printable_keys
+# and %index keys.
+# Sorts the keys according to index-sorting rules.
+# Removes keys with a 0x01 token. (duplicates?)
+# Builds a string to go to the index file.
+# Adds the index entries to the string if they belong in this index.
+# Keeps track of which index is being worked on, so only the proper entries
+# are included.
+# Places the index just built in to the output at the proper place.
+{ my $index_number = 0;
+sub add_real_idx {
+ print "\nDoing the index ... Index Number $index_number\n";
+ local($key, @keys, $next, $index, $old_key, $old_html);
+ my ($idx_ref,$keyref);
+ # RRM, 15.6.96: index constructed from %printable_key, not %index
+ @keys = keys %printable_key;
+
+ while (/$idx_mark/) {
+ # Get the index reference from what follows the $idx_mark and
+ # remove it from the string.
+ s/$idxmark\002(.*?)\002/$idxmark/;
+ $idx_ref = $1;
+ $index = '';
+ # include non- makeidx index-entries
+ foreach $key (keys %index) {
+ next if $printable_key{$key};
+ $old_key = $key;
+ if ($key =~ s/###(.*)$//) {
+ next if $printable_key{$key};
+ push (@keys, $key);
+ $printable_key{$key} = $key;
+ if ($index{$old_key} =~ /HREF="([^"]*)"/i) {
+ $old_html = $1;
+ $old_html =~ /$dd?([^#\Q$dd\E]*)#/;
+ $old_html = $1;
+ } else { $old_html = '' }
+ $index{$key} = $index{$old_key} . $old_html."</A>\n | ";
+ };
+ }
+ @keys = sort makeidx_keysort @keys;
+ @keys = grep(!/\001/, @keys);
+ my $cnt = 0;
+ foreach $key (@keys) {
+ my ($keyref) = $key =~ /.*\002(.*)/;
+ next unless ($idx_ref eq $keyref); # KEC.
+ $index .= &add_idx_key($key);
+ $cnt++;
+ }
+ print "$cnt Index Entries Added\n";
+ $index = '<DD>'.$index unless ($index =~ /^\s*<D(D|T)>/);
+ $index_number++; # KEC.
+ if ($SHORT_INDEX) {
+ print "(compact version with Legend)";
+ local($num) = ( $index =~ s/\<D/<D/g );
+ if ($num > 50 ) {
+ s/$idx_mark/$preindex<HR><DL>\n$index\n<\/DL>$preindex/o;
+ } else {
+ s/$idx_mark/$preindex<HR><DL>\n$index\n<\/DL>/o;
+ }
+ } else {
+ s/$idx_mark/<DL COMPACT>\n$index\n<\/DL>/o; }
+ }
+}
+}
+
+# KEC. Copied from latex2html.pl and modified to support multiple indices.
+# The bibliography and the index should be treated as separate sections
+# in their own HTML files. The \bibliography{} command acts as a sectioning command
+# that has the desired effect. But when the bibliography is constructed
+# manually using the thebibliography environment, or when using the
+# theindex environment it is not possible to use the normal sectioning
+# mechanism. This subroutine inserts a \bibliography{} or a dummy
+# \textohtmlindex command just before the appropriate environments
+# to force sectioning.
+sub add_bbl_and_idx_dummy_commands {
+ local($id) = $global{'max_id'};
+
+ s/([\\]begin\s*$O\d+$C\s*thebibliography)/$bbl_cnt++; $1/eg;
+ ## if ($bbl_cnt == 1) {
+ s/([\\]begin\s*$O\d+$C\s*thebibliography)/$id++; "\\bibliography$O$id$C$O$id$C $1"/geo;
+ #}
+ $global{'max_id'} = $id;
+ # KEC. Modified to global substitution to place multiple index tokens.
+ s/[\\]begin\s*($O\d+$C)\s*theindex/\\textohtmlindex$1/go;
+ # KEC. Modified to pick up the optional argument to \printindex
+ s/[\\]printindex\s*(\[.*?\])?/
+ do { (defined $1) ? "\\textohtmlindex $1" : "\\textohtmlindex []"; } /ego;
+ &lib_add_bbl_and_idx_dummy_commands() if defined(&lib_add_bbl_and_idx_dummy_commands);
+}
+
+# KEC. Copied from latex2html.pl and modified to support multiple indices.
+# For each textohtmlindex mark found, determine the index titles and headers.
+# We place the index ref in the header so the proper index can be generated later.
+# For the default index, the index ref is blank.
+#
+# One problem is that this routine is called twice.. Once for processing the
+# command as originally seen, and once for processing the command when
+# doing the name for the index file. We can detect that by looking at the
+# id numbers (or ref) surrounding the \theindex command, and not incrementing
+# index_number unless a new id (or ref) is seen. This has the side effect of
+# having to unconventionally start the index_number at -1. But it works.
+#
+# Gets the title from the list of indices.
+# If this is the first index, save the title in $first_idx_file. This is what's referenced
+# in the navigation buttons.
+# Increment the index_number for next time.
+# If the indexname command is defined or a newcommand defined for indexname, do it.
+# Save the index TITLE in the toc
+# Save the first_idx_file into the idxfile. This goes into the nav buttons.
+# Build index_labels if needed.
+# Create the index headings and put them in the output stream.
+
+{ my $index_number = 0; # Will be incremented before use.
+ my $first_idx_file; # Static
+ my $no_increment = 0;
+
+sub do_cmd_textohtmlindex {
+ local($_) = @_;
+ my ($idxref,$idxnum,$index_name);
+
+ # We get called from make_name with the first argument = "\001noincrement". This is a sign
+ # to not increment $index_number the next time we are called. We get called twice, once
+ # my make_name and once by process_command. Unfortunately, make_name calls us just to set the name
+ # but doesn't use the result so we get called a second time by process_command. This works fine
+ # except for cases where there are multiple indices except if they aren't named, which is the case
+ # when the index is inserted by an include command in latex. In these cases we are only able to use
+ # the index number to decide which index to draw from, and we don't know how to increment that index
+ # number if we get called a variable number of times for the same index, as is the case between
+ # making html (one output file) and web (multiple output files) output formats.
+ if (/\001noincrement/) {
+ $no_increment = 1;
+ return;
+ }
+
+ # Remove (but save) the index reference
+ s/^\s*\[(.*?)\]/{$idxref = $1; "";}/e;
+
+ # If we have an $idxref, the index name was specified. In this case, we have all the
+ # information we need to carry on. Otherwise, we need to get the idxref
+ # from the $index_number and set the name to "Index".
+ if ($idxref) {
+ $index_name = $indices{'title'}{$idxref};
+ } else {
+ if (defined ($idxref = $indices{'newcmdorder'}->[$index_number])) {
+ $index_name = $indices{'title'}{$idxref};
+ } else {
+ $idxref = '';
+ $index_name = "Index";
+ }
+ }
+
+ $idx_title = "Index"; # The name displayed in the nav bar text.
+
+ # Only set $idxfile if we are at the first index. This will point the
+ # navigation panel to the first index file rather than the last.
+ $first_idx_file = $CURRENT_FILE if ($index_number == 0);
+ $idxfile = $first_idx_file; # Pointer for the Index button in the nav bar.
+ $toc_sec_title = $index_name; # Index link text in the toc.
+ $TITLE = $toc_sec_title; # Title for this index, from which its filename is built.
+ if (%index_labels) { &make_index_labels(); }
+ if (($SHORT_INDEX) && (%index_segment)) { &make_preindex(); }
+ else { $preindex = ''; }
+ local $idx_head = $section_headings{'textohtmlindex'};
+ local($heading) = join(''
+ , &make_section_heading($TITLE, $idx_head)
+ , $idx_mark, "\002", $idxref, "\002" );
+ local($pre,$post) = &minimize_open_tags($heading);
+ $index_number++ unless ($no_increment);
+ $no_increment = 0;
+ join('',"<BR>\n" , $pre, $_);
+}
+}
+
+# Returns an index key, given the key passed as the first argument.
+# Not modified for multiple indices.
+sub add_idx_key {
+ local($key) = @_;
+ local($index, $next);
+ if (($index{$key} eq '@' )&&(!($index_printed{$key}))) {
+ if ($SHORT_INDEX) { $index .= "<DD><BR>\n<DT>".&print_key."\n<DD>"; }
+ else { $index .= "<DT><DD><BR>\n<DT>".&print_key."\n<DD>"; }
+ } elsif (($index{$key})&&(!($index_printed{$key}))) {
+ if ($SHORT_INDEX) {
+ $next = "<DD>".&print_key."\n : ". &print_idx_links;
+ } else {
+ $next = "<DT>".&print_key."\n<DD>". &print_idx_links;
+ }
+ $index .= $next."\n";
+ $index_printed{$key} = 1;
+ }
+
+ if ($sub_index{$key}) {
+ local($subkey, @subkeys, $subnext, $subindex);
+ @subkeys = sort(split("\004", $sub_index{$key}));
+ if ($SHORT_INDEX) {
+ $index .= "<DD>".&print_key unless $index_printed{$key};
+ $index .= "<DL>\n";
+ } else {
+ $index .= "<DT>".&print_key."\n<DD>" unless $index_printed{$key};
+ $index .= "<DL COMPACT>\n";
+ }
+ foreach $subkey (@subkeys) {
+ $index .= &add_sub_idx_key($subkey) unless ($index_printed{$subkey});
+ }
+ $index .= "</DL>\n";
+ }
+ return $index;
+}
+
+1; # Must be present as the last line.
--- /dev/null
+%%
+%%
+
+\chapter{The internal database is not supported, please do not
+use it.}
+\label{InternalDbChapter}
+\index[general]{Use it!The internal database is not supported please
+do not }
+\index[general]{The internal database is not supported, please do not
+use it. }
+
+\section{Internal Bacula Database}
+\index[general]{Internal Bacula Database }
+\index[general]{Database!Internal Bacula }
+
+Previously it was intended to be used primarily by Bacula developers for
+testing; although SQLite is also a good choice for this. We do not recommend
+its use in general.
+
+This database is simplistic in that it consists entirely of Bacula's internal
+structures appended sequentially to a file. Consequently, it is in most cases
+inappropriate for sites with many clients or systems with large numbers of
+files, or long-term production environments.
+
+Below, you will find a table comparing the features available with SQLite and
+MySQL and with the internal Bacula database. At the current time, you cannot
+dynamically switch from one to the other, but must rebuild the Bacula source
+code. If you wish to experiment with both, it is possible to build both
+versions of Bacula and install them into separate directories.
+
+\addcontentsline{lot}{table}{SQLite vs MySQL Database Comparison}
+\begin{longtable}{|l|l|l|}
+ \hline
+\multicolumn{1}{|c| }{\bf Feature } & \multicolumn{1}{c| }{\bf SQLite or MySQL
+ } & \multicolumn{1}{c| }{\bf Bacula } \\
+ \hline
+{Job Record } & {Yes } & {Yes } \\
+ \hline
+{Media Record } & {Yes } & {Yes } \\
+ \hline
+{FileName Record } & {Yes } & {No } \\
+ \hline
+{File Record } & {Yes } & {No } \\
+ \hline
+{FileSet Record } & {Yes } & {Yes } \\
+ \hline
+{Pool Record } & {Yes } & {Yes } \\
+ \hline
+{Client Record } & {Yes } & {Yes } \\
+ \hline
+{JobMedia Record } & {Yes } & {Yes } \\
+ \hline
+{List Job Records } & {Yes } & {Yes } \\
+ \hline
+{List Media Records } & {Yes } & {Yes } \\
+ \hline
+{List Pool Records } & {Yes } & {Yes } \\
+ \hline
+{List JobMedia Records } & {Yes } & {Yes } \\
+ \hline
+{Delete Pool Record } & {Yes } & {Yes } \\
+ \hline
+{Delete Media Record } & {Yes } & {Yes } \\
+ \hline
+{Update Pool Record } & {Yes } & {Yes } \\
+ \hline
+{Implement Verify } & {Yes } & {No } \\
+ \hline
+{MD5 Signatures } & {Yes } & {No }
+\\ \hline
+
+\end{longtable}
+
+In addition, since there is no SQL available, the Console commands: {\bf
+sqlquery}, {\bf query}, {\bf retention}, and any other command that directly
+uses SQL are not available with the Internal database.
--- /dev/null
+# This file serves as a place to put initialization code and constants to
+# affect the behavior of latex2html for generating the bacula manuals.
+
+# $LINKPOINT specifies what filename to use to link to when creating
+# index.html. Not that this is a hard link.
+$LINKPOINT='"$OVERALL_TITLE"';
+
+
+# The following must be the last line of this file.
+1;
--- /dev/null
+%%
+%%
+
+\chapter{Installing and Configuring MySQL}
+\label{MySqlChapter}
+\index[general]{MySQL!Installing and Configuring }
+\index[general]{Installing and Configuring MySQL }
+
+\section{Installing and Configuring MySQL -- Phase I}
+\index[general]{Installing and Configuring MySQL -- Phase I }
+\index[general]{Phase I!Installing and Configuring MySQL -- }
+
+If you use the ./configure \verb:--:with-mysql=mysql-directory statement for
+configuring {\bf Bacula}, you will need MySQL version 4.1 or later installed
+in the {\bf mysql-directory}. If you are using one of the new modes such as
+ANSI/ISO compatibility, you may experience problems.
+
+If MySQL is installed in the standard system location, you need only enter
+{\bf \verb:--:with-mysql} since the configure program will search all the
+standard locations. If you install MySQL in your home directory or some
+other non-standard directory, you will need to provide the full path to it.
+
+Installing and Configuring MySQL is not difficult but can be confusing the
+first time. As a consequence, below, we list the steps that we used to install
+it on our machines. Please note that our configuration leaves MySQL without
+any user passwords. This may be an undesirable situation if you have other
+users on your system.
+
+The notes below describe how to build MySQL from the source tar files. If
+you have a pre-installed MySQL, you can return to complete the installation
+of Bacula, then come back to Phase II of the MySQL installation. If you
+wish to install MySQL from rpms, you will probably need to install
+the following:
+
+\footnotesize
+\begin{verbatim}
+mysql-<version>.rpm
+mysql-server-<version>.rpm
+mysql-devel-<version>.rpm
+\end{verbatim}
+\normalsize
+The names of the packages may vary from distribution to
+distribution. It is important to have the devel package loaded as
+it contains the libraries and header files necessary to build
+Bacula. There may be additional packages that are required to
+install the above, for example, zlib and openssl.
+
+Once these packages are installed, you will be able to build Bacula (using
+the files installed with the mysql package, then run MySQL using the
+files installed with mysql-server. If you have installed MySQL by rpms,
+please skip Phase I below, and return to complete the installation of
+Bacula, then come back to Phase II of the MySQL installation when indicated
+to do so.
+
+Beginning with Bacula version 1.31, the thread safe version of the
+MySQL client library is used, and hence you should add the {\bf
+\verb:--:enable-thread-safe-client} option to the {\bf
+./configure} as shown below:
+
+\begin{enumerate}
+\item Download MySQL source code from
+ \elink{www.mysql.com/downloads}{http://www.mysql.com/downloads}
+
+\item Detar it with something like:
+
+ {\bf tar xvfz mysql-filename}
+
+Note, the above command requires GNU tar. If you do not have GNU tar, a
+command such as:
+
+{\bf zcat mysql-filename | tar xvf - }
+
+will probably accomplish the same thing.
+
+\item cd {\bf mysql-source-directory}
+
+ where you replace {\bf mysql-source-directory} with the directory name where
+ you put the MySQL source code.
+
+\item ./configure \verb:--:enable-thread-safe-client \verb:--:prefix=mysql-directory
+
+ where you replace {\bf mysql-directory} with the directory name where you
+ want to install mysql. Normally for system wide use this is /usr/local/mysql.
+ In my case, I use \~{}kern/mysql.
+
+\item make
+
+ This takes a bit of time.
+
+\item make install
+
+ This will put all the necessary binaries, libraries and support files into
+ the {\bf mysql-directory} that you specified above.
+
+\item ./scripts/mysql\_install\_db
+
+ This will create the necessary MySQL databases for controlling user access.
+Note, this script can also be found in the {\bf bin} directory in the
+installation directory
+
+\end{enumerate}
+
+The MySQL client library {\bf mysqlclient} requires the gzip compression
+library {\bf libz.a} or {\bf libz.so}. If you are using rpm packages, these
+libraries are in the {\bf libz-devel} package. On Debian systems, you will
+need to load the {\bf zlib1g-dev} package. If you are not using rpms or debs,
+you will need to find the appropriate package for your system.
+
+At this point, you should return to completing the installation of {\bf
+Bacula}. Later after Bacula is installed, come back to this chapter to
+complete the installation. Please note, the installation files used in the
+second phase of the MySQL installation are created during the Bacula
+Installation.
+
+\label{mysql_phase2}
+\section{Installing and Configuring MySQL -- Phase II}
+\index[general]{Installing and Configuring MySQL -- Phase II }
+\index[general]{Phase II!Installing and Configuring MySQL -- }
+
+At this point, you should have built and installed MySQL, or already have a
+running MySQL, and you should have configured, built and installed {\bf
+Bacula}. If not, please complete these items before proceeding.
+
+Please note that the {\bf ./configure} used to build {\bf Bacula} will need to
+include {\bf \verb:--:with-mysql=mysql-directory}, where {\bf mysql-directory} is the
+directory name that you specified on the ./configure command for configuring
+MySQL. This is needed so that Bacula can find the necessary include headers
+and library files for interfacing to MySQL.
+
+{\bf Bacula} will install scripts for manipulating the database (create,
+delete, make tables etc) into the main installation directory. These files
+will be of the form *\_bacula\_* (e.g. create\_bacula\_database). These files
+are also available in the \lt{}bacula-src\gt{}/src/cats directory after
+running ./configure. If you inspect create\_bacula\_database, you will see
+that it calls create\_mysql\_database. The *\_bacula\_* files are provided for
+convenience. It doesn't matter what database you have chosen;
+create\_bacula\_database will always create your database.
+
+Now you will create the Bacula MySQL database and the tables that Bacula uses.
+
+
+\begin{enumerate}
+\item Start {\bf mysql}. You might want to use the {\bf startmysql} script
+ provided in the Bacula release.
+
+\item cd \lt{}install-directory\gt{}
+ This directory contains the Bacula catalog interface routines.
+
+\item ./grant\_mysql\_privileges
+ This script creates unrestricted access rights for the user {\bf bacula}.
+ You may want to modify it to suit your situation. Please
+ note that none of the userids, including root, are password protected.
+ If you need more security, please assign a password to the root user
+ and to bacula. The program {\bf mysqladmin} can be used for this.
+
+\item ./create\_mysql\_database
+ This script creates the MySQL {\bf bacula} database. The databases you
+ create as well as the access databases will be located in
+ \lt{}install-dir\gt{}/var/ in a subdirectory with the name of the
+ database, where \lt{}install-dir\gt{} is the directory name that you
+ specified on the {\bf \verb:--:prefix} option. This can be important to
+ know if you want to make a special backup of the Bacula database or to
+ check its size.
+
+\item ./make\_mysql\_tables
+ This script creates the MySQL tables used by {\bf Bacula}.
+\end{enumerate}
+
+Each of the three scripts (grant\_mysql\_privileges, create\_mysql\_database
+and make\_mysql\_tables) allows the addition of a command line argument. This
+can be useful for specifying the user and or password. For example, you might
+need to add {\bf -u root} to the command line to have sufficient privilege to
+create the Bacula tables.
+
+To take a closer look at the access privileges that you have setup with the
+above, you can do:
+
+\footnotesize
+\begin{verbatim}
+mysql-directory/bin/mysql -u root mysql
+select * from user;
+\end{verbatim}
+\normalsize
+
+\section{Re-initializing the Catalog Database}
+\index[general]{Database!Re-initializing the Catalog }
+\index[general]{Re-initializing the Catalog Database }
+
+After you have done some initial testing with {\bf Bacula}, you will probably
+want to re-initialize the catalog database and throw away all the test Jobs
+that you ran. To do so, you can do the following:
+
+\footnotesize
+\begin{verbatim}
+ cd <install-directory>
+ ./drop_mysql_tables
+ ./make_mysql_tables
+\end{verbatim}
+\normalsize
+
+Please note that all information in the database will be lost and you will be
+starting from scratch. If you have written on any Volumes, you must write an
+end of file mark on the volume so that Bacula can reuse it. Do so with:
+
+\footnotesize
+\begin{verbatim}
+ (stop Bacula or unmount the drive)
+ mt -f /dev/nst0 rewind
+ mt -f /dev/nst0 weof
+\end{verbatim}
+\normalsize
+
+Where you should replace {\bf /dev/nst0} with the appropriate tape drive
+device name for your machine.
+
+\section{Linking Bacula with MySQL}
+\index[general]{Linking Bacula with MySQL }
+\index[general]{MySQL!Linking Bacula with }
+\index[general]{Upgrading}
+
+After configuring Bacula with
+
+./configure \verb:--:enable-thread-safe-client \verb:--:prefix=\lt{}mysql-directory\gt{}
+where \lt{}mysql-directory\gt{} is in my case {\bf /home/kern/mysql}, you may
+have to configure the loader so that it can find the MySQL shared libraries.
+If you have previously followed this procedure and later add the {\bf
+\verb:--:enable-thread-safe-client} options, you will need to rerun the {\bf
+ldconfig} program shown below. If you put MySQL in a standard place such as
+{\bf /usr/lib} or {\bf /usr/local/lib} this will not be necessary, but in my
+case it is. The description that follows is Linux specific. For other
+operating systems, please consult your manuals on how to do the same thing:
+
+First edit: {\bf /etc/ld.so.conf} and add a new line to the end of the file
+with the name of the mysql-directory. In my case, it is:
+
+/home/kern/mysql/lib/mysql then rebuild the loader's cache with:
+
+/sbin/ldconfig If you upgrade to a new version of {\bf MySQL}, the shared
+library names will probably change, and you must re-run the {\bf
+/sbin/ldconfig} command so that the runtime loader can find them.
+
+Alternatively, your system my have a loader environment variable that can be
+set. For example, on a Solaris system where I do not have root permission, I
+use:
+
+LD\_LIBRARY\_PATH=/home/kern/mysql/lib/mysql
+
+Finally, if you have encryption enabled in MySQL, you may need to add {\bf
+-lssl -lcrypto} to the link. In that case, you can either export the
+appropriate LDFLAGS definition, or alternatively, you can include them
+directly on the ./configure line as in:
+
+\footnotesize
+\begin{verbatim}
+LDFLAGS="-lssl -lcyrpto" \
+ ./configure \
+ <your-options>
+\end{verbatim}
+\normalsize
+
+\section{Installing MySQL from RPMs}
+\index[general]{MySQL!Installing from RPMs}
+\index[general]{Installing MySQL from RPMs}
+If you are installing MySQL from RPMs, you will need to install
+both the MySQL binaries and the client libraries. The client
+libraries are usually found in a devel package, so you must
+install:
+
+\footnotesize
+\begin{verbatim}
+ mysql
+ mysql-devel
+\end{verbatim}
+\normalsize
+
+This will be the same with most other package managers too.
+
+\section{Upgrading MySQL}
+\index[general]{Upgrading MySQL }
+\index[general]{Upgrading!MySQL }
+\index[general]{Upgrading}
+If you upgrade MySQL, you must reconfigure, rebuild, and re-install
+Bacula otherwise you are likely to get bizarre failures. If you
+install from rpms and you upgrade MySQL, you must also rebuild Bacula.
+You can do so by rebuilding from the source rpm. To do so, you may need
+to modify the bacula.spec file to account for the new MySQL version.
--- /dev/null
+%%
+%%
+
+\chapter{Installer et configurer PostgreSQL}
+\label{_ChapterStart10}
+\index[general]{PostgreSQL!Installer et configurer }
+\index[general]{Installer et configurer PostgreSQL }
+\addcontentsline{toc}{section}{Installer et configurer PostgreSQL}
+
+\section{Installer et configurer PostgreSQL -- Phase I}
+\index[general]{Installer et configurer PostgreSQL -- Phase I }
+\index[general]{Phase I!Installer et configurer PostgreSQL -- }
+\addcontentsline{toc}{section}{Installer et configurer PostgreSQL -- Phase
+I}
+
+Attention !!! Si vous envisagez d'utiliser PostgreSQL, vous devriez
+\^etre conscient de la philosophie des mises \`a jour de PostgreSQL qui
+peut \^etre d\'estabilisant dans un environnement de
+production. En gros, pour chaque mise \`a jour vers une version majeure,
+vous devez exporter vos bases de donn\'ees au format ASCII, faire la
+mise \`a jour, et recharger vos bases de donn\'ees. Ceci est d\^u au \`a des
+mises \`a jour fr\'equentes du "format de donn\'ees" d'une version \`a l'autre,
+et aucun outil n'est fourni pour effectuer la conversion automatiquement.
+Si vous omettez d'exporter vos bases au format ASCII, elles peuvent
+devenir compl\`etement inutiles si aucun des nouveaux outils ne peut y
+acc\'eder en raison d'un changement de format, auquel cas le serveur
+PostgreSQL sera dans l'incapacit\'e de d\'emarrer.
+
+Si vous avez utilis\'e l'option {\bf ./configure
+\verb{--{with-postgresql=PostgreSQL-Directory} pour configurer {\bf Bacula}, vous
+avez besoin d'installer la version 7.3 ou sup\'erieure de PostgreSQL.
+ATTENTION! Les versions pr\'ealables \`a la 7.3 ne fonctionnent pas avec
+Bacula. Si PostgreSQL est install\'e dans ses r\'epertoires sandards, seule
+l'option {\bf \verb{--{with-postgresql} est n\'ecessaire, le programme de
+configuration scrutant tous les r\'epertoires standards. Si PostgreSQL est
+install\'e dans votre r\'epertoire de travail ou dans un r\'epertoire
+atypique, il faut pr\'eciser l'option {\bf \verb{--{with-postgresql} suivie du
+r\'epertoire {\it ad hoc}.
+
+Installer et configurer PostgreSQL n'est pas compliqu\'e mais peut \^etre
+d\'eroutant la premi\`ere fois. Si vous pr\'ef\'erez, vous pouvez utiliser le
+paquet de votre distribution. Les paquets binaires sont disponibles sur la
+plupart des mirroirs de PostgreSQL.
+
+Si vous pr\'ef\'erez installer PostgreSQL \`a partir des sources, nous vous
+recommandons de suivre les instructions de la
+\elink{documentation PostgreSQL}{http://www.postgresql.org/docs/}.
+
+Si vous utilisez PostgreSQL pour FreeBSD,
+\elink{cet article}{http://www.freebsddiary.org/postgresql.php} vous sera peut
+\^etre utile. M\^eme si vous n'utilisez pas FreeBSD, l'article contient des
+informations utiles \`a la configuration et au param\'etrage de PostgreSQL.
+
+Apr\`es l'installation de PostgreSQL, terminez l'installation de {\bf Bacula}.
+Ensuite, quand Bacula sera install\'e, reprenez ce chapitre pour terminer
+l'installation. Notez que les fichiers d'installation utilis\'es dans cette
+seconde phase de l'installation de PostgreSQL sont cr\'e\'es durant
+l'installation de Bacula.
+\label{PostgreSQL_phase2}
+
+\section{Installer et configurer PostgreSQL -- Phase II}
+\index[general]{Phase II!Installer et configurer PostgreSQL -- }
+\index[general]{Installer et configurer PostgreSQL -- Phase II }
+\addcontentsline{toc}{section}{Installer et configurer PostgreSQL -- Phase
+II}
+
+Si vous en \^etes l\`a, vous avez construit et install\'e PostgreSQL, ou vous
+aviez d\'ej\`a un serveur PostgreSQL existant et vous avez configur\'e et
+install\'e {\bf Bacula}. Dans le cas contraire, nous vous invitons \`a le
+faire avant de poursuivre.
+
+Notez bien que la commande {\bf ./configure} utilis\'ee pour
+construire {\bf Bacula} n\'ecessite d'ajouter l'option {\bf
+\verb{--{with-postgresql=repertoire\_de\_PostgreSQL}, o\`u {\bf
+repertoire\_de\_PostgreSQL} sp\'ecifie le chemin de PostgreSQL indiqu\'e \`a
+la commande ./configure. (si vous n'avez pas sp\'ecifi\'e de r\'epertoire ou
+si PostgreSQL est install\'e dans son r\'epertoire par d\'efaut, cette option
+n'est pas n\'ecessaire). Cette option est n\'ecessaire pour que Bacula puisse
+trouver les fichiers d'en-t\^ete et les librairies d'interface \`a PostgreSQL.
+
+
+{\bf Bacula} installe les scripts pour la gestion de la base de donn\'ees
+(cr\'eer, d\'etruire, cr\'eer les tables, etc.) dans le r\'epertoire principal
+de l'installation. Ces fichiers sont de la forme *\_bacula\_* (par exemple
+create\_bacula\_database). Ces fichiers sont \'egalement disponibles dans le
+r\'epertoire \lt{}bacula-src\gt{}/src/cats apr\`es que la commande ./configure
+ait \'et\'e lanc\'ee. Si vous consultez le fichier create\_bacula\_database,
+vous verrez qu'il fait appel \`a create\_postgresql\_database. Les fichiers
+*\_bacula\_* sont fournis pour faciliter les choses. Peu importe la base de
+donn\'ees choisie, create\_bacula\_database cr\'eera la base de donn\'ees.
+
+Maintenant vous allez cr\'eer la base de donn\'ees PostgreSQL et les tables
+utilis\'ees par Bacula. On pr\'esume dans la suite que votre serveur
+PostgreSQL fonctionne. Vous devez ex\'ecuter les diff\'erentes \'etapes
+ci-dessous en tant qu'utilisateur autoris\'e \`a cr\'eer des bases. Ceci peut
+\^etre fait avec l'utilisateur PostgreSQL (sur la plupart des syst\`emes il
+s'agit de pgsql. NDT: sur debian il s'agit de postgres)
+
+\begin{enumerate}
+\item cd \lt{}r\'epertoire\_d\_installation\gt{}
+
+ Ce r\'epertoire contient le catalogue des routines d'interfaces.
+
+\item ./create\_bacula\_database
+
+ Ce script cr\'e\'e le catalogue {\bf bacula} PostgreSQL. S'il \'echoue,
+ c'est probablement que vous n'avez pas les droits requis sur la
+ base de donn\'ees. Sur la plupart des syst\`emes, le propri\'etaire de
+ la base de donn\'ees est {\bf pgsql}, et sur d'autres tels que RedHat ou
+ Fedora, c'est {\bf postgres}. Vous pouvez d\'eterminer lequel en examinant
+ le fichier /etc/passwd. Pour cr\'eer un nouvel utilisateur avec votre nom
+ ou le nom {\bf bacula}, vous pouvez faire ce qui suit :
+
+\begin{verbatim}
+ su
+ (entrez le mot de passe root)
+ su pgsql (ou postgres)
+ createuser kern (ou peut-\^etre bacula)
+ Shall the new user be allowed to create databases? (y/n) y
+ Shall the new user be allowed to create more new users? (y/n) (choisissez ce que vous voulez)
+ exit
+\end{verbatim}
+
+
+ A ce stade, vous devriez pouvoir ex\'ecuter la commande ./create\_bacula\_database
+
+\item ./make\_bacula\_tables
+
+ Cr\'e\'ee les tables utilis\'ees par {\bf Bacula}.
+\item ./grant\_bacula\_privileges
+
+ Cr\'e\'ee l'utilisateur de la base de donn\'ees {\bf bacula} avec des droits
+d'acc\`es restreints. Vous pouvez modifier ce script pour cadrer avec votre
+propre configuration. Attention, cette base n'est pas prot\'eg\'ee par un mot
+de passe.
+
+\end{enumerate}
+
+Chacun de ces scripts (create\_bacula\_database, make\_bacula\_tables et
+grant\_bacula\_privileges) permet l'ajout d'arguments en ligne de commande.
+Ceci peut \^etre utile pour sp\'ecifier le nom de l'utilisateur. Par exemple,
+vous pouvez avoir besoin d'ajouter {\bf -h nom\_d\_hote} \`a la ligne de
+commande pour sp\'ecifier le serveur de base de donn\'ees distant.
+
+Pour avoir un bon aper\c{c}u des droits d'acc\`es que vous avez sp\'ecifi\'e
+vous pouvez utiliser la commande
+
+\footnotesize
+\begin{verbatim}
+
+repertoire_de_PostgreSQL/bin/psql --command \\dp bacula
+\end{verbatim}
+\normalsize
+
+J'ai rencontr\'e un probl\`eme de permissions avec le mot de passe. J'ai finalement
+du modifier mon fichier {\bf pg\_hba.conf} (situ\'e dans /var/lib/pgsql/data sur ma
+machine) :
+
+\footnotesize
+\begin{verbatim}
+de
+ local all all ident sameuser
+vers
+ local all all trust sameuser
+\end{verbatim}
+\normalsize
+
+Ceci a r\'esolu le probl\`eme pour moi, mais ce n'est pas pas forc\'ement une bonne
+chose du point de vue de la s\'ecurit\'e, mais j'ai ainsi pu ex\'ecuter mes scripts de
+r\'egression sans mot de passe.
+
+Un moyen plus s\'ecuris\'e pour l'authentification aupr\`es de la base de donn\'ees
+consiste \`a utiliser le hachage MD5 des mots de passe. Pour cela, \'editez les
+fichier {\bf pg\_hba.conf}, et ajoutez ajoutez ce qui suit juste avant les lignes
+"local" et "host" existantes :
+
+\footnotesize
+\begin{verbatim}
+ local bacula bacula md5
+\end{verbatim}
+\normalsize
+
+Puis red\'emarrez le {\it daemon} Postgres (la plupart du temps, avec
+ "/etc/init.d/postgresql restart") pour activer cette nouvelle r\`egle
+d'authentification.
+
+Ensuite, en tant qu'administrateur Postgres (connectez-vous en tant
+qu'utilisateur postgres ou en utilisant {\bf su} pour devenir root, puis
+ {\bf su postgres}), ajoutez un mot de passe \`a la base de donn\'ees bacula
+pour l'utilisateur bacula avec les commandes suivantes :
+
+\footnotesize
+\begin{verbatim}
+ \$ psql bacula
+ bacula=# alter user bacula with password 'secret';
+ ALTER USER
+ bacula=# \\q
+\end{verbatim}
+\normalsize
+
+Enfin, il vous faudra ajouter ce mot de passe en deux endroits du fichier
+bacula-dir.conf : au niveau de la ressource Catalog et au niveau de la
+directive RunBeforeJob de la ressource Job BackupCatalog. Avec les mots de
+passe en place, ces deux lignes devraient ressembler \`a ceci :
+
+\footnotesize
+\begin{verbatim}
+ dbname = bacula; user = bacula; password = "secret"
+ ... and ...
+ RunBeforeJob = "/etc/make_catalog_backup bacula bacula secret"
+\end{verbatim}
+\normalsize
+
+Naturellement, vous devriez choisir un meilleur mot de passe, et vous assurer
+que le fichier bacula-dir.conf qui contient ce mot de passe n'est lisible
+que par root.
+
+M\^eme avec ces restrictions, il reste un probl\`eme de s\'ecurit\'e avec cette approche :
+sur certaines plateformes, la variable d'environnement utilis\'ee pour soumettre le
+mot de passe \`a Postgres est disponible pour tout utilisateur
+local du syst\`eme. Pour supprimer ce probl\`eme, l'\'equipe Postgres a d\'ecr\'et\'e
+obsol\`ete ce m\'ecanisme de passage de mot de passe par variable d'environnement et
+recommande d'utiliser un fichier .pgpass. Pour utiliser ce m\'ecanisme, cr\'eez un fichier
+nomm\'e .pgpass vcontenant une simple ligne :
+
+\footnotesize
+\begin{verbatim}
+ localhost:5432:bacula:bacula:secret
+\end{verbatim}
+\normalsize
+
+Ce fichier devrait \^etre copi\'e dans les r\'epertoires personnels (NDT : home directories)
+de tous les comptes susceptibles d'avoir besoin d'acc\'eder \`a la base de donn\'ees :
+typiquement, il s'agit de root, bacula et tout utilisateur de la console Bacula. Les fichiers
+doivent appartenir aux utilisateur et groupe correspondant : root:root pour la copie
+dans ~root, etc. Les permissions doivent \^etre positionn\'ees \`a 600 pour limiter
+l'acc\`es au propri\'etaire du fichier.
+
+\section{R\'einitialiser la base des catalogues (de sauvegardes)}
+\index[general]{R\'einitialiser la base des catalogues (de sauvegardes) }
+\index[general]{Sauvegardes!R\'einitialiser la base des catalogues de }
+\addcontentsline{toc}{section}{R\'einitialiser la base des catalogues (de
+sauvegardes)}
+
+Apr\`es avoir fait un certain nombre de tests avec {\bf Bacula}, vous aurez
+tr\`es certainement envie de nettoyer le catalogue des sauvegardes et faire
+dispara{\^\i}tre tous les travaux de tests que vous avez lanc\'es. Pour ce
+faire, vous pouvez ex\'ecuter les commandes suivantes:
+
+\footnotesize
+\begin{verbatim}
+
+ cd <r\'epertoire_d_installation>
+ ./drop_bacula_tables
+ ./make_bacula_tables
+ ./grant_bacula_privileges
+\end{verbatim}
+\normalsize
+
+Attention! Toutes les informations contenues dans cette base seront perdues et
+vous repartirez de z\'ero. Si vous avez \'ecrit sur certains volumes (m\'edia
+de sauvegarde), vous devrez \'ecrire une marque de fin de fichier (EOF) sur
+chacun d'eux afin que {\bf Bacula} puisse les r\'eutiliser. Pour ce faire:
+
+\footnotesize
+\begin{verbatim}
+
+ (arr\^eter Baula ou demonter les volumes)
+ mt -f /dev/nst0 rewind
+ mt -f /dev/nst0 weof
+\end{verbatim}
+\normalsize
+
+o\`u vous devrez remplacer {\bf /dev/nst0} par le chemin appropri\'e de votre
+lecteur de sauvegarde.
+
+\section{Installer PostgreSQL avec les RPMs}
+\index[general]{PostgreSQL!Installer avec les RPMs}
+\index[general]{Installer PostgreSQL avec les RPMs}
+\addcontentsline{toc}{section}{Installer PostgreSQL avec les RPMs}
+Si vous installez PostgreSQL avec les RPMs, il vous faut installer les
+binaires PostgreSQL ainsi que les librairies clientes. Ces derni\`eres font
+g\'en\'eralement partie de paquetages de d\'eveloppement, aussi vous devez installer :
+
+\footnotesize
+\begin{verbatim}
+ postgresql
+ postgresql-devel
+\end{verbatim}
+\normalsize
+
+Il en va de m\^eme avec la plupart des gestionnaires de paquetages.
+
+\section{Migrer de MySQL \`a PostgreSQL}
+\index[general]{Migrer de MySQL \`a PostgreSQL }
+\index[general]{PostgreSQL!Migrer de MySQL \`a }
+\addcontentsline{toc}{section}{Migrer de MySQL \`a PostgreSQL}
+
+La proc\'edure de migration pr\'esent\'ee ici \`a fonctionn\'e pour Norm
+Dressler \lt{}ndressler at dinmar dot com\gt{}
+
+Ce process a \'et\'e test\'e en utilisant les versions suivantes des
+diff\'erents logiciels:
+
+\begin{itemize}
+\item Linux Mandrake 10/Kernel 2.4.22-10 SMP
+\item MySQL Ver 12.21 Distrib 4.0.15, pour mandrake-linux-gnu (i586)
+\item PostgreSQL 7.3.4
+\item Bacula 1.34.5
+ \end{itemize}
+
+ATTENTION! Par pr\'ecaution, r\'ealisez une sauvegarde compl\`ete de vos
+syst\`emes avant de proc\'eder \`a cette migration.
+
+\begin{enumerate}
+\item Arr\^etez bacula (cd /etc/bacula;./bacula stop)
+\item Lancez la commande pour extraire les donn\'ees de votre base MySQL:
+
+ \footnotesize
+\begin{verbatim}
+
+ mysqldump -f -t -n >bacula-backup.dmp
+
+\end{verbatim}
+\normalsize
+
+\item Faites une sauvegarde de votre r\'epertoire /etc/bacula (mais laisser
+ l'original en place ).
+\item Allez dans le r\'epertoire source de {\bf Bacula} et reconstruisez le en
+ incluant le support PostgreSQL au lieu de celui de MySQL . V\'erifiez que le
+ fichier config.log de votre configuration originale et remplacez enable-mysql
+par enable-postgresql.
+\item Recompilez Bacula avec la commande make et si tout se passe correctement
+ lancez un "make install".
+\item Arr\^etez MySQL.
+\item Lancez PostgreSQL sur votre syst\`eme.
+\item Cr\'eez un utilisateur {\bf Bacula} dans Postgres avec la commande
+ "createuser". En fonction de votre installation, vous serez peut \^etre
+ amen\'e \`a faire un "su" vers l'utilisateur ad\'equat (NDT: su postgres).
+\item Verifiez que le fichier pg\_hba.conf (NdT sur Debian:
+ /etc/postgres/pg\_hba.conf) contient les permissions ad\'equates pour
+ permettre \`a {\bf Bacula} d'acc\'eder au serveur. Le mien contient les
+informations suivantes, et il est situ\'e sur un r\'eseau s\'ecuris\'e,
+
+\footnotesize
+\begin{verbatim}
+
+local all all trust
+
+host all all 127.0.0.1 255.255.255.255 trust
+
+ATTENTION: vous devez red\'emmarer PostgreSQL si vous faites des changements dans ce fichier.
+
+\end{verbatim}
+\normalsize
+
+\item Allez dans le r\'epertoire /etc/bacula et pr\'eparez la base de
+ donn\'ees avec les commandes suivantes:
+
+\footnotesize
+\begin{verbatim}
+
+./create_postgresql_database
+
+./make_postgresql_tables
+
+./grant_postgresql_privileges
+
+\end{verbatim}
+\normalsize
+
+\item Verifiez que vous avez acc\`es \`a la base de donn\'ees:
+
+ \footnotesize
+\begin{verbatim}
+
+psql -Ubacula bacula
+
+\end{verbatim}
+\normalsize
+
+Vous ne devriez avoir aucune erreur.
+\item Chargez la base PostgreSQL avec l'extraction MySQL gr\^ace \`a la
+ commande:
+
+\footnotesize
+\begin{verbatim}
+
+psql -Ubacula bacula <bacula-backup.dmp>
+
+\end{verbatim}
+\normalsize
+
+\item R\'eindexez vos tables avec les commandes suivantes:
+
+ \footnotesize
+\begin{verbatim}
+
+psql -Ubacula bacula
+
+SELECT SETVAL('basefiles_baseid_seq', (SELECT
+MAX(baseid) FROM basefiles));
+
+SELECT SETVAL('client_clientid_seq', (SELECT
+MAX(clientid) FROM client));
+
+SELECT SETVAL('file_fileid_seq', (SELECT MAX(fileid)
+FROM file));
+
+SELECT SETVAL('filename_filenameid_seq', (SELECT
+MAX(filenameid) FROM filename));
+
+SELECT SETVAL('fileset_filesetid_seq', (SELECT
+MAX(filesetid) FROM fileset));
+
+SELECT SETVAL('job_jobid_seq', (SELECT MAX(jobid) FROM job));
+
+SELECT SETVAL('jobmedia_jobmediaid_seq', (SELECT
+MAX(jobmediaid) FROM jobmedia));
+
+SELECT SETVAL('media_mediaid_seq', (SELECT MAX(mediaid) FROM media));
+
+SELECT SETVAL('path_pathid_seq', (SELECT MAX(pathid) FROM path));
+
+SELECT SETVAL('pool_poolid_seq', (SELECT MAX(poolid) FROM pool));
+
+\end{verbatim}
+\normalsize
+
+\item Parvenu ici, lancez {\bf Bacula}, v\'erifiez votre librairie et
+ faites un test pour valider que tout s'est bien d\'eroul\'e.
+\end{enumerate}
+
+\section{Mettre \`a jour PostgreSQL}
+\index[general]{Mettre \`a jour PostgreSQL }
+\index[general]{Mettre \`a jour!PostgreSQL }
+\addcontentsline{toc}{section}{Mettre \`a jour PostgreSQL}
+Si vous mettez PosgreSQL \`a jour, vous devez reconfigurer, recompiler et
+r\'einstaller Bacula, faute de quoi vous constaterez probalement des
+erreurs \'etranges.
+Pour cela, il vous faut installer le RPM source, modifier le fichier bacula.spec
+pour l'accorder \`a votre version de PostgreSQL, reconstruire le RPM et l'installer.
+
+If you upgrade PostgreSQL, you must reconfigure, rebuild, and re-install
+Bacula otherwise you are likely to get bizarre failures. If you
+to modify the bacula.spec file to account for the new PostgreSQL version.
+You can do so by rebuilding from the source rpm. To do so, you may need
+install from rpms and you upgrade PostgreSQL, you must also rebuild Bacula.
+
+
+\section{Credits}
+\index[general]{Credits }
+\addcontentsline{toc}{section}{Credits}
+
+Tous mes remerciements \`a Dan Languille pour l'\'ecriture du driver
+PostgreSQL qui deviendra tr\`es certainement la base de donn\'ees la plus
+r\'eput\'ee utilisable avec {\bf Bacula}
--- /dev/null
+/*
+ * html2latex
+ */
+
+available {
+ sun4_sunos.4
+ sun4_solaris.2
+ rs_aix.3
+ rs_aix.4
+ sgi_irix
+}
+
+description {
+ From Jeffrey Schaefer, Geometry Center. Translates HTML document to LaTeX
+}
+
+install {
+ bin/html2latex /afs/rpi.edu/dept/acs/rpinfo/filters/GChtml2latex/html2latex
+ bin/html2latex.tag /afs/rpi.edu/dept/acs/rpinfo/filters/GChtml2latex/html2latex.tag
+ bin/html2latex-local.tag /afs/rpi.edu/dept/acs/rpinfo/filters/GChtml2latex/html2latex-local.tag
+ bin/webtex2latex.tag /afs/rpi.edu/dept/acs/rpinfo/filters/GChtml2latex/webtex2latex.tag
+ man/man1/html2latex.1 /afs/rpi.edu/dept/acs/rpinfo/filters/GChtml2latex/html2latex.1
+}
--- /dev/null
+%%
+%%
+
+\chapter{Installing and Configuring SQLite}
+\label{SqlLiteChapter}
+\index[general]{Installing and Configuring SQLite }
+\index[general]{SQLite!Installing and Configuring }
+
+Please note that SQLite both versions 2 and 3 are not network enabled,
+which means that they must be linked into the Director rather than accessed
+by the network as MySQL and PostgreSQL are. This has two consequences:
+\begin{enumerate}
+\item SQLite cannot be used in the {\bf bweb} web GUI package.
+\item If you use SQLite, and your Storage daemon is not on the same
+machine as your Director, you will need to transfer your database
+to the Storage daemon's machine before you can use any of the SD tools
+such as {\bf bscan}, ...
+\end{enumerate}
+
+\section{Installing and Configuring SQLite -- Phase I}
+\index[general]{Phase I!Installing and Configuring SQLite -- }
+\index[general]{Installing and Configuring SQLite -- Phase I }
+
+If you use the {\bf ./configure \verb:--:with-sqlite} statement for configuring {\bf
+Bacula}, you will need SQLite version 2.8.16 or later installed. Our standard
+location (for the moment) for SQLite is in the dependency package {\bf
+depkgs/sqlite-2.8.16}. Please note that the version will be updated as new
+versions are available and tested.
+
+Installing and Configuring is quite easy.
+
+\begin{enumerate}
+\item Download the Bacula dependency packages
+\item Detar it with something like:
+
+ {\bf tar xvfz depkgs.tar.gz}
+
+ Note, the above command requires GNU tar. If you do not have GNU tar, a
+ command such as:
+
+ {\bf zcat depkgs.tar.gz | tar xvf -}
+
+ will probably accomplish the same thing.
+
+\item {\bf cd depkgs}
+
+\item {\bf make sqlite}
+
+\end{enumerate}
+
+
+Please note that the {\bf ./configure} used to build {\bf Bacula} will need to
+include {\bf \verb:--:with-sqlite} or {\bf \verb:--:with-sqlite3} depending
+one which version of SQLite you are using. You should not use the {\bf
+\verb:--:enable-batch-insert} configuration parameter for Bacula if you
+are using SQLite version 2 as it is probably not thread safe. If you
+are using SQLite version 3, you may use the {\bf \verb:--:enable-batch-insert}
+configuration option with Bacula, but when building SQLite3 you MUST
+configure it with {\bf \verb:--:enable-threadsafe} and
+{\bf \verb:--:enable-cross-thread-connections}.
+
+By default, SQLite3 is now run with {\bf PRAGMA synchronous=OFF} this
+increases the speed by more than 30 time, but it also increases the
+possibility of a corrupted database if your server crashes (power failure
+or kernel bug). If you want more security, you can change the PRAGMA
+that is used in the file src/version.h.
+
+
+At this point, you should return to completing the installation of {\bf
+Bacula}.
+
+
+\section{Installing and Configuring SQLite -- Phase II}
+\label{phase2}
+\index[general]{Phase II!Installing and Configuring SQLite -- }
+\index[general]{Installing and Configuring SQLite -- Phase II }
+
+This phase is done {\bf after} you have run the {\bf ./configure} command to
+configure {\bf Bacula}.
+
+{\bf Bacula} will install scripts for manipulating the database (create,
+delete, make tables etc) into the main installation directory. These files
+will be of the form *\_bacula\_* (e.g. create\_bacula\_database). These files
+are also available in the \lt{}bacula-src\gt{}/src/cats directory after
+running ./configure. If you inspect create\_bacula\_database, you will see
+that it calls create\_sqlite\_database. The *\_bacula\_* files are provided
+for convenience. It doesn't matter what database you have chosen;
+create\_bacula\_database will always create your database.
+
+At this point, you can create the SQLite database and tables:
+
+\begin{enumerate}
+\item cd \lt{}install-directory\gt{}
+
+ This directory contains the Bacula catalog interface routines.
+
+\item ./make\_sqlite\_tables
+
+ This script creates the SQLite database as well as the tables used by {\bf
+ Bacula}. This script will be automatically setup by the {\bf ./configure}
+ program to create a database named {\bf bacula.db} in {\bf Bacula's} working
+ directory.
+\end{enumerate}
+
+\section{Linking Bacula with SQLite}
+\index[general]{SQLite!Linking Bacula with }
+\index[general]{Linking Bacula with SQLite }
+
+If you have followed the above steps, this will all happen automatically and
+the SQLite libraries will be linked into {\bf Bacula}.
+
+\section{Testing SQLite}
+\index[general]{SQLite!Testing }
+\index[general]{Testing SQLite }
+
+We have much less "production" experience using SQLite than using MySQL.
+SQLite has performed flawlessly for us in all our testing. However,
+several users have reported corrupted databases while using SQLite. For
+that reason, we do not recommend it for production use.
+
+If Bacula crashes with the following type of error when it is started:
+\footnotesize
+\begin{verbatim}
+Using default Catalog name=MyCatalog DB=bacula
+Could not open database "bacula".
+sqlite.c:151 Unable to open Database=/var/lib/bacula/bacula.db.
+ERR=malformed database schema - unable to open a temporary database file
+for storing temporary tables
+\end{verbatim}
+\normalsize
+
+this is most likely caused by the fact that some versions of
+SQLite attempt to create a temporary file in the current directory.
+If that fails, because Bacula does not have write permission on
+the current directory, then you may get this errr. The solution is
+to start Bacula in a current directory where it has write permission.
+
+
+\section{Re-initializing the Catalog Database}
+\index[general]{Database!Re-initializing the Catalog }
+\index[general]{Re-initializing the Catalog Database }
+
+After you have done some initial testing with {\bf Bacula}, you will probably
+want to re-initialize the catalog database and throw away all the test Jobs
+that you ran. To do so, you can do the following:
+
+\footnotesize
+\begin{verbatim}
+ cd <install-directory>
+ ./drop_sqlite_tables
+ ./make_sqlite_tables
+\end{verbatim}
+\normalsize
+
+Please note that all information in the database will be lost and you will be
+starting from scratch. If you have written on any Volumes, you must write an
+end of file mark on the volume so that Bacula can reuse it. Do so with:
+
+\footnotesize
+\begin{verbatim}
+ (stop Bacula or unmount the drive)
+ mt -f /dev/nst0 rewind
+ mt -f /dev/nst0 weof
+\end{verbatim}
+\normalsize
+
+Where you should replace {\bf /dev/nst0} with the appropriate tape drive
+device name for your machine.
--- /dev/null
+#!/usr/bin/perl -w
+#
+use strict;
+
+# Used to change the names of the image files generated by latex2html from imgxx.png
+# to meaningful names. Provision is made to go either from or to the meaningful names.
+# The meaningful names are obtained from a file called imagename_translations, which
+# is generated by extensions to latex2html in the make_image_file subroutine in
+# bacula.perl.
+
+# Opens the file imagename_translations and reads the contents into a hash.
+# The hash is creaed with the imgxx.png files as the key if processing TO
+# meaningful filenames, and with the meaningful filenames as the key if
+# processing FROM meaningful filenames.
+# Then opens the html file(s) indicated in the command-line arguments and
+# changes all image references according to the translations described in the
+# above file. Finally, it renames the image files.
+#
+# Original creation: 3-27-05 by Karl Cunningham.
+# Modified 5-21-05 to go FROM and TO meaningful filenames.
+#
+my $TRANSFILE = "imagename_translations";
+my $path;
+
+# Loads the contents of $TRANSFILE file into the hash referenced in the first
+# argument. The hash is loaded to translate old to new if $direction is 0,
+# otherwise it is loaded to translate new to old. In this context, the
+# 'old' filename is the meaningful name, and the 'new' filename is the
+# imgxx.png filename. It is assumed that the old image is the one that
+# latex2html has used as the source to create the imgxx.png filename.
+# The filename extension is taken from the file
+sub read_transfile {
+ my ($trans,$direction) = @_;
+
+ if (!open IN,"<$path$TRANSFILE") {
+ print "WARNING: Cannot open image translation file $path$TRANSFILE for reading\n";
+ print " Image filename translation aborted\n\n";
+ exit 0;
+ }
+
+ while (<IN>) {
+ chomp;
+ my ($new,$old) = split(/\001/);
+
+ # Old filenames will usually have a leading ./ which we don't need.
+ $old =~ s/^\.\///;
+
+ # The filename extension of the old filename must be made to match
+ # the new filename because it indicates the encoding format of the image.
+ my ($ext) = $new =~ /(\.[^\.]*)$/;
+ $old =~ s/\.[^\.]*$/$ext/;
+ if ($direction == 0) {
+ $trans->{$new} = $old;
+ } else {
+ $trans->{$old} = $new;
+ }
+ }
+ close IN;
+}
+
+# Translates the image names in the file given as the first argument, according to
+# the translations in the hash that is given as the second argument.
+# The file contents are read in entirely into a string, the string is processed, and
+# the file contents are then written. No particular care is taken to ensure that the
+# file is not lost if a system failure occurs at an inopportune time. It is assumed
+# that the html files being processed here can be recreated on demand.
+#
+# Links to other files are added to the %filelist for processing. That way,
+# all linked files will be processed (assuming they are local).
+sub translate_html {
+ my ($filename,$trans,$filelist) = @_;
+ my ($contents,$out,$this,$img,$dest);
+ my $cnt = 0;
+
+ # If the filename is an external link ignore it. And drop any file:// from
+ # the filename.
+ $filename =~ /^(http|ftp|mailto)\:/ and return 0;
+ $filename =~ s/^file\:\/\///;
+ # Load the contents of the html file.
+ if (!open IF,"<$path$filename") {
+ print "WARNING: Cannot open $path$filename for reading\n";
+ print " Image Filename Translation aborted\n\n";
+ exit 0;
+ }
+
+ while (<IF>) {
+ $contents .= $_;
+ }
+ close IF;
+
+ # Now do the translation...
+ # First, search for an image filename.
+ while ($contents =~ /\<\s*IMG[^\>]*SRC=\"/si) {
+ $contents = $';
+ $out .= $` . $&;
+
+ # The next thing is an image name. Get it and translate it.
+ $contents =~ /^(.*?)\"/s;
+ $contents = $';
+ $this = $&;
+ $img = $1;
+ # If the image is in our list of ones to be translated, do it
+ # and feed the result to the output.
+ $cnt += $this =~ s/$img/$trans->{$img}/ if (defined($trans->{$img}));
+ $out .= $this;
+ }
+ $out .= $contents;
+
+ # Now send the translated text to the html file, overwriting what's there.
+ open OF,">$path$filename" or die "Cannot open $path$filename for writing\n";
+ print OF $out;
+ close OF;
+
+ # Now look for any links to other files and add them to the list of files to do.
+ while ($out =~ /\<\s*A[^\>]*HREF=\"(.*?)\"/si) {
+ $out = $';
+ $dest = $1;
+ # Drop an # and anything after it.
+ $dest =~ s/\#.*//;
+ $filelist->{$dest} = '' if $dest;
+ }
+ return $cnt;
+}
+
+# REnames the image files spefified in the %translate hash.
+sub rename_images {
+ my $translate = shift;
+ my ($response);
+
+ foreach (keys(%$translate)) {
+ if (! $translate->{$_}) {
+ print " WARNING: No destination Filename for $_\n";
+ } else {
+ $response = `mv -f $path$_ $path$translate->{$_} 2>&1`;
+ $response and print "ERROR from system $response\n";
+ }
+ }
+}
+
+#################################################
+############# MAIN #############################
+################################################
+
+# %filelist starts out with keys from the @ARGV list. As files are processed,
+# any links to other files are added to the %filelist. A hash of processed
+# files is kept so we don't do any twice.
+
+# The first argument must be either --to_meaningful_names or --from_meaningful_names
+
+my (%translate,$search_regex,%filelist,%completed,$thisfile);
+my ($cnt,$direction);
+
+my $arg0 = shift(@ARGV);
+$arg0 =~ /^(--to_meaningful_names|--from_meaningful_names)$/ or
+ die "ERROR: First argument must be either \'--to_meaningful_names\' or \'--from_meaningful_names\'\n";
+
+$direction = ($arg0 eq '--to_meaningful_names') ? 0 : 1;
+
+(@ARGV) or die "ERROR: Filename(s) to process must be given as arguments\n";
+
+# Use the first argument to get the path to the file of translations.
+my $tmp = $ARGV[0];
+($path) = $tmp =~ /(.*\/)/;
+$path = '' unless $path;
+
+read_transfile(\%translate,$direction);
+
+foreach (@ARGV) {
+ # Strip the path from the filename, and use it later on.
+ if (s/(.*\/)//) {
+ $path = $1;
+ } else {
+ $path = '';
+ }
+ $filelist{$_} = '';
+
+ while ($thisfile = (keys(%filelist))[0]) {
+ $cnt += translate_html($thisfile,\%translate,\%filelist) if (!exists($completed{$thisfile}));
+ delete($filelist{$thisfile});
+ $completed{$thisfile} = '';
+ }
+ print "translate_images.pl: $cnt image filenames translated ",($direction)?"from":"to"," meaningful names\n";
+}
+
+rename_images(\%translate);
--- /dev/null
+#!/bin/sh
+#
+# Script file to update the Bacula version
+#
+out=/tmp/$$
+VERSION=`sed -n -e 's/^.*VERSION.*"\(.*\)"$/\1/p' /home/kern/bacula/k/src/version.h`
+DATE=`sed -n -e 's/^.*[ \t]*BDATE.*"\(.*\)"$/\1/p' /home/kern/bacula/k/src/version.h`
+. ./do_echo
+sed -f ${out} version.tex.in >version.tex
+rm -f ${out}
--- /dev/null
+#!/bin/sh
+#
+# Script file to update the Bacula version
+#
+out=/tmp/$$
+VERSION=`sed -n -e 's/^.*VERSION.*"\(.*\)"$/\1/p' @bacula@/src/version.h`
+DATE=`sed -n -e 's/^.*[ \t]*BDATE.*"\(.*\)"$/\1/p' @bacula@/src/version.h`
+. ./do_echo
+sed -f ${out} version.tex.in >version.tex
+rm -f ${out}
--- /dev/null
+2.3.6 (04 November 2007)
--- /dev/null
+@VERSION@ (@DATE@)
--- /dev/null
+#
+#
+# Makefile for LaTeX
+#
+# To build everything do
+# make tex
+# make web
+# make html
+# make dvipdf
+#
+# or simply
+#
+# make
+#
+# for rapid development do:
+# make tex
+# make show
+#
+#
+# If you are having problems getting "make" to work, debugging it is
+# easier if can see the output from latex, which is normally redirected
+# to /dev/null. To see it, do the following:
+#
+# cd docs/manual
+# make tex
+# latex bacula.tex
+#
+# typically the latex command will stop indicating the error (e.g. a
+# missing \ in front of a _ or a missing { or ] ...
+#
+# The following characters must be preceded by a backslash
+# to be entered as printable characters:
+#
+# # $ % & ~ _ ^ \ { }
+#
+
+IMAGES=../../../images
+
+DOC=concepts
+
+first_rule: all
+
+all: tex web dvipdf mini-clean
+
+.SUFFIXES: .tex .html
+.PHONY:
+.DONTCARE:
+
+
+tex:
+ @./update_version
+ @echo "Making version `cat version.tex`"
+ @cp -fp ${IMAGES}/hires/*.eps .
+ @touch ${DOC}i-dir.tex ${DOC}i-fd.tex ${DOC}i-sd.tex \
+ ${DOC}i-console.tex ${DOC}i-general.tex
+ latex -interaction=batchmode ${DOC}.tex
+ makeindex ${DOC}.idx -o ${DOC}.ind 2>/dev/null
+ makeindex ${DOC}.ddx -o ${DOC}.dnd >/dev/null 2>/dev/null
+ makeindex ${DOC}.fdx -o ${DOC}.fnd >/dev/null 2>/dev/null
+ makeindex ${DOC}.sdx -o ${DOC}.snd >/dev/null 2>/dev/null
+ makeindex ${DOC}.cdx -o ${DOC}.cnd >/dev/null 2>/dev/null
+ latex -interaction=batchmode ${DOC}.tex
+
+pdf:
+ @echo "Making pdfm"
+ @cp -fp ${IMAGES}/hires/*.eps .
+ dvipdfm -p a4 ${DOC}.dvi
+
+dvipdf:
+ @echo "Making dvi to pdf"
+ @cp -fp ${IMAGES}/hires/*.eps .
+ dvipdf ${DOC}.dvi ${DOC}.pdf
+
+html:
+ @echo " "
+ @echo "Making html"
+ @cp -fp ${IMAGES}/*.eps .
+ @rm -f next.eps next.png prev.eps prev.png up.eps up.png
+ @(if [ -f imagename_translations ] ; then \
+ ./translate_images.pl --from_meaningful_names ${DOC}.html; \
+ fi)
+ latex2html -white -no_subdir -split 0 -toc_stars -white -notransparent \
+ -init_file latex2html-init.pl ${DOC} >tex.out 2>&1
+ ./translate_images.pl --to_meaningful_names ${DOC}.html
+ @echo "Done making html"
+
+web:
+ @echo "Making web"
+ @mkdir -p ${DOC}
+ @cp -fp ${IMAGES}/*.eps .
+ @rm -f next.eps next.png prev.eps prev.png up.eps up.png
+ @cp -fp ${IMAGES}/*.eps ${DOC}/
+ @cp -fp ${IMAGES}/*.eps ${IMAGES}/*.png ${DOC}/
+ @rm -f ${DOC}/xp-*.png
+ @rm -f ${DOC}/next.eps ${DOC}/next.png ${DOC}/prev.eps ${DOC}/prev.png ${DOC}/up.eps ${DOC}/up.png
+ @rm -rf ${DOC}/*.html
+ latex2html -split 3 -local_icons -t "Bacula Concepts and Overview Guide" -long_titles 4 \
+ -toc_stars -contents_in_nav -init_file latex2html-init.pl -white -notransparent ${DOC} >tex.out 2>&1
+ ./translate_images.pl --to_meaningful_names ${DOC}/Bacula_Concep_Overvi_Guide.html
+ @echo "Done making web"
+show:
+ xdvi ${DOC}
+
+texcheck:
+ ./check_tex.pl ${DOC}.tex
+
+main_configs:
+ pic2graph -density 100 <main_configs.pic >main_configs.png
+
+mini-clean:
+ @rm -f 1 2 3 *.tex~
+ @rm -f *.gif *.jpg *.eps
+ @rm -f *.aux *.cp *.fn *.ky *.log *.pg
+ @rm -f *.backup *.ilg *.lof *.lot
+ @rm -f *.cdx *.cnd *.ddx *.ddn *.fdx *.fnd *.ind *.sdx *.snd
+ @rm -f *.dnd *.old *.out
+ @rm -f ${DOC}/*.gif ${DOC}/*.jpg ${DOC}/*.eps
+ @rm -f ${DOC}/*.aux ${DOC}/*.cp ${DOC}/*.fn ${DOC}/*.ky ${DOC}/*.log ${DOC}/*.pg
+ @rm -f ${DOC}/*.backup ${DOC}/*.ilg ${DOC}/*.lof ${DOC}/*.lot
+ @rm -f ${DOC}/*.cdx ${DOC}/*.cnd ${DOC}/*.ddx ${DOC}/*.ddn ${DOC}/*.fdx ${DOC}/*.fnd ${DOC}/*.ind ${DOC}/*.sdx ${DOC}/*.snd
+ @rm -f ${DOC}/*.dnd ${DOC}/*.old ${DOC}/*.out
+ @rm -f ${DOC}/WARNINGS
+
+
+clean:
+ @rm -f 1 2 3 *.tex~
+ @rm -f *.png *.gif *.jpg *.eps
+ @rm -f *.pdf *.aux *.cp *.fn *.ky *.log *.pg
+ @rm -f *.html *.backup *.ps *.dvi *.ilg *.lof *.lot
+ @rm -f *.cdx *.cnd *.ddx *.ddn *.fdx *.fnd *.ind *.sdx *.snd
+ @rm -f *.dnd imagename_translations
+ @rm -f *.old WARNINGS *.out *.toc *.idx
+ @rm -f ${DOC}i-*.tex
+ @rm -rf ${DOC}
+
+
+distclean: clean
+ @rm -f images.pl labels.pl internals.pl
+ @rm -f Makefile version.tex
--- /dev/null
+#
+#
+# Makefile for LaTeX
+#
+# To build everything do
+# make tex
+# make web
+# make html
+# make dvipdf
+#
+# or simply
+#
+# make
+#
+# for rapid development do:
+# make tex
+# make show
+#
+#
+# If you are having problems getting "make" to work, debugging it is
+# easier if can see the output from latex, which is normally redirected
+# to /dev/null. To see it, do the following:
+#
+# cd docs/manual
+# make tex
+# latex bacula.tex
+#
+# typically the latex command will stop indicating the error (e.g. a
+# missing \ in front of a _ or a missing { or ] ...
+#
+# The following characters must be preceded by a backslash
+# to be entered as printable characters:
+#
+# # $ % & ~ _ ^ \ { }
+#
+
+IMAGES=../../../images
+
+DOC=concepts
+
+first_rule: all
+
+all: tex web dvipdf mini-clean
+
+.SUFFIXES: .tex .html
+.PHONY:
+.DONTCARE:
+
+
+tex:
+ @./update_version
+ @echo "Making version `cat version.tex`"
+ @cp -fp ${IMAGES}/hires/*.eps .
+ @touch ${DOC}i-dir.tex ${DOC}i-fd.tex ${DOC}i-sd.tex \
+ ${DOC}i-console.tex ${DOC}i-general.tex
+ latex -interaction=batchmode ${DOC}.tex
+ makeindex ${DOC}.idx -o ${DOC}.ind 2>/dev/null
+ makeindex ${DOC}.ddx -o ${DOC}.dnd >/dev/null 2>/dev/null
+ makeindex ${DOC}.fdx -o ${DOC}.fnd >/dev/null 2>/dev/null
+ makeindex ${DOC}.sdx -o ${DOC}.snd >/dev/null 2>/dev/null
+ makeindex ${DOC}.cdx -o ${DOC}.cnd >/dev/null 2>/dev/null
+ latex -interaction=batchmode ${DOC}.tex
+
+pdf:
+ @echo "Making pdfm"
+ @cp -fp ${IMAGES}/hires/*.eps .
+ dvipdfm -p a4 ${DOC}.dvi
+
+dvipdf:
+ @echo "Making dvi to pdf"
+ @cp -fp ${IMAGES}/hires/*.eps .
+ dvipdf ${DOC}.dvi ${DOC}.pdf
+
+html:
+ @echo " "
+ @echo "Making html"
+ @cp -fp ${IMAGES}/*.eps .
+ @rm -f next.eps next.png prev.eps prev.png up.eps up.png
+ @(if [ -f imagename_translations ] ; then \
+ ./translate_images.pl --from_meaningful_names ${DOC}.html; \
+ fi)
+ latex2html -white -no_subdir -split 0 -toc_stars -white -notransparent \
+ -init_file latex2html-init.pl ${DOC} >tex.out 2>&1
+ ./translate_images.pl --to_meaningful_names ${DOC}.html
+ @echo "Done making html"
+
+web:
+ @echo "Making web"
+ @mkdir -p ${DOC}
+ @cp -fp ${IMAGES}/*.eps .
+ @rm -f next.eps next.png prev.eps prev.png up.eps up.png
+ @cp -fp ${IMAGES}/*.eps ${DOC}/
+ @cp -fp ${IMAGES}/*.eps ${IMAGES}/*.png ${DOC}/
+ @rm -f ${DOC}/xp-*.png
+ @rm -f ${DOC}/next.eps ${DOC}/next.png ${DOC}/prev.eps ${DOC}/prev.png ${DOC}/up.eps ${DOC}/up.png
+ @rm -rf ${DOC}/*.html
+ latex2html -split 3 -local_icons -t "Bacula Concepts and Overview Guide" -long_titles 4 \
+ -toc_stars -contents_in_nav -init_file latex2html-init.pl -white -notransparent ${DOC} >tex.out 2>&1
+ ./translate_images.pl --to_meaningful_names ${DOC}/Bacula_Concep_Overvi_Guide.html
+ @echo "Done making web"
+show:
+ xdvi ${DOC}
+
+texcheck:
+ ./check_tex.pl ${DOC}.tex
+
+main_configs:
+ pic2graph -density 100 <main_configs.pic >main_configs.png
+
+mini-clean:
+ @rm -f 1 2 3 *.tex~
+ @rm -f *.gif *.jpg *.eps
+ @rm -f *.aux *.cp *.fn *.ky *.log *.pg
+ @rm -f *.backup *.ilg *.lof *.lot
+ @rm -f *.cdx *.cnd *.ddx *.ddn *.fdx *.fnd *.ind *.sdx *.snd
+ @rm -f *.dnd *.old *.out
+ @rm -f ${DOC}/*.gif ${DOC}/*.jpg ${DOC}/*.eps
+ @rm -f ${DOC}/*.aux ${DOC}/*.cp ${DOC}/*.fn ${DOC}/*.ky ${DOC}/*.log ${DOC}/*.pg
+ @rm -f ${DOC}/*.backup ${DOC}/*.ilg ${DOC}/*.lof ${DOC}/*.lot
+ @rm -f ${DOC}/*.cdx ${DOC}/*.cnd ${DOC}/*.ddx ${DOC}/*.ddn ${DOC}/*.fdx ${DOC}/*.fnd ${DOC}/*.ind ${DOC}/*.sdx ${DOC}/*.snd
+ @rm -f ${DOC}/*.dnd ${DOC}/*.old ${DOC}/*.out
+ @rm -f ${DOC}/WARNINGS
+
+
+clean:
+ @rm -f 1 2 3 *.tex~
+ @rm -f *.png *.gif *.jpg *.eps
+ @rm -f *.pdf *.aux *.cp *.fn *.ky *.log *.pg
+ @rm -f *.html *.backup *.ps *.dvi *.ilg *.lof *.lot
+ @rm -f *.cdx *.cnd *.ddx *.ddn *.fdx *.fnd *.ind *.sdx *.snd
+ @rm -f *.dnd imagename_translations
+ @rm -f *.old WARNINGS *.out *.toc *.idx
+ @rm -f ${DOC}i-*.tex
+ @rm -rf ${DOC}
+
+
+distclean: clean
+ @rm -f images.pl labels.pl internals.pl
+ @rm -f Makefile version.tex
--- /dev/null
+TODO
+
+maybe spell out "config" to "configuration" as appropriate
+
+Use American versus British spelling
+
+not critical, but for later consider cleaning out some use of
+"there" and rewrite to not be so passive.
+
+make sure use of \elink shows URL in printed book
+
+get rid of many references of "Red Hat" -- too platform specific?
+
+remove references to names, like "Dan Langille shared ..."
+just put their names in credits for book
+
+don't refer to very old software by specific version such as
+"Red Hat 7" or FreeBSD 4.9 because is too old to put in book. It may be
+relevant, but may be confusing. Maybe just remove the version number
+if applicable.
+
+maybe fine, but discuss point-of-view: don't use personal "I" or
+possessive "my" unless that is consistent style for book.
+
+replace "32 bit" and "64 bit" with "32-bit" and "64-bit" respectively.
+It seems like more popular style standard
+
+be consistent with "Note" and "NOTE". maybe use tex header for this
+
+get rid of redundant or noisy exclamation marks
+
+style for "ctl-alt-del" and "ctl-d"? and be consisten with formatting
+
+be consistent for case for ext3, ext2, EXT3, or EXT2.
+
+fix spelling of "inspite" in source and in docs (maybe use "regardless
+in one place where I already changed to "in spite"
+
+be consistent with software names, like postgres, postgresql, PostreSQL
+and others
+
+instead of using whitehouse for examples, use example.org (as that is defined
+for that usage); also check other hostnames and maybe IPs and networks
+
+use section numbers and cross reference by section number or page number
+no underlining in book (this is not the web :)
+
+some big gaps between paragraphs or between section headers and paragraphs
+-- due to tex -- adjust as necessary to look nice
+
+don't include the GPL and LGPL in book. This will save 19 (A4) pages.
+For 6x9 book this will save 30 pages. (Keep GFDL though.)
+
+many index items are too long
+
+appendices not listed as appendix
+
+some how consolidate indexes into one? on 6x9, the indexes are over 30 pages
+
+don't refer to some website without including URL also
+(such as "this FreeBSD Diary article")
+
+get rid of (R) trademark symbols -- only use on first use; for example
+don't put on the RPM Packaging FAQ
+
+split up very long paragraphs, such as "As mentioned above, you will need ..."
+(on my page 783).
+
+use smaller font or split up long lines (especially from
+console output which is wider than printed page)
+
+don't assume all BSD is "FreeBSD"
+
+don't assume all "kernel" is Linux. If it is Linux, be clear.
+
+
--- /dev/null
+
+\chapter{ANSI and IBM Tape Labels}
+\label{AnsiLabelsChapter}
+\index[general]{ANSI and IBM Tape Labels}
+\index[general]{Labels!Tape}
+
+Bacula supports ANSI or IBM tape labels as long as you
+enable it. In fact, with the proper configuration, you can
+force Bacula to require ANSI or IBM labels.
+
+Bacula can create an ANSI or IBM label, but if Check Labels is
+enabled (see below), Bacula will look for an existing label, and
+if it is found, it will keep the label. Consequently, you
+can label the tapes with programs other than Bacula, and Bacula
+will recognize and support them.
+
+Even though Bacula will recognize and write ANSI and IBM labels,
+it always writes its own tape labels as well.
+
+When using ANSI or IBM tape labeling, you must restrict your Volume
+names to a maximum of six characters.
+
+If you have labeled your Volumes outside of Bacula, then the
+ANSI/IBM label will be recognized by Bacula only if you have created
+the HDR1 label with {\bf BACULA.DATA} in the Filename field (starting
+with character 5). If Bacula writes the labels, it will use
+this information to recognize the tape as a Bacula tape. This allows
+ANSI/IBM labeled tapes to be used at sites with multiple machines
+and multiple backup programs.
+
+
+\section{Director Pool Directive}
+
+\begin{description}
+\item [ Label Type = ANSI | IBM | Bacula]
+ This directive is implemented in the Director Pool resource and in the SD Device
+ resource. If it is specified in the SD Device resource, it will take
+ precedence over the value passed from the Director to the SD. The default
+ is Label Type = Bacula.
+\end{description}
+
+\section{Storage Daemon Device Directives}
+
+\begin{description}
+\item [ Label Type = ANSI | IBM | Bacula]
+ This directive is implemented in the Director Pool resource and in the SD Device
+ resource. If it is specified in the the SD Device resource, it will take
+ precedence over the value passed from the Director to the SD.
+
+\item [Check Labels = yes | no]
+ This directive is implemented in the the SD Device resource. If you intend
+ to read ANSI or IBM labels, this *must* be set. Even if the volume is
+ not ANSI labeled, you can set this to yes, and Bacula will check the
+ label type. Without this directive set to yes, Bacula will assume that
+ labels are of Bacula type and will not check for ANSI or IBM labels.
+ In other words, if there is a possibility of Bacula encountering an
+ ANSI/IBM label, you must set this to yes.
+\end{description}
--- /dev/null
+\chapter{La ressource Autochanger}
+\label{Autochangerres}
+\index[sd]{Autochanger Ressource }
+\index[sd]{Ressource!Autochanger }
+
+La ressource Autochanger supporte les librairies \`a un ou plusieurs
+lecteurs en regroupant une ou plusieurs ressources Device en une
+unit\'e nomm\'ee Autochanger dans Bacula (souvent d\'esign\'ee en tant que
+librairie de bandes par les constructeurs). Si vous poss\'edez une
+librairie, et si vous voulez qu'elle fonctionne correctement, vous
+{\bf devez} avoir une ressource Autochanger dans le fichier de
+configuration de votre Storage Daemon, et les directives Storage
+de votre Director {\bf doivent} se r\'ef\'erer au nom de la ressource
+Autochanger si elles sont suppos\'ees utiliser la librairie. Dans les
+versions ant\'erieures \`a 1.38.0, les directives Storage du Director
+se r\'ef\'eraient directement aux ressources Device qui \'etaient des
+librairies. D\'esormais, ce type de r\'ef\'erence directe ne fonctionne
+plus avec les librairies.
+
+\begin{description}
+\item [Name = \lt{}Autochanger-Name\gt{}]
+ \index[sd]{Name}
+ Sp\'ecifie le nom de la librairie. Ce nom est utilis\'e dans la
+ la d\'efinition de ressource Storage du Director afin de d\'esigner
+ la librairie. Cette directive est requise.
+
+\item [Device = \lt{}Device-name1, device-name2, ...\gt{}]
+ Sp\'ecifie le nom de la (ou des) ressource(s) Device associ\'ees \`a la
+ librairie. Si votre librairie contient plusieurs lecteurs, vous
+ devez sp\'ecifier plusieurs noms de ressources Device, chacun d\'esignant
+ une ressource Device distincte qui comporte un
+ Drive Index correspondant au num\'ero de lecteur. Vous pouvez sp\'ecifier
+ plusieurs noms en une seule ligne s\'epar\'es par des virgules ou/et utiliser
+ plusieurs fois la directive Device. Cette directive est requise.
+
+\item [Changer Device = {\it name-string}]
+ \index[sd]{Changer Device}
+ La cha\^ine {\bf name-string} sp\'ecifi\'ee indique le nom du fichier syst\`eme
+ d\'esignant la librairie. S'il est sp\'ecifi\'e dans cette ressource, ce nom
+ n'est pas requis dans la ressource Device. Le nom \'eventuellement sp\'ecifi\'e
+ dans la ressource Device prend le pas sur celui sp\'ecifi\'e dans la ressource
+ Autochanger.
+
+\item [Changer Command = {\it name-string}]
+ \index[sd]{Changer Command }
+ La cha\^ine {\bf name-string} sp\'ecifie un programme externe appel\'e pour
+ changer de volume automatiquement \`a la demande de Bacula. La plupart du
+ temps, vous renseignerez ce champ avec le script fourni {\bf mtx-changer}
+ comme suit. Si cette commande est sp\'ecifi\'ee ici, elle n'a pas besoin de
+ l'\^etre dans la ressource Device. Dans le cas o\`u elle le serait dans les deux
+ ressources, la sp\'ecification de la ressource Device prendrait le pas sur celle
+ de la ressource Autochanger.
+
+\end{description}
+
+Voici un exemple de d\'efinition de ressource Autochanger valide :
+
+\footnotesize
+\begin{verbatim}
+Autochanger {
+ Name = "DDS-4-changer"
+ Device = DDS-4-1, DDS-4-2, DDS-4-3
+ Changer Device = /dev/sg0
+ Changer Command = "/etc/bacula/mtx-changer %c %o %S %a %d"
+}
+Device {
+ Name = "DDS-4-1"
+ Drive Index = 0
+ Autochanger = yes
+ ...
+}
+Device {
+ Name = "DDS-4-2"
+ Drive Index = 1
+ Autochanger = yes
+ ...
+Device {
+ Name = "DDS-4-3"
+ Drive Index = 2
+ Autochanger = yes
+ Autoselect = no
+ ...
+}
+\end{verbatim}
+\normalsize
+
+Notez l'importance de la directive {\bf Autochanger = yes} dans chaque d\'efinition
+de p\'eriph\'erique appartenant \`a une librairie. Un p\'eriph\'erique ne devrait pas \^etre
+d\'efini comme appartenant \`a plusieurs librairies. Aussi, votre directive Device
+dans la ressource Storage du Director devrait comporter le nom de la ressource
+Autochanger plut\^ot que le nom de l'un des lecteurs.
+
+Si vous avez un lecteur qui appartient physiquement \`a une librairie mais que
+vous ne souhaitez pas que Bacula puisse l'utiliser automatiquement (par exemple,
+si vous voulez le r\'eserver pour les restaurations) vous pouvez utiliser la
+directive :
+
+\footnotesize
+\begin{verbatim}
+Autoselect = no
+\end{verbatim}
+\normalsize
+
+\`a la ressource Device de ce lecteur. Dans ce cas, Bacula ne le s\'electionnera pas
+automatiquement en acc\'edant \`a la librairie. Vous pouvez encore utiliser le lecteur en
+le d\'esignant par son nom de ressource device plut\^ot que par celui de la ressource
+Autochanger. Un exemple d'une telle d\'efinition est montr\'e ci-dessus pour le
+lecteur DDS-4-3, qui ne sera pas s\'electionn\'e si le nom DDS-4-changer est utilis\'e
+dans une ressource Storage, mais le sera si DDS-4-3 est utilis\'e.
--- /dev/null
+%%
+%%
+
+\chapter{Support des librairies}
+\label{AutochangersChapter}
+\index[general]{Support!Librairies}
+\index[general]{Autochanger Support }
+\addcontentsline{toc}{section}{Support des librairies}
+
+Bacula supporte les librairies pour les op\'erations de lecture et \'ecriture.
+Plusieurs conditions sont requises pour que Bacula puisse utiliser une librairie.
+Celles-ci sont expliqu\'ees en d\'etail ci-dessous.
+Mais voyons d'abord la liste de ces conditions :
+
+\begin{itemize}
+\item Un script charg\'e de piloter la librairie en accord avec les commandes
+ envoy\'ees par Bacula est requis. Nous fournissons un tel script pr\'evu pour fonctionner
+ avec le programme {\bf mtx} disponible dans les paquets {\bf depkgs}. ce script ne
+ fonctionne qu'avec les librairies \`a un seul lecteur.
+\item Chaque volume \`a utiliser doit \^etre d\'efini dans le catalogue et avoir
+ un num\'ero de slot (NDT : emplacement dans la librairie) assign\'e, de sorte
+ que Bacula puisse savoir o\`u se trouve le volume dans la librairie. Cet
+ enregistrement se fait la plupart du temps gr\^ace \`a la commande {\bf label}.
+ Voyez ci-dessous pour plus de d\'etails. Vous devez \'etiqueter manuellement
+ vos cartouches avant de pouvoir les utiliser.
+\item Vous devez avoir modifi\'e le fichier de configuration de votre Storage
+ Daemon afin que la ressource Device identifie votre p\'eriph\'erique en tant
+ que librairie. Quelques autres param\`etres doivent \^etre d\'efinis.
+\item Vous devriez aussi modifier la d\'efinition de ressource Storage dans le
+fichier de configuration du Director en sorte que le slot vous soit automatiquement
+demand\'e lorque vous \'etiquetez un volume.
+\item Si vous n'ex\'ecutez pas le Storage Daemon en tant que root, vous devez
+ vous assurer qu'il d\'etient les droits requis pour acc\'eder au lecteur et au
+ bras robotis\'e de la librairie.
+\item Vous devez placer la directive {\bf Autochanger = yes} dans la
+ ressource Storage de votre fichier bacula-dir.conf, de sorte que vous soyez
+ interrog\'e au sujet du slot \`a chaque \'etiquetage de cartouche.
+\end{itemize}
+
+Dans les versions ult\'erieures \`a 1.37, la nouvelle directive
+\ilink{Autochanger resource}{AutochangerRes} permet de grouper les ressources
+Device pour cr\'eer des librairies avec plusieurs lecteurs. Si vous avez une
+librairie, vous devez utiliser cette ressource.
+
+Bacula utilise son propre script {\bf mtx-changer} pour interagir avec un
+programme qui effectue r\'eellement les changement de cartouches. Ainsi,
+{\bf mtx-changer} peut \^etre adapt\'e pour fonctionner avec n'importe quel
+programme de prise en chgarge de librairie. La version actuelle de
+{\bf mtx-changer} fonctionne avec le programme {\bf mtx} . Cependant,
+des utilisateurs de FreeBSD ont r\'ealis\'e un script, disponible dans
+le r\'epertoire {\bf examples/autochangers}, qui permet \`a Bacula de fonctionner
+avec le programme {\bf chio}.
+
+Bacula supporte aussi les librairies \'equip\'ees de lecteurs de codes barres.
+Ce support inclut deux commandes de la console Bacula : {\bf label barcodes}
+et {\bf update slots}. Pour plus de d\'etails au sujet de ces commandes,
+voyez la section "Support des lecteurs de codes barres" plus loin.
+
+Le support des librairies dans Bacula n'inclue pas, pour le moment, la gestion
+du nettoyage des lecteurs, ni celle des bacs de cartouches ou des silos.
+
+Le support des librairies \`a un ou plusieurs lecteurs requiert la ressource
+\ilink{Autochanger resource}{AutochangerRes}.
+
+En principe, si {\bf mtx} fonctionne correctement avec votre librairie, ce
+n'est qu'une question d'adaptation du script {\bf mtx-changer} pour que
+Bacula s'interface correctement avec la librairie. Vous pouvez trouver une
+liste des librairies support\'ees par {\bf mtx} en suivant le lien suivant :
+\elink{http://mtx.opensource-sw.net/compatibility.php}
+{http://mtx.opensource-sw.net/compatibility.php}.
+Le site officiel du projet {\bf mtx} se trouve ici :
+\elink{http://mtx.opensource-sw.net/}{http://mtx.opensource-sw.net/}.
+
+Si vous avez des difficult\'es, veuillez utiliser la commande {\bf auto} du
+programme {\bf btape} pour tester le fonctionnement de votre librairie
+avec Bacula. Lorsque Bacula fonctionne, souvenez vous que pour beaucoup de
+distributions (par exemple FreeBSD, Debian,...), le Storage Daemon est
+ex\'ecut\'e en tant que {\bf bacula.tape} plut\^ot que {\bf root.root}, aussi
+vous devrez vous assurer que le Storage Daemon dispose de droits suffisants pour
+acc\'eder \`a la librairie.
+
+\label{SCSI devices}
+\section*{D\'eterminer vos p\'eriph\'eriques SCSI}
+\index[general]{D\'eterminer!p\'eriph\'eriques SCSI}
+\index[general]{D\'eterminer vos p\'eriph\'eriques SCSI}
+\index[general]{P\'eriph\'eriques}
+\index[general]{p\'eriph\'eriques!SCSI}
+
+Sous Linux, vous pouvez lire le fichier /proc/scsi/scsi :
+
+\footnotesize
+\begin{verbatim}
+cat /proc/scsi/scsi
+\end{verbatim}
+\normalsize
+
+pour conna\^itre vos p\'eriph\'eriques SCSI. Vous pouvez aussi examiner les fichiers
+/proc/scsi/sg/device\_hdr et /proc/scsi/sg/devices :
+
+footnotesize
+\begin{verbatim}
+cat /proc/scsi/sg/device_hdr /proc/scsi/sg/devices
+\end{verbatim}
+\normalsize
+
+pour d\'eterminer comment sp\'ecifier leur nom de p\'eriph\'erique ({\bf /dev/sg0}
+pour le premier, {\bf /dev/sg1} pour le second, ...) au niveau de
+la directive {\bf Changer Device}
+
+Pour des informations plus d\'etaill\'ees sur le sujet, veuillez consulter la
+section \ilink{Linux SCSI Tricks}{SCSITricks} du chapitre sur les tests
+de lecteurs de ce manuel.
+
+Sous FreeBSD, vous disposez de la commande :
+
+\footnotesize
+\begin{verbatim}
+camcontrol devlist
+\end{verbatim}
+\normalsize
+
+pour afficher la liste des p\'eriph\'eriques SCSI ainsi que le {\bf /dev/passn}
+que vous utiliserez pour renseigner la directive {\bf Changer Device}
+
+Assurez-vous que votre Storage Daemon dispose bien des privil\`eges requis
+pour acc\'eder \`a ce p\'eriph\'erique.
+
+L'astuce suivante, destin\'ee aux utilisateurs de FreeBSD, provient de
+Danny Butroyd. Au red\'emarrage, Bacula n'aura PLUS les permissions
+requises pour contr\^oler le p\'eriph\'erique /dev/pass0. Pour vous
+affanchir de cette difficult\'e, \'editez le fichier /etc/devfs.conf et
+ajoutez lui ceci :
+
+\footnotesize
+\begin{verbatim}
+own pass0 root:bacula
+perm pass0 0666
+own nsa0.0 root:bacula
+perm nsa0.0 0666
+\end{verbatim}
+\normalsize
+
+Nous avons ainsi donn\'e au groupe Bacula la permission d'\'ecrire
+sur le p\'eriph\'erique nsa0.0. Pour activer ces modifications, ex\'ecutez :
+/etc/rc.d/devfs restart
+
+Vous n'aurez plus \`a modifier les permissions sur ces p\'eriph\'eriques
+pour que Bacula continue d'utiliser la librairie apr\`es un red\'emarrage.
+
+\label{scripts}
+
+\section{Exemples de scripts}
+\index[general]{Scripts!Exemples }
+\index[general]{Exemples de scripts }
+
+Veuillez lire les sections ci-dessous pour bien comprendre comment
+les librairies fonctionnent avec Bacula. Bien que nous fournissions
+un script {\bf mtx-changer} par d\'efaut, il se peut que votre librairie
+n\'ecessite quelques am\'enagements de ce script. Si vous voulez voir des
+exemples de fichiers de configuration et de scripts, jetez un oeil
+au r\'epertoire \lt{}bacula-src\gt{}/examples/devices o\`u vous
+trouverez un exemple de ressource Device Bacula : {\bf HP-autoloader.conf}
+ainsi que plusieurs scripts {\bf mtx-changer} modifi\'es pour fonctionner
+avec diverses librairies.
+
+\label{Slots}
+
+\section*{Slots}
+\index[general]{Slots }
+
+Pour utiliser convenablement une librairie, Bacula doit savoir quel volume
+se trouve dans quel {\bf slot} de la librairie. Les slots sont les
+emplacements o\`u sont rang\'ees les cartouches lorsqu'elles ne sont pas dans un
+lecteur. Bacula num\'erote ces slots de un jusqu'au nombre de cartouches
+contenues dans la librairie.
+
+Bacula n'utilisera pas automatiquement une cartouche pr\'esente dans la librairie
+si elle ne porte pas d'\'etiquette (label) Bacula et si son num\'ero de slot n'est pas
+r\'ef\'erenc\'e dans le catalogue. Vous devez, \`a l'aide de la console, assigner un
+slot \`a chaque cartouche pr\'esente dans la librairie. Cette information est
+conserv\'ee dans le catalogue avec les autres donn\'ees relatives au volume.
+Si le slot n'est pas pr\'ecis\'e, ou s'il est \'egal \`a z\'ero, alors Bacula ne tentera
+pas d'utiliser la librairie, m\^eme si tous les enregistrements de configuration
+sont pr\'esents. De m\^eme, la commande {\bf mount} de la console Bacula ne
+provoque pas non plus l'utilisation de la librairie, mais se contente d'ordonner
+\`a Bacula de lire toute cartouche \'eventuellement pr\'esente dans le lecteur.
+
+Vous pouvez contr\^oler le num\'ero de slot et le drapeau InChanger avec la commande :
+
+\begin{verbatim}
+list Volumes
+\end{verbatim}
+
+dans la console.
+
+\label{mult}
+\section*{Lecteurs multiples}
+\index[general]{Lecteurs!Multiples }
+\index[general]{Lecteurs ultiples}
+
+Certaines librairies comportent plusieurs p\'eriph\'eriques de lecture/\'ectriture
+(lecteurs). La nouvelle \ilink{ressource Autochanger}{AutochangerRes}
+apparue avec la version 1.37 vous permet de grouper des ressources Devices
+(repr\'esentant chacune un lecteur). Le Director est toujours en mesure
+d'adresser directement un lecteur, mais ce faisant, il outrepasse
+le fonctionnement propre aux groupements de lecteurs. Il est pr\'ef\'erable
+que la Ressource Storage du Director d\'efinisse une ressource
+Autochanger, permettant ainsi au Storage Daemon de s'assurer qu'un seul
+lecteur \`a la fois utilise le script mtx-changer, et que deux lecteurs ne tentent
+pas de lire le m\^eme volume.
+
+Les librairies \`a lecteurs multiples n\'ecessitent d'utiliser la directive
+{\bf Drive Index} dans la ressource Device du Storage Daemon. Les
+lecteurs sont num\'erot\'es \`a partir de z\'ero, ce qui constitue la valeur par
+d\'efaut. Pour utiliser un deuxi\`eme lecteur dans une librairie, vous devez
+d\'efinir une seconde ressource Device et lui attribuer le Drive Index 1.
+En g\'en\'eral, le second p\'eriph\'erique aura le m\^eme {\bf Changer Device}
+(canal de contr\^ole) que le premier, mais une {\bf Archive Device} diff\'erente.
+
+Par d\'efaut, les jobs Bacula pr\'ef\`erent \'ecrire sur un volume d\'ej\`a mont\'e.
+Si vous avez une librairie avec plusieurs lecteurs, et si vous souhaitez que
+Bacula \'ecrive sur plusieurs volumes du m\^eme pool en m\^eme temps, vous devez
+d\'esactiver la directive \ilink{Prefer Mounted Volumes} {PreferMountedVolumes}
+dans la ressource Job du Director. Ainsi le Storage Daemon pourra maximiser
+l'usage des lecteurs.
+
+\label{ConfigRecords}
+\subsection*{Directives de la ressource Device}
+\index[general]{Directives!ressource Device}
+\index[general]{Directives de la ressource Device}
+
+La configuration des librairies s'effectue dans Bacula au niveau de le ressource
+Device du Storage Daemon. Quatre directives permettent de d\'efinir l'usage de
+la librairie par Bacula : {\bf Autochanger}, {\bf Changer Device},
+{\bf Changer Command} et {\bf Maximum Changer Wait}
+
+Ces quatre directives sont d\'ecrites en d\'etail ci-dessous. Notez cependant
+que les directives {\bf Changer Device} et {\bf Changer Command} ne sont pas
+requises dans la ressource Device si elles figurent dans la ressource
+{\bf Autochanger}.
+
+\begin{description}
+
+\item [Autochanger = {\it Yes|No} ]
+ \index[sd]{Autochanger}
+ La directive {\bf Autochanger} stipule que le p\'eriph\'erique ainsi d\'efini est, ou
+ n'est pas, une librairie. La valeur par d\'efaut est {\bf no}.
+
+\item [Changer Device = \lt{}device-name\gt{}]
+ \index[sd]{Changer Device}
+ En plus du nom d'Archive Device, vous devez sp\'ecifier un nom de
+ librairie {\bf Changer Device}, ceci parce que la plupart des librairies
+ sont control\'ees via un pseudo-fichier diff\'erent de celui utilis\'e pour
+ lire et \'ecrire sur les cartouches. Par exemple, sur les syst\`emes Linux,
+ on utilise g\'en\'eralement l'interface SCSI g\'en\'erique pour contr\^oler le bras
+ de la librairie, soit {\bf Changer Device = /dev/sg0} et l'interface SCSI
+ standard pour lire et \'ecrire sur les bandes, soit {\bf Archive Device = /dev/nst0}.
+ Notez que certaines librairies \'evolu\'ees localiseront le bras sur
+ {\bf /dev/sg1}. De telles librairies ont souvent plusieurs lecteurs et un
+ nombre important de cartouches.
+
+ Sur FreeBSD, on sp\'ecifiera typiquement {\bf Changer Device = /dev/pass0} ou
+ {\bf Changer Device = /dev/passn}.
+
+ Sur Solaris, ce sera {\bf Changer Device = /dev/rdsk}.
+
+ Assurez vous que votre Storage Daemon poss\`ede les permissions d'acc\'eder \`a
+ ce p\'eriph\'erique.
+
+\item [Changer Command = \lt{}command\gt{}]
+ \index[sd]{Changer Command }
+ Cette directive est utilis\'ee pour sp\'ecifier le programme externe \`a appeler
+ et les arguments \`a lui fournir. La commande est suppos\'ee \^etre un programme
+ ou un script shell standard qui peut \^etre ex\'ecut\'e par le syst\`eme. cette
+ commande est invoqu\'ee chaque fois que Bacula manipule le bras de la librairie.
+ Les substitutions suivantes sont effectu\'ees dans la ligne {\bf command}
+ avant qu'elle ne soit envoy\'ee au syst\`eme d'exploitation pour ex\'ecution.
+
+\footnotesize
+\begin{verbatim}
+ %% = %
+ %a = archive device name
+ %c = changer device name
+ %d = changer drive index base 0
+ %f = Client's name
+ %j = Job name
+ %o = command (loaded, load, or unload)
+ %s = Slot base 0
+ %S = Slot base 1
+ %v = Volume name
+\end{verbatim}
+\normalsize
+
+Voici un exemple d'utilisation de {\bf mtx} avec le script {\bf mtx-changer} :
+
+\footnotesize
+\begin{verbatim}
+Changer Command = "/etc/bacula/mtx-changer %c %o %S %a %d"
+\end{verbatim}
+\normalsize
+
+O\`u vous devrez adapter le chemin {\bf /etc/bacula} pour qu'il co\''incide \`a
+la r\'ealit\'e de votre installation. Les d\'etails des trois commandes (loaded,
+load, unload) utilis\'ees par Bacula ainsi que la sortie qui en est attendue
+sont donn\'es dans la section {\bf Interface entre Bacula et les librairies}
+ci-dessous.
+
+\item [Maximum Changer Wait = \lt{}time\gt{}]
+ \index[sd]{Maximum Changer Wait}
+ Cette directive sert \`a d\'efinir le d\'elai maximal durant lequel Bacula
+ attendra la r\'eponse d'une librairie \`a une commande (par exemple, load).
+ La valeur par d\'efaut est 120 secondes. Si votre librairie est lente, vous
+ pouvez avoir int\'er\^et \`a allonger ce d\'elai.
+
+ Au del\`a de ce d\'elai, le programme de chargement est tu\'e et Bacula
+ sollicite l'intervention d'un op\'erateur.
+
+\item [Drive Index = \lt{}number\gt{}]
+ \index[sd]{Drive Index}
+ Cette directive vous permet d'indiquer \`a Bacula d'utiliser le second
+ lecteur et les \'eventuels suivants dans une librairie qui en contient
+ plusieurs. Etant donn\'e que les lecteurs sont num\'erot\'es \`a partir de
+ z\'ero, le second est d\'efini par :
+
+\footnotesize
+\begin{verbatim}
+Device Index = 1
+\end{verbatim}
+\normalsize
+
+Pour utiliser le second lecteur, vous devez avoir une seconde d\'efinition
+de ressource Device dans le fichier bacula-sd.conf. Voyez la section
+concernant les lecteurs multiples plus haut dans ce chapitre pour plus
+de plus amples informations.
+\end{description}
+
+De plus, pour un fonctionnement correct de la librairie, vous devez d\'efinir
+une ressource Autochanger.
+\input{autochangerres}
+
+\label{example}
+\section{Un exemple de fichier de configuration}
+\index[general]{exemple fichier configuration}
+\index[general]{fichier!exemple configuration}
+
+Les deux ressource suivantes impl\'ementent une librairie :
+
+\footnotesize
+\begin{verbatim}
+Autochanger {
+ Name = "Autochanger"
+ Device = DDS-4
+ Changer Device = /dev/sg0
+ Changer Command = "/etc/bacula/mtx-changer %c %o %S %a %d"
+}
+
+Device {
+ Name = DDS-4
+ Media Type = DDS-4
+ Archive Device = /dev/nst0 # Normal archive device
+ Autochanger = yes
+ LabelMedia = no;
+ AutomaticMount = yes;
+ AlwaysOpen = yes;
+}
+\end{verbatim}
+\normalsize
+
+o\`u vous adapterez les directives {\bf Archive Device}, {\bf Changer Device} et
+{\bf Changer Command} pour qu'elles conviennent \`a votre syst\`eme.
+
+\section{Un exemple de fichier de configuration multi-lecteurs}
+\index[general]{Multi-lecteurs exemple fichier de configuration}
+
+Les ressources suivantes impl\'ementent une librairie multi-lecteurs :
+
+\footnotesize
+\begin{verbatim}
+Autochanger {
+ Name = "Autochanger"
+ Device = Drive-1, Drive-2
+ Changer Device = /dev/sg0
+ Changer Command = "/etc/bacula/mtx-changer %c %o %S %a %d"
+}
+
+Device {
+ Name = Drive-1
+ Drive Index = 0
+ Media Type = DDS-4
+ Archive Device = /dev/nst0 # Normal archive device
+ Autochanger = yes
+ LabelMedia = no;
+ AutomaticMount = yes;
+ AlwaysOpen = yes;
+}
+
+Device {
+ Name = Drive-2
+ Drive Index = 1
+ Media Type = DDS-4
+ Archive Device = /dev/nst1 # Normal archive device
+ Autochanger = yes
+ LabelMedia = no;
+ AutomaticMount = yes;
+ AlwaysOpen = yes;
+}
+
+\end{verbatim}
+\normalsize
+
+o\`u vous adapterez les directives {\bf Archive Device}, {\bf Changer Device} et
+{\bf Changer Command} pour qu'elles conviennent \`a votre syst\`eme.
+
+\label{SpecifyingSlots}
+\section{Sp\'ecifier des slots lors de l'\'etiquetage}
+\index[general]{Sp\'ecifier des slots lors de l'\'etiquetage}
+\index[general]{Etiquetage!Sp\'ecifier des slots lors de}
+
+Si vous utilisez la directive {\bf Autochanger = yes} \`a la ressource Storage
+du fichier de configuration de votre Director, la console Bacula vous
+demandera automatiquement le num\'ero de slot lors de l'utilisation des
+commandes {\bf add} ou {\bf label} pour ce p\'eriph\'erique de stockage. Si
+votre script {\bf mtx-changer} est correctement install\'e, Bacula
+chargera la bonne cartouche \`a l'ex\'ecution de la commande {\bf label}.
+
+Vous devez aussi sp\'ecifier {\bf Autochanger = yes} dans la ressource
+Device du Storage Daemon ainsi que nous l'avons d\'ecrit plus haut pour
+que la librairie soit utilis\'ee. Veuillez consulter la section
+\ilink{Ressource Storage}{Autochanger1} dans le chapitre sur la configuration
+du Director pour plus de d\'etails sur ce sujet.
+
+Ainsi, toutes les phases de l'utilisation des cartouches peuvent \^etre
+int\'egralement automatis\'ees. Il est aussi possible de param\'etrer ou
+modifier la valeur du slot en utilisant le sous-menu {\bf Volume Parameters}
+de la commande {\bf update} de la console.
+
+M\^eme si tous les param\`etres ci-dessus sont correctement sp\'ecifi\'es, Bacula ne
+tentera d'acc\'eder \`a la librairie que s'il existe un {\bf slot} non-nul parmi
+les volumes enregistr\'es dans le catalogue.
+
+Si votre librairie est \'equip\'ee d'un lecteur de codes barres, vous pouvez
+\'etiqueter vos volumes l'un apr\`es l'autre en utilisant la commande
+{\bf label barcodes}. Bacula montera et \'etiquettera chaque cartouche porteuse
+d'un code barres contenue dans la librairie avec le nom sp\'ecifi\'e par le
+code barres. L'enregistrement apropri\'e sera aussi cr\'e\'e dans le catalogue.
+Toute cartouche dont le code barres commence par les caract\`eres sp\'ecifi\'es par
+la directive {\bf Cleaning Prefix} est consid\'er\'ee comme une cartouche de
+nettoyage, et ne sera pas \'etiquet\'ee. Par exemple, avec :
+
+\footnotesize
+\begin{verbatim}
+Pool {
+ Name ...
+ Cleaning Prefix = "CLN"
+}
+\end{verbatim}
+\normalsize
+
+toute cartouche de code barres CLNxxxx sera trait\'ee en tant que cartouche de
+nettoyage, et ne sera pas mont\'ee.
+
+\section{Changer des cartouches}
+\index[general]{Changer des cartouches}
+Si vous voulez ins\'erer ou retirer des cartouches de votre librairie, ou encore
+ex\'ecuter manuellement le programme {\bf mtx}, vous devez "informer" Bacula de ces op\'erations :
+
+\footnotesize
+\begin{verbatim}
+unmount
+(changez vos cartouches et/ou ex\'ecutez mtx)
+mount
+\end{verbatim}
+\normalsize
+
+Si vous omettez de faire "unmount" avant de telles changements, Bacula ne saura plus
+ce qui est dans la librairie, et ce qui n'y est pas, et peut m\^eme cesser de fonctionner
+parce qu'il s'attend \`a avoir le contr\^ole exclusif de la librairie tandis quie le lecteur
+est mont\'e.
+
+Notez que les volumes doivent \^etre pr\'e-\'etiquet\'es pour pouvoir \^etre utilis\'es
+automatiquement dans la librairie lors d'une sauvegarde. Si vous ne disposez
+pas d'un lecteur de code barres, ceci se fait manuellement, ou \`a l'aide d'un
+script.
+
+\label{Magazines}
+\section{Travailler avec plusieurs magasins}
+\index[general]{Travailler avec plusieurs magasins}
+\index[general]{magasins!Travailler avec plusieurs}
+
+Si vous avez plusieurs magasins ou si vous ins\'erez ou retirez des
+cartouches d'un magasin, vous devriez en informer Bacula. Ainsi, Bacula
+sera en mesure d'utiliser pr\'ef\'erentiellement des cartouches qu'il sait \^etre
+dans la librairie, pr\'evenant ainsi des interventions humaines inutiles.
+
+Si votre librairie est \'equip\'ee d'un lecteur de codes barres, il est ais\'e
+de tenir Bacula inform\'e : chaque fois que vous changez un magasin, ajoutez
+ou pr\'elevez une cartouche, faites simplement :
+
+\footnotesize
+\begin{verbatim}
+unmount
+(remove magazine)
+(insert new magazine)
+update slots
+mount
+\end{verbatim}
+\normalsize
+
+dans la console. Avec cette commande, Bacula se renseigne aupr\`es de la librairie
+pour conna\^itre les volumes qu'elle contient. Ceci ne n\'ecessite pas d'acc\'eder
+aux volumes car la librairie se charge de faire son inventaire lors de sa
+mise sous tension. Bacula s'assure alors que tout volume pr\'esent dans la
+librairie est marqu\'e pr\'esent dans le catalogue et que tout volume absent de la
+librairie est marqu\'e absent dans le catalogue. En outre, les num\'eros de slots
+des volumes sont corrig\'es dans le catalogue s'ils sont inexacts.
+
+Si vous ne disposez pas d'un lecteur de codes barres, vous avez plusieurs alternatives :
+
+\begin{enumerate}
+\item Vous pouvez attribuer manuellement les num\'eros de slots et les drapeaux
+ InChanger \`a l'aide de la commande {\bf update volume} dans la console. Cette
+ m\'ethode est assez p\'enible.
+
+\item Vous pouvez lancer la commande
+
+\footnotesize
+\begin{verbatim}
+update slots scan
+\end{verbatim}
+\normalsize
+
+ qui ordonne \`a Bacula de lire l'\'etiquette (label) de chacune des cartouches
+ dans la librairie par montage successif, et de mettre \`a jour les informations
+ (Slot, drapeau InChanger) dans le catalogue. Cette m\'ethode est efficace, mais
+ prend du temps pour charger chaque cartouche et en lire l'\'etiquette.
+
+\item Vous pouvez modifier le script mtx-changer en sorte qu'il simule une
+ librairie \'equip\'ee d'un lecteur de codes barres. Voyez ce qui suit pour plus de
+ d\'etails
+\end{enumerate}
+
+\label{simulating}
+\section{Simuler un lecteur de codes barres dans votre librairie}
+\index[general]{Librairie!Simuler un lecteur de codes barres dans votre}
+\index[general]{Simuler un lecteur de codes barres dans votre}
+
+Vous pouvez simuler un lecteur de codes barres dans votre librairie en faisant
+en sorte que le script {\bf mtx-changer} retourne les informations que
+retournerait une librairie avec lecteur de codes barres. Pour cela, commentez
+la ligne ci-dessous dans le "case" aux alentours de la ligne 99 :
+
+\footnotesize
+\begin{verbatim}
+ ${MTX} -f $ctl status | grep " *Storage Element [0-9]*:.*Full" | awk "{print \$3 \$4}" | sed "s/Full *\(:VolumeTag=\)*//"
+\end{verbatim}
+\normalsize
+
+en ajoutant un \# au d\'ebut de cette ligne (vous pouvez aussi supprimer la ligne).
+A sa place, ajoutez une nouvelle ligne dont le r\^ole est d'imprimer le contenu
+d'un fichier. Par exemple :
+
+\footnotesize
+\begin{verbatim}
+cat /etc/bacula/changer.volumes
+\end{verbatim}
+\normalsize
+
+Le nom du fichier est libre, mais assurez vous d'utiliser un chemin absolu.
+Le contenu du fichier doit avoir le format :
+
+\footnotesize
+\begin{verbatim}
+1:Volume1
+2:Volume2
+3:Volume3
+...
+\end{verbatim}
+\normalsize
+
+O\`u 1, 2, 3 sont les num\'eros de slots et Volume1, Volume2, Volume3 sont les
+noms de volumes dans ces slots. Vous pouvez utiliser plusieurs fichiers
+repr\'esentant les contenus de plusieurs magasins, ainsi, lorsque vous
+changez de magasin, contentez vous de copier le contenu du fichier associ\'e
+dans le fichier {\bf /etc/bacula/changer.volumes}. Il n'est pas utile de
+stopper et red\'emarrer Bacula lors d'un changement de magasins, mettez simplement
+les bonnes valeurs dans le fichier avant de lancer la commande {\bf update slots}.
+Votre librairie appara\^itra \`a Bacula comme \'equip\'ee d'un lecteur de codes barres.
+
+\label{updateslots}
+
+\section{La forme compl\`ete de la commande Update Slots}
+\index[general]{La forme compl\`ete de la commande Update Slots}
+\index[general]{Command!La forme compl\`ete de la commande Update Slots}
+
+Si vous ne changez qu'une cartouche, vous ne voulez peut-\^etre pas passer au crible
+tous vos volumes, c'est pourquoi la commande {\bf update slots} (de m\^eme que la
+commande {\bf update slots scan}) poss\`ede la forme additionnelle :
+
+\footnotesize
+\begin{verbatim}
+update slots=n1,n2,n3-n4, ...
+\end{verbatim}
+\normalsize
+
+o\`u le mot-clef {\bf scan} peut \'eventuellement \^etre ajout\'e. n1, n2, n3-n4
+repr\'esentent respectivement les num\'eros et la plage de slots que vous souhaitez
+mettre \`a jour.
+
+Cette forme est particuli\`erement utile si vous voulez utiliser "scan" (couteux en temps)
+en restrignant l'op\'eration \`a quelques slots.
+
+Par exemple, si vous lancez la commande :
+
+\footnotesize
+\begin{verbatim}
+update slots=1,6 scan
+\end{verbatim}
+\normalsize
+
+Bacula va charger le volume du slot 6, lire son \'etiquette logicielle (label) et
+mettre \`a jour le catalogue, avant de faire de m\^eme avec la cartouche du slot 6.
+Avec la commande :
+
+\footnotesize
+\begin{verbatim}
+update slots=1-3,6
+\end{verbatim}
+\normalsize
+
+il va lire les codes barres des volumes dans les slots 1,2,3 et 6, et faire les
+mises \`a jour approri\'ees dans le catalogue. Si vous n'avez pas de lecteur de
+codes barres, ni n'en simulez comme d\'ecrit plus haut, la commande ci-dessus
+ne trouvera aucun nom de volume et ne fera donc rien.
+
+\label{FreeBSD}
+
+\section{Sp\'ecificit\'es FreeBSD}
+\index[general]{Sp\'ecificit\'es!FreeBSD }
+\index[general]{Sp\'ecificit\'es FreeBSD}
+
+Si vous rencontrez des probl\`emes sur FreeBSD lorsque Bacula tente de s\'electionner
+une cartouche, et si le message est {\bf Device not configured}, c'est
+parce que FreeBSD a fait dispara\^itre le fichier de p\'eriph\'erique {\bf /dev/nsa1}
+lorsqu'il n'y avait plus de cartouche mont\'ee dans le lecteur. Par cons\'equent,
+Bacula ne peut ouvrir le p\'eriph\'erique. Une solution consiste \`a charger une
+cartouche avant le lancement de Bacula. Ce probl\`eme est corrig\'e dans les
+versions de Bacula ult\'erieures \`a 1.32f-5.
+
+Veuillez consulter le chapitre
+\ilink{Tester votre lecteur}{FreeBSDTapes} de ce manuel pour d'{\bf importantes}
+informations sur votre lecteur avant de passer au test de la librairie.
+\label{AutochangerTesting}
+
+\section{Tester la librairie et adapter le script mtx-changer}
+\index[general]{Tester la librairie et adapter le script mtx-changer}
+\index[general]{Script!Tester la librairie et adapter le script mtx-changer}
+
+Avant d'essayer d'utiliser une librairie avec Bacula, il est pr\'ef\'erable de v\'erifier
+"\`a la main" que le bras robotis\'e fonctionne. Pour ce faire, utilisez les commandes
+suivantes (\`a supposer que le script {\bf mtx-changer} est install\'e dans
+{\bf /etc/bacula/mtx-changer}) :
+
+\begin{description}
+
+\item [Assurez vous que Bacula est stopp\'e]
+
+\item [/etc/bacula/mtx-changer \ /dev/sg0 \ list \ 0 \ /dev/nst0 \ 0]
+\index[sd]{mtx-changer list}
+
+Cette commande devrait afficher :
+
+\footnotesize
+\begin{verbatim}
+ 1:
+ 2:
+ 3:
+ ...
+
+\end{verbatim}
+\normalsize
+
+soit un num\'ero suivi de deux points pour chacun des slots occup\'e dans la librairie.
+Si votre librairie a un lecteur de codes barres, celui-ci sera affich\'e apr\`es les
+deux points. Si un message d'erreur s'affiche, vous devez r\'esoudre le probl\`eme
+(par exemple, essayez un autre nom de p\'eriph\'erique si {\bf /dev/sg0} n'est pas
+le bon. PAr exemple, sur FreeBSD c'est g\'en\'eralement {\bf /dev/pass2}).
+
+\item [/etc/bacula/mtx-changer \ /dev/sg0 \ slots \ 0 \ /dev/nst0 \ 0]
+\index[sd]{mtx-changer slots}
+
+Cette commande devrait retourner le nombre de slots de votre librairie.
+
+\item [/etc/bacula/mtx-changer \ /dev/sg0 \ unload \ ]
+\index[sd]{mtx-changer unload}
+
+Si une cartouche est charg\'ee, cette commande devrait la d\'echarger.
+
+\item [/etc/bacula/mtx-changer \ /dev/sg0 \ load \ 3 \ /dev/nst0 \ 0 ]
+\index[sd]{mtx-changer load}
+
+Si vous avez une cartouche dans le slot 3, elle sera charg\'ee dans le slot
+de lecture (0).
+
+\item [/etc/bacula/mtx-changer \ /dev/sg0 \ loaded \ 0 \ /dev/nst0 \ 0]
+\index[sd]{mtx-changer loaded}
+
+devrait afficher "3"
+
+\item [/etc/bacula/mtx-changer \ /dev/sg0 \ unload]
+\end{description}
+
+Une fois que toutes les commandes ci-dessus fonctionnent correctement, Bacula
+devrait \^etre capable d'utiliser la librairie, pourvu que votre configuration
+comporte la bonne commande {\bf Changer Command}. A ce stade, il ne peut subsister
+qu'un probl\`eme : si votre librairie requiert un certain d\'elai pour charger la cartouche
+apr\`es l'ex\'ecution de la commande. Imm\'ediatement apr\`es avoir obtenu le retour
+du script {\bf mtx-changer}, Bacula commande le rembobinage et la lecture de la bande.
+S'il obtient une erreur I/O, vous devriez probablement ins\'erer une pause ({\bf sleep 20})
+apr\`es la commande {\bf mtx}, mais prenez soin de terminer le script avec un
+code de sortie 0 en ajoutant {\bf exit 0} apr\`es toute commande que vous ajoutez
+au script, car Bacula contr\^ole le code de sortie du script qui devrait \^etre 0 si
+tout s'est bien pass\'e.
+
+Vous pouvez tester si vous avez ou non besoin d'une telle pause en
+ex\'ecutant le script suivant :
+
+\footnotesize
+\begin{verbatim}
+#!/bin/sh
+/etc/bacula/mtx-changer /dev/sg0 unload
+/etc/bacula/mtx-changer /dev/sg0 load 3
+mt -f /dev/st0 rewind
+mt -f /dev/st0 weof
+\end{verbatim}
+\normalsize
+
+S'il fonctionne correctement, vous n'\^etes sans doute pas concern\'e par ce
+probl\`eme. Sinon, commencez par ajouter {\bf sleep 30} voire {\bf sleep 60}
+juste apr\`es la commande "/etc/bacula/mtx-changer /dev/sg0 load 3". Si
+\c{c}a marche, vous pouvez alors int\'egrer cette pause dans le script
+{\bf mtx-changer} afin qu'elle soit effective lorsque Bacula est ex\'ecut\'e.
+
+Quelques rares librairies exigent l'\'ejection de la cartouche avant de pouvoir
+la d\'echarger. Dan ce cas, la commande /etc/bacula/mtx-changer /dev/sg0 load 3
+ne fonctionne jamais, quel que soit la dur\'ee de la pause. Si vous pensez
+avoir ce probl\`eme, ins\'erez une commande "eject" juste avant la commande
+/etc/bacula/mtx-changer /dev/sg0 unload :
+
+\footnotesize
+\begin{verbatim}
+#!/bin/sh
+/etc/bacula/mtx-changer /dev/sg0 unload
+mt -f /dev/st0 offline
+/etc/bacula/mtx-changer /dev/sg0 load 3
+mt -f /dev/st0 rewind
+mt -f /dev/st0 weof
+\end{verbatim}
+\normalsize
+
+Naturellement, si vous avez besoin de la commande {\bf offline}, vous devriez
+l'int\'egrer au script mtx-changer, en n'oubliant pas de pr\'eserver le code de
+sortie du script par l'ajout de {\bf exit 0}.
+
+Comme indiqu\'e pr\'ec\'edemment, plusieurs scripts qui impl\'ementent ces fonctions
+sont regroup\'es dans {\bf \lt{}bacula-source\gt{}/examples/devices}, ils
+peuvent vous inspirer pour faire en sorte que le votre fonctionne.
+
+Si Bacula affiche "Rewind error on /dev/nst0. ERR=Input/output error." vous
+avez probablement besoin d'accro\^itre la pause dans le script {\bf mtx-changer}
+
+\label{using}
+
+\section{Utiliser la librairie}
+\index[general]{Utiliser la librairie}
+\index[general]{Librairie!Utiliser la }
+
+Supposons que vous ayez convenablement d\'efini les directives Device du
+Storage Daemon, et que vous ayez ajout\'e la directive {\bf Autochanger = yes}
+dans la ressource Storage de votre fichier bacula-dir.conf.
+
+Maintenant, alimentez votre librairie avec quelques cartouches vierges.
+
+Que faire pour que Bacula acc\`ede \`a ces cartouches ?
+
+Une strat\'egie consiste \`a pr\'e-\'etiqueter chacune des cartouches. Pour cela,
+d\'emarrez Bacula, puis utilisez la commande {\bf label} dans la console :
+
+\footnotesize
+\begin{verbatim}
+./console
+Connecting to Director rufus:8101
+1000 OK: rufus-dir Version: 1.26 (4 October 2002)
+*label
+\end{verbatim}
+\normalsize
+
+l'affichage devrait \^etre :
+
+\footnotesize
+\begin{verbatim}
+Using default Catalog name=BackupDB DB=bacula
+The defined Storage resources are:
+ 1: Autochanger
+ 2: File
+Select Storage resource (1-2): 1
+\end{verbatim}
+\normalsize
+
+Choisissez la librairie (choix 1), vous obtenez :
+
+\footnotesize
+\begin{verbatim}
+Enter new Volume name: TestVolume1
+Enter slot (0 for none): 1
+\end{verbatim}
+\normalsize
+
+Ici saisissez {\bf TestVolume1} en guise de nom, et {\bf 1} pour le slot.
+On vous demande alors :
+
+\footnotesize
+\begin{verbatim}
+Defined Pools:
+ 1: Default
+ 2: File
+Select the Pool (1-2): 1
+\end{verbatim}
+\normalsize
+
+S\'electionnez le pool Default (ce qui est fait automatiquement si vous
+n'avez que celui-l\`a). Bacula poursuit en d\'echargeant toute cartouche
+charg\'ee, en chargeant celle du slot 1 et en l'\'etiquetant. Dans cet exemple,
+le lecteur \'etait vide, il en r\'esulte l'affichage :
+
+\footnotesize
+\begin{verbatim}
+Connecting to Storage daemon Autochanger at localhost:9103 ...
+Sending label command ...
+3903 Issuing autochanger "load slot 1" command.
+3000 OK label. Volume=TestVolume1 Device=/dev/nst0
+Media record for Volume=TestVolume1 successfully created.
+Requesting mount Autochanger ...
+3001 Device /dev/nst0 is mounted with Volume TestVolume1
+You have messages.
+*
+\end{verbatim}
+\normalsize
+
+Vous pouvez continuer \`a \'etiqueter les autres volumes, les messages
+changeront l\'eg\`erement du fait qu'il y aura cette fois une cartouche
+\`a d\'echarger avant de charger la suivante.
+
+Une fois que tous vos volumes sont \'etiquet\'es, Bacula est en mesure de les
+charger lorsqu'il en a besoin.
+
+Pour "voir" votre \'etiquetage, saisissez la commande {\bf list volumes} dans
+la console, vous devriez obtenir quelque chose comme :
+
+\footnotesize
+\begin{verbatim}
+*{\bf list volumes}
+Using default Catalog name=BackupDB DB=bacula
+Defined Pools:
+ 1: Default
+ 2: File
+Select the Pool (1-2): 1
++-------+----------+--------+---------+-------+--------+----------+-------+------+
+| MedId | VolName | MedTyp | VolStat | Bites | LstWrt | VolReten | Recyc | Slot |
++-------+----------+--------+---------+-------+--------+----------+-------+------+
+| 1 | TestVol1 | DDS-4 | Append | 0 | 0 | 30672000 | 0 | 1 |
+| 2 | TestVol2 | DDS-4 | Append | 0 | 0 | 30672000 | 0 | 2 |
+| 3 | TestVol3 | DDS-4 | Append | 0 | 0 | 30672000 | 0 | 3 |
+| ... |
++-------+----------+--------+---------+-------+--------+----------+-------+------+
+\end{verbatim}
+\normalsize
+
+\label{Barcodes}
+
+\section{Support des codes barres}
+\index[general]{Support!codes barres}
+\index[general]{Support des codes barres}
+
+Bacula utilise les codes barres \`a travers deux commandes de la console :
+{\bf label barcodes} et {\bf update slots}.
+
+La commande {\bf label barcodes} ordonne \`a Bacula de lire tous les codes
+barres de toutes les cartouches pr\'esentes dans la librairie \`a l'aide de la
+commande {\bf mtx-changer} {\bf list}. Les cartouches sont ensuite mont\'ees
+l'une apr\`es l'autre pour \^etre \'etiquet\'e du nom de leur code barres.
+
+La commande {\bf update slots} commence par obtenir du script {\bf mtx-changer}
+la liste des cartouches et de leurs codes barres. Ensuite, il confronte
+chacune des valeurs du catalogues \`a cette liste afin de le mettre \`a jour.
+Notez que si un volume ne figure pas dans le catalogue, il n'y a rien a faire.
+Cette commande est utile pour synchroniser Bacula avec le contenu de la librairie
+si vous avez chang\'e de magasin ou d\'eplac\'e des cartouches.
+
+La directive {\bf Cleaning Prefix} peut \^etre utilis\'ee dans la ressource Pool pour
+d\'efinir un pr\'efixe de nom de volume qui, s'il correspond au code barres d'un volume
+conf\`ere \`a ce volume le statut (VolStatus) {\bf Cleaning}. Ceci \'evite que Bacula
+tente d'\'ecrire sur une cartouche de nettoyage.
+
+\label{interface}
+
+\section{Interface entre Bacula et les librairies}
+\index[general]{Interface!Bacula et les librairies}
+\index[general]{Interface entre Bacula et les librairies}
+
+Bacula appelle le script mtx-changer que vous sp\'ecifiez au niveau de la
+directive {\bf Changer Command}. En principe, ce sera le script {\bf mtx-changer}
+que nous fournissons, mais ce pourrait \^etre n'importe quel programme
+qui impl\'emente les commandes {\bf loaded}, {\bf load}, {\bf unload}, {\bf list},
+et {\bf slots} qu'utilise Bacula. Voici le format sous lequel ces commandes
+doivent retourner les informations :
+
+\footnotesize
+\begin{verbatim}
+- Currently the changer commands used are:
+ loaded -- retourne le num\'ero du slot d'origine de la cartouche charg\'ee,
+ avec pour base 1 et 0 pour le lecteur.
+ load -- charge la cartouche du slot sp\'ecifi\'e dans le lecteur.(notez que certains
+ mat\'eriels requi\`erent une pause de 30 secondes apr\`es cette commande)
+ unload -- d\'echarge le lecteur (la cartouche retourne dans son slot d'origine).
+ list -- retourne une ligne par cartouche pr\'esente dans la librairie
+ au format <slot>:<barcode> o\`u {\bf slot} est un entier non-nul
+ repr\'esentant le num\'ero du slot, et {\bf barcode} est le code barres,
+ s'il existe et si la librairie le prend en charge, associ\'e \`a la cartouche
+ (dans le cas contraire, le champ "barcode" est laiss\'e blanc.
+ slots -- retourne le nombre total de slots dans la librairie.
+\end{verbatim}
+\normalsize
+
+Bacula contr\^ole le code de sortie du programme appel\'e. Si ce code est 0, les
+informations sont accept\'ees. Dans le cas contraire, elles sont ignor\'ees
+et le lecteur est trait\'e comme s'il n'\'etait pas dans une librairie.
--- /dev/null
+\indexentry {Bimagemgr }{2}
+\indexentry {bimagemgr!Installation }{2}
+\indexentry {bimagemgr Installation }{2}
+\indexentry {bimagemgr!Usage }{4}
+\indexentry {bimagemgr Usage }{4}
+\indexentry {GNU Free Documentation License}{7}
+\indexentry {License!GNU Free Documentation}{7}
--- /dev/null
+%%
+%%
+
+\chapter{The Bootstrap File}
+\label{BootstrapChapter}
+\index[general]{File!Bootstrap }
+\index[general]{Bootstrap File }
+
+The information in this chapter is provided so that you may either create your
+own bootstrap files, or so that you can edit a bootstrap file produced by {\bf
+Bacula}. However, normally the bootstrap file will be automatically created
+for you during the
+\ilink{restore\_command}{_ConsoleChapter} command in the Console program, or
+by using a
+\ilink{ Write Bootstrap}{writebootstrap} record in your Backup
+Jobs, and thus you will never need to know the details of this file.
+
+The {\bf bootstrap} file contains ASCII information that permits precise
+specification of what files should be restored, what volume they are on,
+and where they are on the volume. It is a relatively compact
+form of specifying the information, is human readable, and can be edited with
+any text editor.
+
+\section{Bootstrap File Format}
+\index[general]{Format!Bootstrap}
+\index[general]{Bootstrap File Format }
+
+The general format of a {\bf bootstrap} file is:
+
+{\bf \lt{}keyword\gt{}= \lt{}value\gt{}}
+
+Where each {\bf keyword} and the {\bf value} specify which files to restore.
+More precisely the {\bf keyword} and their {\bf values} serve to limit which
+files will be restored and thus act as a filter. The absence of a keyword
+means that all records will be accepted.
+
+Blank lines and lines beginning with a pound sign (\#) in the bootstrap file
+are ignored.
+
+There are keywords which permit filtering by Volume, Client, Job, FileIndex,
+Session Id, Session Time, ...
+
+The more keywords that are specified, the more selective the specification of
+which files to restore will be. In fact, each keyword is {\bf AND}ed with
+other keywords that may be present.
+
+For example,
+
+\footnotesize
+\begin{verbatim}
+Volume = Test-001
+VolSessionId = 1
+VolSessionTime = 108927638
+\end{verbatim}
+\normalsize
+
+directs the Storage daemon (or the {\bf bextract} program) to restore only
+those files on Volume Test-001 {\bf AND} having VolumeSessionId equal to one
+{\bf AND} having VolumeSession time equal to 108927638.
+
+The full set of permitted keywords presented in the order in which they are
+matched against the Volume records are:
+
+\begin{description}
+
+\item [Volume]
+ \index[general]{Volume }
+ The value field specifies what Volume the following commands apply to.
+ Each Volume specification becomes the current Volume, to which all the
+ following commands apply until a new current Volume (if any) is
+ specified. If the Volume name contains spaces, it should be enclosed in
+ quotes. At lease one Volume specification is required.
+
+\item [Count]
+ \index[general]{Count}
+ The value is the total number of files that will be restored for this Volume.
+ This allows the Storage daemon to know when to stop reading the Volume.
+ This value is optional.
+
+\item [VolFile]
+ \index[general]{VolFile}
+ The value is a file number, a list of file numbers, or a range of file
+ numbers to match on the current Volume. The file number represents the
+ physical file on the Volume where the data is stored. For a tape
+ volume, this record is used to position to the correct starting file,
+ and once the tape is past the last specified file, reading will stop.
+
+\item [VolBlock]
+ \index[general]{VolBlock}
+ The value is a block number, a list of block numbers, or a range of
+ block numbers to match on the current Volume. The block number
+ represents the physical block within the file on the Volume where the
+ data is stored.
+
+
+\item [VolSessionTime]
+ \index[general]{VolSessionTime }
+ The value specifies a Volume Session Time to be matched from the current
+ volume.
+
+\item [VolSessionId]
+ \index[general]{VolSessionId }
+ The value specifies a VolSessionId, a list of volume session ids, or a
+ range of volume session ids to be matched from the current Volume. Each
+ VolSessionId and VolSessionTime pair corresponds to a unique Job that is
+ backed up on the Volume.
+
+\item [JobId]
+ \index[general]{JobId }
+ The value specifies a JobId, list of JobIds, or range of JobIds to be
+ selected from the current Volume. Note, the JobId may not be unique if you
+ have multiple Directors, or if you have reinitialized your database. The
+ JobId filter works only if you do not run multiple simultaneous jobs.
+ This value is optional and not used by Bacula to restore files.
+
+\item [Job]
+ \index[general]{Job }
+ The value specifies a Job name or list of Job names to be matched on the
+ current Volume. The Job corresponds to a unique VolSessionId and
+ VolSessionTime pair. However, the Job is perhaps a bit more readable by
+ humans. Standard regular expressions (wildcards) may be used to match Job
+ names. The Job filter works only if you do not run multiple simultaneous
+ jobs.
+ This value is optional and not used by Bacula to restore files.
+
+\item [Client]
+ \index[general]{Client }
+ The value specifies a Client name or list of Clients to will be matched on
+ the current Volume. Standard regular expressions (wildcards) may be used to
+ match Client names. The Client filter works only if you do not run multiple
+ simultaneous jobs.
+ This value is optional and not used by Bacula to restore files.
+
+\item [FileIndex]
+ \index[general]{FileIndex }
+ The value specifies a FileIndex, list of FileIndexes, or range of FileIndexes
+ to be selected from the current Volume. Each file (data) stored on a Volume
+ within a Session has a unique FileIndex. For each Session, the first file
+ written is assigned FileIndex equal to one and incremented for each file
+ backed up.
+
+ This for a given Volume, the triple VolSessionId, VolSessionTime, and
+ FileIndex uniquely identifies a file stored on the Volume. Multiple copies of
+ the same file may be stored on the same Volume, but for each file, the triple
+ VolSessionId, VolSessionTime, and FileIndex will be unique. This triple is
+ stored in the Catalog database for each file.
+
+ To restore a particular file, this value (or a range of FileIndexes) is
+ required.
+
+\item [Slot]
+ \index[general]{Slot }
+ The value specifies the autochanger slot. There may be only a single {\bf
+ Slot} specification for each Volume.
+
+\item [Stream]
+ \index[general]{Stream }
+ The value specifies a Stream, a list of Streams, or a range of Streams to be
+ selected from the current Volume. Unless you really know what you are doing
+ (the internals of {\bf Bacula}), you should avoid this specification.
+ This value is optional and not used by Bacula to restore files.
+
+\item [*JobType]
+ \index[general]{*JobType }
+ Not yet implemented.
+
+\item [*JobLevel]
+ \index[general]{*JobLevel }
+ Not yet implemented.
+\end{description}
+
+The {\bf Volume} record is a bit special in that it must be the first record.
+The other keyword records may appear in any order and any number following a
+Volume record.
+
+Multiple Volume records may be specified in the same bootstrap file, but each
+one starts a new set of filter criteria for the Volume.
+
+In processing the bootstrap file within the current Volume, each filter
+specified by a keyword is {\bf AND}ed with the next. Thus,
+
+\footnotesize
+\begin{verbatim}
+Volume = Test-01
+Client = "My machine"
+FileIndex = 1
+\end{verbatim}
+\normalsize
+
+will match records on Volume {\bf Test-01} {\bf AND} Client records for {\bf
+My machine} {\bf AND} FileIndex equal to {\bf one}.
+
+Multiple occurrences of the same record are {\bf OR}ed together. Thus,
+
+\footnotesize
+\begin{verbatim}
+Volume = Test-01
+Client = "My machine"
+Client = "Backup machine"
+FileIndex = 1
+\end{verbatim}
+\normalsize
+
+will match records on Volume {\bf Test-01} {\bf AND} (Client records for {\bf
+My machine} {\bf OR} {\bf Backup machine}) {\bf AND} FileIndex equal to {\bf
+one}.
+
+For integer values, you may supply a range or a list, and for all other values
+except Volumes, you may specify a list. A list is equivalent to multiple
+records of the same keyword. For example,
+
+\footnotesize
+\begin{verbatim}
+Volume = Test-01
+Client = "My machine", "Backup machine"
+FileIndex = 1-20, 35
+\end{verbatim}
+\normalsize
+
+will match records on Volume {\bf Test-01} {\bf AND} {\bf (}Client records for
+{\bf My machine} {\bf OR} {\bf Backup machine}{\bf )} {\bf AND} {\bf
+(}FileIndex 1 {\bf OR} 2 {\bf OR} 3 ... {\bf OR} 20 {\bf OR} 35{\bf )}.
+
+As previously mentioned above, there may be multiple Volume records in the
+same bootstrap file. Each new Volume definition begins a new set of filter
+conditions that apply to that Volume and will be {\bf OR}ed with any other
+Volume definitions.
+
+As an example, suppose we query for the current set of tapes to restore all
+files on Client {\bf Rufus} using the {\bf query} command in the console
+program:
+
+\footnotesize
+\begin{verbatim}
+Using default Catalog name=MySQL DB=bacula
+*query
+Available queries:
+ 1: List Job totals:
+ 2: List where a file is saved:
+ 3: List where the most recent copies of a file are saved:
+ 4: List total files/bytes by Job:
+ 5: List total files/bytes by Volume:
+ 6: List last 10 Full Backups for a Client:
+ 7: List Volumes used by selected JobId:
+ 8: List Volumes to Restore All Files:
+Choose a query (1-8): 8
+Enter Client Name: Rufus
++-------+------------------+------------+-----------+----------+------------+
+| JobId | StartTime | VolumeName | StartFile | VolSesId | VolSesTime |
++-------+------------------+------------+-----------+----------+------------+
+| 154 | 2002-05-30 12:08 | test-02 | 0 | 1 | 1022753312 |
+| 202 | 2002-06-15 10:16 | test-02 | 0 | 2 | 1024128917 |
+| 203 | 2002-06-15 11:12 | test-02 | 3 | 1 | 1024132350 |
+| 204 | 2002-06-18 08:11 | test-02 | 4 | 1 | 1024380678 |
++-------+------------------+------------+-----------+----------+------------+
+\end{verbatim}
+\normalsize
+
+The output shows us that there are four Jobs that must be restored. The first
+one is a Full backup, and the following three are all Incremental backups.
+
+The following bootstrap file will restore those files:
+
+\footnotesize
+\begin{verbatim}
+Volume=test-02
+VolSessionId=1
+VolSessionTime=1022753312
+Volume=test-02
+VolSessionId=2
+VolSessionTime=1024128917
+Volume=test-02
+VolSessionId=1
+VolSessionTime=1024132350
+Volume=test-02
+VolSessionId=1
+VolSessionTime=1024380678
+\end{verbatim}
+\normalsize
+
+As a final example, assume that the initial Full save spanned two Volumes. The
+output from {\bf query} might look like:
+
+\footnotesize
+\begin{verbatim}
++-------+------------------+------------+-----------+----------+------------+
+| JobId | StartTime | VolumeName | StartFile | VolSesId | VolSesTime |
++-------+------------------+------------+-----------+----------+------------+
+| 242 | 2002-06-25 16:50 | File0003 | 0 | 1 | 1025016612 |
+| 242 | 2002-06-25 16:50 | File0004 | 0 | 1 | 1025016612 |
+| 243 | 2002-06-25 16:52 | File0005 | 0 | 2 | 1025016612 |
+| 246 | 2002-06-25 19:19 | File0006 | 0 | 2 | 1025025494 |
++-------+------------------+------------+-----------+----------+------------+
+\end{verbatim}
+\normalsize
+
+and the following bootstrap file would restore those files:
+
+\footnotesize
+\begin{verbatim}
+Volume=File0003
+VolSessionId=1
+VolSessionTime=1025016612
+Volume=File0004
+VolSessionId=1
+VolSessionTime=1025016612
+Volume=File0005
+VolSessionId=2
+VolSessionTime=1025016612
+Volume=File0006
+VolSessionId=2
+VolSessionTime=1025025494
+\end{verbatim}
+\normalsize
+
+\section{Automatic Generation of Bootstrap Files}
+\index[general]{Files!Automatic Generation of Bootstrap }
+\index[general]{Automatic Generation of Bootstrap Files }
+
+One thing that is probably worth knowing: the bootstrap files that are
+generated automatically at the end of the job are not as optimized as those
+generated by the restore command. This is because during Incremental and
+Differential jobs, the records pertaining to the files written for the
+Job are appended to the end of the bootstrap file.
+As consequence, all the files saved to an Incremental or Differential job will be
+restored first by the Full save, then by any Incremental or Differential
+saves.
+
+When the bootstrap file is generated for the restore command, only one copy
+(the most recent) of each file is restored.
+
+So if you have spare cycles on your machine, you could optimize the bootstrap
+files by doing the following:
+
+\footnotesize
+\begin{verbatim}
+ ./bconsole
+ restore client=xxx select all
+ done
+ no
+ quit
+ Backup bootstrap file.
+\end{verbatim}
+\normalsize
+
+The above will not work if you have multiple FileSets because that will be an
+extra prompt. However, the {\bf restore client=xxx select all} builds the
+in-memory tree, selecting everything and creates the bootstrap file.
+
+The {\bf no} answers the {\bf Do you want to run this (yes/mod/no)} question.
+
+\label{bscanBootstrap}
+\section{Bootstrap for bscan}
+\index[general]{bscan}
+\index[general]{bscan!bootstrap}
+\index[general]{bscan bootstrap}
+If you have a very large number of Volumes to scan with {\bf bscan},
+you may exceed the command line limit (511 characters). I that case,
+you can create a simple bootstrap file that consists of only the
+volume names. An example might be:
+
+\footnotesize
+\begin{verbatim}
+Volume="Vol001"
+Volume="Vol002"
+Volume="Vol003"
+Volume="Vol004"
+Volume="Vol005"
+\end{verbatim}
+\normalsize
+
+
+\section{A Final Bootstrap Example}
+\index[general]{Bootstrap Example}
+\index[general]{Example!Bootstrap}
+
+If you want to extract or copy a single Job, you can do it by selecting by
+JobId (code not tested) or better yet, if you know the VolSessionTime and the
+VolSessionId (printed on Job report and in Catalog), specifying this is by far
+the best. Using the VolSessionTime and VolSessionId is the way Bacula does
+restores. A bsr file might look like the following:
+
+\footnotesize
+\begin{verbatim}
+Volume="Vol001"
+VolSessionId=10
+VolSessionTime=1080847820
+\end{verbatim}
+\normalsize
+
+If you know how many files are backed up (on the job report), you can
+enormously speed up the selection by adding (let's assume there are 157
+files):
+
+\footnotesize
+\begin{verbatim}
+FileIndex=1-157
+Count=157
+\end{verbatim}
+\normalsize
+
+Finally, if you know the File number where the Job starts, you can also cause
+bcopy to forward space to the right file without reading every record:
+
+\footnotesize
+\begin{verbatim}
+VolFile=20
+\end{verbatim}
+\normalsize
+
+There is nothing magic or complicated about a BSR file. Parsing it and
+properly applying it within Bacula *is* magic, but you don't need to worry
+about that.
+
+If you want to see a *real* bsr file, simply fire up the {\bf restore} command
+in the console program, select something, then answer no when it prompts to
+run the job. Then look at the file {\bf restore.bsr} in your working
+directory.
--- /dev/null
+%%
+%%
+
+\section{Bacula Bugs}
+\label{BugsChapter}
+\index[general]{Bacula Bugs }
+\index[general]{Bugs!Bacula }
+
+Well fortunately there are not too many bugs, but thanks to Dan Langille, we
+have a
+\elink{bugs database}{http://bugs.bacula.org} where bugs are reported.
+Generally, when a bug is fixed, a patch for the currently released version will
+be attached to the bug report.
+
+The directory {\bf patches} in the current SVN always contains a list of
+the patches that have been created for the previously released version
+of Bacula. In addition, the file {\bf patches-version-number} in the
+{\bf patches} directory contains a summary of each of the patches.
+
+A "raw" list of the current task list and known issues can be found in {\bf
+kernstodo} in the main Bacula source directory.
--- /dev/null
+#!/usr/bin/perl -w
+# Finds potential problems in tex files, and issues warnings to the console
+# about what it finds. Takes a list of files as its only arguments,
+# and does checks on all the files listed. The assumption is that these are
+# valid (or close to valid) LaTeX files. It follows \include statements
+# recursively to pick up any included tex files.
+#
+#
+#
+# Currently the following checks are made:
+#
+# -- Multiple hyphens not inside a verbatim environment (or \verb). These
+# should be placed inside a \verb{} contruct so they will not be converted
+# to single hyphen by latex and latex2html.
+
+
+# Original creation 3-8-05 by Karl Cunningham karlc -at- keckec -dot- com
+#
+#
+
+use strict;
+
+# The following builds the test string to identify and change multiple
+# hyphens in the tex files. Several constructs are identified but only
+# multiple hyphens are changed; the others are fed to the output
+# unchanged.
+my $b = '\\\\begin\\*?\\s*\\{\\s*'; # \begin{
+my $e = '\\\\end\\*?\\s*\\{\\s*'; # \end{
+my $c = '\\s*\\}'; # closing curly brace
+
+# This captures entire verbatim environments. These are passed to the output
+# file unchanged.
+my $verbatimenv = $b . "verbatim" . $c . ".*?" . $e . "verbatim" . $c;
+
+# This captures \verb{..{ constructs. They are passed to the output unchanged.
+my $verb = '\\\\verb\\*?(.).*?\\1';
+
+# This captures multiple hyphens with a leading and trailing space. These are not changed.
+my $hyphsp = '\\s\\-{2,}\\s';
+
+# This identifies other multiple hyphens.
+my $hyphens = '\\-{2,}';
+
+# This identifies \hyperpage{..} commands, which should be ignored.
+my $hyperpage = '\\\\hyperpage\\*?\\{.*?\\}';
+
+# This builds the actual test string from the above strings.
+#my $teststr = "$verbatimenv|$verb|$tocentry|$hyphens";
+my $teststr = "$verbatimenv|$verb|$hyphsp|$hyperpage|$hyphens";
+
+
+sub get_includes {
+ # Get a list of include files from the top-level tex file. The first
+ # argument is a pointer to the list of files found. The rest of the
+ # arguments is a list of filenames to check for includes.
+ my $files = shift;
+ my ($fileline,$includefile,$includes);
+
+ while (my $filename = shift) {
+ # Get a list of all the html files in the directory.
+ open my $if,"<$filename" or die "Cannot open input file $filename\n";
+ $fileline = 0;
+ $includes = 0;
+ while (<$if>) {
+ chomp;
+ $fileline++;
+ # If a file is found in an include, process it.
+ if (($includefile) = /\\include\s*\{(.*?)\}/) {
+ $includes++;
+ # Append .tex to the filename
+ $includefile .= '.tex';
+
+ # If the include file has already been processed, issue a warning
+ # and don't do it again.
+ my $found = 0;
+ foreach (@$files) {
+ if ($_ eq $includefile) {
+ $found = 1;
+ last;
+ }
+ }
+ if ($found) {
+ print "$includefile found at line $fileline in $filename was previously included\n";
+ } else {
+ # The file has not been previously found. Save it and
+ # recursively process it.
+ push (@$files,$includefile);
+ get_includes($files,$includefile);
+ }
+ }
+ }
+ close IF;
+ }
+}
+
+
+sub check_hyphens {
+ my (@files) = @_;
+ my ($filedata,$this,$linecnt,$before);
+
+ # Build the test string to check for the various environments.
+ # We only do the conversion if the multiple hyphens are outside of a
+ # verbatim environment (either \begin{verbatim}...\end{verbatim} or
+ # \verb{--}). Capture those environments and pass them to the output
+ # unchanged.
+
+ foreach my $file (@files) {
+ # Open the file and load the whole thing into $filedata. A bit wasteful but
+ # easier to deal with, and we don't have a problem with speed here.
+ $filedata = "";
+ open IF,"<$file" or die "Cannot open input file $file";
+ while (<IF>) {
+ $filedata .= $_;
+ }
+ close IF;
+
+ # Set up to process the file data.
+ $linecnt = 1;
+
+ # Go through the file data from beginning to end. For each match, save what
+ # came before it and what matched. $filedata now becomes only what came
+ # after the match.
+ # Chech the match to see if it starts with a multiple-hyphen. If so
+ # warn the user. Keep track of line numbers so they can be output
+ # with the warning message.
+ while ($filedata =~ /$teststr/os) {
+ $this = $&;
+ $before = $`;
+ $filedata = $';
+ $linecnt += $before =~ tr/\n/\n/;
+
+ # Check if the multiple hyphen is present outside of one of the
+ # acceptable constructs.
+ if ($this =~ /^\-+/) {
+ print "Possible unwanted multiple hyphen found in line ",
+ "$linecnt of file $file\n";
+ }
+ $linecnt += $this =~ tr/\n/\n/;
+ }
+ }
+}
+##################################################################
+# MAIN ####
+##################################################################
+
+my (@includes,$cnt);
+
+# Examine the file pointed to by the first argument to get a list of
+# includes to test.
+get_includes(\@includes,@ARGV);
+
+check_hyphens(@includes);
--- /dev/null
+%%
+%%
+%% The following characters must be preceded by a backslash
+%% to be entered as printable characters:
+%%
+%% # $ % & ~ _ ^ \ { }
+%%
+
+\documentclass[11pt,a4paper]{book}
+\usepackage{html}
+\usepackage{float}
+\usepackage{graphicx}
+\usepackage{bacula}
+\usepackage{longtable}
+\usepackage{makeidx}
+\usepackage{index}
+\usepackage{setspace}
+\usepackage{hyperref}
+\usepackage{url}
+
+
+\makeindex
+\newindex{dir}{ddx}{dnd}{Director Index}
+\newindex{fd}{fdx}{fnd}{File Daemon Index}
+\newindex{sd}{sdx}{snd}{Storage Daemon Index}
+\newindex{console}{cdx}{cnd}{Console Index}
+\newindex{general}{idx}{ind}{General Index}
+
+\sloppy
+
+\begin{document}
+\sloppy
+
+\newfont{\bighead}{cmr17 at 36pt}
+\parskip 10pt
+\parindent 0pt
+
+\title{\includegraphics{./bacula-logo.eps} \\ \bigskip
+ \Huge{Bacula Concepts and Overview Guide}
+ \begin{center}
+ \large{It comes in the night and sucks
+ the essence from your computers. }
+ \end{center}
+}
+
+
+\author{Kern Sibbald}
+\date{\vspace{1.0in}\today \\
+ This manual documents Bacula version \input{version} \\
+ \vspace{0.2in}
+ Copyright \copyright 1999-2007, Free Software Foundation Europe
+ e.V. \\
+ \vspace{0.2in}
+ Permission is granted to copy, distribute and/or modify this document under the terms of the
+ GNU Free Documentation License, Version 1.2 published by the Free Software Foundation;
+ with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+ A copy of the license is included in the section entitled "GNU Free Documentation License".
+}
+
+\maketitle
+
+\clearpage
+\pagenumbering{roman}
+\tableofcontents
+\clearpage
+\listoffigures
+\clearpage
+\listoftables
+\clearpage
+
+\markboth{Bacula Manual}{}
+\pagenumbering{arabic}
+\include{general}
+\include{state}
+\include{requirements}
+\include{supportedoses}
+\include{supporteddrives}
+\include{tutorial}
+\include{restore}
+\include{recycling}
+\include{disk}
+\include{dvd}
+\include{pools}
+\include{migration}
+\include{strategies}
+\include{autochangers}
+\include{supportedchangers}
+\include{spooling}
+\include{python}
+\include{ansi-labels}
+\include{win32}
+\include{rescue}
+\include{tls}
+\include{dataencryption}
+\include{verify}
+\include{bootstrap}
+\include{license}
+\include{fdl}
+\include{gpl}
+\include{lesser}
+\include{projects}
+\include{thanks}
+\include{bugs}
+\include{vars}
+\include{stunnel}
+
+% pull in the index
+\clearpage
+\printindex[general]
+\printindex[dir]
+\printindex[fd]
+\printindex[sd]
+\printindex[console]
+
+\end{document}
--- /dev/null
+
+\chapter{Data Encryption}
+\label{DataEncryption}
+\index[general]{Data Encryption}
+\index[general]{Encryption!Data}
+\index[general]{Data Encryption}
+
+Bacula permits file data encryption and signing within the File Daemon (or
+Client) prior to sending data to the Storage Daemon. Upon restoration,
+file signatures are validated and any mismatches are reported. At no time
+does the Director or the Storage Daemon have access to unencrypted file
+contents.
+
+
+It is very important to specify what this implementation does NOT
+do:
+\begin{itemize}
+\item There is one important restore problem to be aware of, namely, it's
+ possible for the director to restore new keys or a Bacula configuration
+ file to the client, and thus force later backups to be made with a
+ compromised key and/or with no encryption at all. You can avoid this by
+ not not changing the location of the keys in your Bacula File daemon
+ configuration file, and not changing your File daemon keys. If you do
+ change either one, you must ensure that no restore is done that restores
+ the old configuration or the old keys. In general, the worst effect of
+ this will be that you can no longer connect the File daemon.
+
+\item The implementation does not encrypt file metadata such as file path
+ names, permissions, and ownership. Extended attributes are also currently
+ not encrypted. However, Mac OS X resource forks are encrypted.
+\end{itemize}
+
+Encryption and signing are implemented using RSA private keys coupled with
+self-signed x509 public certificates. This is also sometimes known as PKI
+or Public Key Infrastructure.
+
+Each File Daemon should be given its own unique private/public key pair.
+In addition to this key pair, any number of "Master Keys" may be specified
+-- these are key pairs that may be used to decrypt any backups should the
+File Daemon key be lost. Only the Master Key's public certificate should
+be made available to the File Daemon. Under no circumstances should the
+Master Private Key be shared or stored on the Client machine.
+
+The Master Keys should be backed up to a secure location, such as a CD
+placed in a in a fire-proof safe or bank safety deposit box. The Master
+Keys should never be kept on the same machine as the Storage Daemon or
+Director if you are worried about an unauthorized party compromising either
+machine and accessing your encrypted backups.
+
+While less critical than the Master Keys, File Daemon Keys are also a prime
+candidate for off-site backups; burn the key pair to a CD and send the CD
+home with the owner of the machine.
+
+NOTE!!! If you lose your encryption keys, backups will be unrecoverable.
+{\bf ALWAYS} store a copy of your master keys in a secure, off-site location.
+
+The basic algorithm used for each backup session (Job) is:
+\begin{enumerate}
+\item The File daemon generates a session key.
+\item The FD encrypts that session key via PKE for all recipients (the file
+daemon, any master keys).
+\item The FD uses that session key to perform symmetric encryption on the data.
+\end{enumerate}
+
+
+\section{Building Bacula with Encryption Support}
+\index[general]{Building Bacula with Encryption Support}
+
+The configuration option for enabling OpenSSL encryption support has not changed
+since Bacula 1.38. To build Bacula with encryption support, you will need
+the OpenSSL libraries and headers installed. When configuring Bacula, use:
+
+\begin{verbatim}
+ ./configure --with-openssl ...
+\end{verbatim}
+
+\section{Encryption Technical Details}
+\index[general]{Encryption Technical Details}
+
+The implementation uses 128bit AES-CBC, with RSA encrypted symmetric
+session keys. The RSA key is user supplied.
+If you are running OpenSSL 0.9.8 or later, the signed file hash uses
+SHA-256 -- otherwise, SHA-1 is used.
+
+End-user configuration settings for the algorithms are not currently
+exposed -- only the algorithms listed above are used. However, the
+data written to Volume supports arbitrary symmetric, asymmetric, and
+digest algorithms for future extensibility, and the back-end
+implementation currently supports:
+
+\begin{verbatim}
+Symmetric Encryption:
+ - 128, 192, and 256-bit AES-CBC
+ - Blowfish-CBC
+
+Asymmetric Encryption (used to encrypt symmetric session keys):
+ - RSA
+
+Digest Algorithms:
+ - MD5
+ - SHA1
+ - SHA256
+ - SHA512
+\end{verbatim}
+
+The various algorithms are exposed via an entirely re-usable,
+OpenSSL-agnostic API (ie, it is possible to drop in a new encryption
+backend). The Volume format is DER-encoded ASN.1, modeled after the
+Cryptographic Message Syntax from RFC 3852. Unfortunately, using CMS
+directly was not possible, as at the time of coding a free software
+streaming DER decoder/encoder was not available.
+
+
+\section{Decrypting with a Master Key}
+\index[general]{Decrypting with a Master Key}
+
+It is preferable to retain a secure, non-encrypted copy of the
+client's own encryption keypair. However, should you lose the
+client's keypair, recovery with the master keypair is possible.
+
+You must:
+\begin{itemize}
+\item Concatenate the master private and public key into a single
+ keypair file, ie:
+ cat master.key master.cert >master.keypair
+
+\item 2) Set the PKI Keypair statement in your bacula configuration file:
+
+\begin{verbatim}
+ PKI Keypair = master.keypair
+\end{verbatim}
+
+\item Start the restore. The master keypair will be used to decrypt
+ the file data.
+
+\end{itemize}
+
+
+\section{Generating Private/Public Encryption Keys}
+\index[general]{Generating Private/Public Encryption Keypairs}
+
+Generate a Master Key Pair with:
+
+\footnotesize
+\begin{verbatim}
+ openssl genrsa -out master.key 2048
+ openssl req -new -key master.key -x509 -out master.cert
+\end{verbatim}
+\normalsize
+
+Generate a File Daemon Key Pair for each FD:
+
+\footnotesize
+\begin{verbatim}
+ openssl genrsa -out fd-example.key 2048
+ openssl req -new -key fd-example.key -x509 -out fd-example.cert
+ cat fd-example.key fd-example.cert >fd-example.pem
+\end{verbatim}
+\normalsize
+
+Note, there seems to be a lot of confusion around the file extensions given
+to these keys. For example, a .pem file can contain all the following:
+private keys (RSA and DSA), public keys (RSA and DSA) and (x509) certificates.
+It is the default format for OpenSSL. It stores data Base64 encoded DER format,
+surrounded by ASCII headers, so is suitable for text mode transfers between
+systems. A .pem file may contain any number of keys either public or
+private. We use it in cases where there is both a public and a private
+key.
+
+Typically, above we have used the .cert extension to refer to X509
+certificate encoding that contains only a single public key.
+
+
+\section{Example Data Encryption Configuration}
+\index[general]{Example!File Daemon Configuration File}
+\index[general]{Example!Data Encryption Configuration File}
+\index[general]{Example Data Encryption Configuration}
+
+{\bf bacula-fd.conf}
+\footnotesize
+\begin{verbatim}
+FileDaemon {
+ Name = example-fd
+ FDport = 9102 # where we listen for the director
+ WorkingDirectory = /var/bacula/working
+ Pid Directory = /var/run
+ Maximum Concurrent Jobs = 20
+
+ PKI Signatures = Yes # Enable Data Signing
+ PKI Encryption = Yes # Enable Data Encryption
+ PKI Keypair = "/etc/bacula/fd-example.pem" # Public and Private Keys
+ PKI Master Key = "/etc/bacula/master.cert" # ONLY the Public Key
+}
+\end{verbatim}
+\normalsize
--- /dev/null
+%%
+%%
+
+\chapter{Basic Volume Management}
+\label{DiskChapter}
+\index[general]{Basic Volume Management}
+\index[general]{Management!Basic Volume}
+\index[general]{Disk Volumes}
+
+This chapter presents most all the features needed to do Volume management.
+Most of the concepts apply equally well to both tape and disk Volumes.
+However, the chapter was originally written to explain backing up to disk, so
+you will see it is slanted in that direction, but all the directives
+presented here apply equally well whether your volume is disk or tape.
+
+If you have a lot of hard disk storage or you absolutely must have your
+backups run within a small time window, you may want to direct Bacula to
+backup to disk Volumes rather than tape Volumes. This chapter is intended to
+give you some of the options that are available to you so that you can manage
+either disk or tape volumes.
+
+\label{Concepts}
+\section{Key Concepts and Resource Records}
+\index[general]{Key Concepts and Resource Records }
+\index[general]{Records!Key Concepts and Resource }
+
+Getting Bacula to write to disk rather than tape in the simplest case is
+rather easy. In the Storage daemon's configuration file, you simply define an
+{\bf Archive Device} to be a directory. For example, if you want your disk
+backups to go into the directory {\bf /home/bacula/backups}, you could use the
+following:
+
+\footnotesize
+\begin{verbatim}
+Device {
+ Name = FileBackup
+ Media Type = File
+ Archive Device = /home/bacula/backups
+ Random Access = Yes;
+ AutomaticMount = yes;
+ RemovableMedia = no;
+ AlwaysOpen = no;
+}
+\end{verbatim}
+\normalsize
+
+Assuming you have the appropriate {\bf Storage} resource in your Director's
+configuration file that references the above Device resource,
+
+\footnotesize
+\begin{verbatim}
+Storage {
+ Name = FileStorage
+ Address = ...
+ Password = ...
+ Device = FileBackup
+ Media Type = File
+}
+\end{verbatim}
+\normalsize
+
+Bacula will then write the archive to the file {\bf
+/home/bacula/backups/\lt{}volume-name\gt{}} where \lt{}volume-name\gt{} is the
+volume name of a Volume defined in the Pool. For example, if you have labeled
+a Volume named {\bf Vol001}, Bacula will write to the file {\bf
+/home/bacula/backups/Vol001}. Although you can later move the archive file to
+another directory, you should not rename it or it will become unreadable by
+Bacula. This is because each archive has the filename as part of the internal
+label, and the internal label must agree with the system filename before
+Bacula will use it.
+
+Although this is quite simple, there are a number of problems. The first is
+that unless you specify otherwise, Bacula will always write to the same volume
+until you run out of disk space. This problem is addressed below.
+
+In addition, if you want to use concurrent jobs that write to several
+different volumes at the same time, you will need to understand a number
+of other details. An example of such a configuration is given
+at the end of this chapter under \ilink{Concurrent Disk
+Jobs}{ConcurrentDiskJobs}.
+
+\subsection{Pool Options to Limit the Volume Usage}
+\index[general]{Usage!Pool Options to Limit the Volume }
+\index[general]{Pool Options to Limit the Volume Usage }
+
+Some of the options you have, all of which are specified in the Pool record,
+are:
+
+\begin{itemize}
+\item To write each Volume only once (i.e. one Job per Volume or file in this
+ case), use:
+
+{\bf UseVolumeOnce = yes}.
+
+\item To write nnn Jobs to each Volume, use:
+
+ {\bf Maximum Volume Jobs = nnn}.
+
+\item To limit the maximum size of each Volume, use:
+
+ {\bf Maximum Volume Bytes = mmmm}.
+
+ Note, if you use disk volumes, with all versions up to and including
+ 1.39.28, you should probably limit the Volume size to some reasonable
+ value such as say 5GB. This is because during a restore, Bacula is
+ currently unable to seek to the proper place in a disk volume to restore
+ a file, which means that it must read all records up to where the
+ restore begins. If your Volumes are 50GB, reading half or more of the
+ volume could take quite a bit of time. Also, if you ever have a partial
+ hard disk failure, you are more likely to be able to recover more data
+ if they are in smaller Volumes.
+
+\item To limit the use time (i.e. write the Volume for a maximum of five days),
+ use:
+
+{\bf Volume Use Duration = ttt}.
+\end{itemize}
+
+Note that although you probably would not want to limit the number of bytes on
+a tape as you would on a disk Volume, the other options can be very useful in
+limiting the time Bacula will use a particular Volume (be it tape or disk).
+For example, the above directives can allow you to ensure that you rotate
+through a set of daily Volumes if you wish.
+
+As mentioned above, each of those directives is specified in the Pool or
+Pools that you use for your Volumes. In the case of {\bf Maximum Volume Job},
+{\bf Maximum Volume Bytes}, and {\bf Volume Use Duration}, you can actually
+specify the desired value on a Volume by Volume basis. The value specified in
+the Pool record becomes the default when labeling new Volumes. Once a Volume
+has been created, it gets its own copy of the Pool defaults, and subsequently
+changing the Pool will have no effect on existing Volumes. You can either
+manually change the Volume values, or refresh them from the Pool defaults using
+the {\bf update volume} command in the Console. As an example
+of the use of one of the above, suppose your Pool resource contains:
+
+\footnotesize
+\begin{verbatim}
+Pool {
+ Name = File
+ Pool Type = Backup
+ Volume Use Duration = 23h
+}
+\end{verbatim}
+\normalsize
+
+then if you run a backup once a day (every 24 hours), Bacula will use a new
+Volume for each backup, because each Volume it writes can only be used for 23 hours
+after the first write. Note, setting the use duration to 23 hours is not a very
+good solution for tapes unless you have someone on-site during the weekends,
+because Bacula will want a new Volume and no one will be present to mount it,
+so no weekend backups will be done until Monday morning.
+
+\label{AutomaticLabeling}
+\subsection{Automatic Volume Labeling}
+\index[general]{Automatic Volume Labeling }
+\index[general]{Labeling!Automatic Volume }
+
+Use of the above records brings up another problem -- that of labeling your
+Volumes. For automated disk backup, you can either manually label each of your
+Volumes, or you can have Bacula automatically label new Volumes when they are
+needed. While, the automatic Volume labeling in version 1.30 and prior is a
+bit simplistic, but it does allow for automation, the features added in
+version 1.31 permit automatic creation of a wide variety of labels including
+information from environment variables and special Bacula Counter variables.
+In version 1.37 and later, it is probably much better to use Python scripting
+and the NewVolume event since generating Volume labels in a Python script is
+much easier than trying to figure out Counter variables. See the
+\ilink{Python Scripting}{PythonChapter} chapter of this manual for more
+details.
+
+Please note that automatic Volume labeling can also be used with tapes, but
+it is not nearly so practical since the tapes must be pre-mounted. This
+requires some user interaction. Automatic labeling from templates does NOT
+work with autochangers since Bacula will not access unknown slots. There
+are several methods of labeling all volumes in an autochanger magazine.
+For more information on this, please see the \ilink{
+Autochanger}{AutochangersChapter} chapter of this manual.
+
+Automatic Volume labeling is enabled by making a change to both the Pool
+resource (Director) and to the Device resource (Storage daemon) shown above.
+In the case of the Pool resource, you must provide Bacula with a label format
+that it will use to create new names. In the simplest form, the label format
+is simply the Volume name, to which Bacula will append a four digit number.
+This number starts at 0001 and is incremented for each Volume the catalog
+contains. Thus if you modify your Pool resource to be:
+
+\footnotesize
+\begin{verbatim}
+Pool {
+ Name = File
+ Pool Type = Backup
+ Volume Use Duration = 23h
+ LabelFormat = "Vol"
+}
+\end{verbatim}
+\normalsize
+
+Bacula will create Volume names Vol0001, Vol0002, and so on when new Volumes
+are needed. Much more complex and elaborate labels can be created using
+variable expansion defined in the
+\ilink{Variable Expansion}{VarsChapter} chapter of this manual.
+
+The second change that is necessary to make automatic labeling work is to give
+the Storage daemon permission to automatically label Volumes. Do so by adding
+{\bf LabelMedia = yes} to the Device resource as follows:
+
+\footnotesize
+\begin{verbatim}
+Device {
+ Name = File
+ Media Type = File
+ Archive Device = /home/bacula/backups
+ Random Access = Yes;
+ AutomaticMount = yes;
+ RemovableMedia = no;
+ AlwaysOpen = no;
+ LabelMedia = yes
+}
+\end{verbatim}
+\normalsize
+
+You can find more details of the {\bf Label Format} Pool record in
+\ilink{Label Format}{Label} description of the Pool resource
+records.
+
+\label{Recycling1}
+\subsection{Restricting the Number of Volumes and Recycling}
+\index[general]{Recycling!Restricting the Number of Volumes and Recycling}
+\index[general]{Restricting the Number of Volumes and Recycling}
+
+Automatic labeling discussed above brings up the problem of Volume management.
+With the above scheme, a new Volume will be created every day. If you have not
+specified Retention periods, your Catalog will continue to fill keeping track
+of all the files Bacula has backed up, and this procedure will create one new
+archive file (Volume) every day.
+
+The tools Bacula gives you to help automatically manage these problems are the
+following:
+
+\begin{enumerate}
+\item Catalog file record retention periods, the
+ \ilink{File Retention = ttt}{FileRetention} record in the Client
+ resource.
+\item Catalog job record retention periods, the
+ \ilink{Job Retention = ttt}{JobRetention} record in the Client
+ resource.
+\item The
+ \ilink{ AutoPrune = yes}{AutoPrune} record in the Client resource
+ to permit application of the above two retention periods.
+\item The
+ \ilink{ Volume Retention = ttt}{VolRetention} record in the Pool
+ resource.
+\item The
+ \ilink{ AutoPrune = yes}{PoolAutoPrune} record in the Pool
+ resource to permit application of the Volume retention period.
+\item The
+ \ilink{ Recycle = yes}{PoolRecycle} record in the Pool resource
+ to permit automatic recycling of Volumes whose Volume retention period has
+ expired.
+\item The
+ \ilink{ Recycle Oldest Volume = yes}{RecycleOldest} record in the
+ Pool resource tells Bacula to Prune the oldest volume in the Pool, and if all
+ files were pruned to recycle this volume and use it.
+\item The
+ \ilink{ Recycle Current Volume = yes}{RecycleCurrent} record in
+ the Pool resource tells Bacula to Prune the currently mounted volume in the
+ Pool, and if all files were pruned to recycle this volume and use it.
+\item The
+ \ilink{ Purge Oldest Volume = yes}{PurgeOldest} record in the
+ Pool resource permits a forced recycling of the oldest Volume when a new one
+ is needed. {\bf N.B. This record ignores retention periods! We highly
+ recommend not to use this record, but instead use Recycle Oldest Volume}
+\item The
+ \ilink{ Maximum Volumes = nnn}{MaxVolumes} record in the Pool
+ resource to limit the number of Volumes that can be created.
+\end{enumerate}
+
+The first three records (File Retention, Job Retention, and AutoPrune)
+determine the amount of time that Job and File records will remain in your
+Catalog, and they are discussed in detail in the
+\ilink{Automatic Volume Recycling}{RecyclingChapter} chapter of
+this manual.
+
+Volume Retention, AutoPrune, and Recycle determine how long Bacula will keep
+your Volumes before reusing them, and they are also discussed in detail in the
+\ilink{Automatic Volume Recycling}{RecyclingChapter} chapter of
+this manual.
+
+The Maximum Volumes record can also be used in conjunction with the Volume
+Retention period to limit the total number of archive Volumes (files) that
+Bacula will create. By setting an appropriate Volume Retention period, a
+Volume will be purged just before it is needed and thus Bacula can cycle
+through a fixed set of Volumes. Cycling through a fixed set of Volumes can
+also be done by setting {\bf Recycle Oldest Volume = yes} or {\bf Recycle
+Current Volume = yes}. In this case, when Bacula needs a new Volume, it will
+prune the specified volume.
+
+\label{ConcurrentDiskJobs}
+\section{Concurrent Disk Jobs}
+\index[general]{Concurrent Disk Jobs}
+Above, we discussed how you could have a single device named {\bf
+FileBackup} that writes to volumes in {\bf /home/bacula/backups}.
+You can, in fact, run multiple concurrent jobs using the
+Storage definition given with this example, and all the jobs will
+simultaneously write into the Volume that is being written.
+
+Now suppose you want to use multiple Pools, which means multiple
+Volumes, or suppose you want each client to have its own Volume
+and perhaps its own directory such as {\bf /home/bacula/client1}
+and {\bf /home/bacula/client2} ... With the single Storage and Device
+definition above, neither of these two is possible. Why? Because
+Bacula disk storage follows the same rules as tape devices. Only
+one Volume can be mounted on any Device at any time. If you want
+to simultaneously write multiple Volumes, you will need multiple
+Device resources in your bacula-sd.conf file, and thus multiple
+Storage resources in your bacula-dir.conf.
+
+OK, so now you should understand that you need multiple Device definitions
+in the case of different directories or different Pools, but you also
+need to know that the catalog data that Bacula keeps contains only
+the Media Type and not the specific storage device. This permits a tape
+for example to be re-read on any compatible tape drive. The compatibility
+being determined by the Media Type. The same applies to disk storage.
+Since a volume that is written by a Device in say directory {\bf
+/home/bacula/backups} cannot be read by a Device with an Archive Device
+definition of {\bf /home/bacula/client1}, you will not be able to
+restore all your files if you give both those devices
+{\bf Media Type = File}. During the restore, Bacula will simply choose
+the first available device, which may not be the correct one. If this
+is confusing, just remember that the Directory has only the Media Type
+and the Volume name. It does not know the {\bf Archive Device} (or the
+full path) that is specified in the Storage daemon. Thus you must
+explicitly tie your Volumes to the correct Device by using the Media Type.
+
+The example shown below shows a case where there are two clients, each
+using its own Pool and storing their Volumes in different directories.
+
+
+\label{Example2}
+\section{An Example}
+\index[general]{Example }
+
+The following example is not very practical, but can be used to demonstrate
+the proof of concept in a relatively short period of time. The example
+consists of a two clients that are backed up to a set of 12 archive files
+(Volumes) for each client into different directories on the Storage
+machine. Each Volume is used (written) only once, and there are four Full
+saves done every hour (so the whole thing cycles around after three hours).
+
+What is key here is that each physical device on the Storage daemon
+has a different Media Type. This allows the Director to choose the
+correct device for restores ...
+
+The Director's configuration file is as follows:
+
+\footnotesize
+\begin{verbatim}
+Director {
+ Name = my-dir
+ QueryFile = "~/bacula/bin/query.sql"
+ PidDirectory = "~/bacula/working"
+ WorkingDirectory = "~/bacula/working"
+ Password = dir_password
+}
+Schedule {
+ Name = "FourPerHour"
+ Run = Level=Full hourly at 0:05
+ Run = Level=Full hourly at 0:20
+ Run = Level=Full hourly at 0:35
+ Run = Level=Full hourly at 0:50
+}
+Job {
+ Name = "RecycleExample"
+ Type = Backup
+ Level = Full
+ Client = Rufus
+ FileSet= "Example FileSet"
+ Messages = Standard
+ Storage = FileStorage
+ Pool = Recycle
+ Schedule = FourPerHour
+}
+
+Job {
+ Name = "RecycleExample2"
+ Type = Backup
+ Level = Full
+ Client = Roxie
+ FileSet= "Example FileSet"
+ Messages = Standard
+ Storage = FileStorage1
+ Pool = Recycle1
+ Schedule = FourPerHour
+}
+
+FileSet {
+ Name = "Example FileSet"
+ Include = compression=GZIP signature=SHA1 {
+ /home/kern/bacula/bin
+ }
+}
+Client {
+ Name = Rufus
+ Address = rufus
+ Catalog = BackupDB
+ Password = client_password
+}
+
+Client {
+ Name = Roxie
+ Address = roxie
+ Catalog = BackupDB
+ Password = client1_password
+}
+
+Storage {
+ Name = FileStorage
+ Address = rufus
+ Password = local_storage_password
+ Device = RecycleDir
+ Media Type = File
+}
+
+Storage {
+ Name = FileStorage1
+ Address = rufus
+ Password = local_storage_password
+ Device = RecycleDir1
+ Media Type = File1
+}
+
+Catalog {
+ Name = BackupDB
+ dbname = bacula; user = bacula; password = ""
+}
+Messages {
+ Name = Standard
+ ...
+}
+Pool {
+ Name = Recycle
+ Use Volume Once = yes
+ Pool Type = Backup
+ LabelFormat = "Recycle-"
+ AutoPrune = yes
+ VolumeRetention = 2h
+ Maximum Volumes = 12
+ Recycle = yes
+}
+
+Pool {
+ Name = Recycle1
+ Use Volume Once = yes
+ Pool Type = Backup
+ LabelFormat = "Recycle1-"
+ AutoPrune = yes
+ VolumeRetention = 2h
+ Maximum Volumes = 12
+ Recycle = yes
+}
+
+\end{verbatim}
+\normalsize
+
+and the Storage daemon's configuration file is:
+
+\footnotesize
+\begin{verbatim}
+Storage {
+ Name = my-sd
+ WorkingDirectory = "~/bacula/working"
+ Pid Directory = "~/bacula/working"
+ MaximumConcurrentJobs = 10
+}
+Director {
+ Name = my-dir
+ Password = local_storage_password
+}
+Device {
+ Name = RecycleDir
+ Media Type = File
+ Archive Device = /home/bacula/backups
+ LabelMedia = yes;
+ Random Access = Yes;
+ AutomaticMount = yes;
+ RemovableMedia = no;
+ AlwaysOpen = no;
+}
+
+Device {
+ Name = RecycleDir1
+ Media Type = File1
+ Archive Device = /home/bacula/backups1
+ LabelMedia = yes;
+ Random Access = Yes;
+ AutomaticMount = yes;
+ RemovableMedia = no;
+ AlwaysOpen = no;
+}
+
+Messages {
+ Name = Standard
+ director = my-dir = all
+}
+\end{verbatim}
+\normalsize
+
+With a little bit of work, you can change the above example into a weekly or
+monthly cycle (take care about the amount of archive disk space used).
+
+\label{MultipleDisks}
+\section{Backing up to Multiple Disks}
+\index[general]{Disks!Backing up to Multiple }
+\index[general]{Backing up to Multiple Disks }
+
+Bacula can, of course, use multiple disks, but in general, each disk must be a
+separate Device specification in the Storage daemon's conf file, and you must
+then select what clients to backup to each disk. You will also want to
+give each Device specification a different Media Type so that during
+a restore, Bacula will be able to find the appropriate drive.
+
+The situation is a bit more complicated if you want to treat two different
+physical disk drives (or partitions) logically as a single drive, which
+Bacula does not directly support. However, it is possible to back up your
+data to multiple disks as if they were a single drive by linking the
+Volumes from the first disk to the second disk.
+
+For example, assume that you have two disks named {\bf /disk1} and {\bf
+/disk2}. If you then create a standard Storage daemon Device resource for
+backing up to the first disk, it will look like the following:
+
+\footnotesize
+\begin{verbatim}
+Device {
+ Name = client1
+ Media Type = File
+ Archive Device = /disk1
+ LabelMedia = yes;
+ Random Access = Yes;
+ AutomaticMount = yes;
+ RemovableMedia = no;
+ AlwaysOpen = no;
+}
+\end{verbatim}
+\normalsize
+
+Since there is no way to get the above Device resource to reference both {\bf
+/disk1} and {\bf /disk2} we do it by pre-creating Volumes on /disk2 with the
+following:
+
+\footnotesize
+\begin{verbatim}
+ln -s /disk2/Disk2-vol001 /disk1/Disk2-vol001
+ln -s /disk2/Disk2-vol002 /disk1/Disk2-vol002
+ln -s /disk2/Disk2-vol003 /disk1/Disk2-vol003
+...
+\end{verbatim}
+\normalsize
+
+At this point, you can label the Volumes as Volume {\bf Disk2-vol001}, {\bf
+Disk2-vol002}, ... and Bacula will use them as if they were on /disk1 but
+actually write the data to /disk2. The only minor inconvenience with this
+method is that you must explicitly name the disks and cannot use automatic
+labeling unless you arrange to have the labels exactly match the links you
+have created.
+
+An important thing to know is that Bacula treats disks like tape drives
+as much as it can. This means that you can only have a single Volume
+mounted at one time on a disk as defined in your Device resource in
+the Storage daemon's conf file. You can have multiple concurrent
+jobs running that all write to the one Volume that is being used, but
+if you want to have multiple concurrent jobs that are writing to
+separate disks drives (or partitions), you will need to define
+separate Device resources for each one, exactly as you would do for
+two different tape drives. There is one fundamental difference, however.
+The Volumes that you create on the two drives cannot be easily exchanged
+as they can for a tape drive, because they are physically resident (already
+mounted in a sense) on the particular drive. As a consequence, you will
+probably want to give them different Media Types so that Bacula can
+distinguish what Device resource to use during a restore.
+An example would be the following:
+
+\footnotesize
+\begin{verbatim}
+Device {
+ Name = Disk1
+ Media Type = File1
+ Archive Device = /disk1
+ LabelMedia = yes;
+ Random Access = Yes;
+ AutomaticMount = yes;
+ RemovableMedia = no;
+ AlwaysOpen = no;
+}
+
+Device {
+ Name = Disk2
+ Media Type = File2
+ Archive Device = /disk2
+ LabelMedia = yes;
+ Random Access = Yes;
+ AutomaticMount = yes;
+ RemovableMedia = no;
+ AlwaysOpen = no;
+}
+\end{verbatim}
+\normalsize
+
+With the above device definitions, you can run two concurrent
+jobs each writing at the same time, one to {\bf /disk2} and the
+other to {\bf /disk2}. The fact that you have given them different
+Media Types will allow Bacula to quickly choose the correct
+Storage resource in the Director when doing a restore.
+
+\label{MultipleClients}
+\section{Considerations for Multiple Clients}
+\index[general]{Clients!Considerations for Multiple }
+\index[general]{Multiple Clients}
+
+If we take the above example and add a second Client, here are a few
+considerations:
+
+\begin{itemize}
+\item Although the second client can write to the same set of Volumes, you
+ will probably want to write to a different set.
+\item You can write to a different set of Volumes by defining a second Pool,
+ which has a different name and a different {\bf LabelFormat}.
+\item If you wish the Volumes for the second client to go into a different
+ directory (perhaps even on a different filesystem to spread the load), you
+ would do so by defining a second Device resource in the Storage daemon. The
+{\bf Name} must be different, and the {\bf Archive Device} could be
+different. To ensure that Volumes are never mixed from one pool to another,
+you might also define a different MediaType (e.g. {\bf File1}).
+\end{itemize}
+
+In this example, we have two clients, each with a different Pool and a
+different number of archive files retained. They also write to different
+directories with different Volume labeling.
+
+The Director's configuration file is as follows:
+
+\footnotesize
+\begin{verbatim}
+Director {
+ Name = my-dir
+ QueryFile = "~/bacula/bin/query.sql"
+ PidDirectory = "~/bacula/working"
+ WorkingDirectory = "~/bacula/working"
+ Password = dir_password
+}
+# Basic weekly schedule
+Schedule {
+ Name = "WeeklySchedule"
+ Run = Level=Full fri at 1:30
+ Run = Level=Incremental sat-thu at 1:30
+}
+FileSet {
+ Name = "Example FileSet"
+ Include = compression=GZIP signature=SHA1 {
+ /home/kern/bacula/bin
+ }
+}
+Job {
+ Name = "Backup-client1"
+ Type = Backup
+ Level = Full
+ Client = client1
+ FileSet= "Example FileSet"
+ Messages = Standard
+ Storage = File1
+ Pool = client1
+ Schedule = "WeeklySchedule"
+}
+Job {
+ Name = "Backup-client2"
+ Type = Backup
+ Level = Full
+ Client = client2
+ FileSet= "Example FileSet"
+ Messages = Standard
+ Storage = File2
+ Pool = client2
+ Schedule = "WeeklySchedule"
+}
+Client {
+ Name = client1
+ Address = client1
+ Catalog = BackupDB
+ Password = client1_password
+ File Retention = 7d
+}
+Client {
+ Name = client2
+ Address = client2
+ Catalog = BackupDB
+ Password = client2_password
+}
+# Two Storage definitions with different Media Types
+# permits different directories
+Storage {
+ Name = File1
+ Address = rufus
+ Password = local_storage_password
+ Device = client1
+ Media Type = File1
+}
+Storage {
+ Name = File2
+ Address = rufus
+ Password = local_storage_password
+ Device = client2
+ Media Type = File2
+}
+Catalog {
+ Name = BackupDB
+ dbname = bacula; user = bacula; password = ""
+}
+Messages {
+ Name = Standard
+ ...
+}
+# Two pools permits different cycling periods and Volume names
+# Cycle through 15 Volumes (two weeks)
+Pool {
+ Name = client1
+ Use Volume Once = yes
+ Pool Type = Backup
+ LabelFormat = "Client1-"
+ AutoPrune = yes
+ VolumeRetention = 13d
+ Maximum Volumes = 15
+ Recycle = yes
+}
+# Cycle through 8 Volumes (1 week)
+Pool {
+ Name = client2
+ Use Volume Once = yes
+ Pool Type = Backup
+ LabelFormat = "Client2-"
+ AutoPrune = yes
+ VolumeRetention = 6d
+ Maximum Volumes = 8
+ Recycle = yes
+}
+\end{verbatim}
+\normalsize
+
+and the Storage daemon's configuration file is:
+
+\footnotesize
+\begin{verbatim}
+Storage {
+ Name = my-sd
+ WorkingDirectory = "~/bacula/working"
+ Pid Directory = "~/bacula/working"
+ MaximumConcurrentJobs = 10
+}
+Director {
+ Name = my-dir
+ Password = local_storage_password
+}
+# Archive directory for Client1
+Device {
+ Name = client1
+ Media Type = File1
+ Archive Device = /home/bacula/client1
+ LabelMedia = yes;
+ Random Access = Yes;
+ AutomaticMount = yes;
+ RemovableMedia = no;
+ AlwaysOpen = no;
+}
+# Archive directory for Client2
+Device {
+ Name = client2
+ Media Type = File2
+ Archive Device = /home/bacula/client2
+ LabelMedia = yes;
+ Random Access = Yes;
+ AutomaticMount = yes;
+ RemovableMedia = no;
+ AlwaysOpen = no;
+}
+Messages {
+ Name = Standard
+ director = my-dir = all
+}
+\end{verbatim}
+\normalsize
--- /dev/null
+#
+# Avoid that @VERSION@ and @DATE@ are changed by configure
+# This file is sourced by update_version
+#
+echo "s%@VERSION@%${VERSION}%g" >${out}
+echo "s%@DATE@%${DATE}%g" >>${out}
--- /dev/null
+%%
+%%
+
+\chapter{DVD Volumes}
+\label{_DVDChapterStart}
+\index[general]{DVD Volumes}
+\index[general]{Writing DVDs}
+\index[general]{DVD Writing}
+\index[general]{Volumes!DVD}
+
+Bacula allows you to specify that you want to write to DVD. However,
+this feature is implemented only in version 1.37 or later.
+You may in fact write to DVD+RW, DVD+R, DVD-R, or DVD-RW
+media. The actual process used by Bacula is to first write
+the image to a spool directory, then when the Volume reaches
+a certain size or, at your option, at the end of a Job, Bacula
+will transfer the image from the spool directory to the
+DVD. The actual work of transferring the image is done
+by a script {\bf dvd-handler}, and the heart of that
+script is a program called {\bf growisofs} which allows
+creating or adding to a DVD ISO filesystem.
+
+You must have {\bf dvd+rw-tools} loaded on your system for DVD writing to
+work. Please note that the original {\bf dvd+rw-tools} package does {\bf
+NOT} work with Bacula. You must apply a patch which can be found in the
+{\bf patches} directory of Bacula sources with the name
+{\bf dvd+rw-tools-5.21.4.10.8.bacula.patch} for version 5.21 of the tools,
+or patch {bf dvd+rw-tools-6.1.bacula.patch} if you have version 6.1
+on your system. Unfortunately, this requires you to build the dvd\_rw-tools
+from source.
+
+Note, some Linux distros such as Debian dvd+rw-tools-7.0-4 package already
+have the patch applied, so please check.
+
+The fact that Bacula cannot use the OS to write directly
+to the DVD makes the whole process a bit more error prone than
+writing to a disk or a tape, but nevertheless, it does work if you
+use some care to set it up properly. However, at the current time
+(version 1.39.30 -- 12 December 2006) we still consider this code to be
+BETA quality. As a consequence, please do careful testing before relying
+on DVD backups in production.
+
+The remainder of this chapter explains the various directives that you can
+use to control the DVD writing.
+
+\label{DVDdirectives}
+\section{DVD Specific SD Directives}
+\index[general]{Directives!DVD}
+\index[general]{DVD Specific SD Directives }
+
+The following directives are added to the Storage daemon's
+Device resource.
+
+\begin{description}
+
+\item [Requires Mount = {\it Yes|No}]
+ \index[sd]{Requires Mount }
+ You must set this directive to {\bf yes} for DVD-writers, and to {\bf no} for
+ all other devices (tapes/files). This directive indicates if the device
+ requires to be mounted using the {\bf Mount Command}.
+ To be able to write a DVD, the following directives must also be
+ defined: {\bf Mount Point}, {\bf Mount Command}, {\bf Unmount Command} and
+ {\bf Write Part Command}.
+
+\item [Mount Point = {\it directory}]
+ \index[sd]{Mount Point}
+ Directory where the device can be mounted.
+
+\item [Mount Command = {\it name-string}]
+ \index[sd]{Mount Command}
+ Command that must be executed to mount the device. Although the
+ device is written directly, the mount command is necessary in
+ order to determine the free space left on the DVD. Before the command is
+ executed, \%a is replaced with the Archive Device, and \%m with the Mount
+ Point.
+
+ Most frequently, you will define it as follows:
+
+\footnotesize
+\begin{verbatim}
+ Mount Command = "/bin/mount -t iso9660 -o ro %a %m"
+\end{verbatim}
+\normalsize
+
+However, if you have defined a mount point in /etc/fstab, you might be
+able to use a mount command such as:
+
+\footnotesize
+\begin{verbatim}
+ Mount Command = "/bin/mount /media/dvd"
+\end{verbatim}
+\normalsize
+
+
+\item [Unmount Command = {\it name-string}]
+ \index[sd]{Unmount Command}
+ Command that must be executed to unmount the device. Before the command is
+ executed, \%a is replaced with the Archive Device, and \%m with the Mount
+ Point.
+
+ Most frequently, you will define it as follows:
+
+\footnotesize
+\begin{verbatim}
+ Unmount Command = "/bin/umount %m"
+\end{verbatim}
+\normalsize
+
+\item [Write Part Command = {\it name-string}]
+ \index[sd]{Write Part Command }
+ Command that must be executed to write a part to the device. Before the
+ command is executed, \%a is replaced with the Archive Device, \%m with the
+ Mount Point, \%e is replaced with 1 if we are writing the first part,
+ and with 0 otherwise, and \%v with the current part filename.
+
+ For a DVD, you will most frequently specify the Bacula supplied {\bf
+ dvd-handler} script as follows:
+
+\footnotesize
+\begin{verbatim}
+ Write Part Command = "/path/dvd-handler %a write %e %v"
+\end{verbatim}
+\normalsize
+
+ Where {\bf /path} is the path to your scripts install directory, and
+ dvd-handler is the Bacula supplied script file.
+ This command will already be present, but commented out,
+ in the default bacula-sd.conf file. To use it, simply remove
+ the comment (\#) symbol.
+
+
+\item [Free Space Command = {\it name-string}]
+ \index[sd]{Free Space Command }
+ Command that must be executed to check how much free space is left on the
+ device. Before the command is executed,\%a is replaced with the Archive
+ Device.
+
+ For a DVD, you will most frequently specify the Bacula supplied {\bf
+ dvd-handler} script as follows:
+
+\footnotesize
+\begin{verbatim}
+ Free Space Command = "/path/dvd-handler %a free"
+\end{verbatim}
+\normalsize
+
+ Where {\bf /path} is the path to your scripts install directory, and
+ dvd-freespace is the Bacula supplied script file.
+ If you want to specify your own command, please look at the code in
+ dvd-handler to see what output Bacula expects from this command.
+ This command will already be present, but commented out,
+ in the default bacula-sd.conf file. To use it, simply remove
+ the comment (\#) symbol.
+
+ If you do not set it, Bacula will expect there is always free space on the
+ device.
+
+\end{description}
+
+In addition to the directives specified above, you must also
+specify the other standard Device resource directives. Please see the
+sample DVD Device resource in the default bacula-sd.conf file. Be sure
+to specify the raw device name for {\bf Archive Device}. It should
+be a name such as {\bf /dev/cdrom} or {\bf /media/cdrecorder} or
+{\bf /dev/dvd} depending on your system. It will not be a name such
+as {\bf /mnt/cdrom}.
+
+Finally, for {\bf growisofs} to work, it must be able to lock
+a certain amount of memory in RAM. If you have restrictions on
+this function, you may have failures. Under {\bf bash}, you can
+set this with the following command:
+
+\footnotesize
+\begin{verbatim}
+ulimit -l unlimited
+\end{verbatim}
+\normalsize
+
+\section{Edit Codes for DVD Directives}
+\index[general]{Directives!DVD Edit Codes}
+\index[general]{Edit Codes for DVD Directives }
+
+Before submitting the {\bf Mount Command}, {\bf Unmount Command},
+{\bf Write Part Command}, or {\bf Free Space Command} directives
+to the operating system, Bacula performs character substitution of the
+following characters:
+
+\footnotesize
+\begin{verbatim}
+ %% = %
+ %a = Archive device name
+ %e = erase (set if cannot mount and first part)
+ %n = part number
+ %m = mount point
+ %v = last part name (i.e. filename)
+\end{verbatim}
+\normalsize
+
+
+
+\section{DVD Specific Director Directives}
+\index[general]{Directives!DVD}
+\index[general]{DVD Specific Director Directives }
+
+The following directives are added to the Director's Job resource.
+
+\label{WritePartAfterJob}
+\begin{description}
+\item [Write Part After Job = \lt{}yes|no\gt{}]
+ \index[dir]{Write Part After Job }
+ If this directive is set to {\bf yes} (default {\bf no}), the
+ Volume written to a temporary spool file for the current Job will
+ be written to the DVD as a new part file
+ will be created after the job is finished.
+
+ It should be set to {\bf yes} when writing to devices that require a mount
+ (for example DVD), so you are sure that the current part, containing
+ this job's data, is written to the device, and that no data is left in
+ the temporary file on the hard disk. However, on some media, like DVD+R
+ and DVD-R, a lot of space (about 10Mb) is lost everytime a part is
+ written. So, if you run several jobs each after another, you could set
+ this directive to {\bf no} for all jobs, except the last one, to avoid
+ wasting too much space, but to ensure that the data is written to the
+ medium when all jobs are finished.
+
+ This directive is ignored for devices other than DVDs.
+\end{description}
+
+
+
+\label{DVDpoints}
+\section{Other Points}
+\index[general]{Points!Other }
+\index[general]{Other Points }
+
+\begin{itemize}
+\item Please be sure that you have any automatic DVD mounting
+ disabled before running Bacula -- this includes auto mounting
+ in /etc/fstab, hotplug, ... If the DVD is automatically
+ mounted by the OS, it will cause problems when Bacula tries
+ to mount/unmount the DVD.
+\item Please be sure that you the directive {\bf Write Part After Job}
+ set to {\bf yes}, otherwise the last part of the data to be
+ written will be left in the DVD spool file and not written to
+ the DVD. The DVD will then be unreadable until this last part
+ is written. If you have a series of jobs that are run one at
+ a time, you can turn this off until the last job is run.
+\item The current code is not designed to have multiple simultaneous
+ jobs writing to the DVD. As a consequence, please ensure that
+ only one DVD backup job runs at any time.
+\item Writing and reading of DVD+RW seems to work quite reliably
+ provided you are using the patched dvd+rw-mediainfo programs.
+ On the other hand, we do not have enough information to ensure
+ that DVD-RW or other forms of DVDs work correctly.
+\item DVD+RW supports only about 1000 overwrites. Every time you
+ mount the filesystem read/write will count as one write. This can
+ add up quickly, so it is best to mount your DVD+RW filesystem read-only.
+ Bacula does not need the DVD to be mounted read-write, since it uses
+ the raw device for writing.
+\item Reformatting DVD+RW 10-20 times can apparently make the medium
+ unusable. Normally you should not have to format or reformat
+ DVD+RW media. If it is necessary, current versions of growisofs will
+ do so automatically.
+\item We have had several problems writing to DVD-RWs (this does NOT
+ concern DVD+RW), because these media have two writing-modes: {\bf
+ Incremental Sequential} and {\bf Restricted Overwrite}. Depending on
+ your device and the media you use, one of these modes may not work
+ correctly (e.g. {\bf Incremental Sequential} does not work with my NEC
+ DVD-writer and Verbatim DVD-RW).
+
+ To retrieve the current mode of a DVD-RW, run:
+\begin{verbatim}
+ dvd+rw-mediainfo /dev/xxx
+\end{verbatim}
+ where you replace xxx with your DVD device name.
+
+ {\bf Mounted Media} line should give you the information.
+
+ To set the device to {\bf Restricted Overwrite} mode, run:
+\begin{verbatim}
+ dvd+rw-format /dev/xxx
+\end{verbatim}
+ If you want to set it back to the default {\bf Incremental Sequential} mode, run:
+\begin{verbatim}
+ dvd+rw-format -blank /dev/xxx
+\end{verbatim}
+
+\item Bacula only accepts to write to blank DVDs. To quickly blank a DVD+/-RW, run
+ this command:
+\begin{verbatim}
+ dd if=/dev/zero bs=1024 count=512 | growisofs -Z /dev/xxx=/dev/fd/0
+\end{verbatim}
+ Then, try to mount the device, if it cannot be mounted, it will be considered
+ as blank by Bacula, if it can be mounted, try a full blank (see below).
+
+\item If you wish to blank completely a DVD+/-RW, use the following:
+\begin{verbatim}
+ growisofs -Z /dev/xxx=/dev/zero
+\end{verbatim}
+ where you replace xxx with your DVD device name. However, note that this
+ blanks the whole DVD, which takes quite a long time (16 minutes on mine).
+\item DVD+RW and DVD-RW support only about 1000 overwrites (i.e. don't use the
+same medium for years if you don't want to have problems...).
+
+To write to the DVD the first time use:
+\begin{verbatim}
+ growisofs -Z /dev/xxx filename
+\end{verbatim}
+
+To add additional files (more parts use):
+
+\begin{verbatim}
+ growisofs -M /dev/xxx filename
+\end{verbatim}
+
+The option {\bf -use-the-force-luke=4gms} was added in growisofs 5.20 to
+override growisofs' behavior of always checking for the 4GB limit.
+Normally, this option is recommended for all Linux 2.6.8 kernels or
+greater, since these newer kernels can handle writing more than 4GB.
+See below for more details on this subject.
+
+\item For more information about DVD writing, please look at the
+\elink{dvd+rw-tools homepage}{http://fy.chalmers.se/~appro/linux/DVD+RW/}.
+
+\item According to bug \#912, bscan cannot read multi-volume DVDs. This is
+on our TODO list, but unless someone submits a patch it is not likely to be
+done any time in the near future. (9 Sept 2007).
+
+\end{itemize}
--- /dev/null
+% TODO: maybe get rid of centering
+
+\chapter{GNU Free Documentation License}
+\index[general]{GNU Free Documentation License}
+\index[general]{License!GNU Free Documentation}
+
+\label{label_fdl}
+
+ \begin{center}
+
+ Version 1.2, November 2002
+
+
+ Copyright \copyright 2000,2001,2002 Free Software Foundation, Inc.
+
+ \bigskip
+
+ 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
+
+ \bigskip
+
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+\end{center}
+
+
+\begin{center}
+{\bf\large Preamble}
+\end{center}
+
+The purpose of this License is to make a manual, textbook, or other
+functional and useful document "free" in the sense of freedom: to
+assure everyone the effective freedom to copy and redistribute it,
+with or without modifying it, either commercially or noncommercially.
+Secondarily, this License preserves for the author and publisher a way
+to get credit for their work, while not being considered responsible
+for modifications made by others.
+
+This License is a kind of "copyleft", which means that derivative
+works of the document must themselves be free in the same sense. It
+complements the GNU General Public License, which is a copyleft
+license designed for free software.
+
+We have designed this License in order to use it for manuals for free
+software, because free software needs free documentation: a free
+program should come with manuals providing the same freedoms that the
+software does. But this License is not limited to software manuals;
+it can be used for any textual work, regardless of subject matter or
+whether it is published as a printed book. We recommend this License
+principally for works whose purpose is instruction or reference.
+
+
+\begin{center}
+{\Large\bf 1. APPLICABILITY AND DEFINITIONS}
+\end{center}
+
+This License applies to any manual or other work, in any medium, that
+contains a notice placed by the copyright holder saying it can be
+distributed under the terms of this License. Such a notice grants a
+world-wide, royalty-free license, unlimited in duration, to use that
+work under the conditions stated herein. The \textbf{"Document"}, below,
+refers to any such manual or work. Any member of the public is a
+licensee, and is addressed as \textbf{"you"}. You accept the license if you
+copy, modify or distribute the work in a way requiring permission
+under copyright law.
+
+A \textbf{"Modified Version"} of the Document means any work containing the
+Document or a portion of it, either copied verbatim, or with
+modifications and/or translated into another language.
+
+A \textbf{"Secondary Section"} is a named appendix or a front-matter section of
+the Document that deals exclusively with the relationship of the
+publishers or authors of the Document to the Document's overall subject
+(or to related matters) and contains nothing that could fall directly
+within that overall subject. (Thus, if the Document is in part a
+textbook of mathematics, a Secondary Section may not explain any
+mathematics.) The relationship could be a matter of historical
+connection with the subject or with related matters, or of legal,
+commercial, philosophical, ethical or political position regarding
+them.
+
+The \textbf{"Invariant Sections"} are certain Secondary Sections whose titles
+are designated, as being those of Invariant Sections, in the notice
+that says that the Document is released under this License. If a
+section does not fit the above definition of Secondary then it is not
+allowed to be designated as Invariant. The Document may contain zero
+Invariant Sections. If the Document does not identify any Invariant
+Sections then there are none.
+
+The \textbf{"Cover Texts"} are certain short passages of text that are listed,
+as Front-Cover Texts or Back-Cover Texts, in the notice that says that
+the Document is released under this License. A Front-Cover Text may
+be at most 5 words, and a Back-Cover Text may be at most 25 words.
+
+A \textbf{"Transparent"} copy of the Document means a machine-readable copy,
+represented in a format whose specification is available to the
+general public, that is suitable for revising the document
+straightforwardly with generic text editors or (for images composed of
+pixels) generic paint programs or (for drawings) some widely available
+drawing editor, and that is suitable for input to text formatters or
+for automatic translation to a variety of formats suitable for input
+to text formatters. A copy made in an otherwise Transparent file
+format whose markup, or absence of markup, has been arranged to thwart
+or discourage subsequent modification by readers is not Transparent.
+An image format is not Transparent if used for any substantial amount
+of text. A copy that is not "Transparent" is called \textbf{"Opaque"}.
+
+Examples of suitable formats for Transparent copies include plain
+ASCII without markup, Texinfo input format, LaTeX input format, SGML
+or XML using a publicly available DTD, and standard-conforming simple
+HTML, PostScript or PDF designed for human modification. Examples of
+transparent image formats include PNG, XCF and JPG. Opaque formats
+include proprietary formats that can be read and edited only by
+proprietary word processors, SGML or XML for which the DTD and/or
+processing tools are not generally available, and the
+machine-generated HTML, PostScript or PDF produced by some word
+processors for output purposes only.
+
+The \textbf{"Title Page"} means, for a printed book, the title page itself,
+plus such following pages as are needed to hold, legibly, the material
+this License requires to appear in the title page. For works in
+formats which do not have any title page as such, "Title Page" means
+the text near the most prominent appearance of the work's title,
+preceding the beginning of the body of the text.
+
+A section \textbf{"Entitled XYZ"} means a named subunit of the Document whose
+title either is precisely XYZ or contains XYZ in parentheses following
+text that translates XYZ in another language. (Here XYZ stands for a
+specific section name mentioned below, such as \textbf{"Acknowledgements"},
+\textbf{"Dedications"}, \textbf{"Endorsements"}, or \textbf{"History"}.)
+To \textbf{"Preserve the Title"}
+of such a section when you modify the Document means that it remains a
+section "Entitled XYZ" according to this definition.
+
+The Document may include Warranty Disclaimers next to the notice which
+states that this License applies to the Document. These Warranty
+Disclaimers are considered to be included by reference in this
+License, but only as regards disclaiming warranties: any other
+implication that these Warranty Disclaimers may have is void and has
+no effect on the meaning of this License.
+
+
+\begin{center}
+{\Large\bf 2. VERBATIM COPYING}
+\end{center}
+
+You may copy and distribute the Document in any medium, either
+commercially or noncommercially, provided that this License, the
+copyright notices, and the license notice saying this License applies
+to the Document are reproduced in all copies, and that you add no other
+conditions whatsoever to those of this License. You may not use
+technical measures to obstruct or control the reading or further
+copying of the copies you make or distribute. However, you may accept
+compensation in exchange for copies. If you distribute a large enough
+number of copies you must also follow the conditions in section 3.
+
+You may also lend copies, under the same conditions stated above, and
+you may publicly display copies.
+
+
+\begin{center}
+{\Large\bf 3. COPYING IN QUANTITY}
+\end{center}
+
+
+If you publish printed copies (or copies in media that commonly have
+printed covers) of the Document, numbering more than 100, and the
+Document's license notice requires Cover Texts, you must enclose the
+copies in covers that carry, clearly and legibly, all these Cover
+Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
+the back cover. Both covers must also clearly and legibly identify
+you as the publisher of these copies. The front cover must present
+the full title with all words of the title equally prominent and
+visible. You may add other material on the covers in addition.
+Copying with changes limited to the covers, as long as they preserve
+the title of the Document and satisfy these conditions, can be treated
+as verbatim copying in other respects.
+
+If the required texts for either cover are too voluminous to fit
+legibly, you should put the first ones listed (as many as fit
+reasonably) on the actual cover, and continue the rest onto adjacent
+pages.
+
+If you publish or distribute Opaque copies of the Document numbering
+more than 100, you must either include a machine-readable Transparent
+copy along with each Opaque copy, or state in or with each Opaque copy
+a computer-network location from which the general network-using
+public has access to download using public-standard network protocols
+a complete Transparent copy of the Document, free of added material.
+If you use the latter option, you must take reasonably prudent steps,
+when you begin distribution of Opaque copies in quantity, to ensure
+that this Transparent copy will remain thus accessible at the stated
+location until at least one year after the last time you distribute an
+Opaque copy (directly or through your agents or retailers) of that
+edition to the public.
+
+It is requested, but not required, that you contact the authors of the
+Document well before redistributing any large number of copies, to give
+them a chance to provide you with an updated version of the Document.
+
+
+\begin{center}
+{\Large\bf 4. MODIFICATIONS}
+\end{center}
+
+You may copy and distribute a Modified Version of the Document under
+the conditions of sections 2 and 3 above, provided that you release
+the Modified Version under precisely this License, with the Modified
+Version filling the role of the Document, thus licensing distribution
+and modification of the Modified Version to whoever possesses a copy
+of it. In addition, you must do these things in the Modified Version:
+
+\begin{itemize}
+\item[A.]
+ Use in the Title Page (and on the covers, if any) a title distinct
+ from that of the Document, and from those of previous versions
+ (which should, if there were any, be listed in the History section
+ of the Document). You may use the same title as a previous version
+ if the original publisher of that version gives permission.
+
+\item[B.]
+ List on the Title Page, as authors, one or more persons or entities
+ responsible for authorship of the modifications in the Modified
+ Version, together with at least five of the principal authors of the
+ Document (all of its principal authors, if it has fewer than five),
+ unless they release you from this requirement.
+
+\item[C.]
+ State on the Title page the name of the publisher of the
+ Modified Version, as the publisher.
+
+\item[D.]
+ Preserve all the copyright notices of the Document.
+
+\item[E.]
+ Add an appropriate copyright notice for your modifications
+ adjacent to the other copyright notices.
+
+\item[F.]
+ Include, immediately after the copyright notices, a license notice
+ giving the public permission to use the Modified Version under the
+ terms of this License, in the form shown in the Addendum below.
+
+\item[G.]
+ Preserve in that license notice the full lists of Invariant Sections
+ and required Cover Texts given in the Document's license notice.
+
+\item[H.]
+ Include an unaltered copy of this License.
+
+\item[I.]
+ Preserve the section Entitled "History", Preserve its Title, and add
+ to it an item stating at least the title, year, new authors, and
+ publisher of the Modified Version as given on the Title Page. If
+ there is no section Entitled "History" in the Document, create one
+ stating the title, year, authors, and publisher of the Document as
+ given on its Title Page, then add an item describing the Modified
+ Version as stated in the previous sentence.
+
+\item[J.]
+ Preserve the network location, if any, given in the Document for
+ public access to a Transparent copy of the Document, and likewise
+ the network locations given in the Document for previous versions
+ it was based on. These may be placed in the "History" section.
+ You may omit a network location for a work that was published at
+ least four years before the Document itself, or if the original
+ publisher of the version it refers to gives permission.
+
+\item[K.]
+ For any section Entitled "Acknowledgements" or "Dedications",
+ Preserve the Title of the section, and preserve in the section all
+ the substance and tone of each of the contributor acknowledgements
+ and/or dedications given therein.
+
+\item[L.]
+ Preserve all the Invariant Sections of the Document,
+ unaltered in their text and in their titles. Section numbers
+ or the equivalent are not considered part of the section titles.
+
+\item[M.]
+ Delete any section Entitled "Endorsements". Such a section
+ may not be included in the Modified Version.
+
+\item[N.]
+ Do not retitle any existing section to be Entitled "Endorsements"
+ or to conflict in title with any Invariant Section.
+
+\item[O.]
+ Preserve any Warranty Disclaimers.
+\end{itemize}
+
+If the Modified Version includes new front-matter sections or
+appendices that qualify as Secondary Sections and contain no material
+copied from the Document, you may at your option designate some or all
+of these sections as invariant. To do this, add their titles to the
+list of Invariant Sections in the Modified Version's license notice.
+These titles must be distinct from any other section titles.
+
+You may add a section Entitled "Endorsements", provided it contains
+nothing but endorsements of your Modified Version by various
+parties--for example, statements of peer review or that the text has
+been approved by an organization as the authoritative definition of a
+standard.
+
+You may add a passage of up to five words as a Front-Cover Text, and a
+passage of up to 25 words as a Back-Cover Text, to the end of the list
+of Cover Texts in the Modified Version. Only one passage of
+Front-Cover Text and one of Back-Cover Text may be added by (or
+through arrangements made by) any one entity. If the Document already
+includes a cover text for the same cover, previously added by you or
+by arrangement made by the same entity you are acting on behalf of,
+you may not add another; but you may replace the old one, on explicit
+permission from the previous publisher that added the old one.
+
+The author(s) and publisher(s) of the Document do not by this License
+give permission to use their names for publicity for or to assert or
+imply endorsement of any Modified Version.
+
+
+\begin{center}
+{\Large\bf 5. COMBINING DOCUMENTS}
+\end{center}
+
+
+You may combine the Document with other documents released under this
+License, under the terms defined in section 4 above for modified
+versions, provided that you include in the combination all of the
+Invariant Sections of all of the original documents, unmodified, and
+list them all as Invariant Sections of your combined work in its
+license notice, and that you preserve all their Warranty Disclaimers.
+
+The combined work need only contain one copy of this License, and
+multiple identical Invariant Sections may be replaced with a single
+copy. If there are multiple Invariant Sections with the same name but
+different contents, make the title of each such section unique by
+adding at the end of it, in parentheses, the name of the original
+author or publisher of that section if known, or else a unique number.
+Make the same adjustment to the section titles in the list of
+Invariant Sections in the license notice of the combined work.
+
+In the combination, you must combine any sections Entitled "History"
+in the various original documents, forming one section Entitled
+"History"; likewise combine any sections Entitled "Acknowledgements",
+and any sections Entitled "Dedications". You must delete all sections
+Entitled "Endorsements".
+
+\begin{center}
+{\Large\bf 6. COLLECTIONS OF DOCUMENTS}
+\end{center}
+
+You may make a collection consisting of the Document and other documents
+released under this License, and replace the individual copies of this
+License in the various documents with a single copy that is included in
+the collection, provided that you follow the rules of this License for
+verbatim copying of each of the documents in all other respects.
+
+You may extract a single document from such a collection, and distribute
+it individually under this License, provided you insert a copy of this
+License into the extracted document, and follow this License in all
+other respects regarding verbatim copying of that document.
+
+
+\begin{center}
+{\Large\bf 7. AGGREGATION WITH INDEPENDENT WORKS}
+\end{center}
+
+
+A compilation of the Document or its derivatives with other separate
+and independent documents or works, in or on a volume of a storage or
+distribution medium, is called an "aggregate" if the copyright
+resulting from the compilation is not used to limit the legal rights
+of the compilation's users beyond what the individual works permit.
+When the Document is included in an aggregate, this License does not
+apply to the other works in the aggregate which are not themselves
+derivative works of the Document.
+
+If the Cover Text requirement of section 3 is applicable to these
+copies of the Document, then if the Document is less than one half of
+the entire aggregate, the Document's Cover Texts may be placed on
+covers that bracket the Document within the aggregate, or the
+electronic equivalent of covers if the Document is in electronic form.
+Otherwise they must appear on printed covers that bracket the whole
+aggregate.
+
+
+\begin{center}
+{\Large\bf 8. TRANSLATION}
+\end{center}
+
+
+Translation is considered a kind of modification, so you may
+distribute translations of the Document under the terms of section 4.
+Replacing Invariant Sections with translations requires special
+permission from their copyright holders, but you may include
+translations of some or all Invariant Sections in addition to the
+original versions of these Invariant Sections. You may include a
+translation of this License, and all the license notices in the
+Document, and any Warranty Disclaimers, provided that you also include
+the original English version of this License and the original versions
+of those notices and disclaimers. In case of a disagreement between
+the translation and the original version of this License or a notice
+or disclaimer, the original version will prevail.
+
+If a section in the Document is Entitled "Acknowledgements",
+"Dedications", or "History", the requirement (section 4) to Preserve
+its Title (section 1) will typically require changing the actual
+title.
+
+
+\begin{center}
+{\Large\bf 9. TERMINATION}
+\end{center}
+
+
+You may not copy, modify, sublicense, or distribute the Document except
+as expressly provided for under this License. Any other attempt to
+copy, modify, sublicense or distribute the Document is void, and will
+automatically terminate your rights under this License. However,
+parties who have received copies, or rights, from you under this
+License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
+
+\begin{center}
+{\Large\bf 10. FUTURE REVISIONS OF THIS LICENSE}
+\end{center}
+
+
+The Free Software Foundation may publish new, revised versions
+of the GNU Free Documentation License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns. See
+http://www.gnu.org/copyleft/.
+
+Each version of the License is given a distinguishing version number.
+If the Document specifies that a particular numbered version of this
+License "or any later version" applies to it, you have the option of
+following the terms and conditions either of that specified version or
+of any later version that has been published (not as a draft) by the
+Free Software Foundation. If the Document does not specify a version
+number of this License, you may choose any version ever published (not
+as a draft) by the Free Software Foundation.
+
+
+\begin{center}
+{\Large\bf ADDENDUM: How to use this License for your documents}
+% TODO: this is too long for table of contents
+\end{center}
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and
+license notices just after the title page:
+
+\bigskip
+\begin{quote}
+ Copyright \copyright YEAR YOUR NAME.
+ Permission is granted to copy, distribute and/or modify this document
+ under the terms of the GNU Free Documentation License, Version 1.2
+ or any later version published by the Free Software Foundation;
+ with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+ A copy of the license is included in the section entitled "GNU
+ Free Documentation License".
+\end{quote}
+\bigskip
+
+If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
+replace the "with...Texts." line with this:
+
+\bigskip
+\begin{quote}
+ with the Invariant Sections being LIST THEIR TITLES, with the
+ Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
+\end{quote}
+\bigskip
+
+If you have Invariant Sections without Cover Texts, or some other
+combination of the three, merge those two alternatives to suit the
+situation.
+
+If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of
+free software license, such as the GNU General Public License,
+to permit their use in free software.
+
+%---------------------------------------------------------------------
--- /dev/null
+#!/usr/bin/perl -w
+# Fixes various things within tex files.
+
+use strict;
+
+my %args;
+
+
+sub get_includes {
+ # Get a list of include files from the top-level tex file.
+ my (@list,$file);
+
+ foreach my $filename (@_) {
+ $filename or next;
+ # Start with the top-level latex file so it gets checked too.
+ push (@list,$filename);
+
+ # Get a list of all the html files in the directory.
+ open IF,"<$filename" or die "Cannot open input file $filename";
+ while (<IF>) {
+ chomp;
+ push @list,"$1.tex" if (/\\include\{(.*?)\}/);
+ }
+
+ close IF;
+ }
+ return @list;
+}
+
+sub convert_files {
+ my (@files) = @_;
+ my ($linecnt,$filedata,$output,$itemcnt,$indentcnt,$cnt);
+
+ $cnt = 0;
+ foreach my $file (@files) {
+ # Open the file and load the whole thing into $filedata. A bit wasteful but
+ # easier to deal with, and we don't have a problem with speed here.
+ $filedata = "";
+ open IF,"<$file" or die "Cannot open input file $file";
+ while (<IF>) {
+ $filedata .= $_;
+ }
+ close IF;
+
+ # We look for a line that starts with \item, and indent the two next lines (if not blank)
+ # by three spaces.
+ my $linecnt = 3;
+ $indentcnt = 0;
+ $output = "";
+ # Process a line at a time.
+ foreach (split(/\n/,$filedata)) {
+ $_ .= "\n"; # Put back the return.
+ # If this line is less than the third line past the \item command,
+ # and the line isn't blank and doesn't start with whitespace
+ # add three spaces to the start of the line. Keep track of the number
+ # of lines changed.
+ if ($linecnt < 3 and !/^\\item/) {
+ if (/^[^\n\s]/) {
+ $output .= " " . $_;
+ $indentcnt++;
+ } else {
+ $output .= $_;
+ }
+ $linecnt++;
+ } else {
+ $linecnt = 3;
+ $output .= $_;
+ }
+ /^\\item / and $linecnt = 1;
+ }
+
+
+ # This is an item line. We need to process it too. If inside a \begin{description} environment, convert
+ # \item {\bf xxx} to \item [xxx] or \item [{xxx}] (if xxx contains '[' or ']'.
+ $itemcnt = 0;
+ $filedata = $output;
+ $output = "";
+ my ($before,$descrip,$this,$between);
+
+ # Find any \begin{description} environment
+ while ($filedata =~ /(\\begin[\s\n]*\{[\s\n]*description[\s\n]*\})(.*?)(\\end[\s\n]*\{[\s\n]*description[\s\n]*\})/s) {
+ $output .= $` . $1;
+ $filedata = $3 . $';
+ $descrip = $2;
+
+ # Search for \item {\bf xxx}
+ while ($descrip =~ /\\item[\s\n]*\{[\s\n]*\\bf[\s\n]*/s) {
+ $descrip = $';
+ $output .= $`;
+ ($between,$descrip) = find_matching_brace($descrip);
+ if (!$descrip) {
+ $linecnt = $output =~ tr/\n/\n/;
+ print STDERR "Missing matching curly brace at line $linecnt in $file\n" if (!$descrip);
+ }
+
+ # Now do the replacement.
+ $between = '{' . $between . '}' if ($between =~ /\[|\]/);
+ $output .= "\\item \[$between\]";
+ $itemcnt++;
+ }
+ $output .= $descrip;
+ }
+ $output .= $filedata;
+
+ # If any hyphens or \item commnads were converted, save the file.
+ if ($indentcnt or $itemcnt) {
+ open OF,">$file" or die "Cannot open output file $file";
+ print OF $output;
+ close OF;
+ print "$indentcnt indent", ($indentcnt == 1) ? "" : "s"," added in $file\n";
+ print "$itemcnt item", ($itemcnt == 1) ? "" : "s"," Changed in $file\n";
+ }
+
+ $cnt += $indentcnt + $itemcnt;
+ }
+ return $cnt;
+}
+
+sub find_matching_brace {
+ # Finds text up to the next matching brace. Assumes that the input text doesn't contain
+ # the opening brace, but we want to find text up to a matching closing one.
+ # Returns the text between the matching braces, followed by the rest of the text following
+ # (which does not include the matching brace).
+ #
+ my $str = shift;
+ my ($this,$temp);
+ my $cnt = 1;
+
+ while ($cnt) {
+ # Ignore verbatim constructs involving curly braces, or if the character preceding
+ # the curly brace is a backslash.
+ if ($str =~ /\\verb\*?\{.*?\{|\\verb\*?\}.*?\}|\{|\}/s) {
+ $this .= $`;
+ $str = $';
+ $temp = $&;
+
+ if ((substr($this,-1,1) eq '\\') or
+ $temp =~ /^\\verb/) {
+ $this .= $temp;
+ next;
+ }
+
+ $cnt += ($temp eq '{') ? 1 : -1;
+ # If this isn't the matching curly brace ($cnt > 0), include the brace.
+ $this .= $temp if ($cnt);
+ } else {
+ # No matching curly brace found.
+ return ($this . $str,'');
+ }
+ }
+ return ($this,$str);
+}
+
+sub check_arguments {
+ # Checks command-line arguments for ones starting with -- puts them into
+ # a hash called %args and removes them from @ARGV.
+ my $args = shift;
+ my $i;
+
+ for ($i = 0; $i < $#ARGV; $i++) {
+ $ARGV[$i] =~ /^\-+/ or next;
+ $ARGV[$i] =~ s/^\-+//;
+ $args{$ARGV[$i]} = "";
+ delete ($ARGV[$i]);
+
+ }
+}
+
+##################################################################
+# MAIN ####
+##################################################################
+
+my @includes;
+my $cnt;
+
+check_arguments(\%args);
+die "No Files given to Check\n" if ($#ARGV < 0);
+
+# Examine the file pointed to by the first argument to get a list of
+# includes to test.
+@includes = get_includes(@ARGV);
+
+$cnt = convert_files(@includes);
+print "No lines changed\n" unless $cnt;
--- /dev/null
+%%
+%%
+
+\chapter{Qu'est-ce que Bacula ?}
+\label{_ChapterStart41}
+\index[general]{Qu'est-ce que Bacula ? }
+\index[general]{Bacula!Qu'est-ce que }
+\addcontentsline{toc}{section}{Qu'est-ce que Bacula ?}
+
+{\bf Bacula} est un jeu de programmes qui vous permet (ou \`a l'administrateur
+syst\`eme) de faire des sauvegardes, restaurations, et v\'erifications des
+donn\'ees d'un ordinateur sur un r\'eseau h\'et\'erog\`ene. Bacula peut
+fonctionner compl\`etement sur un seul ordinateur. Il est capable de
+sauvegarder sur des supports vari\'es, y compris disques et cartouches.
+
+En termes
+techniques, il s'agit d'un programme de sauvegarde Client/Serveur. Bacula est
+relativement facile d'utilisation et efficace, tout en offant de nombreuses
+fonctions avanc\'ees de gestion de stockage qui facilitent la recherche et la
+restauration de fichiers perdus ou endommag\'es. Gr\^ace \`a sa conception
+modulaire, Bacula est \'echelonnable depuis le simple syst\`eme constitu\'e
+d'un ordinateur, jusqu'au syst\`eme de plusieurs centaines d'ordinateurs
+diss\'emin\'es sur un vaste r\'eseau.
+
+\section{Qui a besoin de Bacula ?}
+\index[general]{Qui a besoin de Bacula ? }
+\index[general]{Bacula!Qui a besoin de }
+\addcontentsline{toc}{section}{Qui a besoin de Bacula ?}
+
+Si vous utilisez actuellement un programme tel que {\bf tar}, {\bf dump}, ou
+{\bf bru} pour sauvegarder vos donn\'ees, et aimeriez une solution r\'eseau,
+plus de flexibilit\'e, ou les commodit\'es d'un catalogue, Bacula vous
+procurera certainement les fonctions suppl\'ementaires que vous recherchez.
+Cependant, si vous avez peu d'exp\'erience des syst\`emes Unix ou si vous
+n'avez pas l'exp\'erience d'un syst\`eme de sauvegarde sophistiqu\'e, nous ne
+vous recommandons pas l'utilisation de Bacula, car il est beaucoup plus
+difficile \`a installer et utiliser que {\bf tar} ou {\bf dump}.
+
+Si vous attendez de Bacula qu'il se comporte comme les programmes simples
+mentionn\'es ci-dessus et qu'il \'ecrive sur toute cartouche ins\'er\'ee dans le
+lecteur, vous \'eprouverez des difficult\'es \`a travailler avec Bacula. Bacula
+est con\c {c}u pour prot\'eger vos donn\'ees en suivant les r\`egles que vous sp\'ecifiez,
+ce qui signifie que la r\'eutilisation d'une cartouche ne se fera qu'en dernier
+ressort. Il est possible de "contraindre" Bacula \`a \'ecraser toute cartouche dans
+le lecteur, mais il est plus facile et plus efficace d'utiliser un outil
+plus basique pour ce genre d'op\'erations.
+
+Si vous utilisez {\bf Amanda} et aimeriez un programme de sauvegarde qui peut
+\'ecrire sur plusieurs volumes (qui ne soit pas limit\'e par la capacit\'e de vos
+cartouches), Bacula peut certainement satisfaire vos besoins, d'autant que
+plusieurs de nos utilisateurs estiment que Bacula est plus simple \`a
+installer et utiliser que d'autres programmes \'equivalents.
+
+Si vous utilisez actuellement un logiciel commercial sophistiqu\'e tel que
+{\bf Legato Networker}, {\bf ARCserveIT}, {\bf Arkeia}, ou {\bf
+PerfectBackup+}, vous pourriez \^etre interess\'e par Bacula qui fournit la
+plupart de leurs fonctions et qui est un logiciel libre sous licence GNU
+version 2.
+
+\section{Composants ou Services de Bacula}
+\index[general]{Bacula!Composants ou Services de }
+\index[general]{Composants ou Services de Bacula }
+\addcontentsline{toc}{section}{Composants ou Services de Bacula}
+
+Bacula est constitu\'e des cinq composants ou services majeurs suivants :
+
+\includegraphics{./bacula-applications.eps}
+(remerciements \`a Aristedes Maniatis pour ce sch\'ema et le suivant)
+
+\begin{itemize}
+\item
+ \label{DirDef}
+ Le service {\bf Bacula Director
+\label{a1}
+} est le programme qui supervise toutes les op\'erations de sauvegarde,
+restauration, v\'erification et archivage. L'administrateur syst\`eme utilise
+le Bacula Director pour planifier les sauvegardes et restaurer les fichiers.
+Pour plus de d\'etails, consultez la section concernant la conception du Daemon Director
+dans la documentation pour d\'eveloppeurs. Le Director est ex\'ecut\'e en tant que {\it daemon}
+ou service (c'est \`a dire en tâche de fond).
+\item
+ \label{UADef}
+ Le service {\bf Bacula Console} est le programme qui permet \`a
+l'administrateur ou \`a l'utilisateur de communiquer avec le {\bf Bacula
+Director} (voir ci-dessus). Actuellement, le service Bacula Console est
+disponible en trois versions. La premi\`ere et la plus simple est
+d'ex\'ecuter le programme Console dans une fen\^etre shell (i.e. interface
+TTY). La plupart des administrateurs syst\`eme trouveront cette m\'ethode
+parfaitement ad\'equate. La seconde version est une interface graphique GNOME
+qui est loin d'\^etre compl\`ete, mais est
+tout \`a fait fonctionnelle puisqu'elle poss\`ede la plupart des
+possibilit\'es de la Console shell. La troisi\`eme version est une interface
+graphique wxWidgets qui permet de s\'electionner interactivement les fichiers
+\`a restaurer. Elle int\`egre la plupart des fonctionnalit\'es de la console
+shell, permet la compl\'etion automatique avec la touche tabulation, et
+fournit une aide instantan\'ee relative \`a la commande que vous \^etes en
+train de taper. Pour plus de d\'etails, consultez la section
+\ilink{Conception de la Console Bacula}{_ConsoleChapter} dans la documentation
+pour d\'eveloppeurs.
+\item
+ \label{FDDef}
+ Le service {\bf Bacula File} (ou programme client) est le programme install\'e
+sur la machine \`a sauvegarder. Il est sp\'ecifique au syst\`eme sur lequel
+il est ex\'ecut\'e et a la charge de fournir les attributs des fichiers et
+les donn\'ees requis par le Director. Les Services File sont aussi charg\'es
+de la partie d\'ependant du syst\`eme de fichiers lors de la restauration des
+attributs de fichiers et des donn\'ees. Pour plus de d\'etails, consultez le
+document sur la conception du File Daemon dans le Guide pour Developpeurs. Ce
+programme est ex\'ecut\'e en tant que service sur la machine \`a sauvegarder,
+et la documentation s'y r\'ef\`ere parfois en tant que Client (par exemple
+dans les fichiers de configuration de Bacula). En plus du File Daemon pour
+Unix/Linux, il existe un File Daemon pour Windows (usuellement distribu\'e au
+format binaire). Le File Daemon Windows fonctionne sur toutes les versions
+actuelles de Windows (NT, 2000, XP, 2003 et peut-\^etre aussi 98 et Me).
+\item
+ \label{SDDef}
+ Le service {\bf Bacula Storage} est le programme qui transf\`ere les donn\'ees
+et les attributs de fichiers aux m\'edia physiques ou aux volumes et les
+restitue lors de restaurations. En d'autres termes, Le storage Daemon est
+responsable des op\'erations de lecture et d'\'ecriture sur vos cartouches (ou
+autres m\'edia de stockage, comme par exemple des fichiers). Pour plus de
+d\'etails consultez la Documentation Pour D\'eveloppeurs sur la conception du
+Storage Daemon.
+\item
+ \label{DBDefinition}
+ Les services {\bf Catalogue} ont pour t\^ache de maintenir \`a jour la base de
+donn\'ees des index de fichiers et volumes pour tous les fichiers
+sauvegard\'es. Les services {\bf Catalogue} permettent \`a l'administrateur
+syst\`eme ou \`a l'utilisateur de localiser rapidement et restaurer n'importe
+quel fichier. Les services Catalogue de Bacula le placent dans une
+cat\'egorie diff\'erente de programmes tels que tar et bru, puisque le
+catalogue Bacula maintient un enregistrement de chaque volume utilis\'e,
+chaque job ex\'ecut\'e et chaque fichier sauvegard\'e ce qui permet des
+restaurations et une gestion de volumes efficaces. Bacula supporte
+actuellement trois bases de donn\'ees diff\'erentes, MySQL, PostgreSQL, et
+SQLite. L'une des trois doit \^etre choisie \`a la compilation de {\bf
+Bacula}.
+
+Les trois bases de donn\'ees actuellement support\'ees (MySQL, PostgreSQL, ou
+SQLite) fournissent de nombreuses fonctions telles l'indexation rapide,
+requ\^etes arbitraires, et s\'ecurit\'e. Bien que nous pr\'evoyions de
+supporter d'autres bases de donn\'ees SQL majeures, l'impl\'ementation
+actuelle s'interface seulement avec MySQL, PostgreSQL, et SQLite. Pour plus
+de d\'etails consultez le
+\ilink{document sur la conception des Services Catalogue
+}{_ChapterStart30}.
+
+Les RPMs pour MySQL et PostgreSQL font partie de la distribution Red Hat.
+Sinon, il est tout \`a fait ais\'e de les construire \`a partir des sources.
+Consultez le chapitre
+\ilink{ Installer et configurer MySQL}{_ChapterStart} ou
+\ilink{ Installer et configurer PostgreSQL}{_ChapterStart10} de
+ce document pour plus de d\'etails. Pour plus d'informations sur MySQL et
+PostgreSQL, consultez
+\elink{www.mysql.com}{http://www.mysql.com} ou
+\elink{www.postgresql.org}{http://www.postgresql.org}.
+
+Configurer et construire SQLite est encore plus facile. Pour les d\'etails de
+configuration de SQLite, consultez le chapitre
+\ilink{Installer et Configurer SQLite}{_ChapterStart33} de ce
+document.
+\item
+ \label{MonDef}
+ Le service {\bf Bacula Monitor} est le programme qui permet \`a
+l'administrateur ou \`a l'utilisateur de contr\^oler le statut des {\it
+daemons} Bacula ({\bf Bacula Directors}, {\bf Bacula File Daemons} et {\bf
+Bacula Storage Daemons}) (voir ci-dessus). Actuellement, la seule version
+disponible est une version GTK+, qui fonctionne avec Gnome et KDE (ainsi que
+tout gestionnaire de fen\^etre qui respecte le standard system tray
+FreeDesktop.org).
+\end{itemize}
+
+Pour r\'ealiser avec succ\`es les op\'erations de sauvegarde et restauration,
+les quatre services suivants doivent \^etre configur\'es et lanc\'es : le
+Director Daemon, le File Daemon, le Storage Daemon et MySQL, PostgreSQL ou
+SQLite.
+
+\section{Configuration de Bacula}
+\index[general]{Configuration de Bacula }
+\index[general]{Bacula!Configuration de }
+\addcontentsline{toc}{section}{Configuration de Bacula}
+
+Pour que Bacula comprenne votre syst\`eme, quels clients vous voulez
+sauvegarder et comment, vous devez cr\'eer un certain nombre de fichiers de
+configuration. La suite brosse un tableau de ces op\'erations.
+
+\includegraphics{./bacula-objects.eps}
+
+\section{Conventions utilis\'ees dans ce document}
+\index[general]{Conventions utilis\'ees dans ce document }
+\index[general]{Document!Conventions utilis\'ees dans ce }
+\addcontentsline{toc}{section}{Conventions utilis\'ees dans ce document}
+
+{\bf Bacula} est en constante \'evolution, par cons\'equent, ce manuel ne sera
+pas toujours en accord avec le code. Si un objet de ce manuel est
+pr\'ec\'ed\'e d'un ast\'erisque (*), cela signifie que cette fonctionnalit\'e
+particuli\`ere n'est pas impl\'ement\'ee. S'il est pr\'ec\'ed\'e d'un signe
+plus (+), cela indique que la fonction est peut-\^etre partiellement
+impl\'ement\'ee.
+
+Si vous lisez la version de ce manuel fournie avec les sources de Bacula, le
+paragraphe ci-dessus reste vrai. En revanche, si vous lisez la version en
+ligne :
+\elink{www.bacula.org/manual}{http://www.bacula.org/manual}, veuillez garder
+\`a l'esprit que cette version d\'ecrit la version courante de d\'eveloppement
+de Bacula (celle du CVS) qui peut contenir des fonctionnalit\'es qui
+n'existent pas dans la version "officielle". De m\^eme, il est
+g\'en\'eralement un peu \`a la tra{\^\i}ne derri\`ere le code.
+
+\section{D\'emarrage rapide}
+\index[general]{D\'emarrage rapide }
+\index[general]{Rapide!D\'emarrage }
+\addcontentsline{toc}{section}{D\'emarrage rapide}
+
+Pour faire fonctionner Bacula rapidement, nous vous recommandons de commencer
+par parcourir la section Terminologie ci-dessous, de passer rapidement en
+revue le chapitre suivant intitul\'e
+\ilink{L'\'etat actuel de Bacula}{_ChapterStart2}, puis le
+\ilink{Guide de d\'emarrage rapide de Bacula}{_ChapterStart37},
+qui vous donnera une vue d'ensemble de la mise en oeuvre de Bacula . Apr\`es
+quoi vous devriez poursuivre avec le chapitre sur
+\ilink{ L'installation de Bacula}{_ChapterStart17}, puis le chapitre
+\ilink{Comment configurer Bacula}{_ChapterStart16}, et finalement,
+le chapitre \ilink{Ex\'ecuter Bacula}{_ChapterStart1}.
+
+\section{Terminologie}
+\index[general]{Terminologie }
+\addcontentsline{toc}{section}{Terminologie}
+
+Pour faciliter la communication autour de ce projet, nous fournissons ici les
+d\'efinitions de la terminologie que nous utilisons.
+
+\begin{description}
+
+\item [Administrateur]
+ \index[sd]{Administrateur }
+ La ou les personne(s) responsable(s) de l'administration du syst\`eme Bacula.
+
+
+\item [Sauvegarde]
+ \index[sd]{Sauvegarde }
+ Nous utilisons ce terme pour un job Bacula qui sauvegarde des fichiers.
+
+\item [Fichier Bootstrap (Bootstrap File)]
+ \index[sd]{Fichier Bootstrap (Bootstrap File) }
+ Le bootstrap est un fichier ASCII qui contient, sous une forme compacte, les
+commandes qui permettent \`a Bacula ou \`a l'utilitaire autonome {\bf
+bextract} de restaurer les contenus d'un ou plusieurs volumes, par exemple,
+l'\'etat courant d'un syst\`eme qui vient d'\^etre sauvegard\'e. Avec un
+fichier bootstrap, Bacula peut restaurer votre syst\`eme sans catalogue. Vous
+pouvez cr\'eer un fichier bootstrap depuis un catalogue pour extraire le
+fichier que vous voulez.
+
+\item [Catalogue]
+ \index[sd]{Catalogue }
+ Le catalogue est utilis\'e pour stocker des informations sommaires concernant
+les Jobs et Clients, les fichiers qui ont \'et\'e sauvegard\'es ainsi que le
+ou les volume(s) o\`u ils ont \'et\'e sauvegard\'es. L'information stock\'ee
+dans le catalogue permet \`a l'administrateur ou aux utilisateurs de
+d\'eterminer quels jobs ont \'et\'e ex\'ecut\'es, leur statut, ainsi que
+d'importantes caract\'eristiques de chaque fichier sauvegard\'e. Le catalogue
+est une ressource en ligne, mais ne contient pas les donn\'ees pour les
+fichiers sauvegard\'es. La plupart des informations stock\'ees dans le
+catalogue le sont aussi sur les volumes de sauvegarde (i.e. cartouches). Bien
+sur, les cartouches auront aussi une copie du fichier en plus de ses attributs
+ (voir ci-dessus).
+
+La fonction Catalogue est de celles qui distinguent Bacula de simples
+programmes de sauvegarde et archivage tels que {\bf dump} et {\bf tar}.
+
+\item [Client]
+ \index[sd]{Client }
+ Dans la terminologie de Bacula, le mot Client d\'esigne une machine
+sauvegard\'ee, et est synonyme de File service ou File Daemon. Nous nous y
+r\'ef\'erons assez souvent par "le FD". Un client est d\'efini dans une
+ressource de fichier de configuration.
+
+\item [Console]
+ \index[sd]{Console }
+ Le programme qui interface le Director, permettant \`a l'administrateur de
+contr\^oler Bacula.
+
+\item [Daemon]
+ \index[sd]{Daemon }
+ Terminologie Unix pour un programme toujours pr\'esent en arri\`ere plan pour
+prendre en charge une t\^ache donn\'ee. Sur les syst\`emes Windows, ainsi que
+certains Linux, les {\it daemons} sont appel\'es {\bf Services}.
+
+\item [Directive]
+ \index[sd]{Directive }
+ Le terme directive est utilis\'e pour d\'esigner une entr\'ee ou
+enregistrement \`a l'int\'erieur d'une ressource dans un fichier de
+configuration qui d\'efinit un \'el\'ement sp\'ecifique. Par exemple, la
+directive {\bf Name} d\'efinit le nom de la ressource.
+
+\item [Director]
+ \index[sd]{Director }
+ Le principal {\it daemon} serveur de Bacula qui planifie et dirige toutes
+les op\'erations de Bacula. Occasionnellement, nous le d\'esignons par "le
+DIR".
+
+\item [Differentielle (Differential)]
+ \index[sd]{Differentielle (Differential) }
+ Une sauvegarde qui inclut tous les fichiers modifi\'es depuis le lancement de
+la derni\`ere sauvegarde compl\`ete (Full). Notez que d'autres logiciels de
+sauvegarde peuvent d\'efinir ceci diff\'eremment.
+
+\item [Attributs de fichiers]
+ \index[sd]{Attributs de fichiers }
+ Les Attributs de fichiers sont toutes les informations n\'ecessaires au sujet
+d'un fichier pour l'identifier, et toutes ses propri\'et\'es telles taille,
+date de cr\'eation, date de modification, permission, etc. En principe, les
+attributs sont int\'egralement manipul\'es par Bacula de sorte que
+l'utilisateur n'a jamais \`a s'en pr\'eoccuper. Les attributs n'incluent pas
+les donn\'ees du fichier.
+
+\item [File Daemon]
+ \index[sd]{File Daemon }
+ Le {\it daemon} ex\'ecut\'e sur l'ordinateur client \`a sauvegarder. Il est
+aussi d\'esign\'e par Service Fichier (File Service) et parfois Service Client
+ou FD.
+
+\item [
+ \label{FileSetDef}
+ FileSet]
+\index[sd]{a name }
+Un FileSet est une ressource d'un fichier de configuration qui d\'efinit les
+fichiers \`a sauvegarder. Il consiste en une liste de fichiers ou
+r\'epertoires inclus, une liste de fichiers ou r\'epertoires exclus et la
+fa\c{c}on dont les fichiers seront stock\'es (compression, chiffrement,
+signatures). Pour plus de d\'etails consultez le paragraphe
+\ilink{D\'efinition de la Ressource FileSet}{FileSetResource}
+dans le chapitre Director de ce document.
+
+\item [Incrementale]
+ \index[sd]{Incrementale }
+ Une sauvegarde qui inclut tous les fichiers modifi\'es depuis le lancement de
+la derni\`ere sauvegarde compl\`ete (Full), diff\'erentielle, ou
+incr\'ementale. Normalement sp\'ecifi\'e dans la directive {\bf Level}
+(niveau) dans la d\'efinition de la ressource Job, ou dans une ressource
+Schedule.
+
+\item [
+ \label{JobDef}
+ Job]
+\index[sd]{a name }
+Un Job Bacula est une ressource de configuration qui d\'efinit le travail que
+Bacula doit effectuer pour sauvegarder ou restaurer un client particulier. Un
+Job consiste en un {\bf Type}, (Type : backup, restore, verify, etc.), un
+{\bf Niveau} (Level : full, incremental, ...), un {\bf FileSet}, et un lieu de
+{\bf Stockage} o\`u \'ecrire les fichiers (Storage device, Media Pool). Pour
+plus de d\'etails consultez le chapitre
+\ilink{D\'efinition des Ressources Job}{JobResource} de ce
+document.
+
+\item [Monitor]
+ \index[sd]{Monitor }
+ Le programme qui s'interface avec chacun des {\it daemons} pour permettre \`a
+l'utilisateur ou \`a l'administrateur de surveiller le statut de Bacula.
+
+\item [Resource]
+ \index[sd]{Resource }
+ Une ressource est une partie d'un fichier de configuration qui d\'efinit une
+unit\'e sp\'ecifique d'information disponible pour Bacula. Par exemple, la
+ressource {\bf Job} d\'efinit toutes les propri\'et\'es d'un Job sp\'ecifique
+: nom, schedule (planification), volume pool, type de sauvegarde, niveau de
+sauvegarde, etc.
+
+\item [Restore]
+ \index[sd]{Restore }
+ Une Restore est une ressource de configuration qui d\'ecrit l'op\'eration de
+restauration d'un fichier (perdu ou endommag\'e) depuis un medium de
+sauvegarde. C'est l'op\'eration r\'eciproque d'une sauvegarde, sauf que, dans
+la plupart des cas, une restauration concernera un petit ensemble de fichiers
+tandis qu'une sauvegarde concerne le plus souvent l'ensemble des fichiers
+d'un syst\`eme. Bien sur, apr\`es une d\'efaillance de disque(s), Bacula peut
+\^etre appel\'e \`a effectuer une restauration compl\`ete de tous les
+fichiers qui \'etaient sur le syst\`eme.
+
+\item [Schedule]
+ \index[sd]{Schedule }
+ Un Schedule est une ressource de configuration qui d\'efinit le moment de
+l'ex\'ecution du Job Bacula. Pour utiliser un schedule, la ressource Job se
+r\'ef\`ere au nom du Schedule. Pour plus de d\'etails, consultez la
+\ilink{D\'efinition de la ressource Schedule}{ScheduleResource}
+dans le chapitre Director de ce document.
+
+\item [Service]
+ \index[sd]{Service }
+ Terminologie Windows pour d\'esigner un {\it daemon} -- Voir plus haut. Elle
+est maintenant fr\'equemment utilis\'ee dans les environnements Unix aussi.
+
+\item [Adresses de stockage]
+ \index[sd]{Adresses de stockage }
+ Les informations retourn\'ees par les Storage services qui localisent de
+fa\c{c}on unique les fichiers sur un medium de sauvegarde. Elles consistent
+en deux parties : l'une appartient \`a chaque fichier sauvegard\'e, l'autre
+\`a l'ensemble du Job. Normalement, cette information est sauvegard\'ee dans
+le catalogue de sorte que l'utilisateur n'a pas besoin de connaissances
+particuli\`eres des adresses de stockage. L'adresse de stockage inclut les
+attributs de fichiers (voir plus haut) ainsi que la localisation unique de
+l'information sur le volume de sauvegarde.
+
+\item [Storage Daemon]
+ \index[sd]{Storage Daemon }
+ Le Storage Daemon, parfois d\'esign\'e par "SD" est le programme qui
+\'ecrit les attributs et les donn\'ees sur un Volume de Stockage (Storage
+Volume) (Usuellement une cartouche ou un disque).
+
+\item [Session]
+ \index[sd]{Session }
+ D\'esigne en principe le dialogue interne entre le File Daemon et le Storage
+Daemon. Le File Daemon ouvre une {\bf session} avec le Storage Daemon pour
+sauvegarder un Fileset, ou pour le restaurer. Une session est associ\'ee \`a
+un et un seul Job Bacula (voir plus haut).
+
+\item [Verify]
+ \index[sd]{Verify }
+ Il s'agit d'un job qui compare les attributs du fichier actuel aux attributs
+qui ont \'et\'e pr\'ealablement stock\'es dans le catalogue Bacula. Cette
+fonction peut \^etre utilis\'ee pour d\'etecter les modifications de
+syst\`emes de fichiers critiques, \`a la fa\c{c}on de {\bf Tripwire}. L'un
+des avantages majeurs de l'utilisation de Bacula pour cette t\^ache est que
+sur la machine que vous voulez prot\'eger, vous pouvez n'ex\'ecuter que le
+File Daemon. Le Director, le Storage Daemon et le catalogue peuvent r\'esider
+sur une autre machine. Par cons\'equent si votre serveur est un jour
+compromis, il est peu probable que la base de donn\'ees de v\'erification ait
+\'et\'e trifouill\'ee.
+
+Verify peut aussi \^etre utilis\'e pour s'assurer que les donn\'ees les plus
+r\'ecemment \'ecrites sur un volume sont coh\'erentes avec ce qui figure dans
+le catalogue (c-\`a-d il compare les attributs de fichiers), ou encore,
+confronter le contenu du volume aux fichiers originaux sur le disque.
+
+\item [*Archive]
+ \index[sd]{*Archive }
+ Une op\'eration d'archivage est effectu\'ee apr\`es une sauvegarde, et
+consiste en l'exclusion des volumes sur lesquels les donn\'ees sont
+sauvegard\'ees de l'utilisation courante. Ces volumes sont marqu\'es
+"Archived", et ne sont plus utilis\'es pour sauvegarder des fichiers. Tous
+les fichiers contenus sur un Volume Archive sont supprim\'es du catalogue.
+PAS ENCORE IMPLEMENTE.
+
+\item [*Update]
+ \index[sd]{*Update }
+ Une op\'eration Update synchronise les fichiers du syst\`eme distant sur ceux
+du local. Ceci est l'\'equivalent d'une fonctionnalit\'e {\bf rdist}. PAS
+ENCORE IMPLEMENTE.
+
+\item [P\'eriode de r\'etention]
+ \index[sd]{P\'eriode de r\'etention }
+ Bacula reconnait plusieurs sortes de p\'eriodes de r\'etention. Les plus
+importantes sont la p\'eriode de r\'etention des fichiers, la p\'eriode de
+r\'etention des jobs et la p\'eriode de r\'etention des volumes. Chacune de
+ces p\'eriodes de r\'etention d\'esigne la dur\'ee pendant laquelle
+l'enregistrement sp\'ecifique sera conserv\'e dans le catalogue. Ceci ne doit
+pas \^etre confondu avec le temps pendant lequel les donn\'ees sauvegard\'ees
+sur un volume sont valides.
+
+La p\'eriode de r\'etention des fichiers d\'etermine la dur\'ee pendant
+laquelle les enregistrements concernant les fichiers seront gard\'es dans le
+catalogue. Cette p\'eriode est importante car le volume des enregistrements
+relatifs aux fichiers occupe, de loin, le plus d'espace dans la base de
+donn\'ees. Par cons\'equent, vous devez vous assurer qu'un "\'elagage"
+(NDT : pruning) r\'egulier de ces enregistrements est effectu\'e. (Voir la
+commande {\bf retention} de la Console pour plus de d\'etails sur ce sujet).
+
+La p\'eriode de r\'etention des jobs est la dur\'ee pendant laquelle les
+enregistrements relatifs aux jobs seront conserv\'es dans le catalogue. Notez
+que tous les enregistrements relatifs aux fichiers sont attach\'es aux jobs
+qui ont sauvegard\'e ces fichiers. Les enregistrements relatifs aux fichiers
+peuvent \^etre purg\'es tout en conservant ceux relatifs aux jobs. Dans ce
+cas, l'information concernant les jobs ex\'ecut\'es restera disponible, mais
+pas les d\'etails des fichiers sauvegard\'es. Normalement, lorsqu'un job est
+purg\'e, tous les enregistrements concernant les fichiers qu'il a
+sauvegard\'e le sont aussi.
+
+La p\'eriode de r\'etention des volumes est la
+dur\'ee minimale de conservation d'un volume avant qu'il ne soit
+r\'eutilis\'e. Bacula n'effacera, en principe, jamais un volume qui contient
+la seule copie de sauvegarde d'un fichier. Dans les conditions id\'eales, le
+catalogue maintiendrait les entr\'ees pour tous les fichiers sauvegard\'es
+pour tous les volumes courants. Une fois qu'un volume est \'ecras\'e, les
+fichiers qui \'etaient sauvegard\'es dessus sont automatiquement effac\'es du
+catalogue. Cependant, s'il y a un tr\`es gros pool de volumes ou si un volume
+n'est jamais \'ecras\'e, le catalogue pourrait devenir \'enorme. Pour
+maintenir le catalogue dans des proportions g\'erables, les informations de
+sauvegarde devraient \^etre supprim\'ees apr\`es une p\'eriode de r\'etention
+des fichiers d\'efinie.
+
+\item [Scan]
+ \index[sd]{Scan }
+ Une op\'eration de scan consiste en un balayage du contenu d'un volume ou
+d'une s\'erie de volumes. Ces volumes et les informations concernant les
+fichiers qu'ils contiennent sont restaur\'es vers le catalogue Bacula. Une
+fois ces informations restaur\'ees, les fichiers sauvegard\'es sur ces
+volumes pourront \^etre ais\'ement restaur\'es. Cette fonction est
+particuli\`erement utile si certains volumes ou jobs ont d\'epass\'e leur
+p\'eriode de r\'etention et ont \'et\'e \'elagu\'es ou purg\'es du
+catalogue. Le balayage des donn\'ees des volumes est effectu\'e en utilisant
+le programme {\bf bscan}. Consultez la
+\ilink{section bscan }{bscan} du chapitre sur les utilitaires
+Bacula de ce manuel pour plus de d\'etails.
+
+\item [Volume]
+ \index[sd]{Volume }
+ Un volume est une unit\'e d'archivage, usuellement une cartouche ou un
+fichier nomm\'e sur disque o\`u Bacula stocke les donn\'ees pour un ou
+plusieurs jobs de sauvegarde. Tous les volumes Bacula ont un label unique
+(logiciel) \'ecrit sur le volume par Bacula afin qu'il puisse \^etre assur\'e de
+lire le bon volume. (En principe, il ne devrait pas y avoir de
+confusion avec des fichiers disques, mais avec des cartouches, il est facile
+de monter la mauvaise).
+\end{description}
+
+\section{Ce que Bacula n'est pas}
+\index[general]{Ce que Bacula n'est pas }
+\index[general]{Pas!Ce que Bacula n'est }
+\addcontentsline{toc}{section}{Ce que Bacula n'est pas}
+
+{\bf Bacula} est un programme de sauvegarde, restauration et v\'erification,
+ce n'est pas un syst\`eme complet de disaster recovery
+\label{c}
+\`a lui seul, mais il peut en \^etre une partie clef si vous planifiez
+soigneusement et suivez les instructions incluses dans le chapitre
+\ilink{ Plan de reprise d'activit\'e avec Bacula}{_ChapterStart38} de
+ce manuel.
+
+Avec la planification appropri\'ee, telle que d\'ecrite dans le chapitre sur le
+plan de reprise d'activit\'e, {\bf Bacula} peut devenir la pi\`ece centrale de
+votre plan de reprise d'activit\'e. Par exemple, si vous avez cr\'e\'e un(e)
+disque(tte) boot d'urgence et un(e) disque(tte) de secours Bacula pour
+sauvegarder les informations de partitionnement courantes de votre disque dur,
+et maintenu un jeu de sauvegardes complet de votre syst\`eme, il est possible
+de reconstruire compl\`etement votre syst\`eme "depuis le m\'etal brut"
+(NDT : From bare metal)
+\label{d1}
+.
+
+Si vous avez utilis\'e la directive {\bf WriteBootstrap} dans votre job ou
+quelque autre moyen pour sauvegarder un fichier bootstrap valide, vous pourrez
+l'utiliser pour extraire les fichiers n\'ecessaires (sans utiliser le
+catalogue et sans chercher manuellement les fichiers \`a restaurer).
+
+\section{Interactions entre les services Bacula}
+\index[general]{Bacula!Interactions entre les services }
+\index[general]{Interactions entre les services Bacula }
+\addcontentsline{toc}{section}{Interactions entre les services Bacula}
+
+Le diagramme fonctionnel suivant montre les interactions typiques entre les
+services Bacula pour un job de type sauvegarde. Chaque bloc repr\'esente en
+g\'en\'eral un processus s\'epar\'e (normalement un {\it daemon}). En
+g\'en\'eral, le director surveille le flux d'informations. Il maintient aussi
+le catalogue. \includegraphics{./flow.eps}
--- /dev/null
+%%
+%%
+
+\section*{GNU General Public License}
+\label{GplChapter}
+\index[general]{GNU General Public License }
+\index[general]{License!GNU General Public }
+
+\elink{image of a Philosophical
+GNU}{http://www.gnu.org/graphics/philosophicalgnu.html}
+
+\begin{itemize}
+\item
+ \elink{What to do if you see a possible GPL
+ violation}{http://www.gnu.org/copyleft/gpl-violation.html}
+\item
+ \elink{Translations of the
+ GPL}{http://www.gnu.org/copyleft/copyleft.html\#translations}
+\end{itemize}
+
+
+\section{Table of Contents}
+\index[general]{Table of Contents }
+\index[general]{Contents!Table of }
+
+\begin{itemize}
+\item
+ \label{TOC1}
+ \ilink{GNU GENERAL PUBLIC LICENSE}{SEC1}
+
+\begin{itemize}
+\item
+ \label{TOC2}
+ \ilink{Preamble}{SEC2}
+\item
+ \label{TOC3}
+ \ilink{TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND
+MODIFICATION}{SEC3}
+\item
+ \label{TOC4}
+ \ilink{How to Apply These Terms to Your New Programs}{SEC4}
+\end{itemize}
+
+\end{itemize}
+
+
+\section{GNU GENERAL PUBLIC LICENSE}
+\label{SEC1}
+\index[general]{GNU GENERAL PUBLIC LICENSE }
+\index[general]{LICENSE!GNU GENERAL PUBLIC }
+
+Version 2, June 1991
+
+\footnotesize
+\begin{verbatim}
+Copyright (C) 1989, 1991 Free Software Foundation, Inc.
+51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+\end{verbatim}
+\normalsize
+
+\section{Preamble}
+\label{SEC2}
+\index[general]{Preamble }
+
+The licenses for most software are designed to take away your freedom to share
+and change it. By contrast, the GNU General Public License is intended to
+guarantee your freedom to share and change free software\verb:--:to make sure the
+software is free for all its users. This General Public License applies to
+most of the Free Software Foundation's software and to any other program whose
+authors commit to using it. (Some other Free Software Foundation software is
+covered by the GNU Library General Public License instead.) You can apply it
+to your programs, too.
+
+When we speak of free software, we are referring to freedom, not price. Our
+General Public Licenses are designed to make sure that you have the freedom to
+distribute copies of free software (and charge for this service if you wish),
+that you receive source code or can get it if you want it, that you can change
+the software or use pieces of it in new free programs; and that you know you
+can do these things.
+
+To protect your rights, we need to make restrictions that forbid anyone to
+deny you these rights or to ask you to surrender the rights. These
+restrictions translate to certain responsibilities for you if you distribute
+copies of the software, or if you modify it.
+
+For example, if you distribute copies of such a program, whether gratis or for
+a fee, you must give the recipients all the rights that you have. You must
+make sure that they, too, receive or can get the source code. And you must
+show them these terms so they know their rights.
+
+We protect your rights with two steps: (1) copyright the software, and (2)
+offer you this license which gives you legal permission to copy, distribute
+and/or modify the software.
+
+Also, for each author's protection and ours, we want to make certain that
+everyone understands that there is no warranty for this free software. If the
+software is modified by someone else and passed on, we want its recipients to
+know that what they have is not the original, so that any problems introduced
+by others will not reflect on the original authors' reputations.
+
+Finally, any free program is threatened constantly by software patents. We
+wish to avoid the danger that redistributors of a free program will
+individually obtain patent licenses, in effect making the program proprietary.
+To prevent this, we have made it clear that any patent must be licensed for
+everyone's free use or not licensed at all.
+
+The precise terms and conditions for copying, distribution and modification
+follow.
+
+\section{TERMS AND CONDITIONS}
+\label{SEC3}
+\index[general]{CONDITIONS!TERMS AND }
+\index[general]{TERMS AND CONDITIONS }
+
+TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+{\bf 0.} This License applies to any program or other work which contains a
+notice placed by the copyright holder saying it may be distributed under the
+terms of this General Public License. The "Program", below, refers to any
+such program or work, and a "work based on the Program" means either the
+Program or any derivative work under copyright law: that is to say, a work
+containing the Program or a portion of it, either verbatim or with
+modifications and/or translated into another language. (Hereinafter,
+translation is included without limitation in the term "modification".) Each
+licensee is addressed as "you".
+
+Activities other than copying, distribution and modification are not covered
+by this License; they are outside its scope. The act of running the Program is
+not restricted, and the output from the Program is covered only if its
+contents constitute a work based on the Program (independent of having been
+made by running the Program). Whether that is true depends on what the Program
+does.
+
+{\bf 1.} You may copy and distribute verbatim copies of the Program's source
+code as you receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice and
+disclaimer of warranty; keep intact all the notices that refer to this License
+and to the absence of any warranty; and give any other recipients of the
+Program a copy of this License along with the Program.
+
+You may charge a fee for the physical act of transferring a copy, and you may
+at your option offer warranty protection in exchange for a fee.
+
+{\bf 2.} You may modify your copy or copies of the Program or any portion of
+it, thus forming a work based on the Program, and copy and distribute such
+modifications or work under the terms of Section 1 above, provided that you
+also meet all of these conditions:
+
+\begin{itemize}
+\item {\bf a)} You must cause the modified files to carry prominent notices
+ stating that you changed the files and the date of any change.
+
+\item {\bf b)} You must cause any work that you distribute or publish, that
+ in whole or in part contains or is derived from the Program or any part
+ thereof, to be licensed as a whole at no charge to all third parties under
+ the terms of this License.
+
+\item {\bf c)} If the modified program normally reads commands interactively
+ when run, you must cause it, when started running for such interactive use in
+ the most ordinary way, to print or display an announcement including an
+ appropriate copyright notice and a notice that there is no warranty (or else,
+ saying that you provide a warranty) and that users may redistribute the
+ program under these conditions, and telling the user how to view a copy of
+ this License. (Exception: if the Program itself is interactive but does not
+ normally print such an announcement, your work based on the Program is not
+ required to print an announcement.)
+\end{itemize}
+
+These requirements apply to the modified work as a whole. If identifiable
+sections of that work are not derived from the Program, and can be reasonably
+considered independent and separate works in themselves, then this License,
+and its terms, do not apply to those sections when you distribute them as
+separate works. But when you distribute the same sections as part of a whole
+which is a work based on the Program, the distribution of the whole must be on
+the terms of this License, whose permissions for other licensees extend to the
+entire whole, and thus to each and every part regardless of who wrote it.
+
+Thus, it is not the intent of this section to claim rights or contest your
+rights to work written entirely by you; rather, the intent is to exercise the
+right to control the distribution of derivative or collective works based on
+the Program.
+
+In addition, mere aggregation of another work not based on the Program with
+the Program (or with a work based on the Program) on a volume of a storage or
+distribution medium does not bring the other work under the scope of this
+License.
+
+{\bf 3.} You may copy and distribute the Program (or a work based on it, under
+Section 2) in object code or executable form under the terms of Sections 1 and
+2 above provided that you also do one of the following:
+
+\begin{itemize}
+\item {\bf a)} Accompany it with the complete corresponding machine-readable
+ source code, which must be distributed under the terms of Sections 1 and 2
+ above on a medium customarily used for software interchange; or,
+
+\item {\bf b)} Accompany it with a written offer, valid for at least three
+ years, to give any third party, for a charge no more than your cost of
+ physically performing source distribution, a complete machine-readable copy of
+ the corresponding source code, to be distributed under the terms of Sections
+ 1 and 2 above on a medium customarily used for software interchange; or,
+
+\item {\bf c)} Accompany it with the information you received as to the offer
+ to distribute corresponding source code. (This alternative is allowed only
+ for noncommercial distribution and only if you received the program in object
+ code or executable form with such an offer, in accord with Subsection b
+ above.)
+\end{itemize}
+
+The source code for a work means the preferred form of the work for making
+modifications to it. For an executable work, complete source code means all
+the source code for all modules it contains, plus any associated interface
+definition files, plus the scripts used to control compilation and
+installation of the executable. However, as a special exception, the source
+code distributed need not include anything that is normally distributed (in
+either source or binary form) with the major components (compiler, kernel, and
+so on) of the operating system on which the executable runs, unless that
+component itself accompanies the executable.
+
+If distribution of executable or object code is made by offering access to
+copy from a designated place, then offering equivalent access to copy the
+source code from the same place counts as distribution of the source code,
+even though third parties are not compelled to copy the source along with the
+object code.
+
+{\bf 4.} You may not copy, modify, sublicense, or distribute the Program
+except as expressly provided under this License. Any attempt otherwise to
+copy, modify, sublicense or distribute the Program is void, and will
+automatically terminate your rights under this License. However, parties who
+have received copies, or rights, from you under this License will not have
+their licenses terminated so long as such parties remain in full compliance.
+
+{\bf 5.} You are not required to accept this License, since you have not
+signed it. However, nothing else grants you permission to modify or distribute
+the Program or its derivative works. These actions are prohibited by law if
+you do not accept this License. Therefore, by modifying or distributing the
+Program (or any work based on the Program), you indicate your acceptance of
+this License to do so, and all its terms and conditions for copying,
+distributing or modifying the Program or works based on it.
+
+{\bf 6.} Each time you redistribute the Program (or any work based on the
+Program), the recipient automatically receives a license from the original
+licensor to copy, distribute or modify the Program subject to these terms and
+conditions. You may not impose any further restrictions on the recipients'
+exercise of the rights granted herein. You are not responsible for enforcing
+compliance by third parties to this License.
+
+{\bf 7.} If, as a consequence of a court judgment or allegation of patent
+infringement or for any other reason (not limited to patent issues),
+conditions are imposed on you (whether by court order, agreement or otherwise)
+that contradict the conditions of this License, they do not excuse you from
+the conditions of this License. If you cannot distribute so as to satisfy
+simultaneously your obligations under this License and any other pertinent
+obligations, then as a consequence you may not distribute the Program at all.
+For example, if a patent license would not permit royalty-free redistribution
+of the Program by all those who receive copies directly or indirectly through
+you, then the only way you could satisfy both it and this License would be to
+refrain entirely from distribution of the Program.
+
+If any portion of this section is held invalid or unenforceable under any
+particular circumstance, the balance of the section is intended to apply and
+the section as a whole is intended to apply in other circumstances.
+
+It is not the purpose of this section to induce you to infringe any patents or
+other property right claims or to contest validity of any such claims; this
+section has the sole purpose of protecting the integrity of the free software
+distribution system, which is implemented by public license practices. Many
+people have made generous contributions to the wide range of software
+distributed through that system in reliance on consistent application of that
+system; it is up to the author/donor to decide if he or she is willing to
+distribute software through any other system and a licensee cannot impose that
+choice.
+
+This section is intended to make thoroughly clear what is believed to be a
+consequence of the rest of this License.
+
+{\bf 8.} If the distribution and/or use of the Program is restricted in
+certain countries either by patents or by copyrighted interfaces, the original
+copyright holder who places the Program under this License may add an explicit
+geographical distribution limitation excluding those countries, so that
+distribution is permitted only in or among countries not thus excluded. In
+such case, this License incorporates the limitation as if written in the body
+of this License.
+
+{\bf 9.} The Free Software Foundation may publish revised and/or new versions
+of the General Public License from time to time. Such new versions will be
+similar in spirit to the present version, but may differ in detail to address
+new problems or concerns.
+
+Each version is given a distinguishing version number. If the Program
+specifies a version number of this License which applies to it and "any later
+version", you have the option of following the terms and conditions either of
+that version or of any later version published by the Free Software
+Foundation. If the Program does not specify a version number of this License,
+you may choose any version ever published by the Free Software Foundation.
+
+{\bf 10.} If you wish to incorporate parts of the Program into other free
+programs whose distribution conditions are different, write to the author to
+ask for permission. For software which is copyrighted by the Free Software
+Foundation, write to the Free Software Foundation; we sometimes make
+exceptions for this. Our decision will be guided by the two goals of
+preserving the free status of all derivatives of our free software and of
+promoting the sharing and reuse of software generally.
+
+{\bf NO WARRANTY}
+
+{\bf 11.} BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
+FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
+OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE
+THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR
+IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO
+THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM
+PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR
+CORRECTION.
+
+{\bf 12.} IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
+WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
+REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
+INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
+OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO
+LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR
+THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
+EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
+DAMAGES.
+
+END OF TERMS AND CONDITIONS
+
+\section{How to Apply These Terms to Your New Programs}
+\label{SEC4}
+\index[general]{Programs!How to Apply These Terms to Your New }
+\index[general]{How to Apply These Terms to Your New Programs }
+
+If you develop a new program, and you want it to be of the greatest possible
+use to the public, the best way to achieve this is to make it free software
+which everyone can redistribute and change under these terms.
+
+To do so, attach the following notices to the program. It is safest to attach
+them to the start of each source file to most effectively convey the exclusion
+of warranty; and each file should have at least the "copyright" line and a
+pointer to where the full notice is found.
+
+\footnotesize
+\begin{verbatim}
+{\em one line to give the program's name and an idea of what it does.}
+Copyright (C) {\em yyyy} {\em name of author}
+This program is free software; you can redistribute it and/or
+modify it under the terms of the GNU General Public License
+as published by the Free Software Foundation; either version 2
+of the License, or (at your option) any later version.
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU General Public License for more details.
+You should have received a copy of the GNU General Public License
+along with this program; if not, write to the Free Software
+Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+02110-1301 USA
+\end{verbatim}
+\normalsize
+
+Also add information on how to contact you by electronic and paper mail.
+
+If the program is interactive, make it output a short notice like this when it
+starts in an interactive mode:
+
+\footnotesize
+\begin{verbatim}
+Gnomovision version 69, Copyright (C) {\em year} {\em name of author}
+Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
+type `show w'. This is free software, and you are welcome
+to redistribute it under certain conditions; type `show c'
+for details.
+\end{verbatim}
+\normalsize
+
+The hypothetical commands {\tt `show w'} and {\tt `show c'} should show the
+appropriate parts of the General Public License. Of course, the commands you
+use may be called something other than {\tt `show w'} and {\tt `show c'}; they
+could even be mouse-clicks or menu items\verb:--:whatever suits your program.
+
+You should also get your employer (if you work as a programmer) or your
+school, if any, to sign a "copyright disclaimer" for the program, if
+necessary. Here is a sample; alter the names:
+
+\footnotesize
+\begin{verbatim}
+Yoyodyne, Inc., hereby disclaims all copyright
+interest in the program `Gnomovision'
+(which makes passes at compilers) written
+by James Hacker.
+{\em signature of Ty Coon}, 1 April 1989
+Ty Coon, President of Vice
+\end{verbatim}
+\normalsize
+
+This General Public License does not permit incorporating your program into
+proprietary programs. If your program is a subroutine library, you may
+consider it more useful to permit linking proprietary applications with the
+library. If this is what you want to do, use the GNU Library General Public
+License instead of this License.
+Return to
+\elink{GNU's home page}{http://www.gnu.org/home.html}.
+
+FSF \& GNU inquiries \& questions to
+\elink{gnu@gnu.org}{mailto:gnu@gnu.org}. Other
+\elink{ways to contact}{http://www.gnu.org/home.html\#ContactInfo} the FSF.
+
+Comments on these web pages to
+\elink{webmasters@www.gnu.org}{mailto:webmasters@www.gnu.org}, send other
+questions to
+\elink{gnu@gnu.org}{mailto:gnu@gnu.org}.
+
+Copyright notice above.
+Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
+Boston, MA 02110-1301 USA
+
+Updated: 3 Jan 2000 rms
--- /dev/null
+# This module does multiple indices, supporting the style of the LaTex 'index'
+# package.
+
+# Version Information:
+# 16-Feb-2005 -- Original Creation. Karl E. Cunningham
+# 14-Mar-2005 -- Clarified and Consolodated some of the code.
+# Changed to smoothly handle single and multiple indices.
+
+# Two LaTeX index formats are supported...
+# --- SINGLE INDEX ---
+# \usepackage{makeidx}
+# \makeindex
+# \index{entry1}
+# \index{entry2}
+# \index{entry3}
+# ...
+# \printindex
+#
+# --- MULTIPLE INDICES ---
+#
+# \usepackage{makeidx}
+# \usepackage{index}
+# \makeindex -- latex2html doesn't care but LaTeX does.
+# \newindex{ref1}{ext1}{ext2}{title1}
+# \newindex{ref2}{ext1}{ext2}{title2}
+# \newindex{ref3}{ext1}{ext2}{title3}
+# \index[ref1]{entry1}
+# \index[ref1]{entry2}
+# \index[ref3]{entry3}
+# \index[ref2]{entry4}
+# \index{entry5}
+# \index[ref3]{entry6}
+# ...
+# \printindex[ref1]
+# \printindex[ref2]
+# \printindex[ref3]
+# \printindex
+# ___________________
+#
+# For the multiple-index style, each index is identified by the ref argument to \newindex, \index,
+# and \printindex. A default index is allowed, which is indicated by omitting the optional
+# argument. The default index does not require a \newindex command. As \index commands
+# are encountered, their entries are stored according
+# to the ref argument. When the \printindex command is encountered, the stored index
+# entries for that argument are retrieved and printed. The title for each index is taken
+# from the last argument in the \newindex command.
+# While processing \index and \printindex commands, if no argument is given the index entries
+# are built into a default index. The title of the default index is simply "Index".
+# This makes the difference between single- and multiple-index processing trivial.
+#
+# Another method can be used by omitting the \printindex command and just using \include to
+# pull in index files created by the makeindex program. These files will start with
+# \begin{theindex}. This command is used to determine where to print the index. Using this
+# approach, the indices will be output in the same order as the newindex commands were
+# originally found (see below). Using a combination of \printindex and \include{indexfile} has not
+# been tested and may produce undesireable results.
+#
+# The index data are stored in a hash for later sorting and output. As \printindex
+# commands are handled, the order in which they were found in the tex filea is saved,
+# associated with the ref argument to \printindex.
+#
+# We use the original %index hash to store the index data into. We append a \002 followed by the
+# name of the index to isolate the entries in different indices from each other. This is necessary
+# so that different indices can have entries with the same name. For the default index, the \002 is
+# appended without the name.
+#
+# Since the index order in the output cannot be determined if the \include{indexfile}
+# command is used, the order will be assumed from the order in which the \newindex
+# commands were originally seen in the TeX files. This order is saved as well as the
+# order determined from any printindex{ref} commands. If \printindex commnads are used
+# to specify the index output, that order will be used. If the \include{idxfile} command
+# is used, the order of the original newindex commands will be used. In this case the
+# default index will be printed last since it doesn't have a corresponding \newindex
+# command and its order cannot be determined. Mixing \printindex and \include{idxfile}
+# commands in the same file is likely to produce less than satisfactory results.
+#
+#
+# The hash containing index data is named %indices. It contains the following data:
+#{
+# 'title' => {
+# $ref1 => $indextitle ,
+# $ref2 => $indextitle ,
+# ...
+# },
+# 'newcmdorder' => [ ref1, ref2, ..., * ], # asterisk indicates the position of the default index.
+# 'printindorder' => [ ref1, ref2, ..., * ], # asterisk indicates the position of the default index.
+#}
+
+
+# Globals to handle multiple indices.
+my %indices;
+
+# This tells the system to use up to 7 words in index entries.
+$WORDS_IN_INDEX = 10;
+
+# KEC 2-18-05
+# Handles the \newindex command. This is called if the \newindex command is
+# encountered in the LaTex source. Gets the index ref and title from the arguments.
+# Saves the index ref and title.
+# Note that we are called once to handle multiple \newindex commands that are
+# newline-separated.
+sub do_cmd_newindex {
+ my $data = shift;
+ # The data is sent to us as fields delimited by their ID #'s. We extract the
+ # fields.
+ foreach my $line (split("\n",$data)) {
+ my @fields = split (/(?:\<\#\d+?\#\>)+/,$line);
+
+ # The index name and title are the second and fourth fields in the data.
+ if ($line =~ /^</ or $line =~ /^\\newindex/) {
+ my ($indexref,$indextitle) = ($fields[1],$fields[4]);
+ $indices{'title'}{$indexref} = $indextitle;
+ push (@{$indices{'newcmdorder'}},$indexref);
+ }
+ }
+}
+
+
+# KEC -- Copied from makeidx.perl and modified to do multiple indices.
+# Processes an \index entry from the LaTex file.
+# Gets the optional argument from the index command, which is the name of the index
+# into which to place the entry.
+# Drops the brackets from the index_name
+# Puts the index entry into the html stream
+# Creates the tokenized index entry (which also saves the index entry info
+sub do_real_index {
+ local($_) = @_;
+ local($pat,$idx_entry,$index_name);
+ # catches opt-arg from \index commands for index.sty
+ $index_name = &get_next_optional_argument;
+ $index_name = "" unless defined $index_name;
+ # Drop leading and trailing brackets from the index name.
+ $index_name =~ s/^\[|\]$//g;
+
+ $idx_entry = &missing_braces unless (
+ (s/$next_pair_pr_rx/$pat=$1;$idx_entry=$2;''/e)
+ ||(s/$next_pair_rx/$pat=$1;$idx_entry=$2;''/e));
+
+ if ($index_name and defined $idx_entry and
+ !defined $indices{'title'}{$index_name}) {
+ print STDERR "\nInvalid Index Name: \\index \[$index_name\]\{$idx_entry\}\n";
+ }
+
+ $idx_entry = &named_index_entry($pat, $idx_entry,$index_name);
+ $idx_entry.$_;
+}
+
+# Creates and saves an index entry in the index hashes.
+# Modified to do multiple indices.
+# Creates an index_key that allows index entries to have the same characteristics but be in
+# different indices. This index_key is the regular key with the index name appended.
+# Save the index order for the entry in the %index_order hash.
+sub named_index_entry {
+ local($br_id, $str, $index_name) = @_;
+ my ($index_key);
+ # escape the quoting etc characters
+ # ! -> \001
+ # @ -> \002
+ # | -> \003
+ $* = 1; $str =~ s/\n\s*/ /g; $* = 0; # remove any newlines
+ # protect \001 occurring with images
+ $str =~ s/\001/\016/g; # 0x1 to 0xF
+ $str =~ s/\\\\/\011/g; # Double backslash -> 0xB
+ $str =~ s/\\;SPMquot;/\012/g; # \;SPMquot; -> 0xC
+ $str =~ s/;SPMquot;!/\013/g; # ;SPMquot; -> 0xD
+ $str =~ s/!/\001/g; # Exclamation point -> 0x1
+ $str =~ s/\013/!/g; # 0xD -> Exclaimation point
+ $str =~ s/;SPMquot;@/\015/g; # ;SPMquot;@ to 0xF
+ $str =~ s/@/\002/g; # At sign -> 0x2
+ $str =~ s/\015/@/g; # 0xF to At sign
+ $str =~ s/;SPMquot;\|/\017/g; # ;SMPquot;| to 0x11
+ $str =~ s/\|/\003/g; # Vertical line to 0x3
+ $str =~ s/\017/|/g; # 0x11 to vertical line
+ $str =~ s/;SPMquot;(.)/\1/g; # ;SPMquot; -> whatever the next character is
+ $str =~ s/\012/;SPMquot;/g; # 0x12 to ;SPMquot;
+ $str =~ s/\011/\\\\/g; # 0x11 to double backslash
+ local($key_part, $pageref) = split("\003", $str, 2);
+
+ # For any keys of the form: blablabla!blablabla, which want to be split at the
+ # exclamation point, replace the ! with a comma and a space. We don't do it
+ # that way for this index.
+ $key_part =~ s/\001/, /g;
+ local(@keys) = split("\001", $key_part);
+ # If TITLE is not yet available use $before.
+ $TITLE = $saved_title if (($saved_title)&&(!($TITLE)||($TITLE eq $default_title)));
+ $TITLE = $before unless $TITLE;
+ # Save the reference
+ local($words) = '';
+ if ($SHOW_SECTION_NUMBERS) { $words = &make_idxnum; }
+ elsif ($SHORT_INDEX) { $words = &make_shortidxname; }
+ else { $words = &make_idxname; }
+ local($super_key) = '';
+ local($sort_key, $printable_key, $cur_key);
+ foreach $key (@keys) {
+ $key =~ s/\016/\001/g; # revert protected \001s
+ ($sort_key, $printable_key) = split("\002", $key);
+ #
+ # RRM: 16 May 1996
+ # any \label in the printable-key will have already
+ # created a label where the \index occurred.
+ # This has to be removed, so that the desired label
+ # will be found on the Index page instead.
+ #
+ if ($printable_key =~ /tex2html_anchor_mark/ ) {
+ $printable_key =~ s/><tex2html_anchor_mark><\/A><A//g;
+ local($tmpA,$tmpB) = split("NAME=\"", $printable_key);
+ ($tmpA,$tmpB) = split("\"", $tmpB);
+ $ref_files{$tmpA}='';
+ $index_labels{$tmpA} = 1;
+ }
+ #
+ # resolve and clean-up the hyperlink index-entries
+ # so they can be saved in an index.pl file
+ #
+ if ($printable_key =~ /$cross_ref_mark/ ) {
+ local($label,$id,$ref_label);
+ # $printable_key =~ s/$cross_ref_mark#(\w+)#(\w+)>$cross_ref_mark/
+ $printable_key =~ s/$cross_ref_mark#([^#]+)#([^>]+)>$cross_ref_mark/
+ do { ($label,$id) = ($1,$2);
+ $ref_label = $external_labels{$label} unless
+ ($ref_label = $ref_files{$label});
+ '"' . "$ref_label#$label" . '">' .
+ &get_ref_mark($label,$id)}
+ /geo;
+ }
+ $printable_key =~ s/<\#[^\#>]*\#>//go;
+ #RRM
+ # recognise \char combinations, for a \backslash
+ #
+ $printable_key =~ s/\&\#;\'134/\\/g; # restore \\s
+ $printable_key =~ s/\&\#;\`<BR> /\\/g; # ditto
+ $printable_key =~ s/\&\#;*SPMquot;92/\\/g; # ditto
+ #
+ # $sort_key .= "@$printable_key" if !($printable_key); # RRM
+ $sort_key .= "@$printable_key" if !($sort_key); # RRM
+ $sort_key =~ tr/A-Z/a-z/;
+ if ($super_key) {
+ $cur_key = $super_key . "\001" . $sort_key;
+ $sub_index{$super_key} .= $cur_key . "\004";
+ } else {
+ $cur_key = $sort_key;
+ }
+
+ # Append the $index_name to the current key with a \002 delimiter. This will
+ # allow the same index entry to appear in more than one index.
+ $index_key = $cur_key . "\002$index_name";
+
+ $index{$index_key} .= "";
+
+ #
+ # RRM, 15 June 1996
+ # if there is no printable key, but one is known from
+ # a previous index-entry, then use it.
+ #
+ if (!($printable_key) && ($printable_key{$index_key}))
+ { $printable_key = $printable_key{$index_key}; }
+# if (!($printable_key) && ($printable_key{$cur_key}))
+# { $printable_key = $printable_key{$cur_key}; }
+ #
+ # do not overwrite the printable_key if it contains an anchor
+ #
+ if (!($printable_key{$index_key} =~ /tex2html_anchor_mark/ ))
+ { $printable_key{$index_key} = $printable_key || $key; }
+# if (!($printable_key{$cur_key} =~ /tex2html_anchor_mark/ ))
+# { $printable_key{$cur_key} = $printable_key || $key; }
+
+ $super_key = $cur_key;
+ }
+ #
+ # RRM
+ # page-ranges, from |( and |) and |see
+ #
+ if ($pageref) {
+ if ($pageref eq "\(" ) {
+ $pageref = '';
+ $next .= " from ";
+ } elsif ($pageref eq "\)" ) {
+ $pageref = '';
+ local($next) = $index{$index_key};
+# local($next) = $index{$cur_key};
+ # $next =~ s/[\|] *$//;
+ $next =~ s/(\n )?\| $//;
+ $index{$index_key} = "$next to ";
+# $index{$cur_key} = "$next to ";
+ }
+ }
+
+ if ($pageref) {
+ $pageref =~ s/\s*$//g; # remove trailing spaces
+ if (!$pageref) { $pageref = ' ' }
+ $pageref =~ s/see/<i>see <\/i> /g;
+ #
+ # RRM: 27 Dec 1996
+ # check if $pageref corresponds to a style command.
+ # If so, apply it to the $words.
+ #
+ local($tmp) = "do_cmd_$pageref";
+ if (defined &$tmp) {
+ $words = &$tmp("<#0#>$words<#0#>");
+ $words =~ s/<\#[^\#]*\#>//go;
+ $pageref = '';
+ }
+ }
+ #
+ # RRM: 25 May 1996
+ # any \label in the pageref section will have already
+ # created a label where the \index occurred.
+ # This has to be removed, so that the desired label
+ # will be found on the Index page instead.
+ #
+ if ($pageref) {
+ if ($pageref =~ /tex2html_anchor_mark/ ) {
+ $pageref =~ s/><tex2html_anchor_mark><\/A><A//g;
+ local($tmpA,$tmpB) = split("NAME=\"", $pageref);
+ ($tmpA,$tmpB) = split("\"", $tmpB);
+ $ref_files{$tmpA}='';
+ $index_labels{$tmpA} = 1;
+ }
+ #
+ # resolve and clean-up any hyperlinks in the page-ref,
+ # so they can be saved in an index.pl file
+ #
+ if ($pageref =~ /$cross_ref_mark/ ) {
+ local($label,$id,$ref_label);
+ # $pageref =~ s/$cross_ref_mark#(\w+)#(\w+)>$cross_ref_mark/
+ $pageref =~ s/$cross_ref_mark#([^#]+)#([^>]+)>$cross_ref_mark/
+ do { ($label,$id) = ($1,$2);
+ $ref_files{$label} = ''; # ???? RRM
+ if ($index_labels{$label}) { $ref_label = ''; }
+ else { $ref_label = $external_labels{$label}
+ unless ($ref_label = $ref_files{$label});
+ }
+ '"' . "$ref_label#$label" . '">' . &get_ref_mark($label,$id)}/geo;
+ }
+ $pageref =~ s/<\#[^\#>]*\#>//go;
+
+ if ($pageref eq ' ') { $index{$index_key}='@'; }
+ else { $index{$index_key} .= $pageref . "\n | "; }
+ } else {
+ local($thisref) = &make_named_href('',"$CURRENT_FILE#$br_id",$words);
+ $thisref =~ s/\n//g;
+ $index{$index_key} .= $thisref."\n | ";
+ }
+ #print "\nREF: $sort_key : $index_key :$index{$index_key}";
+
+ #join('',"<A NAME=$br_id>$anchor_invisible_mark<\/A>",$_);
+
+ "<A NAME=\"$br_id\">$anchor_invisible_mark<\/A>";
+}
+
+
+# KEC. -- Copied from makeidx.perl, then modified to do multiple indices.
+# Feeds the index entries to the output. This is called for each index to be built.
+#
+# Generates a list of lookup keys for index entries, from both %printable_keys
+# and %index keys.
+# Sorts the keys according to index-sorting rules.
+# Removes keys with a 0x01 token. (duplicates?)
+# Builds a string to go to the index file.
+# Adds the index entries to the string if they belong in this index.
+# Keeps track of which index is being worked on, so only the proper entries
+# are included.
+# Places the index just built in to the output at the proper place.
+{ my $index_number = 0;
+sub add_real_idx {
+ print "\nDoing the index ... Index Number $index_number\n";
+ local($key, @keys, $next, $index, $old_key, $old_html);
+ my ($idx_ref,$keyref);
+ # RRM, 15.6.96: index constructed from %printable_key, not %index
+ @keys = keys %printable_key;
+
+ while (/$idx_mark/) {
+ # Get the index reference from what follows the $idx_mark and
+ # remove it from the string.
+ s/$idxmark\002(.*?)\002/$idxmark/;
+ $idx_ref = $1;
+ $index = '';
+ # include non- makeidx index-entries
+ foreach $key (keys %index) {
+ next if $printable_key{$key};
+ $old_key = $key;
+ if ($key =~ s/###(.*)$//) {
+ next if $printable_key{$key};
+ push (@keys, $key);
+ $printable_key{$key} = $key;
+ if ($index{$old_key} =~ /HREF="([^"]*)"/i) {
+ $old_html = $1;
+ $old_html =~ /$dd?([^#\Q$dd\E]*)#/;
+ $old_html = $1;
+ } else { $old_html = '' }
+ $index{$key} = $index{$old_key} . $old_html."</A>\n | ";
+ };
+ }
+ @keys = sort makeidx_keysort @keys;
+ @keys = grep(!/\001/, @keys);
+ my $cnt = 0;
+ foreach $key (@keys) {
+ my ($keyref) = $key =~ /.*\002(.*)/;
+ next unless ($idx_ref eq $keyref); # KEC.
+ $index .= &add_idx_key($key);
+ $cnt++;
+ }
+ print "$cnt Index Entries Added\n";
+ $index = '<DD>'.$index unless ($index =~ /^\s*<D(D|T)>/);
+ $index_number++; # KEC.
+ if ($SHORT_INDEX) {
+ print "(compact version with Legend)";
+ local($num) = ( $index =~ s/\<D/<D/g );
+ if ($num > 50 ) {
+ s/$idx_mark/$preindex<HR><DL>\n$index\n<\/DL>$preindex/o;
+ } else {
+ s/$idx_mark/$preindex<HR><DL>\n$index\n<\/DL>/o;
+ }
+ } else {
+ s/$idx_mark/<DL COMPACT>\n$index\n<\/DL>/o; }
+ }
+}
+}
+
+# KEC. Copied from latex2html.pl and modified to support multiple indices.
+# The bibliography and the index should be treated as separate sections
+# in their own HTML files. The \bibliography{} command acts as a sectioning command
+# that has the desired effect. But when the bibliography is constructed
+# manually using the thebibliography environment, or when using the
+# theindex environment it is not possible to use the normal sectioning
+# mechanism. This subroutine inserts a \bibliography{} or a dummy
+# \textohtmlindex command just before the appropriate environments
+# to force sectioning.
+sub add_bbl_and_idx_dummy_commands {
+ local($id) = $global{'max_id'};
+
+ s/([\\]begin\s*$O\d+$C\s*thebibliography)/$bbl_cnt++; $1/eg;
+ ## if ($bbl_cnt == 1) {
+ s/([\\]begin\s*$O\d+$C\s*thebibliography)/$id++; "\\bibliography$O$id$C$O$id$C $1"/geo;
+ #}
+ $global{'max_id'} = $id;
+ # KEC. Modified to global substitution to place multiple index tokens.
+ s/[\\]begin\s*($O\d+$C)\s*theindex/\\textohtmlindex$1/go;
+ # KEC. Modified to pick up the optional argument to \printindex
+ s/[\\]printindex\s*(\[.*?\])?/
+ do { (defined $1) ? "\\textohtmlindex $1" : "\\textohtmlindex []"; } /ego;
+ &lib_add_bbl_and_idx_dummy_commands() if defined(&lib_add_bbl_and_idx_dummy_commands);
+}
+
+# KEC. Copied from latex2html.pl and modified to support multiple indices.
+# For each textohtmlindex mark found, determine the index titles and headers.
+# We place the index ref in the header so the proper index can be generated later.
+# For the default index, the index ref is blank.
+#
+# One problem is that this routine is called twice.. Once for processing the
+# command as originally seen, and once for processing the command when
+# doing the name for the index file. We can detect that by looking at the
+# id numbers (or ref) surrounding the \theindex command, and not incrementing
+# index_number unless a new id (or ref) is seen. This has the side effect of
+# having to unconventionally start the index_number at -1. But it works.
+#
+# Gets the title from the list of indices.
+# If this is the first index, save the title in $first_idx_file. This is what's referenced
+# in the navigation buttons.
+# Increment the index_number for next time.
+# If the indexname command is defined or a newcommand defined for indexname, do it.
+# Save the index TITLE in the toc
+# Save the first_idx_file into the idxfile. This goes into the nav buttons.
+# Build index_labels if needed.
+# Create the index headings and put them in the output stream.
+
+{ my $index_number = 0; # Will be incremented before use.
+ my $first_idx_file; # Static
+ my $no_increment = 0;
+
+sub do_cmd_textohtmlindex {
+ local($_) = @_;
+ my ($idxref,$idxnum,$index_name);
+
+ # We get called from make_name with the first argument = "\001noincrement". This is a sign
+ # to not increment $index_number the next time we are called. We get called twice, once
+ # my make_name and once by process_command. Unfortunately, make_name calls us just to set the name
+ # but doesn't use the result so we get called a second time by process_command. This works fine
+ # except for cases where there are multiple indices except if they aren't named, which is the case
+ # when the index is inserted by an include command in latex. In these cases we are only able to use
+ # the index number to decide which index to draw from, and we don't know how to increment that index
+ # number if we get called a variable number of times for the same index, as is the case between
+ # making html (one output file) and web (multiple output files) output formats.
+ if (/\001noincrement/) {
+ $no_increment = 1;
+ return;
+ }
+
+ # Remove (but save) the index reference
+ s/^\s*\[(.*?)\]/{$idxref = $1; "";}/e;
+
+ # If we have an $idxref, the index name was specified. In this case, we have all the
+ # information we need to carry on. Otherwise, we need to get the idxref
+ # from the $index_number and set the name to "Index".
+ if ($idxref) {
+ $index_name = $indices{'title'}{$idxref};
+ } else {
+ if (defined ($idxref = $indices{'newcmdorder'}->[$index_number])) {
+ $index_name = $indices{'title'}{$idxref};
+ } else {
+ $idxref = '';
+ $index_name = "Index";
+ }
+ }
+
+ $idx_title = "Index"; # The name displayed in the nav bar text.
+
+ # Only set $idxfile if we are at the first index. This will point the
+ # navigation panel to the first index file rather than the last.
+ $first_idx_file = $CURRENT_FILE if ($index_number == 0);
+ $idxfile = $first_idx_file; # Pointer for the Index button in the nav bar.
+ $toc_sec_title = $index_name; # Index link text in the toc.
+ $TITLE = $toc_sec_title; # Title for this index, from which its filename is built.
+ if (%index_labels) { &make_index_labels(); }
+ if (($SHORT_INDEX) && (%index_segment)) { &make_preindex(); }
+ else { $preindex = ''; }
+ local $idx_head = $section_headings{'textohtmlindex'};
+ local($heading) = join(''
+ , &make_section_heading($TITLE, $idx_head)
+ , $idx_mark, "\002", $idxref, "\002" );
+ local($pre,$post) = &minimize_open_tags($heading);
+ $index_number++ unless ($no_increment);
+ $no_increment = 0;
+ join('',"<BR>\n" , $pre, $_);
+}
+}
+
+# Returns an index key, given the key passed as the first argument.
+# Not modified for multiple indices.
+sub add_idx_key {
+ local($key) = @_;
+ local($index, $next);
+ if (($index{$key} eq '@' )&&(!($index_printed{$key}))) {
+ if ($SHORT_INDEX) { $index .= "<DD><BR>\n<DT>".&print_key."\n<DD>"; }
+ else { $index .= "<DT><DD><BR>\n<DT>".&print_key."\n<DD>"; }
+ } elsif (($index{$key})&&(!($index_printed{$key}))) {
+ if ($SHORT_INDEX) {
+ $next = "<DD>".&print_key."\n : ". &print_idx_links;
+ } else {
+ $next = "<DT>".&print_key."\n<DD>". &print_idx_links;
+ }
+ $index .= $next."\n";
+ $index_printed{$key} = 1;
+ }
+
+ if ($sub_index{$key}) {
+ local($subkey, @subkeys, $subnext, $subindex);
+ @subkeys = sort(split("\004", $sub_index{$key}));
+ if ($SHORT_INDEX) {
+ $index .= "<DD>".&print_key unless $index_printed{$key};
+ $index .= "<DL>\n";
+ } else {
+ $index .= "<DT>".&print_key."\n<DD>" unless $index_printed{$key};
+ $index .= "<DL COMPACT>\n";
+ }
+ foreach $subkey (@subkeys) {
+ $index .= &add_sub_idx_key($subkey) unless ($index_printed{$subkey});
+ }
+ $index .= "</DL>\n";
+ }
+ return $index;
+}
+
+1; # Must be present as the last line.
--- /dev/null
+# This file serves as a place to put initialization code and constants to
+# affect the behavior of latex2html for generating the bacula manuals.
+
+# $LINKPOINT specifies what filename to use to link to when creating
+# index.html. Not that this is a hard link.
+$LINKPOINT='"$OVERALL_TITLE"';
+
+
+# The following must be the last line of this file.
+1;
--- /dev/null
+%%
+%%
+
+\section*{GNU Lesser General Public License}
+\label{LesserChapter}
+\index[general]{GNU Lesser General Public License }
+\index[general]{License!GNU Lesser General Public }
+
+\elink{image of a Philosophical GNU}
+{\url{http://www.gnu.org/graphics/philosophicalgnu.html}} [
+\elink{English}{\url{http://www.gnu.org/copyleft/lesser.html}} |
+\elink{Japanese}{\url{http://www.gnu.org/copyleft/lesser.ja.html}} ]
+
+\begin{itemize}
+\item
+ \elink{Why you shouldn't use the Lesser GPL for your next
+ library}{\url{http://www.gnu.org/philosophy/why-not-lgpl.html}}
+\item
+ \elink{What to do if you see a possible LGPL
+ violation}{\url{http://www.gnu.org/copyleft/gpl-violation.html}}
+\item
+ \elink{Translations of the LGPL}
+{\url{http://www.gnu.org/copyleft/copyleft.html\#translationsLGPL}}
+\item The GNU Lesser General Public License as a
+ \elink{text file}{\url{http://www.gnu.org/copyleft/lesser.txt}}
+\item The GNU Lesser General Public License as a
+ \elink{Texinfo}{\url{http://www.gnu.org/copyleft/lesser.texi}} file
+ \end{itemize}
+
+
+This GNU Lesser General Public License counts as the successor of the GNU
+Library General Public License. For an explanation of why this change was
+necessary, read the
+\elink{Why you shouldn't use the Lesser GPL for your next
+library}{\url{http://www.gnu.org/philosophy/why-not-lgpl.html}} article.
+
+\section{Table of Contents}
+\index[general]{Table of Contents }
+\index[general]{Contents!Table of }
+
+\begin{itemize}
+\item
+ \label{TOC12}
+ \ilink{GNU LESSER GENERAL PUBLIC LICENSE}{SEC12}
+
+\begin{itemize}
+\item
+ \label{TOC23}
+ \ilink{Preamble}{SEC23}
+\item
+ \label{TOC34}
+ \ilink{TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND
+MODIFICATION}{SEC34}
+\item
+ \label{TOC45}
+ \ilink{How to Apply These Terms to Your New Libraries}{SEC45}
+\end{itemize}
+
+\end{itemize}
+
+
+\section{GNU LESSER GENERAL PUBLIC LICENSE}
+\label{SEC12}
+\index[general]{LICENSE!GNU LESSER GENERAL PUBLIC }
+\index[general]{GNU LESSER GENERAL PUBLIC LICENSE }
+
+Version 2.1, February 1999
+
+\footnotesize
+\begin{verbatim}
+Copyright (C) 1991, 1999 Free Software Foundation, Inc.
+51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+[This is the first released version of the Lesser GPL. It also counts
+ as the successor of the GNU Library Public License, version 2, hence
+ the version number 2.1.]
+\end{verbatim}
+\normalsize
+
+\section{Preamble}
+\label{SEC23}
+\index[general]{Preamble }
+
+The licenses for most software are designed to take away your freedom to share
+and change it. By contrast, the GNU General Public Licenses are intended to
+guarantee your freedom to share and change free software\verb:--:to make sure the
+software is free for all its users.
+
+This license, the Lesser General Public License, applies to some specially
+designated software packages\verb:--:typically libraries\verb:--:of the Free Software
+Foundation and other authors who decide to use it. You can use it too, but we
+suggest you first think carefully about whether this license or the ordinary
+General Public License is the better strategy to use in any particular case,
+based on the explanations below.
+
+When we speak of free software, we are referring to freedom of use, not price.
+Our General Public Licenses are designed to make sure that you have the
+freedom to distribute copies of free software (and charge for this service if
+you wish); that you receive source code or can get it if you want it; that you
+can change the software and use pieces of it in new free programs; and that
+you are informed that you can do these things.
+
+To protect your rights, we need to make restrictions that forbid distributors
+to deny you these rights or to ask you to surrender these rights. These
+restrictions translate to certain responsibilities for you if you distribute
+copies of the library or if you modify it.
+
+For example, if you distribute copies of the library, whether gratis or for a
+fee, you must give the recipients all the rights that we gave you. You must
+make sure that they, too, receive or can get the source code. If you link
+other code with the library, you must provide complete object files to the
+recipients, so that they can relink them with the library after making changes
+to the library and recompiling it. And you must show them these terms so they
+know their rights.
+
+We protect your rights with a two-step method: (1) we copyright the library,
+and (2) we offer you this license, which gives you legal permission to copy,
+distribute and/or modify the library.
+
+To protect each distributor, we want to make it very clear that there is no
+warranty for the free library. Also, if the library is modified by someone
+else and passed on, the recipients should know that what they have is not the
+original version, so that the original author's reputation will not be
+affected by problems that might be introduced by others.
+
+Finally, software patents pose a constant threat to the existence of any free
+program. We wish to make sure that a company cannot effectively restrict the
+users of a free program by obtaining a restrictive license from a patent
+holder. Therefore, we insist that any patent license obtained for a version of
+the library must be consistent with the full freedom of use specified in this
+license.
+
+Most GNU software, including some libraries, is covered by the ordinary GNU
+General Public License. This license, the GNU Lesser General Public License,
+applies to certain designated libraries, and is quite different from the
+ordinary General Public License. We use this license for certain libraries in
+order to permit linking those libraries into non-free programs.
+
+When a program is linked with a library, whether statically or using a shared
+library, the combination of the two is legally speaking a combined work, a
+derivative of the original library. The ordinary General Public License
+therefore permits such linking only if the entire combination fits its
+criteria of freedom. The Lesser General Public License permits more lax
+criteria for linking other code with the library.
+
+We call this license the "Lesser" General Public License because it does
+Less to protect the user's freedom than the ordinary General Public License.
+It also provides other free software developers Less of an advantage over
+competing non-free programs. These disadvantages are the reason we use the
+ordinary General Public License for many libraries. However, the Lesser
+license provides advantages in certain special circumstances.
+
+For example, on rare occasions, there may be a special need to encourage the
+widest possible use of a certain library, so that it becomes a de-facto
+standard. To achieve this, non-free programs must be allowed to use the
+library. A more frequent case is that a free library does the same job as
+widely used non-free libraries. In this case, there is little to gain by
+limiting the free library to free software only, so we use the Lesser General
+Public License.
+
+In other cases, permission to use a particular library in non-free programs
+enables a greater number of people to use a large body of free software. For
+example, permission to use the GNU C Library in non-free programs enables many
+more people to use the whole GNU operating system, as well as its variant, the
+GNU/Linux operating system.
+
+Although the Lesser General Public License is Less protective of the users'
+freedom, it does ensure that the user of a program that is linked with the
+Library has the freedom and the wherewithal to run that program using a
+modified version of the Library.
+
+The precise terms and conditions for copying, distribution and modification
+follow. Pay close attention to the difference between a "work based on the
+library" and a "work that uses the library". The former contains code
+derived from the library, whereas the latter must be combined with the library
+in order to run.
+
+\section{TERMS AND CONDITIONS}
+\label{SEC34}
+\index[general]{CONDITIONS!TERMS AND }
+\index[general]{TERMS AND CONDITIONS }
+
+TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+{\bf 0.} This License Agreement applies to any software library or other
+program which contains a notice placed by the copyright holder or other
+authorized party saying it may be distributed under the terms of this Lesser
+General Public License (also called "this License"). Each licensee is
+addressed as "you".
+
+A "library" means a collection of software functions and/or data prepared so
+as to be conveniently linked with application programs (which use some of
+those functions and data) to form executables.
+
+The "Library", below, refers to any such software library or work which has
+been distributed under these terms. A "work based on the Library" means
+either the Library or any derivative work under copyright law: that is to say,
+a work containing the Library or a portion of it, either verbatim or with
+modifications and/or translated straightforwardly into another language.
+(Hereinafter, translation is included without limitation in the term
+"modification".)
+
+"Source code" for a work means the preferred form of the work for making
+modifications to it. For a library, complete source code means all the source
+code for all modules it contains, plus any associated interface definition
+files, plus the scripts used to control compilation and installation of the
+library.
+
+Activities other than copying, distribution and modification are not covered
+by this License; they are outside its scope. The act of running a program
+using the Library is not restricted, and output from such a program is covered
+only if its contents constitute a work based on the Library (independent of
+the use of the Library in a tool for writing it). Whether that is true depends
+on what the Library does and what the program that uses the Library does.
+
+{\bf 1.} You may copy and distribute verbatim copies of the Library's complete
+source code as you receive it, in any medium, provided that you conspicuously
+and appropriately publish on each copy an appropriate copyright notice and
+disclaimer of warranty; keep intact all the notices that refer to this License
+and to the absence of any warranty; and distribute a copy of this License
+along with the Library.
+
+You may charge a fee for the physical act of transferring a copy, and you may
+at your option offer warranty protection in exchange for a fee.
+
+{\bf 2.} You may modify your copy or copies of the Library or any portion of
+it, thus forming a work based on the Library, and copy and distribute such
+modifications or work under the terms of Section 1 above, provided that you
+also meet all of these conditions:
+
+\begin{itemize}
+\item {\bf a)} The modified work must itself be a software library.
+\item {\bf b)} You must cause the files modified to carry prominent notices
+ stating that you changed the files and the date of any change.
+\item {\bf c)} You must cause the whole of the work to be licensed at no
+ charge to all third parties under the terms of this License.
+\item {\bf d)} If a facility in the modified Library refers to a function or
+ a table of data to be supplied by an application program that uses the
+ facility, other than as an argument passed when the facility is invoked, then
+you must make a good faith effort to ensure that, in the event an application
+does not supply such function or table, the facility still operates, and
+performs whatever part of its purpose remains meaningful.
+
+(For example, a function in a library to compute square roots has a purpose
+that is entirely well-defined independent of the application. Therefore,
+Subsection 2d requires that any application-supplied function or table used
+by this function must be optional: if the application does not supply it, the
+square root function must still compute square roots.)
+
+These requirements apply to the modified work as a whole. If identifiable
+sections of that work are not derived from the Library, and can be reasonably
+considered independent and separate works in themselves, then this License,
+and its terms, do not apply to those sections when you distribute them as
+separate works. But when you distribute the same sections as part of a whole
+which is a work based on the Library, the distribution of the whole must be
+on the terms of this License, whose permissions for other licensees extend to
+the entire whole, and thus to each and every part regardless of who wrote
+it.
+
+Thus, it is not the intent of this section to claim rights or contest your
+rights to work written entirely by you; rather, the intent is to exercise the
+right to control the distribution of derivative or collective works based on
+the Library.
+
+In addition, mere aggregation of another work not based on the Library with
+the Library (or with a work based on the Library) on a volume of a storage or
+distribution medium does not bring the other work under the scope of this
+License.
+\end{itemize}
+
+{\bf 3.} You may opt to apply the terms of the ordinary GNU General Public
+License instead of this License to a given copy of the Library. To do this,
+you must alter all the notices that refer to this License, so that they refer
+to the ordinary GNU General Public License, version 2, instead of to this
+License. (If a newer version than version 2 of the ordinary GNU General Public
+License has appeared, then you can specify that version instead if you wish.)
+Do not make any other change in these notices.
+
+Once this change is made in a given copy, it is irreversible for that copy, so
+the ordinary GNU General Public License applies to all subsequent copies and
+derivative works made from that copy.
+
+This option is useful when you wish to copy part of the code of the Library
+into a program that is not a library.
+
+{\bf 4.} You may copy and distribute the Library (or a portion or derivative
+of it, under Section 2) in object code or executable form under the terms of
+Sections 1 and 2 above provided that you accompany it with the complete
+corresponding machine-readable source code, which must be distributed under
+the terms of Sections 1 and 2 above on a medium customarily used for software
+interchange.
+
+If distribution of object code is made by offering access to copy from a
+designated place, then offering equivalent access to copy the source code from
+the same place satisfies the requirement to distribute the source code, even
+though third parties are not compelled to copy the source along with the
+object code.
+
+{\bf 5.} A program that contains no derivative of any portion of the Library,
+but is designed to work with the Library by being compiled or linked with it,
+is called a "work that uses the Library". Such a work, in isolation, is not
+a derivative work of the Library, and therefore falls outside the scope of
+this License.
+
+However, linking a "work that uses the Library" with the Library creates an
+executable that is a derivative of the Library (because it contains portions
+of the Library), rather than a "work that uses the library". The executable
+is therefore covered by this License. Section 6 states terms for distribution
+of such executables.
+
+When a "work that uses the Library" uses material from a header file that is
+part of the Library, the object code for the work may be a derivative work of
+the Library even though the source code is not. Whether this is true is
+especially significant if the work can be linked without the Library, or if
+the work is itself a library. The threshold for this to be true is not
+precisely defined by law.
+
+If such an object file uses only numerical parameters, data structure layouts
+and accessors, and small macros and small inline functions (ten lines or less
+in length), then the use of the object file is unrestricted, regardless of
+whether it is legally a derivative work. (Executables containing this object
+code plus portions of the Library will still fall under Section 6.)
+
+Otherwise, if the work is a derivative of the Library, you may distribute the
+object code for the work under the terms of Section 6. Any executables
+containing that work also fall under Section 6, whether or not they are linked
+directly with the Library itself.
+
+{\bf 6.} As an exception to the Sections above, you may also combine or link a
+"work that uses the Library" with the Library to produce a work containing
+portions of the Library, and distribute that work under terms of your choice,
+provided that the terms permit modification of the work for the customer's own
+use and reverse engineering for debugging such modifications.
+
+You must give prominent notice with each copy of the work that the Library is
+used in it and that the Library and its use are covered by this License. You
+must supply a copy of this License. If the work during execution displays
+copyright notices, you must include the copyright notice for the Library among
+them, as well as a reference directing the user to the copy of this License.
+Also, you must do one of these things:
+
+\begin{itemize}
+\item {\bf a)} Accompany the work with the complete corresponding
+ machine-readable source code for the Library including whatever changes were
+ used in the work (which must be distributed under Sections 1 and 2 above);
+and, if the work is an executable linked with the Library, with the complete
+machine-readable "work that uses the Library", as object code and/or source
+code, so that the user can modify the Library and then relink to produce a
+modified executable containing the modified Library. (It is understood that
+the user who changes the contents of definitions files in the Library will
+not necessarily be able to recompile the application to use the modified
+definitions.)
+\item {\bf b)} Use a suitable shared library mechanism for linking with the
+ Library. A suitable mechanism is one that (1) uses at run time a copy of the
+ library already present on the user's computer system, rather than copying
+library functions into the executable, and (2) will operate properly with a
+modified version of the library, if the user installs one, as long as the
+modified version is interface-compatible with the version that the work was
+made with.
+\item {\bf c)} Accompany the work with a written offer, valid for at least
+ three years, to give the same user the materials specified in Subsection 6a,
+ above, for a charge no more than the cost of performing this distribution.
+\item {\bf d)} If distribution of the work is made by offering access to copy
+ from a designated place, offer equivalent access to copy the above specified
+ materials from the same place.
+\item {\bf e)} Verify that the user has already received a copy of these
+ materials or that you have already sent this user a copy.
+ \end{itemize}
+
+For an executable, the required form of the "work that uses the Library"
+must include any data and utility programs needed for reproducing the
+executable from it. However, as a special exception, the materials to be
+distributed need not include anything that is normally distributed (in either
+source or binary form) with the major components (compiler, kernel, and so on)
+of the operating system on which the executable runs, unless that component
+itself accompanies the executable.
+
+It may happen that this requirement contradicts the license restrictions of
+other proprietary libraries that do not normally accompany the operating
+system. Such a contradiction means you cannot use both them and the Library
+together in an executable that you distribute.
+
+{\bf 7.} You may place library facilities that are a work based on the Library
+side-by-side in a single library together with other library facilities not
+covered by this License, and distribute such a combined library, provided that
+the separate distribution of the work based on the Library and of the other
+library facilities is otherwise permitted, and provided that you do these two
+things:
+
+\begin{itemize}
+\item {\bf a)} Accompany the combined library with a copy of the same work
+ based on the Library, uncombined with any other library facilities. This must
+ be distributed under the terms of the Sections above.
+\item {\bf b)} Give prominent notice with the combined library of the fact
+ that part of it is a work based on the Library, and explaining where to find
+ the accompanying uncombined form of the same work.
+\end{itemize}
+
+{\bf 8.} You may not copy, modify, sublicense, link with, or distribute the
+Library except as expressly provided under this License. Any attempt otherwise
+to copy, modify, sublicense, link with, or distribute the Library is void, and
+will automatically terminate your rights under this License. However, parties
+who have received copies, or rights, from you under this License will not have
+their licenses terminated so long as such parties remain in full compliance.
+
+{\bf 9.} You are not required to accept this License, since you have not
+signed it. However, nothing else grants you permission to modify or distribute
+the Library or its derivative works. These actions are prohibited by law if
+you do not accept this License. Therefore, by modifying or distributing the
+Library (or any work based on the Library), you indicate your acceptance of
+this License to do so, and all its terms and conditions for copying,
+distributing or modifying the Library or works based on it.
+
+{\bf 10.} Each time you redistribute the Library (or any work based on the
+Library), the recipient automatically receives a license from the original
+licensor to copy, distribute, link with or modify the Library subject to these
+terms and conditions. You may not impose any further restrictions on the
+recipients' exercise of the rights granted herein. You are not responsible for
+enforcing compliance by third parties with this License.
+
+{\bf 11.} If, as a consequence of a court judgment or allegation of patent
+infringement or for any other reason (not limited to patent issues),
+conditions are imposed on you (whether by court order, agreement or otherwise)
+that contradict the conditions of this License, they do not excuse you from
+the conditions of this License. If you cannot distribute so as to satisfy
+simultaneously your obligations under this License and any other pertinent
+obligations, then as a consequence you may not distribute the Library at all.
+For example, if a patent license would not permit royalty-free redistribution
+of the Library by all those who receive copies directly or indirectly through
+you, then the only way you could satisfy both it and this License would be to
+refrain entirely from distribution of the Library.
+
+If any portion of this section is held invalid or unenforceable under any
+particular circumstance, the balance of the section is intended to apply, and
+the section as a whole is intended to apply in other circumstances.
+
+It is not the purpose of this section to induce you to infringe any patents or
+other property right claims or to contest validity of any such claims; this
+section has the sole purpose of protecting the integrity of the free software
+distribution system which is implemented by public license practices. Many
+people have made generous contributions to the wide range of software
+distributed through that system in reliance on consistent application of that
+system; it is up to the author/donor to decide if he or she is willing to
+distribute software through any other system and a licensee cannot impose that
+choice.
+
+This section is intended to make thoroughly clear what is believed to be a
+consequence of the rest of this License.
+
+{\bf 12.} If the distribution and/or use of the Library is restricted in
+certain countries either by patents or by copyrighted interfaces, the original
+copyright holder who places the Library under this License may add an explicit
+geographical distribution limitation excluding those countries, so that
+distribution is permitted only in or among countries not thus excluded. In
+such case, this License incorporates the limitation as if written in the body
+of this License.
+
+{\bf 13.} The Free Software Foundation may publish revised and/or new versions
+of the Lesser General Public License from time to time. Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+Each version is given a distinguishing version number. If the Library
+specifies a version number of this License which applies to it and "any later
+version", you have the option of following the terms and conditions either of
+that version or of any later version published by the Free Software
+Foundation. If the Library does not specify a license version number, you may
+choose any version ever published by the Free Software Foundation.
+
+{\bf 14.} If you wish to incorporate parts of the Library into other free
+programs whose distribution conditions are incompatible with these, write to
+the author to ask for permission. For software which is copyrighted by the
+Free Software Foundation, write to the Free Software Foundation; we sometimes
+make exceptions for this. Our decision will be guided by the two goals of
+preserving the free status of all derivatives of our free software and of
+promoting the sharing and reuse of software generally.
+
+{\bf NO WARRANTY}
+
+{\bf 15.} BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
+FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
+OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE
+THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR
+IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO
+THE QUALITY AND PERFORMANCE OF THE LIBRARY IS WITH YOU. SHOULD THE LIBRARY
+PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR
+CORRECTION.
+
+{\bf 16.} IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
+WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
+REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
+INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
+OUT OF THE USE OR INABILITY TO USE THE LIBRARY (INCLUDING BUT NOT LIMITED TO
+LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR
+THIRD PARTIES OR A FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE),
+EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
+DAMAGES.
+
+END OF TERMS AND CONDITIONS
+
+\section{How to Apply These Terms to Your New Libraries}
+\label{SEC45}
+\index[general]{Libraries!How to Apply These Terms to Your New }
+\index[general]{How to Apply These Terms to Your New Libraries }
+
+
+If you develop a new library, and you want it to be of the greatest possible
+use to the public, we recommend making it free software that everyone can
+redistribute and change. You can do so by permitting redistribution under
+these terms (or, alternatively, under the terms of the ordinary General Public
+License).
+
+To apply these terms, attach the following notices to the library. It is
+safest to attach them to the start of each source file to most effectively
+convey the exclusion of warranty; and each file should have at least the
+"copyright" line and a pointer to where the full notice is found.
+
+\footnotesize
+\begin{verbatim}
+{\it one line to give the library's name and an idea of what it does.}
+Copyright (C) {\it year} {\it name of author}
+This library is free software; you can redistribute it and/or
+modify it under the terms of the GNU Lesser General Public
+License as published by the Free Software Foundation; either
+version 2.1 of the License, or (at your option) any later version.
+This library is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+Lesser General Public License for more details.
+You should have received a copy of the GNU Lesser General Public
+License along with this library; if not, write to the Free Software
+Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301
+USA
+\end{verbatim}
+\normalsize
+
+Also add information on how to contact you by electronic and paper mail.
+
+You should also get your employer (if you work as a programmer) or your
+school, if any, to sign a "copyright disclaimer" for the library, if
+necessary. Here is a sample; alter the names:
+
+\footnotesize
+\begin{verbatim}
+Yoyodyne, Inc., hereby disclaims all copyright interest in
+the library "Frob" (a library for tweaking knobs) written
+by James Random Hacker.
+{\it signature of Ty Coon}, 1 April 1990
+Ty Coon, President of Vice
+\end{verbatim}
+\normalsize
+
+That's all there is to it!
+Return to
+\elink{GNU's home page}{\url{http://www.gnu.org/home.html}}.
+
+FSF \& GNU inquiries \& questions to
+\elink{gnu@gnu.org}{mailto:gnu@gnu.org}. Other
+\elink{ways to contact}{\url{http://www.gnu.org/home.html\#ContactInfo}} the FSF.
+
+Comments on these web pages to
+\elink{webmasters@www.gnu.org}{mailto:webmasters@www.gnu.org}, send other
+questions to
+\elink{gnu@gnu.org}{mailto:gnu@gnu.org}.
+
+Copyright notice above.
+Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
+Boston, MA 02110-1301 USA
+USA
+
+Updated: 27 Nov 2000 paulv
--- /dev/null
+%%
+%%
+
+\chapter{Bacula Copyright, Trademark, and Licenses}
+\label{LicenseChapter}
+\index[general]{Licenses!Bacula Copyright Trademark}
+\index[general]{Bacula Copyright, Trademark, and Licenses}
+
+There are a number of different licenses that are used in Bacula.
+If you have a printed copy of this manual, the details of each of
+the licenses referred to in this chapter can be found in the
+online version of the manual at
+\elink{http://www.bacula.org}{\url{http://www.bacula.org}}.
+
+\section{FDL}
+\index[general]{FDL }
+
+The GNU Free Documentation License (FDL) is used for this manual,
+which is a free and open license. This means that you may freely
+reproduce it and even make changes to it. However, rather than
+distribute your own version of this manual, we would much prefer
+if you would send any corrections or changes to the Bacula project.
+
+The most recent version of the manual can always be found online
+at \elink{http://www.bacula.org}{\url{http://www.bacula.org}}.
+
+% TODO: Point to appendix that has it
+
+
+\section{GPL}
+\index[general]{GPL }
+
+The vast bulk of the source code is released under the
+\ilink{GNU General Public License version 2.}{GplChapter}.
+
+Most of this code is copyrighted: Copyright \copyright 2000-2007
+Free Software Foundation Europe e.V.
+
+Portions may be copyrighted by other people (ATT, the Free Software
+Foundation, ...). These files are released under the GPL license.
+
+\section{LGPL}
+\index[general]{LGPL }
+
+Some of the Bacula library source code is released under the
+\ilink{GNU Lesser General Public License.}{LesserChapter} This
+permits third parties to use these parts of our code in their proprietary
+programs to interface to Bacula.
+
+\section{Public Domain}
+\index[general]{Domain!Public }
+\index[general]{Public Domain }
+
+Some of the Bacula code, or code that Bacula references, has been released
+to the public domain. E.g. md5.c, SQLite.
+
+\section{Trademark}
+\index[general]{Trademark }
+
+Bacula\raisebox{.6ex}{\textsuperscript{\textregistered}} is a registered
+trademark of John Walker.
+
+We have trademarked the Bacula name to ensure that any program using the
+name Bacula will be exactly compatible with the program that we have
+released. The use of the name Bacula is restricted to software systems
+that agree exactly with the program presented here.
+
+\section{Fiduciary License Agreement}
+\index[general]{Fiduciary License Agreement }
+Developers who have contributed significant changes to the Bacula code
+should have signed a Fiduciary License Agreement (FLA), which
+guarantees them the right to use the code they have developed, and also
+ensures that the Free Software Foundation Europe (and thus the Bacula
+project) has the rights to the code. This Fiduciary License Agreement
+is found on the Bacula web site at:
+
+\elink{http://www.bacula.org/FLA-bacula.en.pdf}{\url{http://www.bacula.org/FLA-bacula.en.pdf}}
+
+and should be filled out then sent to:
+
+\begin{quote}
+ Free Software Foundation Europe \\
+ Freedom Task Force \\
+ Sumatrastrasse 25 \\
+ 8006 Z\"{u}rich \\
+ Switzerland \\
+\end{quote}
+
+Please note that the above address is different from the officially
+registered office mentioned in the document. When you send in such a
+complete document, please notify me: kern at sibbald dot com.
+
+
+\section{Disclaimer}
+\index[general]{Disclaimer }
+
+NO WARRANTY
+
+BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE
+PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE
+STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE
+PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED,
+INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND
+PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE,
+YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY
+COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE
+PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
+GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE
+OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR
+DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR
+A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH
+HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
--- /dev/null
+
+\chapter{Migration}
+\label{MigrationChapter}
+\index[general]{Migration}
+
+The term Migration, as used in the context of Bacula, means moving data from
+one Volume to another. In particular it refers to a Job (similar to a backup
+job) that reads data that was previously backed up to a Volume and writes
+it to another Volume. As part of this process, the File catalog records
+associated with the first backup job are purged. In other words, Migration
+moves Bacula Job data from one Volume to another by reading the Job data
+from the Volume it is stored on, writing it to a different Volume in a
+different Pool, and then purging the database records for the first Job.
+
+The section process for which Job or Jobs are migrated
+can be based on quite a number of different criteria such as:
+\begin{itemize}
+\item a single previous Job
+\item a Volume
+\item a Client
+\item a regular expression matching a Job, Volume, or Client name
+\item the time a Job has been on a Volume
+\item high and low water marks (usage or occupation) of a Pool
+\item Volume size
+\end{itemize}
+
+The details of these selection criteria will be defined below.
+
+To run a Migration job, you must first define a Job resource very similar
+to a Backup Job but with {\bf Type = Migrate} instead of {\bf Type =
+Backup}. One of the key points to remember is that the Pool that is
+specified for the migration job is the only pool from which jobs will
+be migrated, with one exception noted below. In addition, the Pool to
+which the selected Job or Jobs will be migrated is defined by the {\bf
+Next Pool = ...} in the Pool resource specified for the Migration Job.
+
+Bacula permits pools to contain Volumes with different Media Types.
+However, when doing migration, this is a very undesirable condition. For
+migration to work properly, you should use pools containing only Volumes of
+the same Media Type for all migration jobs.
+
+The migration job normally is either manually started or starts
+from a Schedule much like a backup job. It searches
+for a previous backup Job or Jobs that match the parameters you have
+specified in the migration Job resource, primarily a {\bf Selection Type}
+(detailed a bit later). Then for
+each previous backup JobId found, the Migration Job will run a new Job which
+copies the old Job data from the previous Volume to a new Volume in
+the Migration Pool. It is possible that no prior Jobs are found for
+migration, in which case, the Migration job will simply terminate having
+done nothing, but normally at a minimum, three jobs are involved during a
+migration:
+
+\begin{itemize}
+\item The currently running Migration control Job. This is only
+ a control job for starting the migration child jobs.
+\item The previous Backup Job (already run). The File records
+ for this Job are purged if the Migration job successfully
+ terminates. The original data remains on the Volume until
+ it is recycled and rewritten.
+\item A new Migration Backup Job that moves the data from the
+ previous Backup job to the new Volume. If you subsequently
+ do a restore, the data will be read from this Job.
+\end{itemize}
+
+If the Migration control job finds a number of JobIds to migrate (e.g.
+it is asked to migrate one or more Volumes), it will start one new
+migration backup job for each JobId found on the specified Volumes.
+Please note that Migration doesn't scale too well since Migrations are
+done on a Job by Job basis. This if you select a very large volume or
+a number of volumes for migration, you may have a large number of
+Jobs that start. Because each job must read the same Volume, they will
+run consecutively (not simultaneously).
+
+\section{Migration Job Resource Directives}
+
+The following directives can appear in a Director's Job resource, and they
+are used to define a Migration job.
+
+\begin{description}
+\item [Pool = \lt{}Pool-name\gt{}] The Pool specified in the Migration
+ control Job is not a new directive for the Job resource, but it is
+ particularly important because it determines what Pool will be examined for
+ finding JobIds to migrate. The exception to this is when {\bf Selection
+ Type = SQLQuery}, in which case no Pool is used, unless you
+ specifically include it in the SQL query. Note, the Pool resource
+ referenced must contain a {\bf Next Pool = ...} directive to define
+ the Pool to which the data will be migrated.
+
+\item [Type = Migrate]
+ {\bf Migrate} is a new type that defines the job that is run as being a
+ Migration Job. A Migration Job is a sort of control job and does not have
+ any Files associated with it, and in that sense they are more or less like
+ an Admin job. Migration jobs simply check to see if there is anything to
+ Migrate then possibly start and control new Backup jobs to migrate the data
+ from the specified Pool to another Pool.
+
+\item [Selection Type = \lt{}Selection-type-keyword\gt{}]
+ The \lt{}Selection-type-keyword\gt{} determines how the migration job
+ will go about selecting what JobIds to migrate. In most cases, it is
+ used in conjunction with a {\bf Selection Pattern} to give you fine
+ control over exactly what JobIds are selected. The possible values
+ for \lt{}Selection-type-keyword\gt{} are:
+ \begin{description}
+ \item [SmallestVolume] This selection keyword selects the volume with the
+ fewest bytes from the Pool to be migrated. The Pool to be migrated
+ is the Pool defined in the Migration Job resource. The migration
+ control job will then start and run one migration backup job for
+ each of the Jobs found on this Volume. The Selection Pattern, if
+ specified, is not used.
+
+ \item [OldestVolume] This selection keyword selects the volume with the
+ oldest last write time in the Pool to be migrated. The Pool to be
+ migrated is the Pool defined in the Migration Job resource. The
+ migration control job will then start and run one migration backup
+ job for each of the Jobs found on this Volume. The Selection
+ Pattern, if specified, is not used.
+
+ \item [Client] The Client selection type, first selects all the Clients
+ that have been backed up in the Pool specified by the Migration
+ Job resource, then it applies the {\bf Selection Pattern} (defined
+ below) as a regular expression to the list of Client names, giving
+ a filtered Client name list. All jobs that were backed up for those
+ filtered (regexed) Clients will be migrated.
+ The migration control job will then start and run one migration
+ backup job for each of the JobIds found for those filtered Clients.
+
+ \item [Volume] The Volume selection type, first selects all the Volumes
+ that have been backed up in the Pool specified by the Migration
+ Job resource, then it applies the {\bf Selection Pattern} (defined
+ below) as a regular expression to the list of Volume names, giving
+ a filtered Volume list. All JobIds that were backed up for those
+ filtered (regexed) Volumes will be migrated.
+ The migration control job will then start and run one migration
+ backup job for each of the JobIds found on those filtered Volumes.
+
+ \item [Job] The Job selection type, first selects all the Jobs (as
+ defined on the {\bf Name} directive in a Job resource)
+ that have been backed up in the Pool specified by the Migration
+ Job resource, then it applies the {\bf Selection Pattern} (defined
+ below) as a regular expression to the list of Job names, giving
+ a filtered Job name list. All JobIds that were run for those
+ filtered (regexed) Job names will be migrated. Note, for a given
+ Job named, they can be many jobs (JobIds) that ran.
+ The migration control job will then start and run one migration
+ backup job for each of the Jobs found.
+
+ \item [SQLQuery] The SQLQuery selection type, used the {\bf Selection
+ Pattern} as an SQL query to obtain the JobIds to be migrated.
+ The Selection Pattern must be a valid SELECT SQL statement for your
+ SQL engine, and it must return the JobId as the first field
+ of the SELECT.
+
+ \item [PoolOccupancy] This selection type will cause the Migration job
+ to compute the total size of the specified pool for all Media Types
+ combined. If it exceeds the {\bf Migration High Bytes} defined in
+ the Pool, the Migration job will migrate all JobIds beginning with
+ the oldest Volume in the pool (determined by Last Write time) until
+ the Pool bytes drop below the {\bf Migration Low Bytes} defined in the
+ Pool. This calculation should be consider rather approximative because
+ it is made once by the Migration job before migration is begun, and
+ thus does not take into account additional data written into the Pool
+ during the migration. In addition, the calculation of the total Pool
+ byte size is based on the Volume bytes saved in the Volume (Media)
+database
+ entries. The bytes calculate for Migration is based on the value stored
+ in the Job records of the Jobs to be migrated. These do not include the
+ Storage daemon overhead as is in the total Pool size. As a consequence,
+ normally, the migration will migrate more bytes than strictly necessary.
+
+ \item [PoolTime] The PoolTime selection type will cause the Migration job to
+ look at the time each JobId has been in the Pool since the job ended.
+ All Jobs in the Pool longer than the time specified on {\bf Migration Time}
+ directive in the Pool resource will be migrated.
+ \end{description}
+
+\item [Selection Pattern = \lt{}Quoted-string\gt{}]
+ The Selection Patterns permitted for each Selection-type-keyword are
+ described above.
+
+ For the OldestVolume and SmallestVolume, this
+ Selection pattern is not used (ignored).
+
+ For the Client, Volume, and Job
+ keywords, this pattern must be a valid regular expression that will filter
+ the appropriate item names found in the Pool.
+
+ For the SQLQuery keyword, this pattern must be a valid SELECT SQL statement
+ that returns JobIds.
+
+\end{description}
+
+\section{Migration Pool Resource Directives}
+
+The following directives can appear in a Director's Pool resource, and they
+are used to define a Migration job.
+
+\begin{description}
+\item [Migration Time = \lt{}time-specification\gt{}]
+ If a PoolTime migration is done, the time specified here in seconds (time
+ modifiers are permitted -- e.g. hours, ...) will be used. If the
+ previous Backup Job or Jobs selected have been in the Pool longer than
+ the specified PoolTime, then they will be migrated.
+
+\item [Migration High Bytes = \lt{}byte-specification\gt{}]
+ This directive specifies the number of bytes in the Pool which will
+ trigger a migration if a {\bf PoolOccupancy} migration selection
+ type has been specified. The fact that the Pool
+ usage goes above this level does not automatically trigger a migration
+ job. However, if a migration job runs and has the PoolOccupancy selection
+ type set, the Migration High Bytes will be applied. Bacula does not
+ currently restrict a pool to have only a single Media Type, so you
+ must keep in mind that if you mix Media Types in a Pool, the results
+ may not be what you want, as the Pool count of all bytes will be
+ for all Media Types combined.
+
+\item [Migration Low Bytes = \lt{}byte-specification\gt{}]
+ This directive specifies the number of bytes in the Pool which will
+ stop a migration if a {\bf PoolOccupancy} migration selection
+ type has been specified and triggered by more than Migration High
+ Bytes being in the pool. In other words, once a migration job
+ is started with {\bf PoolOccupancy} migration selection and it
+ determines that there are more than Migration High Bytes, the
+ migration job will continue to run jobs until the number of
+ bytes in the Pool drop to or below Migration Low Bytes.
+
+\item [Next Pool = \lt{}pool-specification\gt{}]
+ The Next Pool directive specifies the pool to which Jobs will be
+ migrated. This directive is required to define the Pool into which
+ the data will be migrated. Without this directive, the migration job
+ will terminate in error.
+
+\item [Storage = \lt{}storage-specification\gt{}]
+ The Storage directive specifies what Storage resource will be used
+ for all Jobs that use this Pool. It takes precedence over any other
+ Storage specifications that may have been given such as in the
+ Schedule Run directive, or in the Job resource. We highly recommend
+ that you define the Storage resource to be used in the Pool rather
+ than elsewhere (job, schedule run, ...).
+\end{description}
+
+\section{Important Migration Considerations}
+\index[general]{Important Migration Considerations}
+\begin{itemize}
+\item Each Pool into which you migrate Jobs or Volumes {\bf must}
+ contain Volumes of only one Media Type.
+
+\item Migration takes place on a JobId by JobId basis. That is
+ each JobId is migrated in its entirety and independently
+ of other JobIds. Once the Job is migrated, it will be
+ on the new medium in the new Pool, but for the most part,
+ aside from having a new JobId, it will appear with all the
+ same characteristics of the original job (start, end time, ...).
+ The column RealEndTime in the catalog Job table will contain the
+ time and date that the Migration terminated, and by comparing
+ it with the EndTime column you can tell whether or not the
+ job was migrated. The original job is purged of its File
+ records, and its Type field is changed from "B" to "M" to
+ indicate that the job was migrated.
+
+\item Jobs on Volumes will be Migration only if the Volume is
+ marked, Full, Used, or Error. Volumes that are still
+ marked Append will not be considered for migration. This
+ prevents Bacula from attempting to read the Volume at
+ the same time it is writing it. It also reduces other deadlock
+ situations, as well as avoids the problem that you migrate a
+ Volume and later find new files appended to that Volume.
+
+\item As noted above, for the Migration High Bytes, the calculation
+ of the bytes to migrate is somewhat approximate.
+
+\item If you keep Volumes of different Media Types in the same Pool,
+ it is not clear how well migration will work. We recommend only
+ one Media Type per pool.
+
+\item It is possible to get into a resource deadlock where Bacula does
+ not find enough drives to simultaneously read and write all the
+ Volumes needed to do Migrations. For the moment, you must take
+ care as all the resource deadlock algorithms are not yet implemented.
+
+\item Migration is done only when you run a Migration job. If you set a
+ Migration High Bytes and that number of bytes is exceeded in the Pool
+ no migration job will automatically start. You must schedule the
+ migration jobs, and they must run for any migration to take place.
+
+\item If you migrate a number of Volumes, a very large number of Migration
+ jobs may start.
+
+\item Figuring out what jobs will actually be migrated can be a bit complicated
+ due to the flexibility provided by the regex patterns and the number of
+ different options. Turning on a debug level of 100 or more will provide
+ a limited amount of debug information about the migration selection
+ process.
+
+\item Bacula currently does only minimal Storage conflict resolution, so you
+ must take care to ensure that you don't try to read and write to the
+ same device or Bacula may block waiting to reserve a drive that it
+ will never find. In general, ensure that all your migration
+ pools contain only one Media Type, and that you always
+ migrate to pools with different Media Types.
+
+\item The {\bf Next Pool = ...} directive must be defined in the Pool
+ referenced in the Migration Job to define the Pool into which the
+ data will be migrated.
+
+\item Pay particular attention to the fact that data is migrated on a Job
+ by Job basis, and for any particular Volume, only one Job can read
+ that Volume at a time (no simultaneous read), so migration jobs that
+ all reference the same Volume will run sequentially. This can be a
+ potential bottle neck and does not scale very well to large numbers
+ of jobs.
+
+\item Only migration of Selection Types of Job and Volume have
+ been carefully tested. All the other migration methods (time,
+ occupancy, smallest, oldest, ...) need additional testing.
+
+\item Migration is only implemented for a single Storage daemon. You
+ cannot read on one Storage daemon and write on another.
+\end{itemize}
+
+
+\section{Example Migration Jobs}
+\index[general]{Example Migration Jobs}
+
+When you specify a Migration Job, you must specify all the standard
+directives as for a Job. However, certain such as the Level, Client, and
+FileSet, though they must be defined, are ignored by the Migration job
+because the values from the original job used instead.
+
+As an example, suppose you have the following Job that
+you run every night. To note: there is no Storage directive in the
+Job resource; there is a Storage directive in each of the Pool
+resources; the Pool to be migrated (File) contains a Next Pool
+directive that defines the output Pool (where the data is written
+by the migration job).
+
+\footnotesize
+\begin{verbatim}
+# Define the backup Job
+Job {
+ Name = "NightlySave"
+ Type = Backup
+ Level = Incremental # default
+ Client=rufus-fd
+ FileSet="Full Set"
+ Schedule = "WeeklyCycle"
+ Messages = Standard
+ Pool = Default
+}
+
+# Default pool definition
+Pool {
+ Name = Default
+ Pool Type = Backup
+ AutoPrune = yes
+ Recycle = yes
+ Next Pool = Tape
+ Storage = File
+ LabelFormat = "File"
+}
+
+# Tape pool definition
+Pool {
+ Name = Tape
+ Pool Type = Backup
+ AutoPrune = yes
+ Recycle = yes
+ Storage = DLTDrive
+}
+
+# Definition of File storage device
+Storage {
+ Name = File
+ Address = rufus
+ Password = "ccV3lVTsQRsdIUGyab0N4sMDavui2hOBkmpBU0aQKOr9"
+ Device = "File" # same as Device in Storage daemon
+ Media Type = File # same as MediaType in Storage daemon
+}
+
+# Definition of DLT tape storage device
+Storage {
+ Name = DLTDrive
+ Address = rufus
+ Password = "ccV3lVTsQRsdIUGyab0N4sMDavui2hOBkmpBU0aQKOr9"
+ Device = "HP DLT 80" # same as Device in Storage daemon
+ Media Type = DLT8000 # same as MediaType in Storage daemon
+}
+
+\end{verbatim}
+\normalsize
+
+Where we have included only the essential information -- i.e. the
+Director, FileSet, Catalog, Client, Schedule, and Messages resources are
+omitted.
+
+As you can see, by running the NightlySave Job, the data will be backed up
+to File storage using the Default pool to specify the Storage as File.
+
+Now, if we add the following Job resource to this conf file.
+
+\footnotesize
+\begin{verbatim}
+Job {
+ Name = "migrate-volume"
+ Type = Migrate
+ Level = Full
+ Client = rufus-fd
+ FileSet = "Full Set"
+ Messages = Standard
+ Pool = Default
+ Maximum Concurrent Jobs = 4
+ Selection Type = Volume
+ Selection Pattern = "File"
+}
+\end{verbatim}
+\normalsize
+
+and then run the job named {\bf migrate-volume}, all volumes in the Pool
+named Default (as specified in the migrate-volume Job that match the
+regular expression pattern {\bf File} will be migrated to tape storage
+DLTDrive because the {\bf Next Pool} in the Default Pool specifies that
+Migrations should go to the pool named {\bf Tape}, which uses
+Storage {\bf DLTDrive}.
+
+If instead, we use a Job resource as follows:
+
+\footnotesize
+\begin{verbatim}
+Job {
+ Name = "migrate"
+ Type = Migrate
+ Level = Full
+ Client = rufus-fd
+ FileSet="Full Set"
+ Messages = Standard
+ Pool = Default
+ Maximum Concurrent Jobs = 4
+ Selection Type = Job
+ Selection Pattern = ".*Save"
+}
+\end{verbatim}
+\normalsize
+
+All jobs ending with the name Save will be migrated from the File Default to
+the Tape Pool, or from File storage to Tape storage.
--- /dev/null
+#!/bin/sh
+#
+# Bacula interface to mtx autoloader
+#
+# Created OCT/31/03 by Alexander Kuehn, derived from Ludwig Jaffe's script
+#
+# Works with the HP C1537A L708 DDS3
+#
+#set -x
+# these are the labels of the tapes in each virtual slot, not the slots!
+labels="PSE-0001 PSE-0002 PSE-0003 PSE-0004 PSE-0005 PSE-0006 PSE-0007 PSE-0008 PSE-0009 PSE-0010 PSE-0011 PSE-0012"
+
+# who to send a mail to?
+recipient=root@localhost
+logfile=/var/log/mtx.log
+
+# Delay in seconds how often to check whether a new tape has been inserted
+TAPEDELAY=10 # the default is every 10 seconds
+echo `date` ":" $@ >>$logfile
+
+# change this if mt is not in the path (use different quotes!)
+mt=`which mt`
+grep=`which grep`
+#
+# how to run the console application?
+console="/usr/local/sbin/console -c /usr/local/etc/console.conf"
+
+command="$1"
+
+#TAPEDRIVE0 holds the device/name of your 1st and only drive (Bacula supports only 1 drive currently)
+#Read TAPEDRIVE from command line parameters
+if [ -z "$2" ] ; then
+ TAPEDRIVE0=/dev/nsa0
+else
+ TAPEDRIVE0=$2
+fi
+
+#Read slot from command line parameters
+if [ -z "$3" ] ; then
+ slot=`expr 1`
+else
+ slot=`expr $3`
+fi
+
+if [ -z "$command" ] ; then
+ echo ""
+ echo "The mtx-changer script for Bacula"
+ echo "---------------------------------"
+ echo ""
+ echo "usage: mtx-changer <command> <devicename of tapedrive> [slot]"
+ echo " mtx-changer"
+ echo ""
+ echo "Valid commands:"
+ echo ""
+ echo "unload Unloads a tape into the slot"
+ echo " from where it was loaded."
+ echo "load <slot> Loads a tape from the slot <slot>"
+ echo "list Lists full storage slots"
+ echo "loaded Gives slot from where the tape was loaded."
+ echo " 0 means the tape drive is empty."
+ echo "slots Gives Number of avialable slots."
+ echo "volumes List avialable slots and the label of the."
+ echo " tape in it (slot:volume)"
+ echo "Example:"
+ echo " mtx-changer load /dev/nst0 1 loads a tape from slot1"
+ echo " mtx-changer %a %o %S "
+ echo ""
+ exit 0
+fi
+
+
+case "$command" in
+ unload)
+ # At first do mt -f /dev/st0 offline to unload the tape
+ #
+ # Check if you want to fool me
+ echo "unmount"|$console >/dev/null 2>/dev/null
+ echo "mtx-changer: Checking if drive is loaded before we unload. Request unload" >>$logfile
+ if $mt -f $TAPEDRIVE0 status >/dev/null 2>/dev/null ; then # mt says status ok
+ echo "mtx-changer: Doing mt -f $TAPEDRIVE0 rewoffl to rewind and unload the tape!" >>$logfile
+ $mt -f $TAPEDRIVE0 rewoffl
+ else
+ echo "mtx-changer: *** Don't fool me! *** The Drive $TAPEDRIVE0 is empty." >>$logfile
+ fi
+ exit 0
+ ;;
+
+ load)
+ #Let's check if drive is loaded before we load it
+ echo "mtx-changer: Checking if drive is loaded before we load. I Request loaded" >>$logfile
+ LOADEDVOL=`echo "status Storage"|$console|$grep $TAPEDRIVE0|grep ^Device|grep -v "not open."|grep -v "ERR="|grep -v "no Bacula volume is mounted"|sed -e s/^.*Volume\ //|cut -d\" -f2`
+# if [ -z "$LOADEDVOL" ] ; then # this is wrong, becaus Bacula would try to use the tape if we mount it!
+# LOADEDVOL=`echo "mount"|$console|$grep $TAPEDRIVE0|grep Device|grep -v "not open."|grep -v "ERR="|sed -e s/^.*Volume\ //|cut -d\" -f2`
+# if [ -z "$LOADEDVOL" ] ; then
+# echo "mtx-changer: The Drive $TAPEDRIVE0 is empty." >>$logfile
+# else # restore state?
+# if [ $LOADEDVOL = $3 ] ; then # requested Volume mounted -> exit
+# echo "mtx-changer: *** Don't fool me! *** Tape $LOADEDVOL is already in drive $TAPEDRIVE0!" >>$logfile
+# exit
+# else # oops, wrong volume
+# echo "unmount"|$console >/dev/null 2>/dev/null
+# fi
+# fi
+# fi
+ if [ -z "$LOADEDVOL" ] ; then
+ echo "unmount"|$console >/dev/null 2>/dev/null
+ LOADEDVOL=0
+ else
+ #Check if you want to fool me
+ if [ $LOADEDVOL = $3 ] ; then
+ echo "mtx-changer: *** Don't fool me! *** Tape $LOADEDVOL is already in drive $TAPEDRIVE0!" >>$logfile
+ exit
+ fi
+ echo "mtx-changer: The Drive $TAPEDRIVE0 is loaded with the tape $LOADEDVOL" >>$logfile
+ echo "mtx-changer: Unmounting..." >>$logfile
+ echo "unmount"|$console >/dev/null 2>/dev/null
+ fi
+ echo "mtx-changer: Unloading..." >>$logfile
+ echo "mtx-changer: Doing mt -f $TAPEDRIVE0 rewoffl to rewind and unload the tape!" >>$logfile
+ mt -f $TAPEDRIVE0 rewoffl 2>/dev/null
+ #Now we can load the drive as desired
+ echo "mtx-changer: Doing mtx -f $1 $2 $3" >>$logfile
+ # extract label for the mail
+ count=`expr 1`
+ for label in $labels ; do
+ if [ $slot -eq $count ] ; then volume=$label ; fi
+ count=`expr $count + 1`
+ done
+
+ mail -s "Bacula needs volume $volume." $recipient <<END_OF_DATA
+Please insert volume $volume from slot $slot into $TAPEDRIVE0 .
+Kind regards,
+Bacula.
+END_OF_DATA
+ sleep 15
+ $mt status >/dev/null 2>/dev/null
+ while [ $? -ne 0 ] ; do
+ sleep $TAPEDELAY
+ $mt status >/dev/null 2>/dev/null
+ done
+ mail -s "Bacula says thank you." $recipient <<END_OF_DATA
+Thank you for inserting the new tape! (I requested volume $volume from slot $slot.)
+Kind regards,
+Bacula.
+END_OF_DATA
+ echo "Successfully loaded a tape into drive $TAPEDRIVE0 (requested $volume from slot $slot)." >>$logfile
+ echo "Loading finished." ; >>$logfile
+ echo "$slot"
+ exit 0
+ ;;
+
+ list)
+ echo "mtx-changer: Requested list" >>$logfile
+ LOADEDVOL=`echo "status Storage"|$console|$grep $TAPEDRIVE0|grep ^Device|grep -v "not open."|grep -v "ERR="|grep -v "no Bacula volume is mounted"|sed -e s/^.*Volume\ //|cut -d\" -f2`
+ if [ -z $LOADEDVOL ] ; then # try mounting
+ LOADEDVOL=`echo "mount"|$console|$grep $TAPEDRIVE0|grep Device|grep -v "not open."|grep -v "ERR="|sed -e s/^.*Volume\ //|cut -d\" -f2`
+ if [ -z $LOADEDVOL ] ; then # no luck
+ LOADEDVOL="_no_tape"
+ else # restore state
+ echo "unmount"|$console >/dev/null 2>/dev/null
+ fi
+ fi
+ count=`expr 1`
+ for label in $labels ; do
+ if [ "$label" != "$LOADEDVOL" ] ; then
+ printf "$count "
+ fi
+ count=`expr $count + 1`
+ done
+ printf "\n"
+ ;;
+
+ loaded)
+ echo "mtx-changer: Request loaded, dev $TAPEDRIVE0" >>$logfile
+ LOADEDVOL=`echo "status Storage"|$console|$grep $TAPEDRIVE0|grep ^Device|grep -v "not open."|grep -v "ERR="|grep -v "no Bacula volume is mounted"|sed -e s/^.*Volume\ //|cut -d\" -f2`
+ if [ -z $LOADEDVOL ] ; then
+ LOADEDVOL=`echo "mount"|$console|$grep $TAPEDRIVE0|grep Device|grep -v "not open."|grep -v "ERR="|grep -v "no Bacula volume is mounted"|sed -e s/^.*Volume\ //|cut -d\" -f2`
+ if [ -z "$LOADEDVOL" ] ; then # no luck
+ echo "$TAPEDRIVE0 not mounted!" >>$logfile
+ else # restore state
+ echo "unmount"|$console >/dev/null 2>/dev/null
+ fi
+ fi
+ if [ -z "$LOADEDVOL" ] ; then
+ LOADEDVOL="_no_tape" >>$logfile
+ echo "0"
+ else
+ count=`expr 1`
+ for label in $labels ; do
+ if [ $LOADEDVOL = $label ] ; then echo $count ; fi
+ count=`expr $count + 1`
+ done
+ fi
+ exit 0
+ ;;
+
+ slots)
+ echo "mtx-changer: Request slots" >>$logfile
+ count=`expr 0`
+ for label in $labels ; do
+ count=`expr $count + 1`
+ done
+ echo $count
+ ;;
+
+ volumes)
+ echo "mtx-changer: Request volumes" >>$logfile
+ count=`expr 1`
+ for label in $labels ; do
+ printf "$count:$label "
+ count=`expr $count + 1`
+ done
+ printf "\n"
+ ;;
+esac
--- /dev/null
+%%
+%%
+
+\chapter{Automated Disk Backup}
+\label{PoolsChapter}
+\index[general]{Volumes!Using Pools to Manage}
+\index[general]{Disk!Automated Backup}
+\index[general]{Using Pools to Manage Volumes}
+\index[general]{Automated Disk Backup}
+
+If you manage five or ten machines and have a nice tape backup, you don't need
+Pools, and you may wonder what they are good for. In this chapter, you will
+see that Pools can help you optimize disk storage space. The same techniques
+can be applied to a shop that has multiple tape drives, or that wants to mount
+various different Volumes to meet their needs.
+
+The rest of this chapter will give an example involving backup to disk
+Volumes, but most of the information applies equally well to tape Volumes.
+
+\label{TheProblem}
+\section{The Problem}
+\index[general]{Problem}
+
+A site that I administer (a charitable organization) had a tape DDS-3 tape
+drive that was failing. The exact reason for the failure is still unknown.
+Worse yet, their full backup size is about 15GB whereas the capacity of their
+broken DDS-3 was at best 8GB (rated 6/12). A new DDS-4 tape drive and the
+necessary cassettes was more expensive than their budget could handle.
+
+\label{TheSolution}
+\section{The Solution}
+\index[general]{Solution}
+
+They want to maintain six months of backup data, and be able to access the old
+files on a daily basis for a week, a weekly basis for a month, then monthly
+for six months. In addition, offsite capability was not needed (well perhaps
+it really is, but it was never used). Their daily changes amount to about
+300MB on the average, or about 2GB per week.
+
+As a consequence, the total volume of data they need to keep to meet their
+needs is about 100GB (15GB x 6 + 2GB x 5 + 0.3 x 7) = 102.1GB.
+
+The chosen solution was to buy a 120GB hard disk for next to nothing -- far
+less than 1/10th the price of a tape drive and the cassettes to handle the
+same amount of data, and to have Bacula write to disk files.
+
+The rest of this chapter will explain how to setup Bacula so that it would
+automatically manage a set of disk files with the minimum sysadmin
+intervention. The system has been running since 22 January 2004 until today
+(23 June 2007) with no intervention, with the exception of adding
+a second 120GB hard disk after a year because their needs grew
+over that time to more than the 120GB (168GB to be exact). The only other
+intervention I have made is a periodic (about once a year) Bacula upgrade.
+
+\label{OverallDesign}
+\section{Overall Design}
+\index[general]{Overall Design}
+\index[general]{Design!Overall}
+
+Getting Bacula to write to disk rather than tape in the simplest case is
+rather easy, and is documented in the previous chapter. In addition, all the
+directives discussed here are explained in that chapter. We'll leave it to you
+to look at the details there. If you haven't read it and are not familiar with
+Pools, you probably should at least read it once quickly for the ideas before
+continuing here.
+
+One needs to consider about what happens if we have only a single large Bacula
+Volume defined on our hard disk. Everything works fine until the Volume fills,
+then Bacula will ask you to mount a new Volume. This same problem applies to
+the use of tape Volumes if your tape fills. Being a hard disk and the only one
+you have, this will be a bit of a problem. It should be obvious that it is
+better to use a number of smaller Volumes and arrange for Bacula to
+automatically recycle them so that the disk storage space can be reused. The
+other problem with a single Volume, is that until version 2.0.0,
+Bacula did not seek within a disk Volume, so restoring a single file can take
+more time than one would expect.
+
+As mentioned, the solution is to have multiple Volumes, or files on the disk.
+To do so, we need to limit the use and thus the size of a single Volume, by
+time, by number of jobs, or by size. Any of these would work, but we chose to
+limit the use of a single Volume by putting a single job in each Volume with
+the exception of Volumes containing Incremental backup where there will be 6
+jobs (a week's worth of data) per volume. The details of this will be
+discussed shortly. This is a single client backup, so if you have multiple
+clients you will need to multiply those numbers by the number of clients,
+or use a different system for switching volumes, such as limiting the
+volume size.
+
+The next problem to resolve is recycling of Volumes. As you noted from above,
+the requirements are to be able to restore monthly for 6 months, weekly for a
+month, and daily for a week. So to simplify things, why not do a Full save
+once a month, a Differential save once a week, and Incremental saves daily.
+Now since each of these different kinds of saves needs to remain valid for
+differing periods, the simplest way to do this (and possibly the only) is to
+have a separate Pool for each backup type.
+
+The decision was to use three Pools: one for Full saves, one for Differential
+saves, and one for Incremental saves, and each would have a different number
+of volumes and a different Retention period to accomplish the requirements.
+
+\label{FullPool}
+\subsection{Full Pool}
+\index[general]{Pool!Full}
+\index[general]{Full Pool}
+
+Putting a single Full backup on each Volume, will require six Full save
+Volumes, and a retention period of six months. The Pool needed to do that is:
+
+\footnotesize
+\begin{verbatim}
+Pool {
+ Name = Full-Pool
+ Pool Type = Backup
+ Recycle = yes
+ AutoPrune = yes
+ Volume Retention = 6 months
+ Maximum Volume Jobs = 1
+ Label Format = Full-
+ Maximum Volumes = 9
+}
+\end{verbatim}
+\normalsize
+
+Since these are disk Volumes, no space is lost by having separate Volumes for
+each backup (done once a month in this case). The items to note are the
+retention period of six months (i.e. they are recycled after six months), that
+there is one job per volume (Maximum Volume Jobs = 1), the volumes will be
+labeled Full-0001, ... Full-0006 automatically. One could have labeled these
+manually from the start, but why not use the features of Bacula.
+
+Six months after the first volume is used, it will be subject to pruning
+and thus recycling, so with a maximum of 9 volumes, there should always be
+3 volumes available (note, they may all be marked used, but they will be
+marked purged and recycled as needed).
+
+If you have two clients, you would want to set {\bf Maximum Volume Jobs} to
+2 instead of one, or set a limit on the size of the Volumes, and possibly
+increase the maximum number of Volumes.
+
+
+\label{DiffPool}
+\subsection{Differential Pool}
+\index[general]{Pool!Differential}
+\index[general]{Differential Pool}
+
+For the Differential backup Pool, we choose a retention period of a bit longer
+than a month and ensure that there is at least one Volume for each of the
+maximum of five weeks in a month. So the following works:
+
+\footnotesize
+\begin{verbatim}
+Pool {
+ Name = Diff-Pool
+ Pool Type = Backup
+ Recycle = yes
+ AutoPrune = yes
+ Volume Retention = 40 days
+ Maximum Volume Jobs = 1
+ Label Format = Diff-
+ Maximum Volumes = 10
+}
+\end{verbatim}
+\normalsize
+
+As you can see, the Differential Pool can grow to a maximum of 9 volumes,
+and the Volumes are retained 40 days and thereafter they can be recycled. Finally
+there is one job per volume. This, of course, could be tightened up a lot, but
+the expense here is a few GB which is not too serious.
+
+If a new volume is used every week, after 40 days, one will have used 7
+volumes, and there should then always be 3 volumes that can be purged and
+recycled.
+
+See the discussion above concering the Full pool for how to handle multiple
+clients.
+
+\label{IncPool}
+\subsection{Incremental Pool}
+\index[general]{Incremental Pool}
+\index[general]{Pool!Incremental}
+
+Finally, here is the resource for the Incremental Pool:
+
+\footnotesize
+\begin{verbatim}
+Pool {
+ Name = Inc-Pool
+ Pool Type = Backup
+ Recycle = yes
+ AutoPrune = yes
+ Volume Retention = 20 days
+ Maximum Volume Jobs = 6
+ Label Format = Inc-
+ Maximum Volumes = 7
+}
+\end{verbatim}
+\normalsize
+
+We keep the data for 20 days rather than just a week as the needs require. To
+reduce the proliferation of volume names, we keep a week's worth of data (6
+incremental backups) in each Volume. In practice, the retention period should
+be set to just a bit more than a week and keep only two or three volumes
+instead of five. Again, the lost is very little and as the system reaches the
+full steady state, we can adjust these values so that the total disk usage
+doesn't exceed the disk capacity.
+
+If you have two clients, the simplest thing to do is to increase the
+maximum volume jobs from 6 to 12. As mentioned above, it is also possible
+limit the size of the volumes. However, in that case, you will need to
+have a better idea of the volume or add sufficient volumes to the pool so
+that you will be assured that in the next cycle (after 20 days) there is
+at least one volume that is pruned and can be recycled.
+
+
+\label{Example}
+\section{The Actual Conf Files}
+\index[general]{Files!Actual Conf}
+\index[general]{Actual Conf Files}
+
+The following example shows you the actual files used, with only a few minor
+modifications to simplify things.
+
+The Director's configuration file is as follows:
+
+\footnotesize
+\begin{verbatim}
+Director { # define myself
+ Name = bacula-dir
+ DIRport = 9101
+ QueryFile = "/home/bacula/bin/query.sql"
+ WorkingDirectory = "/home/bacula/working"
+ PidDirectory = "/home/bacula/working"
+ Maximum Concurrent Jobs = 1
+ Password = " *** CHANGE ME ***"
+ Messages = Standard
+}
+# By default, this job will back up to disk in /tmp
+Job {
+ Name = client
+ Type = Backup
+ Client = client-fd
+ FileSet = "Full Set"
+ Schedule = "WeeklyCycle"
+ Storage = File
+ Messages = Standard
+ Pool = Default
+ Full Backup Pool = Full-Pool
+ Incremental Backup Pool = Inc-Pool
+ Differential Backup Pool = Diff-Pool
+ Write Bootstrap = "/home/bacula/working/client.bsr"
+ Priority = 10
+}
+
+# Backup the catalog database (after the nightly save)
+Job {
+ Name = "BackupCatalog"
+ Type = Backup
+ Client = client-fd
+ FileSet="Catalog"
+ Schedule = "WeeklyCycleAfterBackup"
+ Storage = File
+ Messages = Standard
+ Pool = Default
+ # This creates an ASCII copy of the catalog
+ # WARNING!!! Passing the password via the command line is insecure.
+ # see comments in make_catalog_backup for details.
+ RunBeforeJob = "/home/bacula/bin/make_catalog_backup bacula bacula"
+ # This deletes the copy of the catalog
+ RunAfterJob = "/home/bacula/bin/delete_catalog_backup"
+ Write Bootstrap = "/home/bacula/working/BackupCatalog.bsr"
+ Priority = 11 # run after main backup
+}
+
+# Standard Restore template, to be changed by Console program
+Job {
+ Name = "RestoreFiles"
+ Type = Restore
+ Client = havana-fd
+ FileSet="Full Set"
+ Storage = File
+ Messages = Standard
+ Pool = Default
+ Where = /tmp/bacula-restores
+}
+
+
+
+# List of files to be backed up
+FileSet {
+ Name = "Full Set"
+ Include = { Options { signature=SHA1; compression=GZIP9 }
+ File = /
+ File = /usr
+ File = /home
+ File = /boot
+ File = /var
+ File = /opt
+ }
+ Exclude = {
+ File = /proc
+ File = /tmp
+ File = /.journal
+ File = /.fsck
+ ...
+ }
+}
+Schedule {
+ Name = "WeeklyCycle"
+ Run = Level=Full 1st sun at 2:05
+ Run = Level=Differential 2nd-5th sun at 2:05
+ Run = Level=Incremental mon-sat at 2:05
+}
+
+# This schedule does the catalog. It starts after the WeeklyCycle
+Schedule {
+ Name = "WeeklyCycleAfterBackup"
+ Run = Level=Full sun-sat at 2:10
+}
+
+# This is the backup of the catalog
+FileSet {
+ Name = "Catalog"
+ Include { Options { signature=MD5 }
+ File = /home/bacula/working/bacula.sql
+ }
+}
+
+Client {
+ Name = client-fd
+ Address = client
+ FDPort = 9102
+ Catalog = MyCatalog
+ Password = " *** CHANGE ME ***"
+ AutoPrune = yes # Prune expired Jobs/Files
+ Job Retention = 6 months
+ File Retention = 60 days
+}
+
+Storage {
+ Name = File
+ Address = localhost
+ SDPort = 9103
+ Password = " *** CHANGE ME ***"
+ Device = FileStorage
+ Media Type = File
+}
+
+Catalog {
+ Name = MyCatalog
+ dbname = bacula; user = bacula; password = ""
+}
+
+Pool {
+ Name = Full-Pool
+ Pool Type = Backup
+ Recycle = yes # automatically recycle Volumes
+ AutoPrune = yes # Prune expired volumes
+ Volume Retention = 6 months
+ Maximum Volume Jobs = 1
+ Label Format = Full-
+ Maximum Volumes = 9
+}
+
+Pool {
+ Name = Inc-Pool
+ Pool Type = Backup
+ Recycle = yes # automatically recycle Volumes
+ AutoPrune = yes # Prune expired volumes
+ Volume Retention = 20 days
+ Maximum Volume Jobs = 6
+ Label Format = Inc-
+ Maximum Volumes = 7
+}
+
+Pool {
+ Name = Diff-Pool
+ Pool Type = Backup
+ Recycle = yes
+ AutoPrune = yes
+ Volume Retention = 40 days
+ Maximum Volume Jobs = 1
+ Label Format = Diff-
+ Maximum Volumes = 10
+}
+
+Messages {
+ Name = Standard
+ mailcommand = "bsmtp -h mail.domain.com -f \"\(Bacula\) %r\"
+ -s \"Bacula: %t %e of %c %l\" %r"
+ operatorcommand = "bsmtp -h mail.domain.com -f \"\(Bacula\) %r\"
+ -s \"Bacula: Intervention needed for %j\" %r"
+ mail = root@domain.com = all, !skipped
+ operator = root@domain.com = mount
+ console = all, !skipped, !saved
+ append = "/home/bacula/bin/log" = all, !skipped
+}
+\end{verbatim}
+\normalsize
+
+and the Storage daemon's configuration file is:
+
+\footnotesize
+\begin{verbatim}
+Storage { # definition of myself
+ Name = bacula-sd
+ SDPort = 9103 # Director's port
+ WorkingDirectory = "/home/bacula/working"
+ Pid Directory = "/home/bacula/working"
+}
+Director {
+ Name = bacula-dir
+ Password = " *** CHANGE ME ***"
+}
+Device {
+ Name = FileStorage
+ Media Type = File
+ Archive Device = /files/bacula
+ LabelMedia = yes; # lets Bacula label unlabeled media
+ Random Access = Yes;
+ AutomaticMount = yes; # when device opened, read it
+ RemovableMedia = no;
+ AlwaysOpen = no;
+}
+Messages {
+ Name = Standard
+ director = bacula-dir = all
+}
+\end{verbatim}
+\normalsize
--- /dev/null
+%%
+%%
+
+\chapter{Bacula Projects}
+\label{ProjectsChapter}
+\index[general]{Projects!Bacula }
+\index[general]{Bacula Projects }
+
+Once a new major version of Bacula is released, the Bacula
+users will vote on a list of new features. This vote is used
+as the main element determining what new features will be
+implemented for the next version. Generally, the development time
+for a new release is between four to nine months. Sometimes it may be
+a bit longer, but in that case, there will be a number of bug fix
+updates to the currently released version.
+
+For the current list of project, please see the projects page in the CVS
+at: \elink{http://cvs.sourceforge.net/viewcvs.py/*checkout*/bacula/bacula/projects}
+{http://cvs.sourceforge.net/viewcvs.py/*checkout*/bacula/bacula/projects}
+see the {\bf projects} file in the main source directory. The projects
+file is updated approximately once every six months.
+
+Separately from the project list, Kern maintains a current list of
+tasks as well as ideas, feature requests, and occasionally design
+notes. This list is updated roughly weekly (sometimes more often).
+For a current list of tasks you can see {\bf kernstodo} in the Source Forge
+CVS at \elink{http://cvs.sourceforge.net/viewcvs.py/*checkout*/bacula/bacula/kernstodo}
+{http://cvs.sourceforge.net/viewcvs.py/*checkout*/bacula/bacula/kernstodo}.
--- /dev/null
+%%
+%%
+
+\chapter{Python Scripting}
+\label{PythonChapter}
+\index[general]{Python Scripting}
+\index[general]{Scripting!Python}
+
+You may be asking what Python is and why a scripting language is
+needed in Bacula. The answer to the first question is that Python
+is an Object Oriented scripting language with features similar
+to those found in Perl, but the syntax of the language is much
+cleaner and simpler. The answer to why have scripting in Bacula is to
+give the user more control over the whole backup process. Probably
+the simplest example is when Bacula needs a new Volume name, with
+a scripting language such as Python, you can generate any name
+you want, based on the current state of Bacula.
+
+\section{Python Configuration}
+\index[general]{Python Configuration}
+\index[general]{Configuration!Python}
+
+Python must be enabled during the configuration process by adding
+a \verb:--:with-python, and possibly specifying an alternate
+directory if your Python is not installed in a standard system
+location. If you are using RPMs you will need the python-devel package
+installed.
+
+When Python is configured, it becomes an integral part of Bacula and
+runs in Bacula's address space, so even though it is an interpreted
+language, it is very efficient.
+
+When the Director starts, it looks to see if you have a {\bf
+Scripts Directory} Directive defined (normal default {\bf
+/etc/bacula/scripts}, if so, it looks in that directory for a file named
+{\bf DirStartUp.py}. If it is found, Bacula will pass this file to Python
+for execution. The {\bf Scripts Directory} is a new directive that you add
+to the Director resource of your bacula-dir.conf file.
+
+Note: Bacula does not install Python scripts by default because these
+scripts are for you to program. This means that with a default
+installation with Python enabled, Bacula will print the following error
+message:
+
+\begin{verbatim}
+09-Jun 15:14 bacula-dir: ERROR in pythonlib.c:131 Could not import
+Python script /etc/bacula/scripts/DirStartUp. Python disabled.
+\end{verbatim}
+
+The source code directory {\bf examples/python} contains sample scripts
+for DirStartUp.py, SDStartUp.py, and FDStartUp.py that you might want
+to use as a starting point. Normally, your scripts directory (at least
+where you store the Python scripts) should be writable by Bacula, because
+Python will attempt to write a compiled version of the scripts (e.g.
+DirStartUp.pyc) back to that directory.
+
+When starting with the sample scripts, you can delete any part that
+you will not need, but you should keep all the Bacula Event and Job Event
+definitions. If you do not want a particular event, simply replace the
+existing code with a {\bf noop = 1}.
+
+\section{Bacula Events}
+\index[general]{Bacula Events}
+\index[general]{Events}
+A Bacula event is a point in the Bacula code where Bacula
+will call a subroutine (actually a method) that you have
+defined in the Python StartUp script. Events correspond
+to some significant event such as a Job Start, a Job End,
+Bacula needs a new Volume Name, ... When your script is
+called, it will have access to all the Bacula variables
+specific to the Job (attributes of the Job Object), and
+it can even call some of the Job methods (subroutines)
+or set new values in the Job attributes, such as the
+Priority. You will see below how the events are used.
+
+\section{Python Objects}
+\index[general]{Python Objects}
+\index[general]{Objects!Python}
+
+There are four Python objects that you will need to work with:
+\begin{description}
+\item [The Bacula Object]
+ The Bacula object is created by the Bacula daemon (the Director
+ in the present case) when the daemon starts. It is available to
+ the Python startup script, {\bf DirStartup.py}, by importing the
+ Bacula definitions with {\bf import bacula}. The methods
+ available with this object are described below.
+
+\item [The Bacula Events Class]
+ You create this class in the startup script, and you pass
+ it to the Bacula Object's {\bf set\_events} method. The
+ purpose of the Bacula Events Class is to define what global
+ or daemon events you want to monitor. When one of those events
+ occurs, your Bacula Events Class will be called at the method
+ corresponding to the event. There are currently three events,
+ JobStart, JobEnd, and Exit, which are described in detail below.
+
+\item [The Job Object]
+ When a Job starts, and assuming you have defined a JobStart method
+ in your Bacula Events Class, Bacula will create a Job Object. This
+ object will be passed to the JobStart event. The Job Object has a
+ has good number of read-only members or attributes providing many
+ details of the Job, and it also has a number of writable attributes
+ that allow you to pass information into the Job. These attributes
+ are described below.
+
+\item [The Job Events Class]
+ You create this class in the JobStart method of your Bacula Events
+ class, and it allows you to define which of the possible Job Object
+ events you want to see. You must pass an instance of your Job Events
+ class to the Job Object set\_events() method.
+ Normally, you will probably only have one
+ Job Events Class, which will be instantiated for each Job. However,
+ if you wish to see different events in different Jobs, you may have
+ as many Job Events classes as you wish.
+\end{description}
+
+
+The first thing the startup script must do is to define what global Bacula
+events (daemon events), it wants to see. This is done by creating a
+Bacula Events class, instantiating it, then passing it to the
+{\bf set\_events} method. There are three possible
+events.
+
+\begin{description}
+\item [JobStart]
+ \index[dir]{JobStart}
+ This Python method, if defined, will be called each time a Job is started.
+ The method is passed the class instantiation object as the first argument,
+ and the Bacula Job object as the second argument. The Bacula Job object
+ has several built-in methods, and you can define which ones you
+ want called. If you do not define this method, you will not be able
+ to interact with Bacula jobs.
+
+\item [JobEnd]
+ This Python method, if defined, will be called each time a Job terminates.
+ The method is passed the class instantiation object as the first argument,
+ and the Bacula Job object as the second argument.
+
+\item [Exit]
+ This Python method, if defined, will be called when the Director terminates.
+ The method is passed the class instantiation object as the first argument.
+\end{description}
+
+Access to the Bacula variables and methods is done with:
+
+ import bacula
+
+The following are the read-only attributes provided by the bacula object.
+\begin{description}
+\item [Name]
+\item [ConfigFile]
+\item [WorkingDir]
+\item [Version] string consisting of "Version Build-date"
+\end{description}
+
+
+A simple definition of the Bacula Events Class might be the following:
+
+\footnotesize
+\begin{verbatim}
+import sys, bacula
+class BaculaEvents:
+ def JobStart(self, job):
+ ...
+\end{verbatim}
+\normalsize
+
+Then to instantiate the class and pass it to Bacula, you
+would do:
+
+\footnotesize
+\begin{verbatim}
+bacula.set_events(BaculaEvents()) # register Bacula Events wanted
+\end{verbatim}
+\normalsize
+
+And at that point, each time a Job is started, your BaculaEvents JobStart
+method will be called.
+
+Now to actually do anything with a Job, you must define which Job events
+you want to see, and this is done by defining a JobEvents class containing
+the methods you want called. Each method name corresponds to one of the
+Job Events that Bacula will generate.
+
+A simple Job Events class might look like the following:
+
+\footnotesize
+\begin{verbatim}
+class JobEvents:
+ def NewVolume(self, job):
+ ...
+\end{verbatim}
+\normalsize
+
+Here, your JobEvents class method NewVolume will be called each time
+the Job needs a new Volume name. To actually register the events defined
+in your class with the Job, you must instantiate the JobEvents class and
+set it in the Job {\bf set\_events} variable. Note, this is a bit different
+from how you registered the Bacula events. The registration process must
+be done in the Bacula JobStart event (your method). So, you would modify
+Bacula Events (not the Job events) as follows:
+
+\footnotesize
+\begin{verbatim}
+import sys, bacula
+class BaculaEvents:
+ def JobStart(self, job):
+ events = JobEvents() # create instance of Job class
+ job.set_events(events) # register Job events desired
+ ...
+\end{verbatim}
+\normalsize
+
+When a job event is triggered, the appropriate event definition is
+called in the JobEvents class. This is the means by which your Python
+script or code gets control. Once it has control, it may read job
+attributes, or set them. See below for a list of read-only attributes,
+and those that are writable.
+
+In addition, the Bacula {\bf job} object in the Director has
+a number of methods (subroutines) that can be called. They
+are:
+\begin{description}
+\item [set\_events] The set\_events method takes a single
+ argument, which is the instantiation of the Job Events class
+ that contains the methods that you want called. The method
+ names that will be called must correspond to the Bacula
+ defined events. You may define additional methods but Bacula
+ will not use them.
+\item [run] The run method takes a single string
+ argument, which is the run command (same as in the Console)
+ that you want to submit to start a new Job. The value
+ returned by the run method is the JobId of the job that
+ started, or -1 if there was an error.
+\item [write] The write method is used to be able to send
+ print output to the Job Report. This will be described later.
+\item[cancel] The cancel method takes a single integer argument,
+ which is a JobId. If JobId is found, it will be canceled.
+\item [DoesVolumeExist] The DoesVolumeExist method takes a single
+ string argument, which is the Volume name, and returns
+ 1 if the volume exists in the Catalog and 0 if the volume
+ does not exist.
+\end{description}
+
+The following attributes are read/write within the Director
+for the {\bf job} object.
+
+\begin{description}
+\item [Priority] Read or set the Job priority.
+ Note, that setting a Job Priority is effective only before
+ the Job actually starts.
+\item [Level] This attribute contains a string representing the Job
+ level, e.g. Full, Differential, Incremental, ... if read.
+ The level can also be set.
+\end{description}
+
+The following read-only attributes are available within the Director
+for the {\bf job} object.
+
+\begin{description}
+\item [Type] This attribute contains a string representing the Job
+ type, e.g. Backup, Restore, Verify, ...
+\item [JobId] This attribute contains an integer representing the
+ JobId.
+\item [Client] This attribute contains a string with the name of the
+ Client for this job.
+\item [NumVols] This attribute contains an integer with the number of
+ Volumes in the Pool being used by the Job.
+\item [Pool] This attribute contains a string with the name of the Pool
+ being used by the Job.
+\item [Storage] This attribute contains a string with the name of the
+ Storage resource being used by the Job.
+\item [Catalog] This attribute contains a string with the name of the
+ Catalog resource being used by the Job.
+\item [MediaType] This attribute contains a string with the name of the
+ Media Type associated with the Storage resource being used by the Job.
+\item [Job] This attribute contains a string containing the name of the
+ Job resource used by this job (not unique).
+\item [JobName] This attribute contains a string representing the full
+ unique Job name.
+\item [JobStatus] This attribute contains a single character string
+ representing the current Job status. The status may change
+ during execution of the job. It may take on the following
+ values:
+ \begin{description}
+ \item [C] Created, not yet running
+ \item [R] Running
+ \item [B] Blocked
+ \item [T] Completed successfully
+ \item [E] Terminated with errors
+ \item [e] Non-fatal error
+ \item [f] Fatal error
+ \item [D] Verify found differences
+ \item [A] Canceled by user
+ \item [F] Waiting for Client
+ \item [S] Waiting for Storage daemon
+ \item [m] Waiting for new media
+ \item [M] Waiting for media mount
+ \item [s] Waiting for storage resource
+ \item [j] Waiting for job resource
+ \item [c] Waiting for client resource
+ \item [d] Waiting on maximum jobs
+ \item [t] Waiting on start time
+ \item [p] Waiting on higher priority jobs
+ \end{description}
+
+\item [Priority] This attribute contains an integer with the priority
+ assigned to the job.
+\item [CatalogRes] tuple consisting of (DBName, Address, User,
+ Password, Socket, Port, Database Vendor) taken from the Catalog resource
+ for the Job with the exception of Database Vendor, which is
+ one of the following: MySQL, PostgreSQL, SQLite, Internal,
+ depending on what database you configured.
+\item [VolumeName]
+ After a Volume has been purged, this attribute will contain the
+ name of that Volume. At other times, this value may have no meaning.
+\end{description}
+
+The following write-only attributes are available within the
+Director:
+
+\begin{description}
+\item [JobReport] Send line to the Job Report.
+\item [VolumeName] Set a new Volume name. Valid only during the
+ NewVolume event.
+\end{description}
+
+\section{Python Console Command}
+\index[general]{Python Console Command}
+\index[general]{Console Command!Python}
+
+There is a new Console command named {\bf python}. It takes
+a single argument {\bf restart}. Example:
+\begin{verbatim}
+ python restart
+\end{verbatim}
+
+This command restarts the Python interpreter in the Director.
+This can be useful when you are modifying the DirStartUp script,
+because normally Python will cache it, and thus the
+script will be read one time.
+
+\section{Debugging Python Scripts}
+\index[general]{Debugging Python Scripts}
+In general, you debug your Python scripts by using print statements.
+You can also develop your script or important parts of it as a
+separate file using the Python interpreter to run it. Once you
+have it working correctly, you can then call the script from
+within the Bacula Python script (DirStartUp.py).
+
+If you are having problems loading DirStartUp.py, you will probably
+not get any error messages because Bacula can only print Python
+error messages after the Python interpreter is started. However, you
+may be able to see the error messages by starting Bacula in
+a shell window with the {\bf -d1} option on the command line. That
+should cause the Python error messages to be printed in the shell
+window.
+
+If you are getting error messages such as the following when
+loading DirStartUp.py:
+
+\begin{verbatim}
+ Traceback (most recent call last):
+ File "/etc/bacula/scripts/DirStartUp.py", line 6, in ?
+ import time, sys, bacula
+ ImportError: /usr/lib/python2.3/lib-dynload/timemodule.so: undefined
+ symbol: PyInt_FromLong
+ bacula-dir: pythonlib.c:134 Python Import error.
+\end{verbatim}
+
+It is because the DirStartUp script is calling a dynamically loaded
+module (timemodule.so in the above case) that then tries to use
+Python functions exported from the Python interpreter (in this case
+PyInt\_FromLong). The way Bacula is currently linked with Python does
+not permit this. The solution to the problem is to put such functions
+(in this case the import of time into a separate Python script, which
+will do your calculations and return the values you want. Then call
+(not import) this script from the Bacula DirStartUp.py script, and
+it all should work as you expect.
+
+
+
+
+
+\section{Python Example}
+\index[general]{Python Example}
+\index[general]{Example!Python}
+
+An example script for the Director startup file is provided in
+{\bf examples/python/DirStartup.py} as follows:
+
+\footnotesize
+\begin{verbatim}
+#
+# Bacula Python interface script for the Director
+#
+
+# You must import both sys and bacula
+import sys, bacula
+
+# This is the list of Bacula daemon events that you
+# can receive.
+class BaculaEvents(object):
+ def __init__(self):
+ # Called here when a new Bacula Events class is
+ # is created. Normally not used
+ noop = 1
+
+ def JobStart(self, job):
+ """
+ Called here when a new job is started. If you want
+ to do anything with the Job, you must register
+ events you want to receive.
+ """
+ events = JobEvents() # create instance of Job class
+ events.job = job # save Bacula's job pointer
+ job.set_events(events) # register events desired
+ sys.stderr = events # send error output to Bacula
+ sys.stdout = events # send stdout to Bacula
+ jobid = job.JobId; client = job.Client
+ numvols = job.NumVols
+ job.JobReport="Python Dir JobStart: JobId=%d Client=%s NumVols=%d\n" % (jobid,client,numvols)
+
+ # Bacula Job is going to terminate
+ def JobEnd(self, job):
+ jobid = job.JobId
+ client = job.Client
+ job.JobReport="Python Dir JobEnd output: JobId=%d Client=%s.\n" % (jobid, client)
+
+ # Called here when the Bacula daemon is going to exit
+ def Exit(self, job):
+ print "Daemon exiting."
+
+bacula.set_events(BaculaEvents()) # register daemon events desired
+
+"""
+ These are the Job events that you can receive.
+"""
+class JobEvents(object):
+ def __init__(self):
+ # Called here when you instantiate the Job. Not
+ # normally used
+ noop = 1
+
+ def JobInit(self, job):
+ # Called when the job is first scheduled
+ noop = 1
+
+ def JobRun(self, job):
+ # Called just before running the job after initializing
+ # This is the point to change most Job parameters.
+ # It is equivalent to the JobRunBefore point.
+ noop = 1
+
+ def NewVolume(self, job):
+ # Called when Bacula wants a new Volume name. The Volume
+ # name returned, if any, must be stored in job.VolumeName
+ jobid = job.JobId
+ client = job.Client
+ numvol = job.NumVols;
+ print job.CatalogRes
+ job.JobReport = "JobId=%d Client=%s NumVols=%d" % (jobid, client, numvol)
+ job.JobReport="Python before New Volume set for Job.\n"
+ Vol = "TestA-%d" % numvol
+ job.JobReport = "Exists=%d TestA-%d" % (job.DoesVolumeExist(Vol), numvol)
+ job.VolumeName="TestA-%d" % numvol
+ job.JobReport="Python after New Volume set for Job.\n"
+ return 1
+
+ def VolumePurged(self, job):
+ # Called when a Volume is purged. The Volume name can be referenced
+ # with job.VolumeName
+ noop = 1
+
+
+
+\end{verbatim}
+\normalsize
--- /dev/null
+%%
+%%
+
+\chapter{Automatic Volume Recycling}
+\label{RecyclingChapter}
+\index[general]{Recycling!Automatic Volume }
+\index[general]{Automatic Volume Recycling }
+
+By default, once Bacula starts writing a Volume, it can append to the
+volume, but it will not overwrite the existing data thus destroying it.
+However when Bacula {\bf recycles} a Volume, the Volume becomes available
+for being reused, and Bacula can at some later time overwrite the previous
+contents of that Volume. Thus all previous data will be lost. If the
+Volume is a tape, the tape will be rewritten from the beginning. If the
+Volume is a disk file, the file will be truncated before being rewritten.
+
+You may not want Bacula to automatically recycle (reuse) tapes. This would
+require a large number of tapes though, and in such a case, it is possible
+to manually recycle tapes. For more on manual recycling, see the section
+entitled \ilink{ Manually Recycling Volumes}{manualrecycling} below in this
+chapter.
+
+Most people prefer to have a Pool of tapes that are used for daily backups and
+recycled once a week, another Pool of tapes that are used for Full backups
+once a week and recycled monthly, and finally a Pool of tapes that are used
+once a month and recycled after a year or two. With a scheme like this, the
+number of tapes in your pool or pools remains constant.
+
+By properly defining your Volume Pools with appropriate Retention periods,
+Bacula can manage the recycling (such as defined above) automatically.
+
+Automatic recycling of Volumes is controlled by four records in the {\bf
+Pool} resource definition in the Director's configuration file. These four
+records are:
+
+\begin{itemize}
+\item AutoPrune = yes
+\item VolumeRetention = \lt{}time\gt{}
+\item Recycle = yes
+\item RecyclePool = \lt{}APool\gt{} (\textit{This require bacula 2.1.4 or greater})
+\end{itemize}
+
+The above three directives are all you need assuming that you fill
+each of your Volumes then wait the Volume Retention period before
+reusing them. If you want Bacula to stop using a Volume and recycle
+it before it is full, you will need to use one or more additional
+directives such as:
+\begin{itemize}
+\item Use Volume Once = yes
+\item Volume Use Duration = ttt
+\item Maximum Volume Jobs = nnn
+\item Maximum Volume Bytes = mmm
+\end{itemize}
+Please see below and
+the \ilink{Basic Volume Management}{DiskChapter} chapter
+of this manual for more complete examples.
+
+Automatic recycling of Volumes is performed by Bacula only when it wants a
+new Volume and no appendable Volumes are available in the Pool. It will then
+search the Pool for any Volumes with the {\bf Recycle} flag set and whose
+Volume Status is {\bf Full}. At that point, the recycling occurs in two steps.
+The first is that the Catalog for a Volume must be purged of all Jobs and
+Files contained on that Volume, and the second step is the actual recycling of
+the Volume. The Volume will be purged if the VolumeRetention period has
+expired. When a Volume is marked as Purged, it means that no Catalog records
+reference that Volume, and the Volume can be recycled. Until recycling
+actually occurs, the Volume data remains intact. If no Volumes can be found
+for recycling for any of the reasons stated above, Bacula will request
+operator intervention (i.e. it will ask you to label a new volume).
+
+A key point mentioned above, that can be a source of frustration, is that Bacula
+will only recycle purged Volumes if there is no other appendable Volume
+available, otherwise, it will always write to an appendable Volume before
+recycling even if there are Volume marked as Purged. This preserves your data
+as long as possible. So, if you wish to "force" Bacula to use a purged
+Volume, you must first ensure that no other Volume in the Pool is marked {\bf
+Append}. If necessary, you can manually set a volume to {\bf Full}. The reason
+for this is that Bacula wants to preserve the data on your old tapes (even
+though purged from the catalog) as long as absolutely possible before
+overwriting it. There are also a number of directives such as
+{\bf Volume Use Duration} that will automatically mark a volume as {\bf
+Used} and thus no longer appendable.
+
+\label{AutoPruning}
+\section{Automatic Pruning}
+\index[general]{Automatic Pruning}
+\index[general]{Pruning!Automatic}
+
+As Bacula writes files to tape, it keeps a list of files, jobs, and volumes
+in a database called the catalog. Among other things, the database helps
+Bacula to decide which files to back up in an incremental or differential
+backup, and helps you locate files on past backups when you want to restore
+something. However, the catalog will grow larger and larger as time goes
+on, and eventually it can become unacceptably large.
+
+Bacula's process for removing entries from the catalog is called Pruning.
+The default is Automatic Pruning, which means that once an entry reaches a
+certain age (e.g. 30 days old) it is removed from the catalog. Once a job
+has been pruned, you can still restore it from the backup tape, but one
+additional step is required: scanning the volume with bscan. The
+alternative to Automatic Pruning is Manual Pruning, in which you explicitly
+tell Bacula to erase the catalog entries for a volume. You'd usually do
+this when you want to reuse a Bacula volume, because there's no point in
+keeping a list of files that USED TO BE on a tape. Or, if the catalog is
+starting to get too big, you could prune the oldest jobs to save space.
+Manual pruning is done with the \ilink{ prune command}{ManualPruning} in
+the console. (thanks to Bryce Denney for the above explanation).
+
+\section{Pruning Directives}
+\index[general]{Pruning Directives }
+\index[general]{Directives!Pruning }
+
+There are three pruning durations. All apply to catalog database records and
+not to the actual data in a Volume. The pruning (or retention) durations are
+for: Volumes (Media records), Jobs (Job records), and Files (File records).
+The durations inter-depend a bit because if Bacula prunes a Volume, it
+automatically removes all the Job records, and all the File records. Also when
+a Job record is pruned, all the File records for that Job are also pruned
+(deleted) from the catalog.
+
+Having the File records in the database means that you can examine all the
+files backed up for a particular Job. They take the most space in the catalog
+(probably 90-95\% of the total). When the File records are pruned, the Job
+records can remain, and you can still examine what Jobs ran, but not the
+details of the Files backed up. In addition, without the File records, you
+cannot use the Console restore command to restore the files.
+
+When a Job record is pruned, the Volume (Media record) for that Job can still
+remain in the database, and if you do a "list volumes", you will see the
+volume information, but the Job records (and its File records) will no longer
+be available.
+
+In each case, pruning removes information about where older files are, but it
+also prevents the catalog from growing to be too large. You choose the
+retention periods in function of how many files you are backing up and the
+time periods you want to keep those records online, and the size of the
+database. You can always re-insert the records (with 98\% of the original data)
+by using "bscan" to scan in a whole Volume or any part of the volume that
+you want.
+
+By setting {\bf AutoPrune} to {\bf yes} you will permit {\bf Bacula} to
+automatically prune all Volumes in the Pool when a Job needs another Volume.
+Volume pruning means removing records from the catalog. It does not shrink the
+size of the Volume or affect the Volume data until the Volume gets
+overwritten. When a Job requests another volume and there are no Volumes with
+Volume Status {\bf Append} available, Bacula will begin volume pruning. This
+means that all Jobs that are older than the {\bf VolumeRetention} period will
+be pruned from every Volume that has Volume Status {\bf Full} or {\bf Used}
+and has Recycle set to {\bf yes}. Pruning consists of deleting the
+corresponding Job, File, and JobMedia records from the catalog database. No
+change to the physical data on the Volume occurs during the pruning process.
+When all files are pruned from a Volume (i.e. no records in the catalog), the
+Volume will be marked as {\bf Purged} implying that no Jobs remain on the
+volume. The Pool records that control the pruning are described below.
+
+\begin{description}
+
+\item [AutoPrune = \lt{}yes|no\gt{}]
+ \index[console]{AutoPrune }
+ If AutoPrune is set to {\bf yes} (default), Bacula
+ will automatically apply the Volume retention period when running a Job and
+ it needs a new Volume but no appendable volumes are available. At that point,
+ Bacula will prune all Volumes that can be pruned (i.e. AutoPrune set) in an
+ attempt to find a usable volume. If during the autoprune, all files are
+ pruned from the Volume, it will be marked with VolStatus {\bf Purged}. The
+ default is {\bf yes}. Note, that although the File and Job records may be
+ pruned from the catalog, a Volume will be marked Purged (and hence
+ ready for recycling) if the Volume status is Append, Full, Used, or Error.
+ If the Volume has another status, such as Archive, Read-Only, Disabled,
+ Busy, or Cleaning, the Volume status will not be changed to Purged.
+
+\item [Volume Retention = \lt{}time-period-specification\gt{}]
+ \index[console]{Volume Retention}
+ The Volume Retention record defines the length of time that Bacula will
+ guarantee that the Volume is not reused counting from the time the last
+ job stored on the Volume terminated. A key point is that this time
+ period is not even considered as long at the Volume remains appendable.
+ The Volume Retention period count down begins only when the Append
+ status has been changed to some othe status (Full, Used, Purged, ...).
+
+ When this time period expires, and if {\bf AutoPrune} is set to {\bf
+ yes}, and a new Volume is needed, but no appendable Volume is available,
+ Bacula will prune (remove) Job records that are older than the specified
+ Volume Retention period.
+
+ The Volume Retention period takes precedence over any Job Retention
+ period you have specified in the Client resource. It should also be
+ noted, that the Volume Retention period is obtained by reading the
+ Catalog Database Media record rather than the Pool resource record.
+ This means that if you change the VolumeRetention in the Pool resource
+ record, you must ensure that the corresponding change is made in the
+ catalog by using the {\bf update pool} command. Doing so will insure
+ that any new Volumes will be created with the changed Volume Retention
+ period. Any existing Volumes will have their own copy of the Volume
+ Retention period that can only be changed on a Volume by Volume basis
+ using the {\bf update volume} command.
+
+ When all file catalog entries are removed from the volume, its VolStatus is
+ set to {\bf Purged}. The files remain physically on the Volume until the
+ volume is overwritten.
+
+ Retention periods are specified in seconds, minutes, hours, days, weeks,
+ months, quarters, or years on the record. See the
+ \ilink{Configuration chapter}{Time} of this manual for
+ additional details of time specification.
+
+The default is 1 year.
+% TODO: if that is the format, should it be in quotes? decide on a style
+
+\item [Recycle = \lt{}yes|no\gt{}]
+ \index[fd]{Recycle }
+ This statement tells Bacula whether or not the particular Volume can be
+ recycled (i.e. rewritten). If Recycle is set to {\bf no} (the
+ default), then even if Bacula prunes all the Jobs on the volume and it
+ is marked {\bf Purged}, it will not consider the tape for recycling. If
+ Recycle is set to {\bf yes} and all Jobs have been pruned, the volume
+ status will be set to {\bf Purged} and the volume may then be reused
+ when another volume is needed. If the volume is reused, it is relabeled
+ with the same Volume Name, however all previous data will be lost.
+ \end{description}
+
+ It is also possible to "force" pruning of all Volumes in the Pool
+ associated with a Job by adding {\bf Prune Files = yes} to the Job resource.
+
+\label{Recycling}
+\label{RecyclingAlgorithm}
+\section{Recycling Algorithm}
+\index[general]{Algorithm!Recycling }
+\index[general]{Recycling Algorithm }
+
+After all Volumes of a Pool have been pruned (as mentioned above, this happens
+when a Job needs a new Volume and no appendable Volumes are available), Bacula
+will look for the oldest Volume that is Purged (all Jobs and Files expired),
+and if the {\bf Recycle} flag is on (Recycle=yes) for that Volume, Bacula will
+relabel it and write new data on it.
+
+As mentioned above, there are two key points for getting a Volume
+to be recycled. First, the Volume must no longer be marked Append (there
+are a number of directives to automatically make this change), and second
+since the last write on the Volume, one or more of the Retention periods
+must have expired so that there are no more catalog backup job records
+that reference that Volume. Once both those conditions are satisfied,
+the volume can be marked Purged and hence recycled.
+
+The full algorithm that Bacula uses when it needs a new Volume is:
+\index[general]{New Volume Algorithm}
+\index[general]{Algorithm!New Volume}
+
+The algorithm described below assumes that AutoPrune is enabled,
+that Recycling is turned on, and that you have defined
+appropriate Retention periods, or used the defaults for all these
+items.
+
+\begin{itemize}
+\item If the request is for an Autochanger device, look only
+ for Volumes in the Autochanger (i.e. with InChanger set and that have
+ the correct Storage device).
+\item Search the Pool for a Volume with VolStatus=Append (if there is more
+ than one, the Volume with the oldest date last written is chosen. If
+ two have the same date then the one with the lowest MediaId is chosen).
+\item Search the Pool for a Volume with VolStatus=Recycle and the InChanger
+ flag is set true (if there is more than one, the Volume with the oldest
+ date last written is chosen. If two have the same date then the one
+ with the lowest MediaId is chosen).
+\item Try recycling any purged Volumes.
+\item Prune volumes applying Volume retention period (Volumes with VolStatus
+ Full, Used, or Append are pruned). Note, even if all the File and Job
+ records are pruned from a Volume, the Volume will not be marked Purged
+ until the Volume retention period expires.
+\item Search the Pool for a Volume with VolStatus=Purged
+\item If a Pool named "Scratch" exists, search for a Volume and if found
+ move it to the current Pool for the Job and use it. Note, when
+ the Scratch Volume is moved into the current Pool, the basic
+ Pool defaults are applied as if it is a newly labeled Volume
+ (equivalent to an {\bf update volume from pool} command).
+\item If we were looking for Volumes in the Autochanger, go back to
+ step 2 above, but this time, look for any Volume whether or not
+ it is in the Autochanger.
+\item Attempt to create a new Volume if automatic labeling enabled
+ If Python is enabled, a Python NewVolume event is generated before
+ the Label Format directve is used. If the maximum number of Volumes
+ specified for the pool is reached, a new Volume will not be created.
+\item Prune the oldest Volume if RecycleOldestVolume=yes (the Volume with the
+ oldest LastWritten date and VolStatus equal to Full, Recycle, Purged, Used,
+ or Append is chosen). This record ensures that all retention periods are
+ properly respected.
+\item Purge the oldest Volume if PurgeOldestVolume=yes (the Volume with the
+ oldest LastWritten date and VolStatus equal to Full, Recycle, Purged, Used,
+ or Append is chosen). We strongly recommend against the use of {\bf
+ PurgeOldestVolume} as it can quite easily lead to loss of current backup
+ data.
+\item Give up and ask operator.
+\end{itemize}
+
+The above occurs when Bacula has finished writing a Volume or when no Volume
+is present in the drive.
+
+On the other hand, if you have inserted a different Volume after the last job,
+and Bacula recognizes the Volume as valid, it will request authorization from
+the Director to use this Volume. In this case, if you have set {\bf Recycle
+Current Volume = yes} and the Volume is marked as Used or Full, Bacula will
+prune the volume and if all jobs were removed during the pruning (respecting
+the retention periods), the Volume will be recycled and used.
+
+The recycling algorithm in this case is:
+\begin{itemize}
+\item If the VolStatus is {\bf Append} or {\bf Recycle}
+ is set, the volume will be used.
+\item If {\bf Recycle Current Volume} is set and the volume is marked {\bf
+ Full} or {\bf Used}, Bacula will prune the volume (applying the retention
+ period). If all Jobs are pruned from the volume, it will be recycled.
+\end{itemize}
+
+This permits users to manually change the Volume every day and load tapes in
+an order different from what is in the catalog, and if the volume does not
+contain a current copy of your backup data, it will be used.
+
+A few points from Alan Brown to keep in mind:
+
+\begin{enumerate}
+\item If a pool doesn't have maximum volumes defined then Bacula will prefer to
+ demand new volumes over forcibly purging older volumes.
+
+\item If volumes become free through pruning and the Volume retention period has
+ expired, then they get marked as "purged" and are immediately available for
+ recycling - these will be used in preference to creating new volumes.
+
+\item If the Job, File, and Volume retention periods are different, then
+ it's common to see a tape with no files or jobs listed in the database,
+ but which is still not marked as "purged".
+\end{enumerate}
+
+
+\section{Recycle Status}
+\index[general]{Status!Recycle }
+\index[general]{Recycle Status }
+
+Each Volume inherits the Recycle status (yes or no) from the Pool resource
+record when the Media record is created (normally when the Volume is labeled).
+This Recycle status is stored in the Media record of the Catalog. Using
+the Console program, you may subsequently change the Recycle status for each
+Volume. For example in the following output from {\bf list volumes}:
+
+\footnotesize
+\begin{verbatim}
++----------+-------+--------+---------+------------+--------+-----+
+| VolumeNa | Media | VolSta | VolByte | LastWritte | VolRet | Rec |
++----------+-------+--------+---------+------------+--------+-----+
+| File0001 | File | Full | 4190055 | 2002-05-25 | 14400 | 1 |
+| File0002 | File | Full | 1896460 | 2002-05-26 | 14400 | 1 |
+| File0003 | File | Full | 1896460 | 2002-05-26 | 14400 | 1 |
+| File0004 | File | Full | 1896460 | 2002-05-26 | 14400 | 1 |
+| File0005 | File | Full | 1896460 | 2002-05-26 | 14400 | 1 |
+| File0006 | File | Full | 1896460 | 2002-05-26 | 14400 | 1 |
+| File0007 | File | Purged | 1896466 | 2002-05-26 | 14400 | 1 |
++----------+-------+--------+---------+------------+--------+-----+
+\end{verbatim}
+\normalsize
+
+all the volumes are marked as recyclable, and the last Volume, {\bf File0007}
+has been purged, so it may be immediately recycled. The other volumes are all
+marked recyclable and when their Volume Retention period (14400 seconds or four
+hours) expires, they will be eligible for pruning, and possibly recycling.
+Even though Volume {\bf File0007} has been purged, all the data on the Volume
+is still recoverable. A purged Volume simply means that there are no entries
+in the Catalog. Even if the Volume Status is changed to {\bf Recycle}, the
+data on the Volume will be recoverable. The data is lost only when the Volume
+is re-labeled and re-written.
+
+To modify Volume {\bf File0001} so that it cannot be recycled, you use the
+{\bf update volume pool=File} command in the console program, or simply {\bf
+update} and Bacula will prompt you for the information.
+
+\footnotesize
+\begin{verbatim}
++----------+------+-------+---------+-------------+-------+-----+
+| VolumeNa | Media| VolSta| VolByte | LastWritten | VolRet| Rec |
++----------+------+-------+---------+-------------+-------+-----+
+| File0001 | File | Full | 4190055 | 2002-05-25 | 14400 | 0 |
+| File0002 | File | Full | 1897236 | 2002-05-26 | 14400 | 1 |
+| File0003 | File | Full | 1896460 | 2002-05-26 | 14400 | 1 |
+| File0004 | File | Full | 1896460 | 2002-05-26 | 14400 | 1 |
+| File0005 | File | Full | 1896460 | 2002-05-26 | 14400 | 1 |
+| File0006 | File | Full | 1896460 | 2002-05-26 | 14400 | 1 |
+| File0007 | File | Purged| 1896466 | 2002-05-26 | 14400 | 1 |
++----------+------+-------+---------+-------------+-------+-----+
+\end{verbatim}
+\normalsize
+
+In this case, {\bf File0001} will never be automatically recycled. The same
+effect can be achieved by setting the Volume Status to Read-Only.
+
+As you have noted, the Volume Status (VolStatus) column in the
+catalog database contains the current status of the Volume, which
+is normally maintained automatically by Bacula. To give you an
+idea of some of the values it can take during the life cycle of
+a Volume, here is a picture created by Arno Lehmann:
+
+\footnotesize
+\begin{verbatim}
+A typical volume life cycle is like this:
+
+ because job count or size limit exceeded
+ Append ----------------------------------------> Used
+ ^ |
+ | First Job writes to Retention time passed |
+ | the volume and recycling takes |
+ | place |
+ | v
+ Recycled <-------------------------------------- Purged
+ Volume is selected for reuse
+
+\end{verbatim}
+\normalsize
+
+
+\section{Making Bacula Use a Single Tape}
+\label{singletape}
+\index[general]{Tape!Making Bacula Use a Single}
+\index[general]{Making Bacula Use a Single Tape}
+
+Most people will want Bacula to fill a tape and when it is full, a new tape
+will be mounted, and so on. However, as an extreme example, it is possible for
+Bacula to write on a single tape, and every night to rewrite it. To get this
+to work, you must do two things: first, set the VolumeRetention to less than
+your save period (one day), and the second item is to make Bacula mark the
+tape as full after using it once. This is done using {\bf UseVolumeOnce =
+yes}. If this latter record is not used and the tape is not full after the
+first time it is written, Bacula will simply append to the tape and eventually
+request another volume. Using the tape only once, forces the tape to be marked
+{\bf Full} after each use, and the next time {\bf Bacula} runs, it will
+recycle the tape.
+
+An example Pool resource that does this is:
+
+\footnotesize
+\begin{verbatim}
+Pool {
+ Name = DDS-4
+ Use Volume Once = yes
+ Pool Type = Backup
+ AutoPrune = yes
+ VolumeRetention = 12h # expire after 12 hours
+ Recycle = yes
+}
+\end{verbatim}
+\normalsize
+
+\section{Daily, Weekly, Monthly Tape Usage Example}
+\label{usageexample}
+\index[general]{Daily, Weekly, Monthly Tape Usage Example }
+\index[general]{Example!Daily Weekly Monthly Tape Usage }
+
+This example is meant to show you how one could define a fixed set of volumes
+that Bacula will rotate through on a regular schedule. There are an infinite
+number of such schemes, all of which have various advantages and
+disadvantages.
+
+We start with the following assumptions:
+
+\begin{itemize}
+\item A single tape has more than enough capacity to do a full save.
+\item There are ten tapes that are used on a daily basis for incremental
+ backups. They are prelabeled Daily1 ... Daily10.
+\item There are four tapes that are used on a weekly basis for full backups.
+ They are labeled Week1 ... Week4.
+\item There are 12 tapes that are used on a monthly basis for full backups.
+ They are numbered Month1 ... Month12
+\item A full backup is done every Saturday evening (tape inserted Friday
+ evening before leaving work).
+\item No backups are done over the weekend (this is easy to change).
+\item The first Friday of each month, a Monthly tape is used for the Full
+ backup.
+\item Incremental backups are done Monday - Friday (actually Tue-Fri
+ mornings).
+% TODO: why this "actually"? does this need to be explained?
+ \end{itemize}
+
+We start the system by doing a Full save to one of the weekly volumes or one
+of the monthly volumes. The next morning, we remove the tape and insert a
+Daily tape. Friday evening, we remove the Daily tape and insert the next tape
+in the Weekly series. Monday, we remove the Weekly tape and re-insert the
+Daily tape. On the first Friday of the next month, we insert the next Monthly
+tape in the series rather than a Weekly tape, then continue. When a Daily tape
+finally fills up, {\bf Bacula} will request the next one in the series, and
+the next day when you notice the email message, you will mount it and {\bf
+Bacula} will finish the unfinished incremental backup.
+
+What does this give? Well, at any point, you will have the last complete
+Full save plus several Incremental saves. For any given file you want to
+recover (or your whole system), you will have a copy of that file every day
+for at least the last 14 days. For older versions, you will have at least three
+and probably four Friday full saves of that file, and going back further, you
+will have a copy of that file made on the beginning of the month for at least
+a year.
+
+So you have copies of any file (or your whole system) for at least a year, but
+as you go back in time, the time between copies increases from daily to weekly
+to monthly.
+
+What would the Bacula configuration look like to implement such a scheme?
+
+\footnotesize
+\begin{verbatim}
+Schedule {
+ Name = "NightlySave"
+ Run = Level=Full Pool=Monthly 1st sat at 03:05
+ Run = Level=Full Pool=Weekly 2nd-5th sat at 03:05
+ Run = Level=Incremental Pool=Daily tue-fri at 03:05
+}
+Job {
+ Name = "NightlySave"
+ Type = Backup
+ Level = Full
+ Client = LocalMachine
+ FileSet = "File Set"
+ Messages = Standard
+ Storage = DDS-4
+ Pool = Daily
+ Schedule = "NightlySave"
+}
+# Definition of file storage device
+Storage {
+ Name = DDS-4
+ Address = localhost
+ SDPort = 9103
+ Password = XXXXXXXXXXXXX
+ Device = FileStorage
+ Media Type = 8mm
+}
+FileSet {
+ Name = "File Set"
+ Include = signature=MD5 {
+ fffffffffffffffff
+ }
+ Exclude = { *.o }
+}
+Pool {
+ Name = Daily
+ Pool Type = Backup
+ AutoPrune = yes
+ VolumeRetention = 10d # recycle in 10 days
+ Maximum Volumes = 10
+ Recycle = yes
+}
+Pool {
+ Name = Weekly
+ Use Volume Once = yes
+ Pool Type = Backup
+ AutoPrune = yes
+ VolumeRetention = 30d # recycle in 30 days (default)
+ Recycle = yes
+}
+Pool {
+ Name = Monthly
+ Use Volume Once = yes
+ Pool Type = Backup
+ AutoPrune = yes
+ VolumeRetention = 365d # recycle in 1 year
+ Recycle = yes
+}
+\end{verbatim}
+\normalsize
+
+\section{ Automatic Pruning and Recycling Example}
+\label{PruningExample}
+\index[general]{Automatic Pruning and Recycling Example }
+\index[general]{Example!Automatic Pruning and Recycling }
+
+Perhaps the best way to understand the various resource records that come into
+play during automatic pruning and recycling is to run a Job that goes through
+the whole cycle. If you add the following resources to your Director's
+configuration file:
+
+\footnotesize
+\begin{verbatim}
+Schedule {
+ Name = "30 minute cycle"
+ Run = Level=Full Pool=File Messages=Standard Storage=File
+ hourly at 0:05
+ Run = Level=Full Pool=File Messages=Standard Storage=File
+ hourly at 0:35
+}
+Job {
+ Name = "Filetest"
+ Type = Backup
+ Level = Full
+ Client=XXXXXXXXXX
+ FileSet="Test Files"
+ Messages = Standard
+ Storage = File
+ Pool = File
+ Schedule = "30 minute cycle"
+}
+# Definition of file storage device
+Storage {
+ Name = File
+ Address = XXXXXXXXXXX
+ SDPort = 9103
+ Password = XXXXXXXXXXXXX
+ Device = FileStorage
+ Media Type = File
+}
+FileSet {
+ Name = "Test Files"
+ Include = signature=MD5 {
+ fffffffffffffffff
+ }
+ Exclude = { *.o }
+}
+Pool {
+ Name = File
+ Use Volume Once = yes
+ Pool Type = Backup
+ LabelFormat = "File"
+ AutoPrune = yes
+ VolumeRetention = 4h
+ Maximum Volumes = 12
+ Recycle = yes
+}
+\end{verbatim}
+\normalsize
+
+Where you will need to replace the {\bf ffffffffff}'s by the appropriate files
+to be saved for your configuration. For the FileSet Include, choose a
+directory that has one or two megabytes maximum since there will probably be
+approximately eight copies of the directory that {\bf Bacula} will cycle through.
+
+In addition, you will need to add the following to your Storage daemon's
+configuration file:
+
+\footnotesize
+\begin{verbatim}
+Device {
+ Name = FileStorage
+ Media Type = File
+ Archive Device = /tmp
+ LabelMedia = yes;
+ Random Access = Yes;
+ AutomaticMount = yes;
+ RemovableMedia = no;
+ AlwaysOpen = no;
+}
+\end{verbatim}
+\normalsize
+
+With the above resources, Bacula will start a Job every half hour that saves a
+copy of the directory you chose to /tmp/File0001 ... /tmp/File0012. After 4
+hours, Bacula will start recycling the backup Volumes (/tmp/File0001 ...). You
+should see this happening in the output produced. Bacula will automatically
+create the Volumes (Files) the first time it uses them.
+
+To turn it off, either delete all the resources you've added, or simply
+comment out the {\bf Schedule} record in the {\bf Job} resource.
+
+\section{Manually Recycling Volumes}
+\label{manualrecycling}
+\index[general]{Volumes!Manually Recycling }
+\index[general]{Manually Recycling Volumes }
+
+Although automatic recycling of Volumes is implemented in version 1.20 and
+later (see the
+\ilink{Automatic Recycling of Volumes}{RecyclingChapter} chapter of
+this manual), you may want to manually force reuse (recycling) of a Volume.
+
+Assuming that you want to keep the Volume name, but you simply want to write
+new data on the tape, the steps to take are:
+
+\begin{itemize}
+\item Use the {\bf update volume} command in the Console to ensure that the
+ {\bf Recycle} field is set to {\bf 1}
+\item Use the {\bf purge jobs volume} command in the Console to mark the
+ Volume as {\bf Purged}. Check by using {\bf list volumes}.
+\end{itemize}
+
+Once the Volume is marked Purged, it will be recycled the next time a Volume
+is needed.
+
+If you wish to reuse the tape by giving it a new name, follow the following
+steps:
+
+\begin{itemize}
+\item Use the {\bf purge jobs volume} command in the Console to mark the
+ Volume as {\bf Purged}. Check by using {\bf list volumes}.
+\item In Bacula version 1.30 or greater, use the Console {\bf relabel}
+ command to relabel the Volume.
+\end{itemize}
+
+Please note that the relabel command applies only to tape Volumes.
+
+For Bacula versions prior to 1.30 or to manually relabel the Volume, use the
+instructions below:
+
+\begin{itemize}
+\item Use the {\bf delete volume} command in the Console to delete the Volume
+ from the Catalog.
+\item If a different tape is mounted, use the {\bf unmount} command,
+ remove the tape, and insert the tape to be renamed.
+\item Write an EOF mark in the tape using the following commands:
+
+\footnotesize
+\begin{verbatim}
+ mt -f /dev/nst0 rewind
+ mt -f /dev/nst0 weof
+\end{verbatim}
+\normalsize
+
+where you replace {\bf /dev/nst0} with the appropriate device name on your
+system.
+\item Use the {\bf label} command to write a new label to the tape and to
+ enter it in the catalog.
+\end{itemize}
+
+Please be aware that the {\bf delete} command can be dangerous. Once it is
+done, to recover the File records, you must either restore your database as it
+was before the {\bf delete} command, or use the {\bf bscan} utility program to
+scan the tape and recreate the database entries.
--- /dev/null
+%%
+%%
+
+\chapter{Caract\'eristiques syst\`eme g\'en\'erales indispensables \`a Bacula}
+\label{_ChapterStart51}
+\index[general]{Caract\'eristiques syst\`eme g\'en\'erales indispensables \`a Bacula }
+\index[general]{Bacula!Caract\'eristiques syst\`eme g\'en\'erales indispensables \`a }
+\addcontentsline{toc}{section}{Caract\'eristiques syst\`eme g\'en\'erales indispensables \`a Bacula}
+
+\label{SysReqs}
+
+\section{Caract\'eristiques syst\`eme g\'en\'erales indispensables \`a Bacula}
+\index[general]{Caract\'eristiques syst\`eme g\'en\'erales indispensables \`a Bacula }
+\index[general]{Bacula!Caract\'eristiques syst\`eme g\'en\'erales indispensables \`a }
+\addcontentsline{toc}{section}{Caract\'eristiques syst\`eme g\'en\'erales indispensables \`a Bacula}
+
+\begin{itemize}
+\item {\bf Bacula} a \'et\'e compil\'e et ex\'ecut\'e sur les syst\`emes
+ Linux RedHat, Mandriva, SUSE, Debian et Gentoo, sur FreeBSD, et Solaris.
+\item Il requiert GNU C++ version 2.95 ou sup\'erieur pour compiler. Vous
+ pouvez essayer avec d'autres compilateurs et des versions plus anciennes, mais
+ vous serez seuls. Nous avons compil\'e et utilis\'e avec succ\`es Bacula sur
+RH8.0/RH9/RHEL 3.0 avec GCC 3.2. Note, en g\'en\'eral GNU C++ est un paquet
+s\'epar\'e (e.g. RPM) de GNU C, et vous devrez avoir les deux. Sur les
+syst\`emes RedHat, le compilateur C++ fait partie du paquet RPM {\bf
+gcc-c++}.
+\item Certains paquets tiers sont n\'ecessaires \`a {\bf Bacula}.
+ Except\'e pour MySQL et PostgreSQL, ils peuvent tous \^etre trouv\'es dans
+ les distributions {\bf depkgs} et {\bf depkgs1}.
+\item Si vous voulez construire les binaires Win32, vous aurez besoin du
+ compilateur Microsoft Visual C++ (ou Visual Studio). Bien que tous les
+ composants compilent (la console produit quelques messages d'alertes), seul
+le File Daemon a \'et\'e test\'e.
+\item {\bf Bacula} requiert une bonne impl\'ementation fonctionnelle des
+ pthreads. Ce n'est pas le cas sur certains syst\`emes BSD.
+\item Le code source a \'et\'e \'ecrit dans un esprit de portabilit\'e et est
+ le plus souvent compatible POSIX. Ainsi le portage sur chaque syst\`eme
+ d'exploitation compatible POSIX est relativement ais\'e.
+\item Le programme GNOME Console est developp\'e et test\'e sous GNOME 2.X.
+ Il s'ex\'ecute aussi sous GNOME 1.4 mais cette version est d\'epr\'eci\'ee et
+ n'est plus maintenue.
+\item Le programme wxWidgets Console est developp\'e et test\'e avec la
+ derni\`ere version stable de
+ \elink{ wxWidgets}{http://www.wxwidgets.org/} (2.4.2). Il fonctionne bien
+avec la version Windows et GTK+-1.x de wxWidgets, ainsi que sur les autres
+plateformes support\'ees par wxWidgets.
+\item Le programme Tray Monitor est developp\'e pour GTK+-2.x. Il n\'ecessite
+ Gnome \gt{}=2.2, KDE \gt{}=3.1 ou un gestionnaire de fen\^etre supportant le
+ standard
+\elink{systemtray}{http://www.freedesktop.org/Standards/systemtray-spec} de
+FreeDesktop.
+\item Si vous voulez permettre l'\'edition en ligne de commande et
+ l'historique, il vous faudra /usr/include/termcap.h et l'une des
+ biblioth\`eques termcap ou ncurses charg\'ee (libtermcap-devel ou
+ncurses-devel).
+\item Si vous voulez utiliser des DVD en guise de media de sauvegarde, vous devrez
+ t\'el\'echarger les \elink{dvd+rw-tools 5.21.4.10.8}{http://fy.chalmers.se/~appro/linux/DVD+RW/},
+ appliquer le \elink{patch}{http://cvs.sourceforge.net/viewcvs.py/*checkout*/bacula/bacula/patches/dvd+rw-tools-5.21.4.10.8.bacula.patch}
+ pour rendre ces outils compatibles avec Bacula, puis les compiler et installer.
+ N'utilisez pas les dvd+rw-tools fournis par votre distribution, ils ne
+ fonctionneront pas avec Bacula.
+
+\end{itemize}
--- /dev/null
+%%
+%%
+
+\chapter{La commande restore de la console Bacula}
+\label{_ChapterStart13}
+\index[general]{Commande!restore de la console Bacula}
+\index[general]{La commande restore de la console Bacula}
+\addcontentsline{toc}{section}{La commande restore de la console Bacula}
+
+\section{G\'en\'eralit\'es}
+\index[general]{G\'en\'eralit\'es}
+\addcontentsline{toc}{section}{G\'en\'eralit\'es}
+
+Nous allons maintenant d\'ecrire la restauration de fichiers avec la commande
+{\bf restore} de la Console, qui est le mode de restauration recommand\'e.
+Il existe cependant un programme ind\'ependant nomm\'e {\bf bextract}, qui permet
+lui aussi de restaurer des fichiers. Pour plus d'informations sur ce
+programme, consultez le chapitre \ilink{Programmes utilitaires Bacula}{bextract}
+de ce manuel. Vous y trouverez aussi des informations sur le programme {\bf bls}
+qui sert \`a produire une liste du contenu de vos volumes, et sur le programme
+{\bf bscan} qui vous sera utilie si vous voulez restaurer les enregistrements
+du catalogue relatifs \`a un ancien volume qui n'y figure plus.
+
+En g\'en\'eral, pour restaurer un fichier ou un ensemble de fichiers, vous devez
+ex\'ecuter un job de type {\bf restore}, par cons\'equent, vous devez pr\'ed\'efinir
+un tel job dans le fichier de configuration de votre Director. Les param\`etres
+(Client, FileSet,...) que vous d\'efinissez ici ne sont pas importants,
+Bacula les ajustera automatiquement lors de l'utilisation de {\bf restore}.
+
+Bacula \'etant un programme r\'eseau, il vous appartient de vous assurer que
+vous avez s\'electionn\'e le bon client et le bon disque dur pour recevoir la
+restauration. Bacula peut sauvegarder le client A et restaurer ses fichiers
+sur le client B, pourvu que leurs syst\`emes ne soient pas trop diff\'erents
+au niveau de leurs structures de fichiers. Par d\'efaut, Bacula restaure les
+donn\'ees sur leur client d'origine, mais pas \`a leur emplacement d'origine :
+dans le r\'epertoire {\bf /tmp/bacula-restores}. Vous pouvez modifier ces
+valeurs par d\'efaut lorsque la commande {\bf restore} vous demande confirmation
+d'ex\'ecution du job en choisissant l'option {\bf mod}.
+
+\label{Example1}
+\section{La commande Restore}
+\index[general]{Commande!Restore }
+\index[general]{La commande Restore}
+\addcontentsline{toc}{section}{La commande Restore}
+Puisque Bacula maintient un catalogue des fichiers sauvegard\'es, et des volumes
+o\`u ils sont stock\'es, il peut se charger de la majeure partie du travail
+d'intendance. Ainsi, il vous suffit de sp\'ecifier le type de restauration que
+vous souhaitez (d'apr\`es la derni\`ere sauvegarde, d'apr\`es la derni\`ere sauvegarde
+ant\'erieure \`a une date sp\'ecifi\'ee...), et quels fichiers vous voulez restaurer.
+
+Ceci est r\'ealis\'e par la commande {\bf restore} de la Console. Vous s\'electionnez
+d'abord le type de restauration souhait\'ee ce qui entra\^ine la s\'election des
+JobIds requis et la construction d'une arborescence interne \`a Bacula contenant
+les enregistrements de fichiers des JobIds s\'electionn\'es. A ce stade, le
+processus de restauration entre dans un mode o\`u vous pouvez naviguer
+interactivement dans l'arborescence des fichiers disponibles pour restauration
+et s\'electionner ceux que vous voulez restaurer. Ce mode est similaire au
+programme de s\'election de fichier interactif standard d'Unix {\bf restore}.
+
+Si vos fichiers ont \'et\'e \'elagu\'es, la commande {\bf restore} sera dans
+l'incapacit\'e de les trouver. Voyez ci-dessous pour plus de d\'etails sur ce cas
+de figure.
+
+Dans la Console, apr\`es avoir saisi {\bf restore}, le menu suivant vous est
+pr\'esent\'e :
+
+\footnotesize
+\begin{verbatim}
+First you select one or more JobIds that contain files
+to be restored. You will be presented several methods
+of specifying the JobIds. Then you will be allowed to
+select which files from those JobIds are to be restored.
+To select the JobIds, you have the following choices:
+ 1: List last 20 Jobs run
+ 2: List Jobs where a given File is saved
+ 3: Enter list of comma separated JobIds to select
+ 4: Enter SQL list command
+ 5: Select the most recent backup for a client
+ 6: Select backup for a client before a specified time
+ 7: Enter a list of files to restore
+ 8: Enter a list of files to restore before a specified time
+ 9: Find the JobIds of the most recent backup for a client
+ 10: Find the JobIds for a backup for a client before a specified time
+ 11: Enter a list of directories to restore for found JobIds
+ 12: Cancel
+Select item: (1-12):
+\end{verbatim}
+\normalsize
+
+\begin{itemize}
+\item Le choix 1 \'enum\`ere les 20 derniers jobs ex\'ecut\'es. Si vous trouvez
+ celui (ceux) que vous voulez, vous pouvez ensuite faire le choix 3 et entrer
+ son (leurs) JobId(s).
+
+\item Le choix 2 affiche tous les Jobs ayant sauvegard\'e un fichier
+ sp\'ecifi\'e. Si vous trouvez celui (ceux) que vous voulez, vous pouvez ensuite
+ faire le choix 3 et entrer son (leurs) JobId(s).
+
+\item Le choix 3 vous permet de saisir une liste de JobIds, s\'epar\'es par des
+ virgules. Les fichiers de ces jobs seront plac\'es dans l'arborescence afin
+ que vous puissiez s\'electionner ceux que vous voulez restaurer.
+
+\item Le choix 4 vous permet d'entrer une requ\^ete SQL arbitraire. C'est
+ certainement le moyen le plus primitif pour trouver les jobs d\'esir\'es,
+ mais aussi le plus flexible. Si vous trouvez celui (ceux) que vous voulez,
+ vous pouvez ensuite faire le choix 3 et entrer son (leurs) JobId(s).
+
+\item Le choix 5 s\'electionne automatiquement la full la plus r\'ecente, et toutes
+ les incr\'ementales et diff\'erentielles subs\'equentes \`a cette full pour un
+ client sp\'ecifi\'e. Il s'agit l\`a des jobs et fichiers qui, si vous les
+ restaurez, ram\`eneront votre syst\`eme \`a son dernier \'etat sauvegard\'e.
+ Les JobIds sont automatiquement charg\'es dans l'arborescence. C'est
+ probablement le plus pratique des choix propos\'es pour restaurer un
+ client \`a son \'etat le plus r\'ecent.
+
+ Notez que ce processus de s\'election automatique ne s\'electionnera jamais
+ un job qui a \'echou\'e (termin\'e avec un statut d'erreur). Si vous disposez
+ d'un tel job dont vous voulez extraire des fichiers, vous devez
+ eplicitement entrer son JobId au niveau du choix 3 et choisir les fichiers
+ \`a restaurer.
+
+ Si certains de jobs requis pour la restauration ont eu leurs enregistrements
+ de fichiers \'elagu\'es, la restauration sera incompl\`ete. Bacula ne d\'etecte
+ pas, pour l'instant, cette condition. Vous pouvez cependant la
+ contr\^oler en examinant attentivement la liste des jobs s\'electionn\'es
+ et affich\'es par Bacula. Si vous trouvez des jobs dont le champ JobFiles
+ est \`a z\'ero alors que ces fichiers auraient d\^u \^etre sauvegard\'es, alors
+ vous pouvez vous attendre \`a des probl\`emes.
+
+ Si tous les enregistrements de fichiers ont \'et\'e \'elagu\'es, Bacula constatera
+ qu'il n'y a aucune r\'ef\'erence \`a aucun fichier pour le JobIds s\'electionn\'es
+ et vous en informera, et vous proposera de faire une restauration compl\`ete
+ (non s\'elective) de ces JobIds. Ceci est possible car Bacula sait encore
+ o\`u commencent les donn\'ees sur les volumes, m\^eme s'il ne sait plus o\`u sont
+ les fichiers individuellement.
+
+\item Le choix 6 vous permet de sp\'ecifier une date et un heure. Bacula
+ s\'electionne alors automatiquement la plus r\'ecente full ant\'erieure \`a cette date
+ ainsi que les incr\'ementales et diff\'erentielles subs\'equentes \`a cette full et
+ ant\'erieures \`a cette date.
+
+\item Le choix 7 vous permet de sp\'ecifier un ou plusieurs noms de fichiers
+ (le chemin absolu est requis) \`a restaurer. Les noms de fichiers sont saisis
+ un par un, \`a moins que vous ne pr\'ef\'eriez cr\'eer un fichier pr\'efix\'e du
+ caract\`ere "moins" (\lt{}) que Bacula consid\`ere comme une liste de fichier
+ \`a restaurer. Pour quitter ce mode, entrez une ligne vide.
+
+\item Le choix 8 vous permet de sp\'ecifier une date et une heure avant
+ d'entrer les noms de fichiers. Voir le choix 7 pour plus de d\'etails.
+
+\item Le choix 9 vous permet de d\'eterminer les JobIds de la sauvegarde
+ la plus r\'ecente pour un client. C'est essentiellement la m\^eme chose
+ que le choix 5 (le m\^eme code est utilis\'e), mais ces JobIds sont
+ conserv\'es en interne comme si vous les aviez saisis manuellement.
+ Vous pouvez alors faire le choix 11 pour restaurer un ou plusieurs
+ r\'epertoires.
+
+\item Le choix 10 est le m\^eme que le 9, sauf qu'il vous permet d'entrer
+ une date butoir (comme pour le choix 6) pour la s\'election des JobIds.
+ Ces JobIds sont conserv\'es en interne comme si vous les aviez saisis manuellement.
+
+\index[general]{Restaurer des r\'epertoires}
+\item Le choix 11 vous permet d'entrer une liste de JobIds \`a partir de
+ laquelle vous pouvez s\'electionner les r\'epertoires \`a restaurer. La liste de
+ JobIds peut avoir \'et\'e \'etablie pr\'ec\'edemment \`a l'aide des choix 9 ou 10
+ du menu. Vous pouvez alors entrer le chemin absolu d'un r\'epertoire, ou
+ un nom de fichier pr\'efix\'e d'un signe "moins" (\lt{}) contenant la liste
+ des r\'epertoires \`a restaurer. Tous les fichiers des r\'epertoires s\'electionn\'es
+ seront restaur\'es, mais pas les sous-r\'epertoires, \`a moins que vous ne les
+ sp\'ecifiiez explicitement.
+
+\item Le choix 12 vous permet d'abandonner la restauration.
+\end{itemize}
+
+A titre d'exemple, supposons que nous s\'electionnions l'option 5 (restaurer \`a
+l'\'etat le plus r\'ecent). Bacula vous demande alors le client d\'esir\'e ce qui,
+sur mon syst\`eme, se manifeste ainsi :
+
+\footnotesize
+\begin{verbatim}
+Defined clients:
+ 1: Rufus
+ 2: Matou
+ 3: Polymatou
+ 4: Minimatou
+ 5: Minou
+ 6: MatouVerify
+ 7: PmatouVerify
+ 8: RufusVerify
+ 9: Watchdog
+Select Client (File daemon) resource (1-9):
+
+\end{verbatim}
+\normalsize
+
+Si vous n'avez qu'un client, il est automatiquement s\'electionn\'e. Dans le cas
+pr\'esent, j'entre {\bf Rufus} pour s\'electionner ce client. Bacula a
+maintenant conna\^itre le FileSet \`a restaurer, aussi il affiche :
+
+\footnotesize
+\begin{verbatim}
+The defined FileSet resources are:
+ 1: Full Set
+ 2: Kerns Files
+Select FileSet resource (1-2):
+
+\end{verbatim}
+\normalsize
+
+J'opte pour le choix 1, ma sauvegarde full. En principe, vous n'aurez qu'un
+FileSet pour chaque job, et si vos machines de ressemblent (m\^emes syst\`emes),
+vous pouvez n'avoir qu'un seul FileSet pour tous vos clients.
+
+A ce stade, Bacula d\'etient toutes les informations dont il a besoin pour
+trouver le jeu de sauvegardes le plus r\'ecent. Il va maintenant interroger le
+cataloguie, ce qui peut prendre un peu de temps, et afficher quelque chose
+comme :
+
+\footnotesize
+\begin{verbatim}
++-------+------+----------+-------------+-------------+------+-------+----------
+--+
+| JobId | Levl | JobFiles | StartTime | VolumeName | File | SesId |
+VolSesTime |
++-------+------+----------+-------------+-------------+------+-------+----------
+--+
+| 1,792 | F | 128,374 | 08-03 01:58 | DLT-19Jul02 | 67 | 18 |
+1028042998 |
+| 1,792 | F | 128,374 | 08-03 01:58 | DLT-04Aug02 | 0 | 18 |
+1028042998 |
+| 1,797 | I | 254 | 08-04 13:53 | DLT-04Aug02 | 5 | 23 |
+1028042998 |
+| 1,798 | I | 15 | 08-05 01:05 | DLT-04Aug02 | 6 | 24 |
+1028042998 |
++-------+------+----------+-------------+-------------+------+-------+----------
+--+
+You have selected the following JobId: 1792,1792,1797
+Building directory tree for JobId 1792 ...
+Building directory tree for JobId 1797 ...
+Building directory tree for JobId 1798 ...
+cwd is: /
+$
+\end{verbatim}
+\normalsize
+
+(Certaines colonnes sont tromqu\'ees pour des n\'ecessit\'es de mise en page).
+
+Selon le nombre de {\bf JobFiles} pour chaque JobId, la construction de
+l'arborescence peut prendre un certain temps. Si vous constatez que tous les
+JobFiles sont \`a z\'ero, vos fichiers ont probalement \'et\'e \'elagu\'es et vous ne
+pourrez pas s\'electionner les fichiers individuellement : vous devrez
+restaurer tout ou rien.
+
+Dans notre exemple, Bacula a trouv\'e quatre jobs qui comprennent la
+sauvegarde la plus r\'ecente du client et du FileSet sp\'ecifi\'es. Deux des jobs
+ont le m\^eme JobId car le job a \'ecrit sur deux volumes diff\'erents. Le
+troisi\`eme est une incr\'ementale qui n'a sauvegard\'e que 254 fichier sur les
+128 374 de la full. Le quatri\`eme est aussi une incr\'ementale, et n'a sauvegard\'e
+que 15 fichiers.
+
+Maintenant Bacula ins\`ere ces jobs dans l'arborescence, sans en marquer aucun
+pour restauration par d\'efaut. Il vous indique le nombre de fichiers dans
+l'arbre, et vous informe que le r\'epertoire de travail courant ({\bf cwd}) est
+/. Finalement, Bacula vous invite avec le signe (\$) \`a saisir des commandes
+pour vous d\'eplacer dans l'arborescence, et s\'electionner des fichiers.
+
+Si vous voulez que tous les fichiers de l'arbre soient marqu\'es pour
+restauration \`a sa construction, tapez {\bf restore all}.
+
+Plut\^ot que de choisir l'option 5 du premier menu (s\'electionner la
+sauvegarde la plus r\'ecente pour un client), si nous avions choisi l'option 3
+(Entrer une liste de JobIds \`a s\'electionner), et si nous avions saisi
+{\bf 1792,1797,1798}, nous serions arriv\'es au m\^eme point.
+
+Il faut noter un point si vous saisissez manuellement les JobIds : vous devez
+les entrer dans l'ordre o\`u ils ont \'et\'e ex\'ecut\'es (en g\'en\'eral, l'ordre croissant.
+Si vous les sasissez dans un ordre diff\'erent, vous courrez le risque de ne pas
+version la plus r\'ecente d'un fichier sauvegard\'e plusieurs fois si celui-ci a \'et\'e
+sauvegard\'e dans plusieurs jobs.
+
+Entre vos JobIds directement peut aussi vous permettre de restaurer depuis
+un job qui a \'ecrit des donn\'ees sur les volumes mais qui s'est termin\'e en erreur.
+
+Dans le mode s\'election de fichiers, vous pouvez utiliser {\bf help} ou une
+question (?) pour produire un r\'esum\'e des commandes disponibles :
+
+\footnotesize
+\begin{verbatim}
+ Command Description
+ ======= ===========
+ cd change current directory
+ count count marked files in and below the cd
+ dir long list current directory, wildcards allowed
+ done leave file selection mode
+ estimate estimate restore size
+ exit same as done command
+ find find files, wildcards allowed
+ help print help
+ ls list current directory, wildcards allowed
+ lsmark list the marked files in and below the cd
+ mark mark dir/file to be restored recursively in dirs
+ markdir mark directory name to be restored (no files)
+ pwd print current working directory
+ unmark unmark dir/file to be restored recursively in dir
+ unmarkdir unmark directory name only no recursion
+ quit quit and do not do restore
+ ? print help
+\end{verbatim}
+\normalsize
+
+Par d\'efaut, aucun fichier n'est s\'electionn\'e pour restauration (sauf si vous
+avez ajout\'e {\bf all} \`a la ligne de commande). Si, \`a ce stade, vous voulez
+tout restaurer, vous devriez saisir {\bf mark *}, puis {\bf done}, Bacula
+\'ecrira alors les donn\'ees bootstrap dans un fichier et sollicitera votre
+approbation pour d\'emarrer la restauration.
+
+Si vous n'utilisez pas {\bf mark *}, vous commencez avec une s\'election vide.
+Vous pouvez simplement regarder et marquer ({\bf mark}) les fichiers et/ou
+r\'epertoires qui vous int\'eressent. Il est ais\'e de commettre une erreur dans ces
+op\'erations, et la gestion des erreurs dans Bacula n'est pas parfaite, aussi
+contr\^olez votre travail avec la commande {\bf ls} ou {\bf dir} pour voir
+quels fichiers ont \'et\'e s\'electionn\'es. Les fichiers s\'electionn\'es sont pr\'ec\'ed\'es
+d'une ast\'erisque.
+
+Pour contr\^oler ce qui est marqu\'e et ce qui ne l'est pas utilisez la commande
+{\bf count} qui affiche :
+
+\footnotesize
+\begin{verbatim}
+128401 total files. 128401 marked to be restored.
+
+\end{verbatim}
+\normalsize
+
+Chacune des commandes ci-dessus sera expliqu\'e plus en d\'etail dans la
+prochaine section. Poursuivons avec notre exemple, en validant la restauration de
+tous les fichiers. En saisissant {\bf done}, Bacula affiche :
+
+\footnotesize
+\begin{verbatim}
+Bootstrap records written to /home/kern/bacula/working/restore.bsr
+The restore job will require the following Volumes:
+
+ DLT-19Jul02
+ DLT-04Aug02
+128401 files selected to restore.
+Run Restore job
+JobName: kernsrestore
+Bootstrap: /home/kern/bacula/working/restore.bsr
+Where: /tmp/bacula-restores
+Replace: always
+FileSet: Kerns Files
+Client: Rufus
+Storage: SDT-10000
+JobId: *None*
+OK to run? (yes/mod/no):
+
+\end{verbatim}
+\normalsize
+
+Examinez chaque \'el\'ement attentivement pour vous assurer que tout est
+conforme \`a ce que vous souhaitez. En particulier, v\'erifiez la ligne {\bf where},
+qui vous indique dans quelle partie du syst\`eme de fichiers vos donn\'ees
+seront restaur\'ees, et quel client va les recevoir (par d\'efaut, les
+restaurations ont lieu sur le client d'origine). Ces param\`etres n'auront pas
+forc\'ement les bonnes valeurs, mais vous pouvez les modifier \`a l'aide
+de la commande {\bf mod} et en vous laissant guider par l'invite de la
+console.
+
+L'affichage ci-dessus suppose que vous ayez d\'efini une ressource Job de type
+{\bf restore} dans le fichier de configuration de votre Director. en
+principe, vous n'en n'aurez besoin que d'une, car, par nature, une
+restauration est une op\'eration essentiellement manuelle. A l'aide de la
+Console, vous pourrez modifier le job Restore pour faire ce que vous voulez
+qu'il fasse.
+
+Un exemple de ressource Job de type restore est donn\'e plus bas.
+
+Pour en revenir \`a notre exemple, en plus de v\'erifier le client, il est sage
+de v\'erifier que le p\'eriph\'erique de stockage choisi par Bacula est le bon.
+Bien que le FileSet soit pr\'esent\'e, il est en fait ignor\'e dans la restauration.
+Le processus de restauration choisit ses fichiers en lisant le fichier
+{\bf bootstrap}, et restaure tous les fichiers associ\'es au JobId consid\'er\'e
+si ce fichier n'est pas sp\'ecifi\'e.
+
+Enfin, avant de lancer la restauration, notez que le lieu par d\'efaut pour les
+fichiers restaur\'es n'est pas leur emplacement d'origine mais le r\'epertoire
+{\bf /tmp/bacula-restores}. Vous pouvez modifier cette valeur par d\'efaut dans
+le fichier de configuration du Director, ou avec l'option {\bf mod}. Si vous
+voulez restaurer les fichiers \`a leurs emplacements d'origine, modifiez l'option
+{\bf where} : sp\'ecifiez la racine ({\bf /} ou rien du tout).
+
+Si vous entrez maintenant {\bf yes}, Bacula lance la restauration. le Storage
+Daemon va d'abord requ\'erir le volume {\bf DLT-19Jul02}, puis le {\bf DLT-04Aug02}
+une fois qu'il aura extrait les fichiers requis du premier.
+
+\section{S\'electionner des fichiers par leurs noms}
+\index[general]{S\'electionner des fichiers par leurs noms}
+\index[general]{Noms de fichiers!S\'electionner des fichiers par leurs}
+\addcontentsline{toc}{section}{S\'electionner des fichiers par leurs noms}
+
+Si vous n'avez qu'un petit nombre de fichiers \`a restaurer dont vous connaissez
+les noms, vous pouvez, aux choix, placer ces noms dans un fichier qui sera
+lu par Bacula, ou saisir les noms un par un. Les noms de fichier doivent inclure
+le chemin absolu. Les caract\`eres jokers ne peuvent \^etre utilis\'es.
+
+Pour saisir la liste, choisissez l'option 7 dans le menu de la commande {\bf restore} :
+
+\footnotesize
+\begin{verbatim}
+To select the JobIds, you have the following choices:
+ 1: List last 20 Jobs run
+ 2: List Jobs where a given File is saved
+ 3: Enter list of comma separated JobIds to select
+ 4: Enter SQL list command
+ 5: Select the most recent backup for a client
+ 6: Select backup for a client before a specified time
+ 7: Enter a list of files to restore
+ 8: Enter a list of files to restore before a specified time
+ 9: Find the JobIds of the most recent backup for a client
+ 10: Find the JobIds for a backup for a client before a specified time
+ 11: Enter a list of directories to restore for found JobIds
+ 12: Cancel
+Select item: (1-12):
+\end{verbatim}
+\normalsize
+
+Vous \^etes alors invit\'e \`a pr\'eciser le client :
+
+\footnotesize
+\begin{verbatim}
+Defined Clients:
+ 1: Timmy
+ 2: Tibs
+ 3: Rufus
+Select the Client (1-3): 3
+\end{verbatim}
+\normalsize
+
+Si vous n'avez qu'un client, il est s\'electionn\'e automatiquement.
+Finalement, Bacula vous demande d'entrer un nom de fichier :
+
+\footnotesize
+\begin{verbatim}
+Enter filename:
+\end{verbatim}
+\normalsize
+
+Vous pouvez, \`a ce stade, saisir le chemin absolu et le nom du fichier :
+
+\footnotesize
+\begin{verbatim}
+Enter filename: /home/kern/bacula/k/Makefile.in
+Enter filename:
+\end{verbatim}
+\normalsize
+
+Si Bacula ne peut en trouver aucune copie, il affiche ce qui suit :
+
+\footnotesize
+\begin{verbatim}
+Enter filename: junk filename
+No database record found for: junk filename
+Enter filename:
+\end{verbatim}
+\normalsize
+
+Si vous souhaitez que Bacula r\'ecup\`ere la liste des fichiers \`a restaurer depuis
+un fichier, r\'edigez ce fichier et donnez lui un nom commen\c{c}ant par le signe
+moins (\lt{}) et saisissez-le ici. Lorsque vous avez entr\'e tous les noms de
+fichiers, validez une ligne vide. Bacula \'ecrit maintenant le fichier
+bootstrap, vous indique les cartouches qui seront utilis\'ees, et vous propose
+de valider la restauration :
+
+\footnotesize
+\begin{verbatim}
+Enter filename:
+Automatically selected Storage: DDS-4
+Bootstrap records written to /home/kern/bacula/working/restore.bsr
+The restore job will require the following Volumes:
+
+ test1
+1 file selected to restore.
+Run Restore job
+JobName: kernsrestore
+Bootstrap: /home/kern/bacula/working/restore.bsr
+Where: /tmp/bacula-restores
+Replace: always
+FileSet: Kerns Files
+Client: Rufus
+Storage: DDS-4
+When: 2003-09-11 10:20:53
+Priority: 10
+OK to run? (yes/mod/no):
+\end{verbatim}
+\normalsize
+
+Il est possible d'automatiser la s\'election des fichiers en pla\c{c}ant votre liste
+de fichiers dans, part exemple, {\bf /tmp/file-list}, puis en utilisant la
+commande suivante :
+
+\footnotesize
+\begin{verbatim}
+restore client=Rufus file=</tmp/file-list
+\end{verbatim}
+\normalsize
+
+Si, en modifiant les param\`etres du job restauration, vous constatez que Bacula
+vous demande d'entrer un num\'ero de job, c'est vous n'avez pour l'instant sp\'ecifi\'e
+ni num\'ero de job, ni fichier bootstrap. Entrez simplement z\'ero pour pouvoir
+continuer et s\'electionner une autre option \`a modifier.
+
+\label{CommandArguments}
+
+\section{Arguments de la ligne de commande}
+\index[general]{Arguments!ligne de commande}
+\index[general]{Arguments de la ligne de commande}
+\addcontentsline{toc}{section}{Arguments de la ligne de commande}
+
+Si tout ce qui pr\'ec\`ede vous a sembl\'e compliqu\'e, vous admettrez certainement
+que ce n'est vraiment pas le cas apr\`es quelques essais. Il est possible de
+faire tout ce qui vient d'\^etre vu en utilisant la ligne de commande, \`a
+l'exception de la s\'election du FileSet. Voici une telle ligne de commande :
+
+\footnotesize
+\begin{verbatim}
+restore client=Rufus select current all done yes
+\end{verbatim}
+\normalsize
+
+Le sp\'ecification {\bf client=Rufus} s\'electionne automatiquement le client Rufus,
+l'option {\bf current} pr\'ecise que vous voulez une restauration \`a l'\'etat le plus
+r\'ecent possible, et le {\bf yes} \'elude l'invite finale {\bf yes/mod/no} et
+ex\'ecute directement la restauration.
+
+Voici la liste des arguments de la ligne de commandes :
+
+\begin{itemize}
+\item {\bf all} -- s\'electionne tous les fichiers pour la restauration.
+\item {\bf select} -- utilise la s\'election via l'arborescence.
+\item {\bf done} -- permet de quitter le mode de s\'election dans l'arborescence.
+\item {\bf current} -- s\'electionne automatiquement le jeu de sauvegardes le plus
+ r\'ecent pour le client sp\'ecifi\'e.
+\item {\bf client=xxxx} -- S\'electionne le client sp\'ecifi\'e.
+\item {\bf jobid=nnn} -- Sp\'ecifie un JobId ou une liste de JobIds s\'epar\'es par des
+ virgules pour la restauration.
+\item {\bf before=YYYY-MM-DD HH:MM:SS} -- Sp\'ecifie une date et un horaire. Bacula
+ s\'electionne le plus r\'ecent des jeux de sauvegardes ant\'erieurs \`a la date sp\'ecifi\'ee.
+ Cette commande n'est pas tr\`es conviviale, en effet, vous devez sp\'ecifier la date
+ et l'heure en respectant exactement le mod\`ele.
+\item {\bf file=filename} -- Sp\'ecifie un nom de fichier \`a restaurer. Vous devez
+ sp\'ecifier le chemin absolu vers le fichier. Si vous pr\'efixez l'entr\'ee d'un signe moins
+ (\lt{}), Bacula consid\`ere que ce fichier existe et qu'il contient la liste des
+ fichiers \`a restaurer. Les sp\'ecifications multiples {\bf file=xxx} peuvent \^etre
+ utilis\'ees en ligne de commandes.
+\item {\bf jobid=nnn} -- Sp\'ecifie un JobId \`a restaurer.
+\item {\bf pool=pool-name} -- Sp\'ecifie un nom de pool \`a utiliser pour la s\'election des
+ volumes au niveau des options 5 et 6 (restauration \`a l'\'etat le plus r\'ecent et
+ restauration \`a l'\'etat le plus r\'ecent avant une date donn\'ee). Ceci vous permet d'avoir
+ plusieurs pools, dont un \'eventuellement hors site et l'autre sur place disponible pour
+ les restaurations.
+\item {\bf yes} -- Ex\'ecute automatiquement la restauration sans passer par l'invite finale
+ de validation/modification surtout utile pour l'utilisation dans des scripts).
+ \end{itemize}
+
+\section{Restaurer les attributs de fichiers}
+\index[general]{Attributs de fichiers!Restaurer}
+\index[general]{Restaurer les attributs de fichiers}
+\addcontentsline{toc}{section}{Restaurer les attributs de fichiers}
+
+Selon la fa\c{c}on dont vous restaurez, vous pouvez ou non restaurer les
+attributs de fichiers \`a leur \'etat initial. Voici quelques uns des
+probl\`emes auxquels vous pouvez \^etre confront\'es, et, pour les
+restaurations sur la machine d'origine, comment les \'eviter.
+
+\begin{itemize}
+\item Vous avez sauvegard\'e des fichiers sur une machine, et les restaurez
+ sur une autre qui a peut-\^etre un autre syst\`eme d'exploitation ou des
+ utilisateurs/groupes diff\'erents. Bacula fait du mieux qu'il peut dans ces
+ situations. Notez qu'utilisateurs et groupes sont sauvegard\'es au format
+ num\'erique, et qu'ils peuvent donc se r\'ef\'erer \`a d'autres utilisateurs et
+ groupes sur un autre syst\`eme.
+\item Vous restaurez dans un r\'epertoire existant sur lequel portent des
+ restrictions du droit de cr\'eation. Bacula tente alors de tout r\'etablir,
+ mais sans parcourir la cha\^ine compl\`ete des r\'epertoires ni les modifier
+ durant la restauration. En fait, ce que pourra faire Bacula pour r\'etablir
+ les permissions correctement d\'epend pour beaucoup de votre syst\`eme
+ d'exploitation.
+\item Vous faites une restauration recursive d'une arborescence. Dans ce cas,
+ de figure, Bacula restaure un fichier avant de restaurer l'entr\'ee de son
+ r\'epertoire parent. Dans le processus de restauration du fichier, Bacula
+ cr\'ee le r\'epertoire parent avec des permissions ouvertes et le m\^eme
+ propri\'etaire que le fichier restaur\'e. Alors, lorsque Bacula tente de restaurer
+ le r\'epertoire en lui m\^eme, il se rend compte qu'il existe d\'ej\`a (situation
+ similaire \`a la pr\'ec\'edente). Si vous avez fix\'e l'option "Replace" \`a "never"
+ lors du lancement du job, alors Bacula ne modifie pas les permissions et
+ propri\'et\'es du r\'epertoire pour s'accorder \`a ce qu'elles \'etaient lors de la
+ sauvegarde. Vous devriez aussi noter une divergence entre le nombre de fichiers
+ effectivement restaur\'es et le nombre de fichiers attendus. Si vous voulez
+ \'eviter ces inconv\'enients, fixez l'option "Replace" \`a "always", ainsi
+ Bacula sera en mesure de modifier les propri\'etaire et permissions des
+ r\'epertoires pour les ramener \`a leurs \'etats d'origine. Le nombre de
+ fichiers restaur\'es devrait cette fois \^etre identique \`a celui attendu.
+
+\item Vous avez s\'electionn\'e un ou plusieurs fichiers d'un r\'epertoire sans
+ s\'electionner le r\'epertoire lui-m\^eme. Dans ce cas, si le r\'epertoire
+ n'existe pas d\'ej\`a, Bacula le cr\'ee avec des attributs par d\'efaut qui ne
+ seront peut-\^etre pas ceux d'origine. Si vous ne voulez pas s\'electionner
+ un r\'epertoire et tout son contenu, mais seulement quelques objets dans
+ ce r\'epertoire en les marquant individuellement, vous devriez utiliser
+ la commande {\bf markdir} pour s\'electionner un r\'epertoire de plus haut
+ niveau (un \`a la fois) si vous voulez que les entr\'ees de r\'epertoires
+ soient restaur\'ees correctement.
+\end{itemize}
+
+\label{Windows}
+
+\section{Restaurer sur Windows}
+\index[general]{Restaurer sur Windows}
+\index[general]{Windows!Restaurer sur}
+\addcontentsline{toc}{section}{Restaurer sur Windows}
+Sur les syst\`emes WinNT/2K/XP, Bacula restaure les fichiers avec les droits
+et permissions d'origine comme on s'y attend. Ceci est aussi v\'erifi\'e si vous
+restaurez ces fichiers vers un autre r\'epertoire (avec l'option "where") que celui
+d'origine. Cependant, si le nouveau r\'epertoire n'existe pas, le File Daemon
+tente de le cr\'eer. Dans certains cas, il n'y parvient pas. S'il y parvient, le
+r\'epertoire cr\'e\'e appartient \`a l'utilisateur qui ex\'ecute le File Daemon, c'est-\`a-dire
+SYSTEM. Dans ce cas, il se peut que vous ayez des difficult\'es pour acc\'eder aux
+fichiers fraichement restaur\'es.
+
+Pour \'eviter ce probl\`eme, vous devriez cr\'eer le r\'epertoire alternatif avant
+de lancer la restauration. Bacula ne changera pas les attributs de ce r\'epertoire,
+du moment que ce n'est pas l'un des r\'epertoires \`a restaurer.
+
+Le r\'epertoire de restauration par d\'efaut est {\bf /tmp/bacula-restores/}, qui devient
+{\bf /tmp/bacula-restores/e/} si vous restaurez depuis le disque {\bf E}.
+Aussi, assurez-vous que ce r\'epertoire existe avant de lancer la restauration, ou
+utilisez l'option {\bf mod} pour s\'electionner un r\'epertoire destination existant.
+
+Certains utilisateurs ont signal\'e des probl\`emes en restaurant des fichiers
+qui participent \`a Active Directory. Ils ont aussi rapport\'e que le changement de
+l'Id utilisateur sous lequel est ex\'ecut\'e Bacula de SYSTEM en un Id d'administrateur
+du domaine r\'esout le probl\`eme.
+
+\section{Une restauration peut prendre du temps}
+\index[general]{temps!Restauration}
+\index[general]{Une restauration peut prendre du temps}
+\addcontentsline{toc}{section}{Une restauration peut prendre du temps}
+
+Restaurer des fichiers est g\'en\'eralement {\bf beaucoup} plus lent que de les
+sauvegarder, ce pour plusieurs raisons. La premi\`ere est que lors d'une sauvegarde,
+la cartouche est normalement d\'ej\`a positionn\'ee, Bacula n'a qu'\`a \'ecrire dessus.
+D'autre part, les restaurations \'etant si rares (par rapport aux sauvegardes),
+Bacula ne garde dans le catalogue que l'emplacement sur la cartouche du premier
+fichier et du premier bloc pour chaque job, et non l'emplacement de chaque fichier,
+ce qui occuperait trop de place dans le catalogue.
+
+Bacula se place d'abord sur la bonne marque de fichier sur la cartouche, puis
+sur le bloc correct, puis lit s\'equentiellement chaque enregistrement jusqu'\`a
+trouver ceux correspondant aux fichier que vous voulez restaurer. Une fois ces
+fichiers restaur\'es, Bacula cesse de lire la cartouche.
+
+Enfin, au lieu de simplement lire un fichier comme pour une sauvegarde, Bacula
+doit, lors d'une restauration, cr\'eer les fichiers, tandis que le syst\`eme
+d'exploitation doit, de son cot\'e, allouer de l'espace disque pour ces fichiers
+restaur\'es.
+
+Pour toutes ces raisons, le processus de restauration est g\'en\'eralement beaucoup
+plus lent que celui de sauvegarde (une restauration peut prendre trois fois
+plus de temps que la sauvegarde).
+
+\section{Probl\`emes lors de la restauration de fichiers}
+\index[general]{Fichiers!Probl\`emes de restauration}
+\index[general]{Probl\`emes lors de la restauration de fichiers}
+\addcontentsline{toc}{section}{Probl\`emes lors de la restauration de fichiers}
+
+Les probl\`emes que les utilisateurs rencontrent le plus souvent lors des restaurations
+sont des messages d'erreurs tels que :
+
+\footnotesize
+\begin{verbatim}
+04-Jan 00:33 z217-sd: RestoreFiles.2005-01-04_00.31.04 Error:
+block.c:868 Volume data error at 20:0! Short block of 512 bytes on
+device /dev/tape discarded.
+\end{verbatim}
+\normalsize
+
+ou
+
+\footnotesize
+\begin{verbatim}
+04-Jan 00:33 z217-sd: RestoreFiles.2005-01-04_00.31.04 Error:
+block.c:264 Volume data error at 20:0! Wanted ID: "BB02", got ".".
+Buffer discarded.
+\end{verbatim}
+\normalsize
+
+Ces deux types de messages indiquent que vous avez probablement utilis\'e votre
+lecteur en mode "blocs de taille fixe" plut\^ot qu'en mode "blocs de taille
+variable". Le mode "blocs de taille fixe" fonctionne avec tout programme
+qui lit les cartouches s\'equentiellement tel que {\bf tar}, cependant Bacula
+repositionne la bande suivant les blocs lors des restaurations, ce qui lui
+permet d'am\'eliorer les performances en restauration de plusieurs ordres
+de grandeur lorsqu'il s'agit de restaurer quelques fichiers isol\'es. Il existe
+plusieurs moyens pour vous tirer de ce mauvais pas.
+
+Tentez-les l'un apr\`es l'autre, en r\'etablissant votre ressource Device apr\`es
+chacun des tests :
+
+\begin{enumerate}
+\item D\'esactivez le positionnement par blocs ("Block Positioning = no"
+ dans la ressource Device) et essayez de restaurer. Cette directive est
+ r\'ecente et n'est pas encore bien test\'ee.
+\item R\'eglez \`a 512 les tailles minimum et maximum de blocs
+ ("Minimum Block Size = 512" et "Maximum Block Size = 512") et essayez de
+ restaurer. Si vous \^etes en mesure de d\'eterminer la taille de blocs
+ utilis\'ee par votre lecteur pour \'ecrire les donn\'ees, vous devriez essayer
+ cette valeur si la restauration a \'echou\'e avec 512.
+\item Editez le fichier restore.bsr \`a l'invite yes/mod/no de la
+ commande Run xxx avant de valider la restauration, et supprimez tous les
+ enregistrements VolBlock. Ce sont eux qui causent les repositionnements de
+ la bande et les probl\`emes qui s'ensuivent si vous utilisez des blocs de taille
+ fixe sur votre lecteur. Les commandes VolFile provoquent aussi le
+ repositionnement, mais celui-ci fonctionne ind\'ependamment de la taille des blocs.
+\item Utilisez bextract pour extraire vos fichiers -- ce programme lit les
+ volumes s\'equentiellement si vous utilisez la fonctionnalit\'e des listes
+ d'inclusions, ou si vous utilisez un fichier .bsr (priv\'e des enregistrements
+ VolBlock) \`a l'invite "yes/mod/no" qui pr\'ec\`ede le lancement de la
+ restauration.
+\end{enumerate}
+
+\section{Erreurs de restaurations}
+\index[general]{Erreurs!Restauration}
+\index[general]{Erreurs de restauration}
+\addcontentsline{toc}{section}{Erreurs de restauration}
+
+Il existe de multiples causes qui peuvent \^etre \`a l'origine de messages d'alerte ou d'erreurs
+lors des restaurations. Les plus courantes sont les suivantes :
+
+\begin{description}
+
+\item [file count mismatch]
+ Cette erreur peut se produire dans les cas suivants :
+ \begin{itemize}
+ \item Vous avez enjoint Bacula \`a ne pas \'ecraser les fichiers
+ existants ou plus r\'ecents.
+ \item Bacula a commis une erreur dans le d\'ecompte des fichiers/r\'epertoires.
+ Ceci est un probl\`eme inh\'erent \`a la complexit\'e des r\'epertoires, liens
+ symboliques/durs, etc. Contr\^olez simplement que tous les fichiers voulus ont \'et\'e
+ effectivement restaur\'es.
+ \end{itemize}
+\item [file size error]
+ Lorsque Bacula restaure un fichier, il v\'erifie que la taille du fichier
+ restaur\'e est conforme aux donn\'ees d'\'etat enregistr\'ees au d\'ebut de la sauvegarde
+ du fichier. En cas de divergence, Bacula affiche un message d'erreur. Cet
+ divergence survient presque toujours \`a cause d'une \'ecriture du fichier
+ au cours de sa sauvegarde. Dans ce cas, la taille du fichier restaur\'e
+ est plus grande que la taille enregistr\'ee dans les donn\'ees d'\'etat. Cette
+ erreur se produit souvent avec les fichiers de journaux.
+
+ Si en revanche la taille du fichier restaur\'ee est plus petite, vous devriez
+ pousser vos investigations du cot\'e d'un \'eventuel probl\`eme de bande et
+ contr\^oler les rapports de Bacula ainsi que votre syst\`eme de journalisation.
+\end{description}
+
+\section{Un exemple de ressource Restore Job}
+\index[general]{Exemple ressource Restore Job }
+\index[general]{Ressource!Exemple Restore Job }
+\addcontentsline{toc}{section}{Exemple ressource Restore Job}
+
+\footnotesize
+\begin{verbatim}
+Job {
+ Name = "RestoreFiles"
+ Type = Restore
+ Client = Any-client
+ FileSet = "Any-FileSet"
+ Storage = Any-storage
+ Where = /tmp/bacula-restores
+ Messages = Standard
+ Pool = Default
+}
+\end{verbatim}
+\normalsize
+Si la directive {\bf Where} n'est pas pr\'ecis\'ee, les fichiers sont restaur\'es \`a
+leur emplacement d'origine.
+\label{Selection}
+
+\section{Les commande de s\'election de fichiers}
+\index[general]{Commandes!s\'election fichiers}
+\index[general]{Fichiers S\'election Commandes }
+\addcontentsline{toc}{section}{Commandes de s\'election de fichiers}
+
+Une fois que vous avez s\'electionn\'e les jobs \`a restaurer et apr\`es que Bacula a cr\'e\'e
+l'arborescence des r\'epertoires en m\'emoire, vous entrez dans le mode de s\'election
+de fichiers, ce qui est rappel\'e par l'invite ({\bf \$}). Dans ce mode, vous
+pouvez utiliser les commandes \'enum\'er\'ees plus haut. Vous pouvez naviguer dans
+l'arborescence avec la commande {\bf cd} tout comme vous le feriez dans
+un syst\`eme de fichiers. Lorsque vous \^etes dans un r\'epertoire, vous pouvez en
+s\'electionner des fichiers ou r\'epertoires pour restauration. Par d\'efaut, aucun
+fichier n'est s\'electionn\'e. Si vous souhaitez au contraire partir d'une situation
+o\`u tous les fichiers sont s\'electionn\'es, saisissez simplement : {\bf cd /} et
+{\bf mark *}. Sinon, s\'electionnez vos fichiers avec la commande {\bf mark}. Les
+commandes disponibles sont :
+
+\begin{description}
+
+\item [cd]
+ La commande {\bf cd} change le r\'epertoire courant en l'argument sp\'ecifi\'e. les
+ caract\`eres joker ne sont pas admis.
+
+ Notez que sur les syst\`emes Windows, les diff\'erents disques (c:, d:, ...) sont
+ trait\'es comme des r\'epertoires dans l'arborescence. Une cons\'equence est que vous
+ devez saisir {\bf cd c:} ou \'eventuellement {\bf cd C:} pour descendre dans le
+ premier r\'epertoire.
+
+\item [dir]
+ \index[dir]{dir }
+ La commande {\bf dir} est similaire \`a la commande {\bf ls}, mais produit un
+ affichage au format long (tous les d\'etails). Cette commande peut \^etre un peu
+ plus lente que la commande {\bf ls} car elle n\'ecessite l'acc\`es au catalogue
+ pour produire les informations d\'etaill\'ees concernant chaque fichier.
+
+\item [estimate]
+ \index[dir]{estimate }
+ La commande {\bf estimate} affiche un aper\c{c}u du nombre total de fichiers dans
+ l'arbre, de ceux s\'electionn\'es pour restauration, et une estimation du nombre
+ d'octets \`a restaurer. Ceci peut-\^etre tr\`es utile si la machine o\`u vous comptez
+ restaurer est limit\'ee en espace disque.
+
+\item [find]
+ \index[dir]{find }
+ La commande {\bf find} prend un ou plusieurs arguments et affiche tous les fichiers
+ de l'arbre qui satisfont ces arguments. Les arguments peuvent comporter
+ des caract\`eres joker. Cette commande est similaire \`a la commande Unix
+ {\bf find / -name arg}.
+
+\item [ls]
+ La commande {\bf ls} produit la liste des fichiers du r\'epertoire courant, comme
+ le ferait la commande Unix {\bf ls}. Vous pouvez sp\'ecifier un argument
+ comportant des caract\`eres joker, auquel cas seuls les fichiers concern\'es seront
+ list\'es. Le nom de tout fichier s\'electionn\'e pour restauration est pr\'ec\'ed\'e
+ d'un ast\'erisque ({\bf *}). Les noms de r\'epertoires sont suivis d'une barre oblique
+ avant (slash {\bf /}) pour les distinguer des noms de fichiers.
+
+\item [lsmark]
+ \index[fd]{lsmark}
+ La commande {\bf lsmark} est similaire \`a la commande {\bf ls}, mais de port\'ee
+ restreinte aux fichiers s\'electionn\'es pour restauration. D'autre part, contrairement
+ \`a {\bf lsmark}, elle descend r\'ecursivement dans les sous-r\'epertoire du
+ r\'epertoire s\'electionn\'e.
+
+\item [mark]
+ \index[dir]{mark }
+ La commande {\bf mark} vous permet de s\'electionner vos fichiers pour restauration.
+ Elle prend pour unique argument le nom du fichier ou r\'epertoire (du r\'epertoire
+ courant) \`a restaurer. L'argument peut comporter des caract\`eres joker, auquel cas
+ tous les fichiers qui co\"incident avec le motif sp\'ecifi\'e sont s\'electionn\'es pour
+ restauration. Si un r\'epertoire du r\'epertoire courant co\"incide avec l'argument,
+ alors ce r\'epertoire et tous les fichiers qu'il contient sont r\'ecursivement
+ s\'electionn\'es pour restauration. Chacun des fichiers s\'electionn\'e est identifiable par
+ l'ast\'erisque qui pr\'ec\`ede son nom dans la liste produite par les commandes {\bf ls}
+ ou {\bf dir}. Notez que fournir un chemin absolu en argument de la commande
+ {\bf mark} ne produit pas le r\'esultat qu'on pourrait en attendre pour s\'electionner
+ un fichier ou un r\'epertoire du r\'epertoire courant. La commande {\bf mark} travaille
+ sur le r\'epertoire courant et sur les r\'epertoires enfants, mais ne remonte pas vers les
+ r\'epertoires de plus haut niveau.
+
+ Apr\`es ex\'ecution, la commande {\bf mark} affiche un bref r\'esum\'e :
+
+\footnotesize
+\begin{verbatim}
+ No files marked.
+
+\end{verbatim}
+\normalsize
+
+ si aucun fichier n'a \'et\'e s\'electionn\'e, ou :
+
+\footnotesize
+\begin{verbatim}
+ nn files marked.
+
+\end{verbatim}
+\normalsize
+
+ si certains fichiers ont \'et\'e s\'electionn\'es.
+
+\item [unmark]
+ \index[dir]{unmark }
+ la commande {\bf unmark} fonctionne exactement comme la commande {\bf mark}, mais
+ sert \`a d\'es\'electionner les fichiers sp\'ecifi\'es pour qu'ils ne soient pas
+ restaur\'es. Notez que la commande {\bf unmark} travaille sur le r\'epertoire courant
+ et sur les r\'epertoires enfants, mais ne remonte pas vers les r\'epertoires de plus
+ haut niveau. Si vous souhaitez d\'es\'electionner l'ensembles des fichiers, placez-vous
+ \`a la racine ({\bf cd /}) avant de saisir {\bf unmark *}.
+
+\item [pwd]
+ \index[dir]{pwd }
+ La commande {\bf pwd} affiche le r\'epertoire courant. Elle ne prend aucun argument.
+
+\item [count]
+ \index[dir]{count }
+ La commande {\bf count} affiche le nombre total de fichiers dans l'arborescence des
+ fichiers et le nombre de fichiers s\'electionn\'es pour restauration.
+
+\item [done]
+ \index[dir]{done }
+ Cette commande permet de quitter le mode de s\'election de fichiers.
+
+\item [exit]
+ \index[fd]{exit }
+ Cette commande permet de quitter le mode de s\'election de fichiers (identique \`a {\bf done}).
+
+\item [quit]
+ \index[fd]{quit }
+ Cette commande permet de quitter le mode de s\'election de fichiers sans ex\'ecuter la restauration.
+
+\item [help]
+ \index[fd]{help }
+ Cette commande affiche un aper\c{c}u des commandes disponibles.
+
+\item [?]
+ Cette commande est identique \`a {\bf help}.
+\end{description}
+
+\label{database_restore}
+\section{Restaurer lorsque tout va de travers}
+\index[general]{Restaurer lorsque tout va de travers}
+\index[general]{Restaurer le catalogue}
+\index[general]{Catalogue!Restaurer}
+\addcontentsline{toc}{section}{Restaurer lorsque tout va de travers}
+
+Je pr\'esente ici quelques-uns des probl\`emes qui peuvent survenir et
+rendre les op\'erations de restaurations plus difficiles, et quelques id\'ees
+pour se sortir de ces situations d\'elicates. Des informations plus
+sp\'ecifiques aux restaurations compl\`etes des \ilink{clients}{restore_client}
+ou du \ilink{serveur}{restore_server} sont fournies dans le chapitre
+\ilink{Disaster recovery avec Bacula}{_ChapterRescue}.
+
+\begin{description}
+\item[Probl\`eme]
+ Mon catalogue est corrompu.
+\item[Solution]
+ Pour SQLite, utilisez la commande {\bf vacuum} pour tenter de r\'ecup\'erer
+ le catalogue. Pour MySQL ou PostgreSQL, consultez la documentation
+ officielle de la base de donn\'ees. Des outils sp\'ecifiques vous permettront
+ de contr\^oler et r\'eparer votre catalogue.
+
+ Dans le cas contraire, vous devrez restaurer le catalogue.
+\item[Probl\`eme]
+ Comment restaurer mon catalogue ?
+\item[Solution]
+ Si vous avez sauvegard\'e votre catalogue quotidiennement (comme il se doit...)
+ et avez fait un fichier {\it bootstrap}, vous pouvez imm\'ediatement
+ recharger votre base de donn\'ees. Faites une copie de votre base courante,
+ puis r\'einitialisez-la avec les scripts suivants :
+\begin{verbatim}
+ ./drop_bacula_tables
+ ./make_bacula_tables
+\end{verbatim}
+ Apr\`es r\'einitialisation de la base, vous devriez pouvoir d\'emarrer Bacula.
+ Si vous tentez maintenat d'utiliser la commande {\bf run}, \c{c}a ne
+ marchera pas puisque le catalogue est vierge. Cependant, vous pouvez
+ ex\'ecuter manuellement un job et sp\'ecifier votre fichier bootstrap.
+ Pour cela, utilisez la commande {\bf run} et choisissez un job de type
+ {\bf retore}. Si vous utilisez le bacula-dir.conf par d\'efaut, il s'agit
+ de {\bf RestoreFiles}. Vous devriez obtenir quelque chose comme :
+
+\footnotesize
+\begin{verbatim}
+Run Restore job
+JobName: RestoreFiles
+Bootstrap: /home/kern/bacula/working/restore.bsr
+Where: /tmp/bacula-restores
+Replace: always
+FileSet: Full Set
+Client: rufus-fd
+Storage: File
+When: 2005-07-10 17:33:40
+Catalog: MyCatalog
+Priority: 10
+OK to run? (yes/mod/no):
+\end{verbatim}
+\normalsize
+ Plusieurs param\`etres seront diff\'erents dans votre cas. Vous aller modifier
+ (commande {\bf mod}) le param\`etre {\bf Bootstrap} pour qu'il pointe
+ vers votre fichier bootstrap, et vous assurer que les autres param\`etres
+ sont corrects. Notez que le FileSet est ignor\'e lorque vous utilisez un
+ fichier bootstrap. Une fois que vous avez fix\'e tous les bons param\`etres,
+ ex\'evutez le job, vous devriez r\'ecup\'erer la sauvegarde de votre catalogue.
+ Il vous reste alors \`a r\'eg\'en\'erer votre base de donn\'ees \`a partir du
+ fichier de sauvegarde ASCII.
+
+\item[Solution]
+ Si vous avez sauvegard\'e votre catalogue mais n'avez pas fait de fichier
+ bootstrap, la reconstruction du catalogue sera un peu plus difficile.
+ Il vous faudra probablement utiliser {\bf bextract} pour extraire
+ la sauvegarde du catalogue. D'abord vous devez la localiser en
+ consultant le rapport de la derni\`ere sauvegarde du catalogue. Il comporte
+ des informations qui vous seront pr\'ecieuses pour le restaurer rapidement.
+ Par exemple, dans le rapport ci-dessous, les \'elements critiques sont
+ {\it Volume name(s)}, {\it the Volume Session Id} et {\it Volume Session Time}.
+ Si vous les connaissez, vous pouvez restaurer ais\'ement votre catalogue.
+\footnotesize
+\begin{verbatim}
+
+22-Apr 10:22 HeadMan: Start Backup JobId 7510,
+Job=CatalogBackup.2005-04-22_01.10.0
+22-Apr 10:23 HeadMan: Bacula 1.37.14 (21Apr05): 22-Apr-2005 10:23:06
+ JobId: 7510
+ Job: CatalogBackup.2005-04-22_01.10.00
+ Backup Level: Full
+ Client: Polymatou
+ FileSet: "CatalogFile" 2003-04-10 01:24:01
+ Pool: "Default"
+ Storage: "DLTDrive"
+ Start time: 22-Apr-2005 10:21:00
+ End time: 22-Apr-2005 10:23:06
+ FD Files Written: 1
+ SD Files Written: 1
+ FD Bytes Written: 210,739,395
+ SD Bytes Written: 210,739,521
+ Rate: 1672.5 KB/s
+ Software Compression: None
+ Volume name(s): DLT-22Apr05
+ Volume Session Id: 11
+ Volume Session Time: 1114075126
+ Last Volume Bytes: 1,428,240,465
+ Non-fatal FD errors: 0
+ SD Errors: 0
+ FD termination status: OK
+ SD termination status: OK
+ Termination: Backup OK
+
+\end{verbatim}
+\normalsize
+ Avec ces informations, vous pouvez cr\'eer manuellement un fichier
+ bootstrap et embrayer sur les instructions donn\'ees plus haut pour
+ restaurer le catalogue. Un fichier bootstrap reconstruit pour le job
+ ci-dessus ressemblerait \`a ceci :
+
+\footnotesize
+\begin{verbatim}
+Volume="DLT-22Apr05"
+VolSessionId=11
+VolSessionTime=1114075126
+FileIndex=1-1
+\end{verbatim}
+\normalsize
+
+ o\`u les valeurs {\it Volume name}, {\it Volume Session Id} , et {\it Volume Session Time}
+ conformes \`a celles du rapport de job ont \'et\'e introduites. Notez aussi
+ le {\it FileIndex} de valeur 1, ce sera toujours le cas pourvu qu'un seul fichier
+ ait \'et\'e sauvegard\'e par le job.
+
+ L'inconv\'enient de ce fichier bootstrap par rapport \`a celui cr\'e\'e automatiquement
+ lorsque vous le sp\'ecifiez est qu'il ne comporte aucune sp\'ecification {\it File}
+ ou {\it Block}, aussi Bacula doit examiner toutes les donn\'ees du volume pour
+ trouver le fichier requis. Un fichier bootstrap compl\`etement renseign\'e ressemblerait
+ \`a ceci :
+
+\footnotesize
+\begin{verbatim}
+Volume="DLT-22Apr05"
+VolSessionId=11
+VolSessionTime=1114075126
+VolFile=118-118
+VolBlock=0-4053
+FileIndex=1-1
+\end{verbatim}
+\normalsize
+
+\item [Probl\`eme]
+ J'essaye de restaurer depuis la derni\`ere sauvegarde compl\`ete en
+ s\'electionnant le choix 3 dans le menu de restauration, puis le
+ JobId \`a restaurer. Bacula affiche alors :
+
+\footnotesize
+\begin{verbatim}
+ 1 Job 0 Files
+\end{verbatim}
+\normalsize
+ et ne restaure rien.
+\item[Solution]
+ Les enregistrements de fichiers ont tr\`es probablement \'et\'e \'elagu\'es du catalogue
+ soit par expiration de leur p\'eriode de r\'etention (File Retention), soit par purge
+ explicite du job. La commande {\it llist jobid=nn} permet d'obtenir toutes les
+ informations importantes sur ce job :
+\footnotesize
+\begin{verbatim}
+llist jobid=120
+ JobId: 120
+ Job: save.2005-12-05_18.27.33
+ Job.Name: save
+ PurgedFiles: 0
+ Type: B
+ Level: F
+ Job.ClientId: 1
+ Client.Name: Rufus
+ JobStatus: T
+ SchedTime: 2005-12-05 18:27:32
+ StartTime: 2005-12-05 18:27:35
+ EndTime: 2005-12-05 18:27:37
+ JobTDate: 1133803657
+ VolSessionId: 1
+ VolSessionTime: 1133803624
+ JobFiles: 236
+ JobErrors: 0
+ JobMissingFiles: 0
+ Job.PoolId: 4
+ Pool.Name: Full
+ Job.FileSetId: 1
+ FileSet.FileSet: BackupSet
+\end{verbatim}
+\normalsize
+ Vous pouvez alors d\'eterminer le(s) volume(s) avec :
+\footnotesize
+\begin{verbatim}
+sql
+select VolumeName from JobMedia,Media where JobId=1 and JobMedia.MediaId=Media.MediaId;
+\end{verbatim}
+\normalsize
+ Finalement, vous pouvez cr\'eer un fichier bootstrap iavec ces informations
+ comme d\'ecrit plus haut.
+
+ A partir de la version 1.38.0, lorsque vous entrez un jobId apr\`es avoir
+ fait le choix 3, Bacula v ous demande si vous voulez restaurer tous les
+ fichiers du job, collecte pour vous les informations requises et \'ecrit le
+ fichier bootstrap.
+
+\item [Probl\`eme]
+ Vous n'avez ni fichier bootstrap, ni rapport de job pour votre sauvegarde
+ de catalogue, mais vous avez une sauvegarde et vous savez sur quel volume.
+
+\item [Solution]
+ Utilisez {\bf bls} pour d\'eterminer o\`u se trouve le fichier requis sur la bande.
+ Par exemple :
+
+\footnotesize
+\begin{verbatim}
+./bls -j -V DLT-22Apr05 /dev/nst0
+\end{verbatim}
+\normalsize
+ pourrait produire ceci :
+\footnotesize
+\begin{verbatim}
+bls: butil.c:258 Using device: "/dev/nst0" for reading.
+21-Jul 18:34 bls: Ready to read from volume "DLT-22Apr05" on device "DLTDrive"
+(/dev/nst0).
+Volume Record: File:blk=0:0 SessId=11 SessTime=1114075126 JobId=0 DataLen=164
+...
+Begin Job Session Record: File:blk=118:0 SessId=11 SessTime=1114075126
+JobId=7510
+ Job=CatalogBackup.2005-04-22_01.10.0 Date=22-Apr-2005 10:21:00 Level=F Type=B
+End Job Session Record: File:blk=118:4053 SessId=11 SessTime=1114075126
+JobId=7510
+ Date=22-Apr-2005 10:23:06 Level=F Type=B Files=1 Bytes=210,739,395 Errors=0
+Status=T
+...
+21-Jul 18:34 bls: End of Volume at file 201 on device "DLTDrive" (/dev/nst0),
+Volume "DLT-22Apr05"
+21-Jul 18:34 bls: End of all volumes.
+\end{verbatim}
+\normalsize
+ Bien sur, il y aura de nombreuses autres informations affich\'ees, nous n'avons
+ reproduit ici que les essentielles. D'apr\`es les informations sur le d\'ebut
+ ({\it Begin job Session Record} et sur la fin {\it End Job Session Record} du
+ job, vous pouvez \'ecrire un fichier bootstrap comme indiqu\'e plus haut.
+
+\item[Probl\`eme]
+ Comment puis-je d\'eterminer o\`u un fichier est stock\'e ?
+\item[Solution]
+ En principe, ce n'est pas n\'ecessaire. La commande {\bf restore} permet de
+ restaurer la version de la sauvegarde la plus r\'ecente (option 5 du menu),
+ ou une version sauvegard\'ee avant une date donn\'ee (option 8 du menu). Si vous
+ connaissez le JobId du job qui l'a sauvegard\'e, vous pouvez utiliser l'option 3
+ pour entrer ce JobId.
+
+ Pour rechercher le JobId d'une sauvegarde d'un fichier donn\'e, choisissez
+ l'option 2.
+
+ Vous pouvez aussi utiliser la commande {\bf query} pour trouver l'information :
+
+\footnotesize
+\begin{verbatim}
+*query
+Available queries:
+ 1: List Job totals:
+ 2: List up to 20 places where a File is saved regardless of the directory:
+ 3: List where the most recent copies of a file are saved:
+ 4: List last 20 Full Backups for a Client:
+ 5: List all backups for a Client after a specified time
+ 6: List all backups for a Client
+ 7: List Volume Attributes for a selected Volume:
+ 8: List Volumes used by selected JobId:
+ 9: List Volumes to Restore All Files:
+ 10: List Pool Attributes for a selected Pool:
+ 11: List total files/bytes by Job:
+ 12: List total files/bytes by Volume:
+ 13: List Files for a selected JobId:
+ 14: List Jobs stored in a selected MediaId:
+ 15: List Jobs stored for a given Volume name:
+Choose a query (1-15):
+\end{verbatim}
+\normalsize
+
+
+\end{description}
--- /dev/null
+/*
+ * html2latex
+ */
+
+available {
+ sun4_sunos.4
+ sun4_solaris.2
+ rs_aix.3
+ rs_aix.4
+ sgi_irix
+}
+
+description {
+ From Jeffrey Schaefer, Geometry Center. Translates HTML document to LaTeX
+}
+
+install {
+ bin/html2latex /afs/rpi.edu/dept/acs/rpinfo/filters/GChtml2latex/html2latex
+ bin/html2latex.tag /afs/rpi.edu/dept/acs/rpinfo/filters/GChtml2latex/html2latex.tag
+ bin/html2latex-local.tag /afs/rpi.edu/dept/acs/rpinfo/filters/GChtml2latex/html2latex-local.tag
+ bin/webtex2latex.tag /afs/rpi.edu/dept/acs/rpinfo/filters/GChtml2latex/webtex2latex.tag
+ man/man1/html2latex.1 /afs/rpi.edu/dept/acs/rpinfo/filters/GChtml2latex/html2latex.1
+}
--- /dev/null
+%%
+%%
+
+\chapter{Data Spooling}
+\label{SpoolingChapter}
+\index[general]{Data Spooling }
+\index[general]{Spooling!Data }
+
+Bacula allows you to specify that you want the Storage daemon to initially
+write your data to disk and then subsequently to tape. This serves several
+important purposes.
+
+\begin{itemize}
+\item It takes a long time for data to come in from the File daemon during
+ an Incremental backup. If it is directly written to tape, the tape will
+ start and stop or shoe-shine as it is often called causing tape wear.
+ By first writing the data to disk, then writing it to tape, the tape can
+ be kept in continual motion.
+\item While the spooled data is being written to the tape, the despooling
+ process has exclusive use of the tape. This means that you can spool
+ multiple simultaneous jobs to disk, then have them very efficiently
+ despooled one at a time without having the data blocks from several jobs
+ intermingled, thus substantially improving the time needed to restore
+ files. While despooling, all jobs spooling continue running.
+\item Writing to a tape can be slow. By first spooling your data to disk,
+ you can often reduce the time the File daemon is running on a system,
+ thus reducing downtime, and/or interference with users. Of course, if
+ your spool device is not large enough to hold all the data from your
+ File daemon, you may actually slow down the overall backup.
+\end{itemize}
+
+Data spooling is exactly that "spooling". It is not a way to first write a
+"backup" to a disk file and then to a tape. When the backup has only been
+spooled to disk, it is not complete yet and cannot be restored until it is
+written to tape.
+
+Bacula version 1.39.x and later supports writing a backup
+to disk then later {\bf Migrating} or moving it to a tape (or any
+other medium). For
+details on this, please see the \ilink{Migration}{MigrationChapter} chapter
+of this manual for more details.
+
+The remainder of this chapter explains the various directives that you can use
+in the spooling process.
+
+\label{directives}
+\section{Data Spooling Directives}
+\index[general]{Directives!Data Spooling }
+\index[general]{Data Spooling Directives }
+
+The following directives can be used to control data spooling.
+
+\begin{itemize}
+\item To turn data spooling on/off at the Job level in the Job resource in
+ the Director's conf file (default {\bf no}).
+
+{\bf SpoolData = yes|no}
+
+\item To override the Job specification in a Schedule Run directive in the
+ Director's conf file.
+
+{\bf SpoolData = yes|no}
+
+\item To limit the maximum total size of the spooled data for a particular
+ device. Specified in the Device resource of the Storage daemon's conf file
+ (default unlimited).
+
+{\bf Maximum Spool Size = size}
+ Where size is a the maximum spool size for all jobs specified in bytes.
+
+\item To limit the maximum total size of the spooled data for a particular
+ device for a single job. Specified in the Device Resource of the Storage
+ daemon's conf file (default unlimited).
+
+{\bf Maximum Job Spool Size = size}
+ Where size is the maximum spool file size for a single job specified in
+ bytes.
+
+\item To specify the spool directory for a particular device. Specified in
+ the Device Resource of the Storage daemon's conf file (default, the working
+ directory).
+
+{\bf Spool Directory = directory}
+\end{itemize}
+
+\label{warning}
+
+% TODO: fix this section name
+\section{!!! MAJOR WARNING !!!}
+\index[general]{WARNING! MAJOR }
+\index[general]{ MAJOR WARNING }
+
+Please be very careful to exclude the spool directory from any backup,
+otherwise, your job will write enormous amounts of data to the Volume, and
+most probably terminate in error. This is because in attempting to backup the
+spool file, the backup data will be written a second time to the spool file,
+and so on ad infinitum.
+
+Another advice is to always specify the maximum spool size so that your disk
+doesn't completely fill up. In principle, data spooling will properly detect a
+full disk, and despool data allowing the job to continue. However, attribute
+spooling is not so kind to the user. If the disk on which attributes are being
+spooled fills, the job will be canceled. In addition, if your working
+directory is on the same partition as the spool directory, then Bacula jobs
+will fail possibly in bizarre ways when the spool fills.
+
+\label{points}
+\section{Other Points}
+\index[general]{Points!Other }
+\index[general]{Other Points }
+
+\begin{itemize}
+\item When data spooling is enabled, Bacula automatically turns on attribute
+ spooling. In other words, it also spools the catalog entries to disk. This is
+ done so that in case the job fails, there will be no catalog entries
+ pointing to non-existent tape backups.
+\item Attribute despooling occurs near the end of a job. The Storage daemon
+ accumulates file attributes during the backup and sends them to the
+ Director at the end of the job. The Director then inserts the file
+ attributes into the catalog. During this insertion, the tape drive may
+ be inactive. When the file attribute insertion is completed, the job
+ terminates.
+\item Attribute spool files are always placed in the working directory of
+ the Storage daemon.
+\item When Bacula begins despooling data spooled to disk, it takes exclusive
+ use of the tape. This has the major advantage that in running multiple
+ simultaneous jobs at the same time, the blocks of several jobs will not be
+ intermingled.
+\item It probably does not make a lot of sense to enable data spooling if you
+ are writing to disk files.
+\item It is probably best to provide as large a spool file as possible to
+ avoid repeatedly spooling/despooling. Also, while a job is despooling to
+ tape, the File daemon must wait (i.e. spooling stops for the job while it is
+ despooling).
+\item If you are running multiple simultaneous jobs, Bacula will continue
+ spooling other jobs while one is despooling to tape, provided there is
+ sufficient spool file space.
+\end{itemize}
--- /dev/null
+%%
+%%
+
+\chapter{L'\'etat actuel de Bacula}
+\label{_ChapterStart2}
+\index[general]{L'\'etat actuel de Bacula }
+\index[general]{Bacula!L'\'etat actuel de }
+\addcontentsline{toc}{section}{L'\'etat actuel de Bacula}
+
+En d'autres termes, ce qui est et ce qui n'est pas actuellement impl\'ement\'e
+et fonctionnel.
+
+\section{Ce qui est impl\'ement\'e}
+\index[general]{Ce qui est impl\'ement\'e }
+\addcontentsline{toc}{section}{Ce qui est impl\'ement\'e}
+
+\begin{itemize}
+\item Job Control
+ \begin{itemize}
+ \item Sauvegarde/restauration par le r\'eseau avec un Director centralis\'e.
+ \item Scheduler interne pour le lancement automatique des
+ \ilink{Jobs}{JobDef}.
+ \item Programmation de plusieurs Jobs \`a la m\^eme heure.
+ \item Execution simultan\'ee d'un Job ou plusieurs Jobs.
+ \item S\'equencement des Jobs selon une hi\'erarchie de priorit\'es.
+ \item \ilink{Console}{UADef} d'interfa\c{c}age avec le Director permettant un
+ contr\^ole total. La console est disponible en version shell ou en mode graphique GNOME et wxWidget.
+ Notez que pour l'instant, la version GNOME n'offre que tr\`es peu de fonctionnalit\'es
+ suppl\'ementaires par rapport \'a la console shell.
+ \end{itemize}
+
+ \item S\'ecurit\'e
+ \begin{itemize}
+ \item Verification des fichiers pr\'ec\'edemment r\'ef\'erenc\'es offreant des possibilit\'es \'a la Tripwire
+ (V\'erification de l'int\'egrit\'e du syst\`eme).
+ \item Authentification par \'echange de mots de passe CRAM-MD5 entre chaque composant ({\it daemon}).
+ \item \ilink{Chiffrement TLS (ssl)}{_ChapterStart61} entre chaque composant.
+ \item Calcul de signatures MD5 ou SHA1 des fichiers sauvegard\'es sur demande.
+ \end{itemize}
+
+
+\item Fonctionnalit\'es li\'ees aux restaurations
+ \begin{itemize}
+ \item Restauration d'un ou plusieurs fichiers s\'electionn\'es interactivement
+ parmi les fichiers de la derni\`ere sauvegarde ou ceux d'une sauvegarde
+ ant\'erieure \`a une date et heure donn\'ees.
+ \item Restauration d'un syst\`eme complet "depuis le m\'etal brut".
+ Cette op\'eration est largement automatis\'ee pour les syst\`emes Linux et
+ partiellement pour les Solaris. Consultez le
+ \ilink{Plan de Reprise d'activit\'e avec Bacula}{_ChapterStart38}.
+ Selon certains utilisateurs, la restauration "depuis le m\'etal brut"
+ fonctionne aussi pour les syst\`emes Win2K/XP.
+ \item Listage et restauration des fichiers avec les outils autonomes {\bf
+ bextract}. Entre autres choses, ceci permet l'extraction de fichiers quand
+ Bacula et/ou le catalogue ne sont pas disponibles. Notez : La m\'ethode
+ recommand\'ee pour restaurer des fichiers est d'utiliser la commande restore
+ dans la Console. Ces programmes sont con\c{c}us pour une utilisation en
+ dernier recours.
+ \item Possibilit\'e de r\'eg\'en\'erer le catalogue par balayage des volumes
+ de sauvegarde gr\^ace au programme {\bf bscan}.
+ \end{itemize}
+
+\item Catalogue SQL
+ \begin{itemize}
+ \item Fonctions de base de donn\'ees (catalogue) pour les informations
+ concernant les volumes, pools, jobs et fichiers sauvegard\'es.
+ \item Support pour des catalogues de type SQLite, PostgreSQL, et MySQL.
+ \item Requ\^etes utilisateur arbitraires sur les bases de donn\'ees SQLite,
+ PostgreSQL et MySQL.
+ \end{itemize}
+
+\item Gestion avanc\'ee des pools et volume
+ \begin{itemize}
+ \item Marquage (label) des Volumes pour pr\'evenir tout \'ecrasement
+ accidentel (au moins par Bacula).
+ \item Un nombre quelconque de Jobs et Clients peuvent \^etre sauvegard\'es sur
+ un Volume unique. Cela signifie que vous pouvez sauvegarder et restaurer des
+ machines Linux, Unix, Sun, et Windows sur le m\^eme volume.
+ \item Sauvegardes multi-volumes. Lorsqu'un Volume est plein, {\bf Bacula}
+ r\'eclame automatiquement le volume suivant et poursuit la sauvegarde.
+ \item Gestion de librairie par
+ \ilink{Pools et Volumes}{PoolResource} offrant beaucoup de
+ flexibilit\'e dans la gestion des volumes (par exemple, groupes de volumes mensuels,
+ hebdomadaires, quotidiens ou diff\'erenci\'es par client,...).
+ \item Format d'\'ecriture de donn\'ees sur les volumes ind\'ependant des
+ machines. Les clients Linux, Solaris, et Windows peuvent tous \^etre
+ sauvegard\'es sur le m\^eme volume si d\'esir\'e.
+ \item Prise en charge flexible des
+ \ilink{ messages}{MessageResource} incluant le routage des
+ messages depuis n'importe quel {\it daemon} vers le Director pour un
+ reporting automatique par e-mail.
+ \item Possibilit\'e de mettre les donn\'ees sur un tampon disque (data
+ spooling) lors des sauvegardes avec \'ecriture sur cartouche
+ asynchrone. Ceci pr\'evient les arr\`ets et red\'emarrage (NDT : "shoe shine") des lecteurs,
+ surtout lors des incr\'ementales et diff\'erentielles.
+ \end{itemize}
+
+\item Support avanc\'e pour la plupart des p\'eriph\'eriques de stockage
+ \begin{itemize}
+ \item Support pour les librairies de sauvegarde via une simple interface shell
+ capable de s'interfacer avec pratiquement n'importe quel programme
+ autochargeur.
+ \item Support pour les librairies \'equip\'ees de lecteurs de codes barres --
+ marquage (labeling) automatique selon les codes barres.
+ \item Support pour les librairies \`a magasins multiples, soit par
+ l'utilisation des codes barres, soit par lecture des cartouches.
+ \item Support pour les librairies avec plusieurs lecteurs.
+ \item Sauvegardes/restaurations "Raw device". Les restaurations doivent
+ alors s'effectuer vers le m\^eme support physique que la sauvegarde.
+ \item Tous les blocs de donn\'ees des volumes (approx 64K bytes) contiennent
+ une somme de contr\^ole.
+ \end{itemize}
+
+\item Support pour de nonbreux syst\`emes d'exploitation
+ \begin{itemize}
+ \item Programm\'e pour prendre en charge des noms de fichiers et messages
+ arbitrairement longs.
+ \item Compression GZIP fichier par fichier effectu\'ee, si activ\'ee, par le
+ programme Client avant le transfert sur le r\'eseau.
+ \item Sauvegarde et restaure les POSIX ACLs.
+ \item Liste d'acc\`es \`a la console qui permet de restreindre l'acc\`es des
+ utilisateurs \`a leurs donn\'ees seulement.
+ \item Support pour sauvegarde et restauration de fichiers de plus de 2GB.
+ \item Support pour les machines 64 bit, e.g. amd64.
+ \item Possibilit\'e de chiffrer les communications entre les {\it daemons} en
+ utilisant stunnel.
+ \item Support des \'etiquettes (labels) de cartouches ANSI et IBM.
+ \item Support des noms de fichiers Unicode (exemple : chinois) sur les machines Win32
+ depuis la version 1.37.28.
+ \item Sauvegarde coh\'erente des fichiers ouverts sur les syst\`emes Win32 (WinXP, Win2003
+ mais pas Win2000), par l'utilisation de Volume Shadow Copy (VSS).
+ \end{itemize}
+
+\item Divers
+ \begin{itemize}
+ \item Impl\'ementation multi-thread.
+ \item Un \ilink{fichier de configuration}{_ChapterStart40} compr\'ehensible et
+ extensible pour chaque {\it daemon}.
+ \end{itemize}
+\end{itemize}
+
+\section{Avantages de Bacula sur d'autres programmes de sauvegarde}
+\index[general]{Avantages de Bacula sur d'autres programmes de sauvegarde }
+\index[general]{Sauvegarde!Avantages de Bacula sur d'autres programmes de }
+\addcontentsline{toc}{section}{Avantages de Bacula sur d'autres programmes
+de sauvegarde}
+
+\begin{itemize}
+\item Du fait qu'il y a un client pour chaque machine, vous pouvez
+ sauvegarder et restaurer des clients de tous types avec l'assurance que tous
+ les attributs de fichiers sont convenablement sauvegard\'es et restaur\'es.
+\item Il est aussi possible de sauvegarder des clients sans aucun logiciel
+ client en utilisant NFS ou Samba. Cependant, nous recommandons d'ex\'ecuter,
+ si possible, un File Daemon client sur chaque machine \`a sauvegarder.
+\item Bacula prend en charge les sauvegardes multi-volumes.
+\item Une base de donn\'ees compl\`ete aux standards SQL de tous les fichiers
+ sauvegard\'es. Ceci permet une vue en ligne des fichiers sauvegard\'es sur
+ n'importe quel volume.
+\item Elagage automatique du catalogue (destruction des anciens
+ enregistrements), ce qui simplifie l'administration de la base de donn\'ees.
+\item N'importe quel moteur de base de donn\'ees SQL peut \^etre utilis\'e, ce
+ qui rend Bacula tr\`es flexible.
+\item La conception modulaire, mais int\'egr\'ee rend Bacula tr\`es
+ \'echelonnable.
+\item Puisque Bacula utilise des {\it daemons} fichier clients, toute base de
+ donn\'ees, toute application peut \^etre arr\'et\'ee proprement, puis
+ red\'emarr\'ee par Bacula avec les outils natifs du syst\`eme sauvegard\'e
+ (le tout dans un Job Bacula).
+\item Bacula int\`egre un Job Scheduler.
+\item Le format des volumes est document\'e et il existe de simples programmes C
+ pour le lire/\'ecrire.
+\item Bacula utilise des ports TCP/IP bien d\'efinis (enregistr\'es) -- pas de
+ rpcs, pas de m\'emoire partag\'ee.
+\item L'installation et la configuration de Bacula est relativement simple
+ compar\'ee \`a d'autres produits comparables.
+\item Selon un utilisateur, Bacula est aussi rapide que la grande application
+ commerciale majeure.
+\item Selon un autre utilisateur, Bacula est quatre fois plus rapide qu'une
+ autre application commerciale, probablement parce que cette application
+ stocke ses informations de catalogue dans un grand nombre de fichiers
+ plut\^ot que dans une base SQL comme le fait Bacula.
+\item Au lieu d'une interface d'administration graphique, Bacula poss\`ede une
+ interface shell qui permet \'a l'administrateur d'utiliser des outils tels que
+ ssh pour administrer n'importe quelle partie de Bacula depuis n'importe o\`u.
+\item Bacula dispose d'un CD de secours pour les syst\`emes Linux dot\'es des
+ fonctionnalit\'es suivantes :
+ \begin{itemize}
+ \item Vous le g\'en\'erez sur votre propre syst\`eme d'un simple make suivi de make burn.
+ \item Il utilise votre noyau.
+ \item Il capture vos param\`etres de disques et g\'en\`ere les scripts qui vous permettront
+ de repartitionner automatiquement vos disques et de les formater pour y remettre
+ ce qui s'y trouvait avant le d\'esastre.
+ \item Il comporte un script qui red\'emarrera votre r\'eseau (avec l'adresse IP correcte).
+ \item Il comporte un script qui monte automatiquement vos disques durs.
+ \item Il comporte un Bacula FD complet statiquement li\'e.
+ \item Vous pouvez ais\'ement y ajouter des donn\'ees ou programmes additionnels.
+\end{itemize}
+\end{itemize}
+
+\section{Restrictions de l'impl\'ementation actuelle}
+\index[general]{Restrictions de l'impl\'ementation actuelle }
+\index[general]{Actuelle!Restrictions de l'impl\'ementation }
+\addcontentsline{toc}{section}{Restrictions de l'impl\'ementation actuelle}
+
+\begin{itemize}
+\item Les chemins et noms de fichiers de longueur sup\'erieure \'a 260 caract\`eres
+ sur les syst\`emes Win32 ne sont pas support\'es. Il sont sauvegard\'es mais
+ ne peuvent \^etre restaur\'es. L'utilisation de la directive {\bf Portable=yes}
+ dans votre FileSet permet de restaurer ces fichiers vers les syst\`emes
+ Unix et Linux. Les noms de fichiers longs seront impl\'ement\'es dans la
+ version 1.40.
+\item Si vous avez plus de 4 billions de fichiers enregistr\'es dans votre
+ catalogue, la base de donn\'ees FileId atteindra probablement ses limites.
+ Ceci est une base de donn\'ees monstrueuse mais possible. A un certain stade,
+ les champs FileId de Bacula passeront de 32 bits \`a 64 et ce probl\`eme
+ dispara{\^\i}tra. En attendant, un palliatif satisfaisant consiste \`a
+ utiliser plusieurs bases de donn\'ees
+\item Les fichiers supprim\'es apr\`es une sauvegarde full sont inclus dans
+ les restaurations.
+\item Les sauvegardes diff\'erentielles et incr\'ementales de Bacula se basent sur
+ les time stamps. Par cons\'equent, si vous d\'eplacez des fichiers d'un r\'epertoire
+ existant ou un r\'epertoire complet appartenant \'a un FileSet apr\`es une Full,
+ ces fichiers ne seront probablement pas sauvegard\'es par une incr\'ementale,
+ car ils seront encore marqu\'es des anciennes dates. Vous devez explicitement
+ mettre \'a jour ces dates sur tous les fichiers d\'eplac\'es. La correction de ce
+ d\'efaut est en projet.
+\item Les Modules Syst\`eme de Fichiers (routines configurables pour
+ sauvegarder/restaurer les fichiers sp\'eciaux) ne sont pas encore impl\'ement\'es.
+\item Le chiffrement des donn\'ees sur les volumes sera impl\'ement\'e dans la version 1.40.
+\item Bacula ne peut restaurer automatiquement les fichiers d'un job depuis
+ deux ou plusieurs p\'eriph\'eriques de stockage diff\'erents. Si vous
+ un m\^eme job utilise plusieurs p\'eriph\'eriques ou plusieurs types de
+ m\'edia distincts, le processus de restauration n\'ecessitera certaines
+ interventions manuelles.
+\item Bacula ne supporte pas les volumes disque amovibles pour l'instant.
+ Des utilisateurs d\'eclarent \^etre parvenu \'a faire fonctionner Bacula
+ ainsi, mais cela n\'ecessite de prendre garde de monter le bon volume, de
+ plus, les restaurations diss\'emin\'ees sur plusieurs volumes risquent
+ fort de ne pas fonctionner. Cette fonctionnalit\'e est pr\'evue pour la version
+ 1.40.
+\end{itemize}
+
+\section{Limitations ou Restrictions inh\'erentes \`a la conception}
+\index[general]{Limitations ou Restrictions inh\'erentes \`a la conception }
+\index[general]{Conception!Limitations ou Restrictions inh\'erentes \`a la }
+\addcontentsline{toc}{section}{Limitations ou Restrictions inh\'erentes \`a
+la conception}
+
+\begin{itemize}
+\item Les noms (tels que resource names, Volume names, ...) d\'efinis dans les
+ fichiers de configuration de Bacula sont limit\'es \`a un nombre fix\'e de
+ caract\`eres. Actuellement, la limite est d\'efinie \`a 127 caract\`eres.
+Notez que ceci ne concerne pas les noms de fichiers qui peuvent \^etre
+arbitrairement longs.
+\item Sur les machines Win32, les noms de fichiers sont limit\'es \'a 260 caract\`eres
+ par l'API non-Unicode Windows que nous utilisons. A partir de la version 1.39,
+ nous avons bascul\'e sur l'API Unicode et cette limitation n'existe plus.
+\end{itemize}
--- /dev/null
+%%
+%%
+
+\chapter{Backup Strategies}
+\label{StrategiesChapter}
+\index[general]{Strategies!Backup }
+\index[general]{Backup Strategies }
+
+Although Recycling and Backing Up to Disk Volume have been discussed in
+previous chapters, this chapter is meant to give you an overall view of
+possible backup strategies and to explain their advantages and disadvantages.
+\label{Simple}
+
+\section{Simple One Tape Backup}
+\index[general]{Backup!Simple One Tape }
+\index[general]{Simple One Tape Backup }
+
+Probably the simplest strategy is to back everything up to a single tape and
+insert a new (or recycled) tape when it fills and Bacula requests a new one.
+
+\subsection{Advantages}
+\index[general]{Advantages }
+
+\begin{itemize}
+\item The operator intervenes only when a tape change is needed. (once a
+ month at my site).
+\item There is little chance of operator error because the tape is not
+ changed daily.
+\item A minimum number of tapes will be needed for a full restore. Typically
+ the best case will be one tape and worst two.
+\item You can easily arrange for the Full backup to occur a different night
+ of the month for each system, thus load balancing and shortening the backup
+ time.
+\end{itemize}
+
+\subsection{Disadvantages}
+\index[general]{Disadvantages }
+
+\begin{itemize}
+\item If your site burns down, you will lose your current backups, and in my
+ case about a month of data.
+\item After a tape fills and you have put in a blank tape, the backup will
+ continue, and this will generally happen during working hours.
+ \end{itemize}
+
+\subsection{Practical Details}
+\index[general]{Details!Practical }
+\index[general]{Practical Details }
+
+This system is very simple. When the tape fills and Bacula requests a new
+tape, you {\bf unmount} the tape from the Console program, insert a new tape
+and {\bf label} it. In most cases after the label, Bacula will automatically
+mount the tape and resume the backup. Otherwise, you simply {\bf mount} the
+tape.
+
+Using this strategy, one typically does a Full backup once a week followed by
+daily Incremental backups. To minimize the amount of data written to the tape,
+one can do a Full backup once a month on the first Sunday of the
+month, a Differential backup on the 2nd-5th Sunday of the month, and
+incremental backups the rest of the week.
+\label{Manual}
+
+\section{Manually Changing Tapes}
+\index[general]{Tapes!Manually Changing }
+\index[general]{Manually Changing Tapes }
+
+If you use the strategy presented above, Bacula will ask you to change the
+tape, and you will {\bf unmount} it and then remount it when you have inserted
+the new tape.
+
+If you do not wish to interact with Bacula to change each tape, there are
+several ways to get Bacula to release the tape:
+
+\begin{itemize}
+\item In your Storage daemon's Device resource, set
+ {\bf AlwaysOpen = no}
+ In this case, Bacula will release the tape after every job. If you run
+ several jobs, the tape will be rewound and repositioned to the end at the
+ beginning of every job. This is not very efficient, but does let you change
+ the tape whenever you want.
+\item Use a {\bf RunAfterJob} statement to run a script after your last job.
+ This could also be an {\bf Admin} job that runs after all your backup jobs.
+ The script could be something like:
+
+\footnotesize
+\begin{verbatim}
+ #!/bin/sh
+ /full-path/bconsole -c /full-path/bconsole.conf <<END_OF_DATA
+ release storage=your-storage-name
+ END_OF_DATA
+
+\end{verbatim}
+\normalsize
+
+In this example, you would have {\bf AlwaysOpen=yes}, but the {\bf release}
+command would tell Bacula to rewind the tape and on the next job assume the
+tape has changed. This strategy may not work on some systems, or on
+autochangers because Bacula will still keep the drive open.
+\item The final strategy is similar to the previous case except that you
+ would use the unmount command to force Bacula to release the drive. Then you
+ would eject the tape, and remount it as follows:
+
+\footnotesize
+\begin{verbatim}
+ #!/bin/sh
+ /full-path/bconsole -c /full-path/bconsole.conf <\<END_OF_DATA
+ unmount storage=your-storage-name
+ END_OF_DATA
+ # the following is a shell command
+ mt eject
+ /full-path/bconsole -c /full-path/bconsole.conf <<END_OF_DATA
+ mount storage=your-storage-name
+ END_OF_DATA
+
+\end{verbatim}
+\normalsize
+
+\end{itemize}
+
+\label{Daily}
+
+\section{Daily Tape Rotation}
+\index[general]{Rotation!Daily Tape }
+\index[general]{Daily Tape Rotation }
+
+This scheme is quite different from the one mentioned above in that a Full
+backup is done to a different tape every day of the week. Generally, the
+backup will cycle continuously through five or six tapes each week. Variations are
+to use a different tape each Friday, and possibly at the beginning of the
+month. Thus if backups are done Monday through Friday only, you need only five
+tapes, and by having two Friday tapes, you need a total of six tapes. Many sites
+run this way, or using modifications of it based on two week cycles or longer.
+
+
+\subsection{Advantages}
+\index[general]{Advantages }
+
+\begin{itemize}
+\item All the data is stored on a single tape, so recoveries are simple and
+ faster.
+\item Assuming the previous day's tape is taken offsite each day, a maximum
+ of one days data will be lost if the site burns down.
+ \end{itemize}
+
+\subsection{Disadvantages}
+\index[general]{Disadvantages }
+
+\begin{itemize}
+\item The tape must be changed every day requiring a lot of operator
+ intervention.
+\item More errors will occur because of human mistakes.
+\item If the wrong tape is inadvertently mounted, the Backup for that day
+ will not occur exposing the system to data loss.
+\item There is much more movement of the tape each day (rewinds) leading to
+ shorter tape drive life time.
+\item Initial setup of Bacula to run in this mode is more complicated than
+ the Single tape system described above.
+\item Depending on the number of systems you have and their data capacity, it
+ may not be possible to do a Full backup every night for time reasons or
+ reasons of tape capacity.
+\end{itemize}
+
+\subsection{Practical Details}
+\index[general]{Details!Practical }
+\index[general]{Practical Details }
+
+The simplest way to "force" Bacula to use a different tape each day is to
+define a different Pool for each day of the the week a backup is done. In
+addition, you will need to specify appropriate Job and File retention periods
+so that Bacula will relabel and overwrite the tape each week rather than
+appending to it. Nic Bellamy has supplied an actual working model of this
+which we include here.
+
+What is important is to create a different Pool for each day of the week, and
+on the {\bf run} statement in the Schedule, to specify which Pool is to be
+used. He has one Schedule that accomplishes this, and a second Schedule that
+does the same thing for the Catalog backup run each day after the main backup
+(Priorities were not available when this script was written). In addition, he
+uses a {\bf Max Start Delay} of 22 hours so that if the wrong tape is
+premounted by the operator, the job will be automatically canceled, and the
+backup cycle will re-synchronize the next day. He has named his Friday Pool
+{\bf WeeklyPool} because in that Pool, he wishes to have several tapes to be
+able to restore to a time older than one week.
+
+And finally, in his Storage daemon's Device resource, he has {\bf Automatic
+Mount = yes} and {\bf Always Open = No}. This is necessary for the tape
+ejection to work in his {\bf end\_of\_backup.sh} script below.
+
+For example, his bacula-dir.conf file looks like the following:
+
+\footnotesize
+\begin{verbatim}
+
+# /etc/bacula/bacula-dir.conf
+#
+# Bacula Director Configuration file
+#
+Director {
+ Name = ServerName
+ DIRport = 9101
+ QueryFile = "/etc/bacula/query.sql"
+ WorkingDirectory = "/var/lib/bacula"
+ PidDirectory = "/var/run"
+ SubSysDirectory = "/var/lock/subsys"
+ Maximum Concurrent Jobs = 1
+ Password = "console-pass"
+ Messages = Standard
+}
+#
+# Define the main nightly save backup job
+#
+Job {
+ Name = "NightlySave"
+ Type = Backup
+ Client = ServerName
+ FileSet = "Full Set"
+ Schedule = "WeeklyCycle"
+ Storage = Tape
+ Messages = Standard
+ Pool = Default
+ Write Bootstrap = "/var/lib/bacula/NightlySave.bsr"
+ Max Start Delay = 22h
+}
+# Backup the catalog database (after the nightly save)
+Job {
+ Name = "BackupCatalog"
+ Type = Backup
+ Client = ServerName
+ FileSet = "Catalog"
+ Schedule = "WeeklyCycleAfterBackup"
+ Storage = Tape
+ Messages = Standard
+ Pool = Default
+ # This creates an ASCII copy of the catalog
+ # WARNING!!! Passing the password via the command line is insecure.
+ # see comments in make_catalog_backup for details.
+ RunBeforeJob = "/usr/lib/bacula/make_catalog_backup -u bacula"
+ # This deletes the copy of the catalog, and ejects the tape
+ RunAfterJob = "/etc/bacula/end_of_backup.sh"
+ Write Bootstrap = "/var/lib/bacula/BackupCatalog.bsr"
+ Max Start Delay = 22h
+}
+# Standard Restore template, changed by Console program
+Job {
+ Name = "RestoreFiles"
+ Type = Restore
+ Client = ServerName
+ FileSet = "Full Set"
+ Storage = Tape
+ Messages = Standard
+ Pool = Default
+ Where = /tmp/bacula-restores
+}
+# List of files to be backed up
+FileSet {
+ Name = "Full Set"
+ Include = signature=MD5 {
+ /
+ /data
+ }
+ Exclude = { /proc /tmp /.journal }
+}
+#
+# When to do the backups
+#
+Schedule {
+ Name = "WeeklyCycle"
+ Run = Level=Full Pool=MondayPool Monday at 8:00pm
+ Run = Level=Full Pool=TuesdayPool Tuesday at 8:00pm
+ Run = Level=Full Pool=WednesdayPool Wednesday at 8:00pm
+ Run = Level=Full Pool=ThursdayPool Thursday at 8:00pm
+ Run = Level=Full Pool=WeeklyPool Friday at 8:00pm
+}
+# This does the catalog. It starts after the WeeklyCycle
+Schedule {
+ Name = "WeeklyCycleAfterBackup"
+ Run = Level=Full Pool=MondayPool Monday at 8:15pm
+ Run = Level=Full Pool=TuesdayPool Tuesday at 8:15pm
+ Run = Level=Full Pool=WednesdayPool Wednesday at 8:15pm
+ Run = Level=Full Pool=ThursdayPool Thursday at 8:15pm
+ Run = Level=Full Pool=WeeklyPool Friday at 8:15pm
+}
+# This is the backup of the catalog
+FileSet {
+ Name = "Catalog"
+ Include = signature=MD5 {
+ /var/lib/bacula/bacula.sql
+ }
+}
+# Client (File Services) to backup
+Client {
+ Name = ServerName
+ Address = dionysus
+ FDPort = 9102
+ Catalog = MyCatalog
+ Password = "client-pass"
+ File Retention = 30d
+ Job Retention = 30d
+ AutoPrune = yes
+}
+# Definition of file storage device
+Storage {
+ Name = Tape
+ Address = dionysus
+ SDPort = 9103
+ Password = "storage-pass"
+ Device = Tandberg
+ Media Type = MLR1
+}
+# Generic catalog service
+Catalog {
+ Name = MyCatalog
+ dbname = bacula; user = bacula; password = ""
+}
+# Reasonable message delivery -- send almost all to email address
+# and to the console
+Messages {
+ Name = Standard
+ mailcommand = "/usr/sbin/bsmtp -h localhost -f \"\(Bacula\) %r\"
+ -s \"Bacula: %t %e of %c %l\" %r"
+ operatorcommand = "/usr/sbin/bsmtp -h localhost -f \"\(Bacula\) %r\"
+ -s \"Bacula: Intervention needed for %j\" %r"
+ mail = root@localhost = all, !skipped
+ operator = root@localhost = mount
+ console = all, !skipped, !saved
+ append = "/var/lib/bacula/log" = all, !skipped
+}
+
+# Pool definitions
+#
+# Default Pool for jobs, but will hold no actual volumes
+Pool {
+ Name = Default
+ Pool Type = Backup
+}
+Pool {
+ Name = MondayPool
+ Pool Type = Backup
+ Recycle = yes
+ AutoPrune = yes
+ Volume Retention = 6d
+ Maximum Volume Jobs = 2
+}
+Pool {
+ Name = TuesdayPool
+ Pool Type = Backup
+ Recycle = yes
+ AutoPrune = yes
+ Volume Retention = 6d
+ Maximum Volume Jobs = 2
+}
+Pool {
+ Name = WednesdayPool
+ Pool Type = Backup
+ Recycle = yes
+ AutoPrune = yes
+ Volume Retention = 6d
+ Maximum Volume Jobs = 2
+}
+Pool {
+ Name = ThursdayPool
+ Pool Type = Backup
+ Recycle = yes
+ AutoPrune = yes
+ Volume Retention = 6d
+ Maximum Volume Jobs = 2
+}
+Pool {
+ Name = WeeklyPool
+ Pool Type = Backup
+ Recycle = yes
+ AutoPrune = yes
+ Volume Retention = 12d
+ Maximum Volume Jobs = 2
+}
+# EOF
+\end{verbatim}
+\normalsize
+
+Note, the mailcommand and operatorcommand should be on a single line each.
+They were split to preserve the proper page width. In order to get Bacula to
+release the tape after the nightly backup, he uses a {\bf RunAfterJob} script
+that deletes the ASCII copy of the database back and then rewinds and ejects
+the tape. The following is a copy of {\bf end\_of\_backup.sh}
+
+\footnotesize
+\begin{verbatim}
+#! /bin/sh
+/usr/lib/bacula/delete_catalog_backup
+mt rewind
+mt eject
+exit 0
+\end{verbatim}
+\normalsize
+
+Finally, if you list his Volumes, you get something like the following:
+
+\footnotesize
+\begin{verbatim}
+*list media
+Using default Catalog name=MyCatalog DB=bacula
+Pool: WeeklyPool
++-----+-----------+-------+--------+-----------+-----------------+-------+------+
+| MeId| VolumeName| MedTyp| VolStat| VolBytes | LastWritten | VolRet| Recyc|
++-----+-----------+-------+--------+-----------+-----------------+-------+------+
+| 5 | Friday_1 | MLR1 | Used | 2157171998| 2003-07-11 20:20| 103680| 1 |
+| 6 | Friday_2 | MLR1 | Append | 0 | 0 | 103680| 1 |
++-----+-----------+-------+--------+-----------+-----------------+-------+------+
+Pool: MondayPool
++-----+-----------+-------+--------+-----------+-----------------+-------+------+
+| MeId| VolumeName| MedTyp| VolStat| VolBytes | LastWritten | VolRet| Recyc|
++-----+-----------+-------+--------+-----------+-----------------+-------+------+
+| 2 | Monday | MLR1 | Used | 2260942092| 2003-07-14 20:20| 518400| 1 |
++-----+-----------+-------+--------+-----------+-----------------+-------+------+
+Pool: TuesdayPool
++-----+-----------+-------+--------+-----------+-----------------+-------+------+
+| MeId| VolumeName| MedTyp| VolStat| VolBytes | LastWritten | VolRet| Recyc|
++-----+-----------+-------+--------+-----------+-----------------+-------+------+
+| 3 | Tuesday | MLR1 | Used | 2268180300| 2003-07-15 20:20| 518400| 1 |
++-----+-----------+-------+--------+-----------+-----------------+-------+------+
+Pool: WednesdayPool
++-----+-----------+-------+--------+-----------+-----------------+-------+------+
+| MeId| VolumeName| MedTyp| VolStat| VolBytes | LastWritten | VolRet| Recyc|
++-----+-----------+-------+--------+-----------+-----------------+-------+------+
+| 4 | Wednesday | MLR1 | Used | 2138871127| 2003-07-09 20:2 | 518400| 1 |
++-----+-----------+-------+--------+-----------+-----------------+-------+------+
+Pool: ThursdayPool
++-----+-----------+-------+--------+-----------+-----------------+-------+------+
+| MeId| VolumeName| MedTyp| VolStat| VolBytes | LastWritten | VolRet| Recyc|
++-----+-----------+-------+--------+-----------+-----------------+-------+------+
+| 1 | Thursday | MLR1 | Used | 2146276461| 2003-07-10 20:50| 518400| 1 |
++-----+-----------+-------+--------+-----------+-----------------+-------+------+
+Pool: Default
+No results to list.
+\end{verbatim}
+\normalsize
+
+Note, I have truncated a number of the columns so that the information fits on
+the width of a page.
--- /dev/null
+%%
+%%
+
+\chapter{Using Stunnel to Encrypt Communications}
+\label{StunnelChapter}
+\index[general]{Using Stunnel to Encrypt Communications to Clients }
+
+Prior to version 1.37, Bacula did not have built-in communications encryption.
+Please see the \ilink {TLS chapter}{CommEncryption} if you are using Bacula
+1.37 or greater.
+
+Without too much effort, it is possible to encrypt the communications
+between any of the daemons. This chapter will show you how to use {\bf
+stunnel} to encrypt communications to your client programs. We assume the
+Director and the Storage daemon are running on one machine that will be called
+{\bf server} and the Client or File daemon is running on a different machine
+called {\bf client}. Although the details may be slightly different, the same
+principles apply whether you are encrypting between Unix, Linux, or Win32
+machines. This example was developed between two Linux machines running
+stunnel version 4.04-4 on a Red Hat Enterprise 3.0 system.
+
+\section{Communications Ports Used}
+\index[general]{Used!Communications Ports }
+\index[general]{Communications Ports Used }
+
+First, you must know that with the standard Bacula configuration, the Director
+will contact the File daemon on port 9102. The File daemon then contacts the
+Storage daemon using the address and port parameters supplied by the Director.
+The standard port used will be 9103. This is the typical server/client view of
+the world, the File daemon is a server to the Director (i.e. listens for the
+Director to contact it), and the Storage daemon is a server to the File
+daemon.
+
+\section{Encryption}
+\index[general]{Encryption }
+
+The encryption is accomplished between the Director and the File daemon by
+using an stunnel on the Director's machine (server) to encrypt the data and to
+contact an stunnel on the File daemon's machine (client), which decrypts the
+data and passes it to the client.
+
+Between the File daemon and the Storage daemon, we use an stunnel on the File
+daemon's machine to encrypt the data and another stunnel on the Storage
+daemon's machine to decrypt the data.
+
+As a consequence, there are actually four copies of stunnel running, two on the
+server and two on the client. This may sound a bit complicated, but it really
+isn't. To accomplish this, we will need to construct four separate conf files
+for stunnel, and we will need to make some minor modifications to the
+Director's conf file. None of the other conf files need to be changed.
+
+\section{A Picture}
+\index[general]{Picture }
+
+Since pictures usually help a lot, here is an overview of what we will be
+doing. Don't worry about all the details of the port numbers and such for the
+moment.
+
+\footnotesize
+\begin{verbatim}
+ File daemon (client):
+ stunnel-fd1.conf
+ |===========|
+ Port 29102 >----| Stunnel 1 |-----> Port 9102
+ |===========|
+ stunnel-fd2.conf
+ |===========|
+ Port 9103 >----| Stunnel 2 |-----> server:29103
+ |===========|
+ Director (server):
+ stunnel-dir.conf
+ |===========|
+ Port 29102 >----| Stunnel 3 |-----> client:29102
+ |===========|
+ stunnel-sd.conf
+ |===========|
+ Port 29103 >----| Stunnel 4 |-----> 9103
+ |===========|
+\end{verbatim}
+\normalsize
+
+\section{Certificates}
+\index[general]{Certificates }
+
+In order for stunnel to function as a server, which it does in our diagram for
+Stunnel 1 and Stunnel 4, you must have a certificate and the key. It is
+possible to keep the two in separate files, but normally, you keep them in one
+single .pem file. You may create this certificate yourself in which case, it
+will be self-signed, or you may have it signed by a CA.
+
+If you want your clients to verify that the server is in fact valid (Stunnel 2
+and Stunnel 3), you will need to have the server certificates signed by a CA
+(Certificate Authority), and you will need to have the CA's public certificate
+(contains the CA's public key).
+
+Having a CA signed certificate is {\bf highly} recommended if you are using
+your client across the Internet, otherwise you are exposed to the man in the
+middle attack and hence loss of your data.
+
+See below for how to create a self-signed certificate.
+
+\section{Securing the Data Channel}
+\index[general]{Channel!Securing the Data }
+\index[general]{Securing the Data Channel }
+
+To simplify things a bit, let's for the moment consider only the data channel.
+That is the connection between the File daemon and the Storage daemon, which
+takes place on port 9103. In fact, in a minimalist solution, this is the only
+connection that needs to be encrypted, because it is the one that transports your
+data. The connection between the Director and the File daemon is simply a
+control channel used to start the job and get the job status.
+
+Normally the File daemon will contact the Storage daemon on port 9103
+(supplied by the Director), so we need an stunnel that listens on port 9103 on
+the File daemon's machine, encrypts the data and sends it to the Storage
+daemon. This is depicted by Stunnel 2 above. Note that this stunnel is
+listening on port 9103 and sending to server:29103. We use port 29103 on the
+server because if we would send the data to port 9103, it would go directly to the
+Storage daemon, which doesn't understand encrypted data. On the server
+machine, we run Stunnel 4, which listens on port 29103, decrypts the data and
+sends it to the Storage daemon, which is listening on port 9103.
+
+\section{Data Channel Configuration}
+\index[general]{Modification of bacula-dir.conf for the Data Channel }
+\index[general]{baculoa-dir.conf!Modification for the Data Channel }
+
+The Storage resource of the bacula-dir.conf normally looks something like the
+following:
+
+\footnotesize
+\begin{verbatim}
+Storage {
+ Name = File
+ Address = server
+ SDPort = 9103
+ Password = storage_password
+ Device = File
+ Media Type = File
+}
+\end{verbatim}
+\normalsize
+
+Notice that this is running on the server machine, and it points the File
+daemon back to server:9103, which is where our Storage daemon is listening. We
+modify this to be:
+
+\footnotesize
+\begin{verbatim}
+Storage {
+ Name = File
+ Address = localhost
+ SDPort = 9103
+ Password = storage_password
+ Device = File
+ Media Type = File
+}
+\end{verbatim}
+\normalsize
+
+This causes the File daemon to send the data to the stunnel running on
+localhost (the client machine). We could have used client as the address as
+well.
+
+\section{Stunnel Configuration for the Data Channel}
+\index[general]{Stunnel Configuration for the Data Channel }
+
+In the diagram above, we see above Stunnel 2 that we use stunnel-fd2.conf on the
+client. A pretty much minimal config file would look like the following:
+
+\footnotesize
+\begin{verbatim}
+client = yes
+[29103]
+accept = localhost:9103
+connect = server:29103
+\end{verbatim}
+\normalsize
+
+The above config file does encrypt the data but it does not require a
+certificate, so it is subject to the man in the middle attack. The file I
+actually used, stunnel-fd2.conf, looked like this:
+
+\footnotesize
+\begin{verbatim}
+#
+# Stunnel conf for Bacula client -> SD
+#
+pid = /home/kern/bacula/bin/working/stunnel.pid
+#
+# A cert is not mandatory here. If verify=2, a
+# cert signed by a CA must be specified, and
+# either CAfile or CApath must point to the CA's
+# cert
+#
+cert = /home/kern/stunnel/stunnel.pem
+CAfile = /home/kern/ssl/cacert.pem
+verify = 2
+client = yes
+# debug = 7
+# foreground = yes
+[29103]
+accept = localhost:9103
+connect = server:29103
+\end{verbatim}
+\normalsize
+
+You will notice that I specified a pid file location because I ran stunnel
+under my own userid so I could not use the default, which requires root
+permission. I also specified a certificate that I have as well as verify level
+2 so that the certificate is required and verified, and I must supply the
+location of the CA (Certificate Authority) certificate so that the stunnel
+certificate can be verified. Finally, you will see that there are two lines
+commented out, which when enabled, produce a lot of nice debug info in the
+command window.
+
+If you do not have a signed certificate (stunnel.pem), you need to delete the
+cert, CAfile, and verify lines.
+
+Note that the stunnel.pem, is actually a private key and a certificate in a
+single file. These two can be kept and specified individually, but keeping
+them in one file is more convenient.
+
+The config file, stunnel-sd.conf, needed for Stunnel 4 on the server machine
+is:
+
+\footnotesize
+\begin{verbatim}
+#
+# Bacula stunnel conf for Storage daemon
+#
+pid = /home/kern/bacula/bin/working/stunnel.pid
+#
+# A cert is mandatory here, it may be self signed
+# If it is self signed, the client may not use
+# verify
+#
+cert = /home/kern/stunnel/stunnel.pem
+client = no
+# debug = 7
+# foreground = yes
+[29103]
+accept = 29103
+connect = 9103
+\end{verbatim}
+\normalsize
+
+\section{Starting and Testing the Data Encryption}
+\index[general]{Starting and Testing the Data Encryption }
+\index[general]{Encryption!Starting and Testing the Data }
+
+It will most likely be the simplest to implement the Data Channel encryption
+in the following order:
+
+\begin{itemize}
+\item Setup and run Bacula backing up some data on your client machine
+ without encryption.
+\item Stop Bacula.
+\item Modify the Storage resource in the Director's conf file.
+\item Start Bacula
+\item Start stunnel on the server with:
+
+ \footnotesize
+\begin{verbatim}
+ stunnel stunnel-sd.conf
+
+\end{verbatim}
+\normalsize
+
+\item Start stunnel on the client with:
+
+ \footnotesize
+\begin{verbatim}
+ stunnel stunnel-fd2.conf
+
+\end{verbatim}
+\normalsize
+
+\item Run a job.
+\item If it doesn't work, turn debug on in both stunnel conf files, restart
+ the stunnels, rerun the job, repeat until it works.
+ \end{itemize}
+
+\section{Encrypting the Control Channel}
+\index[general]{Channel!Encrypting the Control }
+\index[general]{Encrypting the Control Channel }
+
+The Job control channel is between the Director and the File daemon, and as
+mentioned above, it is not really necessary to encrypt, but it is good
+practice to encrypt it as well. The two stunnels that are used in this case
+will be Stunnel 1 and Stunnel 3 in the diagram above. Stunnel 3 on the server
+might normally listen on port 9102, but if you have a local File daemon, this
+will not work, so we make it listen on port 29102. It then sends the data to
+client:29102. Again we use port 29102 so that the stunnel on the client
+machine can decrypt the data before passing it on to port 9102 where the File
+daemon is listening.
+
+\section{Control Channel Configuration}
+\index[general]{Control Channel Configuration }
+
+We need to modify the standard Client resource, which would normally look
+something like:
+
+\footnotesize
+\begin{verbatim}
+Client {
+ Name = client-fd
+ Address = client
+ FDPort = 9102
+ Catalog = BackupDB
+ Password = "xxx"
+}
+\end{verbatim}
+\normalsize
+
+to be:
+
+\footnotesize
+\begin{verbatim}
+Client {
+ Name = client-fd
+ Address = localhost
+ FDPort = 29102
+ Catalog = BackupDB
+ Password = "xxx"
+}
+\end{verbatim}
+\normalsize
+
+This will cause the Director to send the control information to
+localhost:29102 instead of directly to the client.
+
+\section{Stunnel Configuration for the Control Channel}
+\index[general]{Config Files for stunnel to Encrypt the Control Channel }
+
+The stunnel config file, stunnel-dir.conf, for the Director's machine would
+look like the following:
+
+\footnotesize
+\begin{verbatim}
+#
+# Bacula stunnel conf for the Directory to contact a client
+#
+pid = /home/kern/bacula/bin/working/stunnel.pid
+#
+# A cert is not mandatory here. If verify=2, a
+# cert signed by a CA must be specified, and
+# either CAfile or CApath must point to the CA's
+# cert
+#
+cert = /home/kern/stunnel/stunnel.pem
+CAfile = /home/kern/ssl/cacert.pem
+verify = 2
+client = yes
+# debug = 7
+# foreground = yes
+[29102]
+accept = localhost:29102
+connect = client:29102
+\end{verbatim}
+\normalsize
+
+and the config file, stunnel-fd1.conf, needed to run stunnel on the Client
+would be:
+
+\footnotesize
+\begin{verbatim}
+#
+# Bacula stunnel conf for the Directory to contact a client
+#
+pid = /home/kern/bacula/bin/working/stunnel.pid
+#
+# A cert is not mandatory here. If verify=2, a
+# cert signed by a CA must be specified, and
+# either CAfile or CApath must point to the CA's
+# cert
+#
+cert = /home/kern/stunnel/stunnel.pem
+CAfile = /home/kern/ssl/cacert.pem
+verify = 2
+client = yes
+# debug = 7
+# foreground = yes
+[29102]
+accept = localhost:29102
+connect = client:29102
+\end{verbatim}
+\normalsize
+
+\section{Starting and Testing the Control Channel}
+\index[general]{Starting and Testing the Control Channel }
+\index[general]{Channel!Starting and Testing the Control }
+
+It will most likely be the simplest to implement the Control Channel
+encryption in the following order:
+
+\begin{itemize}
+\item Stop Bacula.
+\item Modify the Client resource in the Director's conf file.
+\item Start Bacula
+\item Start stunnel on the server with:
+
+ \footnotesize
+\begin{verbatim}
+ stunnel stunnel-dir.conf
+
+\end{verbatim}
+\normalsize
+
+\item Start stunnel on the client with:
+
+ \footnotesize
+\begin{verbatim}
+ stunnel stunnel-fd1.conf
+
+\end{verbatim}
+\normalsize
+
+\item Run a job.
+\item If it doesn't work, turn debug on in both stunnel conf files, restart
+ the stunnels, rerun the job, repeat until it works.
+ \end{itemize}
+
+\section{Using stunnel to Encrypt to a Second Client}
+\index[general]{Using stunnel to Encrypt to a Second Client }
+\index[general]{Client!Using stunnel to Encrypt to a Second }
+
+On the client machine, you can just duplicate the setup that you have on the
+first client file for file and it should work fine.
+
+In the bacula-dir.conf file, you will want to create a second client pretty
+much identical to how you did for the first one, but the port number must be
+unique. We previously used:
+
+\footnotesize
+\begin{verbatim}
+Client {
+ Name = client-fd
+ Address = localhost
+ FDPort = 29102
+ Catalog = BackupDB
+ Password = "xxx"
+}
+\end{verbatim}
+\normalsize
+
+so for the second client, we will, of course, have a different name, and we
+will also need a different port. Remember that we used port 29103 for the
+Storage daemon, so for the second client, we can use port 29104, and the
+Client resource would look like:
+
+\footnotesize
+\begin{verbatim}
+Client {
+ Name = client2-fd
+ Address = localhost
+ FDPort = 29104
+ Catalog = BackupDB
+ Password = "yyy"
+}
+\end{verbatim}
+\normalsize
+
+Now, fortunately, we do not need a third stunnel to on the Director's machine,
+we can just add the new port to the config file, stunnel-dir.conf, to make:
+
+\footnotesize
+\begin{verbatim}
+#
+# Bacula stunnel conf for the Directory to contact a client
+#
+pid = /home/kern/bacula/bin/working/stunnel.pid
+#
+# A cert is not mandatory here. If verify=2, a
+# cert signed by a CA must be specified, and
+# either CAfile or CApath must point to the CA's
+# cert
+#
+cert = /home/kern/stunnel/stunnel.pem
+CAfile = /home/kern/ssl/cacert.pem
+verify = 2
+client = yes
+# debug = 7
+# foreground = yes
+[29102]
+accept = localhost:29102
+connect = client:29102
+[29104]
+accept = localhost:29102
+connect = client2:29102
+\end{verbatim}
+\normalsize
+
+There are no changes necessary to the Storage daemon or the other stunnel so
+that this new client can talk to our Storage daemon.
+
+\section{Creating a Self-signed Certificate}
+\index[general]{Creating a Self-signed Certificate }
+\index[general]{Certificate!Creating a Self-signed }
+
+You may create a self-signed certificate for use with stunnel that will permit
+you to make it function, but will not allow certificate validation. The .pem
+file containing both the certificate and the key can be made with the
+following, which I put in a file named {\bf makepem}:
+
+\footnotesize
+\begin{verbatim}
+#!/bin/sh
+#
+# Simple shell script to make a .pem file that can be used
+# with stunnel and Bacula
+#
+OPENSSL=openssl
+ umask 77
+ PEM1="/bin/mktemp openssl.XXXXXX"
+ PEM2="/bin/mktemp openssl.XXXXXX"
+ ${OPENSSL} req -newkey rsa:1024 -keyout $PEM1 -nodes \
+ -x509 -days 365 -out $PEM2
+ cat $PEM1 > stunnel.pem
+ echo "" >>stunnel.pem
+ cat $PEM2 >>stunnel.pem
+ rm $PEM1 $PEM2
+\end{verbatim}
+\normalsize
+
+The above script will ask you a number of questions. You may simply answer
+each of them by entering a return, or if you wish you may enter your own data.
+
+
+\section{Getting a CA Signed Certificate}
+\index[general]{Certificate!Getting a CA Signed }
+\index[general]{Getting a CA Signed Certificate }
+
+The process of getting a certificate that is signed by a CA is quite a bit
+more complicated. You can purchase one from quite a number of PKI vendors, but
+that is not at all necessary for use with Bacula.
+
+To get a CA signed
+certificate, you will either need to find a friend that has setup his own CA
+or to become a CA yourself, and thus you can sign all your own certificates.
+The book OpenSSL by John Viega, Matt Mesier \& Pravir Chandra from O'Reilly
+explains how to do it, or you can read the documentation provided in the
+Open-source PKI Book project at Source Forge:
+\elink{
+http://ospkibook.sourceforge.net/docs/OSPKI-2.4.7/OSPKI-html/ospki-book.htm}
+{http://ospkibook.sourceforge.net/docs/OSPKI-2.4.7/OSPKI-html/ospki-book.htm}.
+Note, this link may change.
+
+\section{Using ssh to Secure the Communications}
+\index[general]{Communications!Using ssh to Secure the }
+\index[general]{Using ssh to Secure the Communications }
+
+Please see the script {\bf ssh-tunnel.sh} in the {\bf examples} directory. It
+was contributed by Stephan Holl.
--- /dev/null
+%%
+%%
+
+\chapter{Librairies support\'ees}
+\label{_ChapterStart21}
+\addcontentsline{toc}{section}{Librairies support\'ees}
+
+\section{Mod\`eles de librairies support\'es}
+\label{Models}
+\index[general]{Mod\`eles de librairies support\'ees}
+\index[general]{Librairies!Support\'ees}
+\addcontentsline{toc}{section}{Mod\`eles de librairies support\'es}
+
+J'h\'esite \`a qualifier ces librairies de "support\'ees", car les seules
+en ma possession et que je peux tester sont une HP SureStore DAT40X6 et
+une Overland PowerLoader LTO-2. Toutes les autres librairies cit\'ees ici
+ont \'et\'e raport\'ees comme fonctionnant avec Bacula par des utilisateurs.
+Notez que dans la colonne Capacit\'e/Slot, je pr\'ecise la capacit\'e compress\'ee
+par cartouche (ou slot).
+
+\addcontentsline{lot}{table}{Librairies connues pour fonctionner avec Bacula}
+\begin{longtable}{|p{0.6in}|p{0.8in}|p{1.9in}|p{0.8in}|p{0.5in}|p{0.75in}|}
+ \hline
+\multicolumn{1}{|c| }{\bf OS } & \multicolumn{1}{c| }{\bf Fabr. } &
+\multicolumn{1}{c| }{\bf Media } & \multicolumn{1}{c| }{\bf Mod\`ele } &
+\multicolumn{1}{c| }{\bf Slots } & \multicolumn{1}{c| }{\bf Cap/Slot } \\
+ \hline {Linux } & {Adic } & {DDS-3} & {Adic 1200G } & {12} & {-} \\
+ \hline {Linux } & {Adic } & {DLT} & {FastStore 4000 } & {7} & {20GB} \\
+ \hline {Linux } & {Adic } & {LTO-1/2, SDLT 320 } & {Adic Scalar 24 } & {24} & {100GB } \\
+ \hline {Linux } & {Adic } & {LTO-2 } & {Adic FastStor 2, Sun Storedge L8 } & {8} & {200GB } \\
+ \hline {- } & {CA-VM } & {?? } & {Tape } & {??} & {?? } \\
+ \hline {Linux} & {Dell} & {DLT VI,LTO-2} & {PowerVault 122T/132T/136T } & {-} & {100GB } \\
+ \hline {Linux } & {Dell} & {LTO-2} & {PowerVault 124T } & {-} & {200GB } \\
+ \hline {- } & {DFSMS } & {?? } & {VM RMM} & {-} & {?? } \\
+ \hline {Linux } & {Exabyte } & {VXA2 } & {VXA PacketLoader 1x10 2U } & {10} & {80/160GB } \\
+ \hline {- } & {Exabyte } & {LTO } & {Magnum 1x7 LTO Tape Auotloader } & {7} & {200/400GB } \\
+ \hline {Linux Gentoo 1.4 } & {Exabyte } & {AIT-2 } & {215A } & {15 (2 drives)} & {50GB } \\
+ \hline {Linux } & {HP } & {DDS-4 } & {SureStore DAT-40X6 } & {6 } & {40GB } \\
+ \hline {Linux } & {HP } & {Ultrium-2/LTO } & {MSL 6000/ 60030/ 5052 } & {28 } & {200/400GB } \\
+ \hline {- } & {HP } & {DLT } & {A4853 DLT } & {30} & {40/70GB } \\
+ \hline {Linux } & {HP (Compaq) } & {DLT VI } & {Compaq TL-895 } & {96+4 import export} & {35/70GB } \\
+ \hline {z/VM } & {IBM } & {?? } & {IBM Tape Manager } & {-} & {?? } \\
+ \hline {z/VM } & {IBM } & {?? } & {native tape } & {-} & {?? } \\
+ \hline {Linux } & {IBM } & {LTO } & {IBM 3581 Ultrium Tape Loader } & {7} & {200/400GB } \\
+ \hline {SuSE 9.0 } & {IBM } & {LTO } & {IBM 3581 Ultrium Tape Loader } & {7} & {200/400GB } \\
+ \hline {FreeBSD 5.4} & {IBM } & {DLT} & {IBM 3502-R14 -- rebranded ATL L-500} & {14} & {35/70GB } \\
+ \hline {Debian} & {Overland } & {LTO } & {Overland LoaderXpress LTO/DLT8000 } & {10-19} & {40-100GB } \\
+ \hline {Fedora} & {Overland } & {LTO } & {Overland PowerLoader LTO-2 } & {10-19} & {200/400GB } \\
+ \hline {FreeBSD 5.4-Stable} & {Overland} & {LTO-2} & {Overland Powerloader tape} & {17} & {100GB } \\
+ \hline {- } & {Overland} & {LTO } & {Overland Neo2000 LTO } & {26-30} & {100GB } \\
+ \hline {- } & {Quantum } & {?? } & {Super Loader } & {??} & {?? } \\
+ \hline {FreeBSD 4.9 } & {QUALSTAR TLS-4210 (Qualstar) } & {AIT1: 36GB, AIT2: 50GB all
+uncomp } & {QUALSTAR TLS-4210 } & {12} & {AIT1: 36GB, AIT2: 50GB all uncomp }\\
+ \hline {Linux } & {Skydata } & {DLT } & {ATL-L200 } & {8} & {40/80 } \\
+ \hline {- } & {Sony } & {DDS-4 } & {TSL-11000 } & {8} & {40GB } \\
+ \hline {Linux } & {Sony } & {AIT-2} & {LIB-304(SDX-500C) } & {?} & {200GB } \\
+ \hline {Linux } & {Sony } & {AIT-3} & {LIB-D81) } & {?} & {200GB } \\
+ \hline {FreeBSD 4.9-STABLE } & {Sony } & {AIT-1 } & {TSL-SA300C } & {4} & {45/70GB }\\
+ \hline {- } & {Storagetek } & {DLT } & {Timberwolf DLT } & {6} & {40/70 } \\
+ \hline {- } & {Storagetek } & {?? } & {ACSLS } & {??} & {?? } \\
+ \hline {Solaris } & {Sun } & {4mm DLT } & {Sun Desktop Archive Python 29279 } & {4} & {20GB } \\
+ \hline {Linux } & {Tandberg } & {DLT VI } & {VS 640 } & {8?} & {35/70GB } \\
+ \hline {Linux 2.6.x } & {Tandberg Data } & {SLR100 } & {SLR100 Autoloader } & {8} & {50/100GB }\\
+\hline
+
+\end{longtable}
--- /dev/null
+%%
+%%
+
+\chapter{Lecteurs de bandes support\'es}
+\label{_ChapterStart19}
+\index[general]{Lecteurs de bandes support\'es }
+\index[general]{Lecteurs!bandes support\'ees }
+\addcontentsline{toc}{section}{Lecteurs de bandes support\'es}
+
+M\^eme si votre lecteur est dans la liste ci dessous, v\'erifiez le
+\ilink{Chapitre Test des Lecteurs Bandes}{btape1} de ce manuel
+pour les proc\'edures que vous pouvez utiliser pour v\'erifier si votre
+lecteur de bandes est susceptible de fonctionner avec Bacula.
+Si votre lecteur est en mode bloc
+fixe, il peut para\^itre fonctionner avec Bacula jusqu'\`a ce que vous essayiez de
+restaurer et que Bacula tente de se positionner sur la bande. Seuls la
+proc\'edure ci-dessus et vos propres tests peuvent vous garantir un
+fonctionnement correct.
+
+Il est tr\`es difficile de fournir une liste de lecteurs de bandes
+support\'es, ou de lecteurs qui sont connus pour fonctionner avec Bacula en
+raison du peu de retours de la part des usagers. (par cons\'equent, si vous
+utilisez Bacula sur un lecteur qui ne figure pas dans la liste, merci de nous
+le faire savoir). Selon les informations provenant de nos utilisateurs, les
+lecteurs suivants sont connus pour fonctionner avec Bacula. Un trait d'union
+dans une colonne signifie "inconnu" :
+
+\begin{longtable}{|l|l|l|l|l|}
+ \hline
+\multicolumn{1}{|c| }{\bf OS } & \multicolumn{1}{c| }{\bf Fabr. } &
+\multicolumn{1}{c| }{\bf Media } & \multicolumn{1}{c| }{\bf Mod\`ele } &
+\multicolumn{1}{c| }{\bf Capacit\'e } \\
+ \hline
+{- } & {ADIC } & {DLT } & {Adic Scalar 100 DLT } & {100GB } \\
+ \hline
+{- } & {ADIC } & {DLT } & {Adic Fastor 22 DLT } & {- } \\
+ \hline
+{- } & {- } & {DDS } & {Compaq DDS 2,3,4 } & {- } \\
+ \hline
+{- } & {Exabyte } & {- } & {Lecteurs Exabyte de moins de dix ans } & {-
+} \\
+ \hline
+{- } & {Exabyte } & {- } & {Exabyte VXA drives } & {- } \\
+ \hline
+{- } & {HP } & {Travan 4 } & {Colorado T4000S } & {- } \\
+ \hline
+{- } & {HP } & {DLT } & {HP DLT drives } & {- } \\
+ \hline
+{- } & {HP } & {LTO } & {HP LTO Ultrium drives } & {- } \\
+ \hline
+{FreeBSD 4.10 RELEASE } & {HP } & {DAT } & {HP StorageWorks DAT72i } & {-
+} \\
+ \hline
+{- } & {Overland } & {LTO } & {LoaderXpress LTO } & {- } \\
+ \hline
+{- } & {Overland } & {- } & {Neo2000 } & {- } \\
+ \hline
+{- } & {OnStream } & {- } & {OnStream drives (see below) } & {- } \\
+ \hline
+{- } & {Quantum } & {DLT } & {DLT-8000 } & {40/80GB } \\
+ \hline
+{Linux } & {Seagate } & {DDS-4 } & {Scorpio 40 } & {20/40GB } \\
+ \hline
+{FreeBSD 4.9 STABLE } & {Seagate } & {DDS-4 } & {STA2401LW } & {20/40GB }
+\\
+ \hline
+{FreeBSD 5.2.1 pthreads patched RELEASE } & {Seagate } & {AIT-1 } &
+{STA1701W } & {35/70GB } \\
+ \hline
+{Linux } & {Sony } & {DDS-2,3,4 } & {- } & {4-40GB } \\
+ \hline
+{Linux } & {Tandberg } & {- } & {Tandbert MLR3 } & {- } \\
+ \hline
+{FreeBSD } & {Tandberg } & {- } & {Tandberg SLR6 } & {- } \\
+ \hline
+{Solaris } & {Tandberg } & {- } & {Tandberg SLR75 } & {- } \\
+ \hline
+{Linux Gentoo } & {ADIC } & {- } & {IBM Ultrium LTO I } & {100/200 Go }
+\\ \hline
+
+\end{longtable}
+
+Une liste des
+\ilink{Librarires support\'ees}{Models} figure dans le
+\ilink{chapitre librairies (autochangers)}{_ChapterStart} de
+ce document, o\`u vous trouverez d'autres lecteurs de bandes qui fonctionnent avec
+Bacula.
+
+\section{Lecteurs de bande non support\'es}
+\label{UnSupportedDrives}
+\index[general]{Lecteurs de bande non support\'es }
+\addcontentsline{toc}{section}{Lecteurs de bande non support\'es}
+
+Auparavant les lecteurs de bandes OnStream IDE-SCSI ne fonctionnaient pas avec
+Bacula. A partir de la version 1.33 de Bacula et de la version 0.9.14 du
+pilote noyau ou sup\'erieur,ce lecteur est support\'e. Consultez le chapitre
+de test car vous devez le configurer pour fonctionner en mode blocs de taille
+fixe.
+
+Les lecteurs QIC sont connus pour avoir nombre de particularit\'es (taille de
+blocs fixe, et un EOF plut\^ot que deux pour terminer la bande). En
+cons\'equence, vous devrez \^etre particuli\`erement attentif \`a sa
+configuration pour le faire fonctionner avec Bacula.
+
+\section{A l'attention des utilisateurs de FreeBSD !!!}
+\index[general]{L'attention des utilisateurs de FreeBSD }
+\index[general]{FreeBSD!l'attention des utilisateurs de }
+\addcontentsline{toc}{section}{l'attention des utilisateurs de FreeBSD !!!}
+
+A moins que vous n'ayez appliqu\'e un correctif sur la biblioth\`eque pthreads
+de votre syst\`eme FreeBSD, vous perdrez des donn\'ees quand Bacula aura
+rempli une bande et passera \`a la suivante. La raison en est que les
+biblioth\`eques pthreads sans correctifs \'echouent \`a retourner un \'etat
+d'alerte \`a Bacula signalant que la fin de bande est proche. Consultez le
+\ilink{chapitre test des lecteurs de bandes}{FreeBSDTapes} de
+ce manuel pour d'importantes informations concernant la configuration de votre
+lecteur de bande pour qu'il soit compatible avec {\bf Bacula}.
+
+\section{Librairiess support\'ees}
+\index[general]{Librairiess support\'ees }
+\addcontentsline{toc}{section}{Librairies support\'ees}
+
+Pour des informations sur les libraries (autochangeurs) support\'ees, allez
+voir la section
+\ilink{Libraries connues pour fonctionner avec Bacula}{Models} du chapitre
+Librairies support\'ees de ce manuel.
+
+\section{Sp\'ecifications des cartouches}
+\index[general]{Sp\'ecifications!Cartouches}
+\index[general]{Cartouches Sp\'ecifications}
+\addcontentsline{toc}{section}{Sp\'ecifications des cartouches}
+Nous ne pouvons vraiment pas vous dire quel lecteur acheter pour utiliser Bacula.
+Cependant, nous pouvons recommander d'\'eviter les lecteurs DDS. La
+technologie est plut\^ot ancienne et ces lecteurs n\'ecessitent de fr\'equents
+nettoyages. Les lecteurs DLT sont g\'en\'eralement bien meilleurs (technologie
+plus r\'ecente) et ne requi\`erent pas autant d'op\'erations de nettoyage.
+
+Ci-dessous, vous trouverez une table de sp\'ecifications de cartouches DLT et LTO
+qui vous permettra de vous faire une id\'ee de la capacit\'e et de la rapidit\'e des
+lecteurs et cartouches modernes. Les capacit\'es report\'ees ici sont les natives,
+sans compression. Tous les lecteurs modernes pratiquent la compression
+mat\'erielle, et les fabricants affichent souvent une capacit\'e compress\'ee avec un
+ratio de 2:1. Le facteur de compression r\'eel d\'epend principalement des donn\'ees
+sauvegard\'ees, mais je pense qu'un ratio 1,5:1 est beaucoup plus raisonnable
+(autrement dit, multipliez la valeur de la table par 1,5 pour obtenir une
+estimation grossi\`ere de la capacit\'e compress\'ee). Les taux de transfert sont
+arrondis au GB/hr le plus proche. Les valeurs sont fournies par les divers
+fabricants.
+
+Le type de media est la d\'esignation du fabricant, vous n'\^etes pas oblig\'e de
+l'utiliser (mais vous devriez...) dans vos ressources de configuration Bacula.
+
+
+\begin{tabular}{|c|c|c|c}
+Type de media & Type de lecteur & Capacit\'e des media & Taux de transfert \\ \hline
+DDS-1 & DAT & 2 GB & ?? GB/hr \\ \hline
+DDS-2 & DAT & 4 GB & ?? GB/hr \\ \hline
+DDS-3 & DAT & 12 GB & 5.4 GB/hr \\ \hline
+Travan 40 & Travan & 20 GB & ?? GB/hr \\ \hline
+DDS-4 & DAT & 20 GB & 11 GB/hr \\ \hline
+VXA-1 & Exabyte & 33 GB & 11 GB/hr \\ \hline
+DAT-72 & DAT & 36 GB & 13 GB/hr \\ \hline
+DLT IV & DLT8000 & 40 GB & 22 GB/hr \\ \hline
+VXA-2 & Exabyte & 80 GB & 22 GB/hr \\ \hline
+Half-high Ultrum 1 & LTO 1 & 100 GB & 27 GB/hr \\ \hline
+Ultrium 1 & LTO 1 & 100 GB & 54 GB/hr \\ \hline
+Super DLT 1 & SDLT 220 & 110 GB & 40 GB/hr \\ \hline
+VXA-3 & Exabyte & 160 GB & 43 GB/hr \\ \hline
+Super DLT I & SDLT 320 & 160 GB & 58 GB/hr \\ \hline
+Ultrium 2 & LTO 2 & 200 GB & 108 GB/hr \\ \hline
+Super DLT II & SDLT 600 & 300 GB & 127 GB/hr \\ \hline
+VXA-4 & Exabyte & 320 GB & 86 GB/hr \\ \hline
+Ultrium 3 & LTO 3 & 400 GB & 216 GB/hr \\ \hline
+\end{tabular}
--- /dev/null
+%%
+%%
+
+\chapter{Syst\`emes d'exploitation support\'es}
+\label{SupportedOSes}
+\index[general]{Syst\`emes d'exploitation support\'es }
+
+\begin{itemize}
+\item Syst\`emes Linux (compil\'e et test\'e sur RedHat Enterprise Linux
+ 3.0).
+\item Si vous avez un syst\`eme Red Hat r\'ecent ex\'ecutant le noyau 2.4.x
+ et si vous avez le r\'epertoire {\bf /lib/tls} install\'e sur votre
+ syst\`eme (par d\'efaut normalement), {\bf Bacula ne fonctionnera pas
+ correctement} Ceci est d\^u \`a la nouvelle biblioth\`eque pthreads qui est
+ d\'efectueuse. Vous devez supprimer ce r\'epertoire avant d'ex\'ecuter
+ Bacula, ou vous pouvez simplement le renommer en {\bf /lib/tls-broken} puis
+ red\'emarrer votre machine (une des rares occasions o\`u; Linux doit \^etre
+ red\'emarr\'e). Si vous ne souhaitez pas d\'eplacer/renommer /lib/tls, une
+ autre alternative est de placer la variable d'environnement
+ ``LD\_ASSUME\_KERNEL=2.4.19'' avant d'ex\'ecuter Bacula. Pour cette option,
+ vous n'avez pas besoin de red\'emarrer, et tous les programmes autres que
+ {\bf Bacula} continueront d'utiliser {\bf /lib/tls}.
+
+ Le probl\`eme n'existe pas sur les noyaux 2.6.
+
+\item La plupart des distributions Linux les plus courantes (Gentoo, SuSE, Mandriva, Debian,
+ ...).
+\item Diff\'erentes versions de Solaris.
+\item FreeBSD (pilote de bande support\'e \`a partir de la version 1.30 --
+ allez voir les consid\'erations {\bf importantes} dans la section
+ \ilink{Configuration des lecteurs de bandes sur FreeBSD}{FreeBSDTapes}
+ du chapitre Test des Bandes de ce manuel.)
+\item Windows (Win98/Me, WinNT/2K/XP) clients binaires ({\bf File Daemon}).
+\item MacOS X/Darwin (voir
+ \elink{ http://fink.sourceforge.net/}{http://fink.sourceforge.net/} pour
+ obtenir les paquets)
+\item OpenBSD Client ({\bf File Daemon}).
+\item Irix Client ({\bf File Daemon}).
+\item Tru64
+\item {\bf Bacula} est r\'eput\'e fonctionner sur d'autres syst\`emes (AIX,
+ BSDI, HPUX, ...) mais nous ne les avons pas test\'e personnellement.
+\item RHat 7.2 AS2, AS3, AS4, Fedora Core 2, SuSE SLES 7,8,9, Debian Woody et Sarge Linux sur
+ S/390 et Linux sur zSeries.
+\item Voir le chapitre de Portage de la Documentation Pour Developpeurs pour
+ les informations concernant le portage sur d'autres syst\`emes.
+\end{itemize}
--- /dev/null
+%%
+%%
+
+\chapter{Thanks}
+\label{ThanksChapter}
+\index[general]{Thanks }
+I thank everyone who has helped this project. Unfortunately, I cannot
+thank everyone (bad memory). However, the AUTHORS file in the main source
+code directory should include the names of all persons who have contributed
+to the Bacula project. Just the same, I would like to include thanks below
+to special contributors as well as to the major contributors to the current
+release.
+
+Thanks to Richard Stallman for starting the Free Software movement and for
+bringing us gcc and all the other GNU tools as well as the GPL license.
+
+Thanks to Linus Torvalds for bringing us Linux.
+
+Thanks to all the Free Software programmers. Without being able to peek at
+your code, and in some cases, take parts of it, this project would have been
+much more difficult.
+
+Thanks to John Walker for suggesting this project, giving it a name,
+contributing software he has written, and for his programming efforts on
+Bacula as well as having acted as a constant sounding board and source of
+ideas.
+
+Thanks to the apcupsd project where I started my Free Software efforts, and
+from which I was able to borrow some ideas and code that I had written.
+
+Special thanks to D. Scott Barninger for writing the bacula RPM spec file,
+building all the RPM files and loading them onto Source Forge. This has been a
+tremendous help.
+
+Many thanks to Karl Cunningham for converting the manual from html format to
+LaTeX. It was a major effort flawlessly done that will benefit the Bacula
+users for many years to come. Thanks Karl.
+
+Thanks to Dan Langille for the {\bf incredible} amount of testing he did on
+FreeBSD. His perseverance is truly remarkable. Thanks also for the many
+contributions he has made to improve Bacula (pthreads patch for FreeBSD,
+improved start/stop script and addition of Bacula userid and group, stunnel,
+...), his continuing support of Bacula users. He also wrote the PostgreSQL
+driver for Bacula and has been a big help in correcting the SQL.
+
+Thanks to multiple other Bacula Packagers who make and release packages for
+different platforms for Bacula.
+
+Thanks to Christopher Hull for developing the native Win32 Bacula emulation
+code and for contributing it to the Bacula project.
+
+Thanks to Robert Nelson for bringing our Win32 implementation up to par
+with all the same features that exist in the Unix/Linux versions. In
+addition, he has ported the Director and Storage daemon to Win32!
+
+Thanks to Thorsten Engel for his excellent knowledge of Win32 systems, and
+for making the Win32 File daemon Unicode compatible, as well as making
+the Win32 File daemon interface to Microsoft's Volume Shadow Copy (VSS).
+These two are big pluses for Bacula!
+
+Thanks to Landon Fuller for writing both the communications and the
+data encryption code for Bacula.
+
+Thanks to Arno Lehmann for his excellent and infatigable help and advice
+to users.
+
+Thanks to all the Bacula users, especially those of you who have contributed
+ideas, bug reports, patches, and new features.
+
+Bacula can be enabled with data encryption and/or communications
+encryption. If this is the case, you will be including OpenSSL code that
+that contains cryptographic software written by Eric Young
+(eay@cryptsoft.com) and also software written by Tim Hudson
+(tjh@cryptsoft.com).
+
+The Bat (Bacula Administration Tool) graphs are based in part on the work
+of the Qwt project (http://qwt.sf.net).
+
+The original variable expansion code used in the LabelFormat comes from the
+Open Source Software Project (www.ossp.org). It has been adapted and extended
+for use in Bacula. This code is now deprecated.
+
+There have been numerous people over the years who have contributed ideas,
+code, and help to the Bacula project. The file AUTHORS in the main source
+release file contains a list of contributors. For all those who I have
+left out, please send me a reminder, and in any case, thanks for your
+contribution.
+
+Thanks to the Free Software Foundation Europe e.V. for assuming the
+responsibilities of protecting the Bacula copyright.
+
+% TODO: remove this from the book?
+\section*{Copyrights and Trademarks}
+\index[general]{Trademarks!Copyrights and }
+\index[general]{Copyrights and Trademarks }
+
+Certain words and/or products are Copyrighted or Trademarked such as Windows
+(by Microsoft). Since they are numerous, and we are not necessarily aware of
+the details of each, we don't try to list them here. However, we acknowledge
+all such Copyrights and Trademarks, and if any copyright or trademark holder
+wishes a specific acknowledgment, notify us, and we will be happy to add it
+where appropriate.
--- /dev/null
+
+\chapter{Bacula TLS -- Communications Encryption}
+\label{CommEncryption}
+\index[general]{TLS -- Communications Encryption}
+\index[general]{Communications Encryption}
+\index[general]{Encryption!Communications}
+\index[general]{Encryption!Transport}
+\index[general]{Transport Encryption}
+\index[general]{TLS}
+
+Bacula TLS (Transport Layer Security) is built-in network
+encryption code to provide secure network transport similar to
+that offered by {\bf stunnel} or {\bf ssh}. The data written to
+Volumes by the Storage daemon is not encrypted by this code.
+For data encryption, please see the \ilink{Data Encryption
+Chapter}{DataEncryption} of this manual.
+
+The Bacula encryption implementations were written by Landon Fuller.
+
+Supported features of this code include:
+\begin{itemize}
+\item Client/Server TLS Requirement Negotiation
+\item TLSv1 Connections with Server and Client Certificate
+Validation
+\item Forward Secrecy Support via Diffie-Hellman Ephemeral Keying
+\end{itemize}
+
+This document will refer to both "server" and "client" contexts. These
+terms refer to the accepting and initiating peer, respectively.
+
+Diffie-Hellman anonymous ciphers are not supported by this code. The
+use of DH anonymous ciphers increases the code complexity and places
+explicit trust upon the two-way CRAM-MD5 implementation. CRAM-MD5 is
+subject to known plaintext attacks, and it should be considered
+considerably less secure than PKI certificate-based authentication.
+
+Appropriate autoconf macros have been added to detect and use OpenSSL
+if enabled on the {\bf ./configure} line with {\bf \verb?--?with-openssl}
+
+\section{TLS Configuration Directives}
+Additional configuration directives have been added to all the daemons
+(Director, File daemon, and Storage daemon) as well as the various
+different Console programs.
+These new directives are defined as follows:
+
+\begin{description}
+\item [TLS Enable = \lt{}yes|no\gt{}]
+Enable TLS support. If TLS is not enabled, none of the other TLS directives
+have any effect. In other words, even if you set {\bf TLS Require = yes}
+you need to have TLS enabled or TLS will not be used.
+
+\item [TLS Require = \lt{}yes|no\gt{}]
+Require TLS connections. This directive is ignored unless {\bf TLS Enable}
+is set to {\bf yes}. If TLS is not required, and TLS is enabled, then
+Bacula will connect with other daemons either with or without TLS depending
+on what the other daemon requests. If TLS is enabled and TLS is required,
+then Bacula will refuse any connection that does not use TLS.
+
+\item [TLS Certificate = \lt{}Filename\gt{}]
+The full path and filename of a PEM encoded TLS certificate. It can be
+used as either a client or server certificate. PEM stands for Privacy
+Enhanced Mail, but in this context refers to how the certificates are
+encoded. It is used because PEM files are base64 encoded and hence ASCII
+text based rather than binary. They may also contain encrypted
+information.
+
+\item [TLS Key = \lt{}Filename\gt{}]
+The full path and filename of a PEM encoded TLS private key. It must
+correspond to the TLS certificate.
+
+\item [TLS Verify Peer = \lt{}yes|no\gt{}]
+Verify peer certificate. Instructs server to request and verify the
+client's x509 certificate. Any client certificate signed by a known-CA
+will be accepted unless the TLS Allowed CN configuration directive is used,
+in which case the client certificate must correspond to the Allowed
+Common Name specified. This directive is valid only for a server
+and not in a client context.
+
+\item [TLS Allowed CN = \lt{}string list\gt{}]
+Common name attribute of allowed peer certificates. If this directive is
+specified, all server certificates will be verified against this list. This
+can be used to ensure that only the CA-approved Director may connect.
+This directive may be specified more than once.
+
+\item [TLS CA Certificate File = \lt{}Filename\gt{}]
+The full path and filename specifying a
+PEM encoded TLS CA certificate(s). Multiple certificates are
+permitted in the file. One of \emph{TLS CA Certificate File} or \emph{TLS
+CA Certificate Dir} are required in a server context if \emph{TLS
+Verify Peer} (see above) is also specified, and are always required in a client
+context.
+
+\item [TLS CA Certificate Dir = \lt{}Directory\gt{}]
+Full path to TLS CA certificate directory. In the current implementation,
+certificates must be stored PEM encoded with OpenSSL-compatible hashes,
+which is the subject name's hash and an extension of {bf .0}.
+One of \emph{TLS CA Certificate File} or \emph{TLS CA Certificate Dir} are
+required in a server context if \emph{TLS Verify Peer} is also specified,
+and are always required in a client context.
+
+\item [TLS DH File = \lt{}Directory\gt{}]
+Path to PEM encoded Diffie-Hellman parameter file. If this directive is
+specified, DH key exchange will be used for the ephemeral keying, allowing
+for forward secrecy of communications. DH key exchange adds an additional
+level of security because the key used for encryption/decryption by the
+server and the client is computed on each end and thus is never passed over
+the network if Diffie-Hellman key exchange is used. Even if DH key
+exchange is not used, the encryption/decryption key is always passed
+encrypted. This directive is only valid within a server context.
+
+To generate the parameter file, you
+may use openssl:
+
+\begin{verbatim}
+ openssl dhparam -out dh1024.pem -5 1024
+\end{verbatim}
+
+\end{description}
+
+\section{Creating a Self-signed Certificate}
+\index[general]{Creating a Self-signed Certificate }
+\index[general]{Certificate!Creating a Self-signed }
+
+You may create a self-signed certificate for use with the Bacula TLS that
+will permit you to make it function, but will not allow certificate
+validation. The .pem file containing both the certificate and the key
+valid for ten years can be made with the following:
+
+\footnotesize
+\begin{verbatim}
+ openssl req -new -x509 -nodes -out bacula.pem -keyout bacula.pem -days 3650
+\end{verbatim}
+\normalsize
+
+The above script will ask you a number of questions. You may simply answer
+each of them by entering a return, or if you wish you may enter your own data.
+
+Note, however, that self-signed certificates will only work for the
+outgoing end of connections. For example, in the case of the Director
+making a connection to a File Daemon, the File Daemon may be configured to
+allow self-signed certificates, but the certificate used by the
+Director must be signed by a certificate that is explicitly trusted on the
+File Daemon end.
+
+This is necessary to prevent ``man in the middle'' attacks from tools such
+as \elink{ettercap}{http://ettercap.sourceforge.net/}. Essentially, if the
+Director does not verify that it is talking to a trusted remote endpoint,
+it can be tricked into talking to a malicious 3rd party who is relaying and
+capturing all traffic by presenting its own certificates to the Director
+and File Daemons. The only way to prevent this is by using trusted
+certificates, so that the man in the middle is incapable of spoofing the
+connection using his own.
+
+To get a trusted certificate (CA or Certificate Authority signed
+certificate), you will either need to purchase certificates signed by a
+commercial CA or find a friend that has setup his own CA or become a CA
+yourself, and thus you can sign all your own certificates. The book
+OpenSSL by John Viega, Matt Mesier \& Pravir Chandra from O'Reilly explains
+how to do it, or you can read the documentation provided in the Open-source
+PKI Book project at Source Forge: \elink{
+http://ospkibook.sourceforge.net/docs/OSPKI-2.4.7/OSPKI-html/ospki-book.htm}
+{http://ospkibook.sourceforge.net/docs/OSPKI-2.4.7/OSPKI-html/ospki-book.htm}.
+Note, this link may change.
+
+The program TinyCA has a very nice Graphical User Interface
+that allows you to easily setup and maintain your own CA.
+TinyCA can be found at
+\elink{http://tinyca.sm-zone.net/}{http://tinyca.sm-zone.net/}.
+
+
+\section{Getting a CA Signed Certificate}
+\index[general]{Certificate!Getting a CA Signed }
+\index[general]{Getting a CA Signed Certificate }
+
+The process of getting a certificate that is signed by a CA is quite a bit
+more complicated. You can purchase one from quite a number of PKI vendors, but
+that is not at all necessary for use with Bacula. To get a CA signed
+certificate, you will either need to find a friend that has setup his own CA
+or to become a CA yourself, and thus you can sign all your own certificates.
+The book OpenSSL by John Viega, Matt Mesier \& Pravir Chandra from O'Reilly
+explains how to do it, or you can read the documentation provided in the
+Open-source PKI Book project at Source Forge:
+\elink{
+http://ospkibook.sourceforge.net/docs/OSPKI-2.4.7/OSPKI-html/ospki-book.htm}
+{http://ospkibook.sourceforge.net/docs/OSPKI-2.4.7/OSPKI-html/ospki-book.htm}.
+Note, this link may change.
+
+\section{Example TLS Configuration Files}
+\index[general]{Example!TLS Configuration Files}
+\index[general]{TLS Configuration Files}
+
+Landon has supplied us with the TLS portions of his configuration
+files, which should help you setting up your own. Note, this example
+shows the directives necessary for a Director to Storage daemon session.
+The technique is the same between the Director and the Client and
+for bconsole to the Director.
+
+{\bf bacula-dir.conf}
+\footnotesize
+\begin{verbatim}
+ Director { # define myself
+ Name = backup1-dir
+ ...
+ TLS Enable = yes
+ TLS Require = yes
+ TLS Verify Peer = yes
+ TLS Allowed CN = "bacula@backup1.example.com"
+ TLS Allowed CN = "administrator@example.com"
+ TLS CA Certificate File = /usr/local/etc/ssl/ca.pem
+ # This is a server certificate, used for incoming
+ # console connections.
+ TLS Certificate = /usr/local/etc/ssl/backup1/cert.pem
+ TLS Key = /usr/local/etc/ssl/backup1/key.pem
+ }
+
+ Storage {
+ Name = File
+ Address = backup1.example.com
+ ...
+ TLS Require = yes
+ TLS CA Certificate File = /usr/local/etc/ssl/ca.pem
+ # This is a client certificate, used by the director to
+ # connect to the storage daemon
+ TLS Certificate = /usr/local/etc/ssl/bacula@backup1/cert.pem
+ TLS Key = /usr/local/etc/ssl/bacula@backup1/key.pem
+ }
+
+ Client {
+ Name = backup1-fd
+ Address = server1.example.com
+ ...
+
+ TLS Enable = yes
+ TLS Require = yes
+ TLS CA Certificate File = /usr/local/etc/ssl/ca.pem
+ }
+
+\end{verbatim}
+\normalsize
+
+{\bf bacula-fd.conf}
+\footnotesize
+\begin{verbatim}
+ Director {
+ Name = backup1-dir
+ ...
+ TLS Enable = yes
+ TLS Require = yes
+ TLS Verify Peer = yes
+ # Allow only the Director to connect
+ TLS Allowed CN = "bacula@backup1.example.com"
+ TLS CA Certificate File = /usr/local/etc/ssl/ca.pem
+ # This is a server certificate. It is used by connecting
+ # directors to verify the authenticity of this file daemon
+ TLS Certificate = /usr/local/etc/ssl/server1/cert.pem
+ TLS Key = /usr/local/etc/ssl/server1/key.pem
+ }
+
+ FileDaemon {
+ Name = backup1-fd
+ ...
+ # you need these TLS entries so the SD and FD can
+ # communicate
+ TLS Enable = yes
+ TLS Require = yes
+
+ TLS CA Certificate File = /usr/local/etc/ssl/ca.pem
+ TLS Certificate = /usr/local/etc/ssl/server1/cert.pem
+ TLS Key = /usr/local/etc/ssl/server1/key.pem
+}
+\end{verbatim}
+\normalsize
+
+{\bf bacula-sd.conf}
+\footnotesize
+\begin{verbatim}
+ Storage { # definition of myself
+ Name = backup1-sd
+ ...
+ # These TLS configuration options are used for incoming
+ # file daemon connections. Director TLS settings are handled
+ # below.
+ TLS Enable = yes
+ TLS Require = yes
+ # Peer certificate is not required/requested -- peer validity
+ # is verified by the storage connection cookie provided to the
+ # File Daemon by the director.
+ TLS Verify Peer = no
+ TLS CA Certificate File = /usr/local/etc/ssl/ca.pem
+ # This is a server certificate. It is used by connecting
+ # file daemons to verify the authenticity of this storage daemon
+ TLS Certificate = /usr/local/etc/ssl/backup1/cert.pem
+ TLS Key = /usr/local/etc/ssl/backup1/key.pem
+ }
+
+ #
+ # List Directors who are permitted to contact Storage daemon
+ #
+ Director {
+ Name = backup1-dir
+ ...
+ TLS Enable = yes
+ TLS Require = yes
+ # Require the connecting director to provide a certificate
+ # with the matching CN.
+ TLS Verify Peer = yes
+ TLS Allowed CN = "bacula@backup1.example.com"
+ TLS CA Certificate File = /usr/local/etc/ssl/ca.pem
+ # This is a server certificate. It is used by the connecting
+ # director to verify the authenticity of this storage daemon
+ TLS Certificate = /usr/local/etc/ssl/backup1/cert.pem
+ TLS Key = /usr/local/etc/ssl/backup1/key.pem
+ }
+\end{verbatim}
+\normalsize
--- /dev/null
+#!/usr/bin/perl -w
+#
+use strict;
+
+# Used to change the names of the image files generated by latex2html from imgxx.png
+# to meaningful names. Provision is made to go either from or to the meaningful names.
+# The meaningful names are obtained from a file called imagename_translations, which
+# is generated by extensions to latex2html in the make_image_file subroutine in
+# bacula.perl.
+
+# Opens the file imagename_translations and reads the contents into a hash.
+# The hash is creaed with the imgxx.png files as the key if processing TO
+# meaningful filenames, and with the meaningful filenames as the key if
+# processing FROM meaningful filenames.
+# Then opens the html file(s) indicated in the command-line arguments and
+# changes all image references according to the translations described in the
+# above file. Finally, it renames the image files.
+#
+# Original creation: 3-27-05 by Karl Cunningham.
+# Modified 5-21-05 to go FROM and TO meaningful filenames.
+#
+my $TRANSFILE = "imagename_translations";
+my $path;
+
+# Loads the contents of $TRANSFILE file into the hash referenced in the first
+# argument. The hash is loaded to translate old to new if $direction is 0,
+# otherwise it is loaded to translate new to old. In this context, the
+# 'old' filename is the meaningful name, and the 'new' filename is the
+# imgxx.png filename. It is assumed that the old image is the one that
+# latex2html has used as the source to create the imgxx.png filename.
+# The filename extension is taken from the file
+sub read_transfile {
+ my ($trans,$direction) = @_;
+
+ if (!open IN,"<$path$TRANSFILE") {
+ print "WARNING: Cannot open image translation file $path$TRANSFILE for reading\n";
+ print " Image filename translation aborted\n\n";
+ exit 0;
+ }
+
+ while (<IN>) {
+ chomp;
+ my ($new,$old) = split(/\001/);
+
+ # Old filenames will usually have a leading ./ which we don't need.
+ $old =~ s/^\.\///;
+
+ # The filename extension of the old filename must be made to match
+ # the new filename because it indicates the encoding format of the image.
+ my ($ext) = $new =~ /(\.[^\.]*)$/;
+ $old =~ s/\.[^\.]*$/$ext/;
+ if ($direction == 0) {
+ $trans->{$new} = $old;
+ } else {
+ $trans->{$old} = $new;
+ }
+ }
+ close IN;
+}
+
+# Translates the image names in the file given as the first argument, according to
+# the translations in the hash that is given as the second argument.
+# The file contents are read in entirely into a string, the string is processed, and
+# the file contents are then written. No particular care is taken to ensure that the
+# file is not lost if a system failure occurs at an inopportune time. It is assumed
+# that the html files being processed here can be recreated on demand.
+#
+# Links to other files are added to the %filelist for processing. That way,
+# all linked files will be processed (assuming they are local).
+sub translate_html {
+ my ($filename,$trans,$filelist) = @_;
+ my ($contents,$out,$this,$img,$dest);
+ my $cnt = 0;
+
+ # If the filename is an external link ignore it. And drop any file:// from
+ # the filename.
+ $filename =~ /^(http|ftp|mailto)\:/ and return 0;
+ $filename =~ s/^file\:\/\///;
+ # Load the contents of the html file.
+ if (!open IF,"<$path$filename") {
+ print "WARNING: Cannot open $path$filename for reading\n";
+ print " Image Filename Translation aborted\n\n";
+ exit 0;
+ }
+
+ while (<IF>) {
+ $contents .= $_;
+ }
+ close IF;
+
+ # Now do the translation...
+ # First, search for an image filename.
+ while ($contents =~ /\<\s*IMG[^\>]*SRC=\"/si) {
+ $contents = $';
+ $out .= $` . $&;
+
+ # The next thing is an image name. Get it and translate it.
+ $contents =~ /^(.*?)\"/s;
+ $contents = $';
+ $this = $&;
+ $img = $1;
+ # If the image is in our list of ones to be translated, do it
+ # and feed the result to the output.
+ $cnt += $this =~ s/$img/$trans->{$img}/ if (defined($trans->{$img}));
+ $out .= $this;
+ }
+ $out .= $contents;
+
+ # Now send the translated text to the html file, overwriting what's there.
+ open OF,">$path$filename" or die "Cannot open $path$filename for writing\n";
+ print OF $out;
+ close OF;
+
+ # Now look for any links to other files and add them to the list of files to do.
+ while ($out =~ /\<\s*A[^\>]*HREF=\"(.*?)\"/si) {
+ $out = $';
+ $dest = $1;
+ # Drop an # and anything after it.
+ $dest =~ s/\#.*//;
+ $filelist->{$dest} = '' if $dest;
+ }
+ return $cnt;
+}
+
+# REnames the image files spefified in the %translate hash.
+sub rename_images {
+ my $translate = shift;
+ my ($response);
+
+ foreach (keys(%$translate)) {
+ if (! $translate->{$_}) {
+ print " WARNING: No destination Filename for $_\n";
+ } else {
+ $response = `mv -f $path$_ $path$translate->{$_} 2>&1`;
+ $response and print "ERROR from system $response\n";
+ }
+ }
+}
+
+#################################################
+############# MAIN #############################
+################################################
+
+# %filelist starts out with keys from the @ARGV list. As files are processed,
+# any links to other files are added to the %filelist. A hash of processed
+# files is kept so we don't do any twice.
+
+# The first argument must be either --to_meaningful_names or --from_meaningful_names
+
+my (%translate,$search_regex,%filelist,%completed,$thisfile);
+my ($cnt,$direction);
+
+my $arg0 = shift(@ARGV);
+$arg0 =~ /^(--to_meaningful_names|--from_meaningful_names)$/ or
+ die "ERROR: First argument must be either \'--to_meaningful_names\' or \'--from_meaningful_names\'\n";
+
+$direction = ($arg0 eq '--to_meaningful_names') ? 0 : 1;
+
+(@ARGV) or die "ERROR: Filename(s) to process must be given as arguments\n";
+
+# Use the first argument to get the path to the file of translations.
+my $tmp = $ARGV[0];
+($path) = $tmp =~ /(.*\/)/;
+$path = '' unless $path;
+
+read_transfile(\%translate,$direction);
+
+foreach (@ARGV) {
+ # Strip the path from the filename, and use it later on.
+ if (s/(.*\/)//) {
+ $path = $1;
+ } else {
+ $path = '';
+ }
+ $filelist{$_} = '';
+
+ while ($thisfile = (keys(%filelist))[0]) {
+ $cnt += translate_html($thisfile,\%translate,\%filelist) if (!exists($completed{$thisfile}));
+ delete($filelist{$thisfile});
+ $completed{$thisfile} = '';
+ }
+ print "translate_images.pl: $cnt image filenames translated ",($direction)?"from":"to"," meaningful names\n";
+}
+
+rename_images(\%translate);
--- /dev/null
+%%
+%%
+
+\chapter{Une br\`eve documentation}
+\label{_ChapterStart1}
+\index[general]{Une br\`eve documentation}
+\index[general]{Documentation!br\`eve }
+
+Ce chapitre vous guidera \`a travers les \'etapes n\'ecessaires pour ex\'ecuter Bacula.
+Pour cela, nous supposons que vous avez install\'e Bacula, peut \^etre dans un simple
+r\'epertoire comme le d\'ecrit le chapitre pr\'ec\'edent, auquel cas vous pouvez ex\'ecuter
+Bacula sans \^etre root pour ces tests. Nous supposons d'autre part que vous n'avez
+pas modifi\'e les fichiers de configuration. Dans le cas contraire, nous vous
+recommandons de d\'esinstaller Bacula et de le r\'einstaller sans rien modifier. Les
+exemples de ce chapitre utilisent les fichiers de configuration par d\'efaut, et
+cr\'eent les volumes dans le r\'epertoire {\bf /tmp} de votre disque. De plus, les
+donn\'ees sauvegard\'ees seront celle du r\'epertoire des sources de Bacula o\`u vous
+l'avez compil\'e. Par cons\'equent, tous les {\it daemons} peuvent \^etre ex\'ecut\'es
+sans les droits root pour ces tests. Notez bien qu'en production, vos File
+Daemons devront \^etre ex\'ecut\'es en tant que root. Voyez le chapitre sur la
+s\'ecurit\'e pour plus d'informations sur ce sujet.
+
+Voici les \'etapes que nous suivrons :
+
+\begin{enumerate}
+\item cd \lt{}install-directory\gt{}
+\item D\'emarrer la base de donn\'ees (si vous utilisez MySQL ou PostgreSQL)
+\item D\'emarrer les {\it daemons} avec {\bf ./bacula start}
+\item Lancer le programme Console pour interagir avec le Director
+\item Lancer un job
+\item Lorsqu'un volume est plein, le d\'emonter, s'il s'agit d'une cartouche, en
+ \'etiqueter une nouvelle et poursuivre. Dans ce chapitre, nous n'\'ecrirons que sur
+ des volumes fichier, aussi vous n'avez pas \`a vous inqui\'eter au sujet des
+ cartouches pour le moment.
+\item Tester la restauration de quelques fichiers depuis le volume fraichement \'ecrit
+ pour s'assurer de la validit\'e de la sauvegarde et qu'il est possible de restaurer.
+ Mieux vaut essayer avant qu'un d\'esastre ne survienne...
+\item Ajouter un second client.
+ \end{enumerate}
+
+Chacune de ces \'etapes est d\'ecrite en d\'etail ci-dessous.
+
+\section{Avant d'ex\'ecuter Bacula}
+\index[general]{Bacula!Avant d'ex\'ecuter}
+\index[general]{Avant d'ex\'ecuter Bacula}
+\addcontentsline{toc}{section}{Avant d'ex\'ecuter Bacula}
+
+Avant d'utiliser Bacula pour la premi\`ere fois en production, nous vous recommandons
+d'ex\'ecuter la commande {\bf test} du programme {\bf btape} ainsi qu'il est d\'ecrit
+dans le chapitre \ilink{Programmes utilitaires}{btape} de ce manuel.
+Ce programme vous aidera \`a vous assurer que votre lecteur de bandes fonctionne
+correctement avec Bacula. Si vous avez un lecteur moderne de marque HP, Sony, ou
+Quantum DDS ou DLT qui fonctionne sous Linux ou Solaris, vous pouvez probablement
+vous dispenser de faire ce test car Bacula est bien test\'e avec ces lecteurs et ces
+syst\`emes. Dans tous les autres cas, vous \^etes {\bf fortement} encourag\'e \`a
+ex\'ecuter les tests avant de poursuivre. {\bf btape} dispose aussi d'une commande
+{\bf fill} qui tente de reproduire le comportement de Bacula lorsqu'il remplit
+une cartouche et qu'il poursuit son \'ecriture sur la suivante. Vous devriez
+songer \`a faire ce test, sachez cependant qu'il peut \^etre long (environ
+4 heures sur mon lecteur) de remplir une cartouche de haute capacit\'e.
+
+\section{D\'emarrer la base de donn\'ees}
+\label{StartDB}
+\index[general]{D\'emarrer la base de donn\'ees}
+\index[general]{base de donn\'ees!D\'emarrer la }
+\addcontentsline{toc}{section}{D\'emarrer la base de donn\'ees}
+
+Si vous utilisez MySQL ou PostgreSQL pour votre catalogue Bacula, vous devez
+d\'emarrer la base de donn\'ees avant d'essayer de lancer un job pour \'eviter
+d'obtenir des messages d'erreur au d\'emarrage de Bacula. J'utilise les scripts
+{\bf startmysql} et {\bf stopmysql} pour d\'emarrer mon MySQL local. Notez que si
+vous utilisez SQLite, vous n'aurez pas \`a utiliser {\bf startmysql} ou {\bf stopmysql}.
+Si vous utilisez ceci en production, vous souhaiterez probablement trouver
+un moyen pour d\'emarrer automatiquement MySQL ou PostgreSQL apr\`es chaque
+red\'emarrage du syst\`eme.
+
+Si vous utilisez SQLite (c'est \`a dire, si vous avez sp\'ecifi\'e l'option
+{\bf \verb:--:with-sqlite=xxx} de la commande {\bf ./configure}, vous n'avez rien \`a faire.
+SQLite est d\'emarr\'ee automatiquement par {\bf Bacula}.
+
+\section{D\'emarrer les daemons}
+\label{StartDaemon}
+\index[general]{D\'emarrer les daemons}
+\index[general]{Daemons!D\'emarrer les}
+\addcontentsline{toc}{section}{D\'emarrer les daemons}
+
+Que vous ayez compil\'e Bacula depuis les sources ou que vous ayez install\'e les rpms,
+tapez simplement :
+
+./bacula start
+
+dans votre r\'epertoire d'installation pour d\'emarrer les trois {\it daemons}.
+
+Le script {\bf bacula} lance le Storage Daemon, le File Daemon et le Director Daemon, qui
+tournent tous trois en tant que {\it daemons} en t\^ache de fond. Si vous utilisez
+la fonction de d\'emarrage automatique de Bacula, vous pouvez, au choix, lancer les
+trois {\it daemons} lors du d\'emarrage, ou au contraire les lancer individuellement
+avec les scripts {\bf bacula-dir}, {\bf bacula-fd}, et {\bf bacula-sd} usuellement
+situ\'es dans {\bf /etc/init.d}, bien que leur localisation effective soit d\'ependante du syst\`eme
+d'exploitation.
+
+Notez que seul le File Daemon a \'et\'e port\'e sur les syst\`emes Windows, et qu'il doit \^etre
+d\'emarr\'e diff\'eramment. Veuillez consulter le chapitre
+\ilink{La version Windows de Bacula}{_ChapterStart7} de ce manuel.
+
+Les paquetages rpm configurent les {\it daemons} pour qu'ils s'ex\'ecutent en tant
+qu'utilisateur root et en tant que groupe bacula. Le processus d'installation rpm
+se charge de cr\'eer le groupe bacula s'il n'existe pas sur le syst\`eme. Tout utilisateur
+ajout\'e au groupe bacula h\'erite de l'acc\`es aux fichiers cr\'e\'es par les {\it daemons}. Pour
+modifier ce comportement, \'editez les scripts de d\'emarrage des {\it daemons} :
+
+\begin{itemize}
+ \item /etc/bacula/bacula
+ \item /etc/init.d/bacula-dir
+ \item /etc/init.d/bacula-sd
+ \item /etc/init.d/bacula-fd
+\end{itemize}
+
+puis red\'emarrez-les.
+
+Le chapitre
+\ilink{installation}{_ChapterStart17} de ce manuel indique comment installer
+les scripts de d\'emarrage automatique des {\it daemons}.
+
+\section{Interagir avec le Director pour l'interroger sur l'\'etat de Bacula ou lancer des jobs}
+\index[general]{Jobs!Interagir avec le Director pour interroger l'\'etat de Bacula ou lancer des}
+\index[general]{Interagir avec le Director pour interroger l'\'etat de Bacula ou lancer des jobs}
+\addcontentsline{toc}{section}{Interagir avec le Director pour interroger l'\'etat de Bacula ou lancer des jobs}
+
+Pour communiquer avec le Director et pour s'enqu\'erir de l'\'etat de Bacula ou de jobs en
+cours d'ex\'ecution, tapez simplement :
+
+./bconsole
+
+dans le r\'epertoire de plus haut niveau.
+
+Si vous avez install\'e la console GNOME et utilis\'e l'option {\bf \verb:--:enable-gnome}
+de la commande configure, vous pouvez aussi utiliser la console GNOME en tapant :
+
+./gnome-console
+
+Vous pouvez aussi utiliser le programme wxWidgets {\bf bwx-console}.
+
+Pour simplifier, nous ne d\'ecrirons ici que le programme {\bf ./bconsole}. La plus
+grande partie de ce qui est d\'ecrit ici s'applique aussi aux programmes {\bf ./gnome-console}
+et {\bf bwx-console}.
+
+La commande {\bf ./bconsole} lance le programme Console, qui se connecte au Director.
+Bacula \'etant un programme r\'eseau, vous pouvez utiliser la Console depuis n'importe quelle
+machine de votre r\'eseau. Cependant, la plupart du temps le Console est ex\'ecut\'ee sur la
+m\^eme machine que le Director. En principe, la Console devrait produire un affichage
+similaire \`a :
+
+\footnotesize
+\begin{verbatim}
+[kern@polymatou bin]$ ./bconsole
+Connecting to Director lpmatou:9101
+1000 OK: HeadMan Version: 1.30 (28 April 2003)
+*
+\end{verbatim}
+\normalsize
+
+L'ast\'erisque est l'invite de commande de la console.
+
+Tapez {\bf help} pour obtenir la liste des commandes disponibles :
+
+\footnotesize
+\begin{verbatim}
+*help
+ Command Description
+ ======= ===========
+ add add media to a pool
+ autodisplay autodisplay [on/off] -- console messages
+ automount automount [on/off] -- after label
+ cancel cancel job=nnn -- cancel a job
+ create create DB Pool from resource
+ delete delete [pool=<pool-name> | media volume=<volume-name>]
+ estimate performs FileSet estimate debug=1 give full listing
+ exit exit = quit
+ help print this command
+ label label a tape
+ list list [pools | jobs | jobtotals | media <pool> |
+ files jobid=<nn>]; from catalog
+ llist full or long list like list command
+ messages messages
+ mount mount <storage-name>
+ prune prune expired records from catalog
+ purge purge records from catalog
+ query query catalog
+ quit quit
+ relabel relabel a tape
+ release release <storage-name>
+ restore restore files
+ run run <job-name>
+ setdebug sets debug level
+ show show (resource records) [jobs | pools | ... | all]
+ sqlquery use SQL to query catalog
+ status status [storage | client]=<name>
+ time print current time
+ unmount unmount <storage-name>
+ update update Volume or Pool
+ use use catalog xxx
+ var does variable expansion
+ version print Director version
+ wait wait until no jobs are running
+*
+\end{verbatim}
+\normalsize
+
+Pour plus de d\'etails sur les commandes de la console, consultez le chapitre
+\ilink{Console}{_ConsoleChapter} de ce manuel.
+
+\section{ex\'ecuter un job}
+\label{Running}
+\index[general]{Job!ex\'ecuter un}
+\index[general]{ex\'ecuter un job}
+\addcontentsline{toc}{section}{Ex\'ecuter un job}
+
+A ce stade, nous supposons que vous avez :
+
+\begin{itemize}
+\item Configur\'e Bacula avec la commande {\bf ./configure \verb:--:your-options}
+\item Compil\'e Bacula avec la commande {\bf make}
+\item Install\'e Bacula avec la commande {\bf make install}
+\item Cr\'e\'e votre catalogue avec, par exemple, la commande {\bf
+ ./create\_sqlite\_database}
+\item Cr\'e\'e les tables du catalogue avec la commande {\bf
+ ./make\_bacula\_tables}
+\item Eventuellement \'edit\'e votre fichier {\bf bacula-dir.conf} pour le personnaliser
+ quelque peu. ATTENTION ! Si vous modifiez le nom du Director ou son mot de passe,
+ vous devez faire les modifications correspondantes dans les autres fichiers de
+ configuration. Il est sans dout pr\'ef\'erable, pour l'instant, de ne rien changer.
+\item D\'emarr\'e Bacula avec la commande {\bf ./bacula start}
+\item Invoqu\'e le programme Console avec la commande {\bf ./bconsole}.
+\end{itemize}
+
+En outre, nous supposons pour le moment que vous utilisez les fichiers de configuration
+par d\'efaut.
+
+Maintenant, entrez les commandes suivantes :
+
+\footnotesize
+\begin{verbatim}
+show filesets
+\end{verbatim}
+\normalsize
+
+Vous devriez obtenir quelque chose comme :
+
+\footnotesize
+\begin{verbatim}
+FileSet: name=Full Set
+ O M
+ N
+ I /home/kern/bacula/regress/build
+ N
+ E /proc
+ E /tmp
+ E /.journal
+ E /.fsck
+ N
+FileSet: name=Catalog
+ O M
+ N
+ I /home/kern/bacula/regress/working/bacula.sql
+ N
+\end{verbatim}
+\normalsize
+
+Il s'agit d'un {\bf FileSet} pr\'ed\'efini qui sauvegardera le r\'epertoire des
+sources de Bacula. Les noms de r\'epertoires qui seront r\'eellement affich\'es
+devraient correspondre \`a votre configuration. Dans une perspective de tests,
+nous avons choisi un r\'epertoire de taille et de complexit\'e mod\'er\'ee (environ
+40 Mo). Le FileSet {\bf Catalog} est utilis\'e pour sauvegarder le catalogue
+Bacula et nous ne nous y attarderons pas pour le moment. Les entr\'ees {\bf I}
+sont les fichiers ou r\'epertoires qui seront inclus dans la sauvegarde, tandis
+que les entr\'ees {\bf E} sont ceux qui en seront exclus, quand aux entr\'ees {\bf O},
+ce sont les options sp\'ecifi\'ees pour ce FileSet. Vous pouvez changer ce qui est
+sauvegard\'e en modifiant la ligne {\bf File =} de la ressource {\bf FileSet}.
+
+
+Il est maintenant temps de lancer votre premi\`ere sauvegarde. Nous allons
+sauvegarder votre r\'epertoire sources de Bacula vers un volume File dans votre
+r\'epertoire {\bf /tmp} afin de vous montrer combien c'est facile. Saisissez :
+
+\footnotesize
+\begin{verbatim}
+status dir
+\end{verbatim}
+\normalsize
+
+Vous devriez obtenir :
+
+\footnotesize
+\begin{verbatim}
+rufus-dir Version: 1.30 (28 April 2003)
+Daemon started 28-Apr-2003 14:03, 0 Jobs run.
+Console connected at 28-Apr-2003 14:03
+No jobs are running.
+Level Type Scheduled Name
+=================================================================
+Incremental Backup 29-Apr-2003 01:05 Client1
+Full Backup 29-Apr-2003 01:10 BackupCatalog
+====
+\end{verbatim}
+\normalsize
+
+O\`u les dates et le nom du Director seront diff\'erents et en accord avec votre
+installation. Ceci montre qu'une sauvegarde incr\'ementale est planifi\'ee pour
+le job {\bf Client1} \`a 1h05, et qu'une sauvegarde full est planifi\'ee pour
+le job {\bf BackupCatalog} \`a 1h10. Vous devriez remplacer le nom {\bf Client1}
+par celui de votre machine, sinon vous risquez la confusion lorsque vous
+ajouterez de nouveaux clients. Pour ma machine r\'eelle, j'utilise {\bf Rufus}
+plut\^ot que {\bf Client1}.
+
+A pr\'esent, tapez :
+
+\footnotesize
+\begin{verbatim}
+status client
+\end{verbatim}
+\normalsize
+
+Vous devriez obtenir :
+
+\footnotesize
+\begin{verbatim}
+The defined Client resources are:
+ 1: rufus-fd
+Item 1 selected automatically.
+Connecting to Client rufus-fd at rufus:8102
+rufus-fd Version: 1.30 (28 April 2003)
+Daemon started 28-Apr-2003 14:03, 0 Jobs run.
+Director connected at: 28-Apr-2003 14:14
+No jobs running.
+====
+\end{verbatim}
+\normalsize
+
+Dans ce cas, le client se nomme {\bf rufus-fd}, votre nom sera diff\'erent, mais la
+ligne qui d\'ebute par {\bf rufus-fd Version...} est produite par votre File Daemon,
+nous sommes donc maintenant surs qu'il fonctionne.
+
+Finalement, faites de m\^eme pour votre Storage Daemon :
+
+\footnotesize
+\begin{verbatim}
+status storage
+\end{verbatim}
+\normalsize
+
+Vous devriez obtenir :
+
+\footnotesize
+\begin{verbatim}
+The defined Storage resources are:
+ 1: File
+Item 1 selected automatically.
+Connecting to Storage daemon File at rufus:8103
+rufus-sd Version: 1.30 (28 April 2003)
+Daemon started 28-Apr-2003 14:03, 0 Jobs run.
+Device /tmp is not open.
+No jobs running.
+====
+\end{verbatim}
+\normalsize
+
+Vous noterez que le p\'eriph\'erique du Storage Daemon par d\'efaut est nomm\'e {\bf File}
+et qu'il utilise le p\'eriph\'erique {\bf /tmp}, qui n'est actuellement pas ouvert.
+
+Maintenant, lancez un job :
+
+\footnotesize
+\begin{verbatim}
+run
+\end{verbatim}
+\normalsize
+
+Vous devriez obtenir :
+
+\footnotesize
+\begin{verbatim}
+Using default Catalog name=MyCatalog DB=bacula
+A job name must be specified.
+The defined Job resources are:
+ 1: Client1
+ 2: BackupCatalog
+ 3: RestoreFiles
+Select Job resource (1-3):
+\end{verbatim}
+\normalsize
+
+Ici, Bacula affiche la liste des trois diff\'erents jobs que vous pouvez ex\'ecuter.
+Choisissez le num\'ero {\bf 1} et validez (entr\'ee).
+
+Vous devriez obtenir :
+
+\footnotesize
+\begin{verbatim}
+Run Backup job
+JobName: Client1
+FileSet: Full Set
+Level: Incremental
+Client: rufus-fd
+Storage: File
+Pool: Default
+When: 2003-04-28 14:18:57
+OK to run? (yes/mod/no):
+\end{verbatim}
+\normalsize
+
+Prenez un peu de temps pour examiner cet affichage et le comprendre. Il vous
+est demand\'e de valider, modifier ou annuler l'ex\'ecution d'un job nomm\'e
+{\bf Client1} avec le FileSet {\bf Full Set} que nous avons affich\'e plus haut
+en incr\'emental sur votre client rufus, utilisant le p\'eriph\'erique de stockage
+{\bf File} et le pool {\bf Default} \`a la date indiqu\'ee sur la ligne "When".
+
+Nous avons le choix de valider ({\bf yes}), modifier un ou plusieurs des
+param\`etres ci-dessus ({\bf mod}), ou de ne pas ex\'ecuter le job ({\bf no}).
+
+Validez l'ex\'ecution du job ({\bf yes}), vous devriez imm\'ediatement obtenir
+l'invite de commande de la console (un ast\'erisque). Apr\`es quelques minutes,
+la commande {\bf messages} devrait produire un r\'esultat tel que :
+
+\footnotesize
+\begin{verbatim}
+28-Apr-2003 14:22 rufus-dir: Last FULL backup time not found. Doing
+ FULL backup.
+28-Apr-2003 14:22 rufus-dir: Start Backup JobId 1,
+ Job=Client1.2003-04-28_14.22.33
+28-Apr-2003 14:22 rufus-sd: Job Client1.2003-04-28_14.22.33 waiting.
+ Cannot find any appendable volumes.
+Please use the "label" command to create a new Volume for:
+ Storage: FileStorage
+ Media type: File
+ Pool: Default
+\end{verbatim}
+\normalsize
+
+Le premier message signale qu'aucune sauvegarde full n'a jamais \'et\'e faite, et
+que par cons\'equent Bacula \'el\`eve votre incr\'ementale en une Full (ce comportement
+est normal). Le second message indique que le job a d\'emarr\'e avec le JobId 1 et le
+troisi\`eme message vous informe que Bacula ne peut trouver aucun volume dans le
+pool Default sur lequel \'ecrire les donn\'ees du job. Ceci est normal, car nous
+n'avons encore cr\'e\'e (ou \'etiquet\'e) aucun volume. Bacula vous fournit tous les d\'etails
+concernant le volume dont il a besoin.
+
+A ce point, le job est bloqu\'e en attente d'un volume. Vous pouvez le v\'erifier
+en utilisant la commande {\bf status dir}. Pour continuer, vous devez cr\'eer un
+volume sur lequel Bacula pourra \'ecrire. Voici la manipulation :
+
+\footnotesize
+\begin{verbatim}
+label
+\end{verbatim}
+\normalsize
+
+Bacula devrait afficher :
+
+\footnotesize
+\begin{verbatim}
+The defined Storage resources are:
+ 1: File
+Item 1 selected automatically.
+Enter new Volume name:
+\end{verbatim}
+\normalsize
+
+Entrez un nom commen\c {c}ant par une lettre et ne contenant que des chiffres et des lettres
+(p\'eriodes, tirets et soulign\'e "\_" sont aussi autoris\'es). Par exemple entrez {\bf TestVolume001},
+vous devriez obtenir :
+
+\footnotesize
+\begin{verbatim}
+Defined Pools:
+ 1: Default
+Item 1 selected automatically.
+Connecting to Storage daemon File at rufus:8103 ...
+Sending label command for Volume "TestVolume001" Slot 0 ...
+3000 OK label. Volume=TestVolume001 Device=/tmp
+Catalog record for Volume "TestVolume002", Slot 0 successfully created.
+Requesting mount FileStorage ...
+3001 OK mount. Device=/tmp
+\end{verbatim}
+\normalsize
+
+Finalement, tapez la commande {\bf messages}, vous devriez obtenir quelque chose comme :
+
+\footnotesize
+\begin{verbatim}
+28-Apr-2003 14:30 rufus-sd: Wrote label to prelabeled Volume
+ "TestVolume001" on device /tmp
+28-Apr-2003 14:30 rufus-dir: Bacula 1.30 (28Apr03): 28-Apr-2003 14:30
+JobId: 1
+Job: Client1.2003-04-28_14.22.33
+FileSet: Full Set
+Backup Level: Full
+Client: rufus-fd
+Start time: 28-Apr-2003 14:22
+End time: 28-Apr-2003 14:30
+Files Written: 1,444
+Bytes Written: 38,988,877
+Rate: 81.2 KB/s
+Software Compression: None
+Volume names(s): TestVolume001
+Volume Session Id: 1
+Volume Session Time: 1051531381
+Last Volume Bytes: 39,072,359
+FD termination status: OK
+SD termination status: OK
+Termination: Backup OK
+28-Apr-2003 14:30 rufus-dir: Begin pruning Jobs.
+28-Apr-2003 14:30 rufus-dir: No Jobs found to prune.
+28-Apr-2003 14:30 rufus-dir: Begin pruning Files.
+28-Apr-2003 14:30 rufus-dir: No Files found to prune.
+28-Apr-2003 14:30 rufus-dir: End auto prune.
+\end{verbatim}
+\normalsize
+
+Si rien ne se passe dans l'imm\'ediat, vous pouvez continuer de rentrer la
+commande {\bf messages} jusqu'\`a ce que le job se termine, ou utiliser la
+commande {\bf autodisplay on} afin que les messages soient affich\'es d\`es-qu'ils
+sont disponibles.
+
+si vous faites {\bf ls -l} dans votre r\'epertoire {\bf /tmp}, vous verrez
+l'\'el\'ement suivant :
+
+\footnotesize
+\begin{verbatim}
+-rw-r----- 1 kern kern 39072153 Apr 28 14:30 TestVolume001
+\end{verbatim}
+\normalsize
+
+Il s'agit du volume File que vous venez juste d'\'ecrire, et qui contient toutes
+les donn\'ees du job que vous venez d'ex\'ecuter. Si vous ex\'ecutez d'autres jobs,
+il seront ajout\'es \`a la suite de ce volume, \`a moins que vous n'ayez sp\'ecifi\'e
+un autre comportement.
+
+Vous vous demandez peut-\^etre s'il va vous falloir \'etiqueter vous m\^eme chaque
+volume que Bacula sera amen\'e \`a utiliser. La r\'eponse, en ce qui concerne les
+volumes disque tels que celui que nous avons utilis\'e, est non. Il est possible
+de param\'etrer Bacula pour qu'il cr\'e\'ee lui m\^eme les volumes. En revanche,
+pour les volumes de type cartouche, il vous faudra tr\`es probablement
+\'etiqueter chaque volume que vous voulez utiliser.
+
+Si vous souhaitez en rester l\`a, saisissez simplement {\bf quit} dans la
+console, puis stoppez Bacula avec {\bf ./bacula stop}. Pour nettoyer
+votre installation des r\'esultats de vos tests, supprimez le fichier
+ {\bf /tmp/TestVolume001}, et r\'einitialisez votre catalogue en utilisant :
+
+\footnotesize
+\begin{verbatim}
+./drop_bacula_tables
+./make_bacula_tables
+\end{verbatim}
+\normalsize
+
+Notez bien que ceci supprimera toutes les informations concernant les jobs pr\'ec\'edemment
+ex\'ecut\'es et que, si c'est sans doute ce que vous souhaitez faire en fin de phase de
+test, ce n'est g\'en\'eralement pas une op\'eration souhaitable en utilisation normale.
+
+Si vous souhaitez essayer de restaurer les fichiers que vous venez de sauvegarder,
+lisez la section suivante.
+
+\label{restoring}
+
+\section{Restaurer vos fichiers}
+\index[general]{Fichiers!Restaurer vos}
+\index[general]{Restaurer vos fichiers}
+\addcontentsline{toc}{section}{Restaurer vos fichiers}
+
+Si vous avez utilis\'e la configuration par d\'efaut et sauvegard\'e les sources de Bacula
+comme dans la d\'emonstration ci-dessus, vous pouvez restaurer les fichiers sauvegard\'es
+en saisissant les commandes suivantes dans la Console :
+
+\footnotesize
+\begin{verbatim}
+restore all
+\end{verbatim}
+\normalsize
+
+Vous obtiendrez :
+
+\footnotesize
+\begin{verbatim}
+First you select one or more JobIds that contain files
+to be restored. You will be presented several methods
+of specifying the JobIds. Then you will be allowed to
+select which files from those JobIds are to be restored.
+
+To select the JobIds, you have the following choices:
+ 1: List last 20 Jobs run
+ 2: List Jobs where a given File is saved
+ 3: Enter list of comma separated JobIds to select
+ 4: Enter SQL list command
+ 5: Select the most recent backup for a client
+ 6: Select backup for a client before a specified time
+ 7: Enter a list of files to restore
+ 8: Enter a list of files to restore before a specified time
+ 9: Find the JobIds of the most recent backup for a client
+ 10: Find the JobIds for a backup for a client before a specified time
+ 11: Enter a list of directories to restore for found JobIds
+ 12: Cancel
+Select item: (1-12):
+\end{verbatim}
+\normalsize
+
+Comme vous pouvez le constater, les options sont nombreuses, mais pour l'instant,
+choisissez l'option {\bf 5} afin de s\'electionner la derni\`ere sauvegarde effectu\'ee.
+Vous obtiendrez :
+
+\footnotesize
+\begin{verbatim}
+Defined Clients:
+ 1: rufus-fd
+Item 1 selected automatically.
+The defined FileSet resources are:
+ 1: 1 Full Set 2003-04-28 14:22:33
+Item 1 selected automatically.
++-------+-------+----------+---------------------+---------------+
+| JobId | Level | JobFiles | StartTime | VolumeName |
++-------+-------+----------+---------------------+---------------+
+| 1 | F | 1444 | 2003-04-28 14:22:33 | TestVolume002 |
++-------+-------+----------+---------------------+---------------+
+You have selected the following JobId: 1
+Building directory tree for JobId 1 ...
+1 Job inserted into the tree and marked for extraction.
+The defined Storage resources are:
+ 1: File
+Item 1 selected automatically.
+You are now entering file selection mode where you add and
+remove files to be restored. All files are initially added.
+Enter "done" to leave this mode.
+cwd is: /
+$
+\end{verbatim}
+\normalsize
+
+(J'ai tronqu\'e l'affichage \`a droite par soucis de lisibilit\'e.)
+Comme vous pouvez le constater au d\'ebut de cet affichage, Bacula conna\^it
+vos clients, et puisque vous n'en avez qu'un, il est automatiquement
+s\'electionn\'e. Il en va de m\^eme pour le FileSet. Bacula produit alors une
+liste de tous les jobs qui constituent la sauvegarde courante. Dans le cas
+pr\'esent, il n'y en a qu'un. Notez que le Storage Daemon est aussi
+s\'electionn\'e automatiquement. Bacula est maintenant en mesure de produire
+une {\bf arborescence} \`a partir de tous les fichiers qui ont \'et\'e
+sauvegard\'es (il s'agit d'une repr\'esentation en m\'emoire de votre syst\`eme de
+fichiers). A ce stade, vous pouvez utiliser les commandes {\bf cd }, {\bf ls}
+et {\bf dir} pour naviguer dans l'arborescence et voir quels fichiers
+peuvent \^etre restaur\'es. Par exemple, si je saisis {\bf cd /home/kern/bacula/bacula-1.30}
+suivi de {\bf dir}, j'obtiens la liste de tous les fichiers du r\'epertoire source de
+Bacula. Pour plus d'information sur ce sujet, veuillez consulter le chapitre
+\ilink{La commande Restore}{_ChapterStart13}.
+
+Pour quitter, tapez simplement :
+
+\footnotesize
+\begin{verbatim}
+done
+\end{verbatim}
+\normalsize
+
+Vous obtiendrez :
+
+\footnotesize
+\begin{verbatim}
+Bootstrap records written to
+ /home/kern/bacula/testbin/working/restore.bsr
+The restore job will require the following Volumes:
+
+ TestVolume001
+1444 files selected to restore.
+Run Restore job
+JobName: RestoreFiles
+Bootstrap: /home/kern/bacula/testbin/working/restore.bsr
+Where: /tmp/bacula-restores
+Replace: always
+FileSet: Full Set
+Client: rufus-fd
+Storage: File
+JobId: *None*
+When: 2005-04-28 14:53:54
+OK to run? (yes/mod/no):
+\end{verbatim}
+\normalsize
+
+Si vous acceptez ({\bf yes}), vos fichiers seront restaur\'es vers le r\'epertoire
+{\bf /tmp/bacula-restores}. Si vous pr\'ef\'erez restaurer les fichiers \`a leurs
+emplacements d'origine, vous devez utiliser l'option {\bf mod} et r\'egler
+explicitement le param\`etre {\bf Where} \`a vide ou "/". Nous vous conseillons de
+poursuivre avec {\bf yes}. Apr\`es quelques instants, la commande {\bf messages}
+devrait produire la liste des fichiers restaur\'es, ainsi qu'un r\'esum\'e du job
+qui devrait ressembler \`a ceci :
+
+\footnotesize
+\begin{verbatim}
+28-Apr-2005 14:56 rufus-dir: Bacula 1.30 (28Apr03): 28-Apr-2003 14:56
+JobId: 2
+Job: RestoreFiles.2005-04-28_14.56.06
+Client: rufus-fd
+Start time: 28-Apr-2005 14:56
+End time: 28-Apr-2005 14:56
+Files Restored: 1,444
+Bytes Restored: 38,816,381
+Rate: 9704.1 KB/s
+FD termination status: OK
+Termination: Restore OK
+28-Apr-2005 14:56 rufus-dir: Begin pruning Jobs.
+28-Apr-2005 14:56 rufus-dir: No Jobs found to prune.
+28-Apr-2005 14:56 rufus-dir: Begin pruning Files.
+28-Apr-2005 14:56 rufus-dir: No Files found to prune.
+28-Apr-2005 14:56 rufus-dir: End auto prune.
+\end{verbatim}
+\normalsize
+
+Apr\`es avoir quitt\'e la Console, vous pouvez examiner les fichiers dans le
+r\'epertoire {\bf /tmp/bacula-restores}, il contient l'arborescence avec tous
+vos fichiers. Supprimez-le apr\`es avoir v\'erifi\'e :
+
+\footnotesize
+\begin{verbatim}
+rm -rf /tmp/bacula-restore
+\end{verbatim}
+\normalsize
+
+\section{Quitter le programme Console}
+\index[general]{Programme!Quitter Console }
+\index[general]{Quitter le programme Console}
+\addcontentsline{toc}{section}{Quitter le programme Console}
+
+Saisissez simplement la commande {\bf quit}.
+\label{SecondClient}
+
+\section{Ajouter un client}
+\index[general]{Client!Ajouter }
+\index[general]{Ajouter un client }
+\addcontentsline{toc}{section}{Ajouter un client}
+
+Si vous \^etes parvenus \`a faire fonctionner tous les exemples ci-dessus, vous \^etes
+sans doute pr\`et \`a ajouter un nouveau client (File Daemon), c'est \`a dire une seconde
+machine que vous souhaitez sauvegarder. La seule chose \`a installer sur la nouvelle
+machine est le binaire {\bf bacula-fd} (ou {\bf bacula-fd.exe} pour Windows) et son
+fichier de configuration {\bf bacula-fd.conf}. Vous pouvez d\'emarrer en copiant le fichier
+pr\'ec\'edemment cr\'e\'e moyennant une modification mineure pour l'adapter au nouveau client :
+changez le nom de File Daemon ({\bf rufus-fd} dans l'exemple ci-dessus) en le nom
+que vous avez choisi pour le nouveau client. Le mieux est d'utiliser le nom de
+la machine. Par exemple :
+
+\footnotesize
+\begin{verbatim}
+...
+#
+# "Global" File daemon configuration specifications
+#
+FileDaemon { # this is me
+ Name = rufus-fd
+ FDport = 9102 # where we listen for the director
+ WorkingDirectory = /home/kern/bacula/working
+ Pid Directory = /var/run
+}
+...
+\end{verbatim}
+\normalsize
+
+devient :
+
+\footnotesize
+\begin{verbatim}
+...
+#
+# "Global" File daemon configuration specifications
+#
+FileDaemon { # this is me
+ Name = matou-fd
+ FDport = 9102 # where we listen for the director
+ WorkingDirectory = /home/kern/bacula/working
+ Pid Directory = /var/run
+}
+...
+\end{verbatim}
+\normalsize
+
+O\`u {\bf rufus-fd} est devenu {\bf matou-fd} (je ne montre qu'une partie du fichier).
+Le choix des noms vous appartient. Pour l'instant, je vous recommande de ne rien changer
+d'autre. Plus tard, vous changerez le mot de passe.
+
+Installez cette configuration sur votre seconde machine. Il vous faut maintenant
+ajouter quelques lignes \`a votre {\bf bacula-dir.conf} pour d\'efinir le nouveau
+File Daemon. En vous basant sur l'exemple initial qui devrait \^etre install\'e
+sur votre syst\`eme, ajoutez les lignes suivantes (essentiellement, une copie des lignes
+existantes avec seulement les noms modifi\'es) \`a votre {\bf bacula-dir.conf} :
+
+\footnotesize
+\begin{verbatim}
+#
+# Define the main nightly save backup job
+# By default, this job will back up to disk in /tmp
+Job {
+ Name = "Matou"
+ Type = Backup
+ Client = matou-fd
+ FileSet = "Full Set"
+ Schedule = "WeeklyCycle"
+ Storage = File
+ Messages = Standard
+ Pool = Default
+ Write Bootstrap = "/home/kern/bacula/working/matou.bsr"
+}
+# Client (File Services) to backup
+Client {
+ Name = matou-fd
+ Address = matou
+ FDPort = 9102
+ Catalog = MyCatalog
+ Password = "xxxxx" # password for
+ File Retention = 30d # 30 days
+ Job Retention = 180d # six months
+ AutoPrune = yes # Prune expired Jobs/Files
+}
+\end{verbatim}
+\normalsize
+
+Assurez-vous que le param\`etre Address de la ressource Storage a pour valeur
+le nom pleinement qualifi\'e et non quelque chose comme "localhost". L'adresse
+sp\'ecifi\'ee est envoy\'ee au client et doit \^etre un nom pleinement qualifi\'e. Si vous
+utilisez "localhost", l'adresse du Storage Daemon ne sera pas r\'esolue
+correctement, il en r\'esultera un {\it timeout} lorsque le File Daemon
+\'echouera \`a connecter le Storage Daemon.
+
+Il n'y a rien d'autre \`a faire. J'ai copi\'e les ressources existantes pour cr\'eer
+un second job (Matou) pour sauvegarder le second client (matou-fd). le client
+se nomme {\bf matou-fd} et le job {\bf Matou}, le fichier bootstrap est modifi\'e
+mais tout le reste est inchang\'e. Ceci signifie que Matou sera sauvegard\'e
+avec la m\^eme planification sur les m\^emes cartouches. Vous pourrez changer ceci
+plus tard, pour le moment, restons simples.
+
+La seconde modification consiste en l'ajout d'une nouvelle ressource Client
+qui d\'efinit {\bf matou-fd} et qui a l'adresse correcte {\bf matou} (mais dans
+la vraie vie, vous pouvez avoir besoin d'un nom pleinement qualifi\'e ou d'une
+adresse IP. J'ai aussi conserv\'e le m\^eme mot de passe (xxxxx dans l'exemple).
+
+A ce stade, il suffit de red\'emarrer Bacula pour qu'il prenne en compte vos
+modifications. L'invite que vous avez vu plus haut devrait maintenant
+inclure la nouvelle machine.
+
+Pour une utilisation en production vous voudrez probablement utiliser
+plusieurs pools et diff\'erentes planifications. Il vous appartient de faire les
+adaptations qui seyent \`a vos besoins. Dans tous les cas, n'oubliez pas de
+changer les mots de passe dans les fichiers de configuration du Director et
+du Client pour des raisons de s\'ecurit\'e.
+
+Vous trouverez des astuces importantes concernant le changement des noms et mots de
+passe, ainsi qu'un diagramme d\'ecrivant leurs correspondances dans la section
+\ilink{Erreurs d'authentification}{AuthorizationErrors} du chapitre FAQ de ce manuel.
+
+\section{Lorsque la cartouche est pleine}
+\label{FullTape}
+\index[general]{pleine!Lorsque la cartouche }
+\index[general]{Lorsque la cartouche est pleine}
+\addcontentsline{toc}{section}{Lorsque la cartouche est pleine}
+Si vous avez planifi\'e votre job, il viendra un moment o\`u la cartouche sera pleine
+et o\`u {\bf Bacula} ne pourra continuer. Dans ce cas, Bacula vous enverra un message
+tel que :
+
+\begin{verbatim}
+rufus-sd: block.c:337 === Write error errno=28: ERR=No space left
+ on device
+\end{verbatim}
+\normalsize
+
+Ceci indique que Bacula a re\c {c}u une erreur d'\'ecriture \`a cause de la carouche pleine.
+Bacula va maintenant rechercher une cartouche utilisable dans le pool sp\'ecifi\'e
+pour le job. Dans la situation id\'eale, vous avez r\'egl\'e correctement vos r\'etentions
+et sp\'ecifi\'e que vos cartouches peuvent \^etre recycl\'ees automatiquement. Dans ce cas,
+Bacula recycle automatiquement vos cartouches sorties de r\'etention et est en mesure
+de r\'e\'ecrire dessus. Pour plus d'informations sur le recyclage, veuillez consulter
+le chapitre \ilink{Recyclage}{_ChapterStart22} de ce manuel. Si vous constatez que
+vos cartouches ne sont pas recycl\'ees correctement, consultez la section sur le
+\ilink{Recyclage manuel}{manualrecycling} du chapitre Recyclage.
+
+Si comme moi, vous avez un tr\`es grand nombre de cartouches que vous \'etiquetez
+avec la date de premi\`ere \'ecriture, si vous n'avez pas r\'egl\'e vos p\'eriodes de
+r\'etention, Bacula ne trouvera pas de cartouche dans le pool et il vous enverra
+un message tel que :
+
+\footnotesize
+\begin{verbatim}
+rufus-sd: Job kernsave.2002-09-19.10:50:48 waiting. Cannot find any
+ appendable volumes.
+Please use the "label" command to create a new Volume for:
+ Storage: SDT-10000
+ Media type: DDS-4
+ Pool: Default
+\end{verbatim}
+\normalsize
+
+Ce message sera r\'ep\'et\'e une heure plus tard, puis deux heures plus tard et
+ainsi de suite en doublant \`a chaque fois l'intervalle \`a concurrence d'un jour
+jusqu'\`a ce que vous cr\'eiez un volume.
+
+Que faire dans cette situation ?
+
+La r\'eponse est simple : d'abord, fermez le lecteur \`a l'aide de la commande
+{\bf unmount} du programme Console. Si vous n'avez qu'un lecteur, il sera
+s\'electionn\'e automatiquement, sinon assurez-vous de d\'emonter celui sp\'ecifi\'e
+dans le message (dans ce cas {\bf STD-10000}).
+
+Ensuite, retirez la cartouche du lecteur et ins\'erez-en une vierge. Notez que
+sur certains lecteurs anciens, il peut \^etre n\'ecessaire d'\'ecrire une marque de
+fin de fichier ({\bf mt \ -f \ /dev/nst0 \ weof}) pour \'eviter que le lecteur
+ne d\'eroule toute la cartouche lorsque Bacula tente de lire le label. (NDT : j'ai un doute, la vo dit : "to prevent the drive from running away when Bacula attempts to read the label.")
+
+Finalement, utilisez la commande {\bf label} dans la console pour \'ecrire un
+label sur le nouveau volume. la commande {\bf label} va contacter le Storage
+Daemon pour qu'il \'ecrive l'\'etiquette logicielle. Si cette op\'eration se termine
+correctement, le nouveau volume est ajout\'e au pool et la commande {\bf mount} est
+envoy\'ee au Storage Daemon. Voyez les sections pr\'ec\'edentes de ce chapitre pour plus
+de d\'etails sur l'\'etiquetage des cartouches.
+
+Bacula peut maintenant poursuivre le job et continuer d'\'ecrire les donn\'ees
+sauvegard\'ees sur le nouveau volume.
+
+Si Bacula cycle sur un pool de volumes, au lieu du message ci-dessus
+ "Cannot find any appendable volumes.", Bacula peut vous demander de
+monter un volume particulier. Dans ce cas, essayez de le satisfaire. Si, pour
+quelque raison, vous n'avez plus le volume, vous pouvez monter n'importe quel
+autre volume du pool, pourvu qu'il soit utilisable, Bacula l'utilisera.
+La commande {\bf list volumes} du programme Console permet de d\'eterminer
+les volumes utilisables et ceux qui ne le sont pas.
+
+Si, comme moi, vous avez param\'etr\'e correctement vos p\'eriodes de r\'etention, mais
+n'avez plus aucun volume libre, vous pouvez r\'e-\'etiqueter et r\'e-utiliser un volume
+comme suit :
+
+\begin{itemize}
+\item Saisissez {\bf list volumes} dans la console et s\'electionnez le volume le plus
+anciens pour le r\'e-\'etiqueter.
+\item Si vos p\'eriodes de r\'etention sont judicieusement choisies, le volume devrait
+avoir le statut {\bf Purged}.
+\item Si le statut n'est pas {\bf Purged}, il vous faut purger le catalogue des jobs \'ecrits
+sur ce volume. Ceci peut \^etre fait avec la commande {\bf purge jobs volume} dans
+la console. Si vous avez plusieurs pools, vous serez invit\'e \`a choisir lequel avant
+de devoir saisir le VolumeName (ou MediaId).
+\item Enfin, utilisez simplement la commande {\bf relabel} pour r\'e-\'etiqueter le
+volume.
+ \end{itemize}
+
+Pour r\'e-\'etiqueter manuellement le volume, suivez les \'etapes suppl\'ementaire ci-dessous :
+
+\begin{itemize}
+\item Effacez le volume du catalogue avec la commande {\bf delete volume} dans la
+console (s\'electionnez le VolumeName ou le MediaId lorsque vous y \^etes invit\'e).
+\item Utilisez la commande {\bf unmount} pour d\'emonter l'ancienne cartouche.
+\item R\'e-\'etiquetez physiquement l'ancienne cartouche de sorte qu'elle puisse
+\^etre r\'eutilis\'ee.
+\item Ins\'erez l'ancienne cartouche dans le lecteur.
+\item Depuis la ligne de commande, saississez : {\bf mt \ -f \ /dev/st0 \ rewind} et
+{\bf mt \ -f \ /dev/st0 \ weof}, o\`u vous prendrez soin de substituer la cha\^ine d\'esignant
+ votre lecteur \`a {\bf /dev/st0}.
+\item Utilisez la commande {\bf label} dans la console pour \'ecrire une nouvelle
+\'etiquette Bacula sur votre cartouche.
+\item Utilisez la commande {\bf mount}, si ce n'est pas r\'ealis\'e automatiquement, afin
+que Bacula commence \`a utiliser la cartouche fraichement \'etiquet\'ee.
+\end{itemize}
+
+\section{D'autres commandes utiles de la console Bacula}
+\index[general]{Commands!autres commandes utiles de la console Bacula}
+\index[general]{autres commandes utiles de la console Bacula}
+\addcontentsline{toc}{section}{D'autres commandes utiles de la console Bacula}
+
+\begin{description}
+
+\item [status dir]
+ \index[console]{status dir }
+ Affiche un \'etat de tous les jobs en cours d'ex\'ecution ainsi que tous les
+ jobs programm\'es dans les prochine 24 heures
+
+\item [status]
+ \index[console]{status }
+ Le programme Console vous invite \`a s\'electionner un {\it daemon}, puis
+ il s'enquiert de l'\'etat de ce {\it daemon}.
+
+\item [status jobid=nn]
+ \index[console]{status jobid }
+ Affiche un \'etat du JobId nn s'il est en cours d'ex\'ecution. Le Storage
+ Daemon est aussi contact\'e pour produire un \'etat du job.
+
+\item [list pools]
+ \index[console]{list pools }
+ Affiche la liste des pools d\'efinis dans le catalogue.
+
+\item [list media]
+ \index[console]{list media }
+ Affiche la liste des m\'edia d\'efinis dans le catalogue.
+
+\item [list jobs]
+ \index[console]{list jobs }
+ Affiche la liste de tous les jobs enregistr\'es dans le catalogue et squi ont \'et\'e
+ ex\'ecut\'es.
+
+\item [list jobid=nn]
+ \index[console]{list jobid }
+ Affiche le JobId nn depuis le catalogue.
+
+\item [list jobtotals]
+ \index[console]{list jobtotals }
+ Affiche les totaux pour tous le jobs du catalogue.
+
+\item [list files jobid=nn]
+ \index[console]{list files jobid }
+ Affiche la liste des fichiers sauvegard\'es pour le JobId nn.
+
+\item [list jobmedia]
+ \index[console]{list jobmedia }
+ Affiche des informations relatives aux m\'edia utilis\'es pour chaque job ex\'ecut\'e.
+
+\item [messages]
+ \index[console]{messages }
+ Affiche tous les messages redirig\'es vers la console.
+
+\item [unmount storage=storage-name]
+ \index[console]{unmount storage }
+ D\'emonte le lecteur associ\'e au p\'eriph\'erique de stockage d\'esign\'e par
+ {\bf storage-name} s'il n'est pas en cours d'utilisation. Cette commande
+ est utile si vous souhaitez que Bacula lib\`ere le lecteur.
+
+\item [mount storage=storage-name]
+ \index[sd]{mount storage }
+ Le lecteur associ\'e au p\'eriph\'erique de stockage est mont\'e \`a nouveau. Lorsque
+ Bacula atteint la fin d'un volume et vous demande d'en monter un nouveau,
+ vous devez utiliser cette commande apr\`es avoir introduit une nouvelle
+ cartouche dans le lecteur. En effet, c'est le signal qui indique \`a Bacula
+ qu'il peut commencer \`a lire ou \'ecrire sur la cartouche.
+
+\item [quit]
+ \index[sd]{quit }
+ Permet de quitter le programme Console.
+\end{description}
+
+La plupart des commandes cit\'ees ci-dessus, \`a l'exception de {\bf list},
+vous invitent \`a compl\'eter la liste des arguments fournis si vous
+vous contentez d'entrer le nom de la commande.
+
+\section{D\'ebugger la sortie des daemons}
+\index[general]{D\'ebugger sortie daemons}
+\index[general]{Output!D\'ebugger daemons}
+\addcontentsline{toc}{section}{D\'ebugger la sortie des daemons}
+
+Si vous voulez d\'ebugger la sortie des {\it daemons} en cours d'ex\'ecution,
+lancez-les, depuis le r\'epertoire d'installation, comme suit :
+
+\footnotesize
+\begin{verbatim}
+./bacula start -d100
+\end{verbatim}
+\normalsize
+
+Cette possibilit\'e peut vous fournir une aide pr\'ecieuse si vos {\it daemons}
+ne d\'emarrent pas correctement. Normalement, la sortie des {\it daemons} est
+dirig\'ee vers le p\'eriph\'erique NULL, avec un niveau de d\'ebuggage sup\'erieur \`a
+z\'ero, elle est dirig\'ee vers le terminal de lancement.
+
+Pour stopper les trois {\it daemons}, tapez simplement :
+
+\footnotesize
+\begin{verbatim}
+./bacula stop
+\end{verbatim}
+\normalsize
+
+dans le r\'epertoire d'installation.
+
+L'ex\'ecution de {\bf bacula stop} peut signaler des pids non trouv\'es. C'est Ok,
+sp\'ecialement si l'un des {\bf bacula stop} est mort, ce qui est tr\`es rare.
+
+Pour faire une sauvegarde compl\`ete (Full) du syst\`eme, chaque File Daemon doit
+\^etre ex\'ecut\'e en tant que root afin d'avoir les permissions requises pour acc\'eder
+\`a tous les fichiers. Les autres {\it daemons} n'ont pas besoin des privil\`eges
+root. Cependant, le Storage Daemon doit \^etre capable d'acc\'eder aux lecteurs, ce qui
+Sur beaucoup de syst\`emes, n'est possible que pour root. Vous pouvez, au choix,
+ex\'ecuter le Storage Daemon en tant que root, ou changer les permissions sur les
+lecteurs pour autoriser les acc\`es non-root. MySQL et PostgreSQL peuvent \^etre
+install\'es et ex\'ecut\'es avec un userid quelconque, les privil\`eges root ne sont pas
+requis.
+
+\section{Soyez patient lorsque vous d\'emarrez les {\it daemons} ou montez des
+cartouches vierges}
+\index[general]{Soyez patient lorsque vous d\'emarrez les {\it daemons} ou montez des
+cartouches vierges}
+\index[general]{Cartouches!Soyez patient lorsque vous d\'emarrez les {\it daemon}s ou montez}
+\addcontentsline{toc}{section}{Soyez patient lorsque vous d\'emarrez les {\it daemon}s
+ou montez des cartouches vierges}
+
+Lorsque vous lancez les {\it daemons} Bacula, le Storage Daemon tente d'ouvrir
+tous les p\'eriph\'eriques de stockage d\'efinis et de v\'erifier le volumes courrament
+mont\'es. Il n'accepte aucune connection de la console tant que tous les p\'eriph\'eriques
+n'ont pas \'et\'e v\'erifi\'es. Une cartouche qui a \'et\'e utilis\'e pr\'ec\'edemment doit \^etre
+rembobin\'ee, ce qui, sur certain lecteurs, peut prendre plusieurs minutes.
+Par cons\'equent, vous devriez faire preuve d'un peu de patience lorsue vous
+tentez de contacter le Storage Daemon pour la premi\`ere fois apr\`es le
+lancement de Bacula. Si vous avez un acc\`es visuel \`a votre lecteur, celui-ci
+devrait \^etre pr\`et \`a l'emploi lorsque son t\'emoin lumineux cesse de clignoter.
+
+Les m\^emes consid\'erations s'appliquent si vous avez mont\'e une cartouche vierge
+dans un lecteur tels qu'un HP DLT. Il peut s'\'ecouler une \`a deux minutes avant
+que le lecteur se rende compte que la cartouche est vierge. Si vous tentez
+de la monter pendant cette p\'eriode, il est probable que vous aller geler votre
+pilote SCSI (c'est le cas sur mon syst\`eme RedHat). Par cons\'equent, nous vous
+enjoignons une fois encore \`a \^etre patient lors de l'insertion de cartouches vierges.
+Laissez le lecteur s'initialiser avant de tenter d'y acc\'eder.
+
+\section{Probl\`emes de connection du FD vers le SD}
+\index[general]{Probl\`emes de connection du FD vers le SD }
+\index[general]{SD!Probl\`emes de connection du FD vers le}
+\addcontentsline{toc}{section}{Probl\`emes de connection du FD vers le SD}
+
+Si l'un ou plusieurs de vos File Daemons rencontre des difficult\'es \`a se connecter
+au Storage Daemon, c'est tr\`es probablement que vous n'avez pas utilis\'e un nom
+pleinement qualifi\'e pour la directive {\bf Address} de la ressource Storage
+du fichier de configuration du Director. Le r\'esolveur de la machine cliente
+(celle qui ex\'ecute le FD) doit \^etre capable de r\'esoudre le nom que vous avez
+sp\'ecifi\'e dans cette directive en une adresse IP. Un exemple d'adresse ne
+fonctionnant pas est {\bf localhost}. Un exemple qui pourrait fonctionner :
+{\bf megalon}. Un exemple qui a encore plus de chances de fonctionner :
+{\bf magalon.mydomain.com}. Sur les syst\`emes Win32, si vous ne disposez pas d'un
+bon r\'esolveur (c'est souvent le cas sur Win98), vous pouvez essayer en utilisant
+une adresse IP plut\^ot qu'un nom.
+
+Si votre adresse est correcte, assurez vous qu'aucun autre programme n'utilise
+le port 9103 sur la machine qui h\'eberge le Storage Daemon. Les num\'eros de ports
+de Bacula sont autoris\'es par l'IANA, et ne devraient donc pas \^etre utilis\'es par
+d'autres programmes, mais il semble que certaines imprimantes HP les utilisent.
+Ex\'ecutez la commande {\bf netstat -a} sur la machine qui h\'eberge le Storage
+Daemon pour d\'eterminer qui utilise le port 9103 (utilis\'e pour les communications
+du FD vers le SD).
+
+\section{Options en ligne de commande des Daemons}
+\index[general]{Options en ligne de commande des Daemons}
+\index[general]{Options!en ligne de commande des Daemons}
+\addcontentsline{toc}{section}{Options en ligne de commande des Daemons}
+
+Chacun des trois {\it daemons} (Director, File, Storage) acceptent quelques options
+sur la ligne de commande. En g\'en\'eral, chacun d'entre eux, de m\^eme que le
+programme Console, admet les otpions suivantes :
+
+
+\begin{description}
+
+\item [-c \lt{}file\gt{}]
+ \index[sd]{-c \lt{}file\gt{} }
+ D\'efinit le fichier de configuration \`a utiliser. La valeur par d\'efaut est le
+nom du {\it daemon} suivi de {\bf conf}, par exemple {\bf bacula -dir.conf} pour
+le Director, {\bf bacula-fd} pour le File Daemon, et {\bf bacula-sd.conf} pour
+le Storage Daemon.
+
+\item [-d nn]
+ \index[sd]{-d nn }
+ Fixe le niveau de d\'ebuggage \`a la valeur {\bf nn}. Les niveaux les plus \'elev\'e
+permettent d'afficher plus d'information sur STDOUT concernant ce que le {\it daemon} est
+en train de faire.
+
+\item [-f]
+ Ex\'ecute le {\it daemon} en arri\`ere plan. Cette option est requise pour ex\'ecuter les
+{\it daemon}s avec le debugger.
+
+\item [-s]
+ Ne pas capturer les signaux. Cette option est requise pour ex\'ecuter les
+{\it daemon}s avec le debugger.
+
+\item [-t]
+ Lire les fichiers de configuration et afficher les messages d'erreur, et quitter
+imm\'ediatement. Tr\`es utile pour tester la syntaxe de nouveaux fichiers de configuration.
+
+\item [-v]
+ Mode verbeux. Utile pour rendre les messages d'erreur et d'information plus complets.
+
+\item [-?]
+ Affiche la version et la liste des options.
+ \end{description}
+
+Le Director a les options sp\'ecifiques suivantes :
+
+\begin{description}
+
+\item [-r \lt{}job\gt{}]
+ \index[fd]{-r \lt{}job\gt{} }
+ Ex\'ecute le job d\'esign\'e imm\'ediatement. Ceci ne devrait servir qu'\`a des fins
+de d\'ebuggage.
+\end{description}
+
+Le File Daemon les options sp\'ecifiques suivantes :
+
+\begin{description}
+
+\item [-i]
+ Suppose que le {\it daemon} est appel\'e par {\bf inetd} ou {\bf xinetd}. Dans ce cas,
+le {\it daemon} suppose qu'une connection est d\'ej\`a \'etablie et qu'elle est pass\'ee en tant que
+STDIN. Le {\it daemon} s'arr\`ete d\`es que la connection se termine.
+\end{description}
+
+Le Storage Daemon n'a pas d'options sp\'ecifiques.
+
+Le programme Console n'a pas d'options sp\'ecifiques.
+
+\section{Cr\'eer un Pool}
+\label{Pool}
+\index[general]{Pool!Cr\'eer un }
+\index[general]{Cr\'eer un Pool }
+\addcontentsline{toc}{section}{Cr\'eer un Pool}
+
+La cr\'eation de pool est automatique au d\'emarrage de Bacula, aussi si vous
+comprenez d\'ej\`a le concept de pools et leur fonctionnement, vous pouvez passer
+\`a la section suivante.
+
+Lorsque vous ex\'ecutez un job, Bacula doit d\'eterminer quel volume utiliser pour
+sauvegarder le FileSet. Plut\^ot que de sp\'ecifier un volume directement, vous
+sp\'ecifiez l'ensemble de volumes dans lequel vous autorisez Bacula \`a puiser
+lorsqu'il lui faut un volume pour \'ecrire les donn\'ees sauvegard\'ees. D\`es lors, Bacula
+se charge de s\'electionner le premier volume utilisable dans le pool appropri\'e
+au p\'eriph\'erique que vous avez sp\'ecifi\'e pour le job ex\'ecut\'e. Lorsqu'un volume est
+plein, Bacula change son VolStatus de {\bf Append} en {\bf Full}, et utilise le
+volume suivant, et ainsi de de suite. S'il n'y a pas de volume utilisable,
+Bacula envoie un message \`a l'op\'erateur pour r\'eclamer la cr\'eation d'un
+volume appropri\'e.
+
+{\bf Bacula} garde trace des noms de pools, des volumes contenus dans les pools,
+et de plusieurs caract\'eristiques de chacun de ces volumes.
+
+Lorsque Bacula d\'emarre, il s'assure que toutes les d\'efinitions de ressources Pool
+ont \'et\'e enregistr\'ees dans le catalogue. Vous pouvez le v\'erifier avec la commande :
+
+\footnotesize
+\begin{verbatim}
+list pools
+\end{verbatim}
+\normalsize
+
+du programme Console, qui devrait produire quelque chose comme :
+
+\footnotesize
+\begin{verbatim}
+*list pools
+Using default Catalog name=MySQL DB=bacula
++--------+---------+---------+---------+----------+-------------+
+| PoolId | Name | NumVols | MaxVols | PoolType | LabelFormat |
++--------+---------+---------+---------+----------+-------------+
+| 1 | Default | 3 | 0 | Backup | * |
+| 2 | File | 12 | 12 | Backup | File |
++--------+---------+---------+---------+----------+-------------+
+*
+\end{verbatim}
+\normalsize
+
+Si vous tentez de cr\'eer un pool existant, Bacula affiche :
+
+\footnotesize
+\begin{verbatim}
+Error: Pool Default already exists.
+Once created, you may use the {\bf update} command to
+modify many of the values in the Pool record.
+\end{verbatim}
+\normalsize
+
+\label{Labeling}
+
+\section{Etiqueter vos Volumes}
+\index[general]{Volumes!Etiqueter vos}
+\index[general]{Etiqueter vos Volumes}
+\addcontentsline{toc}{section}{Etiqueter vos Volumes}
+
+Bacula exige que chaque volume comporte une \'etiquette (NDT : label) logicielle.
+Il existe plusieurs strat\'egies pour \'etiqueter les volumes. Celle que j'utilise
+consiste \`a les \'etiqueter \`a l'aide du programme Console au fur et \`a mesure qu'ils
+sont requis par Bacula. Ainsi, lorsqu'il a besoin d'un volume qu'il ne trouve pas
+dans son catalogue, Bacula m'envoie un e-mail pour m'enjoindre \`a ajouter un
+volume au pool. J'utilise alors la commande {\bf label} dans la console pour
+\'etiqueter un nouveau volume et le d\'efinir dans le catalogue, apr\`es quoi Bacula
+est en mesure de l'utiliser. Alternativement, je peux utiliser la commande
+{\bf relabel} pour r\'e-\'etiquter un volume qui n'est plus utilis\'e, pourvu qu'il ait
+le VolStatus {\bf Purged}.
+
+Une autre strat\'egie consiste \`a \'etiqueter un ensemble de volumes, et \`a les
+utiliser au fur et \`a mesure que Bacula les r\'eclame. C'est le plus souvent ce qui
+est fait lorsque vous cyclez sur un groupe de volumes, par exemple avec une
+librairie. Pour plus de d\'etails sur le recyclage, veuillez consulter le
+chapitre \ilink{Recyclage automatique des volumes}{_ChapterStart22} de ce
+manuel.
+
+Si vous ex\'ecutez un job Bacula alors que vous n'avez pas de volumes
+\'etiquet\'es dans le pool concern\'e, Bacula vous en informe, et vous pouvez les
+cr\'eer "\`a la vol\'ee". Dans mon cas, j'\'etiquette mes cartouches avec la date,
+par exemple : {\bf DLT-18April02}. Voyez ci-dessous pour plus de d\'etails
+sur l'usage de la commande {\bf label}.
+
+\section{Etiquetage des volumes dans la console}
+\index[general]{Etiquetage des volumes dans la console}
+\index[general]{Console!Etiquetage des volumes dans la}
+\addcontentsline{toc}{section}{Etiquetage des volumes dans la console}
+
+L'\'etiquetage des volumes se fait, en principe, avec le programme Console.
+
+\begin{enumerate}
+\item ./bconsole
+\item label
+ \end{enumerate}
+
+Si Bacula annonce que vous ne pouvez \'etiqueter une cartouche au motif qu'elle
+porte d\'ej\`a une \'etiquette, d\'emontez-la avec la commande {\bf unmount}, puis
+recommencez avec une cartouche vierge.
+
+Etand donn\'e que le support de stockage physique est diff\'erent pour chaque
+p\'eriph\'erique, la commande {\bf label} vous propose une liste de ressources
+Storage d\'efinies telle que celle-ci :
+
+\footnotesize
+\begin{verbatim}
+The defined Storage resources are:
+ 1: File
+ 2: 8mmDrive
+ 3: DLTDrive
+ 4: SDT-10000
+Select Storage resource (1-4):
+\end{verbatim}
+\normalsize
+
+A ce stade, vous devriez avoir une cartouche vierge dans votre lecteur
+d'un type correspondant \`a la ressource Storage que vous avez s\'electionn\'e.
+
+Bacula vous demande le nom du volume :
+
+\footnotesize
+\begin{verbatim}
+Enter new Volume name:
+\end{verbatim}
+\normalsize
+
+S'il proteste :
+
+\footnotesize
+\begin{verbatim}
+Media record for Volume xxxx already exists.
+\end{verbatim}
+\normalsize
+
+Cela signifie que le nom de volume {\bf xxxx} que vous avez entr\'e existe d\`ej\`a
+dans le catalogue. Vous pouvez afficher la liste des m\'edia d\'efinis avec la
+commande {\bf list media}. Notez que la colonne LastWritten a ici \'et\'e
+tronqu\'ee pour permettre un affichage propre.
+
+\footnotesize
+\begin{verbatim}
++---------------+---------+--------+----------------+-----/~/-+------------+-----+
+| VolumeName | MediaTyp| VolStat| VolBytes | LastWri | VolReten | Recy|
++---------------+---------+--------+----------------+---------+------------+-----+
+| DLTVol0002 | DLT8000 | Purged | 56,128,042,217 | 2001-10 | 31,536,000 | 0 |
+| DLT-07Oct2001 | DLT8000 | Full | 56,172,030,586 | 2001-11 | 31,536,000 | 0 |
+| DLT-08Nov2001 | DLT8000 | Full | 55,691,684,216 | 2001-12 | 31,536,000 | 0 |
+| DLT-01Dec2001 | DLT8000 | Full | 55,162,215,866 | 2001-12 | 31,536,000 | 0 |
+| DLT-28Dec2001 | DLT8000 | Full | 57,888,007,042 | 2002-01 | 31,536,000 | 0 |
+| DLT-20Jan2002 | DLT8000 | Full | 57,003,507,308 | 2002-02 | 31,536,000 | 0 |
+| DLT-16Feb2002 | DLT8000 | Full | 55,772,630,824 | 2002-03 | 31,536,000 | 0 |
+| DLT-12Mar2002 | DLT8000 | Full | 50,666,320,453 | 1970-01 | 31,536,000 | 0 |
+| DLT-27Mar2002 | DLT8000 | Full | 57,592,952,309 | 2002-04 | 31,536,000 | 0 |
+| DLT-15Apr2002 | DLT8000 | Full | 57,190,864,185 | 2002-05 | 31,536,000 | 0 |
+| DLT-04May2002 | DLT8000 | Full | 60,486,677,724 | 2002-05 | 31,536,000 | 0 |
+| DLT-26May02 | DLT8000 | Append | 1,336,699,620 | 2002-05 | 31,536,000 | 1 |
++---------------+---------+--------+----------------+-----/~/-+------------+-----+
+\end{verbatim}
+\normalsize
+
+Une fois que Bacula a v\'erifi\'e que le volume n'existe pas encore, il vous
+demande le pool dans lequel vous souhaitez que le volume soit cr\'e\'e. S'il
+n'existe qu'un pool, il est s\'electionn\'e automatiquement.
+
+Si la cartouche est \'etiquet\'ee correctement, un enregistrement de volume est
+aussi cr\'e\'e dans le pool. Ainsi, le nom du volume et tous ses attributs
+appara\^itront lorque vous afficherez les volumes du pool. De plus, le volume
+est disponible pour les sauvegardes, pourvu que le MediaType co\"¨incide avec
+celui requis par le Storage Daemon.
+
+Lorsque vous avez \'etiquet\'e la cartouche, vous n'avez r\'epondu qu'\`a quelques
+questions la concernant -- principalement son nom, et \'eventuellement le {\it Slot}.
+Cependant, un enregistrement de volume dans le catalogue (connu au niveau interne
+en tant qu'enregistrement Media) contient un certain nombre d'attributs.
+La plupart d'entre eux sont renseign\'es selon les valeurs par d\'efaut qui ont \'et\'e
+d\'efinies lors de la cr\'eation du pool (au trement dit, le pool comporte la plupart des
+attributs par d\'efaut utilis\'es lors de la cr\'eation d'un volume).
+
+Il est aussi possible d'ajouter des media aux pools sans les \'etiqueter
+physiquement. C'est la fonction de la commande {\bf add}. Pour plus
+d'informations, veuillez consulterle chapitre \ilink{Console}{_ConsoleChapter}
+de ce manuel.
--- /dev/null
+#!/bin/sh
+#
+# Script file to update the Bacula version
+#
+out=/tmp/$$
+VERSION=`sed -n -e 's/^.*VERSION.*"\(.*\)"$/\1/p' /home/kern/bacula/k/src/version.h`
+DATE=`sed -n -e 's/^.*[ \t]*BDATE.*"\(.*\)"$/\1/p' /home/kern/bacula/k/src/version.h`
+. ./do_echo
+sed -f ${out} version.tex.in >version.tex
+rm -f ${out}
--- /dev/null
+#!/bin/sh
+#
+# Script file to update the Bacula version
+#
+out=/tmp/$$
+VERSION=`sed -n -e 's/^.*VERSION.*"\(.*\)"$/\1/p' @bacula@/src/version.h`
+DATE=`sed -n -e 's/^.*[ \t]*BDATE.*"\(.*\)"$/\1/p' @bacula@/src/version.h`
+. ./do_echo
+sed -f ${out} version.tex.in >version.tex
+rm -f ${out}
--- /dev/null
+#!/bin/sh
+
+ftp -i ftp.sectoor.de <<END_OF_DATA
+cd www/htdocs/dev-manual
+lcd /home/kern/bacula/docs/manual/bacula
+mput *
+cd ..
+lcd ..
+put dev-bacula.pdf dev-bacula.pdf
+quit
+END_OF_DATA
--- /dev/null
+%%
+%%
+
+\chapter{Variable Expansion}
+\label{VarsChapter}
+\index[general]{Variable Expansion }
+\index[general]{Expansion!Variable }
+
+% TODO: does the following mean that this should not be in book?
+
+Please note that as of version 1.37, the Variable Expansion
+is deprecated and replaced by Python scripting (not yet
+documented).
+
+Variable expansion is somewhat similar to Unix shell variable expansion.
+Currently (version 1.31), it is used only in format labels, but in the future,
+it will most likely be used in more places.
+
+\section{General Functionality}
+\index[general]{Functionality!General }
+\index[general]{General Functionality }
+
+This is basically a string expansion capability that permits referencing
+variables, indexing arrays, conditional replacement of variables, case
+conversion, substring selection, regular expression matching and replacement,
+character class replacement, padding strings, repeated expansion in a user
+controlled loop, support of arithmetic expressions in the loop start, step and
+end conditions, and recursive expansion.
+
+When using variable expansion characters in a Volume Label Format record, the
+format should always be enclosed in double quotes ({\bf "}).
+
+For example, {\bf \$\{HOME\}} will be replaced by your home directory as
+defined in the environment. If you have defined the variable {\bf xxx} to be
+{\bf Test}, then the reference {\bf \$\{xxx:p/7/Y/r\}} will right pad the
+contents of {\bf xxx} to a length of seven characters filling with the
+character {\bf Y} giving {\bf YYYTest}.
+
+\section{Bacula Variables}
+\index[general]{Bacula Variables }
+\index[general]{Variables!Bacula }
+
+Within Bacula, there are three main classes of variables with some minor
+variations within the classes. The classes are:
+
+\begin{description}
+
+\item [Counters]
+ \index[dir]{Counters }
+ Counters are defined by the {\bf Counter} resources in the Director's conf
+file. The counter can either be a temporary counter that lasts for the
+duration of Bacula's execution, or it can be a variable that is stored in
+the catalog, and thus retains its value from one Bacula execution to another.
+Counter variables may be incremented by postfixing a plus sign ({\bf +} after
+the variable name).
+
+\item [Internal Variables]
+ \index[dir]{Internal Variables }
+ Internal variables are read-only, and may be related to the current job (i.e.
+Job name), or maybe special variables such as the date and time. The
+following variables are available:
+
+\begin{itemize}
+\item [Year] -- the full year
+\item [Month] -- the current month 1-12
+\item [Day] -- the day of the month 1-31
+\item [Hour] -- the hour 0-24
+\item [Minute] -- the current minute 0-59
+\item [Second] -- the current second 0-59
+\item [WeekDay] -- the current day of the week 0-6 with 0 being Sunday
+\item [Job] -- the job name
+\item [Dir] -- the Director's name
+\item [Level] -- the Job Level
+\item [Type] -- the Job type
+\item [JobId] -- the JobId
+\item [JobName] -- the unique job name composed of Job and date
+\item [Storage] -- the Storage daemon's name
+\item [Client] -- the Client's name
+\item [NumVols] -- the current number of Volumes in the Pool
+\item [Pool] -- the Pool name
+\item [Catalog] -- the Catalog name
+\item [MediaType] -- the Media Type
+ \end{itemize}
+
+\item [Environment Variables]
+ \index[dir]{Environment Variables }
+ Environment variables are read-only, and must be defined in the environment
+prior to executing Bacula. Environment variables may be either scalar or an
+array, where the elements of the array are referenced by subscripting the
+variable name (e.g. {\bf \$\{Months[3]\}}). Environment variable arrays are
+defined by separating the elements with a vertical bar ({\bf |}), thus {\bf
+set Months="Jan|Feb|Mar|Apr|..."} defines an environment variable named
+{\bf Month} that will be treated as an array, and the reference {\bf
+\$\{Months[3]\}} will yield {\bf Mar}. The elements of the array can have
+differing lengths.
+\end{description}
+
+\section{Full Syntax}
+\index[general]{Syntax!Full }
+\index[general]{Full Syntax }
+
+Since the syntax is quite extensive, below, you will find the pseudo BNF. The
+special characters have the following meaning:
+
+\footnotesize
+\begin{verbatim}
+ ::= definition
+ ( ) grouping if the parens are not quoted
+ | separates alternatives
+ '/' literal / (or any other character)
+ CAPS a character or character sequence
+ * preceding item can be repeated zero or more times
+ ? preceding item can appear zero or one time
+ + preceding item must appear one or more times
+\end{verbatim}
+\normalsize
+
+And the pseudo BNF describing the syntax is:
+
+\footnotesize
+\begin{verbatim}
+ input ::= ( TEXT
+ | variable
+ | INDEX_OPEN input INDEX_CLOSE (loop_limits)?
+ )*
+ variable ::= DELIM_INIT (name|expression)
+ name ::= (NAME_CHARS)+
+ expression ::= DELIM_OPEN
+ (name|variable)+
+ (INDEX_OPEN num_exp INDEX_CLOSE)?
+ (':' command)*
+ DELIM_CLOSE
+ command ::= '-' (TEXT_EXP|variable)+
+ | '+' (TEXT_EXP|variable)+
+ | 'o' NUMBER ('-'|',') (NUMBER)?
+ | '#'
+ | '*' (TEXT_EXP|variable)+
+ | 's' '/' (TEXT_PATTERN)+
+ '/' (variable|TEXT_SUBST)*
+ '/' ('m'|'g'|'i'|'t')*
+ | 'y' '/' (variable|TEXT_SUBST)+
+ '/' (variable|TEXT_SUBST)*
+ '/'
+ | 'p' '/' NUMBER
+ '/' (variable|TEXT_SUBST)*
+ '/' ('r'|'l'|'c')
+ | '%' (name|variable)+
+ ('(' (TEXT_ARGS)? ')')?
+ | 'l'
+ | 'u'
+ num_exp ::= operand
+ | operand ('+'|'-'|'*'|'/'|'%') num_exp
+ operand ::= ('+'|'-')? NUMBER
+ | INDEX_MARK
+ | '(' num_exp ')'
+ | variable
+ loop_limits ::= DELIM_OPEN
+ (num_exp)? ',' (num_exp)? (',' (num_exp)?)?
+ DELIM_CLOSE
+ NUMBER ::= ('0'|...|'9')+
+ TEXT_PATTERN::= (^('/'))+
+ TEXT_SUBST ::= (^(DELIM_INIT|'/'))+
+ TEXT_ARGS ::= (^(DELIM_INIT|')'))+
+ TEXT_EXP ::= (^(DELIM_INIT|DELIM_CLOSE|':'|'+'))+
+ TEXT ::= (^(DELIM_INIT|INDEX_OPEN|INDEX_CLOSE))+
+ DELIM_INIT ::= '$'
+ DELIM_OPEN ::= '{'
+ DELIM_CLOSE ::= '}'
+ INDEX_OPEN ::= '['
+ INDEX_CLOSE ::= ']'
+ INDEX_MARK ::= '#'
+ NAME_CHARS ::= 'a'|...|'z'|'A'|...|'Z'|'0'|...|'9'
+\end{verbatim}
+\normalsize
+
+\section{Semantics}
+\index[general]{Semantics }
+
+The items listed in {\bf command} above, which always follow a colon ({\bf :})
+have the following meanings:
+
+\footnotesize
+\begin{verbatim}
+ - perform substitution if variable is empty
+ + perform substitution if variable is not empty
+ o cut out substring of the variable value
+ # length of the variable value
+ * substitute empty string if the variable value is not empty,
+ otherwise substitute the trailing parameter
+ s regular expression search and replace. The trailing
+ options are: m = multiline, i = case insensitive,
+ g = global, t = plain text (no regexp)
+ y transpose characters from class A to class B
+ p pad variable to l = left, r = right or c = center,
+ with second value.
+ % special function call (none implemented)
+ l lower case the variable value
+ u upper case the variable value
+\end{verbatim}
+\normalsize
+
+The {\bf loop\_limits} are start, step, and end values.
+
+A counter variable name followed immediately by a plus ({\bf +}) will cause
+the counter to be incremented by one.
+
+\section{Examples}
+\index[general]{Examples }
+
+To create an ISO date:
+
+\footnotesize
+\begin{verbatim}
+ DLT-${Year}-${Month:p/2/0/r}-${Day:p/2/0/r}
+\end{verbatim}
+\normalsize
+
+on 20 June 2003 would give {\bf DLT-2003-06-20}
+
+If you set the environment variable {\bf mon} to
+
+\footnotesize
+\begin{verbatim}
+ January|February|March|April|May|...
+ File-${mon[${Month}]}/${Day}/${Year}
+\end{verbatim}
+\normalsize
+
+on the first of March would give {\bf File-March/1/2003 }
--- /dev/null
+%%
+%%
+
+% TODO: this chapter name is confusing ... maybe rename to
+% TODO: "File Integrity Checking with Bacula"?
+\chapter{Using Bacula to Improve Computer Security}
+\label{VerifyChapter}
+\index[general]{Security!Using Bacula to Improve Computer }
+\index[general]{Using Bacula to Improve Computer Security }
+
+% TODO: only those two digest algorithms?
+% TODO: can it use multiple at a time? (record and use both SHA1 and MD5?)
+Since Bacula maintains a catalog of files, their attributes, and either SHA1
+or MD5 signatures, it can be an ideal tool for improving computer security.
+This is done by making a snapshot of your system files with a {\bf Verify} Job
+and then checking the current state of your system against the snapshot, on a
+regular basis (e.g. nightly).
+
+The first step is to set up a {\bf Verify} Job and to run it with:
+
+\footnotesize
+\begin{verbatim}
+Level = InitCatalog
+\end{verbatim}
+\normalsize
+
+The {\bf InitCatalog} level tells {\bf Bacula} simply to get the information on
+the specified files and to put it into the catalog. That is your database is
+initialized and no comparison is done. The {\bf InitCatalog} is normally run
+one time manually.
+
+Thereafter, you will run a Verify Job on a daily (or whatever) basis with:
+
+\footnotesize
+\begin{verbatim}
+Level = Catalog
+\end{verbatim}
+\normalsize
+
+The {\bf Level = Catalog} level tells Bacula to compare the current state of
+the files on the Client to the last {\bf InitCatalog} that is stored in the
+catalog and to report any differences. See the example below for the format of
+the output.
+
+You decide what files you want to form your "snapshot" by specifying them in
+a {\bf FileSet} resource, and normally, they will be system files that do not
+change, or that only certain features change.
+
+Then you decide what attributes of each file you want compared by specifying
+comparison options on the {\bf Include} statements that you use in the {\bf
+FileSet} resource of your {\bf Catalog} Jobs.
+
+\section{The Details}
+\index[general]{Details }
+
+In the discussion that follows, we will make reference to the Verify
+Configuration Example that is included below in the {\bf A Verify
+Configuration Example} section. You might want to look it over now to get an
+idea of what it does.
+
+The main elements consist of adding a schedule, which will normally be run
+daily, or perhaps more often. This is provided by the {\bf VerifyCycle}
+Schedule, which runs at 5:05 in the morning every day.
+
+Then you must define a Job, much as is done below. We recommend that the Job
+name contain the name of your machine as well as the word {\bf Verify} or {\bf
+Check}. In our example, we named it {\bf MatouVerify}. This will permit you to
+easily identify your job when running it from the Console.
+
+You will notice that most records of the Job are quite standard, but that the
+{\bf FileSet} resource contains {\bf verify=pins1} option in addition to the
+standard {\bf signature=SHA1} option. If you don't want SHA1 signature
+comparison, and we cannot imagine why not, you can drop the {\bf
+signature=SHA1} and none will be computed nor stored in the catalog. Or
+alternatively, you can use {\bf verify=pins5} and {\bf signature=MD5}, which
+will use the MD5 hash algorithm. The MD5 hash computes faster than SHA1, but
+is cryptographically less secure.
+
+The {\bf verify=pins1} is ignored during the {\bf InitCatalog} Job, but is
+used during the subsequent {\bf Catalog} Jobs to specify what attributes of
+the files should be compared to those found in the catalog. {\bf pins1} is a
+reasonable set to begin with, but you may want to look at the details of these
+and other options. They can be found in the
+\ilink{FileSet Resource}{FileSetResource} section of this manual.
+Briefly, however, the {\bf p} of the {\bf pins1} tells Verify to compare the
+permissions bits, the {\bf i} is to compare inodes, the {\bf n} causes
+comparison of the number of links, the {\bf s} compares the file size, and the
+{\bf 1} compares the SHA1 checksums (this requires the {\bf signature=SHA1}
+option to have been set also).
+
+You must also specify the {\bf Client} and the {\bf Catalog} resources for
+your Verify job, but you probably already have them created for your client
+and do not need to recreate them, they are included in the example below for
+completeness.
+
+As mentioned above, you will need to have a {\bf FileSet} resource for the
+Verify job, which will have the additional {\bf verify=pins1} option. You will
+want to take some care in defining the list of files to be included in your
+{\bf FileSet}. Basically, you will want to include all system (or other) files
+that should not change on your system. If you select files, such as log files
+or mail files, which are constantly changing, your automatic Verify job will
+be constantly finding differences. The objective in forming the FileSet is to
+choose all unchanging important system files. Then if any of those files has
+changed, you will be notified, and you can determine if it changed because you
+loaded a new package, or because someone has broken into your computer and
+modified your files. The example below shows a list of files that I use on my
+Red Hat 7.3 system. Since I didn't spend a lot of time working on it, it
+probably is missing a few important files (if you find one, please send it to
+me). On the other hand, as long as I don't load any new packages, none of
+these files change during normal operation of the system.
+
+\section{Running the Verify}
+\index[general]{Running the Verify }
+\index[general]{Verify!Running the }
+
+The first thing you will want to do is to run an {\bf InitCatalog} level
+Verify Job. This will initialize the catalog to contain the file information
+that will later be used as a basis for comparisons with the actual file
+system, thus allowing you to detect any changes (and possible intrusions into
+your system).
+
+The easiest way to run the {\bf InitCatalog} is manually with the console
+program by simply entering {\bf run}. You will be presented with a list of
+Jobs that can be run, and you will choose the one that corresponds to your
+Verify Job, {\bf MatouVerify} in this example.
+
+\footnotesize
+\begin{verbatim}
+The defined Job resources are:
+ 1: MatouVerify
+ 2: kernsrestore
+ 3: Filetest
+ 4: kernsave
+Select Job resource (1-4): 1
+\end{verbatim}
+\normalsize
+
+Next, the console program will show you the basic parameters of the Job and
+ask you:
+
+\footnotesize
+\begin{verbatim}
+Run Verify job
+JobName: MatouVerify
+FileSet: Verify Set
+Level: Catalog
+Client: MatouVerify
+Storage: DLTDrive
+OK to run? (yes/mod/no): mod
+\end{verbatim}
+\normalsize
+
+Here, you want to respond {\bf mod} to modify the parameters because the Level
+is by default set to {\bf Catalog} and we want to run an {\bf InitCatalog}
+Job. After responding {\bf mod}, the console will ask:
+
+\footnotesize
+\begin{verbatim}
+Parameters to modify:
+ 1: Job
+ 2: Level
+ 3: FileSet
+ 4: Client
+ 5: Storage
+Select parameter to modify (1-5): 2
+\end{verbatim}
+\normalsize
+
+you should select number 2 to modify the {\bf Level}, and it will display:
+
+\footnotesize
+\begin{verbatim}
+Levels:
+ 1: Initialize Catalog
+ 2: Verify from Catalog
+ 3: Verify Volume
+ 4: Verify Volume Data
+Select level (1-4): 1
+\end{verbatim}
+\normalsize
+
+Choose item 1, and you will see the final display:
+
+\footnotesize
+\begin{verbatim}
+Run Verify job
+JobName: MatouVerify
+FileSet: Verify Set
+Level: Initcatalog
+Client: MatouVerify
+Storage: DLTDrive
+OK to run? (yes/mod/no): yes
+\end{verbatim}
+\normalsize
+
+at which point you respond {\bf yes}, and the Job will begin.
+
+Thereafter the Job will automatically start according to the schedule you
+have defined. If you wish to immediately verify it, you can simply run a
+Verify {\bf Catalog} which will be the default. No differences should be
+found.
+
+\section{What To Do When Differences Are Found}
+\index[general]{What To Do When Differences Are Found }
+\index[general]{Found!What To Do When Differences Are }
+
+If you have setup your messages correctly, you should be notified if there are
+any differences and exactly what they are. For example, below is the email
+received after doing an update of OpenSSH:
+
+\footnotesize
+\begin{verbatim}
+HeadMan: Start Verify JobId 83 Job=RufusVerify.2002-06-25.21:41:05
+HeadMan: Verifying against Init JobId 70 run 2002-06-21 18:58:51
+HeadMan: File: /etc/pam.d/sshd
+HeadMan: st_ino differ. Cat: 4674b File: 46765
+HeadMan: File: /etc/rc.d/init.d/sshd
+HeadMan: st_ino differ. Cat: 56230 File: 56231
+HeadMan: File: /etc/ssh/ssh_config
+HeadMan: st_ino differ. Cat: 81317 File: 8131b
+HeadMan: st_size differ. Cat: 1202 File: 1297
+HeadMan: SHA1 differs.
+HeadMan: File: /etc/ssh/sshd_config
+HeadMan: st_ino differ. Cat: 81398 File: 81325
+HeadMan: st_size differ. Cat: 1182 File: 1579
+HeadMan: SHA1 differs.
+HeadMan: File: /etc/ssh/ssh_config.rpmnew
+HeadMan: st_ino differ. Cat: 812dd File: 812b3
+HeadMan: st_size differ. Cat: 1167 File: 1114
+HeadMan: SHA1 differs.
+HeadMan: File: /etc/ssh/sshd_config.rpmnew
+HeadMan: st_ino differ. Cat: 81397 File: 812dd
+HeadMan: st_size differ. Cat: 2528 File: 2407
+HeadMan: SHA1 differs.
+HeadMan: File: /etc/ssh/moduli
+HeadMan: st_ino differ. Cat: 812b3 File: 812ab
+HeadMan: File: /usr/bin/scp
+HeadMan: st_ino differ. Cat: 5e07e File: 5e343
+HeadMan: st_size differ. Cat: 26728 File: 26952
+HeadMan: SHA1 differs.
+HeadMan: File: /usr/bin/ssh-keygen
+HeadMan: st_ino differ. Cat: 5df1d File: 5e07e
+HeadMan: st_size differ. Cat: 80488 File: 84648
+HeadMan: SHA1 differs.
+HeadMan: File: /usr/bin/sftp
+HeadMan: st_ino differ. Cat: 5e2e8 File: 5df1d
+HeadMan: st_size differ. Cat: 46952 File: 46984
+HeadMan: SHA1 differs.
+HeadMan: File: /usr/bin/slogin
+HeadMan: st_ino differ. Cat: 5e359 File: 5e2e8
+HeadMan: File: /usr/bin/ssh
+HeadMan: st_mode differ. Cat: 89ed File: 81ed
+HeadMan: st_ino differ. Cat: 5e35a File: 5e359
+HeadMan: st_size differ. Cat: 219932 File: 234440
+HeadMan: SHA1 differs.
+HeadMan: File: /usr/bin/ssh-add
+HeadMan: st_ino differ. Cat: 5e35b File: 5e35a
+HeadMan: st_size differ. Cat: 76328 File: 81448
+HeadMan: SHA1 differs.
+HeadMan: File: /usr/bin/ssh-agent
+HeadMan: st_ino differ. Cat: 5e35c File: 5e35b
+HeadMan: st_size differ. Cat: 43208 File: 47368
+HeadMan: SHA1 differs.
+HeadMan: File: /usr/bin/ssh-keyscan
+HeadMan: st_ino differ. Cat: 5e35d File: 5e96a
+HeadMan: st_size differ. Cat: 139272 File: 151560
+HeadMan: SHA1 differs.
+HeadMan: 25-Jun-2002 21:41
+JobId: 83
+Job: RufusVerify.2002-06-25.21:41:05
+FileSet: Verify Set
+Verify Level: Catalog
+Client: RufusVerify
+Start time: 25-Jun-2002 21:41
+End time: 25-Jun-2002 21:41
+Files Examined: 4,258
+Termination: Verify Differences
+\end{verbatim}
+\normalsize
+
+At this point, it was obvious that these files were modified during
+installation of the RPMs. If you want to be super safe, you should run a {\bf
+Verify Level=Catalog} immediately before installing new software to verify
+that there are no differences, then run a {\bf Verify Level=InitCatalog}
+immediately after the installation.
+
+To keep the above email from being sent every night when the Verify Job runs,
+we simply re-run the Verify Job setting the level to {\bf InitCatalog} (as we
+did above in the very beginning). This will re-establish the current state of
+the system as your new basis for future comparisons. Take care that you don't
+do an {\bf InitCatalog} after someone has placed a Trojan horse on your
+system!
+
+If you have included in your {\bf FileSet} a file that is changed by the
+normal operation of your system, you will get false matches, and you will need
+to modify the {\bf FileSet} to exclude that file (or not to Include it), and
+then re-run the {\bf InitCatalog}.
+
+The FileSet that is shown below is what I use on my Red Hat 7.3 system. With a
+bit more thought, you can probably add quite a number of additional files that
+should be monitored.
+
+\section{A Verify Configuration Example}
+\index[general]{Verify Configuration Example }
+\index[general]{Example!Verify Configuration }
+
+\footnotesize
+\begin{verbatim}
+Schedule {
+ Name = "VerifyCycle"
+ Run = Level=Catalog sun-sat at 5:05
+}
+Job {
+ Name = "MatouVerify"
+ Type = Verify
+ Level = Catalog # default level
+ Client = MatouVerify
+ FileSet = "Verify Set"
+ Messages = Standard
+ Storage = DLTDrive
+ Pool = Default
+ Schedule = "VerifyCycle"
+}
+#
+# The list of files in this FileSet should be carefully
+# chosen. This is a good starting point.
+#
+FileSet {
+ Name = "Verify Set"
+ Include {
+ Options {
+ verify=pins1
+ signature=SHA1
+ }
+ File = /boot
+ File = /bin
+ File = /sbin
+ File = /usr/bin
+ File = /lib
+ File = /root/.ssh
+ File = /home/kern/.ssh
+ File = /var/named
+ File = /etc/sysconfig
+ File = /etc/ssh
+ File = /etc/security
+ File = /etc/exports
+ File = /etc/rc.d/init.d
+ File = /etc/sendmail.cf
+ File = /etc/sysctl.conf
+ File = /etc/services
+ File = /etc/xinetd.d
+ File = /etc/hosts.allow
+ File = /etc/hosts.deny
+ File = /etc/hosts
+ File = /etc/modules.conf
+ File = /etc/named.conf
+ File = /etc/pam.d
+ File = /etc/resolv.conf
+ }
+ Exclude = { }
+P
+Client {
+ Name = MatouVerify
+ Address = lmatou
+ Catalog = Bacula
+ Password = ""
+ File Retention = 80d # 80 days
+ Job Retention = 1y # one year
+ AutoPrune = yes # Prune expired Jobs/Files
+}
+Catalog {
+ Name = Bacula
+ dbname = verify; user = bacula; password = ""
+}
+\end{verbatim}
+\normalsize
--- /dev/null
+2.3.6 (04 November 2007)
--- /dev/null
+@VERSION@ (@DATE@)
--- /dev/null
+%%
+%%
+
+\chapter{The Windows Version of Bacula}
+\label{Win32Chapter}
+\index[general]{Windows Version of Bacula}
+
+At the current time only the File daemon or Client program has
+been thouroughly tested on Windows and is suitable for a
+production environment. As a consequence, when we
+speak of the Windows version of Bacula below, we are referring to
+the File daemon (client) only.
+
+As of Bacula version 1.39.20 or greater, the installer is capable
+of installing not just the Client program, but also the Director
+and the Storage daemon and all the other programs that were
+previously available only on Unix systems. These additional
+programs, notably the Director and Storage daemon, have been partially
+tested, are reported to have some bugs, and still need to be documented.
+They are not yet supported, and we cannot currently accept or fix
+bug reports on them. Consequently, please test them carefully before putting
+them into a critical production environment.
+
+The Windows version of the Bacula File daemon has been tested on Win98, WinMe,
+WinNT, WinXP, Win2000, and Windows 2003 systems. We have coded to support
+Win95, but no longer have a system for testing. The Windows version of
+Bacula is a native Win32 port, but there are very few source code changes
+to the Unix code, which means that the Windows version is for the most part
+running code that has long proved stable on Unix systems. When running, it
+is perfectly integrated with Windows and displays its icon in the system
+icon tray, and provides a system tray menu to obtain additional information
+on how Bacula is running (status and events dialog boxes). If so desired,
+it can also be stopped by using the system tray menu, though this should
+normally never be necessary.
+
+Once installed Bacula normally runs as a system service. This means that it is
+immediately started by the operating system when the system is booted, and
+runs in the background even if there is no user logged into the system.
+
+\section{Win32 Installation}
+\label{installation}
+\index[general]{Installation}
+\index[general]{Win32!Installation}
+
+Normally, you will install the Windows version of Bacula from the binaries.
+This install is standard Windows .exe that runs an install wizard using the
+NSIS Free Software installer, so if you have already installed Windows
+software, it should be very familiar to you.
+
+If you have a previous version Bacula (1.39.20 or lower)
+installed, you should stop the service, uninstall it, and remove
+the Bacula installation directory possibly saving your
+bacula-fd.conf, bconsole.conf, and bwx-console.conf files
+for use with the new version you will install. The Uninstall
+program is normally found in {\bf c:\textbackslash{}bacula\textbackslash{}Uninstall.exe}.
+We also recommend that you completely remove the directory
+{\bf c:\textbackslash{}bacula}, because the current installer
+uses a different directory structure (see below).
+
+Providing you do not already have Bacula installed,
+the new installer (1.39.22 and later) installs the binaries and dlls in
+c:\textbackslash{}Program Files\textbackslash{}Bacula\textbackslash{}bin
+and the configuration files
+in c:\textbackslash{}Documents and Settings\textbackslash{}All Users\textbackslash{}Application Data\textbackslash{}Bacula
+In addition, the {\bf Start\-\gt{}All Programs\-\gt{}Bacula} menu item
+will be created during the installation, and on that menu, you
+will find items for editing the configuration files, displaying
+the document, and starting bwx-console or bconsole.
+
+
+Finally, proceed with the installation.
+
+\begin{itemize}
+\item You must be logged in as Administrator to the local machine
+to do a correct installation, if not, please do so before continuing.
+Some users have attempted to install logged in as a domain administrator
+account and experienced permissions problems attempting to run
+Bacula, so we don't recommend that option.
+
+\item Simply double click on the {\bf winbacula-1.xx.0.exe} NSIS install
+ icon. The actual name of the icon will vary from one release version to
+ another.
+
+\includegraphics{./win32-nsis.eps} winbacula-1.xx.0.exe
+
+\item Once launched, the installer wizard will ask you if you want to install
+ Bacula.
+
+\addcontentsline{lof}{figure}{Win32 Client Setup Wizard}
+\includegraphics{./win32-welcome.eps}
+
+\item Next you will be asked to select the installation type.
+
+\addcontentsline{lof}{figure}{Win32 Installation Type}
+\includegraphics{./win32-installation-type.eps}
+
+
+\item If you proceed, you will be asked to select the components to be
+ installed. You may install the Bacula program (Bacula File Service) and or
+ the documentation. Both will be installed in sub-directories of the install
+ location that you choose later. The components dialog looks like the
+ following:
+
+\addcontentsline{lof}{figure}{Win32 Component Selection Dialog}
+\includegraphics{./win32-pkg.eps}
+\index[general]{Upgrading}
+
+\item If you are installing for the first time, you will be asked to
+ enter some very basic information about your configuration. If
+ you are not sure what to enter, or have previously saved configuration
+ files, you can put anything you want into the fields, then either
+ replace the configuration files later with the ones saved, or edit
+ the file.
+
+ If you are upgrading an existing installation, the following will
+ not be displayed.
+
+
+\addcontentsline{lof}{figure}{Win32 Configure}
+\includegraphics{./win32-config.eps}
+
+\item While the various files are being loaded, you will see the following
+ dialog:
+
+ \addcontentsline{lof}{figure}{Win32 Install Progress}
+ \includegraphics{./win32-installing.eps}
+
+
+\item Finally, the finish dialog will appear:
+
+ \addcontentsline{lof}{figure}{Win32 Client Setup Completed}
+ \includegraphics{./win32-finish.eps}
+
+\
+\end{itemize}
+
+That should complete the installation process. When the Bacula File Server is
+ready to serve files, an icon \includegraphics{./idle.eps} representing a
+cassette (or tape) will appear in the system tray
+\includegraphics{./tray-icon.eps}; right click on it and a menu will appear.\\
+\includegraphics{./menu.eps}\\
+The {\bf Events} item is currently unimplemented, by selecting the {\bf
+Status} item, you can verify whether any jobs are running or not.
+
+When the Bacula File Server begins saving files, the color of the holes in the
+cassette icon will change from white to green \includegraphics{./running.eps},
+and if there is an error, the holes in the cassette icon will change to red
+\includegraphics{./error.eps}.
+
+If you are using remote desktop connections between your Windows boxes, be
+warned that that tray icon does not always appear. It will always be visible
+when you log into the console, but the remote desktop may not display it.
+
+\section{Post Win32 Installation}
+\index[general]{Post Win32 Installation}
+\index[general]{Win32!Post Installation}
+
+After installing Bacula and before running it, you should check the contents
+of the configuration files to ensure that they correspond to your
+installation. You can get to them by using:
+the {\bf Start\-\gt{}All Programs\-\gt{}Bacula} menu item.
+
+Finally, but pulling up the Task Manager (ctl-alt-del), verify that Bacula
+is running as a process (not an Application) with User Name SYSTEM. If this is
+not the case, you probably have not installed Bacula while running as
+Administrator, and hence it will be unlikely that Bacula can access
+all the system files.
+
+\section{Uninstalling Bacula on Win32}
+\index[general]{Win32!Uninstalling Bacula}
+\index[general]{Uninstalling Bacula on Win32}
+
+Once Bacula has been installed, it can be uninstalled using the standard
+Windows Add/Remove Programs dialog found on the Control panel.
+
+\section{Dealing with Win32 Problems}
+\label{problems}
+\index[general]{Win32!Dealing with Problems}
+\index[general]{Dealing with Win32 Problems}
+
+Sometimes Win32 machines the File daemon may have very slow
+backup transfer rates compared to other machines. To you might
+try setting the Maximum Network Buffer Size to 32,768 in both the
+File daemon and in the Storage daemon. The default size is larger,
+and apparently some Windows ethernet controllers do not deal with
+a larger network buffer size.
+
+Many Windows ethernet drivers have a tendency to either run slowly
+due to old broken firmware, or because they are running in half-duplex
+mode. Please check with the ethernet card manufacturer for the latest
+firmware and use whatever techniques are necessary to ensure that the
+card is running in duplex.
+
+If you are not using the portable option, and you have VSS
+(Volume Shadow Copy) enabled in the Director, and you experience
+problems with Bacula not being able to open files, it is most
+likely that you are running an antivirus program that blocks
+Bacula from doing certain operations. In this case, disable the
+antivirus program and try another backup. If it succeeds, either
+get a different (better) antivirus program or use something like
+RunClientJobBefore/After to turn off the antivirus program while
+the backup is running.
+
+If turning off anti-virus software does not resolve your VSS
+problems, you might have to turn on VSS debugging. The following
+link describes how to do this:
+\elink{http://support.microsoft.com/kb/887013/en-us}{\url{http://support.microsoft.com/kb/887013/en-us}}.
+
+In Microsoft Windows Small Business Server 2003 the VSS Writer for Exchange
+is turned off by default. To turn it on, please see the following link:
+\elink{http://support.microsoft.com/default.aspx?scid=kb;EN-US;Q838183}{\url{
+http://support.microsoft.com/default.aspx?scid=kb;EN-US;Q838183}}
+
+
+The most likely source of problems is authentication when the Director
+attempts to connect to the File daemon that you installed. This can occur if
+the names and the passwords defined in the File daemon's configuration file
+{\bf bacula-fd.conf} file on
+the Windows machine do not match with the names and the passwords in the
+Director's configuration file {\bf bacula-dir.conf} located on your Unix/Linux
+server.
+
+More specifically, the password found in the {\bf Client} resource in the
+Director's configuration file must be the same as the password in the {\bf
+Director} resource of the File daemon's configuration file. In addition, the
+name of the {\bf Director} resource in the File daemon's configuration file
+must be the same as the name in the {\bf Director} resource of the Director's
+configuration file.
+
+It is a bit hard to explain in words, but if you understand that a Director
+normally has multiple Clients and a Client (or File daemon) may permit access
+by multiple Directors, you can see that the names and the passwords on both
+sides must match for proper authentication.
+
+One user had serious problems with the configuration file until he realized
+that the Unix end of line conventions were used and Bacula wanted them in
+Windows format. This has not been confirmed though, and Bacula version 2.0.0
+and above should now accept all end of line conventions (Win32,
+Unix, Mac).
+
+Running Unix like programs on Windows machines is a bit frustrating because
+the Windows command line shell (DOS Window) is rather primitive. As a
+consequence, it is not generally possible to see the debug information and
+certain error messages that Bacula prints. With a bit of work, however, it is
+possible. When everything else fails and you want to {\bf see} what is going
+on, try the following:
+
+\footnotesize
+\begin{verbatim}
+ Start a DOS shell Window.
+ c:\Program Files\bacula\bin\bacula-fd -t >out
+ type out
+\end{verbatim}
+\normalsize
+
+The precise path to bacula-fd depends on where it is installed. The
+example above is the default used in 1.39.22 and later.
+The {\bf -t} option will cause Bacula to read the configuration file, print
+any error messages and then exit. the {\bf \gt{}} redirects the output to the
+file named {\bf out}, which you can list with the {\bf type} command.
+
+If something is going wrong later, or you want to run {\bf Bacula} with a
+debug option, you might try starting it as:
+
+\footnotesize
+\begin{verbatim}
+ c:\Program Files\bacula\bin\bacula-fd -d 100 >out
+\end{verbatim}
+\normalsize
+
+In this case, Bacula will run until you explicitly stop it, which will give
+you a chance to connect to it from your Unix/Linux server. In later versions
+of Bacula (1.34 on, I think), when you start the File daemon in debug mode it
+can write the output to a trace file {\bf bacula.trace} in the current
+directory. To enable this, before running a job, use the console, and enter:
+
+\footnotesize
+\begin{verbatim}
+ trace on
+\end{verbatim}
+\normalsize
+
+then run the job, and once you have terminated the File daemon, you will find
+the debug output in the {\bf bacula.trace} file, which will probably be
+located in the same directory as bacula-fd.exe.
+
+In addition, you should look in the System Applications log on the Control
+Panel to find any Windows errors that Bacula got during the startup process.
+
+Finally, due to the above problems, when you turn on debugging, and specify
+trace=1 on a setdebug command in the Console, Bacula will write the debug
+information to the file {\bf bacula.trace} in the directory from which Bacula
+is executing.
+
+If you are having problems with ClientRunBeforeJob scripts randomly dying,
+it is possible that you have run into an Oracle bug. See bug number 622 in
+the bugs.bacula.org database. The following information has been
+provided by a user on this issue:
+
+\footnotesize
+\begin{verbatim}
+The information in this document applies to:
+ Oracle HTTP Server - Version: 9.0.4
+ Microsoft Windows Server 2003
+ Symptoms
+ When starting an OC4J instance, the System Clock runs faster, about 7
+seconds per minute.
+
+ Cause
+
+ + This is caused by the Sun JVM bug 4500388, which states that "Calling
+Thread.sleep() with a small argument affects the system clock". Although
+this is reported as fixed in JDK 1.4.0_02, several reports contradict this
+(see the bug in
+http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4500388).
+
+ + Also reported by Microsoft as "The system clock may run fast when you
+use the ACPI power management timer as a high-resolution counter on Windows
+2000-based computers" (See http://support.microsoft.com/?id=821893)
+\end{verbatim}
+\normalsize
+
+You may wish to start the daemon with debug mode on rather than doing it
+using bconsole. To do so, edit the following registry key:
+
+\footnotesize
+\begin{verbatim}
+HKEY_LOCAL_MACHINE\HARDWARE\SYSTEM\CurrentControlSet\Services\Bacula-dir
+\end{verbatim}
+\normalsize
+
+using regedit, then add -dnn after the /service option, where nn represents
+the debug level you want.
+
+\label{Compatibility}
+\section{Windows Compatibility Considerations}
+\index[general]{Windows Compatibility Considerations}
+\index[general]{Considerations!Windows Compatibility}
+
+If you are not using the VSS (Volume Shadow Copy) option described in the
+next section of this chapter, and if any applications are running during
+the backup and they have files opened exclusively, Bacula will not be able
+to backup those files, so be sure you close your applications (or tell your
+users to close their applications) before the backup. Fortunately, most
+Microsoft applications do not open files exclusively so that they can be
+backed up. However, you will need to experiment. In any case, if Bacula
+cannot open the file, it will print an error message, so you will always
+know which files were not backed up. For version 1.37.25 and greater, see
+the section below on Volume Shadow Copy Service that permits backing up any
+file.
+
+During backup, Bacula doesn't know about the system registry, so you will
+either need to write it out to an ASCII file using {\bf regedit~~/e} or use a
+program specifically designed to make a copy or backup the registry.
+
+In Bacula version 1.31 and later, we use Windows backup API calls by
+default. Typical of Windows, programming these special BackupRead and
+BackupWrite calls is a real nightmare of complications. The end result
+gives some distinct advantages and some disadvantages.
+
+First, the advantages are that on WinNT/2K/XP systems, the security and
+ownership information is now backed up. In addition, with the exception of
+files in exclusive use by another program, Bacula can now access all system
+files. This means that when you restore files, the security and ownership
+information will be restored on WinNT/2K/XP along with the data.
+
+The disadvantage of the Windows backup API calls is that it produces
+non-portable backups. That is files and their data that are backed up on
+WinNT using the native API calls (BackupRead/BackupWrite) cannot be
+restored on Win95/98/Me or Unix systems. In principle, a file backed up on
+WinNT can be restored on WinXP, but this remains to be seen in practice
+(not yet tested). In addition, the stand-alone tools such as {\bf bls} and
+{\bf bextract} cannot be used to retrieve the data for those files because
+those tools are not available on Windows. All restores must use the Bacula
+{\bf restore} command. As of Bacula 1.39.x, thanks to Thorsten Engel, this
+restriction is removed, and Bacula should be able to read non-portable
+backups on any system and restore the data appropriately. However,
+on a system that does not have the BackupRead/BackupWrite calls (older
+Windows versions and all Unix/Linux machines), though the file data
+can be restored, the Windows security and access control data will not be restored.
+This means that a standard set of access permissions will be set for
+such restored files.
+
+
+As a default, Bacula backs up Windows systems using the Windows API calls.
+If you want to backup data on a WinNT/2K/XP system and restore it on a
+Unix/Win95/98/Me system, we have provided a special {\bf portable} option
+that backs up the data in a portable fashion by using portable API calls.
+See the \ilink{portable option}{portable} on the Include statement in a
+FileSet resource in the Director's configuration chapter for the details on
+setting this option. However, using the portable option means you may have
+permissions problems accessing files, and none of the security and
+ownership information will be backed up or restored. The file data can,
+however, be restored on any system.
+
+You should always be able to restore any file backed up on Unix or Win95/98/Me
+to any other system. On some systems, such as WinNT/2K/XP, you may have to
+reset the ownership of such restored files. Any file backed up on WinNT/2K/XP
+should in principle be able to be restored to a similar system (i.e.
+WinNT/2K/XP), however, I am unsure of the consequences if the owner
+information and accounts are not identical on both systems. Bacula will not
+let you restore files backed up on WinNT/2K/XP to any other system (i.e. Unix
+Win95/98/Me) if you have used the defaults.
+
+Finally, if you specify the {\bf portable=yes} option on the files you back
+up. Bacula will be able to restore them on any other system. However, any
+WinNT/2K/XP specific security and ownership information will be lost.
+
+The following matrix will give you an idea of what you can expect. Thanks to
+Marc Brueckner for doing the tests:
+
+\addcontentsline{lot}{table}{WinNT/2K/XP Restore Portability Status}
+\begin{longtable}{|l|l|p{2.8in}|}
+ \hline
+\multicolumn{1}{|c|}{\bf Backup OS} & \multicolumn{1}{c|}{\bf Restore OS}
+& \multicolumn{1}{c|}{\bf Results } \\
+ \hline {WinMe} & {WinMe} & {Works } \\
+ \hline {WinMe} & {WinNT} & {Works (SYSTEM permissions) } \\
+ \hline {WinMe} & {WinXP} & {Works (SYSTEM permissions) } \\
+ \hline {WinMe} & {Linux} & {Works (SYSTEM permissions) } \\
+ \hline {\ } & {\ } & {\ } \\
+ \hline {WinXP} & {WinXP} & {Works } \\
+ \hline {WinXP} & {WinNT} & {Works (all files OK, but got "The data is invalid"
+message) } \\
+ \hline {WinXP} & {WinMe} & {Error: Win32 data stream not supported. } \\
+ \hline {WinXP} & {WinMe} & {Works if {\bf Portable=yes} specified during backup.} \\
+ \hline {WinXP} & {Linux} & {Error: Win32 data stream not supported. } \\
+ \hline {WinXP} & {Linux} & {Works if {\bf Portable=yes} specified during backup.}\\
+ \hline {\ } & {\ } & {\ } \\
+ \hline {WinNT} & {WinNT} & {Works } \\
+ \hline {WinNT} & {WinXP} & {Works } \\
+ \hline {WinNT} & {WinMe} & {Error: Win32 data stream not supported. } \\
+ \hline {WinNT} & {WinMe} & {Works if {\bf Portable=yes} specified during backup.}\\
+ \hline {WinNT} & {Linux} & {Error: Win32 data stream not supported. } \\
+ \hline {WinNT} & {Linux} & {Works if {\bf Portable=yes} specified during backup. }\\
+ \hline {\ } & {\ } & {\ } \\
+ \hline {Linux} & {Linux} & {Works } \\
+ \hline {Linux} & {WinNT} & {Works (SYSTEM permissions) } \\
+ \hline {Linux} & {WinMe} & {Works } \\
+ \hline {Linux} & {WinXP} & {Works (SYSTEM permissions)}
+\\ \hline
+\end{longtable}
+
+Note: with Bacula versions 1.39.x and later, non-portable Windows data can
+be restore to any machine.
+
+
+\label{VSS}
+\section{Volume Shadow Copy Service}
+\index[general]{Volume Shadow Copy Service}
+\index[general]{VSS}
+In version 1.37.30 and greater, you can turn on Microsoft's Volume
+Shadow Copy Service (VSS).
+
+Microsoft added VSS to Windows XP and Windows 2003. From the perspective of
+a backup-solution for Windows, this is an extremely important step. VSS
+allows Bacula to backup open files and even to interact with applications like
+RDBMS to produce consistent file copies. VSS aware applications are called
+VSS Writers, they register with the OS so that when Bacula wants to do a
+Snapshot, the OS will notify the register Writer programs, which may then
+create a consistent state in their application, which will be backed up.
+Examples for these writers are "MSDE" (Microsoft database
+engine), "Event Log Writer", "Registry Writer" plus 3rd
+party-writers. If you have a non-vss aware application (e.g.
+SQL Anywhere or probably MySQL), a shadow copy is still generated
+and the open files can be backed up, but there is no guarantee
+that the file is consistent.
+
+Bacula produces a message from each of the registered writer programs
+when it is doing a VSS backup so you know which ones are correctly backed
+up.
+
+Bacula supports VSS on both Windows 2003 and Windows XP.
+Technically Bacula creates a shadow copy as soon as the backup process
+starts. It does then backup all files from the shadow copy and destroys the
+shadow copy after the backup process. Please have in mind, that VSS
+creates a snapshot and thus backs up the system at the state it had
+when starting the backup. It will disregard file changes which occur during
+the backup process.
+
+VSS can be turned on by placing an
+
+\index[dir]{Enable VSS}
+\index[general]{Enable VSS}
+\begin{verbatim}
+Enable VSS = yes
+\end{verbatim}
+
+in your FileSet resource.
+
+The VSS aware File daemon has the letters VSS on the signon line that
+it produces when contacted by the console. For example:
+\begin{verbatim}
+Tibs-fd Version: 1.37.32 (22 July 2005) VSS Windows XP MVS NT 5.1.2600
+\end{verbatim}
+the VSS is shown in the line above. This only means that the File daemon
+is capable of doing VSS not that VSS is turned on for a particular backup.
+There are two ways of telling if VSS is actually turned on during a backup.
+The first is to look at the status output for a job, e.g.:
+\footnotesize
+\begin{verbatim}
+Running Jobs:
+JobId 1 Job NightlySave.2005-07-23_13.25.45 is running.
+ VSS Backup Job started: 23-Jul-05 13:25
+ Files=70,113 Bytes=3,987,180,650 Bytes/sec=3,244,247
+ Files Examined=75,021
+ Processing file: c:/Documents and Settings/kern/My Documents/My Pictures/Misc1/Sans titre - 39.pdd
+ SDReadSeqNo=5 fd=352
+\end{verbatim}
+\normalsize
+Here, you see under Running Jobs that JobId 1 is "VSS Backup Job started ..."
+This means that VSS is enabled for that job. If VSS is not enabled, it will
+simply show "Backup Job started ..." without the letters VSS.
+
+The second way to know that the job was backed up with VSS is to look at the
+Job Report, which will look something like the following:
+\footnotesize
+\begin{verbatim}
+23-Jul 13:25 rufus-dir: Start Backup JobId 1, Job=NightlySave.2005-07-23_13.25.45
+23-Jul 13:26 rufus-sd: Wrote label to prelabeled Volume "TestVolume001" on device "DDS-4" (/dev/nst0)
+23-Jul 13:26 rufus-sd: Spooling data ...
+23-Jul 13:26 Tibs: Generate VSS snapshots. Driver="VSS WinXP", Drive(s)="C"
+23-Jul 13:26 Tibs: VSS Writer: "MSDEWriter", State: 1 (VSS_WS_STABLE)
+23-Jul 13:26 Tibs: VSS Writer: "Microsoft Writer (Bootable State)", State: 1 (VSS_WS_STABLE)
+23-Jul 13:26 Tibs: VSS Writer: "WMI Writer", State: 1 (VSS_WS_STABLE)
+23-Jul 13:26 Tibs: VSS Writer: "Microsoft Writer (Service State)", State: 1 (VSS_WS_STABLE)
+\end{verbatim}
+\normalsize
+In the above Job Report listing, you see that the VSS snapshot was generated for drive C (if
+other drives are backed up, they will be listed on the {\bf Drive(s)="C"} You also see the
+reports from each of the writer program. Here they all report VSS\_WS\_STABLE, which means
+that you will get a consistent snapshot of the data handled by that writer.
+
+\section{VSS Problems}
+\index[general]{Problems!VSS}
+\index[fd] {Problems!VSS}
+\index[general]{VSS Problems}
+\index[fd]{VSS Problems}
+
+If you are experiencing problems such as VSS hanging on MSDE, first try
+running {\bf vssadmin} to check for problems, then try running {\bf
+ntbackup} which also uses VSS to see if it has similar problems. If so, you
+know that the problem is in your Windows machine and not with Bacula.
+
+The FD hang problems were reported with {\bf MSDEwriter} when:
+\begin{itemize}
+\item a local firewall locked local access to the MSDE TCP port (MSDEwriter
+seems to use TCP/IP and not Named Pipes).
+\item msdtcs was installed to run under "localsystem": try running msdtcs
+under networking account (instead of local system) (com+ seems to work
+better with this configuration).
+\end{itemize}
+
+
+\section{Windows Firewalls}
+\index[general]{Firewalls!Windows}
+\index[general]{Windows Firewalls}
+
+If you turn on the firewalling feature on Windows (default in WinXP SP2), you
+are likely to find that the Bacula ports are blocked and you cannot
+communicate to the other daemons. This can be deactivated through the {\bf
+Security Notification} dialog, which is apparently somewhere in the {\bf
+Security Center}. I don't have this on my computer, so I cannot give the exact
+details.
+
+The command:
+
+\footnotesize
+\begin{verbatim}
+netsh firewall set opmode disable
+\end{verbatim}
+\normalsize
+
+is purported to disable the firewall, but this command is not accepted on my
+WinXP Home machine.
+
+\section{Windows Port Usage}
+\index[general]{Windows Port Usage}
+\index[general]{Usage!Windows Port}
+
+If you want to see if the File daemon has properly opened the port and is
+listening, you can enter the following command in a shell window:
+
+\footnotesize
+\begin{verbatim}
+ netstat -an | findstr 910[123]
+\end{verbatim}
+\normalsize
+
+TopView is another program that has been recommend, but it is not a
+standard Win32 program, so you must find and download it from the Internet.
+
+\section{Windows Disaster Recovery}
+\index[general]{Recovery!Windows Disaster}
+\index[general]{Windows Disaster Recovery}
+
+We don't currently have a good solution for disaster recovery on Windows as we
+do on Linux. The main piece lacking is a Windows boot floppy or a Windows boot
+CD. Microsoft releases a Windows Pre-installation Environment ({\bf WinPE})
+that could possibly work, but we have not investigated it. This means that
+until someone figures out the correct procedure, you must restore the OS from
+the installation disks, then you can load a Bacula client and restore files.
+Please don't count on using {\bf bextract} to extract files from your backup
+tapes during a disaster recovery unless you have backed up those files using
+the {\bf portable} option. {\bf bextract} does not run on Windows, and the
+normal way Bacula saves files using the Windows API prevents the files from
+being restored on a Unix machine. Once you have an operational Windows OS
+loaded, you can run the File daemon and restore your user files.
+
+Please see
+\ilink{ Disaster Recovery of Win32 Systems}{Win3233} for the latest
+suggestion, which looks very promising.
+
+It looks like Bart PE Builder, which creates a Windows PE (Pre-installation
+Environment) Boot-CD, may be just what is needed to build a complete disaster
+recovery system for Win32. This distribution can be found at
+\elink{http://www.nu2.nu/pebuilder/}{\url{http://www.nu2.nu/pebuilder/}}.
+
+\section{Windows Restore Problems}
+\index[general]{Problems!Windows Restore}
+\index[general]{Windows Restore Problems}
+Please see the
+\ilink{Restore Chapter}{Windows} of this manual for problems
+that you might encounter doing a restore.
+
+section{Windows Backup Problems}
+\index[general]{Problems!Windows Backup}
+\index[general]{Windows Backup Problems}
+If during a Backup, you get the message:
+{\bf ERR=Access is denied} and you are using the portable option,
+you should try both adding both the non-portable (backup API) and
+the Volume Shadow Copy options to your Director's conf file.
+
+In the Options resource:
+\footnotesize
+\begin{verbatim}
+portable = no
+\end{verbatim}
+\normalsize
+
+In the FileSet resource:
+\footnotesize
+\begin{verbatim}
+enablevss = yes
+\end{verbatim}
+\normalsize
+
+In general, specifying these two options should allow you to backup
+any file on a Windows system. However, in some cases, if users
+have allowed to have full control of their folders, even system programs
+such a Bacula can be locked out. In this case, you must identify
+which folders or files are creating the problem and do the following:
+
+\begin{enumerate}
+\item Grant ownership of the file/folder to the Administrators group,
+with the option to replace the owner on all child objects.
+\item Grant full control permissions to the Administrators group,
+and change the user's group to only have Modify permission to
+the file/folder and all child objects.
+\end{enumerate}
+
+Thanks to Georger Araujo for the above information.
+
+\section{Windows Ownership and Permissions Problems}
+\index[general]{Problems!Windows Ownership and Permissions}
+\index[general]{Windows Ownership and Permissions Problems}
+
+If you restore files backed up from WinNT/XP/2K to an alternate directory,
+Bacula may need to create some higher level directories that were not saved
+(or restored). In this case, the File daemon will create them under the SYSTEM
+account because that is the account that Bacula runs under as a service. As of
+version 1.32f-3, Bacula creates these files with full access permission.
+However, there may be cases where you have problems accessing those files even
+if you run as administrator. In principle, Microsoft supplies you with the way
+to cease the ownership of those files and thus change the permissions.
+However, a much better solution to working with and changing Win32 permissions
+is the program {\bf SetACL}, which can be found at
+\elink{http://setacl.sourceforge.net/}{\url{http://setacl.sourceforge.net/}}.
+
+If you have not installed Bacula while running as Administrator
+and if Bacula is not running as a Process with the userid (User Name) SYSTEM,
+then it is very unlikely that it will have sufficient permission to
+access all your files.
+
+Some users have experienced problems restoring files that participate in
+the Active Directory. They also report that changing the userid under which
+Bacula (bacula-fd.exe) runs, from SYSTEM to a Domain Admin userid, resolves
+the problem.
+
+
+\section{Manually resetting the Permissions}
+\index[general]{Manually resetting the Permissions}
+\index[general]{Permissions!Manually resetting the}
+
+The following solution was provided by Dan Langille \lt{}dan at langille in
+the dot org domain\gt{}. The steps are performed using Windows 2000 Server but
+they should apply to most Win32 platforms. The procedure outlines how to deal
+with a problem which arises when a restore creates a top-level new directory.
+In this example, "top-level" means something like {\bf
+c:\textbackslash{}src}, not {\bf c:\textbackslash{}tmp\textbackslash{}src}
+where {\bf c:\textbackslash{}tmp} already exists. If a restore job specifies /
+as the {\bf Where:} value, this problem will arise.
+
+The problem appears as a directory which cannot be browsed with Windows
+Explorer. The symptoms include the following message when you try to click on
+that directory:
+
+\includegraphics{./access-is-denied.eps}
+
+If you encounter this message, the following steps will change the permissions
+to allow full access.
+
+\begin{enumerate}
+\item right click on the top level directory (in this example, {\bf c:/src})
+ and select {\bf Properties}.
+\item click on the Security tab.
+\item If the following message appears, you can ignore it, and click on {\bf
+ OK}.
+
+\includegraphics{./view-only.eps}
+
+You should see something like this:
+
+\includegraphics{./properties-security.eps}
+\item click on Advanced
+\item click on the Owner tab
+\item Change the owner to something other than the current owner (which is
+ {\bf SYSTEM} in this example as shown below).
+
+\includegraphics{./properties-security-advanced-owner.eps}
+\item ensure the "Replace owner on subcontainers and objects" box is
+ checked
+\item click on OK
+\item When the message "You do not have permission to read the contents of
+ directory c:\textbackslash{}src\textbackslash{}basis. Do you wish to replace
+ the directory permissions with permissions granting you Full Control?", click
+on Yes.
+
+\includegraphics{./confirm.eps}
+\item Click on OK to close the Properties tab
+ \end{enumerate}
+
+With the above procedure, you should now have full control over your restored
+directory.
+
+In addition to the above methods of changing permissions, there is a Microsoft
+program named {\bf cacls} that can perform similar functions.
+
+\section{Backing Up the WinNT/XP/2K System State}
+\index[general]{State!Backing Up the WinNT/XP/2K System}
+\index[general]{Backing Up the WinNT/XP/2K System State}
+
+A suggestion by Damian Coutts using Microsoft's NTBackup utility in
+conjunction with Bacula should permit a full restore of any damaged system
+files on Win2K/XP. His suggestion is to do an NTBackup of the critical system
+state prior to running a Bacula backup with the following command:
+
+\footnotesize
+\begin{verbatim}
+ntbackup backup systemstate /F c:\systemstate.bkf
+\end{verbatim}
+\normalsize
+
+The {\bf backup} is the command, the {\bf systemstate} says to backup only the
+system state and not all the user files, and the {\bf /F
+c:\textbackslash{}systemstate.bkf} specifies where to write the state file.
+this file must then be saved and restored by Bacula.
+
+To restore the system state, you first reload a base operating system if the
+OS is damaged, otherwise, this is not necessary, then you would use Bacula to
+restore all the damaged or lost user's files and to recover the {\bf
+c:\textbackslash{}systemstate.bkf} file. Finally if there are any damaged or
+missing system files or registry problems, you run {\bf NTBackup} and {\bf
+catalogue} the system statefile, and then select it for restore. The
+documentation says you can't run a command line restore of the systemstate.
+
+To the best of my knowledge, this has not yet been tested. If you test it,
+please report your results to the Bacula email list.
+
+\section{Considerations for Filename Specifications}
+\index[general]{Windows!Considerations for Filename Specifications}
+
+Please see the
+\ilink{Director's Configuration chapter}{win32} of this manual
+for important considerations on how to specify Windows paths in Bacula FileSet
+Include and Exclude directives.
+
+\index[general]{Unicode}
+Bacula versions prior to 1.37.28 do not support Windows Unicode filenames.
+As of that version, both {\bf bconsole} and {\bf bwx-console} support Windows
+Unicode filenames. There may still be some problems with multiple byte
+characters (e.g. Chinese, ...) where it is a two byte character but the
+displayed character is not two characters wide.
+
+\index[general]{Win32 Path Length Restriction}
+Path/filenames longer than 260 characters (up to 32,000) are supported
+beginning with Bacula version 1.39.20. Older Bacula versions support
+only 260 character path/filenames.
+
+\section{Win32 Specific File daemon Command Line}
+\index[general]{Client!Win32 Specific File daemon Command Line Options}
+\index[general]{Win32 Specific File daemon Command Line Options}
+
+These options are not normally seen or used by the user, and are documented
+here only for information purposes. At the current time, to change the default
+options, you must either manually run {\bf Bacula} or you must manually edit
+the system registry and modify the appropriate entries.
+
+In order to avoid option clashes between the options necessary for {\bf
+Bacula} to run on Windows and the standard Bacula options, all Windows
+specific options are signaled with a forward slash character (/), while as
+usual, the standard Bacula options are signaled with a minus (-), or a minus
+minus (\verb:--:). All the standard Bacula options can be used on the Windows
+version. In addition, the following Windows only options are implemented:
+
+\begin{description}
+
+\item [/service ]
+ \index[fd]{/service}
+ Start Bacula as a service
+
+\item [/run ]
+ \index[fd]{/run}
+ Run the Bacula application
+
+\item [/install ]
+ \index[fd]{/install}
+ Install Bacula as a service in the system registry
+
+\item [/remove ]
+ \index[fd]{/remove}
+ Uninstall Bacula from the system registry
+
+\item [/about ]
+ \index[fd]{/about}
+ Show the Bacula about dialogue box
+
+\item [/status ]
+ \index[fd]{/status}
+ Show the Bacula status dialogue box
+
+\item [/events ]
+ \index[fd]{/events}
+ Show the Bacula events dialogue box (not yet implemented)
+
+\item [/kill ]
+ \index[fd]{/kill}
+ Stop any running {\bf Bacula}
+
+\item [/help ]
+ \index[fd]{/help}
+ Show the Bacula help dialogue box
+\end{description}
+
+It is important to note that under normal circumstances the user should never
+need to use these options as they are normally handled by the system
+automatically once Bacula is installed. However, you may note these options in
+some of the .bat files that have been created for your use.
+
+\section{Shutting down Windows Systems}
+\index[general]{Shutting down Windows Systems}
+\index[general]{Systems!Shutting down Windows}
+
+Some users like to shutdown their Windows machines after a backup using a
+Client Run After Job directive. If you want to do something similar, you might
+take the shutdown program from the
+\elink{apcupsd project}{\url{http://www.apcupsd.com}} or one from the
+\elink{Sysinternals project}
+{\url{http://www.sysinternals.com/ntw2k/freeware/psshutdown.shtml}}.
--- /dev/null
+#
+#
+# Makefile for LaTeX
+#
+# To build everything do
+# make tex
+# make web
+# make html
+# make dvipdf
+#
+# or simply
+#
+# make
+#
+# for rapid development do:
+# make tex
+# make show
+#
+#
+# If you are having problems getting "make" to work, debugging it is
+# easier if can see the output from latex, which is normally redirected
+# to /dev/null. To see it, do the following:
+#
+# cd docs/manual
+# make tex
+# latex bacula.tex
+#
+# typically the latex command will stop indicating the error (e.g. a
+# missing \ in front of a _ or a missing { or ] ...
+#
+# The following characters must be preceded by a backslash
+# to be entered as printable characters:
+#
+# # $ % & ~ _ ^ \ { }
+#
+
+IMAGES=../../../images
+
+DOC=console
+
+first_rule: all
+
+all: tex web dvipdf mini-clean
+
+.SUFFIXES: .tex .html
+.PHONY:
+.DONTCARE:
+
+
+tex:
+ @./update_version
+ @echo "Making version `cat version.tex`"
+ @cp -fp ${IMAGES}/hires/*.eps .
+ @touch ${DOC}i-dir.tex ${DOC}i-fd.tex ${DOC}i-sd.tex \
+ ${DOC}i-console.tex ${DOC}i-general.tex
+ latex -interaction=batchmode ${DOC}.tex
+ makeindex ${DOC}.idx -o ${DOC}.ind 2>/dev/null
+ latex -interaction=batchmode ${DOC}.tex
+
+pdf:
+ @echo "Making pdfm"
+ @cp -fp ${IMAGES}/hires/*.eps .
+ dvipdfm -p a4 ${DOC}.dvi
+
+dvipdf:
+ @echo "Making dvi to pdf"
+ @cp -fp ${IMAGES}/hires/*.eps .
+ dvipdf ${DOC}.dvi ${DOC}.pdf
+
+html:
+ @echo " "
+ @echo "Making html"
+ @cp -fp ${IMAGES}/*.eps .
+ @rm -f next.eps next.png prev.eps prev.png up.eps up.png
+ @(if [ -f imagename_translations ] ; then \
+ ./translate_images.pl --from_meaningful_names ${DOC}.html; \
+ fi)
+ latex2html -white -no_subdir -split 0 -toc_stars -white -notransparent \
+ -init_file latex2html-init.pl ${DOC} >tex.out 2>&1
+ ./translate_images.pl --to_meaningful_names ${DOC}.html
+ @echo "Done making html"
+
+web:
+ @echo "Making web"
+ @mkdir -p ${DOC}
+ @cp -fp ${IMAGES}/*.eps .
+ @rm -f next.eps next.png prev.eps prev.png up.eps up.png
+ @cp -fp ${IMAGES}/*.eps ${DOC}/
+ @cp -fp ${IMAGES}/*.eps ${IMAGES}/*.png ${DOC}/
+ @rm -f ${DOC}/xp-*.png
+ @rm -f ${DOC}/next.eps ${DOC}/next.png ${DOC}/prev.eps ${DOC}/prev.png ${DOC}/up.eps ${DOC}/up.png
+ @rm -rf ${DOC}/*.html
+ latex2html -split 3 -local_icons -t "Bacula Console and Operators Guide" -long_titles 4 \
+ -toc_stars -contents_in_nav -init_file latex2html-init.pl -white -notransparent ${DOC} >tex.out 2>&1
+ ./translate_images.pl --to_meaningful_names ${DOC}/Bacula_Consol*.html
+ @echo "Done making web"
+show:
+ xdvi ${DOC}
+
+texcheck:
+ ./check_tex.pl ${DOC}.tex
+
+main_configs:
+ pic2graph -density 100 <main_configs.pic >main_configs.png
+
+mini-clean:
+ @rm -f 1 2 3 *.tex~
+ @rm -f *.gif *.jpg *.eps
+ @rm -f *.aux *.cp *.fn *.ky *.log *.pg
+ @rm -f *.backup *.ilg *.lof *.lot
+ @rm -f *.cdx *.cnd *.ddx *.ddn *.fdx *.fnd *.ind *.sdx *.snd
+ @rm -f *.dnd *.old *.out
+ @rm -f ${DOC}/*.gif ${DOC}/*.jpg ${DOC}/*.eps
+ @rm -f ${DOC}/*.aux ${DOC}/*.cp ${DOC}/*.fn ${DOC}/*.ky ${DOC}/*.log ${DOC}/*.pg
+ @rm -f ${DOC}/*.backup ${DOC}/*.ilg ${DOC}/*.lof ${DOC}/*.lot
+ @rm -f ${DOC}/*.cdx ${DOC}/*.cnd ${DOC}/*.ddx ${DOC}/*.ddn ${DOC}/*.fdx ${DOC}/*.fnd ${DOC}/*.ind ${DOC}/*.sdx ${DOC}/*.snd
+ @rm -f ${DOC}/*.dnd ${DOC}/*.old ${DOC}/*.out
+ @rm -f ${DOC}/WARNINGS
+
+
+clean:
+ @rm -f 1 2 3 *.tex~
+ @rm -f *.png *.gif *.jpg *.eps
+ @rm -f *.pdf *.aux *.cp *.fn *.ky *.log *.pg
+ @rm -f *.html *.backup *.ps *.dvi *.ilg *.lof *.lot
+ @rm -f *.cdx *.cnd *.ddx *.ddn *.fdx *.fnd *.ind *.sdx *.snd
+ @rm -f *.dnd imagename_translations
+ @rm -f *.old WARNINGS *.out *.toc *.idx
+ @rm -f ${DOC}i-*.tex
+ @rm -rf ${DOC}
+
+
+distclean: clean
+ @rm -f images.pl labels.pl internals.pl
+ @rm -f Makefile version.tex
--- /dev/null
+#
+#
+# Makefile for LaTeX
+#
+# To build everything do
+# make tex
+# make web
+# make html
+# make dvipdf
+#
+# or simply
+#
+# make
+#
+# for rapid development do:
+# make tex
+# make show
+#
+#
+# If you are having problems getting "make" to work, debugging it is
+# easier if can see the output from latex, which is normally redirected
+# to /dev/null. To see it, do the following:
+#
+# cd docs/manual
+# make tex
+# latex bacula.tex
+#
+# typically the latex command will stop indicating the error (e.g. a
+# missing \ in front of a _ or a missing { or ] ...
+#
+# The following characters must be preceded by a backslash
+# to be entered as printable characters:
+#
+# # $ % & ~ _ ^ \ { }
+#
+
+IMAGES=../../../images
+
+DOC=console
+
+first_rule: all
+
+all: tex web dvipdf mini-clean
+
+.SUFFIXES: .tex .html
+.PHONY:
+.DONTCARE:
+
+
+tex:
+ @./update_version
+ @echo "Making version `cat version.tex`"
+ @cp -fp ${IMAGES}/hires/*.eps .
+ @touch ${DOC}i-dir.tex ${DOC}i-fd.tex ${DOC}i-sd.tex \
+ ${DOC}i-console.tex ${DOC}i-general.tex
+ latex -interaction=batchmode ${DOC}.tex
+ makeindex ${DOC}.idx -o ${DOC}.ind 2>/dev/null
+ latex -interaction=batchmode ${DOC}.tex
+
+pdf:
+ @echo "Making pdfm"
+ @cp -fp ${IMAGES}/hires/*.eps .
+ dvipdfm -p a4 ${DOC}.dvi
+
+dvipdf:
+ @echo "Making dvi to pdf"
+ @cp -fp ${IMAGES}/hires/*.eps .
+ dvipdf ${DOC}.dvi ${DOC}.pdf
+
+html:
+ @echo " "
+ @echo "Making html"
+ @cp -fp ${IMAGES}/*.eps .
+ @rm -f next.eps next.png prev.eps prev.png up.eps up.png
+ @(if [ -f imagename_translations ] ; then \
+ ./translate_images.pl --from_meaningful_names ${DOC}.html; \
+ fi)
+ latex2html -white -no_subdir -split 0 -toc_stars -white -notransparent \
+ -init_file latex2html-init.pl ${DOC} >tex.out 2>&1
+ ./translate_images.pl --to_meaningful_names ${DOC}.html
+ @echo "Done making html"
+
+web:
+ @echo "Making web"
+ @mkdir -p ${DOC}
+ @cp -fp ${IMAGES}/*.eps .
+ @rm -f next.eps next.png prev.eps prev.png up.eps up.png
+ @cp -fp ${IMAGES}/*.eps ${DOC}/
+ @cp -fp ${IMAGES}/*.eps ${IMAGES}/*.png ${DOC}/
+ @rm -f ${DOC}/xp-*.png
+ @rm -f ${DOC}/next.eps ${DOC}/next.png ${DOC}/prev.eps ${DOC}/prev.png ${DOC}/up.eps ${DOC}/up.png
+ @rm -rf ${DOC}/*.html
+ latex2html -split 3 -local_icons -t "Bacula Console and Operators Guide" -long_titles 4 \
+ -toc_stars -contents_in_nav -init_file latex2html-init.pl -white -notransparent ${DOC} >tex.out 2>&1
+ ./translate_images.pl --to_meaningful_names ${DOC}/Bacula_Consol*.html
+ @echo "Done making web"
+show:
+ xdvi ${DOC}
+
+texcheck:
+ ./check_tex.pl ${DOC}.tex
+
+main_configs:
+ pic2graph -density 100 <main_configs.pic >main_configs.png
+
+mini-clean:
+ @rm -f 1 2 3 *.tex~
+ @rm -f *.gif *.jpg *.eps
+ @rm -f *.aux *.cp *.fn *.ky *.log *.pg
+ @rm -f *.backup *.ilg *.lof *.lot
+ @rm -f *.cdx *.cnd *.ddx *.ddn *.fdx *.fnd *.ind *.sdx *.snd
+ @rm -f *.dnd *.old *.out
+ @rm -f ${DOC}/*.gif ${DOC}/*.jpg ${DOC}/*.eps
+ @rm -f ${DOC}/*.aux ${DOC}/*.cp ${DOC}/*.fn ${DOC}/*.ky ${DOC}/*.log ${DOC}/*.pg
+ @rm -f ${DOC}/*.backup ${DOC}/*.ilg ${DOC}/*.lof ${DOC}/*.lot
+ @rm -f ${DOC}/*.cdx ${DOC}/*.cnd ${DOC}/*.ddx ${DOC}/*.ddn ${DOC}/*.fdx ${DOC}/*.fnd ${DOC}/*.ind ${DOC}/*.sdx ${DOC}/*.snd
+ @rm -f ${DOC}/*.dnd ${DOC}/*.old ${DOC}/*.out
+ @rm -f ${DOC}/WARNINGS
+
+
+clean:
+ @rm -f 1 2 3 *.tex~
+ @rm -f *.png *.gif *.jpg *.eps
+ @rm -f *.pdf *.aux *.cp *.fn *.ky *.log *.pg
+ @rm -f *.html *.backup *.ps *.dvi *.ilg *.lof *.lot
+ @rm -f *.cdx *.cnd *.ddx *.ddn *.fdx *.fnd *.ind *.sdx *.snd
+ @rm -f *.dnd imagename_translations
+ @rm -f *.old WARNINGS *.out *.toc *.idx
+ @rm -f ${DOC}i-*.tex
+ @rm -rf ${DOC}
+
+
+distclean: clean
+ @rm -f images.pl labels.pl internals.pl
+ @rm -f Makefile version.tex
--- /dev/null
+%%
+%%
+
+\chapter{La console Bacula}
+\label{_ConsoleChapter}
+\index[general]{Console!Bacula}
+\index[general]{La console Bacula}
+\index[general]{Console!Bacula}
+\index[general]{LA console Bacula}
+\addcontentsline{toc}{section}{La console Bacula}
+
+\section{G\'en\'eralit\'es}
+\index[general]{G\'en\'eralit\'es}
+\addcontentsline{toc}{section}{G\'en\'eralit\'es}
+
+La {\bf console Bacula} (parfois d\'esign\'ee "Agent utilisateur") est un programme
+qui permet \`a l'utilisateur autoris\'e ou \`a l'administrateur syst\`eme d'interagir
+avec le Director.
+
+Actuellement, la console Bacula existe en deux versions : une interface shell
+(fa\c{c}on TTY), et une interface graphique GNOME. Avec la console Bacula, vous
+pouvez d\'eterminer l'\'etat d'un job particulier, examiner le contenu du
+catalogue et effectuer certaines manipulations de cartouches.
+
+Il existe d'autre part un programme nomm\'e bwx-console, b\^atie avec wxWidgets qui
+offre une interface graphique aux op\'erations de restauration.
+
+Etant donn\'e que la Console interagit avec le Director au travers du r\'eseau,
+il n'est pas n\'ecessaire que les deux programmes r\'esident sur la m\^eme machine.
+
+Bacula a besoin d'un minimum de retour de la Console afin de pouvoir utiliser plus
+d'une cartouche. En effet, lorsqu'il en r\'eclame une nouvelle, il attend jusqu'\`a
+ce qu'un op\'erateur lui indique, via la Console, qu'une nouvelle cartouche est mont\'ee.
+
+\section{Configuration de la Console}
+\index[general]{Configuration de la Console}
+\index[general]{Configuration!Console}
+\index[general]{Configuration de la Console}
+\index[general]{Configuration!Console}
+\addcontentsline{toc}{section}{Configuration de la Console}
+
+Lors de son lancement, la Console lit le fichier de configuration standard
+nomm\'e {\bf bconsole.conf} (ou {\bf gnome-console.conf} dans le cas de la version
+GNOME) Ce fichier d\'efinit une configuration par d\'efaut de la Console et, \`a l'heure
+actuelle, la seule ressource d\'efinie est la ressource Director, qui informe
+la Console du nom et de l'adresse du Director. Pour plus d'informations sur la
+configuration de la Console, voyez le chapitre \ilink{Configurer la Console}{_ChapterStart36}
+de ce manuel.
+
+\section{Utiliser la Console}
+\index[general]{Utiliser la Console}
+\index[general]{Console!Utiliser la}
+\index[general]{Utiliser la Console}
+\index[general]{Console!Utiliser la}
+\addcontentsline{toc}{section}{Utiliser la Console}
+
+Le programme Console admet les options suivantes :
+\footnotesize
+\begin{verbatim}
+Usage: bconsole [-s] [-c config_file] [-d debug_level]
+ -c <file> set configuration file to file
+ -dnn set debug level to nn
+ -n no conio
+ -s no signals
+ -t test - read configuration and exit
+ -? print this message.
+\end{verbatim}
+\normalsize
+
+Apr\`es son d\'emarrage, la Console est en attente de vos commandes, ce qui
+est indiqu\'e par une ast\'erisque (*) (ce n'est pas le cas dans la version
+GNOME o\`u vous saisissez vos commandes dans la boite texte en bas de l'\'ecran).
+Vous pouvez, pour toutes les commandes, vous contenter d'entrer le nom de la
+commande, la Console se chargera de vous demander les arguments n\'ecessaires,
+mais dans la plupart des cas, vous pouvez entrer les commandes suivies de leurs
+arguments. Le format g\'en\'eral est :
+
+\footnotesize
+\begin{verbatim}
+ <command> <keyword1>[=<argument1>] <keyword2>[=<argument2>] ...
+\end{verbatim}
+\normalsize
+
+O\`u {\bf command} est l'une des commandes \'enum\'er\'ees ci-dessous, {\bf keyword}
+est l'un des mots-clef \'enum\'er\'es ci-dessous (usuellement suivi d'un argument),
+et {\bf argument} est la valeur du mot-clef. La commande peut \^etre abr\'eg\'ee
+jusqu'\`a sa plus courte abr\'eviation unique. Si deux commandes commencent
+par les m\^emes lettres, c'est celle qui appara\^it en t\^ete dans la liste fournie
+par la commande {\bf help} qui sera s\'electionn\'ee si votre abr\'eviation est
+ambig\"ue. Aucun des mots-clef suivant la commande ne peut \^etre abr\'eg\'e.
+
+Par exemple :
+
+\footnotesize
+\begin{verbatim}
+list files jobid=23
+\end{verbatim}
+\normalsize
+
+\'enum\`ere les fichiers sauvegard\'es par le job de JobId 23.
+
+Cette autre commande :
+
+\footnotesize
+\begin{verbatim}
+show pools
+\end{verbatim}
+\normalsize
+
+affiche toutes les ressources Pool.
+
+\section{Quitter la Console}
+\index[general]{Console!Quitter}
+\index[general]{Quitter la Console}
+\index[general]{Console!Quitter}
+\index[general]{Quitter la Console}
+\addcontentsline{toc}{section}{Quitter la Console}
+
+Normalement, le programme Console se termine si vous saisissez {\bf quit}
+ou {\bf exit}. Cependant, il il attend jusq"\`a ce que le Director ait pris
+en compte la commande, ce qui peut prendre du temps si ce dernier est d\'ej\`a
+occup\'e \`a une t\^ache longue (par exemple, un \'elagage du catalogue). Si vous voulez
+quitter la Console imm\'ediatement, utilisez la commande {\bf .quit}.
+
+Il n'existe actuellement aucun moyen d'interrompre une commande de la Console
+une fois lanc\'ee (Ctrl-C ne marche pas). En revanche, \`a l'invite d'une commande
+vous demandant de choisir parmi plusieurs possibilit\'es, vous pouvez annuler
+la commande en entrant un point ({\bf .}), vous serez dans la plupart des cas
+ramen\'e \`a l'invite principal, ou \`a l'invite pr\'ec\'edente, dans le cas de choix
+imbriqu\'es. En quelques endroits, comme celui o\`u l'on vous demande un
+nom de volume, le point sera pris pour la r\'eponse (Bacula pensera que vous
+voulez nommer votre volume "."). Dans cette situation, vous serez la plupart
+du temps en mesure d'annuler \`a l'invite suivante.
+
+\label{keywords}
+\section{Index des mots-clef de la Console}
+\index[general]{Mots-clef!Index Console}
+\index[general]{Index des mots-clef de la Console}
+\index[general]{Mots-clef!Index Console}
+\index[general]{Index des mots-clef de la Console}
+\addcontentsline{toc}{section}{Index des mots-clef de la Console}
+Sauf sp\'ecification contraire, chacun des mots-clef suivant admet un argument,
+qui est sp\'ecifi\'e apr\`es le mot-clef suivi du signe \'egale. Par exemple :
+
+\begin{verbatim}
+jobid=536
+\end{verbatim}
+
+Notez que cette liste est probablement incompl\`ete, car le processus de cr\'eation
+est toujours en cours. Il se peut aussi qu'elle ne soit pas dans l'ordre
+alphab\'etique.
+
+\begin{description}
+\item [restart]
+ Permis dans la commande {\it python}, provoque le red\'emarrage de
+ l'interpr\'eteur Python. Ne prend pas d'arguments.
+\item [all]
+ Permis dans les commandes {\it status} et {\it show} pour sp\'ecifier, respectivement, tous les
+ composants ou toutes les ressources.
+\item [before]
+ Utilis\'e dans la commande {\it restore}.
+\item [bootstrap]
+ Utilis\'e dans la commande {\it restore}.
+\item [catalog]
+ Permis dans la commande {\it use} pour sp\'ecifier le nom de catalogue \`a utiliser.
+\item [catalogs]
+ Utilis\'e dans la commande {\it show}. Ne prend pas d'arguments
+\item [client | fd]
+\item [clients]
+ Utilis\'e dans les commandes {\it show}, {\it list}, et {\it llist}. ne prend pas d'arguments.
+\item [counters]
+ Utilis\'e dans la commande {\it show}. Ne prend pas d'arguments.
+\item [current]
+ Utilis\'e dans la commande {\it restore}. Ne prend pas d'arguments.
+\item [days]
+ Utilisé pour définir le nombre de jours que la commande "list nextvol" doit
+ prendre en compte dans son évaluation des prochains jobs à exécuter.
+ Le mot-clef "day" peut aussi être utilisé avec la commande "status dir"
+ afin qu'elle affiche les jobs planifiés pour la période spécifiés.
+\item [devices]
+ Utilis\'e dans la commande {\it show}. Ne prend pas d'arguments.
+\item [dir | director]
+\item [directors]
+ Utilis\'e dans la commande {\it show}. Ne prend pas d'arguments.
+\item [directory]
+ Utilis\'e dans la commande {\it restore}. Son argument spécifie
+ le répertoire à restaurer.
+\item [enabled]
+ Ce mot-clef peut être utilisé avec la commande {\bf update volume} et admet
+ l'un des arguments suivants : yes, true, no, false, archived, 0, 1, 2, où
+ 0 correspond à "no" ou "false", 1 à "yes" ou "true" et 2 à "archived". Les volumes
+ avec le statut "archived" ne seront pas utilisés, pas plus que ne seront élagués leurs
+ enregistrements dans le catalogue. Les volumes qui n'ont pas le statut "enabled"
+ ne seront pas utilisés pour des sauvegardes ou des restaurations.
+\item [done]
+ Utilis\'e dans la commande {\it restore}. Ne prend pas d'arguments.
+\item [file]
+ Utilis\'e dans la commande {\it restore}.
+\item [files]
+ Utilis\'e dans les commandes {\it list}, et {\it llist}. ne prend pas d'arguments.
+\item [fileset]
+\item [filesets]
+ Utilis\'e dans la commande {\it show}. Ne prend pas d'arguments.
+\item [help]
+ Utilis\'e dans la commande {\it show}. Ne prend pas d'arguments.
+\item [jobs]
+ Utilis\'e dans les commandes {\it show}, {\it list} et {\it llist}. Ne prend pas d'arguments.
+\item [jobmedia]
+ Utilis\'e dans les commandes {\it list}, et {\it llist}. ne prend pas d'arguments.
+\item [jobtotals]
+ Utilis\'e dans les commandes {\it list}, et {\it llist}. ne prend pas d'arguments.
+\item [jobid]
+ Le JobId est le num\'ero de job qui est affich\'e dans le rapport de job.
+ C'est l'index du catalogue pour le job donn\'e. Bien qu'il soit unique
+ pour tous les jobs existant dans le catalogue, le m\^eme JobId peut
+ \^etre r\'eutilis\'e une fois qu'un job a \'et\'e supprim\'e du catalogue.
+ Vous d\'esignerez certainement les jobs sp\'ecifiques par leur JobId.
+\item [job | jobname]
+ Le mot-clef Job ou Jobname se r\'ef\`ere au nom que vous avez sp\'ecifi\'e
+ dans la ressource Job, et donc peut d\'esigner plusieurs jobs effectu\'es.
+ C'est particuli\`erement utile lorsque vous voulez la liste des jobs
+ execut\'es portant un nom particulier.
+\item [level]
+\item [listing]
+ Permis dans la commande {\it estimate}. Ne prend pas d'arguments.
+\item [limit]
+\item [messages]
+ Utilis\'e dans la commande {\it show}. Ne prend pas d'arguments.
+\item [media]
+ Utilis\'e dans les commandes {\it list}, et {\it llist}. ne prend pas d'arguments.
+\item [nextvol | nextvolume]
+ Utilis\'e dans les commandes {\it list}, et {\it llist}. ne prend pas d'arguments.
+\item [on]
+ Ne prend pas d'arguments.
+\item [off]
+ Ne prend pas d'arguments.
+\item [pool]
+\item [pools]
+ Utilis\'e dans les commandes, {\it show}, {\it list}, et {\it llist}. ne prend pas d'arguments.
+\item [select]
+ Utilis\'e dans la commande {\it restore}. Ne prend pas d'arguments.
+\item [storages]
+ Utilis\'e dans la commande {\it show}. Ne prend pas d'arguments.
+\item [schedules]
+ Utilis\'e dans la commande {\it show}. Ne prend pas d'arguments.
+\item [sd | store | storage]
+\item [ujobid]
+ L'ujobid est un identificateur unique de job qui est affich\'e dans
+ le rapport du job. Actuellement, il consiste en le nom du job
+ (celui de la directive Name de ce job) suffix\'e de la date et de
+ l'heure d'ex\'ecution du job. Ce mot-clef est utile si vous voulez
+ identifier compl\`etement l'instance du job ex\'ecut\'e.
+\item [volume]
+\item [volumes]
+ Utilis\'e dans les commandes {\it list}, et {\it llist}. ne prend pas d'arguments.
+\item [where]
+ Utilis\'e dans la commande {\it restore}. Ne prend pas d'arguments.
+\item [yes]
+ Utilis\'e dans la commande {\it restore}. Ne prend pas d'arguments.
+\end{description}
+
+\label{list}
+\section{Index des commandes de la Console}
+\index[general]{Commandes!Index des commandes de la Console}
+\index[general]{Index des commandes de la Console}
+\index[general]{Commandes!Index des commandes de la Console}
+\index[general]{Index des commandes de la Console}
+\addcontentsline{toc}{section}{Index des commandes de la Console}
+
+Les commandes suivantes sont actuellement impl\'ement\'ees :
+
+\begin{description}
+\item [{add [pool=\lt{}pool-name\gt{} storage=\lt{}storage\gt{}
+ jobid=\lt{}JobId\gt{}]} ]
+ \index[general]{add}
+Cette commande sert \`a ajouter des volumes \`a un pool existant. Les noms des
+volumes saisis sont plac\'es dans le catalogue et deviennent ainsi disponibles
+pour les sauvegardes. Normalement, on pr\'ef\`er utiliser la commande {\bf label}
+qui remplit les m\^emes fonctions en plus d'apposer une \'etiquette logicielle
+(label) sur les bandes, par opposition \`a {\bf add} qui se contente de
+r\'ef\'erencer le volume dans le catalogue. Ainsi, si vous utilisez {\bf add},
+le volume doit pr\'eexister et \^etre d\'ej\`a \'etiquet\'e. Cette commande peut
+cependant \^etre utile si vous voulez ajouter plusieurs cartouches dans un
+pool en ne les \'etiquettant que plus tard. Elle peut aussi se r\'ev\'eler utile
+si vous importez des cartouches provenant d'un autre site. Consultez le
+paragraphe sur la commande {\bf label} pour conna\^itre la liste des
+caract\`eres autoris\'es dans un nom de volume.
+
+\item [autodisplay on/off]
+ \index[general]{autodisplay on/off}
+ Cette commande accepte les arguments {\bf on} ou {\bf off} et active ou
+ d\'esactive l'affichage automatique des messages. La valeur par d\'efaut dans
+ la Console est {\bf off}, ce qui signifie que les messages en attente
+ vous sont notifi\'es, mais qu'ils ne sont pas automatiquement affich\'es.
+ La valeur par d\'efaut pour la console GNOME est {\bf on}, ainsi les
+ messages sont affich\'es lorqu'ils sont re\c{c}us (habituellement dans les 5 secondes
+ apr\`es qu'ils aient \'et\'e g\'en\'er\'es).
+
+ Lorsque l'affichage automatique est d\'esactiv\'e, vous devez explicitement
+ en demander l'affichage avec la commande {\bf messages}.
+
+\item [automount on/off]
+ \index[general]{automount on/off}
+ Cette commande accepte les arguments {\bf on} ou {\bf off} et active ou
+ d\'esactive le montage automatique de la cartouche apr\`es une commande {\bf label}.
+ La valeur par d\'efaut est {\bf on}. Si le montage automatique est d\'esactiv\'e,
+ vous devez explicitement monter la cartouche apr\`es avoir utilis\'e {\bf label}
+ pour pouvoir \'ecrire dessus.
+
+\item [{cancel [jobid=\lt{}number\gt{} job=\lt{}job-name\gt{} ujobid=\lt{}unique-jobid\gt{}]}]
+ \index[general]{cancel jobid}
+ Cette commande sert \`a supprimer un job et admet les arguments {\bf jobid=nnn}
+ ou {\bf job=xxx} o\`u nnn est \`a remplacer par le JobId et xxx par le nom de
+ job. Si vous lancez cette commande sans arguments, la Console vous propose
+ de choisir parmi les jobs actifs celui \`a supprimer.
+
+ Une fois qu'un job est marqu\'e "A supprimer", il peut se passer quelques instants
+ (en g\'en\'eral, moins d'une minute) avant qu'il se termine, en fonction des
+ op\'erations en cours.
+
+\item [{ create [pool=\lt{}pool-name\gt{}]}]
+ \index[general]{create pool}
+ Cette commande sert \`a cr\'eer un enregistrement Pool dans le catalogue
+ selon les ressources Pool d\'efinis dans le fichier de configuration
+ du Director. En un sens, cette commande se content de transf\'erer
+ l'information depuis la ressource Pool dans le fichier de configuration
+ vers le catalogue. En principe, cete commande est automatiquement
+ ex\'ecut\'ee au lancement du Director, pourvu que le pool soit r\'ef\'erenc\'e
+ dans une ressource Job. Si vous utilisez cette commande sur un pool
+ existant, elle met \`a jour le catalogue en foction des informations de
+ la ressource Pool. Apr\`es avoir cr\'e\'e un pool, vous uiliserez
+ probablement la commande {\bf label} pour \'etiqueter un ou plusieurs
+ volumes et enregistrer leurs noms dans le catalogue.
+
+ Si, au lancement d'un job, Bacula d\'etermine qu'il n'y a pas de pool
+ enregistr\'e dans le catalogue, mais qu'il existe une ressource Pool pour
+ le pool appropri\'e, alors il le cr\'e\'e pour vous. Si vous voulez le voir
+ appara\^itre imm\'ediatement dans le catalogue, utilisez cette commande pour
+ forcer sa cr\'eation imm\'ediate.
+
+\item [{ delete [volume=\lt{}vol-name\gt{} pool=\lt{}pool-name\gt{} job
+ jobid=\lt{}id\gt{}]}]
+ \index[general]{delete}
+ Cette commande s'utilise pour supprimer un volume, un pool ou un job
+ du catalogue, ainsi que tous les enregistrements du catalogue qui leur
+ sont associ\'es. Cette commande op\`ere exclusivement sur le catalogue
+ et n'a aucune r\'epercussion sur les donn\'ees \'ecrites sur les cartouches.
+ Elle peut \^etre dangereuse, et nous vous recommandons fortement de ne
+ pas l'utiliser si vous ne savez pas exactement ce que vous faites.
+
+ Voici la forme compl\`ete de cette commande :
+
+\begin{verbatim}
+delete pool=\lt{}pool-name\gt{}
+\end{verbatim}
+
+ supprime un pool du catalogue.
+
+\begin{verbatim}
+delete volume=\lt{}volume-name\gt{} pool=\lt{}pool-name\gt{}
+\end{verbatim}
+
+ supprime du catalogue un volume du pool sp\'ecifi\'e.
+
+\begin{verbatim}
+delete JobId=\lt{}job-id\gt{} JobId=\lt{}job-id2\gt{} ...
+\end{verbatim}
+
+ supprime du catalogue le job sp\'ecifi\'e.
+
+\begin{verbatim}
+delete Job JobId=n,m,o-r,t ...
+\end{verbatim}
+
+ supprime les job de JobIds m,n,o,p,q,r et t (o\`u m,n,... sont, bien sur, des
+ nombres). Ainsi, la commande "delete jobid" accepte les listes et les plages
+ de jobids.
+
+\item [disable job\lt{}job-name\gt{}]
+ \index[general]{enable}
+ Cette commande vous permet de d\'esactiver un job normalement planifi\'e
+ pour ex\'ecution. Le job peut avoir \'et\'e pr\'ealablement activ\'e par la
+ directive {\bf Enabled} dans la ressource Job, ou avec la commande
+ {\bf enable} dans la Console. Au prochain d\'emarrage du Director, ou
+ si le fichier de configuration est recharg\'e, l'\'etat Enable/Disable sera
+ r\'etabli \`a celui sp\'ecifi\'e dans la ressource Job (la valeur par d\'efaut
+ est enabled).
+
+\item [enable job\lt{}job-name\gt{}]
+ \index[general]{enable}
+ Cette commande vous permet de d'activer un job planifi\'e
+ pour ex\'ecution automatique. Le job peut avoir \'et\'e pr\'ealablement d\'esactiv\'e par la
+ directive {\bf Disabled} dans la ressource Job, ou avec la commande
+ {\bf disable} dans la Console. Au prochain d\'emarrage du Director, ou
+ si le fichier de configuration est recharg\'e, l'\'etat Enable/Disable sera
+ r\'etabli \`a celui sp\'ecifi\'e dans la ressource Job (la valeur par d\'efaut
+ est enabled).
+
+\label{estimate}
+\item [estimate]
+ \index[general]{estimate}
+ Avec cette commande, vous pouvez vous faire une id\'ee du nombre de fichier
+ seront sauvegard\'es. Vous pouvez aussi l'utiliser pour \'eprouver les
+ param\`etres Include de vos FileSets sans passer par une sauvegarde
+ r\'eelle. Par d\'efaut, l'estimation est faite pour une sauvegarde Full.
+ Cependant, vous pouvez passer outre ce comportement en sp\'ecifiant
+ {\bf level=Incremental} ou {\bf level=Differential} sur la ligne de
+ commande. Un nom de job doit \^etre sp\'ecifi\'e, faute de quoi il vous sera
+ demand\'e. Optionnellement, vous pouvez sp\'ecifier un client et un
+ FileSet sur la ligne de commande. Bacula contacte alors le client
+ et calcule le nombre de fichier et d'octets qui seraient
+ sauvegard\'es. Notez qu'il s'agit d'une estimation calcul\'ee d'apr\`es
+ le nombre de blocs dans les fichiers plut\^ot qu'en lisant le nombre
+ effectif d'octets. Aussi, la taille estim\'ee est g\'en\'eralement plus
+ importante que celle de la sauvegarde r\'eelle.
+
+ Optionnellement, vous pouvez ajouter le mot-clef {\bf listing}, auquel cas
+ tous les fichiers \`a sauvegarder seront affich\'es. Notez qu'un tel affichage
+ peut prendre un certain temps s'il s'agit d'une grosse sauvegarde.
+ Voici la forme compl\`ete de cette commande :
+
+\begin{verbatim}
+estimate job=\lt{}job-name\gt{} listing client=\lt{}client-name\gt{}
+ fileset=\lt{}fileset-name\gt{} level=\lt{}level-name\gt{}
+\end{verbatim}
+
+ La sp\'ecification du {\bf job} est suffisante, mais vous pouvez aussi
+ passer outre le client, le FileSet et/ou le niveau en les
+ sp\'ecifiant sur la ligne de commande.
+
+ Par exemple, vous pourriez faire ceci :
+
+\footnotesize
+\begin{verbatim}
+ @output /tmp/listing
+ estimate job=NightlySave listing level=Incremental
+ @output
+\end{verbatim}
+\normalsize
+
+ce qui produirait une liste compl\`ete de tous les fichiers \`a sauvegarder pour
+le job {\bf NightlySave} au cours d'une sauvegarde incr\'ementale, et qui
+consignerait cette liste dans le fichier {\bf /tmp/listing}. Notez que l'évaluation
+produite par cette commande se base sur les tailles de fichiers contenues dans
+l'objet "répertoire", aussi l'estimation peut être très éloignée de la réalité si vous
+avez des fichiers creux (NDT : sparse files) sur votre système. Ce type de fichiers se
+rencontre souvent sur les systèmes 64 bits avec certains systèmes de fichiers.
+Le volume obtenu par l'évaluation est celui que sauvegardera Bacula si l'option
+sparse est désactivée. Il n'y a actuellement aucun moyen d'évaluer le volume de
+ce qui serait sauvegardé avec l'option sparse activée.
+
+\item [help]
+ \index[general]{help}
+ Cette commande affiche la liste des commandes disponibles.
+
+\item [label]
+ \index[general]{label}
+ \index[general]{relabel}
+ \index[general]{label}
+ \index[general]{relabel}
+ Cette commande est utilis\'ee pour \'etiqueter les volumes. La forme compl\`ete est :
+
+\begin{verbatim}
+ label storage=\lt{}storage-name\gt{} volume=\lt{}volume-name\gt{}
+ slot=\lt{}slot\gt{}
+\end{verbatim}
+
+ Si vous omettez l'un quelconque des arguments, il vous sera r\'eclam\'e.
+ Le type de m\'edia est automatiquement r\'ecup\'er\'e de la ressource Storage.
+ Une fois que les informations requises sont r\'eunies, la Console
+ contacte le Storage Daemon sp\'ecifi\'e et lui ordonne d'\'etiqueter la
+ cartouche sp\'ecifi\'ee. Si l'\'etiquetage s'effectue correctement, la
+ Console cr\'e\'e un nouvel enregistrement dans le catalogue pour le
+ volume dans le pool appropri\'e.
+
+ Les noms de volumes ne doivent contenir que des lettres, chiffres et
+ les caract\`eres sp\'eciaux tiret ({\bf -}), sous-lign\'e ({\bf \_}), double-point
+ ({\bf :}), et point ({\bf .}). Tous les autres caract\`eres, y compris l'espace,
+ sont ill\'egaux. Cette restriction vise \`a assurer une bonne lisibilit\'e
+ des noms de volumes pour r\'eduire le risque d'erreurs humaines.
+
+ Notez que lors de l'\'etiquetage d'une cartouche vierge, Bacula obtient des
+ erreurs {\bf read I/O error} lorqu'il tente de v\'erifier si la cartouche
+ a d\'ej\`a un label. Si vous voulez \'eviter ce genre de message, placez un
+ indicateur de fin de fichier sur votre cartouche avant son \'etiquetage :
+
+\footnotesize
+\begin{verbatim}
+ mt rewind
+ mt weof
+
+\end{verbatim}
+\normalsize
+
+La commande label peut \'echouer pour plusieurs raisons :
+
+
+\begin{enumerate}
+\item Le nom de volume que vous avez sp\'ecifi\'e figure d\'ej\`a dans le catalogue.
+\item Le Storage Daemon a d\'ej\`a une cartouche mont\'ee dans le lecteur. Dans ce cas,
+ vous devez la d\'emonter ({\bf unmount}) et ins\'erer une cartouche vierge
+ avant de lancer la commande {\bf label}.
+\item La cartouche dans le lecteur porte d\'ej\`a une \'etiquette Bacula.
+ (Bacula ne r\'e-\'etiquette jamais une cartouche \`a moins qu'elle soit recycl\'ee
+ et que vous utilisiez la commande {\bf relabel} ).
+\item Il n'y a pas de cartouche dans le lecteur.
+\end{enumerate}
+
+Il existe deux moyens pour r\'e-\'etiqueter un volume qui porte d\'ej\`a une
+\'etiquette Bacula. La m\'ethode brutale consiste \`a \'ecrire une marque de fin de
+fichier sur la cartouche vec la commande du syst\`eme d'exploitation {\bf mt},
+quelque chose dans ce style :
+
+\footnotesize
+\begin{verbatim}
+ mt -f /dev/st0 rewind
+ mt -f /dev/st0 weof
+\end{verbatim}
+\normalsize
+
+puis d'utiliser la commande {\bf label} pour ajouter une nouvelle \'etiquette.
+Cette m\'ethode peut cependant laisser des traces de l'ancien volume dans le
+catalogue.
+
+Il est pr\'ef\'erable d'utiliser la commande {\bf relabel} d\'ecrite ci-dessous sur
+un volume purg\'e (automatiquement ou avec la commande {\bf purge}).
+
+Si votre librairie comporte un lecteur de codes barres, vous pouvez
+\'etiqueter tous les volumes qu'elle contient en
+utilisant la commande {\bf label barcodes}. En effet, apr\`es le lancement de
+cette commande, Bacula monte chaque cartouche l'une apr\`es l'autre et
+l'\'etiquette du nom de son code barres. simultan\'ement, l'enregistrement
+appropri\'e est cr\'e\'e dans le catalogue. Toute cartouche dont le code barres
+commence par les m\^emes caract\`eres que ceux sp\'ecifi\'es par la directive
+"CleaningPrefix" de la ressource Pool du director est consid\'er\'ee comme
+une cartouche de nettoyage et ne re\c{c}oit donc pas d'\'etiquette, bien
+qu'une entr\'ee dans le catalogue lui soit d\'edi\'ee. Par exemple avec :
+
+\footnotesize
+\begin{verbatim}
+ Pool {
+ Name ...
+ Cleaning Prefix = "CLN"
+ }
+
+\end{verbatim}
+\normalsize
+
+tout slot contenant une cartouche de code barres CLNxxxxx sera trait\'ee en tant
+que cartouche de nettoyage et ne sera jamais mont\'ee. Notez que la forme
+compl\`ete de la commande est :
+
+\footnotesize
+\begin{verbatim}
+update storage=xxx pool=yyy slots=1-5,10 barcodes
+\end{verbatim}
+\normalsize
+
+\item [list]
+ \index[general]{list}
+ La commande {\bf list} extrait du catalogue les informations demand\'ees. Les
+ diff\'erentes champs de chaque enregistrement sont \'enum\'er\'es sur une simple
+ ligne. Voici les diff\'erentes formes de la commande :
+
+\footnotesize
+\begin{verbatim}
+ list jobs
+
+ list jobid=<id> (affiche le jobid id)
+
+ list ujobid=<unique job name> (affiche le job dont le nom unique est <unique job name>)
+
+ list job=<job-name> (Affiche tous les jobs dont le nom est "job-name")
+
+ list jobname=<job-name> (voir ci-dessus)
+
+ Dans cette commande, vous pouvez ajouter "limit=nn" pour limiter la sortie \`a nn jobs.
+
+ list jobmedia
+
+ list jobmedia jobid=<id>
+
+ list jobmedia job=<job-name>
+
+ list files jobid=<id>
+
+ list files job=<job-name>
+
+ list pools
+
+ list clients
+
+ list jobtotals
+
+ list volumes
+
+ list volumes jobid=<id>
+
+ list volumes pool=<pool-name>
+
+ list volumes job=<job-name>
+
+ list volume=<volume-name>
+
+ list nextvolume job=<job-name>
+
+ list nextvol job=<job-name>
+
+ list nextvol job=<job-name> days=nnn
+
+
+
+\end{verbatim}
+\normalsize
+
+ Ce que font la plupart des commandes ci-dessus devrait \^etre plus ou moins \'evident.
+ En g\'en\'eral, si vous ne sp\'ecifiez pas tous les arguments requis, la Console
+ vous sollicitera pour les arguments manquants.
+
+ La commande {\bf list nextvol} affiche le nom du volume qui dera utilis\'e par
+ le job sp\'ecifi\'e. Soyez conscient que le prochain volume utilis\'e
+ pour un job d\'epend de nombreux facteurs dont le temps, et les autres
+ jobs qui seront ex\'ecut\'es avant celui sp\'ecifi\'e, qui peuvent remplir une
+ cartouche qui \'etait vide au moment de l'ex\'ecution de {\bf list nextvol}.
+ Aussi, consid\'erez la r\'eponse fournie par cette commande comme une bonne
+ estimation plut\^ot que comme une r\'eponse d\'efinitive. De plus, cette commande
+ a certains effets de bord : \'etant donn\'e qu'elle ex\'ecute le m\^eme algorithme
+ qu'un job, elle est susceptible de purger ou recycler un volume. Par d\'efaut,
+ le job sp\'ecifi\'e doit \^etre ex\'ecut\'e dans les deux jours ou aucun volume
+ ne sera trouv\'e. Vous pouvez cependant sp\'ecifier jusqu'\`a 50 jours en avant
+ avec la directive {\bf days=nnn}. Si, par exemple, un vendredi, vous voulez
+ savoir quel volume sera requis lundi pour le job MyJob, utilisez
+ {\bf list nextvol job=MyJob days=3}.
+
+ Si vous souhaitez ajouter vos propres commandes pour interroger le
+ catalogue, vous pouvez les placer dans le fichier {\bf query.sql}.
+ Cela demande quelques connaissances du langage SQL. Voyez le
+ paragraphe sur la commande {\bf query} ci-dessous pour plus
+ d'informations. Voyez aussi le paragraphe sur la commande
+ {\bf llist} qui permet l'affichage complet des informations du
+ catalogue.
+
+ Voici un exemple d'affichage produit par la commande {\bf list pools} :
+
+\footnotesize
+\begin{verbatim}
++------+---------+---------+---------+----------+-------------+
+| PoId | Name | NumVols | MaxVols | PoolType | LabelFormat |
++------+---------+---------+---------+----------+-------------+
+| 1 | Default | 0 | 0 | Backup | * |
+| 2 | Recycle | 0 | 8 | Backup | File |
++------+---------+---------+---------+----------+-------------+
+\end{verbatim}
+\normalsize
+
+ Comme mentionn\'e pr\'ec\'edemment, la commande {\bf list} affiche des
+ informations du catalogue. Certais \'el\'ements sont ajout\'es dans le catalogue
+ d\`es le d\'emarrage de Bacula, mais en g\'en\'eral, la plupart ne le sont que
+ lorsqu'ils sont utilis\'es pour la premi\`ere fois. C'est le cas des clients,
+ des jobs, etc.
+
+ Bacula cr\'e\'e une entr\'ee relative \`a un nouveau client dans le catalogue
+ la premi\`ere fois que vous ex\'ecut\'ez un job pour ce client. L'entr\'ee est
+ cr\'e\'ee que le job aboutisse ou qu'il \'echoue, mais il doit au moins d\'emarrer.
+ Lorsque le client est contact\'e, des informations suppl\'ementaires sont
+ r\'ecup\'er\'ees du client (le r\'esultat d'un "uname -a") et ajout\'ees au
+ catalogue. Un {\bf status} n'entra\^ine pas l'enregistrement dans le catalogue.
+
+ Si vous voulez visualiser les ressources Client disponibles dans votre
+ catalogue, utilisez la commande {\bf show clients}.
+
+\item [llist]
+ \index[general]{llist}
+ La commande {\bf llist} (pour "long list") admet les m\^emes arguments que la
+ commande list d\'ecrite ci-dessus. La diff\'erence est que {\bf llist} affiche
+ le contenu complet de chaque enregistrement du catalogue s\'electionn\'e.
+ L'affichage des diff\'erents champs est produit verticalement, un champ par
+ ligne. Cette commande peut \^etre tr\`es prolixe.
+
+ Si, au lieu du {\bf list pools} de l'exemple pr\'ec\'edent, vous saisissez
+ {\bf llist pools}, vous obtiendrez un affichage de ce genre :
+
+\footnotesize
+\begin{verbatim}
+ PoolId: 1
+ Name: Default
+ NumVols: 0
+ MaxVols: 0
+ UseOnce: 0
+ UseCatalog: 1
+ AcceptAnyVolume: 1
+ VolRetention: 1,296,000
+ VolUseDuration: 86,400
+ MaxVolJobs: 0
+ MaxVolBytes: 0
+ AutoPrune: 0
+ Recycle: 1
+ PoolType: Backup
+ LabelFormat: *
+
+ PoolId: 2
+ Name: Recycle
+ NumVols: 0
+ MaxVols: 8
+ UseOnce: 0
+ UseCatalog: 1
+ AcceptAnyVolume: 1
+ VolRetention: 3,600
+ VolUseDuration: 3,600
+ MaxVolJobs: 1
+ MaxVolBytes: 0
+ AutoPrune: 0
+ Recycle: 1
+ PoolType: Backup
+ LabelFormat: File
+
+\end{verbatim}
+\normalsize
+
+\item [messages]
+ \index[general]{messages}
+ Cette commande affiche imm\'ediatement tout message de la console en attente.
+
+
+\item [mount]
+ \index[general]{mount}
+
+ La commande {\bf mount} est utilis\'ee pour obtenir de Bacula qu'il lise
+ un volume charg\'e dans un lecteur. C'est un moyen d'indiquer \`a Bacula
+ que vous avez charg\'e une cartouche qu'il doit examiner. Cette commande
+ n'est utilis\'ee que lorsque Bacula a demand\'e votre intervention pour
+ charger un lecteur vide, ou lorsque vous avez explicitement d\'emont\'e
+ un volume avec la commande {\bf unmount} dans la Console, ce qui
+ provoque la fermeture du lecteur. Si vous avez une librairie, vous ne
+ ferez pas op\'erer Bacula dessus avec la commande mount. Voici les
+ diff\'erentes formes de cette commande :
+
+mount storage=\lt{}storage-name\gt{}
+
+mount [ jobid=\lt{}id\gt{} | job=\lt{}job-name\gt{} ]
+
+ Si vous avez sp\'ecifi\'e {\bf Automatic Mount = yes} dans la ressource
+ Device du Storage Daemon, Alors Bacula pourra acc\'eder automatiquement
+ au volume, \`a moins que vous ne l'ayez explicitement d\'emont\'e ({\bf unmount})
+ dans la Console.
+
+\item[python]
+ \index[general]{python}
+ La commande {\bf python} n'admet qu'un argument : {\bf restart}.
+
+ La commande {\bf python} {\bf restart} r\'einitialise l'interpr\'eteur Python
+ du Director. Ceci peut \^etre tr\`es utile pour effectuer des tests, car une
+ fois que le Director est lanc\'e, et l'interpr\'eteur Python initialis\'e,
+ il n'y a pas d'autre moyen de lui faire int\'egrer des modifications
+ du script de d\'emarrage {\bf DirStartUp.py}. Pour plus de d\'etails sur
+ l'\'ecriture de scripts Python, consultez le chapitre \ilink{Ecrire des
+ scripts Python}{_ChapterStart60}.
+
+\label{ManualPruning}
+\item [prune]
+ \index[general]{prune}
+ La commande {\bf prune} permet d'\'elaguer en toute s\'ecurit\'e les
+ enregistrements expir\'es du catalogue pour les jobs et les volumes.
+ Cette commande n'affecte que le catalogue, et non les donn\'ees
+ \'ecrites sur les volumes. Dans tous les cas, la commande {\bf prune}
+ respecte les p\'eriodes de r\'etention des enregistrements sp\'ecifi\'es.
+ Vous pouvez \'elaguer les jobs expir\'es, ainsi que les jobs et fichiers
+ d'un volume sp\'ecifi\'e.
+
+prune files|jobs|volume client=\lt{}client-name\gt{}
+volume=\lt{}volume-name\gt{}
+
+ Pour qu'un volume soit \'elagu\'e, son {\bf VolStatus} doit \^etre Full,
+ Used, ou Append, faute de quoi l'\'elagage sera sans effet.
+
+\item [purge]
+ \index[general]{purge}
+ La commande {\bf purge} efface les enregistrements sp\'ecifi\'es du catalogue
+ sans \'egards pour les p\'eriodes de r\'etention. {\bf Purge} n'affecte que le
+ catalogue, et non les donn\'ees \'ecrites sur les volumes. Cette commande
+ peut se r\'ev\'eler tr\`es dangereuse car vous pouvez parfaitement supprimer
+ les enregistrements relatifs \`a des sauvegardes valides et r\'ecentes. Aussi,
+ nous vous recommandons de ne pas l'utiliser \`a moins de savoir exactement
+ ce que vous faites. Voici les diff\'erentes formes de la commande {\bf purge} :
+
+purge files jobid=\lt{}jobid\gt{}|job=\lt{}job-name\gt{}|client=\lt{}client-name\gt{}
+
+purge jobs client=\lt{}client-name\gt{} (of all jobs)
+
+purge volume|volume=\lt{}vol-name\gt{} (of all jobs)
+
+
+ Pour qu'un volume puisse \^etre purg\'e, son {\bf VolStatus} doit \^etre Full,
+ Used, ou Append, faute de quoi la purge sera sans effet.
+
+\item [relabel]
+ \index[general]{relabel}
+ \index[general]{relabel}
+ Cette commande sert \`a r\'e-\'etiqueter physiquement un volume. En voici
+ la forme compl\`ete :
+
+relabel storage=\lt{}storage-name\gt{} oldvolume=\lt{}old-volume-name\gt{}
+ volume=\lt{}newvolume-name\gt{}
+
+ Si vous omettez l'un quelconque des arguments, la console vous sollicitera
+ pour obtenir les informations manquantes. Pour qu'un volume puisse \^etre
+ r\'e-\'etiquet\'e, il doit figurer dans le catalogue, et avoir le statut
+ {\bf Purged} ou {\bf Recycle}. Cette situation peut se pr\'esenter
+ automatiquement par l'application des p\'eriodes de r\'etention, ou vous
+ pouvez l'obtenir par une {\bf purge} explicite du volume.
+
+ Une fois que le volume a \'et\'e physiquement r\'e-\'etiquet\'e, les donn\'ees
+ qu'il contenait sont d\'efinitivement et irr\'em\'ediablement perdues.
+
+\item [release]
+ \index[general]{release}
+ Cette commande ordonne au Storage Daemon de rembobiner la cartouche
+ dans le lecteur, et de relire son \'etiquette \`a la prochaine utilisation
+ de la cartouche.
+
+release storage=\lt{}storage-name\gt{}
+
+ Apr\`es cette commande, le lecteur est gard\'e \`a l'\'etat ouvert par Bacula
+ (sauf si l'option Always Open est d\'esactiv\'ee dans la configuration
+ du Storage Daemon), et il ne peut donc \^etre utilis\'e par un autre
+ programme. Toutefois, il est possible, avec certains lecteurs, de
+ changer la cartouche \`a ce stade. Lors du prochain job, Bacula saura
+ relire l'\'etiquette de la cartouche pour savoir laquelle est mont\'ee.
+ Si vous voulez \^etre en mesure d'utiliser le lecteur avec un autre
+ programme, par exemple {\bf mt}, vous devez uiliser la commande
+ {\bf unmount} pour que Bacula le lib\`ere compl\`etement.
+
+\item [reload]
+ \index[general]{reload}
+ Lorsqu'il re\c{c}oit la commande {\bf reload}, le Director relit ses fichiers
+ de configuration et applique les \'eventuelles modifications. Celles-ci
+ sont prises en compte imm\'ediatement, et donc effectives pour tous les
+ jobs \`a venir. Notez cependant qu'en ce qui concerne les modifications
+ apport\'ees aux Schedules, la prise en compte des nouvelles valeur peut
+ \^etre report\'ee au del\`a de l'ex\'ecution des jobs d\'ej\`a planifi\'es pour
+ les deux prochaines heures. Ceci est d\^u au planificateur qui pr\'evoit
+ "pr\'e-planifie" jusqu'\`a deux heures \`a l'avance les jobs \`a ex\'ecuter.
+ Ainsi, des jobs qui ont d\'ej\`a \'et\'e "pr\'e-planifi\'es" seront ex\'ecut\'es
+ suivant les valeurs sp\'ecifi\'ees par la ressource Schedule avant sa
+ modification. Les nouveaux jobs utiliseront les nouvelles valeurs.
+ A chaque fois que vous utilisez la commande {\bf reload} alors que
+ des jobs sont en cours d'ex\'ecution, les valeurs de la configuration
+ pr\'ec\'edente demeurent en vigueur jusqu'\`a ce que les ces jobs se terminent.
+ Le Director peut ainsi conserver jusqu'\`a 10 jeux de configurations
+ ant\'erieures avant de refuser une nouvelle commande {\bf reload}.
+ Une fois que l'un, au moins, des jeux de valeurs ant\'erieur a \'et\'e accept\'e,
+ il peut \`a nouveau accepter de nouvelles commandes {\bf reload}.
+
+ Bien qu'il soit possible de recharger la configuration du Director
+ \`a la vol\'ee, alors m\^eme que des jobs sont en cours d'ex\'ecution, il faut
+ garder \`a l'esprit que c'est une op\'eration complexe, qui n'est pas d\'enu\'ee
+ d'effets de bords. C'est pourquoi il est recommand\'e, si vous \^etes amen\'e \`a
+ utiliser la commande {\bf reload}, de red\'emarrer le Director d\`es que vous
+ en aurez l'opportunit\'e.
+
+\label{restore_command}
+\item [restore]
+ \index[general]{restore}
+ La commande {\bf restore} vous permet de s\'electionner un ou plusieurs jobs
+ (JobIds) \`a restaurer selon plusieurs m\'ethodes. Une fois que les JobIds ont
+ \'et\'e s\'electionn\'es, les enregistrements de fichiers sont plac\'es dans une
+ arborescence interne \`a Bacula, et la Console entre dans un mode de
+ s\'election interactif qui vous permet de naviguer dans cette arborescence
+ en s\'electionnant individuellement les fichiers ou r\'epertoires \`a restaurer.
+ Ce mode est assez similaire au mode de s\'election interactif du programme
+ Unix {\bf restore} standard.
+
+restore storage=\lt{}storage-name\gt{} client=\lt{}client-name\gt{}
+ where=\lt{}path\gt{} pool=\lt{}pool-name\gt{} fileset=\lt{}fileset-name\gt{}
+ select current all done
+
+ O\`u l'option {\bf current}, si elle est sp\'ecifi\'ee, indique \`a la commande
+ {\bf restore} de s\'electionner automatiquement la sauvegarde la plus
+ r\'ecente (sinon, vous serez sollicit\'e \`a ce sujet). L'option {\bf all},
+ si elle est sp\'ecifi\'ee, indique \`a la commande {\bf restore} de restaurer
+ tous les fichiers (sinon, vous serez sollicit\'e \`a ce sujet). Pour plus de
+ d\'etails concernant la commande {\bf restore}, consultez le chapitre
+ \ilink{Restaurations avec Bacula}{_ChapterStart13}.
+
+\item [run]
+ \index[general]{run}
+ Cette commande vous permet d'ex\'ecuter imm\'ediatement vos jobs. Voici la forme
+ compl\`ete de cette commande :
+
+run job=\lt{}job-name\gt{} client=\lt{}client-name\gt{}
+ fileset=\lt{}FileSet-name\gt{} level=\lt{}level-keyword\gt{}
+ storage=\lt{}storage-name\gt{} where=\lt{}directory-prefix\gt{}
+ when=\lt{}universal-time-specification\gt{} yes
+
+ Toute information omise quoique requise fait l'objet d'une liste de s\'election,
+ et avant le lancement du job, un bilan des param\`etres vous est pr\'esent\'e avec
+ options d'accord, refus et modification, \`a moins que vous ayez sp\'ecifi\'e
+ {\bf yes}, auquel cas le job est imm\'ediatement envoy\'e vers le planificateur.
+
+ Sur mon syst\`eme, j'obtiens ce qui suit lorsque je lance la commande run :
+
+\footnotesize
+\begin{verbatim}
+A job name must be specified.
+The defined Job resources are:
+ 1: Matou
+ 2: Polymatou
+ 3: Rufus
+ 4: Minimatou
+ 5: Minou
+ 6: PmatouVerify
+ 7: MatouVerify
+ 8: RufusVerify
+ 9: Watchdog
+Select Job resource (1-9):
+
+\end{verbatim}
+\normalsize
+
+Si je choisis le num\'ero 5, j'obtiens :
+
+\footnotesize
+\begin{verbatim}
+Run Backup job
+JobName: Minou
+FileSet: Minou Full Set
+Level: Incremental
+Client: Minou
+Storage: DLTDrive
+Pool: Default
+When: 2003-04-23 17:08:18
+OK to run? (yes/mod/no):
+
+\end{verbatim}
+\normalsize
+
+Si maintenant j'entre {\bf yes}, le job est ex\'ecut\'e. Si je choisis {\bf mod},
+voici les otpions qui me sont propos\'ees :
+
+\footnotesize
+\begin{verbatim}
+Parameters to modify:
+ 1: Level
+ 2: Storage
+ 3: Job
+ 4: FileSet
+ 5: Client
+ 6: When
+ 7: Pool
+Select parameter to modify (1-7):
+
+\end{verbatim}
+\normalsize
+
+Vous pouvez, si vous le souhaitez, d\'emarrer un job plus tard, en utilisant le
+param\`etre {\bf When}. Pour cela, faites le choix {\bf mod}, puis s\'electionnez
+{\bf When} (no. 6) et enfin, saisissez l'heure et le jour de lancement
+d\'esir\'es au format AAAA-MM-JJ HH:MM:SS.
+
+\item [setdebug]
+ \index[general]{setdebug}
+ \index[general]{setdebug}
+ \index[general]{debuggage}
+ \index[general]{debuggage Win32}
+ \index[general]{Windows!debuggage}
+
+ Cette commande est utilis\'ee pour param\'etrer le niveau de d\'ebuggage de chaque
+ {\it daemon}. Voici la forme compl\`ete de cette commande.
+
+setdebug level=nn [trace=0/1 client=\lt{}client-name\gt{} | dir | director |
+ storage=\lt{}storage-name\gt{} | all]
+
+ Si le param\`etre de tra\c{c}age est actif (trace=1), alors le {\it daemon} est
+ plac\'e en mode tra\c{c}age, ce qui signifie que toutes les informations de
+ d\'ebuggage sont envoy\'ees vers le fichier {\bf bacula.trace} dans le
+ r\'epertoire courant du {\it daemon}. En principe, ce n'est n\'ecessaire
+ que pour le d\'ebuggage des clients Win32 o\`u les informations ne peuvent
+ \^etre envoy\'ees vers un terminal ou redirig\'ees vers un fichier. en mode
+ tra\c{c}age, chaque message de d\'ebuggage est ajout\'e au fichier, que vous devez
+ supprimer explicitement lorsque vous avez fini.
+
+\item [show]
+ \index[general]{show}
+ \index[general]{show}
+ LA commande {\bf show} \'enum\`ere les directives des ressources du Director
+ telles qu'ells sont d\'efinies dans son fichier de configuration.
+ Cette commande est surtout utilis\'ee par les d\'eveloppeurs \`a des fins
+ de d\'ebuggage. LEs mots-clef suivants sont accept\'es :
+ catalogs, clients, counters, devices, directors,
+ filesets, jobs, messages, pools, schedules, storages, all, help.
+ Ne confondez pas cette commande ave la commande {\bf list}, qui affiche
+ quand \`a elle le contenu du catalogue.
+
+\item [sqlquery]
+ \index[general]{sqlquery}
+ La commande {\bf sqlquery} place le programme Console en mode de
+ requ\^etes SQL, dans lequel chaque ligne que vousq tapez est concat\'en\'ee
+ \`a la pr\'ec\'edents jusqu'\`a ce qu'un point-virgule (;) soit rencontr\'e. Le
+ point-virgule termine la commande qui est alors directement envoy\'e au moteur
+ de base de donn\'ee SQL. Lorsque le r\'esultat issu de la base de donn\'ee SQL est
+ affich\'e, la Console est pr\`ete \`a recevoir une nouvelle commande SQL.
+ Pour sortir du mode {\bf sqlquery} et reevenir \`a l'invite de la Console,
+ entrez un point (.).
+
+ Cette commande vous permet d'interroger directement le catalogue. Notez
+ que vous devriez savoir exactement ce que vous faites en utilisant cette
+ commande, car vous pouvez endommager s\'erieusement votre catalogue.
+ Consultez le paragraphe relatif \`a la commande {\bf query} qui offre un
+ moyen \`a la fois plus simple et plus sur de saisir des requ\^etes SQL.
+
+ En fonction du moteur de base de donn\'ees que vous utilisez (MySQL,
+ PostgreSQL ou SQLite), vous disposerez de commandes quelque peu diff\'erentes.
+ Pour plus de d\'etails, r\'ef\'erez-vous aux documentations de MySQL, PostgreSQL
+ ou SQLite.
+
+\item [status]
+ \index[general]{status}
+ Cette commande produit un \'etat des prochains jobs planifi\'es au cours des
+ 24 prochanes heures, ainsi que l'\'etat des jobs en cours d'ex\'ecution. Voici
+ la forme compl\`ete de cette commande :
+
+status [all | dir=\lt{}dir-name\gt{} | director |
+ client=\lt{}client-name\gt{} | storage=\lt{}storage-name\gt{} |
+ days=nnn]
+
+ Si vous entrez {\bf status dir}, la Console \'enum\`ere tous les jobs en cours
+ d'ex\'ecution, un r\'esum\'e des jobs planifi\'e pour ex\'ecution au cours des prochaines
+ 24 heures incluant le volume qui sera probablement utilis\'e, et donne la liste
+ des dix derniers jobs ex\'ecut\'es avec leurs \'etats. Gardez \`a l'esprit les deux
+ \'el\'ements suivants :
+ \begin{itemize}
+ \item L'obtention du volume n\'ecessite d'appliquer le m\^eme algorithme que
+ celui utilis\'e lors de l'ex\'ecution d'un job, ce qui peut r\'esulter en un \'elagage
+ de cartouche.
+ \item Le volume affich\'e est, au mieux, une bonne supposition. En effet le
+ volume effectivement utilis\'e peut \^etre diff\'erent en raison du temps \'ecoul\'e
+ entre le status et l'ex\'ecution du job, un autre job ayant pu, entre temps,
+ remplir compl\`etement la cartouche.
+ \end{itemize}
+
+ Dans la liste des jobs en cours d'ex\'ecutions, vous pouvez trouver ce type
+ d'informations :
+
+\footnotesize
+\begin{verbatim}
+2507 Catalog MatouVerify.2004-03-13_05.05.02 is waiting execution
+5349 Full CatalogBackup.2004-03-13_01.10.00 is waiting for higher
+ priority jobs to finish
+5348 Differe Minou.2004-03-13_01.05.09 is waiting on max Storage jobs
+5343 Full Rufus.2004-03-13_01.05.04 is running
+\end{verbatim}
+\normalsize
+
+ La liste ci-dessus indique que le job de JobId 5343 (Rufus) est en cours.
+ Le job de JobId 5348 (Minou) est en attente de la fin du job 5343
+ qui utilise la m\^eme ressource Storage, ce qui provoque le "waiting
+ on max Storage jobs". Le job de JobId 5349 a une priorit\'e inf\'erieure
+ \`a celle de tous les autres jobs, aussi, il est en attente de la fin de
+ jobs de priorit\'es sup\'erieures. Finalement, le job de jobId 2508 (MatouVerify)
+ est en attente ("waiting execution") car un seul job peut \^etre ex\'ecut\'e
+ en m\^eme temps.
+
+ Si vous faites un {\bf status dir}, Bacula affiche par d\'efaut les premi\`eres
+ occurrences de tous les jobs pr\'evus pour ex\'ecution aujourd'hui et demain.
+ Si vous voulez voir les jobs pr\'evus pour les trois prochains jours,
+ (Si, par exemple vendredi, vous voulez voir les premi\`eres occurrences
+ des cartouches \`a utiliser vendredi, samedi, dimanche et lundi), vous
+ pouvez ajouter l'option {\bf days=3}. Notez, {\bf days=0} montre les
+ premi\`eres occurrences des jobs planifi\'es pour \^etre ex\'ecut\'es aujourd'hui
+ seulement. Si vous avez plusieurs ex\'ecutions planifi\'ees, pour chaque
+ job, seule la premi\`ere occurrence sera affich\'e pour la p\'eriode sp\'ecifi\'ee.
+
+ Si votre job para\^it bloqu\'e, vous pouvez avoir une id\'ee g\'en\'erale du probl\`eme
+ en utilisant {\bf status dir}, et obtenir une information plus sp\'ecifique
+ avec {\bf status storage=xxx}. Par exemple, si j'utilise cette derni\`ere
+ commande sur un syst\`eme inoccup\'e, j'obtiens :
+
+\footnotesize
+\begin{verbatim}
+status storage=File
+Connecting to Storage daemon File at 192.168.68.112:8103
+
+rufus-sd Version: 1.39.6 (24 March 2006) i686-pc-linux-gnu redhat (Stentz)
+Daemon started 26-Mar-06 11:06, 0 Jobs run since started.
+
+Running Jobs:
+No Jobs running.
+====
+
+Jobs waiting to reserve a drive:
+====
+
+Terminated Jobs:
+ JobId Level Files Bytes Status Finished Name
+======================================================================
+ 59 Full 234 4,417,599 OK 15-Jan-06 11:54 kernsave
+====
+
+Device status:
+utochanger "DDS-4-changer" with devices:
+ "DDS-4" (/dev/nst0)
+Device "DDS-4" (/dev/nst0) is mounted with Volume="TestVolume002"
+Pool="*unknown*"
+ Slot 2 is loaded in drive 0.
+ Total Bytes Read=0 Blocks Read=0 Bytes/block=0
+ Positioned at File=0 Block=0
+Device "Dummy" is not open or does not exist.
+No DEVICE structure.
+
+Device "DVD-Writer" (/dev/hdc) is not open.
+Device "File" (/tmp) is not open.
+====
+
+In Use Volume status:
+====
+\end{verbatim}
+\normalsize
+
+Ce qui r\'ev\`ele qu'aucun job n'est en cours d'ex\'ecution, et qu'aucun des
+p\'eriph\'eriques n'est en cours d'utilisation. Si je d\'emonte la librairie
+({\bf unmount}), qui ne sera plus utilis\'ee dans cet exemple, et que je lance
+un job qui utilise le stockage File, le job se bloque. Si je demande \`a
+nouveau {\bf status storage=xxx}, j'obtiens :
+
+\footnotesize
+\begin{verbatim}
+status storage=File
+...
+Device status:
+Autochanger "DDS-4-changer" with devices:
+ "DDS-4" (/dev/nst0)
+Device "DDS-4" (/dev/nst0) is not open.
+ Device is BLOCKED. User unmounted.
+ Drive 0 is not loaded.
+Device "Dummy" is not open or does not exist.
+No DEVICE structure.
+
+Device "DVD-Writer" (/dev/hdc) is not open.
+Device "File" (/tmp) is not open.
+ Device is BLOCKED waiting for media.
+====
+...
+\end{verbatim}
+\normalsize
+
+Il devrait maintenant \^etre clair que si un job n\'ecessitant la librairie
+est ex\'ecut\'e, il bloquera en raison du d\'emontage de cette derni\`ere par
+l'utilisateur. Mais le probl\`eme pour le job que j'ai lanc\'e avec le
+p\'eriph\'erique "File" est que le p\'eriph\'erique est bloqu\'e en attente
+d'un media : Bacula a besoin que vous \'etiquetiez un volume.
+
+\item [unmount]
+ \index[general]{unmount}
+ Cette commande sert \`a ordonner au Storage Daemon de d\'emonter le p\'eriph\'erique
+ sp\'ecifi\'e. Les formes de cette commande sont les m\^emes que celle de la commande
+ mount :
+
+\footnotesize
+\begin{verbatim}
+unmount storage=<storage-name>
+
+unmount [ jobid=<id> | job=<job-name> ]
+\end{verbatim}
+\normalsize
+
+\label{UpdateCommand}
+\item [update]
+ \index[general]{update}
+ Cette commande met \`a jour le catalogue, que ce soit pour un pool sp\'ecifique,
+ un enregistrement de volume, ou les slots d'une librairie dot\'ee d'un lecteur
+ de codes barres. Dans le cas de la mise \`a jour d'un enregistrement de pool,
+ la nouvelle configuration est automatiquement r\'ecup\'er\'ee de la ressource
+ correspondante du fichier de configuration du Director. Cette commande peut
+ notamment servir \`a augmenter le nombre maxial de volumes dans un pool. Les
+ principaux mots-clef suivants peuvent \^etre utilis\'es :
+
+\footnotesize
+\begin{verbatim}
+ media, volume, pool, slots
+\end{verbatim}
+\normalsize
+
+Dans le cas de la mise \`a jour d'un volume, vous serez interrog\'e sur le
+param\`etre que vous voulez modifier. Voici ces param\`etres :
+
+\footnotesize
+\begin{verbatim}
+
+ Volume Status
+ Volume Retention Period
+ Volume Use Duration
+ Maximum Volume Jobs
+ Maximum Volume Files
+ Maximum Volume Bytes
+ Recycle Flag
+ Slot
+ InChanger Flag
+ Pool
+ Volume Files
+ Volume from Pool
+ All Volumes from Pool
+
+\end{verbatim}
+\normalsize
+
+ Pour le param\`etre slot, {\bf update slots}, Bacula obtient une liste
+ de tous les slots et de leurs codes barres du Storage Daemon,
+ pour chaque code barres trouv\'e, le slot est mis \`a jour dans
+ l'enregistrement Media du catalogue. C'est tr\`es pratique si vous
+ d\'eplacez des cartouches dans la librairie, ou si vous changez des
+ magasins de cartouches. Dans la foul\'ee, le drapeau InChanger est
+ aussi mis \`a jour.Ceci permet \`a BAcula de savoir quels cartouches sont
+ effectivement dans la librairie.
+
+ Si vous n'avez pas de lecteur de codes barres, vous pouvez faire la
+ m\^eme chose depuis la version 1.33 gr\^ace \`a la commande {\bf update slots scan}.
+ Le mot-clef {\bf scan} ordonne \`a Bacula de monter physiquement chaque
+ cartouche afin de lire son VolumeName.
+
+ Pour le param\`etre Pool, {\bf update pool}, Bacula d\'eplace le volume de
+ son pool courant vers le pool sp\'ecifi\'e.
+
+ Pour les parm\`etres {\bf Volume from Pool} et {\bf All Volumes from Pool},
+ les valeurs suivantes sont mises \`a jour depuis l'enregistrement
+ de pool : Recycle, VolRetention, VolUseDuration, MaxVolJobs, MaxVolFiles,
+ and MaxVolBytes.
+
+ Voici la forme compl\`ete de la commande {\bf update} :
+
+\footnotesize
+\begin{verbatim}
+ update volume=xxx pool=yyy slots volstatus=xxx VolRetention=ddd
+ VolUse=ddd MaxVolJobs=nnn MaxVolBytes=nnn Recycle=yes|no
+ slot=nnn enabled=n
+
+\end{verbatim}
+\normalsize
+
+\item [use]
+ \index[general]{use}
+ Cette commande vous perment de pr\'eciser le catalogue que vous voulez utiliser.
+ En principe, vous n'utiliserez qu'un seul catalogue, aussi vous n'aurez pas
+ besoin de faire ce choix. Sinon, utilisez cette commande pour passer de l'un
+ de vos catalogues \`a l'autre.
+
+use \lt{}database-name\gt{}
+
+\item [var]
+ \label{var}
+ \index[general]{var name}
+ Cette commande prend une cha\^ine \'eventuellement encadr\'ee de guillemets et effectue
+ l'expansion des variables comme elle serait effectu\'ee au niveau de la
+ directive {\bf LabelFormat}. Ainsi, vous pouvez tester vos cha\^ines
+ de format d'\'etiquetage. La diff\'erence entre la commande {\bf var} et le
+ processus effectif est que pour la premi\`ere, aucun job n'est en cours,
+ aussi des valeurs factices sont utilis\'ees au lieu des variables sp\'ecifiques
+ aux jobs. Cela vous permet cependant de vous faire une bonne id\'ee de ce qui
+ se passerait dans le cas r\'eel.
+
+\item [version]
+ \index[general]{version}
+ Cette commande affiche la version du Director.
+
+\item [quit]
+ \index[general]{quit}
+ Cette commande stoppe le programme Console. Celui-ci envoie la requ\^ete
+ {\bf quit} au Director et attend son accus\'e de r\'eception. Si le Director
+ est occup\'e, cela peut prendre un certain temps. Vous pouvez quitter
+ imm\'ediatement en utilisant la variante {\bf .quit} ({\bf quit} pr\'ec\'ed\'ee
+ d'un point).
+
+\item [query]
+ \index[general]{query}
+ Cette commande lit une requ\^ete SQL pr\'ed\'efinie dans le fichier de requ\^etes
+ (le nom et l'emplacement de ce fichier sont d\'efinis par la directive
+ QueryFile du fichier de configuration du Director). Il vous est alors
+ demand\'e de s\'electionner une requ\^ete du fichier, et \'eventuellement de
+ saisir un ou plusieurs param\`etres. La requ\^ete est alors soumise au
+ moteur de base de donn\'ees.
+
+Les requ\^etes suivantes sont actuellement (version 1.24) disponibles :
+
+\footnotesize
+\begin{verbatim}
+Available queries:
+ 1: List Job totals:
+ 2: List where a file is saved:
+ 3: List where the most recent copies of a file are saved:
+ 4: List total files/bytes by Job:
+ 5: List total files/bytes by Volume:
+ 6: List last 20 Full Backups for a Client:
+ 7: List Volumes used by selected JobId:
+ 8: List Volumes to Restore All Files:
+ 9: List where a File is saved:
+Choose a query (1-9):
+
+\end{verbatim}
+\normalsize
+
+\item [exit]
+ \index[general]{exit}
+ Cette commande termine le programme Console.
+
+\item [wait]
+ \index[general]{wait}
+ Cette commande place le Director en pause jusqu'\`a ce qu'il n'y ait plus
+ aucun job en ex\'ecution. Cette commande est utile dans des situation
+ d'utilisation automatis\'ee par scripts telles que les tests de r\'egression
+ o\`u vous voulez d\'emarrer un job, et attendre qu'il se termine avant de
+ poursuivre. Cette commande admet les options suivantes :
+
+\footnotesize
+\begin{verbatim}
+ wait [jobid=nn] [jobuid=unique id] [job=job name]
+\end{verbatim}
+\normalsize
+
+\end{description}
+
+\label{dotcommands}
+
+\section{Commandes sp\'eciales, pr\'ec\'ed\'ees d'un point}
+\index[general]{Commands!sp\'eciales, pr\'ec\'ed\'ees d'un point}
+\index[general]{Commandes sp\'eciales, pr\'ec\'ed\'ees d'un point}
+\addcontentsline{toc}{section}{Commandes sp\'eciales, pr\'ec\'ed\'ees d'un point}
+
+Voici une liste de commandes pr\'efix\'ees d'un point (.). Elles ont pour vocation
+d'\^etre utilis\'ees soit dans des programmes {\it batch}, soit par des interfaces
+graphiques. Elles ne sont, en principe, pas utilis\'ees en mode interactif.
+Une fois que le d\'eveloppement d'interfaces graphiques aura d\'emarr\'e, cette liste
+s'accro\^itra consid\'erablement.
+
+\footnotesize
+\begin{verbatim}
+.backups job=xxx list backups for specified job
+.defaults client=xxx fileset=yyy list defaults for specified client
+.die cause the Director to segment fault (for debugging)
+.dir when in tree mode prints the equivalent to the dir command,
+ but with fields separated by commas rather than spaces.
+.jobs list all job names
+.levels list all levels
+.filesets list all fileset names
+.clients list all client names
+.pools list all pool names
+.types list job types
+.msgs return any queued messages
+.messages get quick messages
+.help help command output
+.quit quit
+.status get status output
+.exit quit
+\end{verbatim}
+\normalsize
+
+\label{atcommands}
+
+\section{Commandes sp\'eciales, pr\'ec\'ed\'ees d'un arobase (@)}
+\index[general]{Commandes!sp\'eciales arobase @}
+\index[general]{Commandes sp\'eciales, pr\'ec\'ed\'ees d'un arobase (@)}
+\addcontentsline{toc}{section}{Commandes sp\'eciales, pr\'ec\'ed\'ees d'un arobase (@)}
+
+Normalement, toutes les commandes saisies dans la Console sont imm\'ediatement
+transmises au Director, qui peut r\'esider sur une autre machine, afin d'y \^etre
+ex\'ecut\'ees. Il existe cependant quelques commandes, toutes pr\'ec\'ed\'ees du
+caract\`ere arobase (@), qui ne sont pas envoy\'ees au Director, mais
+directement interpr\'et\'ees par la Console. Notez que seule la Console
+tty impl\'emente ces commandes, et non la Console GNOME. En voici la liste :
+
+\begin{description}
+
+\item [@input \lt{}nom-de-fichier\gt{}]
+ \index[general]{@input \lt{}nom-de-fichier\gt{}}
+ Lit et ex\'ecute les commandes consign\'ees dans le fichier sp\'ecifi\'e.
+
+\item [@output \lt{}nom-de-fichier\gt{} w/a]
+ \index[general]{@output \lt{}nom-de-fichier\gt{} w/a}
+ Envoit l'ensemble des retours de la Console vers le fichier sp\'ecifi\'e,
+ avec \'ecrasement si l'option {\bf w} est sp\'ecifi\'ee, ou ajout \`a la suite si l'option
+ {\bf a} est sp\'ecifi\'ee. Pour rediriger la sortie vers le terminal, entrez
+ simplement {\bf output} sans sp\'ecifier de nom de fichier.
+ ATTENTION : prenez garde de ne pas \'ecraser un fichier valide.
+ Voici un exemple typique lors d'un test de r\'egression :
+
+\footnotesize
+\begin{verbatim}
+ @output /dev/null
+ commands ...
+ @output
+
+\end{verbatim}
+\normalsize
+
+\item [@tee \lt{}nom-de-fichier\gt{} w/a]
+ \index[general]{@tee \lt{}nom-de-fichier\gt{} w/a}
+ Comme la commande pr\'ec\'edente avec envoi simultan\'e vers le terminal. Pour
+ sortir de ce mode, vous pouvez utiliser {\bf @tee} ou {\bf @output} sans
+ sp\'ecifier de nom de fichier.
+
+\item [@sleep \lt{}seconds\gt{}]
+ \index[general]{@sleep \lt{}seconds\gt{}}
+ Met en sommeil pour une dur\'ee du nombre de secondes sp\'ecifi\'e.
+
+\item [@time]
+ \index[general]{@time}
+ Affiche la date et l'heure courantes.
+
+\item [@version]
+ \index[general]{@version}
+ Affiche la version de la Console.
+
+\item [@quit]
+ \index[general]{@quit}
+ Quitte.
+
+\item [@exit]
+ \index[general]{@exit}
+ Quitte.
+
+\item [@\# n-importe-quoi]
+ \index[general]{n-importe-quoi}
+ Commentaire.
+\end{description}
+
+\label{scripting}
+
+\section{Ex\'ecuter la Console depuis un script shell}
+\index[general]{Script!Ex\'ecuter la Console depuis un script shell}
+\index[general]{Ex\'ecuter la Console depuis un script shell}
+\addcontentsline{toc}{section}{Ex\'ecuter la Console depuis un script shell}
+Vous pouvez automatiser de nombreuses t\^aches effectu\'ees \`a la Console, en les
+ex\'ecutant dans un script shell. Par exemple, si vous avez cr\'e\'e un fichier
+contenant ceci :
+
+\footnotesize
+\begin{verbatim}
+ ./bconsole -c ./bconsole.conf <<END_OF_DATA
+ unmount storage=DDS-4
+ quit
+ END_OF_DATA
+\end{verbatim}
+\normalsize
+
+A l'ex\'ecution de ce fichier, le p\'eriph\'erique DDS-4 est d\'emont\'e.
+Vous pouvez, si vous le souhaitez, ex\'ecuter cette t\^ache lors d'un job avec
+les directives {\bf RunBeforeJob} ou {\bf RunAfterJob}.
+
+Il est aussi possible d'ex\'ecuter la Console \`a partir de l'entr\'ee d'un
+fichier contenant les commandes comme suit :
+
+\footnotesize
+\begin{verbatim}
+./bconsole -c ./bconsole.conf <filename
+\end{verbatim}
+\normalsize
+
+o\`u le fichier nomm\'e {\bf filename} contient un ensemble quelconque de
+commandes de la Console.
+
+Voici un exemple r\'eel, issu des tests de r\'egression de Bacula. Il
+\'etiquette un volume (sur disque) ex\'ecute une sauvegarde puis une
+restauration des fichiers sauvegard\'es.
+
+\footnotesize
+\begin{verbatim}
+bin/bconsole -c bin/bconsole.conf <<END_OF_DATA
+@output /dev/null
+messages
+@output /tmp/log1.out
+label volume=TestVolume001
+run job=Client1 yes
+wait
+messages
+@#
+@# now do a restore
+@#
+@output /tmp/log2.out
+restore current all
+yes
+wait
+messages
+@output
+quit
+END_OF_DATA
+\end{verbatim}
+\normalsize
+
+Les donn\'ees issues de la sauvegarde sont envoy\'ees vers /tmp/log1.out et
+celles de la restaurations vers /tmp/log2.out. Pour v\'erifier que les
+op\'erations se sont d\'eroul\'ees correctement, les fichiers de sorties
+sont contr\^ol\'es avec :
+
+\footnotesize
+\begin{verbatim}
+grep "^Termination: *Backup OK" /tmp/log1.out
+backupstat=$?
+grep "^Termination: *Restore OK" /tmp/log2.out
+restorestat=$?
+\end{verbatim}
+\normalsize
+
+\section{Ajouter des volumes \`a un pool}
+\index[general]{Ajouter des volumes \`a un pool}
+\index[general]{Pool!Ajouter des volumes \`a un}
+\addcontentsline{toc}{section}{Ajouter des volumes \`a un pool}
+
+Si vous avez utilis\'e la commande {\bf label} pour \'etiqueter un volume, alors
+celui-ci est automatiquement ajout\'e au pool, et vous n'avez pas besoin de le faire
+manuellement.
+
+Une alternative consiste \`a ajouter plusieurs volumes \`a un pool sans les
+\'etiqueter pr\'ealablement. Vous devrez alors les \'etiqueter plus tard, lorsque Bacula
+en aura besoin.
+
+Avant d'ajouter un volume \`a un pool, vous devez conna\^itre les informations
+suivantes :
+
+\begin{enumerate}
+\item Le nom du pool (normalement, "Default") ;
+\item Le type de media tel qu'il est sp\'ecifi\'e dans la ressource Storage
+du fichier de configuration du Director (par exemple, "DLT8000") ;
+\item Le nombre de volumes que vous voulez cr\'eer, et leurs noms.
+The number and names of the Volumes you wish to create.
+\end{enumerate}
+
+Par exemple, pour ajouter un media \`a un pool, vous utiliseriez les commandes
+suivantes dans la Console :
+
+\footnotesize
+\begin{verbatim}
+*add
+Enter name of Pool to add Volumes to: Default
+Enter the Media Type: DLT8000
+Enter number of Media volumes to create. Max=1000: 10
+Enter base volume name: Save
+Enter the starting number: 1
+10 Volumes created in pool Default
+*
+\end{verbatim}
+\normalsize
+
+Pour voir ce que vous avez ajout\'e, tapez :
+
+\footnotesize
+\begin{verbatim}
+*list media pool=Default
++-------+----------+---------+---------+-------+------------------+
+| MedId | VolumeNa | MediaTyp| VolStat | Bytes | LastWritten |
++-------+----------+---------+---------+-------+------------------+
+| 11 | Save0001 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
+| 12 | Save0002 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
+| 13 | Save0003 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
+| 14 | Save0004 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
+| 15 | Save0005 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
+| 16 | Save0006 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
+| 17 | Save0007 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
+| 18 | Save0008 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
+| 19 | Save0009 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
+| 20 | Save0010 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
++-------+----------+---------+---------+-------+------------------+
+*
+\end{verbatim}
+\normalsize
+
+Notez que la Console a automatiquement ajout\'e un num\'ero au nom de volume de
+base que vous avez sp\'ecifi\'e ("Save" dans ce cas). Si vous ne souhaitez pas
+ce comportement, r\'epondez simplement 0 (z\'ero) \`a la queston "Enter number
+of Media volumes to create . Max=1000:" et un seul volume sera cr\'e\'e avec
+le nom exact que vous avez sp\'ecifi\'e.
--- /dev/null
+#!/usr/bin/perl -w
+# Finds potential problems in tex files, and issues warnings to the console
+# about what it finds. Takes a list of files as its only arguments,
+# and does checks on all the files listed. The assumption is that these are
+# valid (or close to valid) LaTeX files. It follows \include statements
+# recursively to pick up any included tex files.
+#
+#
+#
+# Currently the following checks are made:
+#
+# -- Multiple hyphens not inside a verbatim environment (or \verb). These
+# should be placed inside a \verb{} contruct so they will not be converted
+# to single hyphen by latex and latex2html.
+
+
+# Original creation 3-8-05 by Karl Cunningham karlc -at- keckec -dot- com
+#
+#
+
+use strict;
+
+# The following builds the test string to identify and change multiple
+# hyphens in the tex files. Several constructs are identified but only
+# multiple hyphens are changed; the others are fed to the output
+# unchanged.
+my $b = '\\\\begin\\*?\\s*\\{\\s*'; # \begin{
+my $e = '\\\\end\\*?\\s*\\{\\s*'; # \end{
+my $c = '\\s*\\}'; # closing curly brace
+
+# This captures entire verbatim environments. These are passed to the output
+# file unchanged.
+my $verbatimenv = $b . "verbatim" . $c . ".*?" . $e . "verbatim" . $c;
+
+# This captures \verb{..{ constructs. They are passed to the output unchanged.
+my $verb = '\\\\verb\\*?(.).*?\\1';
+
+# This captures multiple hyphens with a leading and trailing space. These are not changed.
+my $hyphsp = '\\s\\-{2,}\\s';
+
+# This identifies other multiple hyphens.
+my $hyphens = '\\-{2,}';
+
+# This identifies \hyperpage{..} commands, which should be ignored.
+my $hyperpage = '\\\\hyperpage\\*?\\{.*?\\}';
+
+# This builds the actual test string from the above strings.
+#my $teststr = "$verbatimenv|$verb|$tocentry|$hyphens";
+my $teststr = "$verbatimenv|$verb|$hyphsp|$hyperpage|$hyphens";
+
+
+sub get_includes {
+ # Get a list of include files from the top-level tex file. The first
+ # argument is a pointer to the list of files found. The rest of the
+ # arguments is a list of filenames to check for includes.
+ my $files = shift;
+ my ($fileline,$includefile,$includes);
+
+ while (my $filename = shift) {
+ # Get a list of all the html files in the directory.
+ open my $if,"<$filename" or die "Cannot open input file $filename\n";
+ $fileline = 0;
+ $includes = 0;
+ while (<$if>) {
+ chomp;
+ $fileline++;
+ # If a file is found in an include, process it.
+ if (($includefile) = /\\include\s*\{(.*?)\}/) {
+ $includes++;
+ # Append .tex to the filename
+ $includefile .= '.tex';
+
+ # If the include file has already been processed, issue a warning
+ # and don't do it again.
+ my $found = 0;
+ foreach (@$files) {
+ if ($_ eq $includefile) {
+ $found = 1;
+ last;
+ }
+ }
+ if ($found) {
+ print "$includefile found at line $fileline in $filename was previously included\n";
+ } else {
+ # The file has not been previously found. Save it and
+ # recursively process it.
+ push (@$files,$includefile);
+ get_includes($files,$includefile);
+ }
+ }
+ }
+ close IF;
+ }
+}
+
+
+sub check_hyphens {
+ my (@files) = @_;
+ my ($filedata,$this,$linecnt,$before);
+
+ # Build the test string to check for the various environments.
+ # We only do the conversion if the multiple hyphens are outside of a
+ # verbatim environment (either \begin{verbatim}...\end{verbatim} or
+ # \verb{--}). Capture those environments and pass them to the output
+ # unchanged.
+
+ foreach my $file (@files) {
+ # Open the file and load the whole thing into $filedata. A bit wasteful but
+ # easier to deal with, and we don't have a problem with speed here.
+ $filedata = "";
+ open IF,"<$file" or die "Cannot open input file $file";
+ while (<IF>) {
+ $filedata .= $_;
+ }
+ close IF;
+
+ # Set up to process the file data.
+ $linecnt = 1;
+
+ # Go through the file data from beginning to end. For each match, save what
+ # came before it and what matched. $filedata now becomes only what came
+ # after the match.
+ # Chech the match to see if it starts with a multiple-hyphen. If so
+ # warn the user. Keep track of line numbers so they can be output
+ # with the warning message.
+ while ($filedata =~ /$teststr/os) {
+ $this = $&;
+ $before = $`;
+ $filedata = $';
+ $linecnt += $before =~ tr/\n/\n/;
+
+ # Check if the multiple hyphen is present outside of one of the
+ # acceptable constructs.
+ if ($this =~ /^\-+/) {
+ print "Possible unwanted multiple hyphen found in line ",
+ "$linecnt of file $file\n";
+ }
+ $linecnt += $this =~ tr/\n/\n/;
+ }
+ }
+}
+##################################################################
+# MAIN ####
+##################################################################
+
+my (@includes,$cnt);
+
+# Examine the file pointed to by the first argument to get a list of
+# includes to test.
+get_includes(\@includes,@ARGV);
+
+check_hyphens(@includes);
--- /dev/null
+/* Century Schoolbook font is very similar to Computer Modern Math: cmmi */
+.MATH { font-family: "Century Schoolbook", serif; }
+.MATH I { font-family: "Century Schoolbook", serif; font-style: italic }
+.BOLDMATH { font-family: "Century Schoolbook", serif; font-weight: bold }
+
+/* implement both fixed-size and relative sizes */
+SMALL.XTINY { font-size : xx-small }
+SMALL.TINY { font-size : x-small }
+SMALL.SCRIPTSIZE { font-size : smaller }
+SMALL.FOOTNOTESIZE { font-size : small }
+SMALL.SMALL { }
+BIG.LARGE { }
+BIG.XLARGE { font-size : large }
+BIG.XXLARGE { font-size : x-large }
+BIG.HUGE { font-size : larger }
+BIG.XHUGE { font-size : xx-large }
+
+/* heading styles */
+H1 { }
+H2 { }
+H3 { }
+H4 { }
+H5 { }
+
+/* mathematics styles */
+DIV.displaymath { } /* math displays */
+TD.eqno { } /* equation-number cells */
+
+
+/* document-specific styles come next */
--- /dev/null
+%%
+%%
+%% The following characters must be preceded by a backslash
+%% to be entered as printable characters:
+%%
+%% # $ % & ~ _ ^ \ { }
+%%
+
+\documentclass[11pt,a4paper]{book}
+\usepackage{html}
+\usepackage{float}
+\usepackage{graphicx}
+\usepackage{bacula}
+\usepackage{longtable}
+\usepackage{makeidx}
+\usepackage{index}
+\usepackage{setspace}
+\usepackage{hyperref}
+\usepackage{url}
+
+
+\makeindex
+\newindex{general}{idx}{ind}{General Index}
+
+\sloppy
+
+\begin{document}
+\sloppy
+
+\newfont{\bighead}{cmr17 at 36pt}
+\parskip 10pt
+\parindent 0pt
+
+\title{\includegraphics{./bacula-logo.eps} \\ \bigskip
+ \Huge{Bacula Console and Operators Guide}
+ \begin{center}
+ \large{It comes in the night and sucks
+ the essence from your computers. }
+ \end{center}
+}
+
+
+\author{Kern Sibbald}
+\date{\vspace{1.0in}\today \\
+ This manual documents Bacula version \input{version} \\
+ \vspace{0.2in}
+ Copyright \copyright 1999-2007, Free Software Foundation Europe
+ e.V. \\
+ \vspace{0.2in}
+ Permission is granted to copy, distribute and/or modify this document under the terms of the
+ GNU Free Documentation License, Version 1.2 published by the Free Software Foundation;
+ with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+ A copy of the license is included in the section entitled "GNU Free Documentation License".
+}
+
+\maketitle
+
+\clearpage
+\tableofcontents
+\clearpage
+\listoffigures
+\clearpage
+\listoftables
+\clearpage
+
+\include{bconsole}
+\include{gui}
+\include{fdl}
+
+
+% The following line tells link_resolver.pl to not include these files:
+% nolinks developersi baculai-dir baculai-fd baculai-sd baculai-console baculai-main
+
+% pull in the index
+\clearpage
+\printindex[general]
+
+\end{document}
--- /dev/null
+#
+# Avoid that @VERSION@ and @DATE@ are changed by configure
+# This file is sourced by update_version
+#
+echo "s%@VERSION@%${VERSION}%g" >${out}
+echo "s%@DATE@%${DATE}%g" >>${out}
--- /dev/null
+% TODO: maybe get rid of centering
+
+\chapter{GNU Free Documentation License}
+\index[general]{GNU Free Documentation License}
+\index[general]{License!GNU Free Documentation}
+
+\label{label_fdl}
+
+ \begin{center}
+
+ Version 1.2, November 2002
+
+
+ Copyright \copyright 2000,2001,2002 Free Software Foundation, Inc.
+
+ \bigskip
+
+ 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
+
+ \bigskip
+
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+\end{center}
+
+
+\begin{center}
+{\bf\large Preamble}
+\end{center}
+
+The purpose of this License is to make a manual, textbook, or other
+functional and useful document "free" in the sense of freedom: to
+assure everyone the effective freedom to copy and redistribute it,
+with or without modifying it, either commercially or noncommercially.
+Secondarily, this License preserves for the author and publisher a way
+to get credit for their work, while not being considered responsible
+for modifications made by others.
+
+This License is a kind of "copyleft", which means that derivative
+works of the document must themselves be free in the same sense. It
+complements the GNU General Public License, which is a copyleft
+license designed for free software.
+
+We have designed this License in order to use it for manuals for free
+software, because free software needs free documentation: a free
+program should come with manuals providing the same freedoms that the
+software does. But this License is not limited to software manuals;
+it can be used for any textual work, regardless of subject matter or
+whether it is published as a printed book. We recommend this License
+principally for works whose purpose is instruction or reference.
+
+
+\begin{center}
+{\Large\bf 1. APPLICABILITY AND DEFINITIONS}
+\end{center}
+
+This License applies to any manual or other work, in any medium, that
+contains a notice placed by the copyright holder saying it can be
+distributed under the terms of this License. Such a notice grants a
+world-wide, royalty-free license, unlimited in duration, to use that
+work under the conditions stated herein. The \textbf{"Document"}, below,
+refers to any such manual or work. Any member of the public is a
+licensee, and is addressed as \textbf{"you"}. You accept the license if you
+copy, modify or distribute the work in a way requiring permission
+under copyright law.
+
+A \textbf{"Modified Version"} of the Document means any work containing the
+Document or a portion of it, either copied verbatim, or with
+modifications and/or translated into another language.
+
+A \textbf{"Secondary Section"} is a named appendix or a front-matter section of
+the Document that deals exclusively with the relationship of the
+publishers or authors of the Document to the Document's overall subject
+(or to related matters) and contains nothing that could fall directly
+within that overall subject. (Thus, if the Document is in part a
+textbook of mathematics, a Secondary Section may not explain any
+mathematics.) The relationship could be a matter of historical
+connection with the subject or with related matters, or of legal,
+commercial, philosophical, ethical or political position regarding
+them.
+
+The \textbf{"Invariant Sections"} are certain Secondary Sections whose titles
+are designated, as being those of Invariant Sections, in the notice
+that says that the Document is released under this License. If a
+section does not fit the above definition of Secondary then it is not
+allowed to be designated as Invariant. The Document may contain zero
+Invariant Sections. If the Document does not identify any Invariant
+Sections then there are none.
+
+The \textbf{"Cover Texts"} are certain short passages of text that are listed,
+as Front-Cover Texts or Back-Cover Texts, in the notice that says that
+the Document is released under this License. A Front-Cover Text may
+be at most 5 words, and a Back-Cover Text may be at most 25 words.
+
+A \textbf{"Transparent"} copy of the Document means a machine-readable copy,
+represented in a format whose specification is available to the
+general public, that is suitable for revising the document
+straightforwardly with generic text editors or (for images composed of
+pixels) generic paint programs or (for drawings) some widely available
+drawing editor, and that is suitable for input to text formatters or
+for automatic translation to a variety of formats suitable for input
+to text formatters. A copy made in an otherwise Transparent file
+format whose markup, or absence of markup, has been arranged to thwart
+or discourage subsequent modification by readers is not Transparent.
+An image format is not Transparent if used for any substantial amount
+of text. A copy that is not "Transparent" is called \textbf{"Opaque"}.
+
+Examples of suitable formats for Transparent copies include plain
+ASCII without markup, Texinfo input format, LaTeX input format, SGML
+or XML using a publicly available DTD, and standard-conforming simple
+HTML, PostScript or PDF designed for human modification. Examples of
+transparent image formats include PNG, XCF and JPG. Opaque formats
+include proprietary formats that can be read and edited only by
+proprietary word processors, SGML or XML for which the DTD and/or
+processing tools are not generally available, and the
+machine-generated HTML, PostScript or PDF produced by some word
+processors for output purposes only.
+
+The \textbf{"Title Page"} means, for a printed book, the title page itself,
+plus such following pages as are needed to hold, legibly, the material
+this License requires to appear in the title page. For works in
+formats which do not have any title page as such, "Title Page" means
+the text near the most prominent appearance of the work's title,
+preceding the beginning of the body of the text.
+
+A section \textbf{"Entitled XYZ"} means a named subunit of the Document whose
+title either is precisely XYZ or contains XYZ in parentheses following
+text that translates XYZ in another language. (Here XYZ stands for a
+specific section name mentioned below, such as \textbf{"Acknowledgements"},
+\textbf{"Dedications"}, \textbf{"Endorsements"}, or \textbf{"History"}.)
+To \textbf{"Preserve the Title"}
+of such a section when you modify the Document means that it remains a
+section "Entitled XYZ" according to this definition.
+
+The Document may include Warranty Disclaimers next to the notice which
+states that this License applies to the Document. These Warranty
+Disclaimers are considered to be included by reference in this
+License, but only as regards disclaiming warranties: any other
+implication that these Warranty Disclaimers may have is void and has
+no effect on the meaning of this License.
+
+
+\begin{center}
+{\Large\bf 2. VERBATIM COPYING}
+\end{center}
+
+You may copy and distribute the Document in any medium, either
+commercially or noncommercially, provided that this License, the
+copyright notices, and the license notice saying this License applies
+to the Document are reproduced in all copies, and that you add no other
+conditions whatsoever to those of this License. You may not use
+technical measures to obstruct or control the reading or further
+copying of the copies you make or distribute. However, you may accept
+compensation in exchange for copies. If you distribute a large enough
+number of copies you must also follow the conditions in section 3.
+
+You may also lend copies, under the same conditions stated above, and
+you may publicly display copies.
+
+
+\begin{center}
+{\Large\bf 3. COPYING IN QUANTITY}
+\end{center}
+
+
+If you publish printed copies (or copies in media that commonly have
+printed covers) of the Document, numbering more than 100, and the
+Document's license notice requires Cover Texts, you must enclose the
+copies in covers that carry, clearly and legibly, all these Cover
+Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
+the back cover. Both covers must also clearly and legibly identify
+you as the publisher of these copies. The front cover must present
+the full title with all words of the title equally prominent and
+visible. You may add other material on the covers in addition.
+Copying with changes limited to the covers, as long as they preserve
+the title of the Document and satisfy these conditions, can be treated
+as verbatim copying in other respects.
+
+If the required texts for either cover are too voluminous to fit
+legibly, you should put the first ones listed (as many as fit
+reasonably) on the actual cover, and continue the rest onto adjacent
+pages.
+
+If you publish or distribute Opaque copies of the Document numbering
+more than 100, you must either include a machine-readable Transparent
+copy along with each Opaque copy, or state in or with each Opaque copy
+a computer-network location from which the general network-using
+public has access to download using public-standard network protocols
+a complete Transparent copy of the Document, free of added material.
+If you use the latter option, you must take reasonably prudent steps,
+when you begin distribution of Opaque copies in quantity, to ensure
+that this Transparent copy will remain thus accessible at the stated
+location until at least one year after the last time you distribute an
+Opaque copy (directly or through your agents or retailers) of that
+edition to the public.
+
+It is requested, but not required, that you contact the authors of the
+Document well before redistributing any large number of copies, to give
+them a chance to provide you with an updated version of the Document.
+
+
+\begin{center}
+{\Large\bf 4. MODIFICATIONS}
+\end{center}
+
+You may copy and distribute a Modified Version of the Document under
+the conditions of sections 2 and 3 above, provided that you release
+the Modified Version under precisely this License, with the Modified
+Version filling the role of the Document, thus licensing distribution
+and modification of the Modified Version to whoever possesses a copy
+of it. In addition, you must do these things in the Modified Version:
+
+\begin{itemize}
+\item[A.]
+ Use in the Title Page (and on the covers, if any) a title distinct
+ from that of the Document, and from those of previous versions
+ (which should, if there were any, be listed in the History section
+ of the Document). You may use the same title as a previous version
+ if the original publisher of that version gives permission.
+
+\item[B.]
+ List on the Title Page, as authors, one or more persons or entities
+ responsible for authorship of the modifications in the Modified
+ Version, together with at least five of the principal authors of the
+ Document (all of its principal authors, if it has fewer than five),
+ unless they release you from this requirement.
+
+\item[C.]
+ State on the Title page the name of the publisher of the
+ Modified Version, as the publisher.
+
+\item[D.]
+ Preserve all the copyright notices of the Document.
+
+\item[E.]
+ Add an appropriate copyright notice for your modifications
+ adjacent to the other copyright notices.
+
+\item[F.]
+ Include, immediately after the copyright notices, a license notice
+ giving the public permission to use the Modified Version under the
+ terms of this License, in the form shown in the Addendum below.
+
+\item[G.]
+ Preserve in that license notice the full lists of Invariant Sections
+ and required Cover Texts given in the Document's license notice.
+
+\item[H.]
+ Include an unaltered copy of this License.
+
+\item[I.]
+ Preserve the section Entitled "History", Preserve its Title, and add
+ to it an item stating at least the title, year, new authors, and
+ publisher of the Modified Version as given on the Title Page. If
+ there is no section Entitled "History" in the Document, create one
+ stating the title, year, authors, and publisher of the Document as
+ given on its Title Page, then add an item describing the Modified
+ Version as stated in the previous sentence.
+
+\item[J.]
+ Preserve the network location, if any, given in the Document for
+ public access to a Transparent copy of the Document, and likewise
+ the network locations given in the Document for previous versions
+ it was based on. These may be placed in the "History" section.
+ You may omit a network location for a work that was published at
+ least four years before the Document itself, or if the original
+ publisher of the version it refers to gives permission.
+
+\item[K.]
+ For any section Entitled "Acknowledgements" or "Dedications",
+ Preserve the Title of the section, and preserve in the section all
+ the substance and tone of each of the contributor acknowledgements
+ and/or dedications given therein.
+
+\item[L.]
+ Preserve all the Invariant Sections of the Document,
+ unaltered in their text and in their titles. Section numbers
+ or the equivalent are not considered part of the section titles.
+
+\item[M.]
+ Delete any section Entitled "Endorsements". Such a section
+ may not be included in the Modified Version.
+
+\item[N.]
+ Do not retitle any existing section to be Entitled "Endorsements"
+ or to conflict in title with any Invariant Section.
+
+\item[O.]
+ Preserve any Warranty Disclaimers.
+\end{itemize}
+
+If the Modified Version includes new front-matter sections or
+appendices that qualify as Secondary Sections and contain no material
+copied from the Document, you may at your option designate some or all
+of these sections as invariant. To do this, add their titles to the
+list of Invariant Sections in the Modified Version's license notice.
+These titles must be distinct from any other section titles.
+
+You may add a section Entitled "Endorsements", provided it contains
+nothing but endorsements of your Modified Version by various
+parties--for example, statements of peer review or that the text has
+been approved by an organization as the authoritative definition of a
+standard.
+
+You may add a passage of up to five words as a Front-Cover Text, and a
+passage of up to 25 words as a Back-Cover Text, to the end of the list
+of Cover Texts in the Modified Version. Only one passage of
+Front-Cover Text and one of Back-Cover Text may be added by (or
+through arrangements made by) any one entity. If the Document already
+includes a cover text for the same cover, previously added by you or
+by arrangement made by the same entity you are acting on behalf of,
+you may not add another; but you may replace the old one, on explicit
+permission from the previous publisher that added the old one.
+
+The author(s) and publisher(s) of the Document do not by this License
+give permission to use their names for publicity for or to assert or
+imply endorsement of any Modified Version.
+
+
+\begin{center}
+{\Large\bf 5. COMBINING DOCUMENTS}
+\end{center}
+
+
+You may combine the Document with other documents released under this
+License, under the terms defined in section 4 above for modified
+versions, provided that you include in the combination all of the
+Invariant Sections of all of the original documents, unmodified, and
+list them all as Invariant Sections of your combined work in its
+license notice, and that you preserve all their Warranty Disclaimers.
+
+The combined work need only contain one copy of this License, and
+multiple identical Invariant Sections may be replaced with a single
+copy. If there are multiple Invariant Sections with the same name but
+different contents, make the title of each such section unique by
+adding at the end of it, in parentheses, the name of the original
+author or publisher of that section if known, or else a unique number.
+Make the same adjustment to the section titles in the list of
+Invariant Sections in the license notice of the combined work.
+
+In the combination, you must combine any sections Entitled "History"
+in the various original documents, forming one section Entitled
+"History"; likewise combine any sections Entitled "Acknowledgements",
+and any sections Entitled "Dedications". You must delete all sections
+Entitled "Endorsements".
+
+\begin{center}
+{\Large\bf 6. COLLECTIONS OF DOCUMENTS}
+\end{center}
+
+You may make a collection consisting of the Document and other documents
+released under this License, and replace the individual copies of this
+License in the various documents with a single copy that is included in
+the collection, provided that you follow the rules of this License for
+verbatim copying of each of the documents in all other respects.
+
+You may extract a single document from such a collection, and distribute
+it individually under this License, provided you insert a copy of this
+License into the extracted document, and follow this License in all
+other respects regarding verbatim copying of that document.
+
+
+\begin{center}
+{\Large\bf 7. AGGREGATION WITH INDEPENDENT WORKS}
+\end{center}
+
+
+A compilation of the Document or its derivatives with other separate
+and independent documents or works, in or on a volume of a storage or
+distribution medium, is called an "aggregate" if the copyright
+resulting from the compilation is not used to limit the legal rights
+of the compilation's users beyond what the individual works permit.
+When the Document is included in an aggregate, this License does not
+apply to the other works in the aggregate which are not themselves
+derivative works of the Document.
+
+If the Cover Text requirement of section 3 is applicable to these
+copies of the Document, then if the Document is less than one half of
+the entire aggregate, the Document's Cover Texts may be placed on
+covers that bracket the Document within the aggregate, or the
+electronic equivalent of covers if the Document is in electronic form.
+Otherwise they must appear on printed covers that bracket the whole
+aggregate.
+
+
+\begin{center}
+{\Large\bf 8. TRANSLATION}
+\end{center}
+
+
+Translation is considered a kind of modification, so you may
+distribute translations of the Document under the terms of section 4.
+Replacing Invariant Sections with translations requires special
+permission from their copyright holders, but you may include
+translations of some or all Invariant Sections in addition to the
+original versions of these Invariant Sections. You may include a
+translation of this License, and all the license notices in the
+Document, and any Warranty Disclaimers, provided that you also include
+the original English version of this License and the original versions
+of those notices and disclaimers. In case of a disagreement between
+the translation and the original version of this License or a notice
+or disclaimer, the original version will prevail.
+
+If a section in the Document is Entitled "Acknowledgements",
+"Dedications", or "History", the requirement (section 4) to Preserve
+its Title (section 1) will typically require changing the actual
+title.
+
+
+\begin{center}
+{\Large\bf 9. TERMINATION}
+\end{center}
+
+
+You may not copy, modify, sublicense, or distribute the Document except
+as expressly provided for under this License. Any other attempt to
+copy, modify, sublicense or distribute the Document is void, and will
+automatically terminate your rights under this License. However,
+parties who have received copies, or rights, from you under this
+License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
+
+\begin{center}
+{\Large\bf 10. FUTURE REVISIONS OF THIS LICENSE}
+\end{center}
+
+
+The Free Software Foundation may publish new, revised versions
+of the GNU Free Documentation License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns. See
+http://www.gnu.org/copyleft/.
+
+Each version of the License is given a distinguishing version number.
+If the Document specifies that a particular numbered version of this
+License "or any later version" applies to it, you have the option of
+following the terms and conditions either of that specified version or
+of any later version that has been published (not as a draft) by the
+Free Software Foundation. If the Document does not specify a version
+number of this License, you may choose any version ever published (not
+as a draft) by the Free Software Foundation.
+
+
+\begin{center}
+{\Large\bf ADDENDUM: How to use this License for your documents}
+% TODO: this is too long for table of contents
+\end{center}
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and
+license notices just after the title page:
+
+\bigskip
+\begin{quote}
+ Copyright \copyright YEAR YOUR NAME.
+ Permission is granted to copy, distribute and/or modify this document
+ under the terms of the GNU Free Documentation License, Version 1.2
+ or any later version published by the Free Software Foundation;
+ with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+ A copy of the license is included in the section entitled "GNU
+ Free Documentation License".
+\end{quote}
+\bigskip
+
+If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
+replace the "with...Texts." line with this:
+
+\bigskip
+\begin{quote}
+ with the Invariant Sections being LIST THEIR TITLES, with the
+ Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
+\end{quote}
+\bigskip
+
+If you have Invariant Sections without Cover Texts, or some other
+combination of the three, merge those two alternatives to suit the
+situation.
+
+If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of
+free software license, such as the GNU General Public License,
+to permit their use in free software.
+
+%---------------------------------------------------------------------
--- /dev/null
+#!/usr/bin/perl -w
+# Fixes various things within tex files.
+
+use strict;
+
+my %args;
+
+
+sub get_includes {
+ # Get a list of include files from the top-level tex file.
+ my (@list,$file);
+
+ foreach my $filename (@_) {
+ $filename or next;
+ # Start with the top-level latex file so it gets checked too.
+ push (@list,$filename);
+
+ # Get a list of all the html files in the directory.
+ open IF,"<$filename" or die "Cannot open input file $filename";
+ while (<IF>) {
+ chomp;
+ push @list,"$1.tex" if (/\\include\{(.*?)\}/);
+ }
+
+ close IF;
+ }
+ return @list;
+}
+
+sub convert_files {
+ my (@files) = @_;
+ my ($linecnt,$filedata,$output,$itemcnt,$indentcnt,$cnt);
+
+ $cnt = 0;
+ foreach my $file (@files) {
+ # Open the file and load the whole thing into $filedata. A bit wasteful but
+ # easier to deal with, and we don't have a problem with speed here.
+ $filedata = "";
+ open IF,"<$file" or die "Cannot open input file $file";
+ while (<IF>) {
+ $filedata .= $_;
+ }
+ close IF;
+
+ # We look for a line that starts with \item, and indent the two next lines (if not blank)
+ # by three spaces.
+ my $linecnt = 3;
+ $indentcnt = 0;
+ $output = "";
+ # Process a line at a time.
+ foreach (split(/\n/,$filedata)) {
+ $_ .= "\n"; # Put back the return.
+ # If this line is less than the third line past the \item command,
+ # and the line isn't blank and doesn't start with whitespace
+ # add three spaces to the start of the line. Keep track of the number
+ # of lines changed.
+ if ($linecnt < 3 and !/^\\item/) {
+ if (/^[^\n\s]/) {
+ $output .= " " . $_;
+ $indentcnt++;
+ } else {
+ $output .= $_;
+ }
+ $linecnt++;
+ } else {
+ $linecnt = 3;
+ $output .= $_;
+ }
+ /^\\item / and $linecnt = 1;
+ }
+
+
+ # This is an item line. We need to process it too. If inside a \begin{description} environment, convert
+ # \item {\bf xxx} to \item [xxx] or \item [{xxx}] (if xxx contains '[' or ']'.
+ $itemcnt = 0;
+ $filedata = $output;
+ $output = "";
+ my ($before,$descrip,$this,$between);
+
+ # Find any \begin{description} environment
+ while ($filedata =~ /(\\begin[\s\n]*\{[\s\n]*description[\s\n]*\})(.*?)(\\end[\s\n]*\{[\s\n]*description[\s\n]*\})/s) {
+ $output .= $` . $1;
+ $filedata = $3 . $';
+ $descrip = $2;
+
+ # Search for \item {\bf xxx}
+ while ($descrip =~ /\\item[\s\n]*\{[\s\n]*\\bf[\s\n]*/s) {
+ $descrip = $';
+ $output .= $`;
+ ($between,$descrip) = find_matching_brace($descrip);
+ if (!$descrip) {
+ $linecnt = $output =~ tr/\n/\n/;
+ print STDERR "Missing matching curly brace at line $linecnt in $file\n" if (!$descrip);
+ }
+
+ # Now do the replacement.
+ $between = '{' . $between . '}' if ($between =~ /\[|\]/);
+ $output .= "\\item \[$between\]";
+ $itemcnt++;
+ }
+ $output .= $descrip;
+ }
+ $output .= $filedata;
+
+ # If any hyphens or \item commnads were converted, save the file.
+ if ($indentcnt or $itemcnt) {
+ open OF,">$file" or die "Cannot open output file $file";
+ print OF $output;
+ close OF;
+ print "$indentcnt indent", ($indentcnt == 1) ? "" : "s"," added in $file\n";
+ print "$itemcnt item", ($itemcnt == 1) ? "" : "s"," Changed in $file\n";
+ }
+
+ $cnt += $indentcnt + $itemcnt;
+ }
+ return $cnt;
+}
+
+sub find_matching_brace {
+ # Finds text up to the next matching brace. Assumes that the input text doesn't contain
+ # the opening brace, but we want to find text up to a matching closing one.
+ # Returns the text between the matching braces, followed by the rest of the text following
+ # (which does not include the matching brace).
+ #
+ my $str = shift;
+ my ($this,$temp);
+ my $cnt = 1;
+
+ while ($cnt) {
+ # Ignore verbatim constructs involving curly braces, or if the character preceding
+ # the curly brace is a backslash.
+ if ($str =~ /\\verb\*?\{.*?\{|\\verb\*?\}.*?\}|\{|\}/s) {
+ $this .= $`;
+ $str = $';
+ $temp = $&;
+
+ if ((substr($this,-1,1) eq '\\') or
+ $temp =~ /^\\verb/) {
+ $this .= $temp;
+ next;
+ }
+
+ $cnt += ($temp eq '{') ? 1 : -1;
+ # If this isn't the matching curly brace ($cnt > 0), include the brace.
+ $this .= $temp if ($cnt);
+ } else {
+ # No matching curly brace found.
+ return ($this . $str,'');
+ }
+ }
+ return ($this,$str);
+}
+
+sub check_arguments {
+ # Checks command-line arguments for ones starting with -- puts them into
+ # a hash called %args and removes them from @ARGV.
+ my $args = shift;
+ my $i;
+
+ for ($i = 0; $i < $#ARGV; $i++) {
+ $ARGV[$i] =~ /^\-+/ or next;
+ $ARGV[$i] =~ s/^\-+//;
+ $args{$ARGV[$i]} = "";
+ delete ($ARGV[$i]);
+
+ }
+}
+
+##################################################################
+# MAIN ####
+##################################################################
+
+my @includes;
+my $cnt;
+
+check_arguments(\%args);
+die "No Files given to Check\n" if ($#ARGV < 0);
+
+# Examine the file pointed to by the first argument to get a list of
+# includes to test.
+@includes = get_includes(@ARGV);
+
+$cnt = convert_files(@includes);
+print "No lines changed\n" unless $cnt;
--- /dev/null
+# This module does multiple indices, supporting the style of the LaTex 'index'
+# package.
+
+# Version Information:
+# 16-Feb-2005 -- Original Creation. Karl E. Cunningham
+# 14-Mar-2005 -- Clarified and Consolodated some of the code.
+# Changed to smoothly handle single and multiple indices.
+
+# Two LaTeX index formats are supported...
+# --- SINGLE INDEX ---
+# \usepackage{makeidx}
+# \makeindex
+# \index{entry1}
+# \index{entry2}
+# \index{entry3}
+# ...
+# \printindex
+#
+# --- MULTIPLE INDICES ---
+#
+# \usepackage{makeidx}
+# \usepackage{index}
+# \makeindex -- latex2html doesn't care but LaTeX does.
+# \newindex{ref1}{ext1}{ext2}{title1}
+# \newindex{ref2}{ext1}{ext2}{title2}
+# \newindex{ref3}{ext1}{ext2}{title3}
+# \index[ref1]{entry1}
+# \index[ref1]{entry2}
+# \index[ref3]{entry3}
+# \index[ref2]{entry4}
+# \index{entry5}
+# \index[ref3]{entry6}
+# ...
+# \printindex[ref1]
+# \printindex[ref2]
+# \printindex[ref3]
+# \printindex
+# ___________________
+#
+# For the multiple-index style, each index is identified by the ref argument to \newindex, \index,
+# and \printindex. A default index is allowed, which is indicated by omitting the optional
+# argument. The default index does not require a \newindex command. As \index commands
+# are encountered, their entries are stored according
+# to the ref argument. When the \printindex command is encountered, the stored index
+# entries for that argument are retrieved and printed. The title for each index is taken
+# from the last argument in the \newindex command.
+# While processing \index and \printindex commands, if no argument is given the index entries
+# are built into a default index. The title of the default index is simply "Index".
+# This makes the difference between single- and multiple-index processing trivial.
+#
+# Another method can be used by omitting the \printindex command and just using \include to
+# pull in index files created by the makeindex program. These files will start with
+# \begin{theindex}. This command is used to determine where to print the index. Using this
+# approach, the indices will be output in the same order as the newindex commands were
+# originally found (see below). Using a combination of \printindex and \include{indexfile} has not
+# been tested and may produce undesireable results.
+#
+# The index data are stored in a hash for later sorting and output. As \printindex
+# commands are handled, the order in which they were found in the tex filea is saved,
+# associated with the ref argument to \printindex.
+#
+# We use the original %index hash to store the index data into. We append a \002 followed by the
+# name of the index to isolate the entries in different indices from each other. This is necessary
+# so that different indices can have entries with the same name. For the default index, the \002 is
+# appended without the name.
+#
+# Since the index order in the output cannot be determined if the \include{indexfile}
+# command is used, the order will be assumed from the order in which the \newindex
+# commands were originally seen in the TeX files. This order is saved as well as the
+# order determined from any printindex{ref} commands. If \printindex commnads are used
+# to specify the index output, that order will be used. If the \include{idxfile} command
+# is used, the order of the original newindex commands will be used. In this case the
+# default index will be printed last since it doesn't have a corresponding \newindex
+# command and its order cannot be determined. Mixing \printindex and \include{idxfile}
+# commands in the same file is likely to produce less than satisfactory results.
+#
+#
+# The hash containing index data is named %indices. It contains the following data:
+#{
+# 'title' => {
+# $ref1 => $indextitle ,
+# $ref2 => $indextitle ,
+# ...
+# },
+# 'newcmdorder' => [ ref1, ref2, ..., * ], # asterisk indicates the position of the default index.
+# 'printindorder' => [ ref1, ref2, ..., * ], # asterisk indicates the position of the default index.
+#}
+
+
+# Globals to handle multiple indices.
+my %indices;
+
+# This tells the system to use up to 7 words in index entries.
+$WORDS_IN_INDEX = 10;
+
+# KEC 2-18-05
+# Handles the \newindex command. This is called if the \newindex command is
+# encountered in the LaTex source. Gets the index ref and title from the arguments.
+# Saves the index ref and title.
+# Note that we are called once to handle multiple \newindex commands that are
+# newline-separated.
+sub do_cmd_newindex {
+ my $data = shift;
+ # The data is sent to us as fields delimited by their ID #'s. We extract the
+ # fields.
+ foreach my $line (split("\n",$data)) {
+ my @fields = split (/(?:\<\#\d+?\#\>)+/,$line);
+
+ # The index name and title are the second and fourth fields in the data.
+ if ($line =~ /^</ or $line =~ /^\\newindex/) {
+ my ($indexref,$indextitle) = ($fields[1],$fields[4]);
+ $indices{'title'}{$indexref} = $indextitle;
+ push (@{$indices{'newcmdorder'}},$indexref);
+ }
+ }
+}
+
+
+# KEC -- Copied from makeidx.perl and modified to do multiple indices.
+# Processes an \index entry from the LaTex file.
+# Gets the optional argument from the index command, which is the name of the index
+# into which to place the entry.
+# Drops the brackets from the index_name
+# Puts the index entry into the html stream
+# Creates the tokenized index entry (which also saves the index entry info
+sub do_real_index {
+ local($_) = @_;
+ local($pat,$idx_entry,$index_name);
+ # catches opt-arg from \index commands for index.sty
+ $index_name = &get_next_optional_argument;
+ $index_name = "" unless defined $index_name;
+ # Drop leading and trailing brackets from the index name.
+ $index_name =~ s/^\[|\]$//g;
+
+ $idx_entry = &missing_braces unless (
+ (s/$next_pair_pr_rx/$pat=$1;$idx_entry=$2;''/e)
+ ||(s/$next_pair_rx/$pat=$1;$idx_entry=$2;''/e));
+
+ if ($index_name and defined $idx_entry and
+ !defined $indices{'title'}{$index_name}) {
+ print STDERR "\nInvalid Index Name: \\index \[$index_name\]\{$idx_entry\}\n";
+ }
+
+ $idx_entry = &named_index_entry($pat, $idx_entry,$index_name);
+ $idx_entry.$_;
+}
+
+# Creates and saves an index entry in the index hashes.
+# Modified to do multiple indices.
+# Creates an index_key that allows index entries to have the same characteristics but be in
+# different indices. This index_key is the regular key with the index name appended.
+# Save the index order for the entry in the %index_order hash.
+sub named_index_entry {
+ local($br_id, $str, $index_name) = @_;
+ my ($index_key);
+ # escape the quoting etc characters
+ # ! -> \001
+ # @ -> \002
+ # | -> \003
+ $* = 1; $str =~ s/\n\s*/ /g; $* = 0; # remove any newlines
+ # protect \001 occurring with images
+ $str =~ s/\001/\016/g; # 0x1 to 0xF
+ $str =~ s/\\\\/\011/g; # Double backslash -> 0xB
+ $str =~ s/\\;SPMquot;/\012/g; # \;SPMquot; -> 0xC
+ $str =~ s/;SPMquot;!/\013/g; # ;SPMquot; -> 0xD
+ $str =~ s/!/\001/g; # Exclamation point -> 0x1
+ $str =~ s/\013/!/g; # 0xD -> Exclaimation point
+ $str =~ s/;SPMquot;@/\015/g; # ;SPMquot;@ to 0xF
+ $str =~ s/@/\002/g; # At sign -> 0x2
+ $str =~ s/\015/@/g; # 0xF to At sign
+ $str =~ s/;SPMquot;\|/\017/g; # ;SMPquot;| to 0x11
+ $str =~ s/\|/\003/g; # Vertical line to 0x3
+ $str =~ s/\017/|/g; # 0x11 to vertical line
+ $str =~ s/;SPMquot;(.)/\1/g; # ;SPMquot; -> whatever the next character is
+ $str =~ s/\012/;SPMquot;/g; # 0x12 to ;SPMquot;
+ $str =~ s/\011/\\\\/g; # 0x11 to double backslash
+ local($key_part, $pageref) = split("\003", $str, 2);
+
+ # For any keys of the form: blablabla!blablabla, which want to be split at the
+ # exclamation point, replace the ! with a comma and a space. We don't do it
+ # that way for this index.
+ $key_part =~ s/\001/, /g;
+ local(@keys) = split("\001", $key_part);
+ # If TITLE is not yet available use $before.
+ $TITLE = $saved_title if (($saved_title)&&(!($TITLE)||($TITLE eq $default_title)));
+ $TITLE = $before unless $TITLE;
+ # Save the reference
+ local($words) = '';
+ if ($SHOW_SECTION_NUMBERS) { $words = &make_idxnum; }
+ elsif ($SHORT_INDEX) { $words = &make_shortidxname; }
+ else { $words = &make_idxname; }
+ local($super_key) = '';
+ local($sort_key, $printable_key, $cur_key);
+ foreach $key (@keys) {
+ $key =~ s/\016/\001/g; # revert protected \001s
+ ($sort_key, $printable_key) = split("\002", $key);
+ #
+ # RRM: 16 May 1996
+ # any \label in the printable-key will have already
+ # created a label where the \index occurred.
+ # This has to be removed, so that the desired label
+ # will be found on the Index page instead.
+ #
+ if ($printable_key =~ /tex2html_anchor_mark/ ) {
+ $printable_key =~ s/><tex2html_anchor_mark><\/A><A//g;
+ local($tmpA,$tmpB) = split("NAME=\"", $printable_key);
+ ($tmpA,$tmpB) = split("\"", $tmpB);
+ $ref_files{$tmpA}='';
+ $index_labels{$tmpA} = 1;
+ }
+ #
+ # resolve and clean-up the hyperlink index-entries
+ # so they can be saved in an index.pl file
+ #
+ if ($printable_key =~ /$cross_ref_mark/ ) {
+ local($label,$id,$ref_label);
+ # $printable_key =~ s/$cross_ref_mark#(\w+)#(\w+)>$cross_ref_mark/
+ $printable_key =~ s/$cross_ref_mark#([^#]+)#([^>]+)>$cross_ref_mark/
+ do { ($label,$id) = ($1,$2);
+ $ref_label = $external_labels{$label} unless
+ ($ref_label = $ref_files{$label});
+ '"' . "$ref_label#$label" . '">' .
+ &get_ref_mark($label,$id)}
+ /geo;
+ }
+ $printable_key =~ s/<\#[^\#>]*\#>//go;
+ #RRM
+ # recognise \char combinations, for a \backslash
+ #
+ $printable_key =~ s/\&\#;\'134/\\/g; # restore \\s
+ $printable_key =~ s/\&\#;\`<BR> /\\/g; # ditto
+ $printable_key =~ s/\&\#;*SPMquot;92/\\/g; # ditto
+ #
+ # $sort_key .= "@$printable_key" if !($printable_key); # RRM
+ $sort_key .= "@$printable_key" if !($sort_key); # RRM
+ $sort_key =~ tr/A-Z/a-z/;
+ if ($super_key) {
+ $cur_key = $super_key . "\001" . $sort_key;
+ $sub_index{$super_key} .= $cur_key . "\004";
+ } else {
+ $cur_key = $sort_key;
+ }
+
+ # Append the $index_name to the current key with a \002 delimiter. This will
+ # allow the same index entry to appear in more than one index.
+ $index_key = $cur_key . "\002$index_name";
+
+ $index{$index_key} .= "";
+
+ #
+ # RRM, 15 June 1996
+ # if there is no printable key, but one is known from
+ # a previous index-entry, then use it.
+ #
+ if (!($printable_key) && ($printable_key{$index_key}))
+ { $printable_key = $printable_key{$index_key}; }
+# if (!($printable_key) && ($printable_key{$cur_key}))
+# { $printable_key = $printable_key{$cur_key}; }
+ #
+ # do not overwrite the printable_key if it contains an anchor
+ #
+ if (!($printable_key{$index_key} =~ /tex2html_anchor_mark/ ))
+ { $printable_key{$index_key} = $printable_key || $key; }
+# if (!($printable_key{$cur_key} =~ /tex2html_anchor_mark/ ))
+# { $printable_key{$cur_key} = $printable_key || $key; }
+
+ $super_key = $cur_key;
+ }
+ #
+ # RRM
+ # page-ranges, from |( and |) and |see
+ #
+ if ($pageref) {
+ if ($pageref eq "\(" ) {
+ $pageref = '';
+ $next .= " from ";
+ } elsif ($pageref eq "\)" ) {
+ $pageref = '';
+ local($next) = $index{$index_key};
+# local($next) = $index{$cur_key};
+ # $next =~ s/[\|] *$//;
+ $next =~ s/(\n )?\| $//;
+ $index{$index_key} = "$next to ";
+# $index{$cur_key} = "$next to ";
+ }
+ }
+
+ if ($pageref) {
+ $pageref =~ s/\s*$//g; # remove trailing spaces
+ if (!$pageref) { $pageref = ' ' }
+ $pageref =~ s/see/<i>see <\/i> /g;
+ #
+ # RRM: 27 Dec 1996
+ # check if $pageref corresponds to a style command.
+ # If so, apply it to the $words.
+ #
+ local($tmp) = "do_cmd_$pageref";
+ if (defined &$tmp) {
+ $words = &$tmp("<#0#>$words<#0#>");
+ $words =~ s/<\#[^\#]*\#>//go;
+ $pageref = '';
+ }
+ }
+ #
+ # RRM: 25 May 1996
+ # any \label in the pageref section will have already
+ # created a label where the \index occurred.
+ # This has to be removed, so that the desired label
+ # will be found on the Index page instead.
+ #
+ if ($pageref) {
+ if ($pageref =~ /tex2html_anchor_mark/ ) {
+ $pageref =~ s/><tex2html_anchor_mark><\/A><A//g;
+ local($tmpA,$tmpB) = split("NAME=\"", $pageref);
+ ($tmpA,$tmpB) = split("\"", $tmpB);
+ $ref_files{$tmpA}='';
+ $index_labels{$tmpA} = 1;
+ }
+ #
+ # resolve and clean-up any hyperlinks in the page-ref,
+ # so they can be saved in an index.pl file
+ #
+ if ($pageref =~ /$cross_ref_mark/ ) {
+ local($label,$id,$ref_label);
+ # $pageref =~ s/$cross_ref_mark#(\w+)#(\w+)>$cross_ref_mark/
+ $pageref =~ s/$cross_ref_mark#([^#]+)#([^>]+)>$cross_ref_mark/
+ do { ($label,$id) = ($1,$2);
+ $ref_files{$label} = ''; # ???? RRM
+ if ($index_labels{$label}) { $ref_label = ''; }
+ else { $ref_label = $external_labels{$label}
+ unless ($ref_label = $ref_files{$label});
+ }
+ '"' . "$ref_label#$label" . '">' . &get_ref_mark($label,$id)}/geo;
+ }
+ $pageref =~ s/<\#[^\#>]*\#>//go;
+
+ if ($pageref eq ' ') { $index{$index_key}='@'; }
+ else { $index{$index_key} .= $pageref . "\n | "; }
+ } else {
+ local($thisref) = &make_named_href('',"$CURRENT_FILE#$br_id",$words);
+ $thisref =~ s/\n//g;
+ $index{$index_key} .= $thisref."\n | ";
+ }
+ #print "\nREF: $sort_key : $index_key :$index{$index_key}";
+
+ #join('',"<A NAME=$br_id>$anchor_invisible_mark<\/A>",$_);
+
+ "<A NAME=\"$br_id\">$anchor_invisible_mark<\/A>";
+}
+
+
+# KEC. -- Copied from makeidx.perl, then modified to do multiple indices.
+# Feeds the index entries to the output. This is called for each index to be built.
+#
+# Generates a list of lookup keys for index entries, from both %printable_keys
+# and %index keys.
+# Sorts the keys according to index-sorting rules.
+# Removes keys with a 0x01 token. (duplicates?)
+# Builds a string to go to the index file.
+# Adds the index entries to the string if they belong in this index.
+# Keeps track of which index is being worked on, so only the proper entries
+# are included.
+# Places the index just built in to the output at the proper place.
+{ my $index_number = 0;
+sub add_real_idx {
+ print "\nDoing the index ... Index Number $index_number\n";
+ local($key, @keys, $next, $index, $old_key, $old_html);
+ my ($idx_ref,$keyref);
+ # RRM, 15.6.96: index constructed from %printable_key, not %index
+ @keys = keys %printable_key;
+
+ while (/$idx_mark/) {
+ # Get the index reference from what follows the $idx_mark and
+ # remove it from the string.
+ s/$idxmark\002(.*?)\002/$idxmark/;
+ $idx_ref = $1;
+ $index = '';
+ # include non- makeidx index-entries
+ foreach $key (keys %index) {
+ next if $printable_key{$key};
+ $old_key = $key;
+ if ($key =~ s/###(.*)$//) {
+ next if $printable_key{$key};
+ push (@keys, $key);
+ $printable_key{$key} = $key;
+ if ($index{$old_key} =~ /HREF="([^"]*)"/i) {
+ $old_html = $1;
+ $old_html =~ /$dd?([^#\Q$dd\E]*)#/;
+ $old_html = $1;
+ } else { $old_html = '' }
+ $index{$key} = $index{$old_key} . $old_html."</A>\n | ";
+ };
+ }
+ @keys = sort makeidx_keysort @keys;
+ @keys = grep(!/\001/, @keys);
+ my $cnt = 0;
+ foreach $key (@keys) {
+ my ($keyref) = $key =~ /.*\002(.*)/;
+ next unless ($idx_ref eq $keyref); # KEC.
+ $index .= &add_idx_key($key);
+ $cnt++;
+ }
+ print "$cnt Index Entries Added\n";
+ $index = '<DD>'.$index unless ($index =~ /^\s*<D(D|T)>/);
+ $index_number++; # KEC.
+ if ($SHORT_INDEX) {
+ print "(compact version with Legend)";
+ local($num) = ( $index =~ s/\<D/<D/g );
+ if ($num > 50 ) {
+ s/$idx_mark/$preindex<HR><DL>\n$index\n<\/DL>$preindex/o;
+ } else {
+ s/$idx_mark/$preindex<HR><DL>\n$index\n<\/DL>/o;
+ }
+ } else {
+ s/$idx_mark/<DL COMPACT>\n$index\n<\/DL>/o; }
+ }
+}
+}
+
+# KEC. Copied from latex2html.pl and modified to support multiple indices.
+# The bibliography and the index should be treated as separate sections
+# in their own HTML files. The \bibliography{} command acts as a sectioning command
+# that has the desired effect. But when the bibliography is constructed
+# manually using the thebibliography environment, or when using the
+# theindex environment it is not possible to use the normal sectioning
+# mechanism. This subroutine inserts a \bibliography{} or a dummy
+# \textohtmlindex command just before the appropriate environments
+# to force sectioning.
+sub add_bbl_and_idx_dummy_commands {
+ local($id) = $global{'max_id'};
+
+ s/([\\]begin\s*$O\d+$C\s*thebibliography)/$bbl_cnt++; $1/eg;
+ ## if ($bbl_cnt == 1) {
+ s/([\\]begin\s*$O\d+$C\s*thebibliography)/$id++; "\\bibliography$O$id$C$O$id$C $1"/geo;
+ #}
+ $global{'max_id'} = $id;
+ # KEC. Modified to global substitution to place multiple index tokens.
+ s/[\\]begin\s*($O\d+$C)\s*theindex/\\textohtmlindex$1/go;
+ # KEC. Modified to pick up the optional argument to \printindex
+ s/[\\]printindex\s*(\[.*?\])?/
+ do { (defined $1) ? "\\textohtmlindex $1" : "\\textohtmlindex []"; } /ego;
+ &lib_add_bbl_and_idx_dummy_commands() if defined(&lib_add_bbl_and_idx_dummy_commands);
+}
+
+# KEC. Copied from latex2html.pl and modified to support multiple indices.
+# For each textohtmlindex mark found, determine the index titles and headers.
+# We place the index ref in the header so the proper index can be generated later.
+# For the default index, the index ref is blank.
+#
+# One problem is that this routine is called twice.. Once for processing the
+# command as originally seen, and once for processing the command when
+# doing the name for the index file. We can detect that by looking at the
+# id numbers (or ref) surrounding the \theindex command, and not incrementing
+# index_number unless a new id (or ref) is seen. This has the side effect of
+# having to unconventionally start the index_number at -1. But it works.
+#
+# Gets the title from the list of indices.
+# If this is the first index, save the title in $first_idx_file. This is what's referenced
+# in the navigation buttons.
+# Increment the index_number for next time.
+# If the indexname command is defined or a newcommand defined for indexname, do it.
+# Save the index TITLE in the toc
+# Save the first_idx_file into the idxfile. This goes into the nav buttons.
+# Build index_labels if needed.
+# Create the index headings and put them in the output stream.
+
+{ my $index_number = 0; # Will be incremented before use.
+ my $first_idx_file; # Static
+ my $no_increment = 0;
+
+sub do_cmd_textohtmlindex {
+ local($_) = @_;
+ my ($idxref,$idxnum,$index_name);
+
+ # We get called from make_name with the first argument = "\001noincrement". This is a sign
+ # to not increment $index_number the next time we are called. We get called twice, once
+ # my make_name and once by process_command. Unfortunately, make_name calls us just to set the name
+ # but doesn't use the result so we get called a second time by process_command. This works fine
+ # except for cases where there are multiple indices except if they aren't named, which is the case
+ # when the index is inserted by an include command in latex. In these cases we are only able to use
+ # the index number to decide which index to draw from, and we don't know how to increment that index
+ # number if we get called a variable number of times for the same index, as is the case between
+ # making html (one output file) and web (multiple output files) output formats.
+ if (/\001noincrement/) {
+ $no_increment = 1;
+ return;
+ }
+
+ # Remove (but save) the index reference
+ s/^\s*\[(.*?)\]/{$idxref = $1; "";}/e;
+
+ # If we have an $idxref, the index name was specified. In this case, we have all the
+ # information we need to carry on. Otherwise, we need to get the idxref
+ # from the $index_number and set the name to "Index".
+ if ($idxref) {
+ $index_name = $indices{'title'}{$idxref};
+ } else {
+ if (defined ($idxref = $indices{'newcmdorder'}->[$index_number])) {
+ $index_name = $indices{'title'}{$idxref};
+ } else {
+ $idxref = '';
+ $index_name = "Index";
+ }
+ }
+
+ $idx_title = "Index"; # The name displayed in the nav bar text.
+
+ # Only set $idxfile if we are at the first index. This will point the
+ # navigation panel to the first index file rather than the last.
+ $first_idx_file = $CURRENT_FILE if ($index_number == 0);
+ $idxfile = $first_idx_file; # Pointer for the Index button in the nav bar.
+ $toc_sec_title = $index_name; # Index link text in the toc.
+ $TITLE = $toc_sec_title; # Title for this index, from which its filename is built.
+ if (%index_labels) { &make_index_labels(); }
+ if (($SHORT_INDEX) && (%index_segment)) { &make_preindex(); }
+ else { $preindex = ''; }
+ local $idx_head = $section_headings{'textohtmlindex'};
+ local($heading) = join(''
+ , &make_section_heading($TITLE, $idx_head)
+ , $idx_mark, "\002", $idxref, "\002" );
+ local($pre,$post) = &minimize_open_tags($heading);
+ $index_number++ unless ($no_increment);
+ $no_increment = 0;
+ join('',"<BR>\n" , $pre, $_);
+}
+}
+
+# Returns an index key, given the key passed as the first argument.
+# Not modified for multiple indices.
+sub add_idx_key {
+ local($key) = @_;
+ local($index, $next);
+ if (($index{$key} eq '@' )&&(!($index_printed{$key}))) {
+ if ($SHORT_INDEX) { $index .= "<DD><BR>\n<DT>".&print_key."\n<DD>"; }
+ else { $index .= "<DT><DD><BR>\n<DT>".&print_key."\n<DD>"; }
+ } elsif (($index{$key})&&(!($index_printed{$key}))) {
+ if ($SHORT_INDEX) {
+ $next = "<DD>".&print_key."\n : ". &print_idx_links;
+ } else {
+ $next = "<DT>".&print_key."\n<DD>". &print_idx_links;
+ }
+ $index .= $next."\n";
+ $index_printed{$key} = 1;
+ }
+
+ if ($sub_index{$key}) {
+ local($subkey, @subkeys, $subnext, $subindex);
+ @subkeys = sort(split("\004", $sub_index{$key}));
+ if ($SHORT_INDEX) {
+ $index .= "<DD>".&print_key unless $index_printed{$key};
+ $index .= "<DL>\n";
+ } else {
+ $index .= "<DT>".&print_key."\n<DD>" unless $index_printed{$key};
+ $index .= "<DL COMPACT>\n";
+ }
+ foreach $subkey (@subkeys) {
+ $index .= &add_sub_idx_key($subkey) unless ($index_printed{$subkey});
+ }
+ $index .= "</DL>\n";
+ }
+ return $index;
+}
+
+1; # Must be present as the last line.
--- /dev/null
+# This file serves as a place to put initialization code and constants to
+# affect the behavior of latex2html for generating the bacula manuals.
+
+# $LINKPOINT specifies what filename to use to link to when creating
+# index.html. Not that this is a hard link.
+$LINKPOINT='"$OVERALL_TITLE"';
+
+
+# The following must be the last line of this file.
+1;
--- /dev/null
+/*
+ * html2latex
+ */
+
+available {
+ sun4_sunos.4
+ sun4_solaris.2
+ rs_aix.3
+ rs_aix.4
+ sgi_irix
+}
+
+description {
+ From Jeffrey Schaefer, Geometry Center. Translates HTML document to LaTeX
+}
+
+install {
+ bin/html2latex /afs/rpi.edu/dept/acs/rpinfo/filters/GChtml2latex/html2latex
+ bin/html2latex.tag /afs/rpi.edu/dept/acs/rpinfo/filters/GChtml2latex/html2latex.tag
+ bin/html2latex-local.tag /afs/rpi.edu/dept/acs/rpinfo/filters/GChtml2latex/html2latex-local.tag
+ bin/webtex2latex.tag /afs/rpi.edu/dept/acs/rpinfo/filters/GChtml2latex/webtex2latex.tag
+ man/man1/html2latex.1 /afs/rpi.edu/dept/acs/rpinfo/filters/GChtml2latex/html2latex.1
+}
--- /dev/null
+#!/usr/bin/perl -w
+#
+use strict;
+
+# Used to change the names of the image files generated by latex2html from imgxx.png
+# to meaningful names. Provision is made to go either from or to the meaningful names.
+# The meaningful names are obtained from a file called imagename_translations, which
+# is generated by extensions to latex2html in the make_image_file subroutine in
+# bacula.perl.
+
+# Opens the file imagename_translations and reads the contents into a hash.
+# The hash is creaed with the imgxx.png files as the key if processing TO
+# meaningful filenames, and with the meaningful filenames as the key if
+# processing FROM meaningful filenames.
+# Then opens the html file(s) indicated in the command-line arguments and
+# changes all image references according to the translations described in the
+# above file. Finally, it renames the image files.
+#
+# Original creation: 3-27-05 by Karl Cunningham.
+# Modified 5-21-05 to go FROM and TO meaningful filenames.
+#
+my $TRANSFILE = "imagename_translations";
+my $path;
+
+# Loads the contents of $TRANSFILE file into the hash referenced in the first
+# argument. The hash is loaded to translate old to new if $direction is 0,
+# otherwise it is loaded to translate new to old. In this context, the
+# 'old' filename is the meaningful name, and the 'new' filename is the
+# imgxx.png filename. It is assumed that the old image is the one that
+# latex2html has used as the source to create the imgxx.png filename.
+# The filename extension is taken from the file
+sub read_transfile {
+ my ($trans,$direction) = @_;
+
+ if (!open IN,"<$path$TRANSFILE") {
+ print "WARNING: Cannot open image translation file $path$TRANSFILE for reading\n";
+ print " Image filename translation aborted\n\n";
+ exit 0;
+ }
+
+ while (<IN>) {
+ chomp;
+ my ($new,$old) = split(/\001/);
+
+ # Old filenames will usually have a leading ./ which we don't need.
+ $old =~ s/^\.\///;
+
+ # The filename extension of the old filename must be made to match
+ # the new filename because it indicates the encoding format of the image.
+ my ($ext) = $new =~ /(\.[^\.]*)$/;
+ $old =~ s/\.[^\.]*$/$ext/;
+ if ($direction == 0) {
+ $trans->{$new} = $old;
+ } else {
+ $trans->{$old} = $new;
+ }
+ }
+ close IN;
+}
+
+# Translates the image names in the file given as the first argument, according to
+# the translations in the hash that is given as the second argument.
+# The file contents are read in entirely into a string, the string is processed, and
+# the file contents are then written. No particular care is taken to ensure that the
+# file is not lost if a system failure occurs at an inopportune time. It is assumed
+# that the html files being processed here can be recreated on demand.
+#
+# Links to other files are added to the %filelist for processing. That way,
+# all linked files will be processed (assuming they are local).
+sub translate_html {
+ my ($filename,$trans,$filelist) = @_;
+ my ($contents,$out,$this,$img,$dest);
+ my $cnt = 0;
+
+ # If the filename is an external link ignore it. And drop any file:// from
+ # the filename.
+ $filename =~ /^(http|ftp|mailto)\:/ and return 0;
+ $filename =~ s/^file\:\/\///;
+ # Load the contents of the html file.
+ if (!open IF,"<$path$filename") {
+ print "WARNING: Cannot open $path$filename for reading\n";
+ print " Image Filename Translation aborted\n\n";
+ exit 0;
+ }
+
+ while (<IF>) {
+ $contents .= $_;
+ }
+ close IF;
+
+ # Now do the translation...
+ # First, search for an image filename.
+ while ($contents =~ /\<\s*IMG[^\>]*SRC=\"/si) {
+ $contents = $';
+ $out .= $` . $&;
+
+ # The next thing is an image name. Get it and translate it.
+ $contents =~ /^(.*?)\"/s;
+ $contents = $';
+ $this = $&;
+ $img = $1;
+ # If the image is in our list of ones to be translated, do it
+ # and feed the result to the output.
+ $cnt += $this =~ s/$img/$trans->{$img}/ if (defined($trans->{$img}));
+ $out .= $this;
+ }
+ $out .= $contents;
+
+ # Now send the translated text to the html file, overwriting what's there.
+ open OF,">$path$filename" or die "Cannot open $path$filename for writing\n";
+ print OF $out;
+ close OF;
+
+ # Now look for any links to other files and add them to the list of files to do.
+ while ($out =~ /\<\s*A[^\>]*HREF=\"(.*?)\"/si) {
+ $out = $';
+ $dest = $1;
+ # Drop an # and anything after it.
+ $dest =~ s/\#.*//;
+ $filelist->{$dest} = '' if $dest;
+ }
+ return $cnt;
+}
+
+# REnames the image files spefified in the %translate hash.
+sub rename_images {
+ my $translate = shift;
+ my ($response);
+
+ foreach (keys(%$translate)) {
+ if (! $translate->{$_}) {
+ print " WARNING: No destination Filename for $_\n";
+ } else {
+ $response = `mv -f $path$_ $path$translate->{$_} 2>&1`;
+ $response and print "ERROR from system $response\n";
+ }
+ }
+}
+
+#################################################
+############# MAIN #############################
+################################################
+
+# %filelist starts out with keys from the @ARGV list. As files are processed,
+# any links to other files are added to the %filelist. A hash of processed
+# files is kept so we don't do any twice.
+
+# The first argument must be either --to_meaningful_names or --from_meaningful_names
+
+my (%translate,$search_regex,%filelist,%completed,$thisfile);
+my ($cnt,$direction);
+
+my $arg0 = shift(@ARGV);
+$arg0 =~ /^(--to_meaningful_names|--from_meaningful_names)$/ or
+ die "ERROR: First argument must be either \'--to_meaningful_names\' or \'--from_meaningful_names\'\n";
+
+$direction = ($arg0 eq '--to_meaningful_names') ? 0 : 1;
+
+(@ARGV) or die "ERROR: Filename(s) to process must be given as arguments\n";
+
+# Use the first argument to get the path to the file of translations.
+my $tmp = $ARGV[0];
+($path) = $tmp =~ /(.*\/)/;
+$path = '' unless $path;
+
+read_transfile(\%translate,$direction);
+
+foreach (@ARGV) {
+ # Strip the path from the filename, and use it later on.
+ if (s/(.*\/)//) {
+ $path = $1;
+ } else {
+ $path = '';
+ }
+ $filelist{$_} = '';
+
+ while ($thisfile = (keys(%filelist))[0]) {
+ $cnt += translate_html($thisfile,\%translate,\%filelist) if (!exists($completed{$thisfile}));
+ delete($filelist{$thisfile});
+ $completed{$thisfile} = '';
+ }
+ print "translate_images.pl: $cnt image filenames translated ",($direction)?"from":"to"," meaningful names\n";
+}
+
+rename_images(\%translate);
--- /dev/null
+#!/bin/sh
+#
+# Script file to update the Bacula version
+#
+out=/tmp/$$
+VERSION=`sed -n -e 's/^.*VERSION.*"\(.*\)"$/\1/p' /home/kern/bacula/k/src/version.h`
+DATE=`sed -n -e 's/^.*[ \t]*BDATE.*"\(.*\)"$/\1/p' /home/kern/bacula/k/src/version.h`
+. ./do_echo
+sed -f ${out} version.tex.in >version.tex
+rm -f ${out}
--- /dev/null
+#!/bin/sh
+#
+# Script file to update the Bacula version
+#
+out=/tmp/$$
+VERSION=`sed -n -e 's/^.*VERSION.*"\(.*\)"$/\1/p' @bacula@/src/version.h`
+DATE=`sed -n -e 's/^.*[ \t]*BDATE.*"\(.*\)"$/\1/p' @bacula@/src/version.h`
+. ./do_echo
+sed -f ${out} version.tex.in >version.tex
+rm -f ${out}
--- /dev/null
+2.3.6 (04 November 2007)
--- /dev/null
+@VERSION@ (@DATE@)
--- /dev/null
+#
+#
+# Makefile for LaTeX
+#
+# To build everything do
+# make tex
+# make web
+# make html
+# make dvipdf
+#
+# or simply
+#
+# make
+#
+
+IMAGES=../../../images
+
+DOC=developers
+
+first_rule: all
+
+all: tex web html dvipdf
+
+.SUFFIXES: .tex .html
+.PHONY:
+.DONTCARE:
+
+
+tex:
+ @cp -fp ${IMAGES}/hires/*.eps .
+ touch ${DOC}.idx ${DOC}i-general.tex
+ -latex -interaction=batchmode ${DOC}.tex
+ makeindex ${DOC}.idx >/dev/null 2>/dev/null
+ -latex -interaction=batchmode ${DOC}.tex
+ @rm -f *.eps *.old
+
+pdf:
+ @echo "Making ${DOC} pdf"
+ @cp -fp ${IMAGES}/hires/*.eps .
+ dvipdf ${DOC}.dvi ${DOC}.pdf
+ @rm -f *.eps *.old
+
+dvipdf:
+ @echo "Making ${DOC} pdfm"
+ @cp -fp ${IMAGES}/hires/*.eps .
+ dvipdfm -p a4 ${DOC}.dvi
+ @rm -f *.eps *.old
+
+html:
+ @echo "Making ${DOC} html"
+ @cp -fp ${IMAGES}/*.eps .
+ @rm -f next.eps next.png prev.eps prev.png up.eps up.png
+ @touch ${DOC}.html
+ @(if [ -f imagename_translations ] ; then \
+ ./translate_images.pl --from_meaningful_names ${DOC}.html; \
+ fi)
+ latex2html -white -no_subdir -split 0 -toc_stars -white -notransparent \
+ ${DOC} >/dev/null
+ ./translate_images.pl --to_meaningful_names ${DOC}.html
+ @rm -f *.eps *.gif *.jpg *.old
+
+web:
+ @echo "Making ${DOC} web"
+ @mkdir -p ${DOC}
+ @rm -f ${DOC}/*
+ @cp -fp ${IMAGES}/*.eps .
+ @rm -f next.eps next.png prev.eps prev.png up.eps up.png
+ @cp -fp ${IMAGES}/*.eps ${IMAGES}/*.png ${DOC}/
+ @rm -f ${DOC}/next.eps ${DOC}/next.png ${DOC}/prev.eps ${DOC}/prev.png ${DOC}/up.eps ${DOC}/up.png
+ @(if [ -f ${DOC}/imagename_translations ] ; then \
+ ./translate_images.pl --to_meaningful_names ${DOC}/Developer*Guide.html; \
+ fi)
+ @rm -rf ${DOC}/*.html
+ latex2html -split 4 -local_icons -t "Developer's Guide" -long_titles 4 \
+ -contents_in_nav -toc_stars -white -notransparent ${DOC} >/dev/null
+ ./translate_images.pl --to_meaningful_names ${DOC}/Developer*Guide.html
+ @cp -f ${DOC}/${DOC}_Guide.html ${DOC}/index.html
+ @rm -f *.eps *.gif *.jpg ${DOC}/*.eps *.old
+ @rm -f ${DOC}/idle.png
+ @rm -f ${DOC}/win32-*.png ${DOC}/wx-console*.png ${DOC}/xp-*.png
+ @rm -f ${DOC}/*.pl ${DOC}/*.log ${DOC}/*.aux ${DOC}/*.idx
+ @rm -f ${DOC}/*.out WARNINGS
+
+texcheck:
+ ./check_tex.pl ${DOC}.tex
+
+main_configs:
+ pic2graph -density 100 <main_configs.pic >main_configs.png
+
+clean:
+ @rm -f 1 2 3
+ @rm -f *.png *.gif *.jpg *.eps
+ @rm -f *.pdf *.aux *.cp *.fn *.ky *.log *.pg
+ @rm -f *.html *.backup *.pdf *.ps *.dvi *.ilg *.lof *.lot
+ @rm -f *.cdx *.cnd *.ddx *.ddn *.fdx *.fnd *.ind *.sdx *.snd
+ @rm -f *.dnd imagename_translations
+ @rm -f *.old WARNINGS *.out *.toc *.idx
+ @rm -f images.pl labels.pl internals.pl
+ @rm -rf ${DOC}
+ @rm -f images.tex ${DOC}i.tex
+ @rm -f ${DOC}i-*.tex
+
+
+distclean: clean
+ @rm -f ${DOC}.html ${DOC}.pdf
+ @rm -f Makefile version.tex
--- /dev/null
+#
+#
+# Makefile for LaTeX
+#
+# To build everything do
+# make tex
+# make web
+# make html
+# make dvipdf
+#
+# or simply
+#
+# make
+#
+
+IMAGES=../../../images
+
+DOC=developers
+
+first_rule: all
+
+all: tex web html dvipdf
+
+.SUFFIXES: .tex .html
+.PHONY:
+.DONTCARE:
+
+
+tex:
+ @cp -fp ${IMAGES}/hires/*.eps .
+ touch ${DOC}.idx ${DOC}i-general.tex
+ -latex -interaction=batchmode ${DOC}.tex
+ makeindex ${DOC}.idx >/dev/null 2>/dev/null
+ -latex -interaction=batchmode ${DOC}.tex
+ @rm -f *.eps *.old
+
+pdf:
+ @echo "Making ${DOC} pdf"
+ @cp -fp ${IMAGES}/hires/*.eps .
+ dvipdf ${DOC}.dvi ${DOC}.pdf
+ @rm -f *.eps *.old
+
+dvipdf:
+ @echo "Making ${DOC} pdfm"
+ @cp -fp ${IMAGES}/hires/*.eps .
+ dvipdfm -p a4 ${DOC}.dvi
+ @rm -f *.eps *.old
+
+html:
+ @echo "Making ${DOC} html"
+ @cp -fp ${IMAGES}/*.eps .
+ @rm -f next.eps next.png prev.eps prev.png up.eps up.png
+ @touch ${DOC}.html
+ @(if [ -f imagename_translations ] ; then \
+ ./translate_images.pl --from_meaningful_names ${DOC}.html; \
+ fi)
+ latex2html -white -no_subdir -split 0 -toc_stars -white -notransparent \
+ ${DOC} >/dev/null
+ ./translate_images.pl --to_meaningful_names ${DOC}.html
+ @rm -f *.eps *.gif *.jpg *.old
+
+web:
+ @echo "Making ${DOC} web"
+ @mkdir -p ${DOC}
+ @rm -f ${DOC}/*
+ @cp -fp ${IMAGES}/*.eps .
+ @rm -f next.eps next.png prev.eps prev.png up.eps up.png
+ @cp -fp ${IMAGES}/*.eps ${IMAGES}/*.png ${DOC}/
+ @rm -f ${DOC}/next.eps ${DOC}/next.png ${DOC}/prev.eps ${DOC}/prev.png ${DOC}/up.eps ${DOC}/up.png
+ @(if [ -f ${DOC}/imagename_translations ] ; then \
+ ./translate_images.pl --to_meaningful_names ${DOC}/Developer*Guide.html; \
+ fi)
+ @rm -rf ${DOC}/*.html
+ latex2html -split 4 -local_icons -t "Developer's Guide" -long_titles 4 \
+ -contents_in_nav -toc_stars -white -notransparent ${DOC} >/dev/null
+ ./translate_images.pl --to_meaningful_names ${DOC}/Developer*Guide.html
+ @cp -f ${DOC}/${DOC}_Guide.html ${DOC}/index.html
+ @rm -f *.eps *.gif *.jpg ${DOC}/*.eps *.old
+ @rm -f ${DOC}/idle.png
+ @rm -f ${DOC}/win32-*.png ${DOC}/wx-console*.png ${DOC}/xp-*.png
+ @rm -f ${DOC}/*.pl ${DOC}/*.log ${DOC}/*.aux ${DOC}/*.idx
+ @rm -f ${DOC}/*.out WARNINGS
+
+texcheck:
+ ./check_tex.pl ${DOC}.tex
+
+main_configs:
+ pic2graph -density 100 <main_configs.pic >main_configs.png
+
+clean:
+ @rm -f 1 2 3
+ @rm -f *.png *.gif *.jpg *.eps
+ @rm -f *.pdf *.aux *.cp *.fn *.ky *.log *.pg
+ @rm -f *.html *.backup *.pdf *.ps *.dvi *.ilg *.lof *.lot
+ @rm -f *.cdx *.cnd *.ddx *.ddn *.fdx *.fnd *.ind *.sdx *.snd
+ @rm -f *.dnd imagename_translations
+ @rm -f *.old WARNINGS *.out *.toc *.idx
+ @rm -f images.pl labels.pl internals.pl
+ @rm -rf ${DOC}
+ @rm -f images.tex ${DOC}i.tex
+ @rm -f ${DOC}i-*.tex
+
+
+distclean: clean
+ @rm -f ${DOC}.html ${DOC}.pdf
+ @rm -f Makefile version.tex
--- /dev/null
+%%
+%%
+
+\chapter{Catalog Services}
+\label{_ChapterStart30}
+\index[general]{Services!Catalog }
+\index[general]{Catalog Services }
+
+\section{General}
+\index[general]{General }
+\addcontentsline{toc}{subsection}{General}
+
+This chapter is intended to be a technical discussion of the Catalog services
+and as such is not targeted at end users but rather at developers and system
+administrators that want or need to know more of the working details of {\bf
+Bacula}.
+
+The {\bf Bacula Catalog} services consist of the programs that provide the SQL
+database engine for storage and retrieval of all information concerning files
+that were backed up and their locations on the storage media.
+
+We have investigated the possibility of using the following SQL engines for
+Bacula: Beagle, mSQL, GNU SQL, PostgreSQL, SQLite, Oracle, and MySQL. Each
+presents certain problems with either licensing or maturity. At present, we
+have chosen for development purposes to use MySQL, PostgreSQL and SQLite.
+MySQL was chosen because it is fast, proven to be reliable, widely used, and
+actively being developed. MySQL is released under the GNU GPL license.
+PostgreSQL was chosen because it is a full-featured, very mature database, and
+because Dan Langille did the Bacula driver for it. PostgreSQL is distributed
+under the BSD license. SQLite was chosen because it is small, efficient, and
+can be directly embedded in {\bf Bacula} thus requiring much less effort from
+the system administrator or person building {\bf Bacula}. In our testing
+SQLite has performed very well, and for the functions that we use, it has
+never encountered any errors except that it does not appear to handle
+databases larger than 2GBytes. That said, we would not recommend it for
+serious production use.
+
+The Bacula SQL code has been written in a manner that will allow it to be
+easily modified to support any of the current SQL database systems on the
+market (for example: mSQL, iODBC, unixODBC, Solid, OpenLink ODBC, EasySoft
+ODBC, InterBase, Oracle8, Oracle7, and DB2).
+
+If you do not specify either {\bf \verb{--{with-mysql} or {\bf \verb{--{with-postgresql} or
+{\bf \verb{--{with-sqlite} on the ./configure line, Bacula will use its minimalist
+internal database. This database is kept for build reasons but is no longer
+supported. Bacula {\bf requires} one of the three databases (MySQL,
+PostgreSQL, or SQLite) to run.
+
+\subsection{Filenames and Maximum Filename Length}
+\index[general]{Filenames and Maximum Filename Length }
+\index[general]{Length!Filenames and Maximum Filename }
+\addcontentsline{toc}{subsubsection}{Filenames and Maximum Filename Length}
+
+In general, either MySQL, PostgreSQL or SQLite permit storing arbitrary long
+path names and file names in the catalog database. In practice, there still
+may be one or two places in the Catalog interface code that restrict the
+maximum path length to 512 characters and the maximum file name length to 512
+characters. These restrictions are believed to have been removed. Please note,
+these restrictions apply only to the Catalog database and thus to your ability
+to list online the files saved during any job. All information received and
+stored by the Storage daemon (normally on tape) allows and handles arbitrarily
+long path and filenames.
+
+\subsection{Installing and Configuring MySQL}
+\index[general]{MySQL!Installing and Configuring }
+\index[general]{Installing and Configuring MySQL }
+\addcontentsline{toc}{subsubsection}{Installing and Configuring MySQL}
+
+For the details of installing and configuring MySQL, please see the
+\ilink{Installing and Configuring MySQL}{_ChapterStart} chapter of
+this manual.
+
+\subsection{Installing and Configuring PostgreSQL}
+\index[general]{PostgreSQL!Installing and Configuring }
+\index[general]{Installing and Configuring PostgreSQL }
+\addcontentsline{toc}{subsubsection}{Installing and Configuring PostgreSQL}
+
+For the details of installing and configuring PostgreSQL, please see the
+\ilink{Installing and Configuring PostgreSQL}{_ChapterStart10}
+chapter of this manual.
+
+\subsection{Installing and Configuring SQLite}
+\index[general]{Installing and Configuring SQLite }
+\index[general]{SQLite!Installing and Configuring }
+\addcontentsline{toc}{subsubsection}{Installing and Configuring SQLite}
+
+For the details of installing and configuring SQLite, please see the
+\ilink{Installing and Configuring SQLite}{_ChapterStart33} chapter of
+this manual.
+
+\subsection{Internal Bacula Catalog}
+\index[general]{Catalog!Internal Bacula }
+\index[general]{Internal Bacula Catalog }
+\addcontentsline{toc}{subsubsection}{Internal Bacula Catalog}
+
+Please see the
+\ilink{Internal Bacula Database}{_ChapterStart42} chapter of this
+manual for more details.
+
+\subsection{Database Table Design}
+\index[general]{Design!Database Table }
+\index[general]{Database Table Design }
+\addcontentsline{toc}{subsubsection}{Database Table Design}
+
+All discussions that follow pertain to the MySQL database. The details for the
+PostgreSQL and SQLite databases are essentially identical except for that all
+fields in the SQLite database are stored as ASCII text and some of the
+database creation statements are a bit different. The details of the internal
+Bacula catalog are not discussed here.
+
+Because the Catalog database may contain very large amounts of data for large
+sites, we have made a modest attempt to normalize the data tables to reduce
+redundant information. While reducing the size of the database significantly,
+it does, unfortunately, add some complications to the structures.
+
+In simple terms, the Catalog database must contain a record of all Jobs run by
+Bacula, and for each Job, it must maintain a list of all files saved, with
+their File Attributes (permissions, create date, ...), and the location and
+Media on which the file is stored. This is seemingly a simple task, but it
+represents a huge amount interlinked data. Note: the list of files and their
+attributes is not maintained when using the internal Bacula database. The data
+stored in the File records, which allows the user or administrator to obtain a
+list of all files backed up during a job, is by far the largest volume of
+information put into the Catalog database.
+
+Although the Catalog database has been designed to handle backup data for
+multiple clients, some users may want to maintain multiple databases, one for
+each machine to be backed up. This reduces the risk of confusion of accidental
+restoring a file to the wrong machine as well as reducing the amount of data
+in a single database, thus increasing efficiency and reducing the impact of a
+lost or damaged database.
+
+\section{Sequence of Creation of Records for a Save Job}
+\index[general]{Sequence of Creation of Records for a Save Job }
+\index[general]{Job!Sequence of Creation of Records for a Save }
+\addcontentsline{toc}{subsection}{Sequence of Creation of Records for a Save
+Job}
+
+Start with StartDate, ClientName, Filename, Path, Attributes, MediaName,
+MediaCoordinates. (PartNumber, NumParts). In the steps below, ``Create new''
+means to create a new record whether or not it is unique. ``Create unique''
+means each record in the database should be unique. Thus, one must first
+search to see if the record exists, and only if not should a new one be
+created, otherwise the existing RecordId should be used.
+
+\begin{enumerate}
+\item Create new Job record with StartDate; save JobId
+\item Create unique Media record; save MediaId
+\item Create unique Client record; save ClientId
+\item Create unique Filename record; save FilenameId
+\item Create unique Path record; save PathId
+\item Create unique Attribute record; save AttributeId
+ store ClientId, FilenameId, PathId, and Attributes
+\item Create new File record
+ store JobId, AttributeId, MediaCoordinates, etc
+\item Repeat steps 4 through 8 for each file
+\item Create a JobMedia record; save MediaId
+\item Update Job record filling in EndDate and other Job statistics
+ \end{enumerate}
+
+\section{Database Tables}
+\index[general]{Database Tables }
+\index[general]{Tables!Database }
+\addcontentsline{toc}{subsection}{Database Tables}
+
+\addcontentsline{lot}{table}{Filename Table Layout}
+\begin{longtable}{|l|l|l|}
+ \hline
+\multicolumn{3}{|l| }{\bf Filename } \\
+ \hline
+\multicolumn{1}{|c| }{\bf Column Name } & \multicolumn{1}{l| }{\bf Data Type }
+& \multicolumn{1}{l| }{\bf Remark } \\
+ \hline
+{FilenameId } & {integer } & {Primary Key } \\
+ \hline
+{Name } & {Blob } & {Filename }
+\\ \hline
+
+\end{longtable}
+
+The {\bf Filename} table shown above contains the name of each file backed up
+with the path removed. If different directories or machines contain the same
+filename, only one copy will be saved in this table.
+
+\
+
+\addcontentsline{lot}{table}{Path Table Layout}
+\begin{longtable}{|l|l|l|}
+ \hline
+\multicolumn{3}{|l| }{\bf Path } \\
+ \hline
+\multicolumn{1}{|c| }{\bf Column Name } & \multicolumn{1}{c| }{\bf Data Type
+} & \multicolumn{1}{c| }{\bf Remark } \\
+ \hline
+{PathId } & {integer } & {Primary Key } \\
+ \hline
+{Path } & {Blob } & {Full Path }
+\\ \hline
+
+\end{longtable}
+
+The {\bf Path} table contains shown above the path or directory names of all
+directories on the system or systems. The filename and any MSDOS disk name are
+stripped off. As with the filename, only one copy of each directory name is
+kept regardless of how many machines or drives have the same directory. These
+path names should be stored in Unix path name format.
+
+Some simple testing on a Linux file system indicates that separating the
+filename and the path may be more complication than is warranted by the space
+savings. For example, this system has a total of 89,097 files, 60,467 of which
+have unique filenames, and there are 4,374 unique paths.
+
+Finding all those files and doing two stats() per file takes an average wall
+clock time of 1 min 35 seconds on a 400MHz machine running RedHat 6.1 Linux.
+
+Finding all those files and putting them directly into a MySQL database with
+the path and filename defined as TEXT, which is variable length up to 65,535
+characters takes 19 mins 31 seconds and creates a 27.6 MByte database.
+
+Doing the same thing, but inserting them into Blob fields with the filename
+indexed on the first 30 characters and the path name indexed on the 255 (max)
+characters takes 5 mins 18 seconds and creates a 5.24 MB database. Rerunning
+the job (with the database already created) takes about 2 mins 50 seconds.
+
+Running the same as the last one (Path and Filename Blob), but Filename
+indexed on the first 30 characters and the Path on the first 50 characters
+(linear search done there after) takes 5 mins on the average and creates a 3.4
+MB database. Rerunning with the data already in the DB takes 3 mins 35
+seconds.
+
+Finally, saving only the full path name rather than splitting the path and the
+file, and indexing it on the first 50 characters takes 6 mins 43 seconds and
+creates a 7.35 MB database.
+
+\
+
+\addcontentsline{lot}{table}{File Table Layout}
+\begin{longtable}{|l|l|l|}
+ \hline
+\multicolumn{3}{|l| }{\bf File } \\
+ \hline
+\multicolumn{1}{|c| }{\bf Column Name } & \multicolumn{1}{c| }{\bf Data Type
+} & \multicolumn{1}{c| }{\bf Remark } \\
+ \hline
+{FileId } & {integer } & {Primary Key } \\
+ \hline
+{FileIndex } & {integer } & {The sequential file number in the Job } \\
+ \hline
+{JobId } & {integer } & {Link to Job Record } \\
+ \hline
+{PathId } & {integer } & {Link to Path Record } \\
+ \hline
+{FilenameId } & {integer } & {Link to Filename Record } \\
+ \hline
+{MarkId } & {integer } & {Used to mark files during Verify Jobs } \\
+ \hline
+{LStat } & {tinyblob } & {File attributes in base64 encoding } \\
+ \hline
+{MD5 } & {tinyblob } & {MD5 signature in base64 encoding }
+\\ \hline
+
+\end{longtable}
+
+The {\bf File} table shown above contains one entry for each file backed up by
+Bacula. Thus a file that is backed up multiple times (as is normal) will have
+multiple entries in the File table. This will probably be the table with the
+most number of records. Consequently, it is essential to keep the size of this
+record to an absolute minimum. At the same time, this table must contain all
+the information (or pointers to the information) about the file and where it
+is backed up. Since a file may be backed up many times without having changed,
+the path and filename are stored in separate tables.
+
+This table contains by far the largest amount of information in the Catalog
+database, both from the stand point of number of records, and the stand point
+of total database size. As a consequence, the user must take care to
+periodically reduce the number of File records using the {\bf retention}
+command in the Console program.
+
+\
+
+\addcontentsline{lot}{table}{Job Table Layout}
+\begin{longtable}{|l|l|p{2.5in}|}
+ \hline
+\multicolumn{3}{|l| }{\bf Job } \\
+ \hline
+\multicolumn{1}{|c| }{\bf Column Name } & \multicolumn{1}{c| }{\bf Data Type
+} & \multicolumn{1}{c| }{\bf Remark } \\
+ \hline
+{JobId } & {integer } & {Primary Key } \\
+ \hline
+{Job } & {tinyblob } & {Unique Job Name } \\
+ \hline
+{Name } & {tinyblob } & {Job Name } \\
+ \hline
+{PurgedFiles } & {tinyint } & {Used by Bacula for purging/retention periods
+} \\
+ \hline
+{Type } & {binary(1) } & {Job Type: Backup, Copy, Clone, Archive, Migration
+} \\
+ \hline
+{Level } & {binary(1) } & {Job Level } \\
+ \hline
+{ClientId } & {integer } & {Client index } \\
+ \hline
+{JobStatus } & {binary(1) } & {Job Termination Status } \\
+ \hline
+{SchedTime } & {datetime } & {Time/date when Job scheduled } \\
+ \hline
+{StartTime } & {datetime } & {Time/date when Job started } \\
+ \hline
+{EndTime } & {datetime } & {Time/date when Job ended } \\
+ \hline
+{JobTDate } & {bigint } & {Start day in Unix format but 64 bits; used for
+Retention period. } \\
+ \hline
+{VolSessionId } & {integer } & {Unique Volume Session ID } \\
+ \hline
+{VolSessionTime } & {integer } & {Unique Volume Session Time } \\
+ \hline
+{JobFiles } & {integer } & {Number of files saved in Job } \\
+ \hline
+{JobBytes } & {bigint } & {Number of bytes saved in Job } \\
+ \hline
+{JobErrors } & {integer } & {Number of errors during Job } \\
+ \hline
+{JobMissingFiles } & {integer } & {Number of files not saved (not yet used) }
+\\
+ \hline
+{PoolId } & {integer } & {Link to Pool Record } \\
+ \hline
+{FileSetId } & {integer } & {Link to FileSet Record } \\
+ \hline
+{PurgedFiles } & {tiny integer } & {Set when all File records purged } \\
+ \hline
+{HasBase } & {tiny integer } & {Set when Base Job run }
+\\ \hline
+
+\end{longtable}
+
+The {\bf Job} table contains one record for each Job run by Bacula. Thus
+normally, there will be one per day per machine added to the database. Note,
+the JobId is used to index Job records in the database, and it often is shown
+to the user in the Console program. However, care must be taken with its use
+as it is not unique from database to database. For example, the user may have
+a database for Client data saved on machine Rufus and another database for
+Client data saved on machine Roxie. In this case, the two database will each
+have JobIds that match those in another database. For a unique reference to a
+Job, see Job below.
+
+The Name field of the Job record corresponds to the Name resource record given
+in the Director's configuration file. Thus it is a generic name, and it will
+be normal to find many Jobs (or even all Jobs) with the same Name.
+
+The Job field contains a combination of the Name and the schedule time of the
+Job by the Director. Thus for a given Director, even with multiple Catalog
+databases, the Job will contain a unique name that represents the Job.
+
+For a given Storage daemon, the VolSessionId and VolSessionTime form a unique
+identification of the Job. This will be the case even if multiple Directors
+are using the same Storage daemon.
+
+The Job Type (or simply Type) can have one of the following values:
+
+\addcontentsline{lot}{table}{Job Types}
+\begin{longtable}{|l|l|}
+ \hline
+\multicolumn{1}{|c| }{\bf Value } & \multicolumn{1}{c| }{\bf Meaning } \\
+ \hline
+{B } & {Backup Job } \\
+ \hline
+{V } & {Verify Job } \\
+ \hline
+{R } & {Restore Job } \\
+ \hline
+{C } & {Console program (not in database) } \\
+ \hline
+{D } & {Admin Job } \\
+ \hline
+{A } & {Archive Job (not implemented) }
+\\ \hline
+
+\end{longtable}
+
+The JobStatus field specifies how the job terminated, and can be one of the
+following:
+
+\addcontentsline{lot}{table}{Job Statuses}
+\begin{longtable}{|l|l|}
+ \hline
+\multicolumn{1}{|c| }{\bf Value } & \multicolumn{1}{c| }{\bf Meaning } \\
+ \hline
+{C } & {Created but not yet running } \\
+ \hline
+{R } & {Running } \\
+ \hline
+{B } & {Blocked } \\
+ \hline
+{T } & {Terminated normally } \\
+ \hline
+{E } & {Terminated in Error } \\
+ \hline
+{e } & {Non-fatal error } \\
+ \hline
+{f } & {Fatal error } \\
+ \hline
+{D } & {Verify Differences } \\
+ \hline
+{A } & {Canceled by the user } \\
+ \hline
+{F } & {Waiting on the File daemon } \\
+ \hline
+{S } & {Waiting on the Storage daemon } \\
+ \hline
+{m } & {Waiting for a new Volume to be mounted } \\
+ \hline
+{M } & {Waiting for a Mount } \\
+ \hline
+{s } & {Waiting for Storage resource } \\
+ \hline
+{j } & {Waiting for Job resource } \\
+ \hline
+{c } & {Waiting for Client resource } \\
+ \hline
+{d } & {Wating for Maximum jobs } \\
+ \hline
+{t } & {Waiting for Start Time } \\
+ \hline
+{p } & {Waiting for higher priority job to finish }
+\\ \hline
+
+\end{longtable}
+
+\
+
+\addcontentsline{lot}{table}{File Sets Table Layout}
+\begin{longtable}{|l|l|l|}
+ \hline
+\multicolumn{3}{|l| }{\bf FileSet } \\
+ \hline
+\multicolumn{1}{|c| }{\bf Column Name } & \multicolumn{1}{c| }{\bf Data Type\
+\ \ } & \multicolumn{1}{c| }{\bf Remark } \\
+ \hline
+{FileSetId } & {integer } & {Primary Key } \\
+ \hline
+{FileSet } & {tinyblob } & {FileSet name } \\
+ \hline
+{MD5 } & {tinyblob } & {MD5 checksum of FileSet } \\
+ \hline
+{CreateTime } & {datetime } & {Time and date Fileset created }
+\\ \hline
+
+\end{longtable}
+
+The {\bf FileSet} table contains one entry for each FileSet that is used. The
+MD5 signature is kept to ensure that if the user changes anything inside the
+FileSet, it will be detected and the new FileSet will be used. This is
+particularly important when doing an incremental update. If the user deletes a
+file or adds a file, we need to ensure that a Full backup is done prior to the
+next incremental.
+
+\
+
+\addcontentsline{lot}{table}{JobMedia Table Layout}
+\begin{longtable}{|l|l|p{2.5in}|}
+ \hline
+\multicolumn{3}{|l| }{\bf JobMedia } \\
+ \hline
+\multicolumn{1}{|c| }{\bf Column Name } & \multicolumn{1}{c| }{\bf Data Type\
+\ \ } & \multicolumn{1}{c| }{\bf Remark } \\
+ \hline
+{JobMediaId } & {integer } & {Primary Key } \\
+ \hline
+{JobId } & {integer } & {Link to Job Record } \\
+ \hline
+{MediaId } & {integer } & {Link to Media Record } \\
+ \hline
+{FirstIndex } & {integer } & {The index (sequence number) of the first file
+written for this Job to the Media } \\
+ \hline
+{LastIndex } & {integer } & {The index of the last file written for this
+Job to the Media } \\
+ \hline
+{StartFile } & {integer } & {The physical media (tape) file number of the
+first block written for this Job } \\
+ \hline
+{EndFile } & {integer } & {The physical media (tape) file number of the
+last block written for this Job } \\
+ \hline
+{StartBlock } & {integer } & {The number of the first block written for
+this Job } \\
+ \hline
+{EndBlock } & {integer } & {The number of the last block written for this
+Job } \\
+ \hline
+{VolIndex } & {integer } & {The Volume use sequence number within the Job }
+\\ \hline
+
+\end{longtable}
+
+The {\bf JobMedia} table contains one entry at the following: start of
+the job, start of each new tape file, start of each new tape, end of the
+job. Since by default, a new tape file is written every 2GB, in general,
+you will have more than 2 JobMedia records per Job. The number can be
+varied by changing the "Maximum File Size" specified in the Device
+resource. This record allows Bacula to efficiently position close to
+(within 2GB) any given file in a backup. For restoring a full Job,
+these records are not very important, but if you want to retrieve
+a single file that was written near the end of a 100GB backup, the
+JobMedia records can speed it up by orders of magnitude by permitting
+forward spacing files and blocks rather than reading the whole 100GB
+backup.
+
+
+
+\
+
+\addcontentsline{lot}{table}{Media Table Layout}
+\begin{longtable}{|l|l|p{2.4in}|}
+ \hline
+\multicolumn{3}{|l| }{\bf Media } \\
+ \hline
+\multicolumn{1}{|c| }{\bf Column Name } & \multicolumn{1}{c| }{\bf Data Type\
+\ \ } & \multicolumn{1}{c| }{\bf Remark } \\
+ \hline
+{MediaId } & {integer } & {Primary Key } \\
+ \hline
+{VolumeName } & {tinyblob } & {Volume name } \\
+ \hline
+{Slot } & {integer } & {Autochanger Slot number or zero } \\
+ \hline
+{PoolId } & {integer } & {Link to Pool Record } \\
+ \hline
+{MediaType } & {tinyblob } & {The MediaType supplied by the user } \\
+ \hline
+{FirstWritten } & {datetime } & {Time/date when first written } \\
+ \hline
+{LastWritten } & {datetime } & {Time/date when last written } \\
+ \hline
+{LabelDate } & {datetime } & {Time/date when tape labeled } \\
+ \hline
+{VolJobs } & {integer } & {Number of jobs written to this media } \\
+ \hline
+{VolFiles } & {integer } & {Number of files written to this media } \\
+ \hline
+{VolBlocks } & {integer } & {Number of blocks written to this media } \\
+ \hline
+{VolMounts } & {integer } & {Number of time media mounted } \\
+ \hline
+{VolBytes } & {bigint } & {Number of bytes saved in Job } \\
+ \hline
+{VolErrors } & {integer } & {Number of errors during Job } \\
+ \hline
+{VolWrites } & {integer } & {Number of writes to media } \\
+ \hline
+{MaxVolBytes } & {bigint } & {Maximum bytes to put on this media } \\
+ \hline
+{VolCapacityBytes } & {bigint } & {Capacity estimate for this volume } \\
+ \hline
+{VolStatus } & {enum } & {Status of media: Full, Archive, Append, Recycle,
+Read-Only, Disabled, Error, Busy } \\
+ \hline
+{Recycle } & {tinyint } & {Whether or not Bacula can recycle the Volumes:
+Yes, No } \\
+ \hline
+{VolRetention } & {bigint } & {64 bit seconds until expiration } \\
+ \hline
+{VolUseDuration } & {bigint } & {64 bit seconds volume can be used } \\
+ \hline
+{MaxVolJobs } & {integer } & {maximum jobs to put on Volume } \\
+ \hline
+{MaxVolFiles } & {integer } & {maximume EOF marks to put on Volume }
+\\ \hline
+
+\end{longtable}
+
+The {\bf Volume} table (internally referred to as the Media table) contains
+one entry for each volume, that is each tape, cassette (8mm, DLT, DAT, ...),
+or file on which information is or was backed up. There is one Volume record
+created for each of the NumVols specified in the Pool resource record.
+
+\
+
+\addcontentsline{lot}{table}{Pool Table Layout}
+\begin{longtable}{|l|l|p{2.4in}|}
+ \hline
+\multicolumn{3}{|l| }{\bf Pool } \\
+ \hline
+\multicolumn{1}{|c| }{\bf Column Name } & \multicolumn{1}{c| }{\bf Data Type
+} & \multicolumn{1}{c| }{\bf Remark } \\
+ \hline
+{PoolId } & {integer } & {Primary Key } \\
+ \hline
+{Name } & {Tinyblob } & {Pool Name } \\
+ \hline
+{NumVols } & {Integer } & {Number of Volumes in the Pool } \\
+ \hline
+{MaxVols } & {Integer } & {Maximum Volumes in the Pool } \\
+ \hline
+{UseOnce } & {tinyint } & {Use volume once } \\
+ \hline
+{UseCatalog } & {tinyint } & {Set to use catalog } \\
+ \hline
+{AcceptAnyVolume } & {tinyint } & {Accept any volume from Pool } \\
+ \hline
+{VolRetention } & {bigint } & {64 bit seconds to retain volume } \\
+ \hline
+{VolUseDuration } & {bigint } & {64 bit seconds volume can be used } \\
+ \hline
+{MaxVolJobs } & {integer } & {max jobs on volume } \\
+ \hline
+{MaxVolFiles } & {integer } & {max EOF marks to put on Volume } \\
+ \hline
+{MaxVolBytes } & {bigint } & {max bytes to write on Volume } \\
+ \hline
+{AutoPrune } & {tinyint } & {yes|no for autopruning } \\
+ \hline
+{Recycle } & {tinyint } & {yes|no for allowing auto recycling of Volume }
+\\
+ \hline
+{PoolType } & {enum } & {Backup, Copy, Cloned, Archive, Migration } \\
+ \hline
+{LabelFormat } & {Tinyblob } & {Label format }
+\\ \hline
+
+\end{longtable}
+
+The {\bf Pool} table contains one entry for each media pool controlled by
+Bacula in this database. One media record exists for each of the NumVols
+contained in the Pool. The PoolType is a Bacula defined keyword. The MediaType
+is defined by the administrator, and corresponds to the MediaType specified in
+the Director's Storage definition record. The CurrentVol is the sequence
+number of the Media record for the current volume.
+
+\
+
+\addcontentsline{lot}{table}{Client Table Layout}
+\begin{longtable}{|l|l|l|}
+ \hline
+\multicolumn{3}{|l| }{\bf Client } \\
+ \hline
+\multicolumn{1}{|c| }{\bf Column Name } & \multicolumn{1}{c| }{\bf Data Type
+} & \multicolumn{1}{c| }{\bf Remark } \\
+ \hline
+{ClientId } & {integer } & {Primary Key } \\
+ \hline
+{Name } & {TinyBlob } & {File Services Name } \\
+ \hline
+{UName } & {TinyBlob } & {uname -a from Client (not yet used) } \\
+ \hline
+{AutoPrune } & {tinyint } & {yes|no for autopruning } \\
+ \hline
+{FileRetention } & {bigint } & {64 bit seconds to retain Files } \\
+ \hline
+{JobRetention } & {bigint } & {64 bit seconds to retain Job }
+\\ \hline
+
+\end{longtable}
+
+The {\bf Client} table contains one entry for each machine backed up by Bacula
+in this database. Normally the Name is a fully qualified domain name.
+
+\
+
+\addcontentsline{lot}{table}{Unsaved Files Table Layout}
+\begin{longtable}{|l|l|l|}
+ \hline
+\multicolumn{3}{|l| }{\bf UnsavedFiles } \\
+ \hline
+\multicolumn{1}{|c| }{\bf Column Name } & \multicolumn{1}{c| }{\bf Data Type
+} & \multicolumn{1}{c| }{\bf Remark } \\
+ \hline
+{UnsavedId } & {integer } & {Primary Key } \\
+ \hline
+{JobId } & {integer } & {JobId corresponding to this record } \\
+ \hline
+{PathId } & {integer } & {Id of path } \\
+ \hline
+{FilenameId } & {integer } & {Id of filename }
+\\ \hline
+
+\end{longtable}
+
+The {\bf UnsavedFiles} table contains one entry for each file that was not
+saved. Note! This record is not yet implemented.
+
+\
+
+\addcontentsline{lot}{table}{Counter Table Layout}
+\begin{longtable}{|l|l|l|}
+ \hline
+\multicolumn{3}{|l| }{\bf Counter } \\
+ \hline
+\multicolumn{1}{|c| }{\bf Column Name } & \multicolumn{1}{c| }{\bf Data Type
+} & \multicolumn{1}{c| }{\bf Remark } \\
+ \hline
+{Counter } & {tinyblob } & {Counter name } \\
+ \hline
+{MinValue } & {integer } & {Start/Min value for counter } \\
+ \hline
+{MaxValue } & {integer } & {Max value for counter } \\
+ \hline
+{CurrentValue } & {integer } & {Current counter value } \\
+ \hline
+{WrapCounter } & {tinyblob } & {Name of another counter }
+\\ \hline
+
+\end{longtable}
+
+The {\bf Counter} table contains one entry for each permanent counter defined
+by the user.
+
+\
+
+\addcontentsline{lot}{table}{Version Table Layout}
+\begin{longtable}{|l|l|l|}
+ \hline
+\multicolumn{3}{|l| }{\bf Version } \\
+ \hline
+\multicolumn{1}{|c| }{\bf Column Name } & \multicolumn{1}{c| }{\bf Data Type
+} & \multicolumn{1}{c| }{\bf Remark } \\
+ \hline
+{VersionId } & {integer } & {Primary Key }
+\\ \hline
+
+\end{longtable}
+
+The {\bf Version} table defines the Bacula database version number. Bacula
+checks this number before reading the database to ensure that it is compatible
+with the Bacula binary file.
+
+\
+
+\addcontentsline{lot}{table}{Base Files Table Layout}
+\begin{longtable}{|l|l|l|}
+ \hline
+\multicolumn{3}{|l| }{\bf BaseFiles } \\
+ \hline
+\multicolumn{1}{|c| }{\bf Column Name } & \multicolumn{1}{c| }{\bf Data Type
+} & \multicolumn{1}{c| }{\bf Remark } \\
+ \hline
+{BaseId } & {integer } & {Primary Key } \\
+ \hline
+{BaseJobId } & {integer } & {JobId of Base Job } \\
+ \hline
+{JobId } & {integer } & {Reference to Job } \\
+ \hline
+{FileId } & {integer } & {Reference to File } \\
+ \hline
+{FileIndex } & {integer } & {File Index number }
+\\ \hline
+
+\end{longtable}
+
+The {\bf BaseFiles} table contains all the File references for a particular
+JobId that point to a Base file -- i.e. they were previously saved and hence
+were not saved in the current JobId but in BaseJobId under FileId. FileIndex
+is the index of the file, and is used for optimization of Restore jobs to
+prevent the need to read the FileId record when creating the in memory tree.
+This record is not yet implemented.
+
+\
+
+\subsection{MySQL Table Definition}
+\index[general]{MySQL Table Definition }
+\index[general]{Definition!MySQL Table }
+\addcontentsline{toc}{subsubsection}{MySQL Table Definition}
+
+The commands used to create the MySQL tables are as follows:
+
+\footnotesize
+\begin{verbatim}
+USE bacula;
+CREATE TABLE Filename (
+ FilenameId INTEGER UNSIGNED NOT NULL AUTO_INCREMENT,
+ Name BLOB NOT NULL,
+ PRIMARY KEY(FilenameId),
+ INDEX (Name(30))
+ );
+CREATE TABLE Path (
+ PathId INTEGER UNSIGNED NOT NULL AUTO_INCREMENT,
+ Path BLOB NOT NULL,
+ PRIMARY KEY(PathId),
+ INDEX (Path(50))
+ );
+CREATE TABLE File (
+ FileId INTEGER UNSIGNED NOT NULL AUTO_INCREMENT,
+ FileIndex INTEGER UNSIGNED NOT NULL DEFAULT 0,
+ JobId INTEGER UNSIGNED NOT NULL REFERENCES Job,
+ PathId INTEGER UNSIGNED NOT NULL REFERENCES Path,
+ FilenameId INTEGER UNSIGNED NOT NULL REFERENCES Filename,
+ MarkId INTEGER UNSIGNED NOT NULL DEFAULT 0,
+ LStat TINYBLOB NOT NULL,
+ MD5 TINYBLOB NOT NULL,
+ PRIMARY KEY(FileId),
+ INDEX (JobId),
+ INDEX (PathId),
+ INDEX (FilenameId)
+ );
+CREATE TABLE Job (
+ JobId INTEGER UNSIGNED NOT NULL AUTO_INCREMENT,
+ Job TINYBLOB NOT NULL,
+ Name TINYBLOB NOT NULL,
+ Type BINARY(1) NOT NULL,
+ Level BINARY(1) NOT NULL,
+ ClientId INTEGER NOT NULL REFERENCES Client,
+ JobStatus BINARY(1) NOT NULL,
+ SchedTime DATETIME NOT NULL,
+ StartTime DATETIME NOT NULL,
+ EndTime DATETIME NOT NULL,
+ JobTDate BIGINT UNSIGNED NOT NULL,
+ VolSessionId INTEGER UNSIGNED NOT NULL DEFAULT 0,
+ VolSessionTime INTEGER UNSIGNED NOT NULL DEFAULT 0,
+ JobFiles INTEGER UNSIGNED NOT NULL DEFAULT 0,
+ JobBytes BIGINT UNSIGNED NOT NULL,
+ JobErrors INTEGER UNSIGNED NOT NULL DEFAULT 0,
+ JobMissingFiles INTEGER UNSIGNED NOT NULL DEFAULT 0,
+ PoolId INTEGER UNSIGNED NOT NULL REFERENCES Pool,
+ FileSetId INTEGER UNSIGNED NOT NULL REFERENCES FileSet,
+ PurgedFiles TINYINT NOT NULL DEFAULT 0,
+ HasBase TINYINT NOT NULL DEFAULT 0,
+ PRIMARY KEY(JobId),
+ INDEX (Name(128))
+ );
+CREATE TABLE FileSet (
+ FileSetId INTEGER UNSIGNED NOT NULL AUTO_INCREMENT,
+ FileSet TINYBLOB NOT NULL,
+ MD5 TINYBLOB NOT NULL,
+ CreateTime DATETIME NOT NULL,
+ PRIMARY KEY(FileSetId)
+ );
+CREATE TABLE JobMedia (
+ JobMediaId INTEGER UNSIGNED NOT NULL AUTO_INCREMENT,
+ JobId INTEGER UNSIGNED NOT NULL REFERENCES Job,
+ MediaId INTEGER UNSIGNED NOT NULL REFERENCES Media,
+ FirstIndex INTEGER UNSIGNED NOT NULL DEFAULT 0,
+ LastIndex INTEGER UNSIGNED NOT NULL DEFAULT 0,
+ StartFile INTEGER UNSIGNED NOT NULL DEFAULT 0,
+ EndFile INTEGER UNSIGNED NOT NULL DEFAULT 0,
+ StartBlock INTEGER UNSIGNED NOT NULL DEFAULT 0,
+ EndBlock INTEGER UNSIGNED NOT NULL DEFAULT 0,
+ VolIndex INTEGER UNSIGNED NOT NULL DEFAULT 0,
+ PRIMARY KEY(JobMediaId),
+ INDEX (JobId, MediaId)
+ );
+CREATE TABLE Media (
+ MediaId INTEGER UNSIGNED NOT NULL AUTO_INCREMENT,
+ VolumeName TINYBLOB NOT NULL,
+ Slot INTEGER NOT NULL DEFAULT 0,
+ PoolId INTEGER UNSIGNED NOT NULL REFERENCES Pool,
+ MediaType TINYBLOB NOT NULL,
+ FirstWritten DATETIME NOT NULL,
+ LastWritten DATETIME NOT NULL,
+ LabelDate DATETIME NOT NULL,
+ VolJobs INTEGER UNSIGNED NOT NULL DEFAULT 0,
+ VolFiles INTEGER UNSIGNED NOT NULL DEFAULT 0,
+ VolBlocks INTEGER UNSIGNED NOT NULL DEFAULT 0,
+ VolMounts INTEGER UNSIGNED NOT NULL DEFAULT 0,
+ VolBytes BIGINT UNSIGNED NOT NULL DEFAULT 0,
+ VolErrors INTEGER UNSIGNED NOT NULL DEFAULT 0,
+ VolWrites INTEGER UNSIGNED NOT NULL DEFAULT 0,
+ VolCapacityBytes BIGINT UNSIGNED NOT NULL,
+ VolStatus ENUM('Full', 'Archive', 'Append', 'Recycle', 'Purged',
+ 'Read-Only', 'Disabled', 'Error', 'Busy', 'Used', 'Cleaning') NOT NULL,
+ Recycle TINYINT NOT NULL DEFAULT 0,
+ VolRetention BIGINT UNSIGNED NOT NULL DEFAULT 0,
+ VolUseDuration BIGINT UNSIGNED NOT NULL DEFAULT 0,
+ MaxVolJobs INTEGER UNSIGNED NOT NULL DEFAULT 0,
+ MaxVolFiles INTEGER UNSIGNED NOT NULL DEFAULT 0,
+ MaxVolBytes BIGINT UNSIGNED NOT NULL DEFAULT 0,
+ InChanger TINYINT NOT NULL DEFAULT 0,
+ MediaAddressing TINYINT NOT NULL DEFAULT 0,
+ VolReadTime BIGINT UNSIGNED NOT NULL DEFAULT 0,
+ VolWriteTime BIGINT UNSIGNED NOT NULL DEFAULT 0,
+ PRIMARY KEY(MediaId),
+ INDEX (PoolId)
+ );
+CREATE TABLE Pool (
+ PoolId INTEGER UNSIGNED NOT NULL AUTO_INCREMENT,
+ Name TINYBLOB NOT NULL,
+ NumVols INTEGER UNSIGNED NOT NULL DEFAULT 0,
+ MaxVols INTEGER UNSIGNED NOT NULL DEFAULT 0,
+ UseOnce TINYINT NOT NULL,
+ UseCatalog TINYINT NOT NULL,
+ AcceptAnyVolume TINYINT DEFAULT 0,
+ VolRetention BIGINT UNSIGNED NOT NULL,
+ VolUseDuration BIGINT UNSIGNED NOT NULL,
+ MaxVolJobs INTEGER UNSIGNED NOT NULL DEFAULT 0,
+ MaxVolFiles INTEGER UNSIGNED NOT NULL DEFAULT 0,
+ MaxVolBytes BIGINT UNSIGNED NOT NULL,
+ AutoPrune TINYINT DEFAULT 0,
+ Recycle TINYINT DEFAULT 0,
+ PoolType ENUM('Backup', 'Copy', 'Cloned', 'Archive', 'Migration', 'Scratch') NOT NULL,
+ LabelFormat TINYBLOB,
+ Enabled TINYINT DEFAULT 1,
+ ScratchPoolId INTEGER UNSIGNED DEFAULT 0 REFERENCES Pool,
+ RecyclePoolId INTEGER UNSIGNED DEFAULT 0 REFERENCES Pool,
+ UNIQUE (Name(128)),
+ PRIMARY KEY (PoolId)
+ );
+CREATE TABLE Client (
+ ClientId INTEGER UNSIGNED NOT NULL AUTO_INCREMENT,
+ Name TINYBLOB NOT NULL,
+ Uname TINYBLOB NOT NULL, /* full uname -a of client */
+ AutoPrune TINYINT DEFAULT 0,
+ FileRetention BIGINT UNSIGNED NOT NULL,
+ JobRetention BIGINT UNSIGNED NOT NULL,
+ UNIQUE (Name(128)),
+ PRIMARY KEY(ClientId)
+ );
+CREATE TABLE BaseFiles (
+ BaseId INTEGER UNSIGNED AUTO_INCREMENT,
+ BaseJobId INTEGER UNSIGNED NOT NULL REFERENCES Job,
+ JobId INTEGER UNSIGNED NOT NULL REFERENCES Job,
+ FileId INTEGER UNSIGNED NOT NULL REFERENCES File,
+ FileIndex INTEGER UNSIGNED,
+ PRIMARY KEY(BaseId)
+ );
+CREATE TABLE UnsavedFiles (
+ UnsavedId INTEGER UNSIGNED AUTO_INCREMENT,
+ JobId INTEGER UNSIGNED NOT NULL REFERENCES Job,
+ PathId INTEGER UNSIGNED NOT NULL REFERENCES Path,
+ FilenameId INTEGER UNSIGNED NOT NULL REFERENCES Filename,
+ PRIMARY KEY (UnsavedId)
+ );
+CREATE TABLE Version (
+ VersionId INTEGER UNSIGNED NOT NULL
+ );
+-- Initialize Version
+INSERT INTO Version (VersionId) VALUES (7);
+CREATE TABLE Counters (
+ Counter TINYBLOB NOT NULL,
+ MinValue INTEGER,
+ MaxValue INTEGER,
+ CurrentValue INTEGER,
+ WrapCounter TINYBLOB NOT NULL,
+ PRIMARY KEY (Counter(128))
+ );
+\end{verbatim}
+\normalsize
--- /dev/null
+#!/usr/bin/perl -w
+# Finds potential problems in tex files, and issues warnings to the console
+# about what it finds. Takes a list of files as its only arguments,
+# and does checks on all the files listed. The assumption is that these are
+# valid (or close to valid) LaTeX files. It follows \include statements
+# recursively to pick up any included tex files.
+#
+#
+#
+# Currently the following checks are made:
+#
+# -- Multiple hyphens not inside a verbatim environment (or \verb). These
+# should be placed inside a \verb{} contruct so they will not be converted
+# to single hyphen by latex and latex2html.
+
+
+# Original creation 3-8-05 by Karl Cunningham karlc -at- keckec -dot- com
+#
+#
+
+use strict;
+
+# The following builds the test string to identify and change multiple
+# hyphens in the tex files. Several constructs are identified but only
+# multiple hyphens are changed; the others are fed to the output
+# unchanged.
+my $b = '\\\\begin\\*?\\s*\\{\\s*'; # \begin{
+my $e = '\\\\end\\*?\\s*\\{\\s*'; # \end{
+my $c = '\\s*\\}'; # closing curly brace
+
+# This captures entire verbatim environments. These are passed to the output
+# file unchanged.
+my $verbatimenv = $b . "verbatim" . $c . ".*?" . $e . "verbatim" . $c;
+
+# This captures \verb{..{ constructs. They are passed to the output unchanged.
+my $verb = '\\\\verb\\*?(.).*?\\1';
+
+# This captures multiple hyphens with a leading and trailing space. These are not changed.
+my $hyphsp = '\\s\\-{2,}\\s';
+
+# This identifies other multiple hyphens.
+my $hyphens = '\\-{2,}';
+
+# This identifies \hyperpage{..} commands, which should be ignored.
+my $hyperpage = '\\\\hyperpage\\*?\\{.*?\\}';
+
+# This builds the actual test string from the above strings.
+#my $teststr = "$verbatimenv|$verb|$tocentry|$hyphens";
+my $teststr = "$verbatimenv|$verb|$hyphsp|$hyperpage|$hyphens";
+
+
+sub get_includes {
+ # Get a list of include files from the top-level tex file. The first
+ # argument is a pointer to the list of files found. The rest of the
+ # arguments is a list of filenames to check for includes.
+ my $files = shift;
+ my ($fileline,$includefile,$includes);
+
+ while (my $filename = shift) {
+ # Get a list of all the html files in the directory.
+ open my $if,"<$filename" or die "Cannot open input file $filename\n";
+ $fileline = 0;
+ $includes = 0;
+ while (<$if>) {
+ chomp;
+ $fileline++;
+ # If a file is found in an include, process it.
+ if (($includefile) = /\\include\s*\{(.*?)\}/) {
+ $includes++;
+ # Append .tex to the filename
+ $includefile .= '.tex';
+
+ # If the include file has already been processed, issue a warning
+ # and don't do it again.
+ my $found = 0;
+ foreach (@$files) {
+ if ($_ eq $includefile) {
+ $found = 1;
+ last;
+ }
+ }
+ if ($found) {
+ print "$includefile found at line $fileline in $filename was previously included\n";
+ } else {
+ # The file has not been previously found. Save it and
+ # recursively process it.
+ push (@$files,$includefile);
+ get_includes($files,$includefile);
+ }
+ }
+ }
+ close IF;
+ }
+}
+
+
+sub check_hyphens {
+ my (@files) = @_;
+ my ($filedata,$this,$linecnt,$before);
+
+ # Build the test string to check for the various environments.
+ # We only do the conversion if the multiple hyphens are outside of a
+ # verbatim environment (either \begin{verbatim}...\end{verbatim} or
+ # \verb{--}). Capture those environments and pass them to the output
+ # unchanged.
+
+ foreach my $file (@files) {
+ # Open the file and load the whole thing into $filedata. A bit wasteful but
+ # easier to deal with, and we don't have a problem with speed here.
+ $filedata = "";
+ open IF,"<$file" or die "Cannot open input file $file";
+ while (<IF>) {
+ $filedata .= $_;
+ }
+ close IF;
+
+ # Set up to process the file data.
+ $linecnt = 1;
+
+ # Go through the file data from beginning to end. For each match, save what
+ # came before it and what matched. $filedata now becomes only what came
+ # after the match.
+ # Chech the match to see if it starts with a multiple-hyphen. If so
+ # warn the user. Keep track of line numbers so they can be output
+ # with the warning message.
+ while ($filedata =~ /$teststr/os) {
+ $this = $&;
+ $before = $`;
+ $filedata = $';
+ $linecnt += $before =~ tr/\n/\n/;
+
+ # Check if the multiple hyphen is present outside of one of the
+ # acceptable constructs.
+ if ($this =~ /^\-+/) {
+ print "Possible unwanted multiple hyphen found in line ",
+ "$linecnt of file $file\n";
+ }
+ $linecnt += $this =~ tr/\n/\n/;
+ }
+ }
+}
+##################################################################
+# MAIN ####
+##################################################################
+
+my (@includes,$cnt);
+
+# Examine the file pointed to by the first argument to get a list of
+# includes to test.
+get_includes(\@includes,@ARGV);
+
+check_hyphens(@includes);
--- /dev/null
+%%
+%%
+
+\chapter{Daemon Protocol}
+\label{_ChapterStart2}
+\index{Protocol!Daemon }
+\index{Daemon Protocol }
+
+\section{General}
+\index{General }
+\addcontentsline{toc}{subsection}{General}
+
+This document describes the protocols used between the various daemons. As
+Bacula has developed, it has become quite out of date. The general idea still
+holds true, but the details of the fields for each command, and indeed the
+commands themselves have changed considerably.
+
+It is intended to be a technical discussion of the general daemon protocols
+and as such is not targeted at end users but rather at developers and system
+administrators that want or need to know more of the working details of {\bf
+Bacula}.
+
+\section{Low Level Network Protocol}
+\index{Protocol!Low Level Network }
+\index{Low Level Network Protocol }
+\addcontentsline{toc}{subsection}{Low Level Network Protocol}
+
+At the lowest level, the network protocol is handled by {\bf BSOCK} packets
+which contain a lot of information about the status of the network connection:
+who is at the other end, etc. Each basic {\bf Bacula} network read or write
+actually consists of two low level network read/writes. The first write always
+sends four bytes of data in machine independent byte order. If data is to
+follow, the first four bytes are a positive non-zero integer indicating the
+length of the data that follow in the subsequent write. If the four byte
+integer is zero or negative, it indicates a special request, a sort of network
+signaling capability. In this case, no data packet will follow. The low level
+BSOCK routines expect that only a single thread is accessing the socket at a
+time. It is advised that multiple threads do not read/write the same socket.
+If you must do this, you must provide some sort of locking mechanism. It would
+not be appropriate for efficiency reasons to make every call to the BSOCK
+routines lock and unlock the packet.
+
+\section{General Daemon Protocol}
+\index{General Daemon Protocol }
+\index{Protocol!General Daemon }
+\addcontentsline{toc}{subsection}{General Daemon Protocol}
+
+In general, all the daemons follow the following global rules. There may be
+exceptions depending on the specific case. Normally, one daemon will be
+sending commands to another daemon (specifically, the Director to the Storage
+daemon and the Director to the File daemon).
+
+\begin{itemize}
+\item Commands are always ASCII commands that are upper/lower case dependent
+ as well as space sensitive.
+\item All binary data is converted into ASCII (either with printf statements
+ or using base64 encoding).
+\item All responses to commands sent are always prefixed with a return
+ numeric code where codes in the 1000's are reserved for the Director, the
+ 2000's are reserved for the File daemon, and the 3000's are reserved for the
+Storage daemon.
+\item Any response that is not prefixed with a numeric code is a command (or
+ subcommand if you like) coming from the other end. For example, while the
+ Director is corresponding with the Storage daemon, the Storage daemon can
+request Catalog services from the Director. This convention permits each side
+to send commands to the other daemon while simultaneously responding to
+commands.
+\item Any response that is of zero length, depending on the context, either
+ terminates the data stream being sent or terminates command mode prior to
+ closing the connection.
+\item Any response that is of negative length is a special sign that normally
+ requires a response. For example, during data transfer from the File daemon
+ to the Storage daemon, normally the File daemon sends continuously without
+intervening reads. However, periodically, the File daemon will send a packet
+of length -1 indicating that the current data stream is complete and that the
+Storage daemon should respond to the packet with an OK, ABORT JOB, PAUSE,
+etc. This permits the File daemon to efficiently send data while at the same
+time occasionally ``polling'' the Storage daemon for his status or any
+special requests.
+
+Currently, these negative lengths are specific to the daemon, but shortly,
+the range 0 to -999 will be standard daemon wide signals, while -1000 to
+-1999 will be for Director user, -2000 to -2999 for the File daemon, and
+-3000 to -3999 for the Storage daemon.
+\end{itemize}
+
+\section{The Protocol Used Between the Director and the Storage Daemon}
+\index{Daemon!Protocol Used Between the Director and the Storage }
+\index{Protocol Used Between the Director and the Storage Daemon }
+\addcontentsline{toc}{subsection}{Protocol Used Between the Director and the
+Storage Daemon}
+
+Before sending commands to the File daemon, the Director opens a Message
+channel with the Storage daemon, identifies itself and presents its password.
+If the password check is OK, the Storage daemon accepts the Director. The
+Director then passes the Storage daemon, the JobId to be run as well as the
+File daemon authorization (append, read all, or read for a specific session).
+The Storage daemon will then pass back to the Director a enabling key for this
+JobId that must be presented by the File daemon when opening the job. Until
+this process is complete, the Storage daemon is not available for use by File
+daemons.
+
+\footnotesize
+\begin{verbatim}
+SD: listens
+DR: makes connection
+DR: Hello <Director-name> calling <password>
+SD: 3000 OK Hello
+DR: JobId=nnn Allow=(append, read) Session=(*, SessionId)
+ (Session not implemented yet)
+SD: 3000 OK Job Authorization=<password>
+DR: use device=<device-name> media_type=<media-type>
+ pool_name=<pool-name> pool_type=<pool_type>
+SD: 3000 OK use device
+\end{verbatim}
+\normalsize
+
+For the Director to be authorized, the \lt{}Director-name\gt{} and the
+\lt{}password\gt{} must match the values in one of the Storage daemon's
+Director resources (there may be several Directors that can access a single
+Storage daemon).
+
+\section{The Protocol Used Between the Director and the File Daemon}
+\index{Daemon!Protocol Used Between the Director and the File }
+\index{Protocol Used Between the Director and the File Daemon }
+\addcontentsline{toc}{subsection}{Protocol Used Between the Director and the
+File Daemon}
+
+A typical conversation might look like the following:
+
+\footnotesize
+\begin{verbatim}
+FD: listens
+DR: makes connection
+DR: Hello <Director-name> calling <password>
+FD: 2000 OK Hello
+DR: JobId=nnn Authorization=<password>
+FD: 2000 OK Job
+DR: storage address = <Storage daemon address> port = <port-number>
+ name = <DeviceName> mediatype = <MediaType>
+FD: 2000 OK storage
+DR: include
+DR: <directory1>
+DR: <directory2>
+ ...
+DR: Null packet
+FD: 2000 OK include
+DR: exclude
+DR: <directory1>
+DR: <directory2>
+ ...
+DR: Null packet
+FD: 2000 OK exclude
+DR: full
+FD: 2000 OK full
+DR: save
+FD: 2000 OK save
+FD: Attribute record for each file as sent to the
+ Storage daemon (described above).
+FD: Null packet
+FD: <append close responses from Storage daemon>
+ e.g.
+ 3000 OK Volumes = <number of volumes>
+ 3001 Volume = <volume-id> <start file> <start block>
+ <end file> <end block> <volume session-id>
+ 3002 Volume data = <date/time of last write> <Number bytes written>
+ <number errors>
+ ... additional Volume / Volume data pairs for volumes 2 .. n
+FD: Null packet
+FD: close socket
+\end{verbatim}
+\normalsize
+
+\section{The Save Protocol Between the File Daemon and the Storage Daemon}
+\index{Save Protocol Between the File Daemon and the Storage Daemon }
+\index{Daemon!Save Protocol Between the File Daemon and the Storage }
+\addcontentsline{toc}{subsection}{Save Protocol Between the File Daemon and
+the Storage Daemon}
+
+Once the Director has send a {\bf save} command to the File daemon, the File
+daemon will contact the Storage daemon to begin the save.
+
+In what follows: FD: refers to information set via the network from the File
+daemon to the Storage daemon, and SD: refers to information set from the
+Storage daemon to the File daemon.
+
+\subsection{Command and Control Information}
+\index{Information!Command and Control }
+\index{Command and Control Information }
+\addcontentsline{toc}{subsubsection}{Command and Control Information}
+
+Command and control information is exchanged in human readable ASCII commands.
+
+
+\footnotesize
+\begin{verbatim}
+FD: listens
+SD: makes connection
+FD: append open session = <JobId> [<password>]
+SD: 3000 OK ticket = <number>
+FD: append data <ticket-number>
+SD: 3000 OK data address = <IPaddress> port = <port>
+\end{verbatim}
+\normalsize
+
+\subsection{Data Information}
+\index{Information!Data }
+\index{Data Information }
+\addcontentsline{toc}{subsubsection}{Data Information}
+
+The Data information consists of the file attributes and data to the Storage
+daemon. For the most part, the data information is sent one way: from the File
+daemon to the Storage daemon. This allows the File daemon to transfer
+information as fast as possible without a lot of handshaking and network
+overhead.
+
+However, from time to time, the File daemon needs to do a sort of checkpoint
+of the situation to ensure that everything is going well with the Storage
+daemon. To do so, the File daemon sends a packet with a negative length
+indicating that he wishes the Storage daemon to respond by sending a packet of
+information to the File daemon. The File daemon then waits to receive a packet
+from the Storage daemon before continuing.
+
+All data sent are in binary format except for the header packet, which is in
+ASCII. There are two packet types used data transfer mode: a header packet,
+the contents of which are known to the Storage daemon, and a data packet, the
+contents of which are never examined by the Storage daemon.
+
+The first data packet to the Storage daemon will be an ASCII header packet
+consisting of the following data.
+
+\lt{}File-Index\gt{} \lt{}Stream-Id\gt{} \lt{}Info\gt{} where {\bf
+\lt{}File-Index\gt{}} is a sequential number beginning from one that
+increments with each file (or directory) sent.
+
+where {\bf \lt{}Stream-Id\gt{}} will be 1 for the Attributes record and 2 for
+uncompressed File data. 3 is reserved for the MD5 signature for the file.
+
+where {\bf \lt{}Info\gt{}} transmit information about the Stream to the
+Storage Daemon. It is a character string field where each character has a
+meaning. The only character currently defined is 0 (zero), which is simply a
+place holder (a no op). In the future, there may be codes indicating
+compressed data, encrypted data, etc.
+
+Immediately following the header packet, the Storage daemon will expect any
+number of data packets. The series of data packets is terminated by a zero
+length packet, which indicates to the Storage daemon that the next packet will
+be another header packet. As previously mentioned, a negative length packet is
+a request for the Storage daemon to temporarily enter command mode and send a
+reply to the File daemon. Thus an actual conversation might contain the
+following exchanges:
+
+\footnotesize
+\begin{verbatim}
+FD: <1 1 0> (header packet)
+FD: <data packet containing file-attributes>
+FD: Null packet
+FD: <1 2 0>
+FD: <multiple data packets containing the file data>
+FD: Packet length = -1
+SD: 3000 OK
+FD: <2 1 0>
+FD: <data packet containing file-attributes>
+FD: Null packet
+FD: <2 2 0>
+FD: <multiple data packets containing the file data>
+FD: Null packet
+FD: Null packet
+FD: append end session <ticket-number>
+SD: 3000 OK end
+FD: append close session <ticket-number>
+SD: 3000 OK Volumes = <number of volumes>
+SD: 3001 Volume = <volumeid> <start file> <start block>
+ <end file> <end block> <volume session-id>
+SD: 3002 Volume data = <date/time of last write> <Number bytes written>
+ <number errors>
+SD: ... additional Volume / Volume data pairs for
+ volumes 2 .. n
+FD: close socket
+\end{verbatim}
+\normalsize
+
+The information returned to the File daemon by the Storage daemon in response
+to the {\bf append close session} is transmit in turn to the Director.
--- /dev/null
+/* Century Schoolbook font is very similar to Computer Modern Math: cmmi */
+.MATH { font-family: "Century Schoolbook", serif; }
+.MATH I { font-family: "Century Schoolbook", serif; font-style: italic }
+.BOLDMATH { font-family: "Century Schoolbook", serif; font-weight: bold }
+
+/* implement both fixed-size and relative sizes */
+SMALL.XTINY { font-size : xx-small }
+SMALL.TINY { font-size : x-small }
+SMALL.SCRIPTSIZE { font-size : smaller }
+SMALL.FOOTNOTESIZE { font-size : small }
+SMALL.SMALL { }
+BIG.LARGE { }
+BIG.XLARGE { font-size : large }
+BIG.XXLARGE { font-size : x-large }
+BIG.HUGE { font-size : larger }
+BIG.XHUGE { font-size : xx-large }
+
+/* heading styles */
+H1 { }
+H2 { }
+H3 { }
+H4 { }
+H5 { }
+
+/* mathematics styles */
+DIV.displaymath { } /* math displays */
+TD.eqno { } /* equation-number cells */
+
+
+/* document-specific styles come next */
--- /dev/null
+%%
+%%
+
+\documentclass[11pt,a4paper]{report}
+\usepackage{html}
+\usepackage{float}
+\usepackage{graphicx}
+\usepackage{bacula}
+\usepackage{longtable}
+\usepackage{makeidx}
+\usepackage{index}
+\usepackage{setspace}
+\usepackage{hyperref}
+\usepackage{url}
+
+
+\makeindex
+\newindex{general}{idx}{ind}{General Index}
+
+\sloppy
+
+\begin{document}
+\sloppy
+
+\newfont{\bighead}{cmr17 at 36pt}
+\parskip 10pt
+\parindent 0pt
+
+\title{\includegraphics{./bacula-logo.eps} \\ \bigskip
+ \Huge{Developers' Guide}
+ \begin{center}
+ \large{It comes in the night and sucks
+ the essence from your computers. }
+ \end{center}
+}
+
+
+\author{Kern Sibbald}
+\date{\vspace{1.0in}\today \\
+ This manual documents Bacula version \input{version} \\
+ \vspace{0.2in}
+ Copyright \copyright 1999-2007, Free Software Foundation Europe
+ e.V. \\
+ \vspace{0.2in}
+ Permission is granted to copy, distribute and/or modify this document under the terms of the
+ GNU Free Documentation License, Version 1.2 published by the Free Software Foundation;
+ with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+ A copy of the license is included in the section entitled "GNU Free Documentation License".
+}
+
+
+\maketitle
+
+\clearpage
+\tableofcontents
+\clearpage
+\listoffigures
+\clearpage
+\listoftables
+\clearpage
+
+\include{generaldevel}
+\include{platformsupport}
+\include{daemonprotocol}
+\include{director}
+\include{file}
+\include{storage}
+\include{catalog}
+\include{mediaformat}
+\include{porting}
+\include{gui-interface}
+\include{tls-techdoc}
+\include{regression}
+\include{md5}
+\include{mempool}
+\include{netprotocol}
+\include{smartall}
+\include{fdl}
+
+
+% The following line tells link_resolver.pl to not include these files:
+% nolinks developersi baculai-dir baculai-fd baculai-sd baculai-console baculai-main
+
+% pull in the index
+\clearpage
+\printindex
+
+\end{document}
--- /dev/null
+%%
+%%
+
+\chapter{Director Services Daemon}
+\label{_ChapterStart6}
+\index{Daemon!Director Services }
+\index{Director Services Daemon }
+\addcontentsline{toc}{section}{Director Services Daemon}
+
+This chapter is intended to be a technical discussion of the Director services
+and as such is not targeted at end users but rather at developers and system
+administrators that want or need to know more of the working details of {\bf
+Bacula}.
+
+The {\bf Bacula Director} services consist of the program that supervises all
+the backup and restore operations.
+
+To be written ...
--- /dev/null
+%---------The file header---------------------------------------------
+
+%% \usepackage[english]{babel} %language selection
+%% \usepackage[T1]{fontenc}
+
+%%\pagenumbering{arabic}
+
+%% \usepackage{hyperref}
+%% \hypersetup{colorlinks,
+%% citecolor=black,
+%% filecolor=black,
+%% linkcolor=black,
+%% urlcolor=black,
+%% pdftex}
+
+
+%---------------------------------------------------------------------
+\chapter{GNU Free Documentation License}
+\index[general]{GNU ree Documentation License}
+\index[general]{License!GNU ree Documentation}
+\addcontentsline{toc}{section}{GNU ree Documentation License}
+
+%\label{label_fdl}
+
+ \begin{center}
+
+ Version 1.2, November 2002
+
+
+ Copyright \copyright 2000,2001,2002 Free Software Foundation, Inc.
+
+ \bigskip
+
+ 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
+
+ \bigskip
+
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+\end{center}
+
+
+\begin{center}
+{\bf\large Preamble}
+\end{center}
+
+The purpose of this License is to make a manual, textbook, or other
+functional and useful document "free" in the sense of freedom: to
+assure everyone the effective freedom to copy and redistribute it,
+with or without modifying it, either commercially or noncommercially.
+Secondarily, this License preserves for the author and publisher a way
+to get credit for their work, while not being considered responsible
+for modifications made by others.
+
+This License is a kind of "copyleft", which means that derivative
+works of the document must themselves be free in the same sense. It
+complements the GNU General Public License, which is a copyleft
+license designed for free software.
+
+We have designed this License in order to use it for manuals for free
+software, because free software needs free documentation: a free
+program should come with manuals providing the same freedoms that the
+software does. But this License is not limited to software manuals;
+it can be used for any textual work, regardless of subject matter or
+whether it is published as a printed book. We recommend this License
+principally for works whose purpose is instruction or reference.
+
+
+\begin{center}
+{\Large\bf 1. APPLICABILITY AND DEFINITIONS}
+\addcontentsline{toc}{section}{1. APPLICABILITY AND DEFINITIONS}
+\end{center}
+
+This License applies to any manual or other work, in any medium, that
+contains a notice placed by the copyright holder saying it can be
+distributed under the terms of this License. Such a notice grants a
+world-wide, royalty-free license, unlimited in duration, to use that
+work under the conditions stated herein. The \textbf{"Document"}, below,
+refers to any such manual or work. Any member of the public is a
+licensee, and is addressed as \textbf{"you"}. You accept the license if you
+copy, modify or distribute the work in a way requiring permission
+under copyright law.
+
+A \textbf{"Modified Version"} of the Document means any work containing the
+Document or a portion of it, either copied verbatim, or with
+modifications and/or translated into another language.
+
+A \textbf{"Secondary Section"} is a named appendix or a front-matter section of
+the Document that deals exclusively with the relationship of the
+publishers or authors of the Document to the Document's overall subject
+(or to related matters) and contains nothing that could fall directly
+within that overall subject. (Thus, if the Document is in part a
+textbook of mathematics, a Secondary Section may not explain any
+mathematics.) The relationship could be a matter of historical
+connection with the subject or with related matters, or of legal,
+commercial, philosophical, ethical or political position regarding
+them.
+
+The \textbf{"Invariant Sections"} are certain Secondary Sections whose titles
+are designated, as being those of Invariant Sections, in the notice
+that says that the Document is released under this License. If a
+section does not fit the above definition of Secondary then it is not
+allowed to be designated as Invariant. The Document may contain zero
+Invariant Sections. If the Document does not identify any Invariant
+Sections then there are none.
+
+The \textbf{"Cover Texts"} are certain short passages of text that are listed,
+as Front-Cover Texts or Back-Cover Texts, in the notice that says that
+the Document is released under this License. A Front-Cover Text may
+be at most 5 words, and a Back-Cover Text may be at most 25 words.
+
+A \textbf{"Transparent"} copy of the Document means a machine-readable copy,
+represented in a format whose specification is available to the
+general public, that is suitable for revising the document
+straightforwardly with generic text editors or (for images composed of
+pixels) generic paint programs or (for drawings) some widely available
+drawing editor, and that is suitable for input to text formatters or
+for automatic translation to a variety of formats suitable for input
+to text formatters. A copy made in an otherwise Transparent file
+format whose markup, or absence of markup, has been arranged to thwart
+or discourage subsequent modification by readers is not Transparent.
+An image format is not Transparent if used for any substantial amount
+of text. A copy that is not "Transparent" is called \textbf{"Opaque"}.
+
+Examples of suitable formats for Transparent copies include plain
+ASCII without markup, Texinfo input format, LaTeX input format, SGML
+or XML using a publicly available DTD, and standard-conforming simple
+HTML, PostScript or PDF designed for human modification. Examples of
+transparent image formats include PNG, XCF and JPG. Opaque formats
+include proprietary formats that can be read and edited only by
+proprietary word processors, SGML or XML for which the DTD and/or
+processing tools are not generally available, and the
+machine-generated HTML, PostScript or PDF produced by some word
+processors for output purposes only.
+
+The \textbf{"Title Page"} means, for a printed book, the title page itself,
+plus such following pages as are needed to hold, legibly, the material
+this License requires to appear in the title page. For works in
+formats which do not have any title page as such, "Title Page" means
+the text near the most prominent appearance of the work's title,
+preceding the beginning of the body of the text.
+
+A section \textbf{"Entitled XYZ"} means a named subunit of the Document whose
+title either is precisely XYZ or contains XYZ in parentheses following
+text that translates XYZ in another language. (Here XYZ stands for a
+specific section name mentioned below, such as \textbf{"Acknowledgements"},
+\textbf{"Dedications"}, \textbf{"Endorsements"}, or \textbf{"History"}.)
+To \textbf{"Preserve the Title"}
+of such a section when you modify the Document means that it remains a
+section "Entitled XYZ" according to this definition.
+
+The Document may include Warranty Disclaimers next to the notice which
+states that this License applies to the Document. These Warranty
+Disclaimers are considered to be included by reference in this
+License, but only as regards disclaiming warranties: any other
+implication that these Warranty Disclaimers may have is void and has
+no effect on the meaning of this License.
+
+
+\begin{center}
+{\Large\bf 2. VERBATIM COPYING}
+\addcontentsline{toc}{section}{2. VERBATIM COPYING}
+\end{center}
+
+You may copy and distribute the Document in any medium, either
+commercially or noncommercially, provided that this License, the
+copyright notices, and the license notice saying this License applies
+to the Document are reproduced in all copies, and that you add no other
+conditions whatsoever to those of this License. You may not use
+technical measures to obstruct or control the reading or further
+copying of the copies you make or distribute. However, you may accept
+compensation in exchange for copies. If you distribute a large enough
+number of copies you must also follow the conditions in section 3.
+
+You may also lend copies, under the same conditions stated above, and
+you may publicly display copies.
+
+
+\begin{center}
+{\Large\bf 3. COPYING IN QUANTITY}
+\addcontentsline{toc}{section}{3. COPYING IN QUANTITY}
+\end{center}
+
+
+If you publish printed copies (or copies in media that commonly have
+printed covers) of the Document, numbering more than 100, and the
+Document's license notice requires Cover Texts, you must enclose the
+copies in covers that carry, clearly and legibly, all these Cover
+Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
+the back cover. Both covers must also clearly and legibly identify
+you as the publisher of these copies. The front cover must present
+the full title with all words of the title equally prominent and
+visible. You may add other material on the covers in addition.
+Copying with changes limited to the covers, as long as they preserve
+the title of the Document and satisfy these conditions, can be treated
+as verbatim copying in other respects.
+
+If the required texts for either cover are too voluminous to fit
+legibly, you should put the first ones listed (as many as fit
+reasonably) on the actual cover, and continue the rest onto adjacent
+pages.
+
+If you publish or distribute Opaque copies of the Document numbering
+more than 100, you must either include a machine-readable Transparent
+copy along with each Opaque copy, or state in or with each Opaque copy
+a computer-network location from which the general network-using
+public has access to download using public-standard network protocols
+a complete Transparent copy of the Document, free of added material.
+If you use the latter option, you must take reasonably prudent steps,
+when you begin distribution of Opaque copies in quantity, to ensure
+that this Transparent copy will remain thus accessible at the stated
+location until at least one year after the last time you distribute an
+Opaque copy (directly or through your agents or retailers) of that
+edition to the public.
+
+It is requested, but not required, that you contact the authors of the
+Document well before redistributing any large number of copies, to give
+them a chance to provide you with an updated version of the Document.
+
+
+\begin{center}
+{\Large\bf 4. MODIFICATIONS}
+\addcontentsline{toc}{section}{4. MODIFICATIONS}
+\end{center}
+
+You may copy and distribute a Modified Version of the Document under
+the conditions of sections 2 and 3 above, provided that you release
+the Modified Version under precisely this License, with the Modified
+Version filling the role of the Document, thus licensing distribution
+and modification of the Modified Version to whoever possesses a copy
+of it. In addition, you must do these things in the Modified Version:
+
+\begin{itemize}
+\item[A.]
+ Use in the Title Page (and on the covers, if any) a title distinct
+ from that of the Document, and from those of previous versions
+ (which should, if there were any, be listed in the History section
+ of the Document). You may use the same title as a previous version
+ if the original publisher of that version gives permission.
+
+\item[B.]
+ List on the Title Page, as authors, one or more persons or entities
+ responsible for authorship of the modifications in the Modified
+ Version, together with at least five of the principal authors of the
+ Document (all of its principal authors, if it has fewer than five),
+ unless they release you from this requirement.
+
+\item[C.]
+ State on the Title page the name of the publisher of the
+ Modified Version, as the publisher.
+
+\item[D.]
+ Preserve all the copyright notices of the Document.
+
+\item[E.]
+ Add an appropriate copyright notice for your modifications
+ adjacent to the other copyright notices.
+
+\item[F.]
+ Include, immediately after the copyright notices, a license notice
+ giving the public permission to use the Modified Version under the
+ terms of this License, in the form shown in the Addendum below.
+
+\item[G.]
+ Preserve in that license notice the full lists of Invariant Sections
+ and required Cover Texts given in the Document's license notice.
+
+\item[H.]
+ Include an unaltered copy of this License.
+
+\item[I.]
+ Preserve the section Entitled "History", Preserve its Title, and add
+ to it an item stating at least the title, year, new authors, and
+ publisher of the Modified Version as given on the Title Page. If
+ there is no section Entitled "History" in the Document, create one
+ stating the title, year, authors, and publisher of the Document as
+ given on its Title Page, then add an item describing the Modified
+ Version as stated in the previous sentence.
+
+\item[J.]
+ Preserve the network location, if any, given in the Document for
+ public access to a Transparent copy of the Document, and likewise
+ the network locations given in the Document for previous versions
+ it was based on. These may be placed in the "History" section.
+ You may omit a network location for a work that was published at
+ least four years before the Document itself, or if the original
+ publisher of the version it refers to gives permission.
+
+\item[K.]
+ For any section Entitled "Acknowledgements" or "Dedications",
+ Preserve the Title of the section, and preserve in the section all
+ the substance and tone of each of the contributor acknowledgements
+ and/or dedications given therein.
+
+\item[L.]
+ Preserve all the Invariant Sections of the Document,
+ unaltered in their text and in their titles. Section numbers
+ or the equivalent are not considered part of the section titles.
+
+\item[M.]
+ Delete any section Entitled "Endorsements". Such a section
+ may not be included in the Modified Version.
+
+\item[N.]
+ Do not retitle any existing section to be Entitled "Endorsements"
+ or to conflict in title with any Invariant Section.
+
+\item[O.]
+ Preserve any Warranty Disclaimers.
+\end{itemize}
+
+If the Modified Version includes new front-matter sections or
+appendices that qualify as Secondary Sections and contain no material
+copied from the Document, you may at your option designate some or all
+of these sections as invariant. To do this, add their titles to the
+list of Invariant Sections in the Modified Version's license notice.
+These titles must be distinct from any other section titles.
+
+You may add a section Entitled "Endorsements", provided it contains
+nothing but endorsements of your Modified Version by various
+parties--for example, statements of peer review or that the text has
+been approved by an organization as the authoritative definition of a
+standard.
+
+You may add a passage of up to five words as a Front-Cover Text, and a
+passage of up to 25 words as a Back-Cover Text, to the end of the list
+of Cover Texts in the Modified Version. Only one passage of
+Front-Cover Text and one of Back-Cover Text may be added by (or
+through arrangements made by) any one entity. If the Document already
+includes a cover text for the same cover, previously added by you or
+by arrangement made by the same entity you are acting on behalf of,
+you may not add another; but you may replace the old one, on explicit
+permission from the previous publisher that added the old one.
+
+The author(s) and publisher(s) of the Document do not by this License
+give permission to use their names for publicity for or to assert or
+imply endorsement of any Modified Version.
+
+
+\begin{center}
+{\Large\bf 5. COMBINING DOCUMENTS}
+\addcontentsline{toc}{section}{5. COMBINING DOCUMENTS}
+\end{center}
+
+
+You may combine the Document with other documents released under this
+License, under the terms defined in section 4 above for modified
+versions, provided that you include in the combination all of the
+Invariant Sections of all of the original documents, unmodified, and
+list them all as Invariant Sections of your combined work in its
+license notice, and that you preserve all their Warranty Disclaimers.
+
+The combined work need only contain one copy of this License, and
+multiple identical Invariant Sections may be replaced with a single
+copy. If there are multiple Invariant Sections with the same name but
+different contents, make the title of each such section unique by
+adding at the end of it, in parentheses, the name of the original
+author or publisher of that section if known, or else a unique number.
+Make the same adjustment to the section titles in the list of
+Invariant Sections in the license notice of the combined work.
+
+In the combination, you must combine any sections Entitled "History"
+in the various original documents, forming one section Entitled
+"History"; likewise combine any sections Entitled "Acknowledgements",
+and any sections Entitled "Dedications". You must delete all sections
+Entitled "Endorsements".
+
+\begin{center}
+{\Large\bf 6. COLLECTIONS OF DOCUMENTS}
+\addcontentsline{toc}{section}{6. COLLECTIONS OF DOCUMENTS}
+\end{center}
+
+You may make a collection consisting of the Document and other documents
+released under this License, and replace the individual copies of this
+License in the various documents with a single copy that is included in
+the collection, provided that you follow the rules of this License for
+verbatim copying of each of the documents in all other respects.
+
+You may extract a single document from such a collection, and distribute
+it individually under this License, provided you insert a copy of this
+License into the extracted document, and follow this License in all
+other respects regarding verbatim copying of that document.
+
+
+\begin{center}
+{\Large\bf 7. AGGREGATION WITH INDEPENDENT WORKS}
+\addcontentsline{toc}{section}{7. AGGREGATION WITH INDEPENDENT WORKS}
+\end{center}
+
+
+A compilation of the Document or its derivatives with other separate
+and independent documents or works, in or on a volume of a storage or
+distribution medium, is called an "aggregate" if the copyright
+resulting from the compilation is not used to limit the legal rights
+of the compilation's users beyond what the individual works permit.
+When the Document is included in an aggregate, this License does not
+apply to the other works in the aggregate which are not themselves
+derivative works of the Document.
+
+If the Cover Text requirement of section 3 is applicable to these
+copies of the Document, then if the Document is less than one half of
+the entire aggregate, the Document's Cover Texts may be placed on
+covers that bracket the Document within the aggregate, or the
+electronic equivalent of covers if the Document is in electronic form.
+Otherwise they must appear on printed covers that bracket the whole
+aggregate.
+
+
+\begin{center}
+{\Large\bf 8. TRANSLATION}
+\addcontentsline{toc}{section}{8. TRANSLATION}
+\end{center}
+
+
+Translation is considered a kind of modification, so you may
+distribute translations of the Document under the terms of section 4.
+Replacing Invariant Sections with translations requires special
+permission from their copyright holders, but you may include
+translations of some or all Invariant Sections in addition to the
+original versions of these Invariant Sections. You may include a
+translation of this License, and all the license notices in the
+Document, and any Warranty Disclaimers, provided that you also include
+the original English version of this License and the original versions
+of those notices and disclaimers. In case of a disagreement between
+the translation and the original version of this License or a notice
+or disclaimer, the original version will prevail.
+
+If a section in the Document is Entitled "Acknowledgements",
+"Dedications", or "History", the requirement (section 4) to Preserve
+its Title (section 1) will typically require changing the actual
+title.
+
+
+\begin{center}
+{\Large\bf 9. TERMINATION}
+\addcontentsline{toc}{section}{9. TERMINATION}
+\end{center}
+
+
+You may not copy, modify, sublicense, or distribute the Document except
+as expressly provided for under this License. Any other attempt to
+copy, modify, sublicense or distribute the Document is void, and will
+automatically terminate your rights under this License. However,
+parties who have received copies, or rights, from you under this
+License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
+
+\begin{center}
+{\Large\bf 10. FUTURE REVISIONS OF THIS LICENSE}
+\addcontentsline{toc}{section}{10. FUTURE REVISIONS OF THIS LICENSE}
+\end{center}
+
+
+The Free Software Foundation may publish new, revised versions
+of the GNU Free Documentation License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns. See
+http://www.gnu.org/copyleft/.
+
+Each version of the License is given a distinguishing version number.
+If the Document specifies that a particular numbered version of this
+License "or any later version" applies to it, you have the option of
+following the terms and conditions either of that specified version or
+of any later version that has been published (not as a draft) by the
+Free Software Foundation. If the Document does not specify a version
+number of this License, you may choose any version ever published (not
+as a draft) by the Free Software Foundation.
+
+
+\begin{center}
+{\Large\bf ADDENDUM: How to use this License for your documents}
+\addcontentsline{toc}{section}{ADDENDUM: How to use this License for your documents}
+\end{center}
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and
+license notices just after the title page:
+
+\bigskip
+\begin{quote}
+ Copyright \copyright YEAR YOUR NAME.
+ Permission is granted to copy, distribute and/or modify this document
+ under the terms of the GNU Free Documentation License, Version 1.2
+ or any later version published by the Free Software Foundation;
+ with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+ A copy of the license is included in the section entitled "GNU
+ Free Documentation License".
+\end{quote}
+\bigskip
+
+If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
+replace the "with...Texts." line with this:
+
+\bigskip
+\begin{quote}
+ with the Invariant Sections being LIST THEIR TITLES, with the
+ Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
+\end{quote}
+\bigskip
+
+If you have Invariant Sections without Cover Texts, or some other
+combination of the three, merge those two alternatives to suit the
+situation.
+
+If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of
+free software license, such as the GNU General Public License,
+to permit their use in free software.
+
+%---------------------------------------------------------------------
--- /dev/null
+%%
+%%
+
+\chapter{File Services Daemon}
+\label{_ChapterStart11}
+\index{File Services Daemon }
+\index{Daemon!File Services }
+\addcontentsline{toc}{section}{File Services Daemon}
+
+Please note, this section is somewhat out of date as the code has evolved
+significantly. The basic idea has not changed though.
+
+This chapter is intended to be a technical discussion of the File daemon
+services and as such is not targeted at end users but rather at developers and
+system administrators that want or need to know more of the working details of
+{\bf Bacula}.
+
+The {\bf Bacula File Services} consist of the programs that run on the system
+to be backed up and provide the interface between the Host File system and
+Bacula -- in particular, the Director and the Storage services.
+
+When time comes for a backup, the Director gets in touch with the File daemon
+on the client machine and hands it a set of ``marching orders'' which, if
+written in English, might be something like the following:
+
+OK, {\bf File daemon}, it's time for your daily incremental backup. I want you
+to get in touch with the Storage daemon on host archive.mysite.com and perform
+the following save operations with the designated options. You'll note that
+I've attached include and exclude lists and patterns you should apply when
+backing up the file system. As this is an incremental backup, you should save
+only files modified since the time you started your last backup which, as you
+may recall, was 2000-11-19-06:43:38. Please let me know when you're done and
+how it went. Thank you.
+
+So, having been handed everything it needs to decide what to dump and where to
+store it, the File daemon doesn't need to have any further contact with the
+Director until the backup is complete providing there are no errors. If there
+are errors, the error messages will be delivered immediately to the Director.
+While the backup is proceeding, the File daemon will send the file coordinates
+and data for each file being backed up to the Storage daemon, which will in
+turn pass the file coordinates to the Director to put in the catalog.
+
+During a {\bf Verify} of the catalog, the situation is different, since the
+File daemon will have an exchange with the Director for each file, and will
+not contact the Storage daemon.
+
+A {\bf Restore} operation will be very similar to the {\bf Backup} except that
+during the {\bf Restore} the Storage daemon will not send storage coordinates
+to the Director since the Director presumably already has them. On the other
+hand, any error messages from either the Storage daemon or File daemon will
+normally be sent directly to the Directory (this, of course, depends on how
+the Message resource is defined).
+
+\section{Commands Received from the Director for a Backup}
+\index{Backup!Commands Received from the Director for a }
+\index{Commands Received from the Director for a Backup }
+\addcontentsline{toc}{subsection}{Commands Received from the Director for a
+Backup}
+
+To be written ...
+
+\section{Commands Received from the Director for a Restore}
+\index{Commands Received from the Director for a Restore }
+\index{Restore!Commands Received from the Director for a }
+\addcontentsline{toc}{subsection}{Commands Received from the Director for a
+Restore}
+
+To be written ...
--- /dev/null
+#!/usr/bin/perl -w
+# Fixes various things within tex files.
+
+use strict;
+
+my %args;
+
+
+sub get_includes {
+ # Get a list of include files from the top-level tex file.
+ my (@list,$file);
+
+ foreach my $filename (@_) {
+ $filename or next;
+ # Start with the top-level latex file so it gets checked too.
+ push (@list,$filename);
+
+ # Get a list of all the html files in the directory.
+ open IF,"<$filename" or die "Cannot open input file $filename";
+ while (<IF>) {
+ chomp;
+ push @list,"$1.tex" if (/\\include\{(.*?)\}/);
+ }
+
+ close IF;
+ }
+ return @list;
+}
+
+sub convert_files {
+ my (@files) = @_;
+ my ($linecnt,$filedata,$output,$itemcnt,$indentcnt,$cnt);
+
+ $cnt = 0;
+ foreach my $file (@files) {
+ # Open the file and load the whole thing into $filedata. A bit wasteful but
+ # easier to deal with, and we don't have a problem with speed here.
+ $filedata = "";
+ open IF,"<$file" or die "Cannot open input file $file";
+ while (<IF>) {
+ $filedata .= $_;
+ }
+ close IF;
+
+ # We look for a line that starts with \item, and indent the two next lines (if not blank)
+ # by three spaces.
+ my $linecnt = 3;
+ $indentcnt = 0;
+ $output = "";
+ # Process a line at a time.
+ foreach (split(/\n/,$filedata)) {
+ $_ .= "\n"; # Put back the return.
+ # If this line is less than the third line past the \item command,
+ # and the line isn't blank and doesn't start with whitespace
+ # add three spaces to the start of the line. Keep track of the number
+ # of lines changed.
+ if ($linecnt < 3 and !/^\\item/) {
+ if (/^[^\n\s]/) {
+ $output .= " " . $_;
+ $indentcnt++;
+ } else {
+ $output .= $_;
+ }
+ $linecnt++;
+ } else {
+ $linecnt = 3;
+ $output .= $_;
+ }
+ /^\\item / and $linecnt = 1;
+ }
+
+
+ # This is an item line. We need to process it too. If inside a \begin{description} environment, convert
+ # \item {\bf xxx} to \item [xxx] or \item [{xxx}] (if xxx contains '[' or ']'.
+ $itemcnt = 0;
+ $filedata = $output;
+ $output = "";
+ my ($before,$descrip,$this,$between);
+
+ # Find any \begin{description} environment
+ while ($filedata =~ /(\\begin[\s\n]*\{[\s\n]*description[\s\n]*\})(.*?)(\\end[\s\n]*\{[\s\n]*description[\s\n]*\})/s) {
+ $output .= $` . $1;
+ $filedata = $3 . $';
+ $descrip = $2;
+
+ # Search for \item {\bf xxx}
+ while ($descrip =~ /\\item[\s\n]*\{[\s\n]*\\bf[\s\n]*/s) {
+ $descrip = $';
+ $output .= $`;
+ ($between,$descrip) = find_matching_brace($descrip);
+ if (!$descrip) {
+ $linecnt = $output =~ tr/\n/\n/;
+ print STDERR "Missing matching curly brace at line $linecnt in $file\n" if (!$descrip);
+ }
+
+ # Now do the replacement.
+ $between = '{' . $between . '}' if ($between =~ /\[|\]/);
+ $output .= "\\item \[$between\]";
+ $itemcnt++;
+ }
+ $output .= $descrip;
+ }
+ $output .= $filedata;
+
+ # If any hyphens or \item commnads were converted, save the file.
+ if ($indentcnt or $itemcnt) {
+ open OF,">$file" or die "Cannot open output file $file";
+ print OF $output;
+ close OF;
+ print "$indentcnt indent", ($indentcnt == 1) ? "" : "s"," added in $file\n";
+ print "$itemcnt item", ($itemcnt == 1) ? "" : "s"," Changed in $file\n";
+ }
+
+ $cnt += $indentcnt + $itemcnt;
+ }
+ return $cnt;
+}
+
+sub find_matching_brace {
+ # Finds text up to the next matching brace. Assumes that the input text doesn't contain
+ # the opening brace, but we want to find text up to a matching closing one.
+ # Returns the text between the matching braces, followed by the rest of the text following
+ # (which does not include the matching brace).
+ #
+ my $str = shift;
+ my ($this,$temp);
+ my $cnt = 1;
+
+ while ($cnt) {
+ # Ignore verbatim constructs involving curly braces, or if the character preceding
+ # the curly brace is a backslash.
+ if ($str =~ /\\verb\*?\{.*?\{|\\verb\*?\}.*?\}|\{|\}/s) {
+ $this .= $`;
+ $str = $';
+ $temp = $&;
+
+ if ((substr($this,-1,1) eq '\\') or
+ $temp =~ /^\\verb/) {
+ $this .= $temp;
+ next;
+ }
+
+ $cnt += ($temp eq '{') ? 1 : -1;
+ # If this isn't the matching curly brace ($cnt > 0), include the brace.
+ $this .= $temp if ($cnt);
+ } else {
+ # No matching curly brace found.
+ return ($this . $str,'');
+ }
+ }
+ return ($this,$str);
+}
+
+sub check_arguments {
+ # Checks command-line arguments for ones starting with -- puts them into
+ # a hash called %args and removes them from @ARGV.
+ my $args = shift;
+ my $i;
+
+ for ($i = 0; $i < $#ARGV; $i++) {
+ $ARGV[$i] =~ /^\-+/ or next;
+ $ARGV[$i] =~ s/^\-+//;
+ $args{$ARGV[$i]} = "";
+ delete ($ARGV[$i]);
+
+ }
+}
+
+##################################################################
+# MAIN ####
+##################################################################
+
+my @includes;
+my $cnt;
+
+check_arguments(\%args);
+die "No Files given to Check\n" if ($#ARGV < 0);
+
+# Examine the file pointed to by the first argument to get a list of
+# includes to test.
+@includes = get_includes(@ARGV);
+
+$cnt = convert_files(@includes);
+print "No lines changed\n" unless $cnt;
--- /dev/null
+%%
+%%
+
+\chapter{Bacula Developer Notes}
+\label{_ChapterStart10}
+\index{Bacula Developer Notes}
+\index{Notes!Bacula Developer}
+\addcontentsline{toc}{section}{Bacula Developer Notes}
+
+\section{General}
+\index{General}
+\addcontentsline{toc}{subsection}{General}
+
+This document is intended mostly for developers and describes the the general
+framework of making Bacula source changes.
+
+\subsection{Contributions}
+\index{Contributions}
+\addcontentsline{toc}{subsubsection}{Contributions}
+
+Contributions from programmers are broken into two groups. The first are
+contributions that are aids and not essential to Bacula. In general, these
+will be scripts or will go into and examples or contributions directory.
+For these kinds of non-essential contributions there is no obligation to do
+a copyright assignment as described below. However, a copyright assignment
+would still be appreciated.
+
+The second class of contributions are those which will be integrated with
+Bacula and become an essential part. Within this class of contributions, there
+are two hurdles to surmount. One is getting your patch accepted, and two is
+dealing with copyright issues. The following text describes some of the
+requirements for such code.
+
+\subsection{Patches}
+\index{Patches}
+\addcontentsline{toc}{subsubsection}{Patches}
+
+Subject to the copyright assignment described below, your patches should be
+sent in {\bf diff -u} format relative to the current contents of the Source
+Forge SVN, which is the easiest to understand and integrate.
+Please be sure to use the Bacula indenting standard (see below).
+If you have checked out the source with SVN, you can get a diff using:
+
+\begin{verbatim}
+svn update
+svn diff > change.patch
+\end{verbatim}
+
+If you plan on doing significant development work over a period of time,
+after having your first patch reviewed and approved, you will be eligible
+for having developer SVN access so that you can commit your changes
+directly to the SVN repository. To do so, you will need a userid on Source
+Forge.
+
+\subsection{Copyrights}
+\index{Copyrights}
+\addcontentsline{toc}{subsubsection}{Copyrights}
+
+To avoid future problems concerning changing licensing or
+copyrights, all code contributions more than a hand full of lines
+must be in the Public Domain or have the copyright transferred to
+the Free Software Foundation Europe e.V. with a Fiduciary License
+Agreement (FLA) as in the current code. Note, prior to
+November 2004, the code was copyrighted by Kern Sibbald and John
+Walker. After November 2004, the code was copyrighted by Kern
+Sibbald, then on the 15th of November 2006, the copyright was
+transferred to the Free Software Foundation Europe e.V.
+
+Your name should be clearly indicated as the author of the code, and you
+must be extremely careful not to violate any copyrights or use other
+people's code without acknowledging it. The purpose of this requirement is
+to avoid future copyright, patent, or intellectual property problems.
+Please read the LICENSE agreement in the main source code
+directory. When you sign the Fiduciary License Agreement (FLA)
+and send it in, you are argeeing to the terms of that LICENSE
+file.
+
+To understand the possible source of future problems, please
+examine the difficulties Mozilla is (was?) having finding
+previous contributors at \elink{
+http://www.mozilla.org/MPL/missing.html}
+{http://www.mozilla.org/MPL/missing.html}. The other important issue is to
+avoid copyright, patent, or intellectual property violations as are currently
+(May 2003) being claimed by SCO against IBM.
+
+Although the copyright will be held by the Free Software
+Foundation Europe e.V., each developer is expected to indicate
+that he wrote and/or modified a particular module (or file) and
+any other sources. The copyright assignment may seem a bit
+unusual, but in reality, it is not. Most large projects require
+this.
+
+If you have any doubts about this, please don't hesitate to ask. The
+objective is to assure the long term servival of the Bacula project.
+
+Items not needing a copyright assignment are: most small changes,
+enhancements, or bug fixes of 5-10 lines of code, which amount to
+less than 20% of any particular file.
+
+\subsection{Copyright Assignment -- Fiduciary License Agreement}
+\index{Copyright Assignment}
+\index{Assignment!Copyright}
+\addcontentsline{toc}{subsubsection}{Copyright Assignment -- Fiduciary License Agreement}
+
+Since this is not a commercial enterprise, and we prefer to believe in
+everyone's good faith, previously developers could assign the copyright by
+explicitly acknowledging that they do so in their first submission. This
+was sufficient if the developer is independent, or an employee of a
+not-for-profit organization or a university. However, in an effort to
+ensure that the Bacula code is really clean, beginning in August 2006, all
+previous and future developers with SVN access will be asked to submit a
+copyright assignment (or Fiduciary License Agreement -- FLA),
+which means you agree to the LICENSE in the main source
+directory. It also means that you receive back the right to use
+the code that you have submitted.
+
+Any developer who wants to contribute and is employed by a company should
+either list the employer as the owner of the code, or get
+explicit permission from him to sign the copyright assignment.
+This is because in many
+countries, all work that an employee does whether on company time or in the
+employee's free time is considered to be Intellectual Property of the
+company. Obtaining official approval or an FLA from the company will avoid
+misunderstandings between the employee, the company, and the Bacula
+project. A good number of companies have already followed this procedure.
+
+The Fiduciary License Agreement is posted on the Bacula web site at:
+\elink{http://www.bacula.org/FLA-bacula.en.pdf}{http://www.bacula.org/FLA-bacula.en.pdf}
+
+The instructions for filling out this agreement are also at:
+\elink{http://www.bacula.org/?page=fsfe}{http://www.bacula.org/?page=fsfe}
+
+It should be filled out, then sent to:
+
+\begin{verbatim}
+ Free Software Foundation Europe
+ Freedom Task Force
+ Sumatrastrasse 25
+ 8006 Zürich
+ Switzerland
+\end{verbatim}
+
+Please note that the above address is different from the officially
+registered office mentioned in the document. When you send in such a
+complete document, please notify me: kern at sibbald dot com.
+
+
+
+\section{The Development Cycle}
+\index{Developement Cycle}
+\index{Cycle!Developement}
+\addcontentsline{toc}{subsubsection}{Development Cycle}
+
+As I noted in the 1.38 ReleaseNotes, version 1.38 was different from prior
+versions because it had a lot more contributions. I expect that this trend
+will continue. As a consequence, I am going to modify how I normally do
+development, and instead of making a list of all the features that I will
+implement in the next version, I will personally sign up for one (maybe
+two) projects at a time, and when they are complete, I will release a new
+version.
+
+The difference is that I will have more time to review the new code that is
+being contributed, and will be able to devote more time to a smaller number
+of projects (1.38 had too many new features for me to handle correctly).
+
+I expect that future release schedules will be much the same, and the
+number of new features will also be much the same providing that the
+contributions continue to come -- and they show no signs of let up :-)
+
+\index{Feature Requests}
+{\bf Feature Requests:} \\
+In addition, I would like to "formalize" the feature requests a bit.
+
+Instead of me maintaining an informal list of everything I run into
+(kernstodo), I would like to maintain a "formal" list of projects. This
+means that all new feature requests, including those recently discussed on
+the email lists, must be formally submitted and approved.
+
+Formal submission of feature requests will take two forms: \\
+1. non-mandatory, but highly recommended is to discuss proposed new features
+on the mailing list.\\
+2. Formal submission of an Feature Request in a special format.
+I'll give an example of this below, but you can also find it on the web
+site under "Support -\gt{} Feature Requests". Since it takes a bit of time to
+properly fill out a Feature Request form, you probably should check on the email list
+first.
+
+Once the Feature Request is received by the keeper of the projects list, it
+will be sent to me, and I will either accept it, send it back
+asking for clarification, send it to the email list asking for opinions, or
+reject it.
+
+If it is accepted, it will go in the "projects" file (a simple ASCII file)
+maintained in the main Bacula source directory.
+
+{\bf Implementation of Feature Requests:}\\
+Any qualified developer can sign up for a project. The project must have
+an entry in the projects file, and the developer's name will appear in the
+Status field.
+
+{\bf How Feature Requests are accepted:}\\
+Acceptance of Feature Requests depends on several things: \\
+1. feedback from users. If it is negative, the Feature Request will probably not be
+accepted. \\
+2. the difficulty of the project. A project that is so
+difficult that I cannot imagine finding someone to implement probably won't
+be accepted. \\
+ 3. whether or not the Feature Request fits within the
+current stategy of Bacula (for example an Feature Request that requests changing the
+tape to tar format would not be accepted, ...)
+
+{\bf How Feature Requests are prioritized:}\\
+Once an Feature Request is accepted, it needs to be implemented. If you
+can find a developer for it, or one signs up for implementing it, then the
+Feature Request becomes top priority (at least for that developer).
+
+Between releases of Bacula, we will generally solicit Feature Request input
+for the next version, and by way of this email, we suggest that you send
+discuss and send in your Feature Requests for the next release. Please
+verify that the Feature Request is not in the current list (attached to this email).
+
+Once users have had several weeks to submit Feature Requests, the keeper of the
+projects list will
+organize them, and request users to vote on them. This will allow fixing
+prioritizing the Feature Requests. Having a priority is one thing, but
+getting it implement is another thing -- we are hoping that the Bacula
+community will take more responsibility for assuring the implementation of
+accepted Feature Requests.
+
+Feature Request format:
+\begin{verbatim}
+============= Empty Feature Request form ===========
+Item n: One line summary ...
+ Date: Date submitted
+ Origin: Name and email of originator.
+ Status:
+
+ What: More detailed explanation ...
+
+ Why: Why it is important ...
+
+ Notes: Additional notes or features (omit if not used)
+============== End Feature Request form ==============
+\end{verbatim}
+
+\begin{verbatim}
+============= Example Completed Feature Request form ===========
+Item 1: Implement a Migration job type that will move the job
+ data from one device to another.
+ Origin: Sponsored by Riege Sofware International GmbH. Contact:
+ Daniel Holtkamp <holtkamp at riege dot com>
+ Date: 28 October 2005
+ Status: Partially coded in 1.37 -- much more to do. Assigned to
+ Kern.
+
+ What: The ability to copy, move, or archive data that is on a
+ device to another device is very important.
+
+ Why: An ISP might want to backup to disk, but after 30 days
+ migrate the data to tape backup and delete it from
+ disk. Bacula should be able to handle this
+ automatically. It needs to know what was put where,
+ and when, and what to migrate -- it is a bit like
+ retention periods. Doing so would allow space to be
+ freed up for current backups while maintaining older
+ data on tape drives.
+
+ Notes: Migration could be triggered by:
+ Number of Jobs
+ Number of Volumes
+ Age of Jobs
+ Highwater size (keep total size)
+ Lowwater mark
+=================================================
+\end{verbatim}
+
+
+\section{Bacula Code Submissions and Projects}
+\index{Submissions and Projects}
+\addcontentsline{toc}{subsection}{Code Submissions and Projects}
+
+Getting code implemented in Bacula works roughly as follows:
+
+\begin{itemize}
+
+\item Kern is the project manager, but prefers not to be a "gate keeper".
+ This means that the developers are expected to be self-motivated,
+ and once they have experience submit directly to the SVN. However,
+ it is a good idea to have your patches reviewed prior to submitting,
+ and it is a bad idea to submit monster patches because no one will
+ be able to properly review them. See below for more details on this.
+
+\item There are growing numbers of contributions (very good).
+
+\item Some contributions come in the form of relatively small patches,
+ which Kern reviews, integrates, documents, tests, and maintains.
+
+\item All Bacula developers take full
+ responsibility for writing the code, posting as patches so that I can
+ review it as time permits, integrating it at an appropriate time,
+ responding to my requests for tweaking it (name changes, ...),
+ document it in the code, document it in the manual (even though
+ their mother tongue is not English), test it, develop and commit
+ regression scripts, and answer in a timely fashion all bug reports --
+ even occassionally accepting additional bugs :-)
+
+ This is a sustainable way of going forward with Bacula, and the
+ direction that the project will be taking more and more. For
+ example, in the past, we have had some very dedicated programmers
+ who did major projects. However, these
+ programmers due to outside obligations (job responsibilities change of
+ job, school duties, ...) could not continue to maintain the code. In
+ those cases, the code suffers from lack of maintenance, sometimes I
+ patch it, sometimes not. In the end, the code gets dropped from the
+ project (there are two such contributions that are heading in that
+ direction). When ever possible, we would like to avoid this, and
+ ensure a continuation of the code and a sharing of the development,
+ debugging, documentation, and maintenance responsibilities.
+\end{itemize}
+
+\section{Patches for Released Versions}
+\index{Patches for Released Versions}
+\addcontentsline{toc}{subsection}{Patches for Released Versions}
+If you fix a bug in a released version, you should, unless it is
+an absolutely trivial bug, create and release a patch file for the
+bug. The procedure is as follows:
+
+Fix the bug in the branch and in the trunk.
+
+Make a patch file for the branch and add the branch patch to
+the patches directory in both the branch and the trunk.
+The name should be 2.2.4-xxx.patch where xxx is unique, in this case it can
+be "restore", e.g. 2.2.4-restore.patch. Add to the top of the
+file a brief description and instructions for applying it -- see for example
+2.2.4-poll-mount.patch. The best way to create the patch file is as
+follows:
+
+\begin{verbatim}
+ (edit) 2.2.4-restore.patch
+ (input description)
+ (end edit)
+
+ svn diff >>2.2.4-restore.patch
+\end{verbatim}
+
+check to make sure no extra junk got put into the patch file (i.e.
+it should have the patch for that bug only).
+
+If there is not a bug report on the problem, create one, then add the
+patch to the bug report.
+
+Uthen upload it to the 2.2.x release of bacula-patches.
+
+So, end the end, the patch file is:
+\begin{itemize}
+\item Attached to the bug report
+
+\item In Branch-2.2/bacula/patches/...
+
+\item In the trunk
+
+\item Loaded on Source Forge bacula-patches 2.2.x release. When
+ you add it, click on the check box to send an Email so that all the
+ users that are monitoring SF patches get notified.
+\end{itemize}
+
+
+
+\section{SVN Usage}
+\index{SVN Usage}
+\addcontentsline{toc}{subsection}{SVN Usage}
+
+Please note that if you are familar with CVS, SVN is very
+similar (and better), but there can be a few surprising
+differences.
+
+The *entire* Bacula SourceForge.net Subversion repository can be
+checked out through SVN with the following command:
+
+\begin{verbatim}
+svn checkout https://bacula.svn.sourceforge.net/svnroot/bacula bacula
+\end{verbatim}
+
+With the above command, you will get everything, which is a very large
+amount of data:
+
+\begin{verbatim}
+branches/
+ Branch-1.32a/
+ ...
+ Branch-2.0/
+ import/
+ vendor/
+tags/
+ Release-1.1/
+ ...
+ Release-2.0.2/
+trunk/
+ bacula/
+ docs/
+ gui/
+ regress/
+ rescue/
+\end{verbatim}
+
+Note, you should NEVER commit code to any checkout that you have
+done of a tag. All tags (e.g. Release-1.1, ... Release-2.0.2)
+should be considered read-only.
+
+You may commit code to the most recent item in
+branches (in the above the most recent one is Branch-2.0). If
+you want to commit code to an older branch, then please contact
+Kern first.
+
+You may create your own tags and/or branches, but they should
+have a name clearly distinctive from Branch-, Release-, or Beta-,
+which are official names used by the project. If you create a
+tag, then you should NEVER commit code to it, for the same
+reason noted above -- it should serve as a marker for something
+you released. If you create a branch, then you are free to
+commit to it as you wish.
+
+You may, of course, commit to the trunk.
+
+In summary:
+
+\begin{verbatim}
+branches
+ Branch-nnn
+tags
+ Release-nnn
+ Beta-nnn
+\end{verbatim}
+
+are reserved names to be created only by the project manager (or
+with his OK), where the nnn is any sequence of numbers and
+periods (e.g. 2.0, 2.0.1, ...).
+
+In addition all tags even those that you create are read-only
+forever. Typically tags represent release points either in the
+trunc or in a branch.
+
+
+Coming back to getting source code.
+If you only want the current Bacula source code, you could use:
+
+\begin{verbatim}
+svn checkout https://bacula.svn.sourceforge.net/svnroot/bacula/trunk/bacula bacula
+\end{verbatim}
+
+To view what is in the SVN, point your browser at the following URL:
+http://bacula.svn.sourceforge.net/viewvc/bacula/
+
+Many of the Subversion (svn) commands are almost identical to those that
+you have used for cvs, but some (such as a checkout) can have surprising
+results, so you should take a careful look at the documentation.
+
+Robert has kindly provided the following documentation on the new
+svn repository and how to use it:
+
+Here is the list of branches:
+\begin{verbatim}
+ Branch-1.32a
+ Branch-1.32e
+ Branch-1.34.2
+ Branch-1.34.5
+ Branch-1.36
+ Branch-1.36.1
+ Branch-1.36.2
+ Branch-1.38
+ Branch-2.0
+ import
+ vendor
+\end{verbatim}
+
+The list of tags is:
+\begin{verbatim}
+ Release-1.1 Release-1.19 Release-1.19a Release-1.19b
+ Release-1.20 Release-1.21 Release-1.22 Release-1.23
+ Release-1.23a Release-1.24 Release-1.25 Release-1.25a
+ Release-1.26 Release-1.27 Release-1.27a Release-1.27b
+ Release-1.27c Release-1.28 Release-1.29 Release-1.30
+ Release-1.31 Release-1.31a Release-1.32 Release-1.32a
+ Release-1.32b Release-1.32c Release-1.32d Release-1.32e
+ Release-1.32f Release-1.32f-2 Release-1.32f-3 Release-1.32f-4
+ Release-1.32f-5 Release-1.34.0 Release-1.34.1 Release-1.34.3
+ Release-1.34.4 Release-1.34.5 Release-1.34.6 Release-1.35.1
+ Release-1.35.2 Release-1.35.3 Release-1.35.6 Release-1.35.7
+ Release-1.35.8 Release-1.36.0 Release-1.36.1 Release-1.36.2
+ Release-1.36.3 Release-1.38.0 Release-1.38.1 Release-1.38.10
+ Release-1.38.11 Release-1.38.2 Release-1.38.3 Release-1.38.4
+ Release-1.38.5 Release-1.38.6 Release-1.38.7 Release-1.38.8
+ Release-1.38.9 Release-1.8.1 Release-1.8.2 Release-1.8.3
+ Release-1.8.4 Release-1.8.5 Release-1.8.6 Release-2.0.0
+ Release-2.0.1 Release-2.0.2
+\end{verbatim}
+
+Here is a list of commands to get you started. The recommended book is
+"Version Control with Subversion", by Ben Collins-Sussmann,
+Brian W. Fitzpatrick, and Michael Pilato, O'Reilly. The book is
+Open Source, so it is also available on line at:
+
+\begin{verbatim}
+ http://svnbook.red-bean.com
+\end{verbatim}
+
+Get a list of commands
+
+\begin{verbatim}
+ svn help
+\end{verbatim}
+
+Get a help with a command
+
+\begin{verbatim}
+ svn help command
+\end{verbatim}
+
+Checkout the HEAD revision of all modules from the project into the
+directory bacula-new
+
+\begin{verbatim}
+ svn co https://bacula.svn.sourceforge.net/svnroot/bacula/trunk bacula.new
+\end{verbatim}
+
+Checkout the HEAD revision of the bacula module into the bacula subdirectory
+
+\begin{verbatim}
+ svn checkout https://bacula.svn.sourceforge.net/svnroot/bacula/trunk/bacula
+\end{verbatim}
+
+See which files have changed in the working copy
+
+\begin{verbatim}
+ svn status
+\end{verbatim}
+
+See which files are out of date
+
+\begin{verbatim}
+ svn status -u
+\end{verbatim}
+
+Add a new file file.c
+
+\begin{verbatim}
+ svn add file.c
+\end{verbatim}
+
+Create a new directory
+
+\begin{verbatim}
+ svn mkdir newdir
+\end{verbatim}
+
+Delete an obsolete file
+
+\begin{verbatim}
+ svn delete file.c
+\end{verbatim}
+
+Rename a file
+
+\begin{verbatim}
+ svn move file.c newfile.c
+\end{verbatim}
+
+Move a file to a new location
+
+\begin{verbatim}
+ svn move file.c ../newdir/file.c
+\end{verbatim}
+
+Copy a file retaining the original history in the new file
+
+\begin{verbatim}
+ svn copy file.c newfile.c
+\end{verbatim}
+
+Update the working copy with the outstanding changes
+
+\begin{verbatim}
+ svn update
+\end{verbatim}
+
+Compare working copy with the repository
+
+\begin{verbatim}
+ svn diff file.c
+\end{verbatim}
+
+Commit the changes in the local working copy
+
+\begin{verbatim}
+ svn commit
+\end{verbatim}
+
+Specify which files are ignored in the current directory
+
+\begin{verbatim}
+ svn propedit svn:ignore .
+\end{verbatim}
+
+Mark a file to be executable
+
+\begin{verbatim}
+ svn propset svn:executable '*' prog.sh
+\end{verbatim}
+
+Unmark a file as executable
+
+\begin{verbatim}
+ svn propdel svn:executable prog.sh
+\end{verbatim}
+
+List a file's properties
+
+\begin{verbatim}
+ svn proplist file.c
+\end{verbatim}
+
+Create a branch for a new version
+
+\begin{verbatim}
+ svn copy https://bacula.svn.sourceforge.net/svnroot/bacula/trunk \
+ https://bacula.svn.sourceforge.net/svnroot/bacula/branches/Branch-2.1
+\end{verbatim}
+
+Tag a version for a new release
+
+\begin{verbatim}
+ svn copy https://bacula.svn.sourceforge.net/svnroot/bacula/branches/Branch-2.1 \
+ https://bacula.svn.sourceforge.net/svnroot/bacula/branches/Release-2.1
+\end{verbatim}
+
+
+Let's say you are working in the directory scripts. You would then do:
+
+\begin{verbatim}
+cd scripts
+(edit some files)
+\end{verbatim}
+
+when you are happy with your changes, you can do the following:
+
+\begin{verbatim}
+cd bacula (to your top level directory)
+svn diff my-changes.patch
+\end{verbatim}
+
+When the command is done, you can look in the file my-changes.patch
+and you will see all the changes you have made to your copy of the
+repository. Make sure that you understand all the changes that
+it reports before proceeding. If you modified files that you do
+do not want to commit to the main repository, you can simply delete
+them from your local directory, and they will be restored from the
+repository with the "svn update" that is shown below. Normally, you
+should not find changes to files that you do not want to commit, and
+if you find yourself in that position a lot, you are probably doing
+something wrong.
+
+Let's assume that now you want to commit your changes to the main
+SVN repository.
+
+First do:
+
+\begin{verbatim}
+cd bacula
+svn update
+\end{verbatim}
+
+When you do this, it will pull any changes made by other developers into
+your local copy of the repository, and it will check for conflicts. If there
+are any, it will tell you, and you will need to resolve them. The problems
+of resolving conflicts are a bit more than this document can cover, but
+you can examine the files it claims have conflicts and look for \lt{}\lt{}\lt{}\lt{}
+or look in the .rej files that it creates. If you have problems, just ask
+on the developer's list.
+
+Note, doing the above "svn update" is not absolutely necessary. There are
+times when you may be working on code and you want to commit it, but you
+explicitly do not want to move up to the latest version of the code in
+the SVN. If that is the case, you can simply skip the "svn update" and
+do the commit shown below. If the commit fails because of a conflict, it
+will tell you, and you must resolve the conflict before it will permit
+you to do the commit.
+
+Once your local copy of the repository has been updated, you can now
+commit your changes:
+
+\begin{verbatim}
+svn commit -m "Some comment about what you changed"
+\end{verbatim}
+
+or if you really only want to commit a single file, you can
+do:
+
+\begin{verbatim}
+svn commit -m "comment" scripts/file-I-edited
+\end{verbatim}
+
+Note, if you have done a build in your directory, or you have added
+other new files, the commit will update only the files that are
+actually in the repository. For example, none of the object files
+are stored in the repository, so when you do a commit, those object
+files will simply be ignored.
+
+If you want to add new files or remove files from the main SVN
+repository, and you are not experienced with SVN, please ask Kern
+to do it. If you follow the simple steps above, it is unlikely that
+you will do any damage to the repository, and if you do, it is always
+possible for us to recover, but it can be painful.
+
+If you are only working in one subdirectory of say the bacula project,
+for example, the scripts directory, you can do your commit from
+that subdirectory, and only the changes in that directory and all its
+subdirectories will be committed. This can be helpful for translators.
+If you are doing a French translation, you will be working in
+docs/manual-fr, and if you are always cd'ed into that directory when
+doing your commits, your commit will effect only that directory. As
+long as you are careful only to change files that you want changed,
+you have little to worry about.
+
+\section{Subversion Resources}
+\index{Subversion (svn) Resources}
+\addcontentsline{toc}{subsection}{Subversion Resources}
+
+\begin{verbatim}
+cvs2svn Statistics:
+------------------
+Total CVS Files: 3286
+Total CVS Revisions: 28924
+Total Unique Tags: 63
+Total Unique Branches: 11
+CVS Repos Size in KB: 232421
+Total SVN Commits: 4116
+First Revision Date: Tue Apr 23 12:42:57 2002
+Last Revision Date: Tue Feb 6 06:37:57 2007
+\end{verbatim}
+
+The new Subversion repository size on Robert's machine:
+
+\begin{verbatim}
+4.0K bacula-tst/dav
+12K bacula-tst/locks
+40K bacula-tst/hooks
+16K bacula-tst/conf
+190M bacula-tst/db/revs
+17M bacula-tst/db/revprops
+4.0K bacula-tst/db/transactions
+206M bacula-tst/db
+206M bacula-tst
+\end{verbatim}
+
+
+Main Subversion Web Page
+\elink{http://subversion.tigris.org}{http://subversion.tigris.org}
+
+Subversion Book
+\elink{http://svnbook.red-bean.com}{http://svnbook.red-bean.com}
+
+Subversion Clients
+\elink{http://subversion.tigris.org/project\_packages.html}{http://subversion.tigris.org/project\_packages.html}
+
+ (For Windows users the TortoiseSVN package is awesome)
+
+GUI UNIX client link
+\elink{http://rapidsvn.tigris.org/}{http://rapidsvn.tigris.org/}
+
+A nice KDE GUI client:
+kdesvn
+
+
+
+\section{Developing Bacula}
+\index{Developing Bacula}
+\index{Bacula!Developing}
+\addcontentsline{toc}{subsubsection}{Developing Bacula}
+
+Typically the simplest way to develop Bacula is to open one xterm window
+pointing to the source directory you wish to update; a second xterm window at
+the top source directory level, and a third xterm window at the bacula
+directory \lt{}top\gt{}/src/bacula. After making source changes in one of the
+directories, in the top source directory xterm, build the source, and start
+the daemons by entering:
+
+make and
+
+./startit then in the enter:
+
+./console or
+
+./gnome-console to start the Console program. Enter any commands for testing.
+For example: run kernsverify full.
+
+Note, the instructions here to use {\bf ./startit} are different from using a
+production system where the administrator starts Bacula by entering {\bf
+./bacula start}. This difference allows a development version of {\bf Bacula}
+to be run on a computer at the same time that a production system is running.
+The {\bf ./startit} strip starts {\bf Bacula} using a different set of
+configuration files, and thus permits avoiding conflicts with any production
+system.
+
+To make additional source changes, exit from the Console program, and in the
+top source directory, stop the daemons by entering:
+
+./stopit then repeat the process.
+
+\subsection{Debugging}
+\index{Debugging}
+\addcontentsline{toc}{subsubsection}{Debugging}
+
+Probably the first thing to do is to turn on debug output.
+
+A good place to start is with a debug level of 20 as in {\bf ./startit -d20}.
+The startit command starts all the daemons with the same debug level.
+Alternatively, you can start the appropriate daemon with the debug level you
+want. If you really need more info, a debug level of 60 is not bad, and for
+just about everything a level of 200.
+
+\subsection{Using a Debugger}
+\index{Using a Debugger}
+\index{Debugger!Using a}
+\addcontentsline{toc}{subsubsection}{Using a Debugger}
+
+If you have a serious problem such as a segmentation fault, it can usually be
+found quickly using a good multiple thread debugger such as {\bf gdb}. For
+example, suppose you get a segmentation violation in {\bf bacula-dir}. You
+might use the following to find the problem:
+
+\lt{}start the Storage and File daemons\gt{}
+cd dird
+gdb ./bacula-dir
+run -f -s -c ./dird.conf
+\lt{}it dies with a segmentation fault\gt{}
+where
+The {\bf -f} option is specified on the {\bf run} command to inhibit {\bf
+dird} from going into the background. You may also want to add the {\bf -s}
+option to the run command to disable signals which can potentially interfere
+with the debugging.
+
+As an alternative to using the debugger, each {\bf Bacula} daemon has a built
+in back trace feature when a serious error is encountered. It calls the
+debugger on itself, produces a back trace, and emails the report to the
+developer. For more details on this, please see the chapter in the main Bacula
+manual entitled ``What To Do When Bacula Crashes (Kaboom)''.
+
+\subsection{Memory Leaks}
+\index{Leaks!Memory}
+\index{Memory Leaks}
+\addcontentsline{toc}{subsubsection}{Memory Leaks}
+
+Because Bacula runs routinely and unattended on client and server machines, it
+may run for a long time. As a consequence, from the very beginning, Bacula
+uses SmartAlloc to ensure that there are no memory leaks. To make detection of
+memory leaks effective, all Bacula code that dynamically allocates memory MUST
+have a way to release it. In general when the memory is no longer needed, it
+should be immediately released, but in some cases, the memory will be held
+during the entire time that Bacula is executing. In that case, there MUST be a
+routine that can be called at termination time that releases the memory. In
+this way, we will be able to detect memory leaks. Be sure to immediately
+correct any and all memory leaks that are printed at the termination of the
+daemons.
+
+\subsection{Special Files}
+\index{Files!Special}
+\index{Special Files}
+\addcontentsline{toc}{subsubsection}{Special Files}
+
+Kern uses files named 1, 2, ... 9 with any extension as scratch files. Thus
+any files with these names are subject to being rudely deleted at any time.
+
+\subsection{When Implementing Incomplete Code}
+\index{Code!When Implementing Incomplete}
+\index{When Implementing Incomplete Code}
+\addcontentsline{toc}{subsubsection}{When Implementing Incomplete Code}
+
+Please identify all incomplete code with a comment that contains
+
+\begin{verbatim}
+***FIXME***
+\end{verbatim}
+
+where there are three asterisks (*) before and after the word
+FIXME (in capitals) and no intervening spaces. This is important as it allows
+new programmers to easily recognize where things are partially implemented.
+
+\subsection{Bacula Source File Structure}
+\index{Structure!Bacula Source File}
+\index{Bacula Source File Structure}
+\addcontentsline{toc}{subsubsection}{Bacula Source File Structure}
+
+The distribution generally comes as a tar file of the form {\bf
+bacula.x.y.z.tar.gz} where x, y, and z are the version, release, and update
+numbers respectively.
+
+Once you detar this file, you will have a directory structure as follows:
+
+\footnotesize
+\begin{verbatim}
+|
+Tar file:
+|- depkgs
+ |- mtx (autochanger control program + tape drive info)
+ |- sqlite (SQLite database program)
+
+Tar file:
+|- depkgs-win32
+ |- pthreads (Native win32 pthreads library -- dll)
+ |- zlib (Native win32 zlib library)
+ |- wx (wxWidgets source code)
+
+Project bacula:
+|- bacula (main source directory containing configuration
+ | and installation files)
+ |- autoconf (automatic configuration files, not normally used
+ | by users)
+ |- intl (programs used to translate)
+ |- platforms (OS specific installation files)
+ |- redhat (Red Hat installation)
+ |- solaris (Sun installation)
+ |- freebsd (FreeBSD installation)
+ |- irix (Irix installation -- not tested)
+ |- unknown (Default if system not identified)
+ |- po (translations of source strings)
+ |- src (source directory; contains global header files)
+ |- cats (SQL catalog database interface directory)
+ |- console (bacula user agent directory)
+ |- dird (Director daemon)
+ |- filed (Unix File daemon)
+ |- win32 (Win32 files to make bacula-fd be a service)
+ |- findlib (Unix file find library for File daemon)
+ |- gnome-console (GNOME version of console program)
+ |- lib (General Bacula library)
+ |- stored (Storage daemon)
+ |- tconsole (Tcl/tk console program -- not yet working)
+ |- testprogs (test programs -- normally only in Kern's tree)
+ |- tools (Various tool programs)
+ |- win32 (Native Win32 File daemon)
+ |- baculafd (Visual Studio project file)
+ |- compat (compatibility interface library)
+ |- filed (links to src/filed)
+ |- findlib (links to src/findlib)
+ |- lib (links to src/lib)
+ |- console (beginning of native console program)
+ |- wx-console (wxWidget console Win32 specific parts)
+ |- wx-console (wxWidgets console main source program)
+
+Project regress:
+|- regress (Regression scripts)
+ |- bin (temporary directory to hold Bacula installed binaries)
+ |- build (temporary directory to hold Bacula source)
+ |- scripts (scripts and .conf files)
+ |- tests (test scripts)
+ |- tmp (temporary directory for temp files)
+ |- working (temporary working directory for Bacula daemons)
+
+Project docs:
+|- docs (documentation directory)
+ |- developers (Developer's guide)
+ |- home-page (Bacula's home page source)
+ |- manual (html document directory)
+ |- manual-fr (French translation)
+ |- manual-de (German translation)
+ |- techlogs (Technical development notes);
+
+Project rescue:
+|- rescue (Bacula rescue CDROM)
+ |- linux (Linux rescue CDROM)
+ |- cdrom (Linux rescue CDROM code)
+ ...
+ |- solaris (Solaris rescue -- incomplete)
+ |- freebsd (FreeBSD rescue -- incomplete)
+
+Project gui:
+|- gui (Bacula GUI projects)
+ |- bacula-web (Bacula web php management code)
+ |- bimagemgr (Web application for burning CDROMs)
+
+
+\end{verbatim}
+\normalsize
+
+\subsection{Header Files}
+\index{Header Files}
+\index{Files!Header}
+\addcontentsline{toc}{subsubsection}{Header Files}
+
+Please carefully follow the scheme defined below as it permits in general only
+two header file includes per C file, and thus vastly simplifies programming.
+With a large complex project like Bacula, it isn't always easy to ensure that
+the right headers are invoked in the right order (there are a few kludges to
+make this happen -- i.e. in a few include files because of the chicken and egg
+problem, certain references to typedefs had to be replaced with {\bf void} ).
+
+Every file should include {\bf bacula.h}. It pulls in just about everything,
+with very few exceptions. If you have system dependent ifdefing, please do it
+in {\bf baconfig.h}. The version number and date are kept in {\bf version.h}.
+
+Each of the subdirectories (console, cats, dird, filed, findlib, lib, stored,
+...) contains a single directory dependent include file generally the name of
+the directory, which should be included just after the include of {\bf
+bacula.h}. This file (for example, for the dird directory, it is {\bf dird.h})
+contains either definitions of things generally needed in this directory, or
+it includes the appropriate header files. It always includes {\bf protos.h}.
+See below.
+
+Each subdirectory contains a header file named {\bf protos.h}, which contains
+the prototypes for subroutines exported by files in that directory. {\bf
+protos.h} is always included by the main directory dependent include file.
+
+\subsection{Programming Standards}
+\index{Standards!Programming}
+\index{Programming Standards}
+\addcontentsline{toc}{subsubsection}{Programming Standards}
+
+For the most part, all code should be written in C unless there is a burning
+reason to use C++, and then only the simplest C++ constructs will be used.
+Note, Bacula is slowly evolving to use more and more C++.
+
+Code should have some documentation -- not a lot, but enough so that I can
+understand it. Look at the current code, and you will see that I document more
+than most, but am definitely not a fanatic.
+
+I prefer simple linear code where possible. Gotos are strongly discouraged
+except for handling an error to either bail out or to retry some code, and
+such use of gotos can vastly simplify the program.
+
+Remember this is a C program that is migrating to a {\bf tiny} subset of C++,
+so be conservative in your use of C++ features.
+
+\subsection{Do Not Use}
+\index{Use!Do Not}
+\index{Do Not Use}
+\addcontentsline{toc}{subsubsection}{Do Not Use}
+
+\begin{itemize}
+ \item STL -- it is totally incomprehensible.
+\end{itemize}
+
+\subsection{Avoid if Possible}
+\index{Possible!Avoid if}
+\index{Avoid if Possible}
+\addcontentsline{toc}{subsubsection}{Avoid if Possible}
+
+\begin{itemize}
+\item Using {\bf void *} because this generally means that one must
+ using casting, and in C++ casting is rather ugly. It is OK to use
+ void * to pass structure address where the structure is not known
+ to the routines accepting the packet (typically callback routines).
+ However, declaring "void *buf" is a bad idea. Please use the
+ correct types whenever possible.
+
+\item Using undefined storage specifications such as (short, int, long,
+ long long, size\_t ...). The problem with all these is that the number of bytes
+ they allocate depends on the compiler and the system. Instead use
+ Bacula's types (int8\_t, uint8\_t, int32\_t, uint32\_t, int64\_t, and
+ uint64\_t). This guarantees that the variables are given exactly the
+ size you want. Please try at all possible to avoid using size\_t ssize\_t
+ and the such. They are very system dependent. However, some system
+ routines may need them, so their use is often unavoidable.
+
+\item Returning a malloc'ed buffer from a subroutine -- someone will forget
+ to release it.
+
+\item Heap allocation (malloc) unless needed -- it is expensive. Use
+ POOL\_MEM instead.
+
+\item Templates -- they can create portability problems.
+
+\item Fancy or tricky C or C++ code, unless you give a good explanation of
+ why you used it.
+
+\item Too much inheritance -- it can complicate the code, and make reading it
+ difficult (unless you are in love with colons)
+
+\end{itemize}
+
+\subsection{Do Use Whenever Possible}
+\index{Possible!Do Use Whenever}
+\index{Do Use Whenever Possible}
+\addcontentsline{toc}{subsubsection}{Do Use Whenever Possible}
+
+\begin{itemize}
+\item Locking and unlocking within a single subroutine.
+
+\item A single point of exit from all subroutines. A goto is
+ perfectly OK to use to get out early, but only to a label
+ named bail\_out, and possibly an ok\_out. See current code
+ examples.
+
+\item Malloc and free within a single subroutine.
+
+\item Comments and global explanations on what your code or algorithm does.
+
+\end{itemize}
+
+\subsection{Indenting Standards}
+\index{Standards!Indenting}
+\index{Indenting Standards}
+\addcontentsline{toc}{subsubsection}{Indenting Standards}
+
+I cannot stand code indented 8 columns at a time. This makes the code
+unreadable. Even 4 at a time uses a lot of space, so I have adopted indenting
+3 spaces at every level. Note, indention is the visual appearance of the
+source on the page, while tabbing is replacing a series of up to 8 spaces from
+a tab character.
+
+The closest set of parameters for the Linux {\bf indent} program that will
+produce reasonably indented code are:
+
+\footnotesize
+\begin{verbatim}
+-nbad -bap -bbo -nbc -br -brs -c36 -cd36 -ncdb -ce -ci3 -cli0
+-cp36 -d0 -di1 -ndj -nfc1 -nfca -hnl -i3 -ip0 -l85 -lp -npcs
+-nprs -npsl -saf -sai -saw -nsob -nss -nbc -ncs -nbfda
+\end{verbatim}
+\normalsize
+
+You can put the above in your .indent.pro file, and then just invoke indent on
+your file. However, be warned. This does not produce perfect indenting, and it
+will mess up C++ class statements pretty badly.
+
+Braces are required in all if statements (missing in some very old code). To
+avoid generating too many lines, the first brace appears on the first line
+(e.g. of an if), and the closing brace is on a line by itself. E.g.
+
+\footnotesize
+\begin{verbatim}
+ if (abc) {
+ some_code;
+ }
+\end{verbatim}
+\normalsize
+
+Just follow the convention in the code. Originally I indented case clauses
+under a switch(), but now I prefer non-indented cases.
+
+\footnotesize
+\begin{verbatim}
+ switch (code) {
+ case 'A':
+ do something
+ break;
+ case 'B':
+ again();
+ break;
+ default:
+ break;
+ }
+\end{verbatim}
+\normalsize
+
+Avoid using // style comments except for temporary code or turning off debug
+code. Standard C comments are preferred (this also keeps the code closer to
+C).
+
+Attempt to keep all lines less than 85 characters long so that the whole line
+of code is readable at one time. This is not a rigid requirement.
+
+Always put a brief description at the top of any new file created describing
+what it does and including your name and the date it was first written. Please
+don't forget any Copyrights and acknowledgments if it isn't 100\% your code.
+Also, include the Bacula copyright notice that is in {\bf src/c}.
+
+In general you should have two includes at the top of the an include for the
+particular directory the code is in, for includes are needed, but this should
+be rare.
+
+In general (except for self-contained packages), prototypes should all be put
+in {\bf protos.h} in each directory.
+
+Always put space around assignment and comparison operators.
+
+\footnotesize
+\begin{verbatim}
+ a = 1;
+ if (b >= 2) {
+ cleanup();
+ }
+\end{verbatim}
+\normalsize
+
+but your can compress things in a {\bf for} statement:
+
+\footnotesize
+\begin{verbatim}
+ for (i=0; i < del.num_ids; i++) {
+ ...
+\end{verbatim}
+\normalsize
+
+Don't overuse the inline if (?:). A full {\bf if} is preferred, except in a
+print statement, e.g.:
+
+\footnotesize
+\begin{verbatim}
+ if (ua->verbose \&& del.num_del != 0) {
+ bsendmsg(ua, _("Pruned %d %s on Volume %s from catalog.\n"), del.num_del,
+ del.num_del == 1 ? "Job" : "Jobs", mr->VolumeName);
+ }
+\end{verbatim}
+\normalsize
+
+Leave a certain amount of debug code (Dmsg) in code you submit, so that future
+problems can be identified. This is particularly true for complicated code
+likely to break. However, try to keep the debug code to a minimum to avoid
+bloating the program and above all to keep the code readable.
+
+Please keep the same style in all new code you develop. If you include code
+previously written, you have the option of leaving it with the old indenting
+or re-indenting it. If the old code is indented with 8 spaces, then please
+re-indent it to Bacula standards.
+
+If you are using {\bf vim}, simply set your tabstop to 8 and your shiftwidth
+to 3.
+
+\subsection{Tabbing}
+\index{Tabbing}
+\addcontentsline{toc}{subsubsection}{Tabbing}
+
+Tabbing (inserting the tab character in place of spaces) is as normal on all
+Unix systems -- a tab is converted space up to the next column multiple of 8.
+My editor converts strings of spaces to tabs automatically -- this results in
+significant compression of the files. Thus, you can remove tabs by replacing
+them with spaces if you wish. Please don't confuse tabbing (use of tab
+characters) with indenting (visual alignment of the code).
+
+\subsection{Don'ts}
+\index{Don'ts}
+\addcontentsline{toc}{subsubsection}{Don'ts}
+
+Please don't use:
+
+\footnotesize
+\begin{verbatim}
+strcpy()
+strcat()
+strncpy()
+strncat();
+sprintf()
+snprintf()
+\end{verbatim}
+\normalsize
+
+They are system dependent and un-safe. These should be replaced by the Bacula
+safe equivalents:
+
+\footnotesize
+\begin{verbatim}
+char *bstrncpy(char *dest, char *source, int dest_size);
+char *bstrncat(char *dest, char *source, int dest_size);
+int bsnprintf(char *buf, int32_t buf_len, const char *fmt, ...);
+int bvsnprintf(char *str, int32_t size, const char *format, va_list ap);
+\end{verbatim}
+\normalsize
+
+See src/lib/bsys.c for more details on these routines.
+
+Don't use the {\bf \%lld} or the {\bf \%q} printf format editing types to edit
+64 bit integers -- they are not portable. Instead, use {\bf \%s} with {\bf
+edit\_uint64()}. For example:
+
+\footnotesize
+\begin{verbatim}
+ char buf[100];
+ uint64_t num = something;
+ char ed1[50];
+ bsnprintf(buf, sizeof(buf), "Num=%s\n", edit_uint64(num, ed1));
+\end{verbatim}
+\normalsize
+
+The edit buffer {\bf ed1} must be at least 27 bytes long to avoid overflow.
+See src/lib/edit.c for more details. If you look at the code, don't start
+screaming that I use {\bf lld}. I actually use subtle trick taught to me by
+John Walker. The {\bf lld} that appears in the editing routine is actually
+{\bf \#define} to a what is needed on your OS (usually ``lld'' or ``q'') and
+is defined in autoconf/configure.in for each OS. C string concatenation causes
+the appropriate string to be concatenated to the ``\%''.
+
+Also please don't use the STL or Templates or any complicated C++ code.
+
+\subsection{Message Classes}
+\index{Classes!Message}
+\index{Message Classes}
+\addcontentsline{toc}{subsubsection}{Message Classes}
+
+Currently, there are five classes of messages: Debug, Error, Job, Memory,
+and Queued.
+
+\subsection{Debug Messages}
+\index{Messages!Debug}
+\index{Debug Messages}
+\addcontentsline{toc}{subsubsection}{Debug Messages}
+
+Debug messages are designed to be turned on at a specified debug level and are
+always sent to STDOUT. There are designed to only be used in the development
+debug process. They are coded as:
+
+DmsgN(level, message, arg1, ...) where the N is a number indicating how many
+arguments are to be substituted into the message (i.e. it is a count of the
+number arguments you have in your message -- generally the number of percent
+signs (\%)). {\bf level} is the debug level at which you wish the message to
+be printed. message is the debug message to be printed, and arg1, ... are the
+arguments to be substituted. Since not all compilers support \#defines with
+varargs, you must explicitly specify how many arguments you have.
+
+When the debug message is printed, it will automatically be prefixed by the
+name of the daemon which is running, the filename where the Dmsg is, and the
+line number within the file.
+
+Some actual examples are:
+
+Dmsg2(20, ``MD5len=\%d MD5=\%s\textbackslash{}n'', strlen(buf), buf);
+
+Dmsg1(9, ``Created client \%s record\textbackslash{}n'', client->hdr.name);
+
+\subsection{Error Messages}
+\index{Messages!Error}
+\index{Error Messages}
+\addcontentsline{toc}{subsubsection}{Error Messages}
+
+Error messages are messages that are related to the daemon as a whole rather
+than a particular job. For example, an out of memory condition my generate an
+error message. They should be very rarely needed. In general, you should be
+using Job and Job Queued messages (Jmsg and Qmsg). They are coded as:
+
+EmsgN(error-code, level, message, arg1, ...) As with debug messages, you must
+explicitly code the of arguments to be substituted in the message. error-code
+indicates the severity or class of error, and it may be one of the following:
+
+\addcontentsline{lot}{table}{Message Error Code Classes}
+\begin{longtable}{lp{3in}}
+{{\bf M\_ABORT} } & {Causes the daemon to immediately abort. This should be
+used only in extreme cases. It attempts to produce a traceback. } \\
+{{\bf M\_ERROR\_TERM} } & {Causes the daemon to immediately terminate. This
+should be used only in extreme cases. It does not produce a traceback. } \\
+{{\bf M\_FATAL} } & {Causes the daemon to terminate the current job, but the
+daemon keeps running } \\
+{{\bf M\_ERROR} } & {Reports the error. The daemon and the job continue
+running } \\
+{{\bf M\_WARNING} } & {Reports an warning message. The daemon and the job
+continue running } \\
+{{\bf M\_INFO} } & {Reports an informational message.}
+
+\end{longtable}
+
+There are other error message classes, but they are in a state of being
+redesigned or deprecated, so please do not use them. Some actual examples are:
+
+
+Emsg1(M\_ABORT, 0, ``Cannot create message thread: \%s\textbackslash{}n'',
+strerror(status));
+
+Emsg3(M\_WARNING, 0, ``Connect to File daemon \%s at \%s:\%d failed. Retrying
+...\textbackslash{}n'', client-\gt{}hdr.name, client-\gt{}address,
+client-\gt{}port);
+
+Emsg3(M\_FATAL, 0, ``bdird\lt{}filed: bad response from Filed to \%s command:
+\%d \%s\textbackslash{}n'', cmd, n, strerror(errno));
+
+\subsection{Job Messages}
+\index{Job Messages}
+\index{Messages!Job}
+\addcontentsline{toc}{subsubsection}{Job Messages}
+
+Job messages are messages that pertain to a particular job such as a file that
+could not be saved, or the number of files and bytes that were saved. They
+Are coded as:
+\begin{verbatim}
+Jmsg(jcr, M\_FATAL, 0, "Text of message");
+\end{verbatim}
+A Jmsg with M\_FATAL will fail the job. The Jmsg() takes varargs so can
+have any number of arguments for substituted in a printf like format.
+Output from the Jmsg() will go to the Job report.
+<br>
+If the Jmsg is followed with a number such as Jmsg1(...), the number
+indicates the number of arguments to be substituted (varargs is not
+standard for \#defines), and what is more important is that the file and
+line number will be prefixed to the message. This permits a sort of debug
+from user's output.
+
+\subsection{Queued Job Messages}
+\index{Queued Job Messages}
+\index{Messages!Job}
+\addcontentsline{toc}{subsubsection}{Queued Job Messages}
+Queued Job messages are similar to Jmsg()s except that the message is
+Queued rather than immediately dispatched. This is necessary within the
+network subroutines and in the message editing routines. This is to prevent
+recursive loops, and to ensure that messages can be delivered even in the
+event of a network error.
+
+
+\subsection{Memory Messages}
+\index{Messages!Memory}
+\index{Memory Messages}
+\addcontentsline{toc}{subsubsection}{Memory Messages}
+
+Memory messages are messages that are edited into a memory buffer. Generally
+they are used in low level routines such as the low level device file dev.c in
+the Storage daemon or in the low level Catalog routines. These routines do not
+generally have access to the Job Control Record and so they return error
+essages reformatted in a memory buffer. Mmsg() is the way to do this.
--- /dev/null
+# This module does multiple indices, supporting the style of the LaTex 'index'
+# package.
+
+# Version Information:
+# 16-Feb-2005 -- Original Creation. Karl E. Cunningham
+# 14-Mar-2005 -- Clarified and Consolodated some of the code.
+# Changed to smoothly handle single and multiple indices.
+
+# Two LaTeX index formats are supported...
+# --- SINGLE INDEX ---
+# \usepackage{makeidx}
+# \makeindex
+# \index{entry1}
+# \index{entry2}
+# \index{entry3}
+# ...
+# \printindex
+#
+# --- MULTIPLE INDICES ---
+#
+# \usepackage{makeidx}
+# \usepackage{index}
+# \makeindex -- latex2html doesn't care but LaTeX does.
+# \newindex{ref1}{ext1}{ext2}{title1}
+# \newindex{ref2}{ext1}{ext2}{title2}
+# \newindex{ref3}{ext1}{ext2}{title3}
+# \index[ref1]{entry1}
+# \index[ref1]{entry2}
+# \index[ref3]{entry3}
+# \index[ref2]{entry4}
+# \index{entry5}
+# \index[ref3]{entry6}
+# ...
+# \printindex[ref1]
+# \printindex[ref2]
+# \printindex[ref3]
+# \printindex
+# ___________________
+#
+# For the multiple-index style, each index is identified by the ref argument to \newindex, \index,
+# and \printindex. A default index is allowed, which is indicated by omitting the optional
+# argument. The default index does not require a \newindex command. As \index commands
+# are encountered, their entries are stored according
+# to the ref argument. When the \printindex command is encountered, the stored index
+# entries for that argument are retrieved and printed. The title for each index is taken
+# from the last argument in the \newindex command.
+# While processing \index and \printindex commands, if no argument is given the index entries
+# are built into a default index. The title of the default index is simply "Index".
+# This makes the difference between single- and multiple-index processing trivial.
+#
+# Another method can be used by omitting the \printindex command and just using \include to
+# pull in index files created by the makeindex program. These files will start with
+# \begin{theindex}. This command is used to determine where to print the index. Using this
+# approach, the indices will be output in the same order as the newindex commands were
+# originally found (see below). Using a combination of \printindex and \include{indexfile} has not
+# been tested and may produce undesireable results.
+#
+# The index data are stored in a hash for later sorting and output. As \printindex
+# commands are handled, the order in which they were found in the tex filea is saved,
+# associated with the ref argument to \printindex.
+#
+# We use the original %index hash to store the index data into. We append a \002 followed by the
+# name of the index to isolate the entries in different indices from each other. This is necessary
+# so that different indices can have entries with the same name. For the default index, the \002 is
+# appended without the name.
+#
+# Since the index order in the output cannot be determined if the \include{indexfile}
+# command is used, the order will be assumed from the order in which the \newindex
+# commands were originally seen in the TeX files. This order is saved as well as the
+# order determined from any printindex{ref} commands. If \printindex commnads are used
+# to specify the index output, that order will be used. If the \include{idxfile} command
+# is used, the order of the original newindex commands will be used. In this case the
+# default index will be printed last since it doesn't have a corresponding \newindex
+# command and its order cannot be determined. Mixing \printindex and \include{idxfile}
+# commands in the same file is likely to produce less than satisfactory results.
+#
+#
+# The hash containing index data is named %indices. It contains the following data:
+#{
+# 'title' => {
+# $ref1 => $indextitle ,
+# $ref2 => $indextitle ,
+# ...
+# },
+# 'newcmdorder' => [ ref1, ref2, ..., * ], # asterisk indicates the position of the default index.
+# 'printindorder' => [ ref1, ref2, ..., * ], # asterisk indicates the position of the default index.
+#}
+
+
+# Globals to handle multiple indices.
+my %indices;
+
+# This tells the system to use up to 7 words in index entries.
+$WORDS_IN_INDEX = 10;
+
+# KEC 2-18-05
+# Handles the \newindex command. This is called if the \newindex command is
+# encountered in the LaTex source. Gets the index ref and title from the arguments.
+# Saves the index ref and title.
+# Note that we are called once to handle multiple \newindex commands that are
+# newline-separated.
+sub do_cmd_newindex {
+ my $data = shift;
+ # The data is sent to us as fields delimited by their ID #'s. We extract the
+ # fields.
+ foreach my $line (split("\n",$data)) {
+ my @fields = split (/(?:\<\#\d+?\#\>)+/,$line);
+
+ # The index name and title are the second and fourth fields in the data.
+ if ($line =~ /^</ or $line =~ /^\\newindex/) {
+ my ($indexref,$indextitle) = ($fields[1],$fields[4]);
+ $indices{'title'}{$indexref} = $indextitle;
+ push (@{$indices{'newcmdorder'}},$indexref);
+ }
+ }
+}
+
+
+# KEC -- Copied from makeidx.perl and modified to do multiple indices.
+# Processes an \index entry from the LaTex file.
+# Gets the optional argument from the index command, which is the name of the index
+# into which to place the entry.
+# Drops the brackets from the index_name
+# Puts the index entry into the html stream
+# Creates the tokenized index entry (which also saves the index entry info
+sub do_real_index {
+ local($_) = @_;
+ local($pat,$idx_entry,$index_name);
+ # catches opt-arg from \index commands for index.sty
+ $index_name = &get_next_optional_argument;
+ $index_name = "" unless defined $index_name;
+ # Drop leading and trailing brackets from the index name.
+ $index_name =~ s/^\[|\]$//g;
+
+ $idx_entry = &missing_braces unless (
+ (s/$next_pair_pr_rx/$pat=$1;$idx_entry=$2;''/e)
+ ||(s/$next_pair_rx/$pat=$1;$idx_entry=$2;''/e));
+
+ if ($index_name and defined $idx_entry and
+ !defined $indices{'title'}{$index_name}) {
+ print STDERR "\nInvalid Index Name: \\index \[$index_name\]\{$idx_entry\}\n";
+ }
+
+ $idx_entry = &named_index_entry($pat, $idx_entry,$index_name);
+ $idx_entry.$_;
+}
+
+# Creates and saves an index entry in the index hashes.
+# Modified to do multiple indices.
+# Creates an index_key that allows index entries to have the same characteristics but be in
+# different indices. This index_key is the regular key with the index name appended.
+# Save the index order for the entry in the %index_order hash.
+sub named_index_entry {
+ local($br_id, $str, $index_name) = @_;
+ my ($index_key);
+ # escape the quoting etc characters
+ # ! -> \001
+ # @ -> \002
+ # | -> \003
+ $* = 1; $str =~ s/\n\s*/ /g; $* = 0; # remove any newlines
+ # protect \001 occurring with images
+ $str =~ s/\001/\016/g; # 0x1 to 0xF
+ $str =~ s/\\\\/\011/g; # Double backslash -> 0xB
+ $str =~ s/\\;SPMquot;/\012/g; # \;SPMquot; -> 0xC
+ $str =~ s/;SPMquot;!/\013/g; # ;SPMquot; -> 0xD
+ $str =~ s/!/\001/g; # Exclamation point -> 0x1
+ $str =~ s/\013/!/g; # 0xD -> Exclaimation point
+ $str =~ s/;SPMquot;@/\015/g; # ;SPMquot;@ to 0xF
+ $str =~ s/@/\002/g; # At sign -> 0x2
+ $str =~ s/\015/@/g; # 0xF to At sign
+ $str =~ s/;SPMquot;\|/\017/g; # ;SMPquot;| to 0x11
+ $str =~ s/\|/\003/g; # Vertical line to 0x3
+ $str =~ s/\017/|/g; # 0x11 to vertical line
+ $str =~ s/;SPMquot;(.)/\1/g; # ;SPMquot; -> whatever the next character is
+ $str =~ s/\012/;SPMquot;/g; # 0x12 to ;SPMquot;
+ $str =~ s/\011/\\\\/g; # 0x11 to double backslash
+ local($key_part, $pageref) = split("\003", $str, 2);
+
+ # For any keys of the form: blablabla!blablabla, which want to be split at the
+ # exclamation point, replace the ! with a comma and a space. We don't do it
+ # that way for this index.
+ $key_part =~ s/\001/, /g;
+ local(@keys) = split("\001", $key_part);
+ # If TITLE is not yet available use $before.
+ $TITLE = $saved_title if (($saved_title)&&(!($TITLE)||($TITLE eq $default_title)));
+ $TITLE = $before unless $TITLE;
+ # Save the reference
+ local($words) = '';
+ if ($SHOW_SECTION_NUMBERS) { $words = &make_idxnum; }
+ elsif ($SHORT_INDEX) { $words = &make_shortidxname; }
+ else { $words = &make_idxname; }
+ local($super_key) = '';
+ local($sort_key, $printable_key, $cur_key);
+ foreach $key (@keys) {
+ $key =~ s/\016/\001/g; # revert protected \001s
+ ($sort_key, $printable_key) = split("\002", $key);
+ #
+ # RRM: 16 May 1996
+ # any \label in the printable-key will have already
+ # created a label where the \index occurred.
+ # This has to be removed, so that the desired label
+ # will be found on the Index page instead.
+ #
+ if ($printable_key =~ /tex2html_anchor_mark/ ) {
+ $printable_key =~ s/><tex2html_anchor_mark><\/A><A//g;
+ local($tmpA,$tmpB) = split("NAME=\"", $printable_key);
+ ($tmpA,$tmpB) = split("\"", $tmpB);
+ $ref_files{$tmpA}='';
+ $index_labels{$tmpA} = 1;
+ }
+ #
+ # resolve and clean-up the hyperlink index-entries
+ # so they can be saved in an index.pl file
+ #
+ if ($printable_key =~ /$cross_ref_mark/ ) {
+ local($label,$id,$ref_label);
+ # $printable_key =~ s/$cross_ref_mark#(\w+)#(\w+)>$cross_ref_mark/
+ $printable_key =~ s/$cross_ref_mark#([^#]+)#([^>]+)>$cross_ref_mark/
+ do { ($label,$id) = ($1,$2);
+ $ref_label = $external_labels{$label} unless
+ ($ref_label = $ref_files{$label});
+ '"' . "$ref_label#$label" . '">' .
+ &get_ref_mark($label,$id)}
+ /geo;
+ }
+ $printable_key =~ s/<\#[^\#>]*\#>//go;
+ #RRM
+ # recognise \char combinations, for a \backslash
+ #
+ $printable_key =~ s/\&\#;\'134/\\/g; # restore \\s
+ $printable_key =~ s/\&\#;\`<BR> /\\/g; # ditto
+ $printable_key =~ s/\&\#;*SPMquot;92/\\/g; # ditto
+ #
+ # $sort_key .= "@$printable_key" if !($printable_key); # RRM
+ $sort_key .= "@$printable_key" if !($sort_key); # RRM
+ $sort_key =~ tr/A-Z/a-z/;
+ if ($super_key) {
+ $cur_key = $super_key . "\001" . $sort_key;
+ $sub_index{$super_key} .= $cur_key . "\004";
+ } else {
+ $cur_key = $sort_key;
+ }
+
+ # Append the $index_name to the current key with a \002 delimiter. This will
+ # allow the same index entry to appear in more than one index.
+ $index_key = $cur_key . "\002$index_name";
+
+ $index{$index_key} .= "";
+
+ #
+ # RRM, 15 June 1996
+ # if there is no printable key, but one is known from
+ # a previous index-entry, then use it.
+ #
+ if (!($printable_key) && ($printable_key{$index_key}))
+ { $printable_key = $printable_key{$index_key}; }
+# if (!($printable_key) && ($printable_key{$cur_key}))
+# { $printable_key = $printable_key{$cur_key}; }
+ #
+ # do not overwrite the printable_key if it contains an anchor
+ #
+ if (!($printable_key{$index_key} =~ /tex2html_anchor_mark/ ))
+ { $printable_key{$index_key} = $printable_key || $key; }
+# if (!($printable_key{$cur_key} =~ /tex2html_anchor_mark/ ))
+# { $printable_key{$cur_key} = $printable_key || $key; }
+
+ $super_key = $cur_key;
+ }
+ #
+ # RRM
+ # page-ranges, from |( and |) and |see
+ #
+ if ($pageref) {
+ if ($pageref eq "\(" ) {
+ $pageref = '';
+ $next .= " from ";
+ } elsif ($pageref eq "\)" ) {
+ $pageref = '';
+ local($next) = $index{$index_key};
+# local($next) = $index{$cur_key};
+ # $next =~ s/[\|] *$//;
+ $next =~ s/(\n )?\| $//;
+ $index{$index_key} = "$next to ";
+# $index{$cur_key} = "$next to ";
+ }
+ }
+
+ if ($pageref) {
+ $pageref =~ s/\s*$//g; # remove trailing spaces
+ if (!$pageref) { $pageref = ' ' }
+ $pageref =~ s/see/<i>see <\/i> /g;
+ #
+ # RRM: 27 Dec 1996
+ # check if $pageref corresponds to a style command.
+ # If so, apply it to the $words.
+ #
+ local($tmp) = "do_cmd_$pageref";
+ if (defined &$tmp) {
+ $words = &$tmp("<#0#>$words<#0#>");
+ $words =~ s/<\#[^\#]*\#>//go;
+ $pageref = '';
+ }
+ }
+ #
+ # RRM: 25 May 1996
+ # any \label in the pageref section will have already
+ # created a label where the \index occurred.
+ # This has to be removed, so that the desired label
+ # will be found on the Index page instead.
+ #
+ if ($pageref) {
+ if ($pageref =~ /tex2html_anchor_mark/ ) {
+ $pageref =~ s/><tex2html_anchor_mark><\/A><A//g;
+ local($tmpA,$tmpB) = split("NAME=\"", $pageref);
+ ($tmpA,$tmpB) = split("\"", $tmpB);
+ $ref_files{$tmpA}='';
+ $index_labels{$tmpA} = 1;
+ }
+ #
+ # resolve and clean-up any hyperlinks in the page-ref,
+ # so they can be saved in an index.pl file
+ #
+ if ($pageref =~ /$cross_ref_mark/ ) {
+ local($label,$id,$ref_label);
+ # $pageref =~ s/$cross_ref_mark#(\w+)#(\w+)>$cross_ref_mark/
+ $pageref =~ s/$cross_ref_mark#([^#]+)#([^>]+)>$cross_ref_mark/
+ do { ($label,$id) = ($1,$2);
+ $ref_files{$label} = ''; # ???? RRM
+ if ($index_labels{$label}) { $ref_label = ''; }
+ else { $ref_label = $external_labels{$label}
+ unless ($ref_label = $ref_files{$label});
+ }
+ '"' . "$ref_label#$label" . '">' . &get_ref_mark($label,$id)}/geo;
+ }
+ $pageref =~ s/<\#[^\#>]*\#>//go;
+
+ if ($pageref eq ' ') { $index{$index_key}='@'; }
+ else { $index{$index_key} .= $pageref . "\n | "; }
+ } else {
+ local($thisref) = &make_named_href('',"$CURRENT_FILE#$br_id",$words);
+ $thisref =~ s/\n//g;
+ $index{$index_key} .= $thisref."\n | ";
+ }
+ #print "\nREF: $sort_key : $index_key :$index{$index_key}";
+
+ #join('',"<A NAME=$br_id>$anchor_invisible_mark<\/A>",$_);
+
+ "<A NAME=\"$br_id\">$anchor_invisible_mark<\/A>";
+}
+
+
+# KEC. -- Copied from makeidx.perl, then modified to do multiple indices.
+# Feeds the index entries to the output. This is called for each index to be built.
+#
+# Generates a list of lookup keys for index entries, from both %printable_keys
+# and %index keys.
+# Sorts the keys according to index-sorting rules.
+# Removes keys with a 0x01 token. (duplicates?)
+# Builds a string to go to the index file.
+# Adds the index entries to the string if they belong in this index.
+# Keeps track of which index is being worked on, so only the proper entries
+# are included.
+# Places the index just built in to the output at the proper place.
+{ my $index_number = 0;
+sub add_real_idx {
+ print "\nDoing the index ... Index Number $index_number\n";
+ local($key, @keys, $next, $index, $old_key, $old_html);
+ my ($idx_ref,$keyref);
+ # RRM, 15.6.96: index constructed from %printable_key, not %index
+ @keys = keys %printable_key;
+
+ while (/$idx_mark/) {
+ # Get the index reference from what follows the $idx_mark and
+ # remove it from the string.
+ s/$idxmark\002(.*?)\002/$idxmark/;
+ $idx_ref = $1;
+ $index = '';
+ # include non- makeidx index-entries
+ foreach $key (keys %index) {
+ next if $printable_key{$key};
+ $old_key = $key;
+ if ($key =~ s/###(.*)$//) {
+ next if $printable_key{$key};
+ push (@keys, $key);
+ $printable_key{$key} = $key;
+ if ($index{$old_key} =~ /HREF="([^"]*)"/i) {
+ $old_html = $1;
+ $old_html =~ /$dd?([^#\Q$dd\E]*)#/;
+ $old_html = $1;
+ } else { $old_html = '' }
+ $index{$key} = $index{$old_key} . $old_html."</A>\n | ";
+ };
+ }
+ @keys = sort makeidx_keysort @keys;
+ @keys = grep(!/\001/, @keys);
+ my $cnt = 0;
+ foreach $key (@keys) {
+ my ($keyref) = $key =~ /.*\002(.*)/;
+ next unless ($idx_ref eq $keyref); # KEC.
+ $index .= &add_idx_key($key);
+ $cnt++;
+ }
+ print "$cnt Index Entries Added\n";
+ $index = '<DD>'.$index unless ($index =~ /^\s*<D(D|T)>/);
+ $index_number++; # KEC.
+ if ($SHORT_INDEX) {
+ print "(compact version with Legend)";
+ local($num) = ( $index =~ s/\<D/<D/g );
+ if ($num > 50 ) {
+ s/$idx_mark/$preindex<HR><DL>\n$index\n<\/DL>$preindex/o;
+ } else {
+ s/$idx_mark/$preindex<HR><DL>\n$index\n<\/DL>/o;
+ }
+ } else {
+ s/$idx_mark/<DL COMPACT>\n$index\n<\/DL>/o; }
+ }
+}
+}
+
+# KEC. Copied from latex2html.pl and modified to support multiple indices.
+# The bibliography and the index should be treated as separate sections
+# in their own HTML files. The \bibliography{} command acts as a sectioning command
+# that has the desired effect. But when the bibliography is constructed
+# manually using the thebibliography environment, or when using the
+# theindex environment it is not possible to use the normal sectioning
+# mechanism. This subroutine inserts a \bibliography{} or a dummy
+# \textohtmlindex command just before the appropriate environments
+# to force sectioning.
+sub add_bbl_and_idx_dummy_commands {
+ local($id) = $global{'max_id'};
+
+ s/([\\]begin\s*$O\d+$C\s*thebibliography)/$bbl_cnt++; $1/eg;
+ ## if ($bbl_cnt == 1) {
+ s/([\\]begin\s*$O\d+$C\s*thebibliography)/$id++; "\\bibliography$O$id$C$O$id$C $1"/geo;
+ #}
+ $global{'max_id'} = $id;
+ # KEC. Modified to global substitution to place multiple index tokens.
+ s/[\\]begin\s*($O\d+$C)\s*theindex/\\textohtmlindex$1/go;
+ # KEC. Modified to pick up the optional argument to \printindex
+ s/[\\]printindex\s*(\[.*?\])?/
+ do { (defined $1) ? "\\textohtmlindex $1" : "\\textohtmlindex []"; } /ego;
+ &lib_add_bbl_and_idx_dummy_commands() if defined(&lib_add_bbl_and_idx_dummy_commands);
+}
+
+# KEC. Copied from latex2html.pl and modified to support multiple indices.
+# For each textohtmlindex mark found, determine the index titles and headers.
+# We place the index ref in the header so the proper index can be generated later.
+# For the default index, the index ref is blank.
+#
+# One problem is that this routine is called twice.. Once for processing the
+# command as originally seen, and once for processing the command when
+# doing the name for the index file. We can detect that by looking at the
+# id numbers (or ref) surrounding the \theindex command, and not incrementing
+# index_number unless a new id (or ref) is seen. This has the side effect of
+# having to unconventionally start the index_number at -1. But it works.
+#
+# Gets the title from the list of indices.
+# If this is the first index, save the title in $first_idx_file. This is what's referenced
+# in the navigation buttons.
+# Increment the index_number for next time.
+# If the indexname command is defined or a newcommand defined for indexname, do it.
+# Save the index TITLE in the toc
+# Save the first_idx_file into the idxfile. This goes into the nav buttons.
+# Build index_labels if needed.
+# Create the index headings and put them in the output stream.
+
+{ my $index_number = 0; # Will be incremented before use.
+ my $first_idx_file; # Static
+ my $no_increment = 0;
+
+sub do_cmd_textohtmlindex {
+ local($_) = @_;
+ my ($idxref,$idxnum,$index_name);
+
+ # We get called from make_name with the first argument = "\001noincrement". This is a sign
+ # to not increment $index_number the next time we are called. We get called twice, once
+ # my make_name and once by process_command. Unfortunately, make_name calls us just to set the name
+ # but doesn't use the result so we get called a second time by process_command. This works fine
+ # except for cases where there are multiple indices except if they aren't named, which is the case
+ # when the index is inserted by an include command in latex. In these cases we are only able to use
+ # the index number to decide which index to draw from, and we don't know how to increment that index
+ # number if we get called a variable number of times for the same index, as is the case between
+ # making html (one output file) and web (multiple output files) output formats.
+ if (/\001noincrement/) {
+ $no_increment = 1;
+ return;
+ }
+
+ # Remove (but save) the index reference
+ s/^\s*\[(.*?)\]/{$idxref = $1; "";}/e;
+
+ # If we have an $idxref, the index name was specified. In this case, we have all the
+ # information we need to carry on. Otherwise, we need to get the idxref
+ # from the $index_number and set the name to "Index".
+ if ($idxref) {
+ $index_name = $indices{'title'}{$idxref};
+ } else {
+ if (defined ($idxref = $indices{'newcmdorder'}->[$index_number])) {
+ $index_name = $indices{'title'}{$idxref};
+ } else {
+ $idxref = '';
+ $index_name = "Index";
+ }
+ }
+
+ $idx_title = "Index"; # The name displayed in the nav bar text.
+
+ # Only set $idxfile if we are at the first index. This will point the
+ # navigation panel to the first index file rather than the last.
+ $first_idx_file = $CURRENT_FILE if ($index_number == 0);
+ $idxfile = $first_idx_file; # Pointer for the Index button in the nav bar.
+ $toc_sec_title = $index_name; # Index link text in the toc.
+ $TITLE = $toc_sec_title; # Title for this index, from which its filename is built.
+ if (%index_labels) { &make_index_labels(); }
+ if (($SHORT_INDEX) && (%index_segment)) { &make_preindex(); }
+ else { $preindex = ''; }
+ local $idx_head = $section_headings{'textohtmlindex'};
+ local($heading) = join(''
+ , &make_section_heading($TITLE, $idx_head)
+ , $idx_mark, "\002", $idxref, "\002" );
+ local($pre,$post) = &minimize_open_tags($heading);
+ $index_number++ unless ($no_increment);
+ $no_increment = 0;
+ join('',"<BR>\n" , $pre, $_);
+}
+}
+
+# Returns an index key, given the key passed as the first argument.
+# Not modified for multiple indices.
+sub add_idx_key {
+ local($key) = @_;
+ local($index, $next);
+ if (($index{$key} eq '@' )&&(!($index_printed{$key}))) {
+ if ($SHORT_INDEX) { $index .= "<DD><BR>\n<DT>".&print_key."\n<DD>"; }
+ else { $index .= "<DT><DD><BR>\n<DT>".&print_key."\n<DD>"; }
+ } elsif (($index{$key})&&(!($index_printed{$key}))) {
+ if ($SHORT_INDEX) {
+ $next = "<DD>".&print_key."\n : ". &print_idx_links;
+ } else {
+ $next = "<DT>".&print_key."\n<DD>". &print_idx_links;
+ }
+ $index .= $next."\n";
+ $index_printed{$key} = 1;
+ }
+
+ if ($sub_index{$key}) {
+ local($subkey, @subkeys, $subnext, $subindex);
+ @subkeys = sort(split("\004", $sub_index{$key}));
+ if ($SHORT_INDEX) {
+ $index .= "<DD>".&print_key unless $index_printed{$key};
+ $index .= "<DL>\n";
+ } else {
+ $index .= "<DT>".&print_key."\n<DD>" unless $index_printed{$key};
+ $index .= "<DL COMPACT>\n";
+ }
+ foreach $subkey (@subkeys) {
+ $index .= &add_sub_idx_key($subkey) unless ($index_printed{$subkey});
+ }
+ $index .= "</DL>\n";
+ }
+ return $index;
+}
+
+1; # Must be present as the last line.
--- /dev/null
+# This file serves as a place to put initialization code and constants to
+# affect the behavior of latex2html for generating the bacula manuals.
+
+# $LINKPOINT specifies what filename to use to link to when creating
+# index.html. Not that this is a hard link.
+$LINKPOINT='"$OVERALL_TITLE"';
+
+
+# The following must be the last line of this file.
+1;
--- /dev/null
+%%
+%%
+
+\chapter{Bacula MD5 Algorithm}
+\label{MD5Chapter}
+\addcontentsline{toc}{section}{}
+
+\section{Command Line Message Digest Utility }
+\index{Utility!Command Line Message Digest }
+\index{Command Line Message Digest Utility }
+\addcontentsline{toc}{subsection}{Command Line Message Digest Utility}
+
+
+This page describes {\bf md5}, a command line utility usable on either Unix or
+MS-DOS/Windows, which generates and verifies message digests (digital
+signatures) using the MD5 algorithm. This program can be useful when
+developing shell scripts or Perl programs for software installation, file
+comparison, and detection of file corruption and tampering.
+
+\subsection{Name}
+\index{Name}
+\addcontentsline{toc}{subsubsection}{Name}
+
+{\bf md5} - generate / check MD5 message digest
+
+\subsection{Synopsis}
+\index{Synopsis }
+\addcontentsline{toc}{subsubsection}{Synopsis}
+
+{\bf md5} [ {\bf -c}{\it signature} ] [ {\bf -u} ] [ {\bf -d}{\it input\_text}
+| {\it infile} ] [ {\it outfile} ]
+
+\subsection{Description}
+\index{Description }
+\addcontentsline{toc}{subsubsection}{Description}
+
+A {\it message digest} is a compact digital signature for an arbitrarily long
+stream of binary data. An ideal message digest algorithm would never generate
+the same signature for two different sets of input, but achieving such
+theoretical perfection would require a message digest as long as the input
+file. Practical message digest algorithms compromise in favour of a digital
+signature of modest size created with an algorithm designed to make
+preparation of input text with a given signature computationally infeasible.
+Message digest algorithms have much in common with techniques used in
+encryption, but to a different end; verification that data have not been
+altered since the signature was published.
+
+Many older programs requiring digital signatures employed 16 or 32 bit {\it
+cyclical redundancy codes} (CRC) originally developed to verify correct
+transmission in data communication protocols, but these short codes, while
+adequate to detect the kind of transmission errors for which they were
+intended, are insufficiently secure for applications such as electronic
+commerce and verification of security related software distributions.
+
+The most commonly used present-day message digest algorithm is the 128 bit MD5
+algorithm, developed by Ron Rivest of the
+\elink{MIT}{http://web.mit.edu/}
+\elink{Laboratory for Computer Science}{http://www.lcs.mit.edu/} and
+\elink{RSA Data Security, Inc.}{http://www.rsa.com/} The algorithm, with a
+reference implementation, was published as Internet
+\elink{RFC 1321}{http://www.fourmilab.ch/md5/rfc1321.html} in April 1992, and
+was placed into the public domain at that time. Message digest algorithms such
+as MD5 are not deemed ``encryption technology'' and are not subject to the
+export controls some governments impose on other data security products.
+(Obviously, the responsibility for obeying the laws in the jurisdiction in
+which you reside is entirely your own, but many common Web and Mail utilities
+use MD5, and I am unaware of any restrictions on their distribution and use.)
+
+The MD5 algorithm has been implemented in numerous computer languages
+including C,
+\elink{Perl}{http://www.perl.org/}, and
+\elink{Java}{http://www.javasoft.com/}; if you're writing a program in such a
+language, track down a suitable subroutine and incorporate it into your
+program. The program described on this page is a {\it command line}
+implementation of MD5, intended for use in shell scripts and Perl programs (it
+is much faster than computing an MD5 signature directly in Perl). This {\bf
+md5} program was originally developed as part of a suite of tools intended to
+monitor large collections of files (for example, the contents of a Web site)
+to detect corruption of files and inadvertent (or perhaps malicious) changes.
+That task is now best accomplished with more comprehensive packages such as
+\elink{Tripwire}{ftp://coast.cs.purdue.edu/pub/COAST/Tripwire/}, but the
+command line {\bf md5} component continues to prove useful for verifying
+correct delivery and installation of software packages, comparing the contents
+of two different systems, and checking for changes in specific files.
+
+\subsection{Options}
+\index{Options }
+\addcontentsline{toc}{subsubsection}{Options}
+
+\begin{description}
+
+\item [{\bf -c}{\it signature} ]
+ \index{-csignature }
+ Computes the signature of the specified {\it infile} or the string supplied
+by the {\bf -d} option and compares it against the specified {\it signature}.
+If the two signatures match, the exit status will be zero, otherwise the exit
+status will be 1. No signature is written to {\it outfile} or standard
+output; only the exit status is set. The signature to be checked must be
+specified as 32 hexadecimal digits.
+
+\item [{\bf -d}{\it input\_text} ]
+ \index{-dinput\_text }
+ A signature is computed for the given {\it input\_text} (which must be quoted
+if it contains white space characters) instead of input from {\it infile} or
+standard input. If input is specified with the {\bf -d} option, no {\it
+infile} should be specified.
+
+\item [{\bf -u} ]
+ Print how-to-call information.
+ \end{description}
+
+\subsection{Files}
+\index{Files }
+\addcontentsline{toc}{subsubsection}{Files}
+
+If no {\it infile} or {\bf -d} option is specified or {\it infile} is a single
+``-'', {\bf md5} reads from standard input; if no {\it outfile} is given, or
+{\it outfile} is a single ``-'', output is sent to standard output. Input and
+output are processed strictly serially; consequently {\bf md5} may be used in
+pipelines.
+
+\subsection{Bugs}
+\index{Bugs }
+\addcontentsline{toc}{subsubsection}{Bugs}
+
+The mechanism used to set standard input to binary mode may be specific to
+Microsoft C; if you rebuild the DOS/Windows version of the program from source
+using another compiler, be sure to verify binary files work properly when read
+via redirection or a pipe.
+
+This program has not been tested on a machine on which {\tt int} and/or {\tt
+long} are longer than 32 bits.
+
+\section{
+\elink{Download md5.zip}{http://www.fourmilab.ch/md5/md5.zip} (Zipped
+archive)}
+\index{Archive!Download md5.zip Zipped }
+\index{Download md5.zip (Zipped archive) }
+\addcontentsline{toc}{subsection}{Download md5.zip (Zipped archive)}
+
+The program is provided as
+\elink{md5.zip}{http://www.fourmilab.ch/md5/md5.zip}, a
+\elink{Zipped}{http://www.pkware.com/} archive containing an ready-to-run
+Win32 command-line executable program, {\tt md5.exe} (compiled using Microsoft
+Visual C++ 5.0), and in source code form along with a {\tt Makefile} to build
+the program under Unix.
+
+\subsection{See Also}
+\index{ALSO!SEE }
+\index{See Also }
+\addcontentsline{toc}{subsubsection}{SEE ALSO}
+
+{\bf sum}(1)
+
+\subsection{Exit Status}
+\index{Status!Exit }
+\index{Exit Status }
+\addcontentsline{toc}{subsubsection}{Exit Status}
+
+{\bf md5} returns status 0 if processing was completed without errors, 1 if
+the {\bf -c} option was specified and the given signature does not match that
+of the input, and 2 if processing could not be performed at all due, for
+example, to a nonexistent input file.
+
+\subsection{Copying}
+\index{Copying }
+\addcontentsline{toc}{subsubsection}{Copying}
+
+\begin{quote}
+This software is in the public domain. Permission to use, copy, modify, and
+distribute this software and its documentation for any purpose and without
+fee is hereby granted, without any conditions or restrictions. This software
+is provided ``as is'' without express or implied warranty.
+\end{quote}
+
+\subsection{Acknowledgements}
+\index{Acknowledgements }
+\addcontentsline{toc}{subsubsection}{Acknowledgements}
+
+The MD5 algorithm was developed by Ron Rivest. The public domain C language
+implementation used in this program was written by Colin Plumb in 1993.
+{\it
+\elink{by John Walker}{http://www.fourmilab.ch/}
+January 6th, MIM }
--- /dev/null
+%%
+%%
+
+\chapter{Storage Media Output Format}
+\label{_ChapterStart9}
+\index{Format!Storage Media Output}
+\index{Storage Media Output Format}
+\addcontentsline{toc}{section}{Storage Media Output Format}
+
+\section{General}
+\index{General}
+\addcontentsline{toc}{subsection}{General}
+
+This document describes the media format written by the Storage daemon. The
+Storage daemon reads and writes in units of blocks. Blocks contain records.
+Each block has a block header followed by records, and each record has a
+record header followed by record data.
+
+This chapter is intended to be a technical discussion of the Media Format and
+as such is not targeted at end users but rather at developers and system
+administrators that want or need to know more of the working details of {\bf
+Bacula}.
+
+\section{Definitions}
+\index{Definitions}
+\addcontentsline{toc}{subsection}{Definitions}
+
+\begin{description}
+
+\item [Block]
+ \index{Block}
+ A block represents the primitive unit of information that the Storage daemon
+reads and writes to a physical device. Normally, for a tape device, it will
+be the same as a tape block. The Storage daemon always reads and writes
+blocks. A block consists of block header information followed by records.
+Clients of the Storage daemon (the File daemon) normally never see blocks.
+However, some of the Storage tools (bls, bscan, bextract, ...) may be use
+block header information. In older Bacula tape versions, a block could
+contain records (see record definition below) from multiple jobs. However,
+all blocks currently written by Bacula are block level BB02, and a given
+block contains records for only a single job. Different jobs simply have
+their own private blocks that are intermingled with the other blocks from
+other jobs on the Volume (previously the records were intermingled within
+the blocks). Having only records from a single job in any give block
+permitted moving the VolumeSessionId and VolumeSessionTime (see below) from
+each record heading to the Block header. This has two advantages: 1. a block
+can be quickly rejected based on the contents of the header without reading
+all the records. 2. because there is on the average more than one record per
+block, less data is written to the Volume for each job.
+
+\item [Record]
+ \index{Record}
+ A record consists of a Record Header, which is managed by the Storage daemon
+and Record Data, which is the data received from the Client. A record is the
+primitive unit of information sent to and from the Storage daemon by the
+Client (File daemon) programs. The details are described below.
+
+\item [JobId]
+ \index{JobId}
+ A number assigned by the Director daemon for a particular job. This number
+will be unique for that particular Director (Catalog). The daemons use this
+number to keep track of individual jobs. Within the Storage daemon, the JobId
+may not be unique if several Directors are accessing the Storage daemon
+simultaneously.
+
+\item [Session]
+ \index{Session}
+ A Session is a concept used in the Storage daemon corresponds one to one to a
+Job with the exception that each session is uniquely identified within the
+Storage daemon by a unique SessionId/SessionTime pair (see below).
+
+\item [VolSessionId]
+ \index{VolSessionId}
+ A unique number assigned by the Storage daemon to a particular session (Job)
+it is having with a File daemon. This number by itself is not unique to the
+given Volume, but with the VolSessionTime, it is unique.
+
+\item [VolSessionTime]
+ \index{VolSessionTime}
+ A unique number assigned by the Storage daemon to a particular Storage daemon
+execution. It is actually the Unix time\_t value of when the Storage daemon
+began execution cast to a 32 bit unsigned integer. The combination of the
+{\bf VolSessionId} and the {\bf VolSessionTime} for a given Storage daemon is
+guaranteed to be unique for each Job (or session).
+
+\item [FileIndex]
+ \index{FileIndex}
+ A sequential number beginning at one assigned by the File daemon to the files
+within a job that are sent to the Storage daemon for backup. The Storage
+daemon ensures that this number is greater than zero and sequential. Note,
+the Storage daemon uses negative FileIndexes to flag Session Start and End
+Labels as well as End of Volume Labels. Thus, the combination of
+VolSessionId, VolSessionTime, and FileIndex uniquely identifies the records
+for a single file written to a Volume.
+
+\item [Stream]
+ \index{Stream}
+ While writing the information for any particular file to the Volume, there
+can be any number of distinct pieces of information about that file, e.g. the
+attributes, the file data, ... The Stream indicates what piece of data it
+is, and it is an arbitrary number assigned by the File daemon to the parts
+(Unix attributes, Win32 attributes, data, compressed data,\ ...) of a file
+that are sent to the Storage daemon. The Storage daemon has no knowledge of
+the details of a Stream; it simply represents a numbered stream of bytes. The
+data for a given stream may be passed to the Storage daemon in single record,
+or in multiple records.
+
+\item [Block Header]
+ \index{Block Header}
+ A block header consists of a block identification (``BB02''), a block length
+in bytes (typically 64,512) a checksum, and sequential block number. Each
+block starts with a Block Header and is followed by Records. Current block
+headers also contain the VolSessionId and VolSessionTime for the records
+written to that block.
+
+\item [Record Header]
+ \index{Record Header}
+ A record header contains the Volume Session Id, the Volume Session Time, the
+FileIndex, the Stream, and the size of the data record which follows. The
+Record Header is always immediately followed by a Data Record if the size
+given in the Header is greater than zero. Note, for Block headers of level
+BB02 (version 1.27 and later), the Record header as written to tape does not
+contain the Volume Session Id and the Volume Session Time as these two
+fields are stored in the BB02 Block header. The in-memory record header does
+have those fields for convenience.
+
+\item [Data Record]
+ \index{Data Record}
+ A data record consists of a binary stream of bytes and is always preceded by
+a Record Header. The details of the meaning of the binary stream of bytes are
+unknown to the Storage daemon, but the Client programs (File daemon) defines
+and thus knows the details of each record type.
+
+\item [Volume Label]
+ \index{Volume Label}
+ A label placed by the Storage daemon at the beginning of each storage volume.
+It contains general information about the volume. It is written in Record
+format. The Storage daemon manages Volume Labels, and if the client wants, he
+may also read them.
+
+\item [Begin Session Label]
+ \index{Begin Session Label}
+ The Begin Session Label is a special record placed by the Storage daemon on
+the storage medium as the first record of an append session job with a File
+daemon. This record is useful for finding the beginning of a particular
+session (Job), since no records with the same VolSessionId and VolSessionTime
+will precede this record. This record is not normally visible outside of the
+Storage daemon. The Begin Session Label is similar to the Volume Label except
+that it contains additional information pertaining to the Session.
+
+\item [End Session Label]
+ \index{End Session Label}
+ The End Session Label is a special record placed by the Storage daemon on the
+storage medium as the last record of an append session job with a File
+daemon. The End Session Record is distinguished by a FileIndex with a value
+of minus two (-2). This record is useful for detecting the end of a
+particular session since no records with the same VolSessionId and
+VolSessionTime will follow this record. This record is not normally visible
+outside of the Storage daemon. The End Session Label is similar to the Volume
+Label except that it contains additional information pertaining to the
+Session.
+\end{description}
+
+\section{Storage Daemon File Output Format}
+\index{Format!Storage Daemon File Output}
+\index{Storage Daemon File Output Format}
+\addcontentsline{toc}{subsection}{Storage Daemon File Output Format}
+
+The file storage and tape storage formats are identical except that tape
+records are by default blocked into blocks of 64,512 bytes, except for the
+last block, which is the actual number of bytes written rounded up to a
+multiple of 1024 whereas the last record of file storage is not rounded up.
+The default block size of 64,512 bytes may be overridden by the user (some
+older tape drives only support block sizes of 32K). Each Session written to
+tape is terminated with an End of File mark (this will be removed later).
+Sessions written to file are simply appended to the end of the file.
+
+\section{Overall Format}
+\index{Format!Overall}
+\index{Overall Format}
+\addcontentsline{toc}{subsection}{Overall Format}
+
+A Bacula output file consists of Blocks of data. Each block contains a block
+header followed by records. Each record consists of a record header followed
+by the record data. The first record on a tape will always be the Volume Label
+Record.
+
+No Record Header will be split across Bacula blocks. However, Record Data may
+be split across any number of Bacula blocks. Obviously this will not be the
+case for the Volume Label which will always be smaller than the Bacula Block
+size.
+
+To simplify reading tapes, the Start of Session (SOS) and End of Session (EOS)
+records are never split across blocks. If this is about to happen, Bacula will
+write a short block before writing the session record (actually, the SOS
+record should always be the first record in a block, excepting perhaps the
+Volume label).
+
+Due to hardware limitations, the last block written to the tape may not be
+fully written. If your drive permits backspace record, Bacula will backup over
+the last record written on the tape, re-read it and verify that it was
+correctly written.
+
+When a new tape is mounted Bacula will write the full contents of the
+partially written block to the new tape ensuring that there is no loss of
+data. When reading a tape, Bacula will discard any block that is not totally
+written, thus ensuring that there is no duplication of data. In addition,
+since Bacula blocks are sequentially numbered within a Job, it is easy to
+ensure that no block is missing or duplicated.
+
+\section{Serialization}
+\index{Serialization}
+\addcontentsline{toc}{subsection}{Serialization}
+
+All Block Headers, Record Headers, and Label Records are written using
+Bacula's serialization routines. These routines guarantee that the data is
+written to the output volume in a machine independent format.
+
+\section{Block Header}
+\index{Header!Block}
+\index{Block Header}
+\addcontentsline{toc}{subsection}{Block Header}
+
+The format of the Block Header (version 1.27 and later) is:
+
+\footnotesize
+\begin{verbatim}
+ uint32_t CheckSum; /* Block check sum */
+ uint32_t BlockSize; /* Block byte size including the header */
+ uint32_t BlockNumber; /* Block number */
+ char ID[4] = "BB02"; /* Identification and block level */
+ uint32_t VolSessionId; /* Session Id for Job */
+ uint32_t VolSessionTime; /* Session Time for Job */
+\end{verbatim}
+\normalsize
+
+The Block header is a fixed length and fixed format and is followed by Record
+Headers and Record Data. The CheckSum field is a 32 bit checksum of the block
+data and the block header but not including the CheckSum field. The Block
+Header is always immediately followed by a Record Header. If the tape is
+damaged, a Bacula utility will be able to recover as much information as
+possible from the tape by recovering blocks which are valid. The Block header
+is written using the Bacula serialization routines and thus is guaranteed to
+be in machine independent format. See below for version 2 of the block header.
+
+
+\section{Record Header}
+\index{Header!Record}
+\index{Record Header}
+\addcontentsline{toc}{subsection}{Record Header}
+
+Each binary data record is preceded by a Record Header. The Record Header is
+fixed length and fixed format, whereas the binary data record is of variable
+length. The Record Header is written using the Bacula serialization routines
+and thus is guaranteed to be in machine independent format.
+
+The format of the Record Header (version 1.27 or later) is:
+
+\footnotesize
+\begin{verbatim}
+ int32_t FileIndex; /* File index supplied by File daemon */
+ int32_t Stream; /* Stream number supplied by File daemon */
+ uint32_t DataSize; /* size of following data record in bytes */
+\end{verbatim}
+\normalsize
+
+This record is followed by the binary Stream data of DataSize bytes, followed
+by another Record Header record and the binary stream data. For the definitive
+definition of this record, see record.h in the src/stored directory.
+
+Additional notes on the above:
+
+\begin{description}
+
+\item [The {\bf VolSessionId} ]
+ \index{VolSessionId}
+ is a unique sequential number that is assigned by the Storage Daemon to a
+particular Job. This number is sequential since the start of execution of the
+daemon.
+
+\item [The {\bf VolSessionTime} ]
+ \index{VolSessionTime}
+ is the time/date that the current execution of the Storage Daemon started. It
+assures that the combination of VolSessionId and VolSessionTime is unique for
+every jobs written to the tape, even if there was a machine crash between two
+writes.
+
+\item [The {\bf FileIndex} ]
+ \index{FileIndex}
+ is a sequential file number within a job. The Storage daemon requires this
+index to be greater than zero and sequential. Note, however, that the File
+daemon may send multiple Streams for the same FileIndex. In addition, the
+Storage daemon uses negative FileIndices to hold the Begin Session Label, the
+End Session Label, and the End of Volume Label.
+
+\item [The {\bf Stream} ]
+ \index{Stream}
+ is defined by the File daemon and is used to identify separate parts of the
+data saved for each file (Unix attributes, Win32 attributes, file data,
+compressed file data, sparse file data, ...). The Storage Daemon has no idea
+of what a Stream is or what it contains except that the Stream is required to
+be a positive integer. Negative Stream numbers are used internally by the
+Storage daemon to indicate that the record is a continuation of the previous
+record (the previous record would not entirely fit in the block).
+
+For Start Session and End Session Labels (where the FileIndex is negative),
+the Storage daemon uses the Stream field to contain the JobId. The current
+stream definitions are:
+
+\footnotesize
+\begin{verbatim}
+#define STREAM_UNIX_ATTRIBUTES 1 /* Generic Unix attributes */
+#define STREAM_FILE_DATA 2 /* Standard uncompressed data */
+#define STREAM_MD5_SIGNATURE 3 /* MD5 signature for the file */
+#define STREAM_GZIP_DATA 4 /* GZip compressed file data */
+/* Extended Unix attributes with Win32 Extended data. Deprecated. */
+#define STREAM_UNIX_ATTRIBUTES_EX 5 /* Extended Unix attr for Win32 EX */
+#define STREAM_SPARSE_DATA 6 /* Sparse data stream */
+#define STREAM_SPARSE_GZIP_DATA 7
+#define STREAM_PROGRAM_NAMES 8 /* program names for program data */
+#define STREAM_PROGRAM_DATA 9 /* Data needing program */
+#define STREAM_SHA1_SIGNATURE 10 /* SHA1 signature for the file */
+#define STREAM_WIN32_DATA 11 /* Win32 BackupRead data */
+#define STREAM_WIN32_GZIP_DATA 12 /* Gzipped Win32 BackupRead data */
+#define STREAM_MACOS_FORK_DATA 13 /* Mac resource fork */
+#define STREAM_HFSPLUS_ATTRIBUTES 14 /* Mac OS extra attributes */
+#define STREAM_UNIX_ATTRIBUTES_ACCESS_ACL 15 /* Standard ACL attributes on UNIX */
+#define STREAM_UNIX_ATTRIBUTES_DEFAULT_ACL 16 /* Default ACL attributes on UNIX */
+\end{verbatim}
+\normalsize
+
+\item [The {\bf DataSize} ]
+ \index{DataSize}
+ is the size in bytes of the binary data record that follows the Session
+Record header. The Storage Daemon has no idea of the actual contents of the
+binary data record. For standard Unix files, the data record typically
+contains the file attributes or the file data. For a sparse file the first
+64 bits of the file data contains the storage address for the data block.
+\end{description}
+
+The Record Header is never split across two blocks. If there is not enough
+room in a block for the full Record Header, the block is padded to the end
+with zeros and the Record Header begins in the next block. The data record, on
+the other hand, may be split across multiple blocks and even multiple physical
+volumes. When a data record is split, the second (and possibly subsequent)
+piece of the data is preceded by a new Record Header. Thus each piece of data
+is always immediately preceded by a Record Header. When reading a record, if
+Bacula finds only part of the data in the first record, it will automatically
+read the next record and concatenate the data record to form a full data
+record.
+
+\section{Version BB02 Block Header}
+\index{Version BB02 Block Header}
+\index{Header!Version BB02 Block}
+\addcontentsline{toc}{subsection}{Version BB02 Block Header}
+
+Each session or Job has its own private block. As a consequence, the SessionId
+and SessionTime are written once in each Block Header and not in the Record
+Header. So, the second and current version of the Block Header BB02 is:
+
+\footnotesize
+\begin{verbatim}
+ uint32_t CheckSum; /* Block check sum */
+ uint32_t BlockSize; /* Block byte size including the header */
+ uint32_t BlockNumber; /* Block number */
+ char ID[4] = "BB02"; /* Identification and block level */
+ uint32_t VolSessionId; /* Applies to all records */
+ uint32_t VolSessionTime; /* contained in this block */
+\end{verbatim}
+\normalsize
+
+As with the previous version, the BB02 Block header is a fixed length and
+fixed format and is followed by Record Headers and Record Data. The CheckSum
+field is a 32 bit CRC checksum of the block data and the block header but not
+including the CheckSum field. The Block Header is always immediately followed
+by a Record Header. If the tape is damaged, a Bacula utility will be able to
+recover as much information as possible from the tape by recovering blocks
+which are valid. The Block header is written using the Bacula serialization
+routines and thus is guaranteed to be in machine independent format.
+
+\section{Version 2 Record Header}
+\index{Version 2 Record Header}
+\index{Header!Version 2 Record}
+\addcontentsline{toc}{subsection}{Version 2 Record Header}
+
+Version 2 Record Header is written to the medium when using Version BB02 Block
+Headers. The memory representation of the record is identical to the old BB01
+Record Header, but on the storage medium, the first two fields, namely
+VolSessionId and VolSessionTime are not written. The Block Header is filled
+with these values when the First user record is written (i.e. non label
+record) so that when the block is written, it will have the current and unique
+VolSessionId and VolSessionTime. On reading each record from the Block, the
+VolSessionId and VolSessionTime is filled in the Record Header from the Block
+Header.
+
+\section{Volume Label Format}
+\index{Volume Label Format}
+\index{Format!Volume Label}
+\addcontentsline{toc}{subsection}{Volume Label Format}
+
+Tape volume labels are created by the Storage daemon in response to a {\bf
+label} command given to the Console program, or alternatively by the {\bf
+btape} program. created. Each volume is labeled with the following information
+using the Bacula serialization routines, which guarantee machine byte order
+independence.
+
+For Bacula versions 1.27 and later, the Volume Label Format is:
+
+\footnotesize
+\begin{verbatim}
+ char Id[32]; /* Bacula 1.0 Immortal\n */
+ uint32_t VerNum; /* Label version number */
+ /* VerNum 11 and greater Bacula 1.27 and later */
+ btime_t label_btime; /* Time/date tape labeled */
+ btime_t write_btime; /* Time/date tape first written */
+ /* The following are 0 in VerNum 11 and greater */
+ float64_t write_date; /* Date this label written */
+ float64_t write_time; /* Time this label written */
+ char VolName[128]; /* Volume name */
+ char PrevVolName[128]; /* Previous Volume Name */
+ char PoolName[128]; /* Pool name */
+ char PoolType[128]; /* Pool type */
+ char MediaType[128]; /* Type of this media */
+ char HostName[128]; /* Host name of writing computer */
+ char LabelProg[32]; /* Label program name */
+ char ProgVersion[32]; /* Program version */
+ char ProgDate[32]; /* Program build date/time */
+\end{verbatim}
+\normalsize
+
+Note, the LabelType (Volume Label, Volume PreLabel, Session Start Label, ...)
+is stored in the record FileIndex field of the Record Header and does not
+appear in the data part of the record.
+
+\section{Session Label}
+\index{Label!Session}
+\index{Session Label}
+\addcontentsline{toc}{subsection}{Session Label}
+
+The Session Label is written at the beginning and end of each session as well
+as the last record on the physical medium. It has the following binary format:
+
+
+\footnotesize
+\begin{verbatim}
+ char Id[32]; /* Bacula Immortal ... */
+ uint32_t VerNum; /* Label version number */
+ uint32_t JobId; /* Job id */
+ uint32_t VolumeIndex; /* sequence no of vol */
+ /* Prior to VerNum 11 */
+ float64_t write_date; /* Date this label written */
+ /* VerNum 11 and greater */
+ btime_t write_btime; /* time/date record written */
+ /* The following is zero VerNum 11 and greater */
+ float64_t write_time; /* Time this label written */
+ char PoolName[128]; /* Pool name */
+ char PoolType[128]; /* Pool type */
+ char JobName[128]; /* base Job name */
+ char ClientName[128];
+ /* Added in VerNum 10 */
+ char Job[128]; /* Unique Job name */
+ char FileSetName[128]; /* FileSet name */
+ uint32_t JobType;
+ uint32_t JobLevel;
+\end{verbatim}
+\normalsize
+
+In addition, the EOS label contains:
+
+\footnotesize
+\begin{verbatim}
+ /* The remainder are part of EOS label only */
+ uint32_t JobFiles;
+ uint64_t JobBytes;
+ uint32_t start_block;
+ uint32_t end_block;
+ uint32_t start_file;
+ uint32_t end_file;
+ uint32_t JobErrors;
+\end{verbatim}
+\normalsize
+
+In addition, for VerNum greater than 10, the EOS label contains (in addition
+to the above):
+
+\footnotesize
+\begin{verbatim}
+ uint32_t JobStatus /* Job termination code */
+\end{verbatim}
+\normalsize
+
+: Note, the LabelType (Volume Label, Volume PreLabel, Session Start Label,
+...) is stored in the record FileIndex field and does not appear in the data
+part of the record. Also, the Stream field of the Record Header contains the
+JobId. This permits quick filtering without actually reading all the session
+data in many cases.
+
+\section{Overall Storage Format}
+\index{Format!Overall Storage}
+\index{Overall Storage Format}
+\addcontentsline{toc}{subsection}{Overall Storage Format}
+
+\footnotesize
+\begin{verbatim}
+ Current Bacula Tape Format
+ 6 June 2001
+ Version BB02 added 28 September 2002
+ Version BB01 is the old deprecated format.
+ A Bacula tape is composed of tape Blocks. Each block
+ has a Block header followed by the block data. Block
+ Data consists of Records. Records consist of Record
+ Headers followed by Record Data.
+ :=======================================================:
+ | |
+ | Block Header (24 bytes) |
+ | |
+ |-------------------------------------------------------|
+ | |
+ | Record Header (12 bytes) |
+ | |
+ |-------------------------------------------------------|
+ | |
+ | Record Data |
+ | |
+ |-------------------------------------------------------|
+ | |
+ | Record Header (12 bytes) |
+ | |
+ |-------------------------------------------------------|
+ | |
+ | ... |
+ Block Header: the first item in each block. The format is
+ shown below.
+ Partial Data block: occurs if the data from a previous
+ block spills over to this block (the normal case except
+ for the first block on a tape). However, this partial
+ data block is always preceded by a record header.
+ Record Header: identifies the Volume Session, the Stream
+ and the following Record Data size. See below for format.
+ Record data: arbitrary binary data.
+ Block Header Format BB02
+ :=======================================================:
+ | CheckSum (uint32_t) |
+ |-------------------------------------------------------|
+ | BlockSize (uint32_t) |
+ |-------------------------------------------------------|
+ | BlockNumber (uint32_t) |
+ |-------------------------------------------------------|
+ | "BB02" (char [4]) |
+ |-------------------------------------------------------|
+ | VolSessionId (uint32_t) |
+ |-------------------------------------------------------|
+ | VolSessionTime (uint32_t) |
+ :=======================================================:
+ BBO2: Serves to identify the block as a
+ Bacula block and also servers as a block format identifier
+ should we ever need to change the format.
+ BlockSize: is the size in bytes of the block. When reading
+ back a block, if the BlockSize does not agree with the
+ actual size read, Bacula discards the block.
+ CheckSum: a checksum for the Block.
+ BlockNumber: is the sequential block number on the tape.
+ VolSessionId: a unique sequential number that is assigned
+ by the Storage Daemon to a particular Job.
+ This number is sequential since the start
+ of execution of the daemon.
+ VolSessionTime: the time/date that the current execution
+ of the Storage Daemon started. It assures
+ that the combination of VolSessionId and
+ VolSessionTime is unique for all jobs
+ written to the tape, even if there was a
+ machine crash between two writes.
+ Record Header Format BB02
+ :=======================================================:
+ | FileIndex (int32_t) |
+ |-------------------------------------------------------|
+ | Stream (int32_t) |
+ |-------------------------------------------------------|
+ | DataSize (uint32_t) |
+ :=======================================================:
+ FileIndex: a sequential file number within a job. The
+ Storage daemon enforces this index to be
+ greater than zero and sequential. Note,
+ however, that the File daemon may send
+ multiple Streams for the same FileIndex.
+ The Storage Daemon uses negative FileIndices
+ to identify Session Start and End labels
+ as well as the End of Volume labels.
+ Stream: defined by the File daemon and is intended to be
+ used to identify separate parts of the data
+ saved for each file (attributes, file data,
+ ...). The Storage Daemon has no idea of
+ what a Stream is or what it contains.
+ DataSize: the size in bytes of the binary data record
+ that follows the Session Record header.
+ The Storage Daemon has no idea of the
+ actual contents of the binary data record.
+ For standard Unix files, the data record
+ typically contains the file attributes or
+ the file data. For a sparse file
+ the first 64 bits of the data contains
+ the storage address for the data block.
+ Volume Label
+ :=======================================================:
+ | Id (32 bytes) |
+ |-------------------------------------------------------|
+ | VerNum (uint32_t) |
+ |-------------------------------------------------------|
+ | label_date (float64_t) |
+ | label_btime (btime_t VerNum 11 |
+ |-------------------------------------------------------|
+ | label_time (float64_t) |
+ | write_btime (btime_t VerNum 11 |
+ |-------------------------------------------------------|
+ | write_date (float64_t) |
+ | 0 (float64_t) VerNum 11 |
+ |-------------------------------------------------------|
+ | write_time (float64_t) |
+ | 0 (float64_t) VerNum 11 |
+ |-------------------------------------------------------|
+ | VolName (128 bytes) |
+ |-------------------------------------------------------|
+ | PrevVolName (128 bytes) |
+ |-------------------------------------------------------|
+ | PoolName (128 bytes) |
+ |-------------------------------------------------------|
+ | PoolType (128 bytes) |
+ |-------------------------------------------------------|
+ | MediaType (128 bytes) |
+ |-------------------------------------------------------|
+ | HostName (128 bytes) |
+ |-------------------------------------------------------|
+ | LabelProg (32 bytes) |
+ |-------------------------------------------------------|
+ | ProgVersion (32 bytes) |
+ |-------------------------------------------------------|
+ | ProgDate (32 bytes) |
+ |-------------------------------------------------------|
+ :=======================================================:
+
+ Id: 32 byte Bacula identifier "Bacula 1.0 immortal\n"
+ (old version also recognized:)
+ Id: 32 byte Bacula identifier "Bacula 0.9 mortal\n"
+ LabelType (Saved in the FileIndex of the Header record).
+ PRE_LABEL -1 Volume label on unwritten tape
+ VOL_LABEL -2 Volume label after tape written
+ EOM_LABEL -3 Label at EOM (not currently implemented)
+ SOS_LABEL -4 Start of Session label (format given below)
+ EOS_LABEL -5 End of Session label (format given below)
+ VerNum: 11
+ label_date: Julian day tape labeled
+ label_time: Julian time tape labeled
+ write_date: Julian date tape first used (data written)
+ write_time: Julian time tape first used (data written)
+ VolName: "Physical" Volume name
+ PrevVolName: The VolName of the previous tape (if this tape is
+ a continuation of the previous one).
+ PoolName: Pool Name
+ PoolType: Pool Type
+ MediaType: Media Type
+ HostName: Name of host that is first writing the tape
+ LabelProg: Name of the program that labeled the tape
+ ProgVersion: Version of the label program
+ ProgDate: Date Label program built
+ Session Label
+ :=======================================================:
+ | Id (32 bytes) |
+ |-------------------------------------------------------|
+ | VerNum (uint32_t) |
+ |-------------------------------------------------------|
+ | JobId (uint32_t) |
+ |-------------------------------------------------------|
+ | write_btime (btime_t) VerNum 11 |
+ |-------------------------------------------------------|
+ | 0 (float64_t) VerNum 11 |
+ |-------------------------------------------------------|
+ | PoolName (128 bytes) |
+ |-------------------------------------------------------|
+ | PoolType (128 bytes) |
+ |-------------------------------------------------------|
+ | JobName (128 bytes) |
+ |-------------------------------------------------------|
+ | ClientName (128 bytes) |
+ |-------------------------------------------------------|
+ | Job (128 bytes) |
+ |-------------------------------------------------------|
+ | FileSetName (128 bytes) |
+ |-------------------------------------------------------|
+ | JobType (uint32_t) |
+ |-------------------------------------------------------|
+ | JobLevel (uint32_t) |
+ |-------------------------------------------------------|
+ | FileSetMD5 (50 bytes) VerNum 11 |
+ |-------------------------------------------------------|
+ Additional fields in End Of Session Label
+ |-------------------------------------------------------|
+ | JobFiles (uint32_t) |
+ |-------------------------------------------------------|
+ | JobBytes (uint32_t) |
+ |-------------------------------------------------------|
+ | start_block (uint32_t) |
+ |-------------------------------------------------------|
+ | end_block (uint32_t) |
+ |-------------------------------------------------------|
+ | start_file (uint32_t) |
+ |-------------------------------------------------------|
+ | end_file (uint32_t) |
+ |-------------------------------------------------------|
+ | JobErrors (uint32_t) |
+ |-------------------------------------------------------|
+ | JobStatus (uint32_t) VerNum 11 |
+ :=======================================================:
+ * => fields deprecated
+ Id: 32 byte Bacula Identifier "Bacula 1.0 immortal\n"
+ LabelType (in FileIndex field of Header):
+ EOM_LABEL -3 Label at EOM
+ SOS_LABEL -4 Start of Session label
+ EOS_LABEL -5 End of Session label
+ VerNum: 11
+ JobId: JobId
+ write_btime: Bacula time/date this tape record written
+ write_date: Julian date tape this record written - deprecated
+ write_time: Julian time tape this record written - deprecated.
+ PoolName: Pool Name
+ PoolType: Pool Type
+ MediaType: Media Type
+ ClientName: Name of File daemon or Client writing this session
+ Not used for EOM_LABEL.
+\end{verbatim}
+\normalsize
+
+\section{Unix File Attributes}
+\index{Unix File Attributes}
+\index{Attributes!Unix File}
+\addcontentsline{toc}{subsection}{Unix File Attributes}
+
+The Unix File Attributes packet consists of the following:
+
+\lt{}File-Index\gt{} \lt{}Type\gt{}
+\lt{}Filename\gt{}@\lt{}File-Attributes\gt{}@\lt{}Link\gt{}
+@\lt{}Extended-Attributes@\gt{} where
+
+\begin{description}
+
+\item [@]
+ represents a byte containing a binary zero.
+
+\item [FileIndex]
+ \index{FileIndex}
+ is the sequential file index starting from one assigned by the File daemon.
+
+\item [Type]
+ \index{Type}
+ is one of the following:
+
+\footnotesize
+\begin{verbatim}
+#define FT_LNKSAVED 1 /* hard link to file already saved */
+#define FT_REGE 2 /* Regular file but empty */
+#define FT_REG 3 /* Regular file */
+#define FT_LNK 4 /* Soft Link */
+#define FT_DIR 5 /* Directory */
+#define FT_SPEC 6 /* Special file -- chr, blk, fifo, sock */
+#define FT_NOACCESS 7 /* Not able to access */
+#define FT_NOFOLLOW 8 /* Could not follow link */
+#define FT_NOSTAT 9 /* Could not stat file */
+#define FT_NOCHG 10 /* Incremental option, file not changed */
+#define FT_DIRNOCHG 11 /* Incremental option, directory not changed */
+#define FT_ISARCH 12 /* Trying to save archive file */
+#define FT_NORECURSE 13 /* No recursion into directory */
+#define FT_NOFSCHG 14 /* Different file system, prohibited */
+#define FT_NOOPEN 15 /* Could not open directory */
+#define FT_RAW 16 /* Raw block device */
+#define FT_FIFO 17 /* Raw fifo device */
+\end{verbatim}
+\normalsize
+
+\item [Filename]
+ \index{Filename}
+ is the fully qualified filename.
+
+\item [File-Attributes]
+ \index{File-Attributes}
+ consists of the 13 fields of the stat() buffer in ASCII base64 format
+separated by spaces. These fields and their meanings are shown below. This
+stat() packet is in Unix format, and MUST be provided (constructed) for ALL
+systems.
+
+\item [Link]
+ \index{Link}
+ when the FT code is FT\_LNK or FT\_LNKSAVED, the item in question is a Unix
+link, and this field contains the fully qualified link name. When the FT code
+is not FT\_LNK or FT\_LNKSAVED, this field is null.
+
+\item [Extended-Attributes]
+ \index{Extended-Attributes}
+ The exact format of this field is operating system dependent. It contains
+additional or extended attributes of a system dependent nature. Currently,
+this field is used only on WIN32 systems where it contains a ASCII base64
+representation of the WIN32\_FILE\_ATTRIBUTE\_DATA structure as defined by
+Windows. The fields in the base64 representation of this structure are like
+the File-Attributes separated by spaces.
+\end{description}
+
+The File-attributes consist of the following:
+
+\addcontentsline{lot}{table}{File Attributes}
+\begin{longtable}{|p{0.6in}|p{0.7in}|p{1in}|p{1in}|p{1.4in}|}
+ \hline
+\multicolumn{1}{|c|}{\bf Field No. } & \multicolumn{1}{c|}{\bf Stat Name }
+& \multicolumn{1}{c|}{\bf Unix } & \multicolumn{1}{c|}{\bf Win98/NT } &
+\multicolumn{1}{c|}{\bf MacOS } \\
+ \hline
+\multicolumn{1}{|c|}{1 } & {st\_dev } & {Device number of filesystem } &
+{Drive number } & {vRefNum } \\
+ \hline
+\multicolumn{1}{|c|}{2 } & {st\_ino } & {Inode number } & {Always 0 } &
+{fileID/dirID } \\
+ \hline
+\multicolumn{1}{|c|}{3 } & {st\_mode } & {File mode } & {File mode } &
+{777 dirs/apps; 666 docs; 444 locked docs } \\
+ \hline
+\multicolumn{1}{|c|}{4 } & {st\_nlink } & {Number of links to the file } &
+{Number of link (only on NTFS) } & {Always 1 } \\
+ \hline
+\multicolumn{1}{|c|}{5 } & {st\_uid } & {Owner ID } & {Always 0 } &
+{Always 0 } \\
+ \hline
+\multicolumn{1}{|c|}{6 } & {st\_gid } & {Group ID } & {Always 0 } &
+{Always 0 } \\
+ \hline
+\multicolumn{1}{|c|}{7 } & {st\_rdev } & {Device ID for special files } &
+{Drive No. } & {Always 0 } \\
+ \hline
+\multicolumn{1}{|c|}{8 } & {st\_size } & {File size in bytes } & {File
+size in bytes } & {Data fork file size in bytes } \\
+ \hline
+\multicolumn{1}{|c|}{9 } & {st\_blksize } & {Preferred block size } &
+{Always 0 } & {Preferred block size } \\
+ \hline
+\multicolumn{1}{|c|}{10 } & {st\_blocks } & {Number of blocks allocated }
+& {Always 0 } & {Number of blocks allocated } \\
+ \hline
+\multicolumn{1}{|c|}{11 } & {st\_atime } & {Last access time since epoch }
+& {Last access time since epoch } & {Last access time -66 years } \\
+ \hline
+\multicolumn{1}{|c|}{12 } & {st\_mtime } & {Last modify time since epoch }
+& {Last modify time since epoch } & {Last access time -66 years } \\
+ \hline
+\multicolumn{1}{|c|}{13 } & {st\_ctime } & {Inode change time since epoch
+} & {File create time since epoch } & {File create time -66 years}
+\\ \hline
+
+\end{longtable}
+
+\section{Old Depreciated Tape Format}
+\index{Old Depreciated Tape Format}
+\index{Format!Old Depreciated Tape}
+\addcontentsline{toc}{subsection}{Old Depreciated Tape Format}
+
+The format of the Block Header (version 1.26 and earlier) is:
+
+\footnotesize
+\begin{verbatim}
+ uint32_t CheckSum; /* Block check sum */
+ uint32_t BlockSize; /* Block byte size including the header */
+ uint32_t BlockNumber; /* Block number */
+ char ID[4] = "BB01"; /* Identification and block level */
+\end{verbatim}
+\normalsize
+
+The format of the Record Header (version 1.26 or earlier) is:
+
+\footnotesize
+\begin{verbatim}
+ uint32_t VolSessionId; /* Unique ID for this session */
+ uint32_t VolSessionTime; /* Start time/date of session */
+ int32_t FileIndex; /* File index supplied by File daemon */
+ int32_t Stream; /* Stream number supplied by File daemon */
+ uint32_t DataSize; /* size of following data record in bytes */
+\end{verbatim}
+\normalsize
+
+\footnotesize
+\begin{verbatim}
+ Current Bacula Tape Format
+ 6 June 2001
+ Version BB01 is the old deprecated format.
+ A Bacula tape is composed of tape Blocks. Each block
+ has a Block header followed by the block data. Block
+ Data consists of Records. Records consist of Record
+ Headers followed by Record Data.
+ :=======================================================:
+ | |
+ | Block Header |
+ | (16 bytes version BB01) |
+ |-------------------------------------------------------|
+ | |
+ | Record Header |
+ | (20 bytes version BB01) |
+ |-------------------------------------------------------|
+ | |
+ | Record Data |
+ | |
+ |-------------------------------------------------------|
+ | |
+ | Record Header |
+ | (20 bytes version BB01) |
+ |-------------------------------------------------------|
+ | |
+ | ... |
+ Block Header: the first item in each block. The format is
+ shown below.
+ Partial Data block: occurs if the data from a previous
+ block spills over to this block (the normal case except
+ for the first block on a tape). However, this partial
+ data block is always preceded by a record header.
+ Record Header: identifies the Volume Session, the Stream
+ and the following Record Data size. See below for format.
+ Record data: arbitrary binary data.
+ Block Header Format BB01 (deprecated)
+ :=======================================================:
+ | CheckSum (uint32_t) |
+ |-------------------------------------------------------|
+ | BlockSize (uint32_t) |
+ |-------------------------------------------------------|
+ | BlockNumber (uint32_t) |
+ |-------------------------------------------------------|
+ | "BB01" (char [4]) |
+ :=======================================================:
+ BBO1: Serves to identify the block as a
+ Bacula block and also servers as a block format identifier
+ should we ever need to change the format.
+ BlockSize: is the size in bytes of the block. When reading
+ back a block, if the BlockSize does not agree with the
+ actual size read, Bacula discards the block.
+ CheckSum: a checksum for the Block.
+ BlockNumber: is the sequential block number on the tape.
+ VolSessionId: a unique sequential number that is assigned
+ by the Storage Daemon to a particular Job.
+ This number is sequential since the start
+ of execution of the daemon.
+ VolSessionTime: the time/date that the current execution
+ of the Storage Daemon started. It assures
+ that the combination of VolSessionId and
+ VolSessionTime is unique for all jobs
+ written to the tape, even if there was a
+ machine crash between two writes.
+ Record Header Format BB01 (deprecated)
+ :=======================================================:
+ | VolSessionId (uint32_t) |
+ |-------------------------------------------------------|
+ | VolSessionTime (uint32_t) |
+ |-------------------------------------------------------|
+ | FileIndex (int32_t) |
+ |-------------------------------------------------------|
+ | Stream (int32_t) |
+ |-------------------------------------------------------|
+ | DataSize (uint32_t) |
+ :=======================================================:
+ VolSessionId: a unique sequential number that is assigned
+ by the Storage Daemon to a particular Job.
+ This number is sequential since the start
+ of execution of the daemon.
+ VolSessionTime: the time/date that the current execution
+ of the Storage Daemon started. It assures
+ that the combination of VolSessionId and
+ VolSessionTime is unique for all jobs
+ written to the tape, even if there was a
+ machine crash between two writes.
+ FileIndex: a sequential file number within a job. The
+ Storage daemon enforces this index to be
+ greater than zero and sequential. Note,
+ however, that the File daemon may send
+ multiple Streams for the same FileIndex.
+ The Storage Daemon uses negative FileIndices
+ to identify Session Start and End labels
+ as well as the End of Volume labels.
+ Stream: defined by the File daemon and is intended to be
+ used to identify separate parts of the data
+ saved for each file (attributes, file data,
+ ...). The Storage Daemon has no idea of
+ what a Stream is or what it contains.
+ DataSize: the size in bytes of the binary data record
+ that follows the Session Record header.
+ The Storage Daemon has no idea of the
+ actual contents of the binary data record.
+ For standard Unix files, the data record
+ typically contains the file attributes or
+ the file data. For a sparse file
+ the first 64 bits of the data contains
+ the storage address for the data block.
+ Volume Label
+ :=======================================================:
+ | Id (32 bytes) |
+ |-------------------------------------------------------|
+ | VerNum (uint32_t) |
+ |-------------------------------------------------------|
+ | label_date (float64_t) |
+ |-------------------------------------------------------|
+ | label_time (float64_t) |
+ |-------------------------------------------------------|
+ | write_date (float64_t) |
+ |-------------------------------------------------------|
+ | write_time (float64_t) |
+ |-------------------------------------------------------|
+ | VolName (128 bytes) |
+ |-------------------------------------------------------|
+ | PrevVolName (128 bytes) |
+ |-------------------------------------------------------|
+ | PoolName (128 bytes) |
+ |-------------------------------------------------------|
+ | PoolType (128 bytes) |
+ |-------------------------------------------------------|
+ | MediaType (128 bytes) |
+ |-------------------------------------------------------|
+ | HostName (128 bytes) |
+ |-------------------------------------------------------|
+ | LabelProg (32 bytes) |
+ |-------------------------------------------------------|
+ | ProgVersion (32 bytes) |
+ |-------------------------------------------------------|
+ | ProgDate (32 bytes) |
+ |-------------------------------------------------------|
+ :=======================================================:
+
+ Id: 32 byte Bacula identifier "Bacula 1.0 immortal\n"
+ (old version also recognized:)
+ Id: 32 byte Bacula identifier "Bacula 0.9 mortal\n"
+ LabelType (Saved in the FileIndex of the Header record).
+ PRE_LABEL -1 Volume label on unwritten tape
+ VOL_LABEL -2 Volume label after tape written
+ EOM_LABEL -3 Label at EOM (not currently implemented)
+ SOS_LABEL -4 Start of Session label (format given below)
+ EOS_LABEL -5 End of Session label (format given below)
+ label_date: Julian day tape labeled
+ label_time: Julian time tape labeled
+ write_date: Julian date tape first used (data written)
+ write_time: Julian time tape first used (data written)
+ VolName: "Physical" Volume name
+ PrevVolName: The VolName of the previous tape (if this tape is
+ a continuation of the previous one).
+ PoolName: Pool Name
+ PoolType: Pool Type
+ MediaType: Media Type
+ HostName: Name of host that is first writing the tape
+ LabelProg: Name of the program that labeled the tape
+ ProgVersion: Version of the label program
+ ProgDate: Date Label program built
+ Session Label
+ :=======================================================:
+ | Id (32 bytes) |
+ |-------------------------------------------------------|
+ | VerNum (uint32_t) |
+ |-------------------------------------------------------|
+ | JobId (uint32_t) |
+ |-------------------------------------------------------|
+ | *write_date (float64_t) VerNum 10 |
+ |-------------------------------------------------------|
+ | *write_time (float64_t) VerNum 10 |
+ |-------------------------------------------------------|
+ | PoolName (128 bytes) |
+ |-------------------------------------------------------|
+ | PoolType (128 bytes) |
+ |-------------------------------------------------------|
+ | JobName (128 bytes) |
+ |-------------------------------------------------------|
+ | ClientName (128 bytes) |
+ |-------------------------------------------------------|
+ | Job (128 bytes) |
+ |-------------------------------------------------------|
+ | FileSetName (128 bytes) |
+ |-------------------------------------------------------|
+ | JobType (uint32_t) |
+ |-------------------------------------------------------|
+ | JobLevel (uint32_t) |
+ |-------------------------------------------------------|
+ | FileSetMD5 (50 bytes) VerNum 11 |
+ |-------------------------------------------------------|
+ Additional fields in End Of Session Label
+ |-------------------------------------------------------|
+ | JobFiles (uint32_t) |
+ |-------------------------------------------------------|
+ | JobBytes (uint32_t) |
+ |-------------------------------------------------------|
+ | start_block (uint32_t) |
+ |-------------------------------------------------------|
+ | end_block (uint32_t) |
+ |-------------------------------------------------------|
+ | start_file (uint32_t) |
+ |-------------------------------------------------------|
+ | end_file (uint32_t) |
+ |-------------------------------------------------------|
+ | JobErrors (uint32_t) |
+ |-------------------------------------------------------|
+ | JobStatus (uint32_t) VerNum 11 |
+ :=======================================================:
+ * => fields deprecated
+ Id: 32 byte Bacula Identifier "Bacula 1.0 immortal\n"
+ LabelType (in FileIndex field of Header):
+ EOM_LABEL -3 Label at EOM
+ SOS_LABEL -4 Start of Session label
+ EOS_LABEL -5 End of Session label
+ VerNum: 11
+ JobId: JobId
+ write_btime: Bacula time/date this tape record written
+ write_date: Julian date tape this record written - deprecated
+ write_time: Julian time tape this record written - deprecated.
+ PoolName: Pool Name
+ PoolType: Pool Type
+ MediaType: Media Type
+ ClientName: Name of File daemon or Client writing this session
+ Not used for EOM_LABEL.
+\end{verbatim}
+\normalsize
--- /dev/null
+%%
+%%
+
+\chapter{Bacula Memory Management}
+\label{_ChapterStart7}
+\index{Management!Bacula Memory}
+\index{Bacula Memory Management}
+\addcontentsline{toc}{section}{Bacula Memory Management}
+
+\section{General}
+\index{General}
+\addcontentsline{toc}{subsection}{General}
+
+This document describes the memory management routines that are used in Bacula
+and is meant to be a technical discussion for developers rather than part of
+the user manual.
+
+Since Bacula may be called upon to handle filenames of varying and more or
+less arbitrary length, special attention needs to be used in the code to
+ensure that memory buffers are sufficiently large. There are four
+possibilities for memory usage within {\bf Bacula}. Each will be described in
+turn. They are:
+
+\begin{itemize}
+\item Statically allocated memory.
+\item Dynamically allocated memory using malloc() and free().
+\item Non-pooled memory.
+\item Pooled memory.
+ \end{itemize}
+
+\subsection{Statically Allocated Memory}
+\index{Statically Allocated Memory}
+\index{Memory!Statically Allocated}
+\addcontentsline{toc}{subsubsection}{Statically Allocated Memory}
+
+Statically allocated memory is of the form:
+
+\footnotesize
+\begin{verbatim}
+char buffer[MAXSTRING];
+\end{verbatim}
+\normalsize
+
+The use of this kind of memory is discouraged except when you are 100\% sure
+that the strings to be used will be of a fixed length. One example of where
+this is appropriate is for {\bf Bacula} resource names, which are currently
+limited to 127 characters (MAX\_NAME\_LENGTH). Although this maximum size may
+change, particularly to accommodate Unicode, it will remain a relatively small
+value.
+
+\subsection{Dynamically Allocated Memory}
+\index{Dynamically Allocated Memory}
+\index{Memory!Dynamically Allocated}
+\addcontentsline{toc}{subsubsection}{Dynamically Allocated Memory}
+
+Dynamically allocated memory is obtained using the standard malloc() routines.
+As in:
+
+\footnotesize
+\begin{verbatim}
+char *buf;
+buf = malloc(256);
+\end{verbatim}
+\normalsize
+
+This kind of memory can be released with:
+
+\footnotesize
+\begin{verbatim}
+free(buf);
+\end{verbatim}
+\normalsize
+
+It is recommended to use this kind of memory only when you are sure that you
+know the memory size needed and the memory will be used for short periods of
+time -- that is it would not be appropriate to use statically allocated
+memory. An example might be to obtain a large memory buffer for reading and
+writing files. When {\bf SmartAlloc} is enabled, the memory obtained by
+malloc() will automatically be checked for buffer overwrite (overflow) during
+the free() call, and all malloc'ed memory that is not released prior to
+termination of the program will be reported as Orphaned memory.
+
+\subsection{Pooled and Non-pooled Memory}
+\index{Memory!Pooled and Non-pooled}
+\index{Pooled and Non-pooled Memory}
+\addcontentsline{toc}{subsubsection}{Pooled and Non-pooled Memory}
+
+In order to facility the handling of arbitrary length filenames and to
+efficiently handle a high volume of dynamic memory usage, we have implemented
+routines between the C code and the malloc routines. The first is called
+``Pooled'' memory, and is memory, which once allocated and then released, is
+not returned to the system memory pool, but rather retained in a Bacula memory
+pool. The next request to acquire pooled memory will return any free memory
+block. In addition, each memory block has its current size associated with the
+block allowing for easy checking if the buffer is of sufficient size. This
+kind of memory would normally be used in high volume situations (lots of
+malloc()s and free()s) where the buffer length may have to frequently change
+to adapt to varying filename lengths.
+
+The non-pooled memory is handled by routines similar to those used for pooled
+memory, allowing for easy size checking. However, non-pooled memory is
+returned to the system rather than being saved in the Bacula pool. This kind
+of memory would normally be used in low volume situations (few malloc()s and
+free()s), but where the size of the buffer might have to be adjusted
+frequently.
+
+\paragraph*{Types of Memory Pool:}
+
+Currently there are three memory pool types:
+
+\begin{itemize}
+\item PM\_NOPOOL -- non-pooled memory.
+\item PM\_FNAME -- a filename pool.
+\item PM\_MESSAGE -- a message buffer pool.
+\item PM\_EMSG -- error message buffer pool.
+ \end{itemize}
+
+\paragraph*{Getting Memory:}
+
+To get memory, one uses:
+
+\footnotesize
+\begin{verbatim}
+void *get_pool_memory(pool);
+\end{verbatim}
+\normalsize
+
+where {\bf pool} is one of the above mentioned pool names. The size of the
+memory returned will be determined by the system to be most appropriate for
+the application.
+
+If you wish non-pooled memory, you may alternatively call:
+
+\footnotesize
+\begin{verbatim}
+void *get_memory(size_t size);
+\end{verbatim}
+\normalsize
+
+The buffer length will be set to the size specified, and it will be assigned
+to the PM\_NOPOOL pool (no pooling).
+
+\paragraph*{Releasing Memory:}
+
+To free memory acquired by either of the above two calls, use:
+
+\footnotesize
+\begin{verbatim}
+void free_pool_memory(void *buffer);
+\end{verbatim}
+\normalsize
+
+where buffer is the memory buffer returned when the memory was acquired. If
+the memory was originally allocated as type PM\_NOPOOL, it will be released to
+the system, otherwise, it will be placed on the appropriate Bacula memory pool
+free chain to be used in a subsequent call for memory from that pool.
+
+\paragraph*{Determining the Memory Size:}
+
+To determine the memory buffer size, use:
+
+\footnotesize
+\begin{verbatim}
+size_t sizeof_pool_memory(void *buffer);
+\end{verbatim}
+\normalsize
+
+\paragraph*{Resizing Pool Memory:}
+
+To resize pool memory, use:
+
+\footnotesize
+\begin{verbatim}
+void *realloc_pool_memory(void *buffer);
+\end{verbatim}
+\normalsize
+
+The buffer will be reallocated, and the contents of the original buffer will
+be preserved, but the address of the buffer may change.
+
+\paragraph*{Automatic Size Adjustment:}
+
+To have the system check and if necessary adjust the size of your pooled
+memory buffer, use:
+
+\footnotesize
+\begin{verbatim}
+void *check_pool_memory_size(void *buffer, size_t new-size);
+\end{verbatim}
+\normalsize
+
+where {\bf new-size} is the buffer length needed. Note, if the buffer is
+already equal to or larger than {\bf new-size} no buffer size change will
+occur. However, if a buffer size change is needed, the original contents of
+the buffer will be preserved, but the buffer address may change. Many of the
+low level Bacula subroutines expect to be passed a pool memory buffer and use
+this call to ensure the buffer they use is sufficiently large.
+
+\paragraph*{Releasing All Pooled Memory:}
+
+In order to avoid orphaned buffer error messages when terminating the program,
+use:
+
+\footnotesize
+\begin{verbatim}
+void close_memory_pool();
+\end{verbatim}
+\normalsize
+
+to free all unused memory retained in the Bacula memory pool. Note, any memory
+not returned to the pool via free\_pool\_memory() will not be released by this
+call.
+
+\paragraph*{Pooled Memory Statistics:}
+
+For debugging purposes and performance tuning, the following call will print
+the current memory pool statistics:
+
+\footnotesize
+\begin{verbatim}
+void print_memory_pool_stats();
+\end{verbatim}
+\normalsize
+
+an example output is:
+
+\footnotesize
+\begin{verbatim}
+Pool Maxsize Maxused Inuse
+ 0 256 0 0
+ 1 256 1 0
+ 2 256 1 0
+\end{verbatim}
+\normalsize
--- /dev/null
+%%
+%%
+
+\chapter{TCP/IP Network Protocol}
+\label{_ChapterStart5}
+\index{TCP/IP Network Protocol}
+\index{Protocol!TCP/IP Network}
+\addcontentsline{toc}{section}{TCP/IP Network Protocol}
+
+\section{General}
+\index{General}
+\addcontentsline{toc}{subsection}{General}
+
+This document describes the TCP/IP protocol used by Bacula to communicate
+between the various daemons and services. The definitive definition of the
+protocol can be found in src/lib/bsock.h, src/lib/bnet.c and
+src/lib/bnet\_server.c.
+
+Bacula's network protocol is basically a ``packet oriented'' protocol built on
+a standard TCP/IP streams. At the lowest level all packet transfers are done
+with read() and write() requests on system sockets. Pipes are not used as they
+are considered unreliable for large serial data transfers between various
+hosts.
+
+Using the routines described below (bnet\_open, bnet\_write, bnet\_recv, and
+bnet\_close) guarantees that the number of bytes you write into the socket
+will be received as a single record on the other end regardless of how many
+low level write() and read() calls are needed. All data transferred are
+considered to be binary data.
+
+\section{bnet and Threads}
+\index{Threads!bnet and}
+\index{Bnet and Threads}
+\addcontentsline{toc}{subsection}{bnet and Threads}
+
+These bnet routines work fine in a threaded environment. However, they assume
+that there is only one reader or writer on the socket at any time. It is
+highly recommended that only a single thread access any BSOCK packet. The
+exception to this rule is when the socket is first opened and it is waiting
+for a job to start. The wait in the Storage daemon is done in one thread and
+then passed to another thread for subsequent handling.
+
+If you envision having two threads using the same BSOCK, think twice, then you
+must implement some locking mechanism. However, it probably would not be
+appropriate to put locks inside the bnet subroutines for efficiency reasons.
+
+\section{bnet\_open}
+\index{Bnet\_open}
+\addcontentsline{toc}{subsection}{bnet\_open}
+
+To establish a connection to a server, use the subroutine:
+
+BSOCK *bnet\_open(void *jcr, char *host, char *service, int port, int *fatal)
+bnet\_open(), if successful, returns the Bacula sock descriptor pointer to be
+used in subsequent bnet\_send() and bnet\_read() requests. If not successful,
+bnet\_open() returns a NULL. If fatal is set on return, it means that a fatal
+error occurred and that you should not repeatedly call bnet\_open(). Any error
+message will generally be sent to the JCR.
+
+\section{bnet\_send}
+\index{Bnet\_send}
+\addcontentsline{toc}{subsection}{bnet\_send}
+
+To send a packet, one uses the subroutine:
+
+int bnet\_send(BSOCK *sock) This routine is equivalent to a write() except
+that it handles the low level details. The data to be sent is expected to be
+in sock-\gt{}msg and be sock-\gt{}msglen bytes. To send a packet, bnet\_send()
+first writes four bytes in network byte order than indicate the size of the
+following data packet. It returns:
+
+\footnotesize
+\begin{verbatim}
+ Returns 0 on failure
+ Returns 1 on success
+\end{verbatim}
+\normalsize
+
+In the case of a failure, an error message will be sent to the JCR contained
+within the bsock packet.
+
+\section{bnet\_fsend}
+\index{Bnet\_fsend}
+\addcontentsline{toc}{subsection}{bnet\_fsend}
+
+This form uses:
+
+int bnet\_fsend(BSOCK *sock, char *format, ...) and it allows you to send a
+formatted messages somewhat like fprintf(). The return status is the same as
+bnet\_send.
+
+\section{Additional Error information}
+\index{Information!Additional Error}
+\index{Additional Error information}
+\addcontentsline{toc}{subsection}{Additional Error information}
+
+Fro additional error information, you can call {\bf is\_bnet\_error(BSOCK
+*bsock)} which will return 0 if there is no error or non-zero if there is an
+error on the last transmission. The {\bf is\_bnet\_stop(BSOCK *bsock)}
+function will return 0 if there no errors and you can continue sending. It
+will return non-zero if there are errors or the line is closed (no more
+transmissions should be sent).
+
+\section{bnet\_recv}
+\index{Bnet\_recv}
+\addcontentsline{toc}{subsection}{bnet\_recv}
+
+To read a packet, one uses the subroutine:
+
+int bnet\_recv(BSOCK *sock) This routine is similar to a read() except that it
+handles the low level details. bnet\_read() first reads packet length that
+follows as four bytes in network byte order. The data is read into
+sock-\gt{}msg and is sock-\gt{}msglen bytes. If the sock-\gt{}msg is not large
+enough, bnet\_recv() realloc() the buffer. It will return an error (-2) if
+maxbytes is less than the record size sent. It returns:
+
+\footnotesize
+\begin{verbatim}
+ * Returns number of bytes read
+ * Returns 0 on end of file
+ * Returns -1 on hard end of file (i.e. network connection close)
+ * Returns -2 on error
+\end{verbatim}
+\normalsize
+
+It should be noted that bnet\_recv() is a blocking read.
+
+\section{bnet\_sig}
+\index{Bnet\_sig}
+\addcontentsline{toc}{subsection}{bnet\_sig}
+
+To send a ``signal'' from one daemon to another, one uses the subroutine:
+
+int bnet\_sig(BSOCK *sock, SIGNAL) where SIGNAL is one of the following:
+
+\begin{enumerate}
+\item BNET\_EOF - deprecated use BNET\_EOD
+\item BNET\_EOD - End of data stream, new data may follow
+\item BNET\_EOD\_POLL - End of data and poll all in one
+\item BNET\_STATUS - Request full status
+\item BNET\_TERMINATE - Conversation terminated, doing close()
+\item BNET\_POLL - Poll request, I'm hanging on a read
+\item BNET\_HEARTBEAT - Heartbeat Response requested
+\item BNET\_HB\_RESPONSE - Only response permitted to HB
+\item BNET\_PROMPT - Prompt for UA
+ \end{enumerate}
+
+\section{bnet\_strerror}
+\index{Bnet\_strerror}
+\addcontentsline{toc}{subsection}{bnet\_strerror}
+
+Returns a formated string corresponding to the last error that occurred.
+
+\section{bnet\_close}
+\index{Bnet\_close}
+\addcontentsline{toc}{subsection}{bnet\_close}
+
+The connection with the server remains open until closed by the subroutine:
+
+void bnet\_close(BSOCK *sock)
+
+\section{Becoming a Server}
+\index{Server!Becoming a}
+\index{Becoming a Server}
+\addcontentsline{toc}{subsection}{Becoming a Server}
+
+The bnet\_open() and bnet\_close() routines described above are used on the
+client side to establish a connection and terminate a connection with the
+server. To become a server (i.e. wait for a connection from a client), use the
+routine {\bf bnet\_thread\_server}. The calling sequence is a bit complicated,
+please refer to the code in bnet\_server.c and the code at the beginning of
+each daemon as examples of how to call it.
+
+\section{Higher Level Conventions}
+\index{Conventions!Higher Level}
+\index{Higher Level Conventions}
+\addcontentsline{toc}{subsection}{Higher Level Conventions}
+
+Within Bacula, we have established the convention that any time a single
+record is passed, it is sent with bnet\_send() and read with bnet\_recv().
+Thus the normal exchange between the server (S) and the client (C) are:
+
+\footnotesize
+\begin{verbatim}
+S: wait for connection C: attempt connection
+S: accept connection C: bnet_send() send request
+S: bnet_recv() wait for request
+S: act on request
+S: bnet_send() send ack C: bnet_recv() wait for ack
+\end{verbatim}
+\normalsize
+
+Thus a single command is sent, acted upon by the server, and then
+acknowledged.
+
+In certain cases, such as the transfer of the data for a file, all the
+information or data cannot be sent in a single packet. In this case, the
+convention is that the client will send a command to the server, who knows
+that more than one packet will be returned. In this case, the server will
+enter a loop:
+
+\footnotesize
+\begin{verbatim}
+while ((n=bnet_recv(bsock)) > 0) {
+ act on request
+}
+if (n < 0)
+ error
+\end{verbatim}
+\normalsize
+
+The client will perform the following:
+
+\footnotesize
+\begin{verbatim}
+bnet_send(bsock);
+bnet_send(bsock);
+...
+bnet_sig(bsock, BNET_EOD);
+\end{verbatim}
+\normalsize
+
+Thus the client will send multiple packets and signal to the server when all
+the packets have been sent by sending a zero length record.
--- /dev/null
+%%
+%%
+
+\chapter{Platform Support}
+\label{_PlatformChapter}
+\index{Support!Platform}
+\index{Platform Support}
+\addcontentsline{toc}{section}{Platform Support}
+
+\section{General}
+\index{General }
+\addcontentsline{toc}{subsection}{General}
+
+This chapter describes the requirements for having a
+supported platform (Operating System). In general, Bacula is
+quite portable. It supports 32 and 64 bit architectures as well
+as bigendian and littleendian machines. For full
+support, the platform (Operating System) must implement POSIX Unix
+system calls. However, for File daemon support only, a small
+compatibility library can be written to support almost any
+architecture.
+
+Currently Linux, FreeBSD, and Solaris are fully supported
+platforms, which means that the code has been tested on those
+machines and passes a full set of regression tests.
+
+In addition, the Windows File daemon is supported on most versions
+of Windows, and finally, there are a number of other platforms
+where the File daemon (client) is known to run: NetBSD, OpenBSD,
+Mac OSX, SGI, ...
+
+\section{Requirements to become a Supported Platform}
+\index{Requirements!Platform}
+\index{Platform Requirements}
+\addcontentsline{toc}{subsection}{Platform Requirements}
+
+As mentioned above, in order to become a fully supported platform, it
+must support POSIX Unix system calls. In addition, the following
+requirements must be met:
+
+\begin{itemize}
+\item The principal developer (currently Kern) must have
+ non-root ssh access to a test machine running the platform.
+\item The ideal requirements and minimum requirements
+ for this machine are given below.
+\item There must be a defined platform champion who is normally
+ a system administrator for the machine that is available. This
+ person need not be a developer/programmer but must be familiar
+ with system administration of the platform.
+\item There must be at least one person designated who will
+ run regression tests prior to each release. Releases occur
+ approximately once every 6 months, but can be more frequent.
+ It takes at most a day's effort to setup the regression scripts
+ in the beginning, and after that, they can either be run daily
+ or on demand before a release. Running the regression scripts
+ involves only one or two command line commands and is fully
+ automated.
+\item Ideally there are one or more persons who will package
+ each Bacula release.
+\item Ideally there are one or more developers who can respond to
+ and fix platform specific bugs.
+\end{itemize}
+
+Ideal requirements for a test machine:
+\begin{itemize}
+\item The principal developer will have non-root ssh access to
+ the test machine at all times.
+\item The pricipal developer will have a root password.
+\item The test machine will provide approximately 200 MB of
+ disk space for continual use.
+\item The test machine will have approximately 500 MB of free
+ disk space for temporary use.
+\item The test machine will run the most common version of the OS.
+\item The test machine will have an autochanger of DDS-4 technology
+ or later having two or more tapes.
+\item The test machine will have MySQL and/or PostgreSQL database
+ access for account "bacula" available.
+\item The test machine will have sftp access.
+\item The test machine will provide an smtp server.
+\end{itemize}
+
+Minimum requirements for a test machine:
+\begin{itemize}
+\item The principal developer will have non-root ssh access to
+ the test machine when requested approximately once a month.
+\item The pricipal developer not have root access.
+\item The test machine will provide approximately 80 MB of
+ disk space for continual use.
+\item The test machine will have approximately 300 MB of free
+ disk space for temporary use.
+\item The test machine will run the the OS.
+\item The test machine will have a tape drive of DDS-4 technology
+ or later that can be scheduled for access.
+\item The test machine will not have MySQL and/or PostgreSQL database
+ access.
+\item The test machine will have no sftp access.
+\item The test machine will provide no email access.
+\end{itemize}
+
+Bare bones test machine requirements:
+\begin{itemize}
+\item The test machine is available only to a designated
+ test person (your own machine).
+\item The designated test person runs the regession
+ tests on demand.
+\item The test machine has a tape drive available.
+\end{itemize}
--- /dev/null
+%%
+%%
+
+\chapter{Bacula Porting Notes}
+\label{_ChapterStart1}
+\index{Notes!Bacula Porting}
+\index{Bacula Porting Notes}
+\addcontentsline{toc}{section}{Bacula Porting Notes}
+
+This document is intended mostly for developers who wish to port Bacula to a
+system that is not {\bf officially} supported.
+
+It is hoped that Bacula clients will eventually run on every imaginable system
+that needs backing up (perhaps even a Palm). It is also hoped that the Bacula
+Directory and Storage daemons will run on every system capable of supporting
+them.
+
+\section{Porting Requirements}
+\index{Requirements!Porting}
+\index{Porting Requirements}
+\addcontentsline{toc}{section}{Porting Requirements}
+
+In General, the following holds true:
+
+\begin{itemize}
+\item {\bf Bacula} has been compiled and run on Linux RedHat, FreeBSD, and
+ Solaris systems.
+\item In addition, clients exist on Win32, and Irix
+\item It requires GNU C++ to compile. You can try with other compilers, but
+ you are on your own. The Irix client is built with the Irix complier, but, in
+ general, you will need GNU.
+\item Your compiler must provide support for 64 bit signed and unsigned
+ integers.
+\item You will need a recent copy of the {\bf autoconf} tools loaded on your
+ system (version 2.13 or later). The {\bf autoconf} tools are used to build
+ the configuration program, but are not part of the Bacula source
+distribution.
+\item There are certain third party packages that Bacula needs. Except for
+ MySQL, they can all be found in the {\bf depkgs} and {\bf depkgs1} releases.
+\item To build the Win32 binaries, we use Microsoft VC++ standard
+ 2003. Please see the instructions in
+ bacula-source/src/win32/README.win32 for more details. If you
+ want to use VC++ Express, please see README.vc8. Our build is
+ done under the most recent version of Cygwin, but Cygwin is
+ not used in the Bacula binaries that are produced.
+ Unfortunately, we do not have the resources to help you build
+ your own version of the Win32 FD, so you are pretty much on
+ your own. You can ask the bacula-devel list for help, but
+ please don't expect much.
+\item {\bf Bacula} requires a good implementation of pthreads to work.
+\item The source code has been written with portability in mind and is mostly
+ POSIX compatible. Thus porting to any POSIX compatible operating system
+ should be relatively easy.
+\end{itemize}
+
+\section{Steps to Take for Porting}
+\index{Porting!Steps to Take for}
+\index{Steps to Take for Porting}
+\addcontentsline{toc}{section}{Steps to Take for Porting}
+
+\begin{itemize}
+\item The first step is to ensure that you have version 2.13 or later of the
+ {\bf autoconf} tools loaded. You can skip this step, but making changes to
+ the configuration program will be difficult or impossible.
+\item The run a {\bf ./configure} command in the main source directory and
+ examine the output. It should look something like the following:
+
+\footnotesize
+\begin{verbatim}
+Configuration on Mon Oct 28 11:42:27 CET 2002:
+ Host: i686-pc-linux-gnu -- redhat 7.3
+ Bacula version: 1.27 (26 October 2002)
+ Source code location: .
+ Install binaries: /sbin
+ Install config files: /etc/bacula
+ C Compiler: gcc
+ C++ Compiler: c++
+ Compiler flags: -g -O2
+ Linker flags:
+ Libraries: -lpthread
+ Statically Linked Tools: no
+ Database found: no
+ Database type: Internal
+ Database lib:
+ Job Output Email: root@localhost
+ Traceback Email: root@localhost
+ SMTP Host Address: localhost
+ Director Port 9101
+ File daemon Port 9102
+ Storage daemon Port 9103
+ Working directory /etc/bacula/working
+ SQL binaries Directory
+ Large file support: yes
+ readline support: yes
+ cweb support: yes /home/kern/bacula/depkgs/cweb
+ TCP Wrappers support: no
+ ZLIB support: yes
+ enable-smartalloc: yes
+ enable-gnome: no
+ gmp support: yes
+\end{verbatim}
+\normalsize
+
+The details depend on your system. The first thing to check is that it
+properly identified your host on the {\bf Host:} line. The first part (added
+in version 1.27) is the GNU four part identification of your system. The part
+after the -- is your system and the system version. Generally, if your system
+is not yet supported, you must correct these.
+\item If the {\bf ./configure} does not function properly, you must determine
+ the cause and fix it. Generally, it will be because some required system
+ routine is not available on your machine.
+\item To correct problems with detection of your system type or with routines
+ and libraries, you must edit the file {\bf
+ \lt{}bacula-src\gt{}/autoconf/configure.in}. This is the ``source'' from
+which {\bf configure} is built. In general, most of the changes for your
+system will be made in {\bf autoconf/aclocal.m4} in the routine {\bf
+BA\_CHECK\_OPSYS} or in the routine {\bf BA\_CHECK\_OPSYS\_DISTNAME}. I have
+already added the necessary code for most systems, but if yours shows up as
+{\bf unknown} you will need to make changes. Then as mentioned above, you
+will need to set a number of system dependent items in {\bf configure.in} in
+the {\bf case} statement at approximately line 1050 (depending on the Bacula
+release).
+\item The items to in the case statement that corresponds to your system are
+ the following:
+
+\begin{itemize}
+\item DISTVER -- set to the version of your operating system. Typically some
+ form of {\bf uname} obtains it.
+\item TAPEDRIVE -- the default tape drive. Not too important as the user can
+ set it as an option.
+\item PSCMD -- set to the {\bf ps} command that will provide the PID in the
+ first field and the program name in the second field. If this is not set
+ properly, the {\bf bacula stop} script will most likely not be able to stop
+Bacula in all cases.
+\item hostname -- command to return the base host name (non-qualified) of
+ your system. This is generally the machine name. Not too important as the
+ user can correct this in his configuration file.
+\item CFLAGS -- set any special compiler flags needed. Many systems need a
+ special flag to make pthreads work. See cygwin for an example.
+\item LDFLAGS -- set any special loader flags. See cygwin for an example.
+\item PTHREAD\_LIB -- set for any special pthreads flags needed during
+ linking. See freebsd as an example.
+\item lld -- set so that a ``long long int'' will be properly edited in a
+ printf() call.
+\item llu -- set so that a ``long long unsigned'' will be properly edited in
+ a printf() call.
+\item PFILES -- set to add any files that you may define is your platform
+ subdirectory. These files are used for installation of automatic system
+ startup of Bacula daemons.
+\end{itemize}
+
+\item To rebuild a new version of {\bf configure} from a changed {\bf
+ autoconf/configure.in} you enter {\bf make configure} in the top level Bacula
+ source directory. You must have done a ./configure prior to trying to rebuild
+ the configure script or it will get into an infinite loop.
+\item If the {\bf make configure} gets into an infinite loop, ctl-c it, then
+ do {\bf ./configure} (no options are necessary) and retry the {\bf make
+ configure}, which should now work.
+\item To rebuild {\bf configure} you will need to have {\bf autoconf} version
+ 2.57-3 or higher loaded. Older versions of autoconf will complain about
+ unknown or bad options, and won't work.
+\item After you have a working {\bf configure} script, you may need to make a
+ few system dependent changes to the way Bacula works. Generally, these are
+ done in {\bf src/baconfig.h}. You can find a few examples of system dependent
+changes toward the end of this file. For example, on Irix systems, there is
+no definition for {\bf socklen\_t}, so it is made in this file. If your
+system has structure alignment requirements, check the definition of BALIGN
+in this file. Currently, all Bacula allocated memory is aligned on a {\bf
+double} boundary.
+\item If you are having problems with Bacula's type definitions, you might
+ look at {\bf src/bc\_types.h} where all the types such as {\bf uint32\_t},
+ {\bf uint64\_t}, etc. that Bacula uses are defined.
+\end{itemize}
--- /dev/null
+/*
+ * html2latex
+ */
+
+available {
+ sun4_sunos.4
+ sun4_solaris.2
+ rs_aix.3
+ rs_aix.4
+ sgi_irix
+}
+
+description {
+ From Jeffrey Schaefer, Geometry Center. Translates HTML document to LaTeX
+}
+
+install {
+ bin/html2latex /afs/rpi.edu/dept/acs/rpinfo/filters/GChtml2latex/html2latex
+ bin/html2latex.tag /afs/rpi.edu/dept/acs/rpinfo/filters/GChtml2latex/html2latex.tag
+ bin/html2latex-local.tag /afs/rpi.edu/dept/acs/rpinfo/filters/GChtml2latex/html2latex-local.tag
+ bin/webtex2latex.tag /afs/rpi.edu/dept/acs/rpinfo/filters/GChtml2latex/webtex2latex.tag
+ man/man1/html2latex.1 /afs/rpi.edu/dept/acs/rpinfo/filters/GChtml2latex/html2latex.1
+}
--- /dev/null
+%%
+%%
+
+\addcontentsline{lof}{figure}{Smart Memory Allocation with Orphaned Buffer
+Detection}
+\includegraphics{./smartall.eps}
+
+\chapter{Smart Memory Allocation}
+\label{_ChapterStart4}
+\index{Detection!Smart Memory Allocation With Orphaned Buffer }
+\index{Smart Memory Allocation With Orphaned Buffer Detection }
+\addcontentsline{toc}{section}{Smart Memory Allocation With Orphaned Buffer
+Detection}
+
+Few things are as embarrassing as a program that leaks, yet few errors are so
+easy to commit or as difficult to track down in a large, complicated program
+as failure to release allocated memory. SMARTALLOC replaces the standard C
+library memory allocation functions with versions which keep track of buffer
+allocations and releases and report all orphaned buffers at the end of program
+execution. By including this package in your program during development and
+testing, you can identify code that loses buffers right when it's added and
+most easily fixed, rather than as part of a crisis debugging push when the
+problem is identified much later in the testing cycle (or even worse, when the
+code is in the hands of a customer). When program testing is complete, simply
+recompiling with different flags removes SMARTALLOC from your program,
+permitting it to run without speed or storage penalties.
+
+In addition to detecting orphaned buffers, SMARTALLOC also helps to find other
+common problems in management of dynamic storage including storing before the
+start or beyond the end of an allocated buffer, referencing data through a
+pointer to a previously released buffer, attempting to release a buffer twice
+or releasing storage not obtained from the allocator, and assuming the initial
+contents of storage allocated by functions that do not guarantee a known
+value. SMARTALLOC's checking does not usually add a large amount of overhead
+to a program (except for programs which use {\tt realloc()} extensively; see
+below). SMARTALLOC focuses on proper storage management rather than internal
+consistency of the heap as checked by the malloc\_debug facility available on
+some systems. SMARTALLOC does not conflict with malloc\_debug and both may be
+used together, if you wish. SMARTALLOC makes no assumptions regarding the
+internal structure of the heap and thus should be compatible with any C
+language implementation of the standard memory allocation functions.
+
+\subsection{ Installing SMARTALLOC}
+\index{SMARTALLOC!Installing }
+\index{Installing SMARTALLOC }
+\addcontentsline{toc}{subsection}{Installing SMARTALLOC}
+
+SMARTALLOC is provided as a Zipped archive,
+\elink{smartall.zip}{http://www.fourmilab.ch/smartall/smartall.zip}; see the
+download instructions below.
+
+To install SMARTALLOC in your program, simply add the statement:
+
+to every C program file which calls any of the memory allocation functions
+({\tt malloc}, {\tt calloc}, {\tt free}, etc.). SMARTALLOC must be used for
+all memory allocation with a program, so include file for your entire program,
+if you have such a thing. Next, define the symbol SMARTALLOC in the
+compilation before the inclusion of smartall.h. I usually do this by having my
+Makefile add the ``{\tt -DSMARTALLOC}'' option to the C compiler for
+non-production builds. You can define the symbol manually, if you prefer, by
+adding the statement:
+
+{\tt \#define SMARTALLOC}
+
+At the point where your program is all done and ready to relinquish control to
+the operating system, add the call:
+
+{\tt \ \ \ \ \ \ \ \ sm\_dump(}{\it datadump}{\tt );}
+
+where {\it datadump} specifies whether the contents of orphaned buffers are to
+be dumped in addition printing to their size and place of allocation. The data
+are dumped only if {\it datadump} is nonzero, so most programs will normally
+use ``{\tt sm\_dump(0);}''. If a mysterious orphaned buffer appears that can't
+be identified from the information this prints about it, replace the statement
+with ``{\tt sm\_dump(1)};''. Usually the dump of the buffer's data will
+furnish the additional clues you need to excavate and extirpate the elusive
+error that left the buffer allocated.
+
+Finally, add the files ``smartall.h'' and ``smartall.c'' from this release to
+your source directory, make dependencies, and linker input. You needn't make
+inclusion of smartall.c in your link optional; if compiled with SMARTALLOC not
+defined it generates no code, so you may always include it knowing it will
+waste no storage in production builds. Now when you run your program, if it
+leaves any buffers around when it's done, each will be reported by {\tt
+sm\_dump()} on stderr as follows:
+
+\footnotesize
+\begin{verbatim}
+Orphaned buffer: 120 bytes allocated at line 50 of gutshot.c
+\end{verbatim}
+\normalsize
+
+\subsection{ Squelching a SMARTALLOC}
+\index{SMARTALLOC!Squelching a }
+\index{Squelching a SMARTALLOC }
+\addcontentsline{toc}{subsection}{Squelching a SMARTALLOC}
+
+Usually, when you first install SMARTALLOC in an existing program you'll find
+it nattering about lots of orphaned buffers. Some of these turn out to be
+legitimate errors, but some are storage allocated during program
+initialisation that, while dynamically allocated, is logically static storage
+not intended to be released. Of course, you can get rid of the complaints
+about these buffers by adding code to release them, but by doing so you're
+adding unnecessary complexity and code size to your program just to silence
+the nattering of a SMARTALLOC, so an escape hatch is provided to eliminate the
+need to release these buffers.
+
+Normally all storage allocated with the functions {\tt malloc()}, {\tt
+calloc()}, and {\tt realloc()} is monitored by SMARTALLOC. If you make the
+function call:
+
+\footnotesize
+\begin{verbatim}
+ sm_static(1);
+\end{verbatim}
+\normalsize
+
+you declare that subsequent storage allocated by {\tt malloc()}, {\tt
+calloc()}, and {\tt realloc()} should not be considered orphaned if found to
+be allocated when {\tt sm\_dump()} is called. I use a call on ``{\tt
+sm\_static(1);}'' before I allocate things like program configuration tables
+so I don't have to add code to release them at end of program time. After
+allocating unmonitored data this way, be sure to add a call to:
+
+\footnotesize
+\begin{verbatim}
+ sm_static(0);
+\end{verbatim}
+\normalsize
+
+to resume normal monitoring of buffer allocations. Buffers allocated while
+{\tt sm\_static(1}) is in effect are not checked for having been orphaned but
+all the other safeguards provided by SMARTALLOC remain in effect. You may
+release such buffers, if you like; but you don't have to.
+
+\subsection{ Living with Libraries}
+\index{Libraries!Living with }
+\index{Living with Libraries }
+\addcontentsline{toc}{subsection}{Living with Libraries}
+
+Some library functions for which source code is unavailable may gratuitously
+allocate and return buffers that contain their results, or require you to pass
+them buffers which they subsequently release. If you have source code for the
+library, by far the best approach is to simply install SMARTALLOC in it,
+particularly since this kind of ill-structured dynamic storage management is
+the source of so many storage leaks. Without source code, however, there's no
+option but to provide a way to bypass SMARTALLOC for the buffers the library
+allocates and/or releases with the standard system functions.
+
+For each function {\it xxx} redefined by SMARTALLOC, a corresponding routine
+named ``{\tt actually}{\it xxx}'' is furnished which provides direct access to
+the underlying system function, as follows:
+
+\begin{quote}
+
+\begin{longtable}{ll}
+\multicolumn{1}{l }{\bf Standard function } & \multicolumn{1}{l }{\bf Direct
+access function } \\
+{{\tt malloc(}{\it size}{\tt )} } & {{\tt actuallymalloc(}{\it size}{\tt )}
+} \\
+{{\tt calloc(}{\it nelem}{\tt ,} {\it elsize}{\tt )} } & {{\tt
+actuallycalloc(}{\it nelem}, {\it elsize}{\tt )} } \\
+{{\tt realloc(}{\it ptr}{\tt ,} {\it size}{\tt )} } & {{\tt
+actuallyrealloc(}{\it ptr}, {\it size}{\tt )} } \\
+{{\tt free(}{\it ptr}{\tt )} } & {{\tt actuallyfree(}{\it ptr}{\tt )} }
+
+\end{longtable}
+
+\end{quote}
+
+For example, suppose there exists a system library function named ``{\tt
+getimage()}'' which reads a raster image file and returns the address of a
+buffer containing it. Since the library routine allocates the image directly
+with {\tt malloc()}, you can't use SMARTALLOC's {\tt free()}, as that call
+expects information placed in the buffer by SMARTALLOC's special version of
+{\tt malloc()}, and hence would report an error. To release the buffer you
+should call {\tt actuallyfree()}, as in this code fragment:
+
+\footnotesize
+\begin{verbatim}
+ struct image *ibuf = getimage("ratpack.img");
+ display_on_screen(ibuf);
+ actuallyfree(ibuf);
+\end{verbatim}
+\normalsize
+
+Conversely, suppose we are to call a library function, ``{\tt putimage()}'',
+which writes an image buffer into a file and then releases the buffer with
+{\tt free()}. Since the system {\tt free()} is being called, we can't pass a
+buffer allocated by SMARTALLOC's allocation routines, as it contains special
+information that the system {\tt free()} doesn't expect to be there. The
+following code uses {\tt actuallymalloc()} to obtain the buffer passed to such
+a routine.
+
+\footnotesize
+\begin{verbatim}
+ struct image *obuf =
+ (struct image *) actuallymalloc(sizeof(struct image));
+ dump_screen_to_image(obuf);
+ putimage("scrdump.img", obuf); /* putimage() releases obuf */
+\end{verbatim}
+\normalsize
+
+It's unlikely you'll need any of the ``actually'' calls except under very odd
+circumstances (in four products and three years, I've only needed them once),
+but they're there for the rare occasions that demand them. Don't use them to
+subvert the error checking of SMARTALLOC; if you want to disable orphaned
+buffer detection, use the {\tt sm\_static(1)} mechanism described above. That
+way you don't forfeit all the other advantages of SMARTALLOC as you do when
+using {\tt actuallymalloc()} and {\tt actuallyfree()}.
+
+\subsection{ SMARTALLOC Details}
+\index{SMARTALLOC Details }
+\index{Details!SMARTALLOC }
+\addcontentsline{toc}{subsection}{SMARTALLOC Details}
+
+When you include ``smartall.h'' and define SMARTALLOC, the following standard
+system library functions are redefined with the \#define mechanism to call
+corresponding functions within smartall.c instead. (For details of the
+redefinitions, please refer to smartall.h.)
+
+\footnotesize
+\begin{verbatim}
+ void *malloc(size_t size)
+ void *calloc(size_t nelem, size_t elsize)
+ void *realloc(void *ptr, size_t size)
+ void free(void *ptr)
+ void cfree(void *ptr)
+\end{verbatim}
+\normalsize
+
+{\tt cfree()} is a historical artifact identical to {\tt free()}.
+
+In addition to allocating storage in the same way as the standard library
+functions, the SMARTALLOC versions expand the buffers they allocate to include
+information that identifies where each buffer was allocated and to chain all
+allocated buffers together. When a buffer is released, it is removed from the
+allocated buffer chain. A call on {\tt sm\_dump()} is able, by scanning the
+chain of allocated buffers, to find all orphaned buffers. Buffers allocated
+while {\tt sm\_static(1)} is in effect are specially flagged so that, despite
+appearing on the allocated buffer chain, {\tt sm\_dump()} will not deem them
+orphans.
+
+When a buffer is allocated by {\tt malloc()} or expanded with {\tt realloc()},
+all bytes of newly allocated storage are set to the hexadecimal value 0x55
+(alternating one and zero bits). Note that for {\tt realloc()} this applies
+only to the bytes added at the end of buffer; the original contents of the
+buffer are not modified. Initializing allocated storage to a distinctive
+nonzero pattern is intended to catch code that erroneously assumes newly
+allocated buffers are cleared to zero; in fact their contents are random. The
+{\tt calloc()} function, defined as returning a buffer cleared to zero,
+continues to zero its buffers under SMARTALLOC.
+
+Buffers obtained with the SMARTALLOC functions contain a special sentinel byte
+at the end of the user data area. This byte is set to a special key value
+based upon the buffer's memory address. When the buffer is released, the key
+is tested and if it has been overwritten an assertion in the {\tt free}
+function will fail. This catches incorrect program code that stores beyond the
+storage allocated for the buffer. At {\tt free()} time the queue links are
+also validated and an assertion failure will occur if the program has
+destroyed them by storing before the start of the allocated storage.
+
+In addition, when a buffer is released with {\tt free()}, its contents are
+immediately destroyed by overwriting them with the hexadecimal pattern 0xAA
+(alternating bits, the one's complement of the initial value pattern). This
+will usually trip up code that keeps a pointer to a buffer that's been freed
+and later attempts to reference data within the released buffer. Incredibly,
+this is {\it legal} in the standard Unix memory allocation package, which
+permits programs to free() buffers, then raise them from the grave with {\tt
+realloc()}. Such program ``logic'' should be fixed, not accommodated, and
+SMARTALLOC brooks no such Lazarus buffer`` nonsense.
+
+Some C libraries allow a zero size argument in calls to {\tt malloc()}. Since
+this is far more likely to indicate a program error than a defensible
+programming stratagem, SMARTALLOC disallows it with an assertion.
+
+When the standard library {\tt realloc()} function is called to expand a
+buffer, it attempts to expand the buffer in place if possible, moving it only
+if necessary. Because SMARTALLOC must place its own private storage in the
+buffer and also to aid in error detection, its version of {\tt realloc()}
+always moves and copies the buffer except in the trivial case where the size
+of the buffer is not being changed. By forcing the buffer to move on every
+call and destroying the contents of the old buffer when it is released,
+SMARTALLOC traps programs which keep pointers into a buffer across a call on
+{\tt realloc()} which may move it. This strategy may prove very costly to
+programs which make extensive use of {\tt realloc()}. If this proves to be a
+problem, such programs may wish to use {\tt actuallymalloc()}, {\tt
+actuallyrealloc()}, and {\tt actuallyfree()} for such frequently-adjusted
+buffers, trading error detection for performance. Although not specified in
+the System V Interface Definition, many C library implementations of {\tt
+realloc()} permit an old buffer argument of NULL, causing {\tt realloc()} to
+allocate a new buffer. The SMARTALLOC version permits this.
+
+\subsection{ When SMARTALLOC is Disabled}
+\index{When SMARTALLOC is Disabled }
+\index{Disabled!When SMARTALLOC is }
+\addcontentsline{toc}{subsection}{When SMARTALLOC is Disabled}
+
+When SMARTALLOC is disabled by compiling a program with the symbol SMARTALLOC
+not defined, calls on the functions otherwise redefined by SMARTALLOC go
+directly to the system functions. In addition, compile-time definitions
+translate calls on the ''{\tt actually}...{\tt ()}`` functions into the
+corresponding library calls; ''{\tt actuallymalloc(100)}``, for example,
+compiles into ''{\tt malloc(100)}``. The two special SMARTALLOC functions,
+{\tt sm\_dump()} and {\tt sm\_static()}, are defined to generate no code
+(hence the null statement). Finally, if SMARTALLOC is not defined, compilation
+of the file smartall.c generates no code or data at all, effectively removing
+it from the program even if named in the link instructions.
+
+Thus, except for unusual circumstances, a program that works with SMARTALLOC
+defined for testing should require no changes when built without it for
+production release.
+
+\subsection{ The {\tt alloc()} Function}
+\index{Function!alloc }
+\index{Alloc() Function }
+\addcontentsline{toc}{subsection}{alloc() Function}
+
+Many programs I've worked on use very few direct calls to {\tt malloc()},
+using the identically declared {\tt alloc()} function instead. Alloc detects
+out-of-memory conditions and aborts, removing the need for error checking on
+every call of {\tt malloc()} (and the temptation to skip checking for
+out-of-memory).
+
+As a convenience, SMARTALLOC supplies a compatible version of {\tt alloc()} in
+the file alloc.c, with its definition in the file alloc.h. This version of
+{\tt alloc()} is sensitive to the definition of SMARTALLOC and cooperates with
+SMARTALLOC's orphaned buffer detection. In addition, when SMARTALLOC is
+defined and {\tt alloc()} detects an out of memory condition, it takes
+advantage of the SMARTALLOC diagnostic information to identify the file and
+line number of the call on {\tt alloc()} that failed.
+
+\subsection{ Overlays and Underhandedness}
+\index{Underhandedness!Overlays and }
+\index{Overlays and Underhandedness }
+\addcontentsline{toc}{subsection}{Overlays and Underhandedness}
+
+String constants in the C language are considered to be static arrays of
+characters accessed through a pointer constant. The arrays are potentially
+writable even though their pointer is a constant. SMARTALLOC uses the
+compile-time definition {\tt ./smartall.wml} to obtain the name of the file in
+which a call on buffer allocation was performed. Rather than reserve space in
+a buffer to save this information, SMARTALLOC simply stores the pointer to the
+compiled-in text of the file name. This works fine as long as the program does
+not overlay its data among modules. If data are overlayed, the area of memory
+which contained the file name at the time it was saved in the buffer may
+contain something else entirely when {\tt sm\_dump()} gets around to using the
+pointer to edit the file name which allocated the buffer.
+
+If you want to use SMARTALLOC in a program with overlayed data, you'll have to
+modify smartall.c to either copy the file name to a fixed-length field added
+to the {\tt abufhead} structure, or else allocate storage with {\tt malloc()},
+copy the file name there, and set the {\tt abfname} pointer to that buffer,
+then remember to release the buffer in {\tt sm\_free}. Either of these
+approaches are wasteful of storage and time, and should be considered only if
+there is no alternative. Since most initial debugging is done in non-overlayed
+environments, the restrictions on SMARTALLOC with data overlaying may never
+prove a problem. Note that conventional overlaying of code, by far the most
+common form of overlaying, poses no problems for SMARTALLOC; you need only be
+concerned if you're using exotic tools for data overlaying on MS-DOS or other
+address-space-challenged systems.
+
+Since a C language ''constant`` string can actually be written into, most C
+compilers generate a unique copy of each string used in a module, even if the
+same constant string appears many times. In modules that contain many calls on
+allocation functions, this results in substantial wasted storage for the
+strings that identify the file name. If your compiler permits optimization of
+multiple occurrences of constant strings, enabling this mode will eliminate
+the overhead for these strings. Of course, it's up to you to make sure
+choosing this compiler mode won't wreak havoc on some other part of your
+program.
+
+\subsection{ Test and Demonstration Program}
+\index{Test and Demonstration Program }
+\index{Program!Test and Demonstration }
+\addcontentsline{toc}{subsection}{Test and Demonstration Program}
+
+A test and demonstration program, smtest.c, is supplied with SMARTALLOC. You
+can build this program with the Makefile included. Please refer to the
+comments in smtest.c and the Makefile for information on this program. If
+you're attempting to use SMARTALLOC on a new machine or with a new compiler or
+operating system, it's a wise first step to check it out with smtest first.
+
+\subsection{ Invitation to the Hack}
+\index{Hack!Invitation to the }
+\index{Invitation to the Hack }
+\addcontentsline{toc}{subsection}{Invitation to the Hack}
+
+SMARTALLOC is not intended to be a panacea for storage management problems,
+nor is it universally applicable or effective; it's another weapon in the
+arsenal of the defensive professional programmer attempting to create reliable
+products. It represents the current state of evolution of expedient debug code
+which has been used in several commercial software products which have,
+collectively, sold more than third of a million copies in the retail market,
+and can be expected to continue to develop through time as it is applied to
+ever more demanding projects.
+
+The version of SMARTALLOC here has been tested on a Sun SPARCStation, Silicon
+Graphics Indigo2, and on MS-DOS using both Borland and Microsoft C. Moving
+from compiler to compiler requires the usual small changes to resolve disputes
+about prototyping of functions, whether the type returned by buffer allocation
+is {\tt char\ *} or {\tt void\ *}, and so forth, but following those changes
+it works in a variety of environments. I hope you'll find SMARTALLOC as useful
+for your projects as I've found it in mine.
+
+\section{
+\elink{}{http://www.fourmilab.ch/smartall/smartall.zip}
+\elink{Download smartall.zip}{http://www.fourmilab.ch/smartall/smartall.zip}
+(Zipped archive)}
+\index{Archive! Download smartall.zip Zipped }
+\index{ Download smartall.zip (Zipped archive) }
+\addcontentsline{toc}{section}{ Download smartall.zip (Zipped archive)}
+
+SMARTALLOC is provided as
+\elink{smartall.zip}{http://www.fourmilab.ch/smartall/smartall.zip}, a
+\elink{Zipped}{http://www.pkware.com/} archive containing source code,
+documentation, and a {\tt Makefile} to build the software under Unix.
+
+\subsection{ Copying}
+\index{Copying }
+\addcontentsline{toc}{subsection}{Copying}
+
+\begin{quote}
+SMARTALLOC is in the public domain. Permission to use, copy, modify, and
+distribute this software and its documentation for any purpose and without fee
+is hereby granted, without any conditions or restrictions. This software is
+provided ''as is`` without express or implied warranty.
+\end{quote}
+
+{\it
+\elink{by John Walker}{http://www.fourmilab.ch}
+October 30th, 1998 }
--- /dev/null
+%%
+%%
+
+\chapter{Storage Daemon Design}
+\label{_ChapterStart3}
+\index{Storage Daemon Design }
+\index{Design!Storage Daemon }
+\addcontentsline{toc}{section}{Storage Daemon Design}
+
+This chapter is intended to be a technical discussion of the Storage daemon
+services and as such is not targeted at end users but rather at developers and
+system administrators that want or need to know more of the working details of
+{\bf Bacula}.
+
+This document is somewhat out of date.
+
+\section{SD Design Introduction}
+\index{Introduction!SD Design }
+\index{SD Design Introduction }
+\addcontentsline{toc}{section}{SD Design Introduction}
+
+The Bacula Storage daemon provides storage resources to a Bacula installation.
+An individual Storage daemon is associated with a physical permanent storage
+device (for example, a tape drive, CD writer, tape changer or jukebox, etc.),
+and may employ auxiliary storage resources (such as space on a hard disk file
+system) to increase performance and/or optimize use of the permanent storage
+medium.
+
+Any number of storage daemons may be run on a given machine; each associated
+with an individual storage device connected to it, and BACULA operations may
+employ storage daemons on any number of hosts connected by a network, local or
+remote. The ability to employ remote storage daemons (with appropriate
+security measures) permits automatic off-site backup, possibly to publicly
+available backup repositories.
+
+\section{SD Development Outline}
+\index{Outline!SD Development }
+\index{SD Development Outline }
+\addcontentsline{toc}{section}{SD Development Outline}
+
+In order to provide a high performance backup and restore solution that scales
+to very large capacity devices and networks, the storage daemon must be able
+to extract as much performance from the storage device and network with which
+it interacts. In order to accomplish this, storage daemons will eventually
+have to sacrifice simplicity and painless portability in favor of techniques
+which improve performance. My goal in designing the storage daemon protocol
+and developing the initial prototype storage daemon is to provide for these
+additions in the future, while implementing an initial storage daemon which is
+very simple and portable to almost any POSIX-like environment. This original
+storage daemon (and its evolved descendants) can serve as a portable solution
+for non-demanding backup requirements (such as single servers of modest size,
+individual machines, or small local networks), while serving as the starting
+point for development of higher performance configurable derivatives which use
+techniques such as POSIX threads, shared memory, asynchronous I/O, buffering
+to high-speed intermediate media, and support for tape changers and jukeboxes.
+
+
+\section{SD Connections and Sessions}
+\index{Sessions!SD Connections and }
+\index{SD Connections and Sessions }
+\addcontentsline{toc}{section}{SD Connections and Sessions}
+
+A client connects to a storage server by initiating a conventional TCP
+connection. The storage server accepts the connection unless its maximum
+number of connections has been reached or the specified host is not granted
+access to the storage server. Once a connection has been opened, the client
+may make any number of Query requests, and/or initiate (if permitted), one or
+more Append sessions (which transmit data to be stored by the storage daemon)
+and/or Read sessions (which retrieve data from the storage daemon).
+
+Most requests and replies sent across the connection are simple ASCII strings,
+with status replies prefixed by a four digit status code for easier parsing.
+Binary data appear in blocks stored and retrieved from the storage. Any
+request may result in a single-line status reply of ``{\tt 3201\ Notification\
+pending}'', which indicates the client must send a ``Query notification''
+request to retrieve one or more notifications posted to it. Once the
+notifications have been returned, the client may then resubmit the request
+which resulted in the 3201 status.
+
+The following descriptions omit common error codes, yet to be defined, which
+can occur from most or many requests due to events like media errors,
+restarting of the storage daemon, etc. These details will be filled in, along
+with a comprehensive list of status codes along with which requests can
+produce them in an update to this document.
+
+\subsection{SD Append Requests}
+\index{Requests!SD Append }
+\index{SD Append Requests }
+\addcontentsline{toc}{subsection}{SD Append Requests}
+
+\begin{description}
+
+\item [{append open session = \lt{}JobId\gt{} [ \lt{}Password\gt{} ] }]
+ \index{SPAN class }
+ A data append session is opened with the Job ID given by {\it JobId} with
+client password (if required) given by {\it Password}. If the session is
+successfully opened, a status of {\tt 3000\ OK} is returned with a ``{\tt
+ticket\ =\ }{\it number}'' reply used to identify subsequent messages in the
+session. If too many sessions are open, or a conflicting session (for
+example, a read in progress when simultaneous read and append sessions are
+not permitted), a status of ``{\tt 3502\ Volume\ busy}'' is returned. If no
+volume is mounted, or the volume mounted cannot be appended to, a status of
+``{\tt 3503\ Volume\ not\ mounted}'' is returned.
+
+\item [append data = \lt{}ticket-number\gt{} ]
+ \index{SPAN class }
+ If the append data is accepted, a status of {\tt 3000\ OK data address =
+\lt{}IPaddress\gt{} port = \lt{}port\gt{}} is returned, where the {\tt
+IPaddress} and {\tt port} specify the IP address and port number of the data
+channel. Error status codes are {\tt 3504\ Invalid\ ticket\ number} and {\tt
+3505\ Session\ aborted}, the latter of which indicates the entire append
+session has failed due to a daemon or media error.
+
+Once the File daemon has established the connection to the data channel
+opened by the Storage daemon, it will transfer a header packet followed by
+any number of data packets. The header packet is of the form:
+
+{\tt \lt{}file-index\gt{} \lt{}stream-id\gt{} \lt{}info\gt{}}
+
+The details are specified in the
+\ilink{Daemon Protocol}{_ChapterStart2} section of this
+document.
+
+\item [*append abort session = \lt{}ticket-number\gt{} ]
+ \index{SPAN class }
+ The open append session with ticket {\it ticket-number} is aborted; any blocks
+not yet written to permanent media are discarded. Subsequent attempts to
+append data to the session will receive an error status of {\tt 3505\
+Session\ aborted}.
+
+\item [append end session = \lt{}ticket-number\gt{} ]
+ \index{SPAN class }
+ The open append session with ticket {\it ticket-number} is marked complete; no
+further blocks may be appended. The storage daemon will give priority to
+saving any buffered blocks from this session to permanent media as soon as
+possible.
+
+\item [append close session = \lt{}ticket-number\gt{} ]
+ \index{SPAN class }
+ The append session with ticket {\it ticket} is closed. This message does not
+receive an {\tt 3000\ OK} reply until all of the content of the session are
+stored on permanent media, at which time said reply is given, followed by a
+list of volumes, from first to last, which contain blocks from the session,
+along with the first and last file and block on each containing session data
+and the volume session key identifying data from that session in lines with
+the following format:
+
+{\tt {\tt Volume = }\lt{}Volume-id\gt{} \lt{}start-file\gt{}
+\lt{}start-block\gt{} \lt{}end-file\gt{} \lt{}end-block\gt{}
+\lt{}volume-session-id\gt{}}where {\it Volume-id} is the volume label, {\it
+start-file} and {\it start-block} are the file and block containing the first
+data from that session on the volume, {\it end-file} and {\it end-block} are
+the file and block with the last data from the session on the volume and {\it
+volume-session-id} is the volume session ID for blocks from the session
+stored on that volume.
+\end{description}
+
+\subsection{SD Read Requests}
+\index{SD Read Requests }
+\index{Requests!SD Read }
+\addcontentsline{toc}{subsection}{SD Read Requests}
+
+\begin{description}
+
+\item [Read open session = \lt{}JobId\gt{} \lt{}Volume-id\gt{}
+ \lt{}start-file\gt{} \lt{}start-block\gt{} \lt{}end-file\gt{}
+ \lt{}end-block\gt{} \lt{}volume-session-id\gt{} \lt{}password\gt{} ]
+\index{SPAN class }
+where {\it Volume-id} is the volume label, {\it start-file} and {\it
+start-block} are the file and block containing the first data from that
+session on the volume, {\it end-file} and {\it end-block} are the file and
+block with the last data from the session on the volume and {\it
+volume-session-id} is the volume session ID for blocks from the session
+stored on that volume.
+
+If the session is successfully opened, a status of
+
+{\tt {\tt 3100\ OK Ticket\ =\ }{\it number}``}
+
+is returned with a reply used to identify subsequent messages in the session.
+If too many sessions are open, or a conflicting session (for example, an
+append in progress when simultaneous read and append sessions are not
+permitted), a status of ''{\tt 3502\ Volume\ busy}`` is returned. If no
+volume is mounted, or the volume mounted cannot be appended to, a status of
+''{\tt 3503\ Volume\ not\ mounted}`` is returned. If no block with the given
+volume session ID and the correct client ID number appears in the given first
+file and block for the volume, a status of ''{\tt 3505\ Session\ not\
+found}`` is returned.
+
+\item [Read data = \lt{}Ticket\gt{} \gt{} \lt{}Block\gt{} ]
+ \index{SPAN class }
+ The specified Block of data from open read session with the specified Ticket
+number is returned, with a status of {\tt 3000\ OK} followed by a ''{\tt
+Length\ =\ }{\it size}`` line giving the length in bytes of the block data
+which immediately follows. Blocks must be retrieved in ascending order, but
+blocks may be skipped. If a block number greater than the largest stored on
+the volume is requested, a status of ''{\tt 3201\ End\ of\ volume}`` is
+returned. If a block number greater than the largest in the file is
+requested, a status of ''{\tt 3401\ End\ of\ file}`` is returned.
+
+\item [Read close session = \lt{}Ticket\gt{} ]
+ \index{SPAN class }
+ The read session with Ticket number is closed. A read session may be closed
+at any time; you needn't read all its blocks before closing it.
+\end{description}
+
+{\it by
+\elink{John Walker}{http://www.fourmilab.ch/}
+January 30th, MM }
+
+\section{SD Data Structures}
+\index{SD Data Structures}
+\addcontentsline{toc}{section}{SD Data Structures}
+
+In the Storage daemon, there is a Device resource (i.e. from conf file)
+that describes each physical device. When the physical device is used it
+is controled by the DEVICE structure (defined in dev.h), and typically
+refered to as dev in the C++ code. Anyone writing or reading a physical
+device must ultimately get a lock on the DEVICE structure -- this controls
+the device. However, multiple Jobs (defined by a JCR structure src/jcr.h)
+can be writing a physical DEVICE at the same time (of course they are
+sequenced by locking the DEVICE structure). There are a lot of job
+dependent "device" variables that may be different for each Job such as
+spooling (one job may spool and another may not, and when a job is
+spooling, it must have an i/o packet open, each job has its own record and
+block structures, ...), so there is a device control record or DCR that is
+the primary way of interfacing to the physical device. The DCR contains
+all the job specific data as well as a pointer to the Device resource
+(DEVRES structure) and the physical DEVICE structure.
+
+Now if a job is writing to two devices (it could be writing two separate
+streams to the same device), it must have two DCRs. Today, the code only
+permits one. This won't be hard to change, but it is new code.
+
+Today three jobs (threads), two physical devices each job
+ writes to only one device:
+
+\begin{verbatim}
+ Job1 -> DCR1 -> DEVICE1
+ Job2 -> DCR2 -> DEVICE1
+ Job3 -> DCR3 -> DEVICE2
+\end{verbatim}
+
+To be implemented three jobs, three physical devices, but
+ job1 is writing simultaneously to three devices:
+
+\begin{verbatim}
+ Job1 -> DCR1 -> DEVICE1
+ -> DCR4 -> DEVICE2
+ -> DCR5 -> DEVICE3
+ Job2 -> DCR2 -> DEVICE1
+ Job3 -> DCR3 -> DEVICE2
+
+ Job = job control record
+ DCR = Job contorl data for a specific device
+ DEVICE = Device only control data
+\end{verbatim}
+
--- /dev/null
+%%
+%%
+
+%\author{Landon Fuller}
+%\title{Bacula TLS Additions}
+
+\chapter{TLS}
+\label{_Chapter_TLS}
+\index{TLS}
+
+Written by Landon Fuller
+
+\section{Introduction to TLS}
+\index{TLS Introduction}
+\index{Introduction!TLS}
+\addcontentsline{toc}{section}{TLS Introduction}
+
+This patch includes all the back-end code necessary to add complete TLS
+data encryption support to Bacula. In addition, support for TLS in
+Console/Director communications has been added as a proof of concept.
+Adding support for the remaining daemons will be straight-forward.
+Supported features of this patchset include:
+
+\begin{itemize}
+\item Client/Server TLS Requirement Negotiation
+\item TLSv1 Connections with Server and Client Certificate
+Validation
+\item Forward Secrecy Support via Diffie-Hellman Ephemeral Keying
+\end{itemize}
+
+This document will refer to both ``server'' and ``client'' contexts. These
+terms refer to the accepting and initiating peer, respectively.
+
+Diffie-Hellman anonymous ciphers are not supported by this patchset. The
+use of DH anonymous ciphers increases the code complexity and places
+explicit trust upon the two-way Cram-MD5 implementation. Cram-MD5 is
+subject to known plaintext attacks, and is should be considered
+considerably less secure than PKI certificate-based authentication.
+
+Appropriate autoconf macros have been added to detect and use OpenSSL. Two
+additional preprocessor defines have been added: \emph{HAVE\_TLS} and
+\emph{HAVE\_OPENSSL}. All changes not specific to OpenSSL rely on
+\emph{HAVE\_TLS}. OpenSSL-specific code is constrained to
+\emph{src/lib/tls.c} to facilitate the support of alternative TLS
+implementations.
+
+\section{New Configuration Directives}
+\index{TLS Configuration Directives}
+\index{Directives!TLS Configuration}
+\addcontentsline{toc}{section}{New Configuration Directives}
+
+Additional configuration directives have been added to both the Console and
+Director resources. These new directives are defined as follows:
+
+\begin{itemize}
+\item \underline{TLS Enable} \emph{(yes/no)}
+Enable TLS support.
+
+\item \underline{TLS Require} \emph{(yes/no)}
+Require TLS connections.
+
+\item \underline{TLS Certificate} \emph{(path)}
+Path to PEM encoded TLS certificate. Used as either a client or server
+certificate.
+
+\item \underline{TLS Key} \emph{(path)}
+Path to PEM encoded TLS private key. Must correspond with the TLS
+certificate.
+
+\item \underline{TLS Verify Peer} \emph{(yes/no)}
+Verify peer certificate. Instructs server to request and verify the
+client's x509 certificate. Any client certificate signed by a known-CA
+will be accepted unless the TLS Allowed CN configuration directive is used.
+Not valid in a client context.
+
+\item \underline{TLS Allowed CN} \emph{(string list)}
+Common name attribute of allowed peer certificates. If directive is
+specified, all client certificates will be verified against this list.
+This directive may be specified more than once. Not valid in a client
+context.
+
+\item \underline{TLS CA Certificate File} \emph{(path)}
+Path to PEM encoded TLS CA certificate(s). Multiple certificates are
+permitted in the file. One of \emph{TLS CA Certificate File} or \emph{TLS
+CA Certificate Dir} are required in a server context if \underline{TLS
+Verify Peer} is also specified, and are always required in a client
+context.
+
+\item \underline{TLS CA Certificate Dir} \emph{(path)}
+Path to TLS CA certificate directory. In the current implementation,
+certificates must be stored PEM encoded with OpenSSL-compatible hashes.
+One of \emph{TLS CA Certificate File} or \emph{TLS CA Certificate Dir} are
+required in a server context if \emph{TLS Verify Peer} is also specified,
+and are always required in a client context.
+
+\item \underline{TLS DH File} \emph{(path)}
+Path to PEM encoded Diffie-Hellman parameter file. If this directive is
+specified, DH ephemeral keying will be enabled, allowing for forward
+secrecy of communications. This directive is only valid within a server
+context. To generate the parameter file, you may use openssl:
+\footnotesize
+\begin{verbatim}
+openssl dhparam -out dh1024.pem -5 1024
+\end{verbatim}
+\normalsize
+\end{itemize}
+
+\section{TLS API Implementation}
+\index{TLS API Implimentation}
+\index{API Implimentation!TLS}
+\addcontentsline{toc}{section}{TLS API Implementation}
+
+To facilitate the use of additional TLS libraries, all OpenSSL-specific
+code has been implemented within \emph{src/lib/tls.c}. In turn, a generic
+TLS API is exported.
+
+\subsection{Library Initialization and Cleanup}
+\index{Library Initialization and Cleanup}
+\index{Initialization and Cleanup!Library}
+\addcontentsline{toc}{subsection}{Library Initialization and Cleanup}
+
+\footnotesize
+\begin{verbatim}
+int init_tls (void);
+\end{verbatim}
+\normalsize
+
+Performs TLS library initialization, including seeding of the PRNG. PRNG
+seeding has not yet been implemented for win32.
+
+\footnotesize
+\begin{verbatim}
+int cleanup_tls (void);
+\end{verbatim}
+\normalsize
+
+Performs TLS library cleanup.
+
+\subsection{Manipulating TLS Contexts}
+\index{TLS Context Manipulation}
+\index{Contexts!Manipulating TLS}
+\addcontentsline{toc}{subsection}{Manipulating TLS Contexts}
+
+\footnotesize
+\begin{verbatim}
+TLS_CONTEXT *new_tls_context (const char *ca_certfile,
+ const char *ca_certdir, const char *certfile,
+ const char *keyfile, const char *dhfile, bool verify_peer);
+\end{verbatim}
+\normalsize
+
+Allocates and initalizes a new opaque \emph{TLS\_CONTEXT} structure. The
+\emph{TLS\_CONTEXT} structure maintains default TLS settings from which
+\emph{TLS\_CONNECTION} structures are instantiated. In the future the
+\emph{TLS\_CONTEXT} structure may be used to maintain the TLS session
+cache. \emph{ca\_certfile} and \emph{ca\_certdir} arguments are used to
+initialize the CA verification stores. The \emph{certfile} and
+\emph{keyfile} arguments are used to initialize the local certificate and
+private key. If \emph{dhfile} is non-NULL, it is used to initialize
+Diffie-Hellman ephemeral keying. If \emph{verify\_peer} is \emph{true} ,
+client certificate validation is enabled.
+
+\footnotesize
+\begin{verbatim}
+void free_tls_context (TLS_CONTEXT *ctx);
+\end{verbatim}
+\normalsize
+
+Deallocated a previously allocated \emph{TLS\_CONTEXT} structure.
+
+\subsection{Performing Post-Connection Verification}
+\index{TLS Post-Connection Verification}
+\index{Verification!TLS Post-Connection}
+\addcontentsline{toc}{subsection}{Performing Post-Connection Verification}
+
+\footnotesize
+\begin{verbatim}
+bool tls_postconnect_verify_host (TLS_CONNECTION *tls, const char *host);
+\end{verbatim}
+\normalsize
+
+Performs post-connection verification of the peer-supplied x509
+certificate. Checks whether the \emph{subjectAltName} and
+\emph{commonName} attributes match the supplied \emph{host} string.
+Returns \emph{true} if there is a match, \emph{false} otherwise.
+
+\footnotesize
+\begin{verbatim}
+bool tls_postconnect_verify_cn (TLS_CONNECTION *tls, alist *verify_list);
+\end{verbatim}
+\normalsize
+
+Performs post-connection verification of the peer-supplied x509
+certificate. Checks whether the \emph{commonName} attribute matches any
+strings supplied via the \emph{verify\_list} parameter. Returns
+\emph{true} if there is a match, \emph{false} otherwise.
+
+\subsection{Manipulating TLS Connections}
+\index{TLS Connection Manipulation}
+\index{Connections!Manipulating TLS}
+\addcontentsline{toc}{subsection}{Manipulating TLS Connections}
+
+\footnotesize
+\begin{verbatim}
+TLS_CONNECTION *new_tls_connection (TLS_CONTEXT *ctx, int fd);
+\end{verbatim}
+\normalsize
+
+Allocates and initializes a new \emph{TLS\_CONNECTION} structure with
+context \emph{ctx} and file descriptor \emph{fd}.
+
+\footnotesize
+\begin{verbatim}
+void free_tls_connection (TLS_CONNECTION *tls);
+\end{verbatim}
+\normalsize
+
+Deallocates memory associated with the \emph{tls} structure.
+
+\footnotesize
+\begin{verbatim}
+bool tls_bsock_connect (BSOCK *bsock);
+\end{verbatim}
+\normalsize
+
+Negotiates a a TLS client connection via \emph{bsock}. Returns \emph{true}
+if successful, \emph{false} otherwise. Will fail if there is a TLS
+protocol error or an invalid certificate is presented
+
+\footnotesize
+\begin{verbatim}
+bool tls_bsock_accept (BSOCK *bsock);
+\end{verbatim}
+\normalsize
+
+Accepts a TLS client connection via \emph{bsock}. Returns \emph{true} if
+successful, \emph{false} otherwise. Will fail if there is a TLS protocol
+error or an invalid certificate is presented.
+
+\footnotesize
+\begin{verbatim}
+bool tls_bsock_shutdown (BSOCK *bsock);
+\end{verbatim}
+\normalsize
+
+Issues a blocking TLS shutdown request to the peer via \emph{bsock}. This function may not wait for the peer's reply.
+
+\footnotesize
+\begin{verbatim}
+int tls_bsock_writen (BSOCK *bsock, char *ptr, int32_t nbytes);
+\end{verbatim}
+\normalsize
+
+Writes \emph{nbytes} from \emph{ptr} via the \emph{TLS\_CONNECTION}
+associated with \emph{bsock}. Due to OpenSSL's handling of \emph{EINTR},
+\emph{bsock} is set non-blocking at the start of the function, and restored
+to its original blocking state before the function returns. Less than
+\emph{nbytes} may be written if an error occurs. The actual number of
+bytes written will be returned.
+
+\footnotesize
+\begin{verbatim}
+int tls_bsock_readn (BSOCK *bsock, char *ptr, int32_t nbytes);
+\end{verbatim}
+\normalsize
+
+Reads \emph{nbytes} from the \emph{TLS\_CONNECTION} associated with
+\emph{bsock} and stores the result in \emph{ptr}. Due to OpenSSL's
+handling of \emph{EINTR}, \emph{bsock} is set non-blocking at the start of
+the function, and restored to its original blocking state before the
+function returns. Less than \emph{nbytes} may be read if an error occurs.
+The actual number of bytes read will be returned.
+
+\section{Bnet API Changes}
+\index{Bnet API Changes}
+\index{API Changes!Bnet}
+\addcontentsline{toc}{section}{Bnet API Changes}
+
+A minimal number of changes were required in the Bnet socket API. The BSOCK
+structure was expanded to include an associated TLS\_CONNECTION structure,
+as well as a flag to designate the current blocking state of the socket.
+The blocking state flag is required for win32, where it does not appear
+possible to discern the current blocking state of a socket.
+
+\subsection{Negotiating a TLS Connection}
+\index{Negotiating a TLS Connection}
+\index{TLS Connection!Negotiating}
+\addcontentsline{toc}{subsection}{Negotiating a TLS Connection}
+
+\emph{bnet\_tls\_server()} and \emph{bnet\_tls\_client()} were both
+implemented using the new TLS API as follows:
+
+\footnotesize
+\begin{verbatim}
+int bnet_tls_client(TLS_CONTEXT *ctx, BSOCK * bsock);
+\end{verbatim}
+\normalsize
+
+Negotiates a TLS session via \emph{bsock} using the settings from
+\emph{ctx}. Returns 1 if successful, 0 otherwise.
+
+\footnotesize
+\begin{verbatim}
+int bnet_tls_server(TLS_CONTEXT *ctx, BSOCK * bsock, alist *verify_list);
+\end{verbatim}
+\normalsize
+
+Accepts a TLS client session via \emph{bsock} using the settings from
+\emph{ctx}. If \emph{verify\_list} is non-NULL, it is passed to
+\emph{tls\_postconnect\_verify\_cn()} for client certificate verification.
+
+\subsection{Manipulating Socket Blocking State}
+\index{Manipulating Socket Blocking State}
+\index{Socket Blocking State!Manipulating}
+\index{Blocking State!Socket!Manipulating}
+\addcontentsline{toc}{subsection}{Manipulating Socket Blocking State}
+
+Three functions were added for manipulating the blocking state of a socket
+on both Win32 and Unix-like systems. The Win32 code was written according
+to the MSDN documentation, but has not been tested.
+
+These functions are prototyped as follows:
+
+\footnotesize
+\begin{verbatim}
+int bnet_set_nonblocking (BSOCK *bsock);
+\end{verbatim}
+\normalsize
+
+Enables non-blocking I/O on the socket associated with \emph{bsock}.
+Returns a copy of the socket flags prior to modification.
+
+\footnotesize
+\begin{verbatim}
+int bnet_set_blocking (BSOCK *bsock);
+\end{verbatim}
+\normalsize
+
+Enables blocking I/O on the socket associated with \emph{bsock}. Returns a
+copy of the socket flags prior to modification.
+
+\footnotesize
+\begin{verbatim}
+void bnet_restore_blocking (BSOCK *bsock, int flags);
+\end{verbatim}
+\normalsize
+
+Restores blocking or non-blocking IO setting on the socket associated with
+\emph{bsock}. The \emph{flags} argument must be the return value of either
+\emph{bnet\_set\_blocking()} or \emph{bnet\_restore\_blocking()}.
+
+\pagebreak
+
+\section{Authentication Negotiation}
+\index{Authentication Negotiation}
+\index{Negotiation!TLS Authentication}
+\addcontentsline{toc}{section}{Authentication Negotiation}
+
+Backwards compatibility with the existing SSL negotiation hooks implemented
+in src/lib/cram-md5.c have been maintained. The
+\emph{cram\_md5\_get\_auth()} function has been modified to accept an
+integer pointer argument, tls\_remote\_need. The TLS requirement
+advertised by the remote host is returned via this pointer.
+
+After exchanging cram-md5 authentication and TLS requirements, both the
+client and server independently decide whether to continue:
+
+\footnotesize
+\begin{verbatim}
+if (!cram_md5_get_auth(dir, password, &tls_remote_need) ||
+ !cram_md5_auth(dir, password, tls_local_need)) {
+[snip]
+/* Verify that the remote host is willing to meet our TLS requirements */
+if (tls_remote_need < tls_local_need && tls_local_need != BNET_TLS_OK &&
+ tls_remote_need != BNET_TLS_OK) {
+ sendit(_("Authorization problem:"
+ " Remote server did not advertise required TLS support.\n"));
+ auth_success = false;
+ goto auth_done;
+}
+
+/* Verify that we are willing to meet the remote host's requirements */
+if (tls_remote_need > tls_local_need && tls_local_need != BNET_TLS_OK &&
+ tls_remote_need != BNET_TLS_OK) {
+ sendit(_("Authorization problem:"
+ " Remote server requires TLS.\n"));
+ auth_success = false;
+ goto auth_done;
+}
+\end{verbatim}
+\normalsize
--- /dev/null
+#!/usr/bin/perl -w
+#
+use strict;
+
+# Used to change the names of the image files generated by latex2html from imgxx.png
+# to meaningful names. Provision is made to go either from or to the meaningful names.
+# The meaningful names are obtained from a file called imagename_translations, which
+# is generated by extensions to latex2html in the make_image_file subroutine in
+# bacula.perl.
+
+# Opens the file imagename_translations and reads the contents into a hash.
+# The hash is creaed with the imgxx.png files as the key if processing TO
+# meaningful filenames, and with the meaningful filenames as the key if
+# processing FROM meaningful filenames.
+# Then opens the html file(s) indicated in the command-line arguments and
+# changes all image references according to the translations described in the
+# above file. Finally, it renames the image files.
+#
+# Original creation: 3-27-05 by Karl Cunningham.
+# Modified 5-21-05 to go FROM and TO meaningful filenames.
+#
+my $TRANSFILE = "imagename_translations";
+my $path;
+
+# Loads the contents of $TRANSFILE file into the hash referenced in the first
+# argument. The hash is loaded to translate old to new if $direction is 0,
+# otherwise it is loaded to translate new to old. In this context, the
+# 'old' filename is the meaningful name, and the 'new' filename is the
+# imgxx.png filename. It is assumed that the old image is the one that
+# latex2html has used as the source to create the imgxx.png filename.
+# The filename extension is taken from the file
+sub read_transfile {
+ my ($trans,$direction) = @_;
+
+ if (!open IN,"<$path$TRANSFILE") {
+ print "WARNING: Cannot open image translation file $path$TRANSFILE for reading\n";
+ print " Image filename translation aborted\n\n";
+ exit 0;
+ }
+
+ while (<IN>) {
+ chomp;
+ my ($new,$old) = split(/\001/);
+
+ # Old filenames will usually have a leading ./ which we don't need.
+ $old =~ s/^\.\///;
+
+ # The filename extension of the old filename must be made to match
+ # the new filename because it indicates the encoding format of the image.
+ my ($ext) = $new =~ /(\.[^\.]*)$/;
+ $old =~ s/\.[^\.]*$/$ext/;
+ if ($direction == 0) {
+ $trans->{$new} = $old;
+ } else {
+ $trans->{$old} = $new;
+ }
+ }
+ close IN;
+}
+
+# Translates the image names in the file given as the first argument, according to
+# the translations in the hash that is given as the second argument.
+# The file contents are read in entirely into a string, the string is processed, and
+# the file contents are then written. No particular care is taken to ensure that the
+# file is not lost if a system failure occurs at an inopportune time. It is assumed
+# that the html files being processed here can be recreated on demand.
+#
+# Links to other files are added to the %filelist for processing. That way,
+# all linked files will be processed (assuming they are local).
+sub translate_html {
+ my ($filename,$trans,$filelist) = @_;
+ my ($contents,$out,$this,$img,$dest);
+ my $cnt = 0;
+
+ # If the filename is an external link ignore it. And drop any file:// from
+ # the filename.
+ $filename =~ /^(http|ftp|mailto)\:/ and return 0;
+ $filename =~ s/^file\:\/\///;
+ # Load the contents of the html file.
+ if (!open IF,"<$path$filename") {
+ print "WARNING: Cannot open $path$filename for reading\n";
+ print " Image Filename Translation aborted\n\n";
+ exit 0;
+ }
+
+ while (<IF>) {
+ $contents .= $_;
+ }
+ close IF;
+
+ # Now do the translation...
+ # First, search for an image filename.
+ while ($contents =~ /\<\s*IMG[^\>]*SRC=\"/si) {
+ $contents = $';
+ $out .= $` . $&;
+
+ # The next thing is an image name. Get it and translate it.
+ $contents =~ /^(.*?)\"/s;
+ $contents = $';
+ $this = $&;
+ $img = $1;
+ # If the image is in our list of ones to be translated, do it
+ # and feed the result to the output.
+ $cnt += $this =~ s/$img/$trans->{$img}/ if (defined($trans->{$img}));
+ $out .= $this;
+ }
+ $out .= $contents;
+
+ # Now send the translated text to the html file, overwriting what's there.
+ open OF,">$path$filename" or die "Cannot open $path$filename for writing\n";
+ print OF $out;
+ close OF;
+
+ # Now look for any links to other files and add them to the list of files to do.
+ while ($out =~ /\<\s*A[^\>]*HREF=\"(.*?)\"/si) {
+ $out = $';
+ $dest = $1;
+ # Drop an # and anything after it.
+ $dest =~ s/\#.*//;
+ $filelist->{$dest} = '' if $dest;
+ }
+ return $cnt;
+}
+
+# REnames the image files spefified in the %translate hash.
+sub rename_images {
+ my $translate = shift;
+ my ($response);
+
+ foreach (keys(%$translate)) {
+ if (! $translate->{$_}) {
+ print " WARNING: No destination Filename for $_\n";
+ } else {
+ $response = `mv -f $path$_ $path$translate->{$_} 2>&1`;
+ $response and print "ERROR from system $response\n";
+ }
+ }
+}
+
+#################################################
+############# MAIN #############################
+################################################
+
+# %filelist starts out with keys from the @ARGV list. As files are processed,
+# any links to other files are added to the %filelist. A hash of processed
+# files is kept so we don't do any twice.
+
+# The first argument must be either --to_meaningful_names or --from_meaningful_names
+
+my (%translate,$search_regex,%filelist,%completed,$thisfile);
+my ($cnt,$direction);
+
+my $arg0 = shift(@ARGV);
+$arg0 =~ /^(--to_meaningful_names|--from_meaningful_names)$/ or
+ die "ERROR: First argument must be either \'--to_meaningful_names\' or \'--from_meaningful_names\'\n";
+
+$direction = ($arg0 eq '--to_meaningful_names') ? 0 : 1;
+
+(@ARGV) or die "ERROR: Filename(s) to process must be given as arguments\n";
+
+# Use the first argument to get the path to the file of translations.
+my $tmp = $ARGV[0];
+($path) = $tmp =~ /(.*\/)/;
+$path = '' unless $path;
+
+read_transfile(\%translate,$direction);
+
+foreach (@ARGV) {
+ # Strip the path from the filename, and use it later on.
+ if (s/(.*\/)//) {
+ $path = $1;
+ } else {
+ $path = '';
+ }
+ $filelist{$_} = '';
+
+ while ($thisfile = (keys(%filelist))[0]) {
+ $cnt += translate_html($thisfile,\%translate,\%filelist) if (!exists($completed{$thisfile}));
+ delete($filelist{$thisfile});
+ $completed{$thisfile} = '';
+ }
+ print "translate_images.pl: $cnt image filenames translated ",($direction)?"from":"to"," meaningful names\n";
+}
+
+rename_images(\%translate);
--- /dev/null
+#!/bin/sh
+#
+# Script file to update the Bacula version
+#
+out=/tmp/$$
+VERSION=`sed -n -e 's/^.*VERSION.*"\(.*\)"$/\1/p' /home/kern/bacula/k/src/version.h`
+DATE=`sed -n -e 's/^.*[ \t]*BDATE.*"\(.*\)"$/\1/p' /home/kern/bacula/k/src/version.h`
+. ./do_echo
+sed -f ${out} version.tex.in >version.tex
+rm -f ${out}
--- /dev/null
+#!/bin/sh
+#
+# Script file to update the Bacula version
+#
+out=/tmp/$$
+VERSION=`sed -n -e 's/^.*VERSION.*"\(.*\)"$/\1/p' @bacula@/src/version.h`
+DATE=`sed -n -e 's/^.*[ \t]*BDATE.*"\(.*\)"$/\1/p' @bacula@/src/version.h`
+. ./do_echo
+sed -f ${out} version.tex.in >version.tex
+rm -f ${out}
--- /dev/null
+2.3.6 (04 November 2007)
--- /dev/null
+@VERSION@ (@DATE@)
--- /dev/null
+#
+#
+# Makefile for LaTeX
+#
+# To build everything do
+# make tex
+# make web
+# make html
+# make dvipdf
+#
+# or simply
+#
+# make
+#
+# for rapid development do:
+# make tex
+# make show
+#
+#
+# If you are having problems getting "make" to work, debugging it is
+# easier if can see the output from latex, which is normally redirected
+# to /dev/null. To see it, do the following:
+#
+# cd docs/manual
+# make tex
+# latex bacula.tex
+#
+# typically the latex command will stop indicating the error (e.g. a
+# missing \ in front of a _ or a missing { or ] ...
+#
+# The following characters must be preceded by a backslash
+# to be entered as printable characters:
+#
+# # $ % & ~ _ ^ \ { }
+#
+
+IMAGES=../../../images
+
+DOC=install
+
+first_rule: all
+
+all: tex web dvipdf mini-clean
+
+.SUFFIXES: .tex .html
+.PHONY:
+.DONTCARE:
+
+
+tex:
+ @./update_version
+ @echo "Making version `cat version.tex`"
+ @cp -fp ${IMAGES}/hires/*.eps .
+ @touch ${DOC}i-dir.tex ${DOC}i-fd.tex ${DOC}i-sd.tex \
+ ${DOC}i-console.tex ${DOC}i-general.tex
+ latex -interaction=batchmode ${DOC}.tex
+ makeindex ${DOC}.idx -o ${DOC}.ind 2>/dev/null
+ makeindex ${DOC}.ddx -o ${DOC}.dnd >/dev/null 2>/dev/null
+ makeindex ${DOC}.fdx -o ${DOC}.fnd >/dev/null 2>/dev/null
+ makeindex ${DOC}.sdx -o ${DOC}.snd >/dev/null 2>/dev/null
+ makeindex ${DOC}.cdx -o ${DOC}.cnd >/dev/null 2>/dev/null
+ latex -interaction=batchmode ${DOC}.tex
+
+pdf:
+ @echo "Making pdfm"
+ @cp -fp ${IMAGES}/hires/*.eps .
+ dvipdfm -p a4 ${DOC}.dvi
+
+dvipdf:
+ @echo "Making dvi to pdf"
+ @cp -fp ${IMAGES}/hires/*.eps .
+ dvipdf ${DOC}.dvi ${DOC}.pdf
+
+html:
+ @echo " "
+ @echo "Making html"
+ @cp -fp ${IMAGES}/*.eps .
+ @rm -f next.eps next.png prev.eps prev.png up.eps up.png
+ @(if [ -f imagename_translations ] ; then \
+ ./translate_images.pl --from_meaningful_names ${DOC}.html; \
+ fi)
+ latex2html -white -no_subdir -split 0 -toc_stars -white -notransparent \
+ -init_file latex2html-init.pl ${DOC} >tex.out 2>&1
+ ./translate_images.pl --to_meaningful_names ${DOC}.html
+ @echo "Done making html"
+
+web:
+ @echo "Making web"
+ @mkdir -p ${DOC}
+ @cp -fp ${IMAGES}/*.eps .
+ @rm -f next.eps next.png prev.eps prev.png up.eps up.png
+ @cp -fp ${IMAGES}/*.eps ${DOC}/
+ @cp -fp ${IMAGES}/*.eps ${IMAGES}/*.png ${DOC}/
+ @rm -f ${DOC}/xp-*.png
+ @rm -f ${DOC}/next.eps ${DOC}/next.png ${DOC}/prev.eps ${DOC}/prev.png ${DOC}/up.eps ${DOC}/up.png
+ @rm -rf ${DOC}/*.html
+ latex2html -split 3 -local_icons -t "Bacula Installation and Configuration Guide" -long_titles 4 \
+ -toc_stars -contents_in_nav -init_file latex2html-init.pl -white -notransparent ${DOC} >tex.out 2>&1
+ ./translate_images.pl --to_meaningful_names ${DOC}/Bacula_Instal_Config_Guide.html
+ @echo "Done making web"
+show:
+ xdvi ${DOC}
+
+texcheck:
+ ./check_tex.pl ${DOC}.tex
+
+main_configs:
+ pic2graph -density 100 <main_configs.pic >main_configs.png
+
+mini-clean:
+ @rm -f 1 2 3 *.tex~
+ @rm -f *.gif *.jpg *.eps
+ @rm -f *.aux *.cp *.fn *.ky *.log *.pg
+ @rm -f *.backup *.ilg *.lof *.lot
+ @rm -f *.cdx *.cnd *.ddx *.ddn *.fdx *.fnd *.ind *.sdx *.snd
+ @rm -f *.dnd *.old *.out
+ @rm -f ${DOC}/*.gif ${DOC}/*.jpg ${DOC}/*.eps
+ @rm -f ${DOC}/*.aux ${DOC}/*.cp ${DOC}/*.fn ${DOC}/*.ky ${DOC}/*.log ${DOC}/*.pg
+ @rm -f ${DOC}/*.backup ${DOC}/*.ilg ${DOC}/*.lof ${DOC}/*.lot
+ @rm -f ${DOC}/*.cdx ${DOC}/*.cnd ${DOC}/*.ddx ${DOC}/*.ddn ${DOC}/*.fdx ${DOC}/*.fnd ${DOC}/*.ind ${DOC}/*.sdx ${DOC}/*.snd
+ @rm -f ${DOC}/*.dnd ${DOC}/*.old ${DOC}/*.out
+ @rm -f ${DOC}/WARNINGS
+
+
+clean:
+ @rm -f 1 2 3 *.tex~
+ @rm -f *.png *.gif *.jpg *.eps
+ @rm -f *.pdf *.aux *.cp *.fn *.ky *.log *.pg
+ @rm -f *.html *.backup *.ps *.dvi *.ilg *.lof *.lot
+ @rm -f *.cdx *.cnd *.ddx *.ddn *.fdx *.fnd *.ind *.sdx *.snd
+ @rm -f *.dnd imagename_translations
+ @rm -f *.old WARNINGS *.out *.toc *.idx
+ @rm -f ${DOC}i-*.tex
+ @rm -rf ${DOC}
+
+
+distclean: clean
+ @rm -f images.pl labels.pl internals.pl
+ @rm -f Makefile version.tex
--- /dev/null
+#
+#
+# Makefile for LaTeX
+#
+# To build everything do
+# make tex
+# make web
+# make html
+# make dvipdf
+#
+# or simply
+#
+# make
+#
+# for rapid development do:
+# make tex
+# make show
+#
+#
+# If you are having problems getting "make" to work, debugging it is
+# easier if can see the output from latex, which is normally redirected
+# to /dev/null. To see it, do the following:
+#
+# cd docs/manual
+# make tex
+# latex bacula.tex
+#
+# typically the latex command will stop indicating the error (e.g. a
+# missing \ in front of a _ or a missing { or ] ...
+#
+# The following characters must be preceded by a backslash
+# to be entered as printable characters:
+#
+# # $ % & ~ _ ^ \ { }
+#
+
+IMAGES=../../../images
+
+DOC=install
+
+first_rule: all
+
+all: tex web dvipdf mini-clean
+
+.SUFFIXES: .tex .html
+.PHONY:
+.DONTCARE:
+
+
+tex:
+ @./update_version
+ @echo "Making version `cat version.tex`"
+ @cp -fp ${IMAGES}/hires/*.eps .
+ @touch ${DOC}i-dir.tex ${DOC}i-fd.tex ${DOC}i-sd.tex \
+ ${DOC}i-console.tex ${DOC}i-general.tex
+ latex -interaction=batchmode ${DOC}.tex
+ makeindex ${DOC}.idx -o ${DOC}.ind 2>/dev/null
+ makeindex ${DOC}.ddx -o ${DOC}.dnd >/dev/null 2>/dev/null
+ makeindex ${DOC}.fdx -o ${DOC}.fnd >/dev/null 2>/dev/null
+ makeindex ${DOC}.sdx -o ${DOC}.snd >/dev/null 2>/dev/null
+ makeindex ${DOC}.cdx -o ${DOC}.cnd >/dev/null 2>/dev/null
+ latex -interaction=batchmode ${DOC}.tex
+
+pdf:
+ @echo "Making pdfm"
+ @cp -fp ${IMAGES}/hires/*.eps .
+ dvipdfm -p a4 ${DOC}.dvi
+
+dvipdf:
+ @echo "Making dvi to pdf"
+ @cp -fp ${IMAGES}/hires/*.eps .
+ dvipdf ${DOC}.dvi ${DOC}.pdf
+
+html:
+ @echo " "
+ @echo "Making html"
+ @cp -fp ${IMAGES}/*.eps .
+ @rm -f next.eps next.png prev.eps prev.png up.eps up.png
+ @(if [ -f imagename_translations ] ; then \
+ ./translate_images.pl --from_meaningful_names ${DOC}.html; \
+ fi)
+ latex2html -white -no_subdir -split 0 -toc_stars -white -notransparent \
+ -init_file latex2html-init.pl ${DOC} >tex.out 2>&1
+ ./translate_images.pl --to_meaningful_names ${DOC}.html
+ @echo "Done making html"
+
+web:
+ @echo "Making web"
+ @mkdir -p ${DOC}
+ @cp -fp ${IMAGES}/*.eps .
+ @rm -f next.eps next.png prev.eps prev.png up.eps up.png
+ @cp -fp ${IMAGES}/*.eps ${DOC}/
+ @cp -fp ${IMAGES}/*.eps ${IMAGES}/*.png ${DOC}/
+ @rm -f ${DOC}/xp-*.png
+ @rm -f ${DOC}/next.eps ${DOC}/next.png ${DOC}/prev.eps ${DOC}/prev.png ${DOC}/up.eps ${DOC}/up.png
+ @rm -rf ${DOC}/*.html
+ latex2html -split 3 -local_icons -t "Bacula Installation and Configuration Guide" -long_titles 4 \
+ -toc_stars -contents_in_nav -init_file latex2html-init.pl -white -notransparent ${DOC} >tex.out 2>&1
+ ./translate_images.pl --to_meaningful_names ${DOC}/Bacula_Instal_Config_Guide.html
+ @echo "Done making web"
+show:
+ xdvi ${DOC}
+
+texcheck:
+ ./check_tex.pl ${DOC}.tex
+
+main_configs:
+ pic2graph -density 100 <main_configs.pic >main_configs.png
+
+mini-clean:
+ @rm -f 1 2 3 *.tex~
+ @rm -f *.gif *.jpg *.eps
+ @rm -f *.aux *.cp *.fn *.ky *.log *.pg
+ @rm -f *.backup *.ilg *.lof *.lot
+ @rm -f *.cdx *.cnd *.ddx *.ddn *.fdx *.fnd *.ind *.sdx *.snd
+ @rm -f *.dnd *.old *.out
+ @rm -f ${DOC}/*.gif ${DOC}/*.jpg ${DOC}/*.eps
+ @rm -f ${DOC}/*.aux ${DOC}/*.cp ${DOC}/*.fn ${DOC}/*.ky ${DOC}/*.log ${DOC}/*.pg
+ @rm -f ${DOC}/*.backup ${DOC}/*.ilg ${DOC}/*.lof ${DOC}/*.lot
+ @rm -f ${DOC}/*.cdx ${DOC}/*.cnd ${DOC}/*.ddx ${DOC}/*.ddn ${DOC}/*.fdx ${DOC}/*.fnd ${DOC}/*.ind ${DOC}/*.sdx ${DOC}/*.snd
+ @rm -f ${DOC}/*.dnd ${DOC}/*.old ${DOC}/*.out
+ @rm -f ${DOC}/WARNINGS
+
+
+clean:
+ @rm -f 1 2 3 *.tex~
+ @rm -f *.png *.gif *.jpg *.eps
+ @rm -f *.pdf *.aux *.cp *.fn *.ky *.log *.pg
+ @rm -f *.html *.backup *.ps *.dvi *.ilg *.lof *.lot
+ @rm -f *.cdx *.cnd *.ddx *.ddn *.fdx *.fnd *.ind *.sdx *.snd
+ @rm -f *.dnd imagename_translations
+ @rm -f *.old WARNINGS *.out *.toc *.idx
+ @rm -f ${DOC}i-*.tex
+ @rm -rf ${DOC}
+
+
+distclean: clean
+ @rm -f images.pl labels.pl internals.pl
+ @rm -f Makefile version.tex
--- /dev/null
+#
+#
+# Makefile for LaTeX
+#
+# To build everything do
+# make tex
+# make web
+# make html
+# make dvipdf
+#
+# or simply
+#
+# make
+#
+
+IMAGES=../../../images
+
+first_rule: bacula
+
+bacula: tex web html dvipdf
+
+.SUFFIXES: .tex .html
+.PHONY:
+.DONTCARE:
+
+
+tex:
+ @cp -fp ${IMAGES}/hires/*.eps .
+ touch install.idx installi-general.tex
+ -latex -interaction=batchmode install.tex
+ makeindex install.idx >/dev/null 2>/dev/null
+ -latex -interaction=batchmode install.tex
+
+pdf:
+ @echo "Making install pdf"
+ @cp -fp ${IMAGES}/hires/*.eps .
+ dvipdf install.dvi install.pdf
+ @rm -f *.eps *.old
+
+dvipdf:
+ @echo "Making install pdfm"
+ @cp -fp ${IMAGES}/hires/*.eps .
+ dvipdfm -p a4 install.dvi
+ @rm -f *.eps *.old
+
+html:
+ @echo "Making install html"
+ @cp -fp ${IMAGES}/*.eps .
+ @rm -f next.eps next.png prev.eps prev.png up.eps up.png
+ @(if [ -f imagename_translations ] ; then \
+ ./translate_images.pl --from_meaningful_names install.html; \
+ fi)
+ latex2html -white -no_subdir -split 0 -toc_stars -white -notransparent \
+ install >/dev/null
+ ./translate_images.pl --to_meaningful_names install.html
+ @rm -f *.eps *.gif *.jpg *.old
+
+web:
+ @echo "Making install web"
+ @mkdir -p install
+ @rm -f install/*
+ @cp -fp ${IMAGES}/*.eps .
+ @rm -f next.eps next.png prev.eps prev.png up.eps up.png
+ @cp -fp ${IMAGES}/*.eps ${IMAGES}/*.png install/
+ @rm -f install/next.eps install/next.png install/prev.eps install/prev.png install/up.eps install/up.png
+ @(if [ -f install/imagename_translations ] ; then \
+ ./translate_images.pl --to_meaningful_names install/Bacula_Users_Guide.html; \
+ fi)
+ @rm -rf install/*.html
+ latex2html -split 3 -local_icons -t "Developer's Guide" \
+ -long_titles 4 -contents_in_nav -toc_stars -white \
+ -notransparent install >/dev/null
+ ./translate_images.pl --to_meaningful_names install/install_Guide.html
+ @cp -f install/install_Guide.html install/index.html
+ @rm -f *.eps *.gif *.jpg install/*.eps *.old
+ @rm -f install/idle.png
+ @rm -f install/win32-*.png install/wx-console*.png install/xp-*.png
+ @rm -f install/*.pl install/*.log install/*.aux install/*.idx
+ @rm -f install/*.out WARNINGS
+
+texcheck:
+ ./check_tex.pl install.tex
+
+main_configs:
+ pic2graph -density 100 <main_configs.pic >main_configs.png
+
+clean:
+ @rm -f 1 2 3
+ @rm -f *.png *.gif *.jpg *.eps
+ @rm -f *.pdf *.aux *.cp *.fn *.ky *.log *.pg
+ @rm -f *.html *.backup *.pdf *.ps *.dvi *.ilg *.lof *.lot
+ @rm -f *.cdx *.cnd *.ddx *.ddn *.fdx *.fnd *.ind *.sdx *.snd
+ @rm -f *.dnd imagename_translations
+ @rm -f *.old WARNINGS *.out *.toc *.idx
+ @rm -f images.pl labels.pl internals.pl
+ @rm -rf install
+ @rm -f images.tex installi-general.tex
+
+
+distclean: clean
+ @rm -f install.html install.pdf
--- /dev/null
+%%
+\chapter{Autochanger Resource}
+\index[sd]{Autochanger Resource}
+\index[sd]{Resource!Autochanger}
+
+The Autochanger resource supports single or multiple drive
+autochangers by grouping one or more Device resources
+into one unit called an autochanger in Bacula (often referred to
+as a "tape library" by autochanger manufacturers).
+
+If you have an Autochanger, and you want it to function correctly,
+you {\bf must} have an Autochanger resource in your Storage
+conf file, and your Director's Storage directives that want to
+use an Autochanger {\bf must} refer to the Autochanger resource name.
+In previous versions of Bacula, the Director's Storage directives
+referred directly to Device resources that were autochangers.
+In version 1.38.0 and later, referring directly to Device resources
+will not work for Autochangers.
+
+\begin{description}
+\item [Name = \lt{}Autochanger-Name\gt{}]
+ \index[sd]{Name}
+ Specifies the Name of the Autochanger. This name is used in the
+ Director's Storage definition to refer to the autochanger. This
+ directive is required.
+
+\item [Device = \lt{}Device-name1, device-name2, ...\gt{}]
+ Specifies the names of the Device resource or resources that correspond
+ to the autochanger drive. If you have a multiple drive autochanger, you
+ must specify multiple Device names, each one referring to a separate
+ Device resource that contains a Drive Index specification that
+ corresponds to the drive number base zero. You may specify multiple
+ device names on a single line separated by commas, and/or you may
+ specify multiple Device directives. This directive is required.
+
+\item [Changer Device = {\it name-string}]
+ \index[sd]{Changer Device}
+ The specified {\bf name-string} gives the system file name of the autochanger
+ device name. If specified in this resource, the Changer Device name
+ is not needed in the Device resource. If it is specified in the Device
+ resource (see above), it will take precedence over one specified in
+ the Autochanger resource.
+
+\item [Changer Command = {\it name-string}]
+ \index[sd]{Changer Command }
+ The {\bf name-string} specifies an external program to be called that will
+ automatically change volumes as required by {\bf Bacula}. Most frequently,
+ you will specify the Bacula supplied {\bf mtx-changer} script as follows.
+ If it is specified here, it need not be specified in the Device
+ resource. If it is also specified in the Device resource, it will take
+ precedence over the one specified in the Autochanger resource.
+
+\end{description}
+
+The following is an example of a valid Autochanger resource definition:
+
+\footnotesize
+\begin{verbatim}
+Autochanger {
+ Name = "DDS-4-changer"
+ Device = DDS-4-1, DDS-4-2, DDS-4-3
+ Changer Device = /dev/sg0
+ Changer Command = "/etc/bacula/mtx-changer %c %o %S %a %d"
+}
+Device {
+ Name = "DDS-4-1"
+ Drive Index = 0
+ Autochanger = yes
+ ...
+}
+Device {
+ Name = "DDS-4-2"
+ Drive Index = 1
+ Autochanger = yes
+ ...
+Device {
+ Name = "DDS-4-3"
+ Drive Index = 2
+ Autochanger = yes
+ Autoselect = no
+ ...
+}
+\end{verbatim}
+\normalsize
+
+Please note that it is important to include the {\bf Autochanger = yes} directive
+in each Device definition that belongs to an Autochanger. A device definition
+should not belong to more than one Autochanger resource. Also, your Device
+directive in the Storage resource of the Director's conf file should have
+the Autochanger's resource name rather than a name of one of the Devices.
+
+If you have a drive that physically belongs to an Autochanger but you don't want
+to have it automatically used when Bacula references the Autochanger for backups,
+for example, you want to reserve it for restores, you can add the directive:
+
+\footnotesize
+\begin{verbatim}
+Autoselect = no
+\end{verbatim}
+\normalsize
+
+to the Device resource for that drive. In that case, Bacula will not automatically
+select that drive when accessing the Autochanger. You can, still use the drive
+by referencing it by the Device name directly rather than the Autochanger name. An example
+of such a definition is shown above for the Device DDS-4-3, which will not be
+selected when the name DDS-4-changer is used in a Storage definition, but will
+be used if DDS-4-3 is used.
--- /dev/null
+#!/usr/bin/perl -w
+# Finds potential problems in tex files, and issues warnings to the console
+# about what it finds. Takes a list of files as its only arguments,
+# and does checks on all the files listed. The assumption is that these are
+# valid (or close to valid) LaTeX files. It follows \include statements
+# recursively to pick up any included tex files.
+#
+#
+#
+# Currently the following checks are made:
+#
+# -- Multiple hyphens not inside a verbatim environment (or \verb). These
+# should be placed inside a \verb{} contruct so they will not be converted
+# to single hyphen by latex and latex2html.
+
+
+# Original creation 3-8-05 by Karl Cunningham karlc -at- keckec -dot- com
+#
+#
+
+use strict;
+
+# The following builds the test string to identify and change multiple
+# hyphens in the tex files. Several constructs are identified but only
+# multiple hyphens are changed; the others are fed to the output
+# unchanged.
+my $b = '\\\\begin\\*?\\s*\\{\\s*'; # \begin{
+my $e = '\\\\end\\*?\\s*\\{\\s*'; # \end{
+my $c = '\\s*\\}'; # closing curly brace
+
+# This captures entire verbatim environments. These are passed to the output
+# file unchanged.
+my $verbatimenv = $b . "verbatim" . $c . ".*?" . $e . "verbatim" . $c;
+
+# This captures \verb{..{ constructs. They are passed to the output unchanged.
+my $verb = '\\\\verb\\*?(.).*?\\1';
+
+# This captures multiple hyphens with a leading and trailing space. These are not changed.
+my $hyphsp = '\\s\\-{2,}\\s';
+
+# This identifies other multiple hyphens.
+my $hyphens = '\\-{2,}';
+
+# This identifies \hyperpage{..} commands, which should be ignored.
+my $hyperpage = '\\\\hyperpage\\*?\\{.*?\\}';
+
+# This builds the actual test string from the above strings.
+#my $teststr = "$verbatimenv|$verb|$tocentry|$hyphens";
+my $teststr = "$verbatimenv|$verb|$hyphsp|$hyperpage|$hyphens";
+
+
+sub get_includes {
+ # Get a list of include files from the top-level tex file. The first
+ # argument is a pointer to the list of files found. The rest of the
+ # arguments is a list of filenames to check for includes.
+ my $files = shift;
+ my ($fileline,$includefile,$includes);
+
+ while (my $filename = shift) {
+ # Get a list of all the html files in the directory.
+ open my $if,"<$filename" or die "Cannot open input file $filename\n";
+ $fileline = 0;
+ $includes = 0;
+ while (<$if>) {
+ chomp;
+ $fileline++;
+ # If a file is found in an include, process it.
+ if (($includefile) = /\\include\s*\{(.*?)\}/) {
+ $includes++;
+ # Append .tex to the filename
+ $includefile .= '.tex';
+
+ # If the include file has already been processed, issue a warning
+ # and don't do it again.
+ my $found = 0;
+ foreach (@$files) {
+ if ($_ eq $includefile) {
+ $found = 1;
+ last;
+ }
+ }
+ if ($found) {
+ print "$includefile found at line $fileline in $filename was previously included\n";
+ } else {
+ # The file has not been previously found. Save it and
+ # recursively process it.
+ push (@$files,$includefile);
+ get_includes($files,$includefile);
+ }
+ }
+ }
+ close IF;
+ }
+}
+
+
+sub check_hyphens {
+ my (@files) = @_;
+ my ($filedata,$this,$linecnt,$before);
+
+ # Build the test string to check for the various environments.
+ # We only do the conversion if the multiple hyphens are outside of a
+ # verbatim environment (either \begin{verbatim}...\end{verbatim} or
+ # \verb{--}). Capture those environments and pass them to the output
+ # unchanged.
+
+ foreach my $file (@files) {
+ # Open the file and load the whole thing into $filedata. A bit wasteful but
+ # easier to deal with, and we don't have a problem with speed here.
+ $filedata = "";
+ open IF,"<$file" or die "Cannot open input file $file";
+ while (<IF>) {
+ $filedata .= $_;
+ }
+ close IF;
+
+ # Set up to process the file data.
+ $linecnt = 1;
+
+ # Go through the file data from beginning to end. For each match, save what
+ # came before it and what matched. $filedata now becomes only what came
+ # after the match.
+ # Chech the match to see if it starts with a multiple-hyphen. If so
+ # warn the user. Keep track of line numbers so they can be output
+ # with the warning message.
+ while ($filedata =~ /$teststr/os) {
+ $this = $&;
+ $before = $`;
+ $filedata = $';
+ $linecnt += $before =~ tr/\n/\n/;
+
+ # Check if the multiple hyphen is present outside of one of the
+ # acceptable constructs.
+ if ($this =~ /^\-+/) {
+ print "Possible unwanted multiple hyphen found in line ",
+ "$linecnt of file $file\n";
+ }
+ $linecnt += $this =~ tr/\n/\n/;
+ }
+ }
+}
+##################################################################
+# MAIN ####
+##################################################################
+
+my (@includes,$cnt);
+
+# Examine the file pointed to by the first argument to get a list of
+# includes to test.
+get_includes(\@includes,@ARGV);
+
+check_hyphens(@includes);
--- /dev/null
+%%
+%%
+
+\chapter{Customizing the Configuration Files}
+\label{ConfigureChapter}
+\index[general]{Files!Customizing the Configuration }
+\index[general]{Customizing the Configuration Files }
+
+When each of the Bacula programs starts, it reads a configuration file
+specified on the command line or the default {\bf bacula-dir.conf}, {\bf
+bacula-fd.conf}, {\bf bacula-sd.conf}, or {\bf console.conf} for the Director
+daemon, the File daemon, the Storage daemon, and the Console program
+respectively.
+
+Each service (Director, Client, Storage, Console) has its own configuration
+file containing a set of Resource definitions. These resources are very
+similar from one service to another, but may contain different directives
+(records) depending on the service. For example, in the Director's resource
+file, the {\bf Director} resource defines the name of the Director, a number
+of global Director parameters and his password. In the File daemon
+configuration file, the {\bf Director} resource specifies which Directors are
+permitted to use the File daemon.
+
+Before running Bacula for the first time, you must customize the configuration
+files for each daemon. Default configuration files will have been created by
+the installation process, but you will need to modify them to correspond to
+your system. An overall view of the resources can be seen in the following:
+
+\addcontentsline{lof}{figure}{Bacula Objects}
+\includegraphics{./bacula-objects.eps}
+\\
+(thanks to Aristides Maniatis for the above graphic)
+\label{ResFormat}
+
+\section{Character Sets}
+\index[general]{Character Sets}
+Bacula is designed to handle most character sets of the world,
+US ASCII, German, French, Chinese, ... However, it does this by
+encoding everything in UTF-8, and it expects all configuration files
+(including those read on Win32 machines) to be in UTF-8 format.
+UTF-8 is typically the default on Linux machines, but not on all
+Unix machines, nor on Windows, so you must take some care to ensure
+that your locale is set properly before starting Bacula.
+
+To ensure that Bacula configuration files can be correctly read including
+foreign characters the {bf LANG} environment variable
+must end in {\bf .UTF-8}. An full example is {\bf en\_US.UTF-8}. The
+exact syntax may vary a bit from OS to OS, and exactly how you define
+it will also vary. On most newer Win32 machines, you can use {\bf notepad}
+to edit the conf files, then choose output encoding UTF-8.
+
+Bacula assumes that all filenames are in UTF-8 format on Linux and
+Unix machines. On Win32 they are in Unicode (UTF-16), and will
+be automatically converted to UTF-8 format.
+
+\section{Resource Directive Format}
+\index[general]{Resource Directive Format }
+\index[general]{Format!Resource Directive }
+
+Although, you won't need to know the details of all the directives a basic
+knowledge of Bacula resource directives is essential. Each directive contained
+within the resource (within the braces) is composed of a keyword followed by
+an equal sign (=) followed by one or more values. The keywords must be one of
+the known Bacula resource record keywords, and it may be composed of upper or
+lower case characters and spaces.
+
+Each resource definition MUST contain a Name directive, and may optionally
+contain a Description directive. The Name directive is used to
+uniquely identify the resource. The Description directive is (will be) used
+during display of the Resource to provide easier human recognition. For
+example:
+
+\footnotesize
+\begin{verbatim}
+Director {
+ Name = "MyDir"
+ Description = "Main Bacula Director"
+ WorkingDirectory = "$HOME/bacula/bin/working"
+}
+\end{verbatim}
+\normalsize
+
+Defines the Director resource with the name "MyDir" and a working directory
+\$HOME/bacula/bin/working. In general, if you want spaces in a name to the
+right of the first equal sign (=), you must enclose that name within double
+quotes. Otherwise quotes are not generally necessary because once defined,
+quoted strings and unquoted strings are all equal.
+
+\label{Comments}
+\subsection{Comments}
+\index[general]{Comments}
+
+When reading the configuration file, blank lines are ignored and everything
+after a hash sign (\#) until the end of the line is taken to be a comment. A
+semicolon (;) is a logical end of line, and anything after the semicolon is
+considered as the next statement. If a statement appears on a line by itself,
+a semicolon is not necessary to terminate it, so generally in the examples in
+this manual, you will not see many semicolons.
+\label{Case1}
+
+\subsection{Upper and Lower Case and Spaces}
+\index[general]{Spaces!Upper/Lower Case}
+\index[general]{Upper and Lower Case and Spaces}
+
+Case (upper/lower) and spaces are totally ignored in the resource directive
+keywords (the part before the equal sign).
+
+Within the keyword (i.e. before the equal sign), spaces are not significant.
+Thus the keywords: {\bf name}, {\bf Name}, and {\bf N a m e} are all
+identical.
+
+Spaces after the equal sign and before the first character of the value are
+ignored.
+
+In general, spaces within a value are significant (not ignored), and if the
+value is a name, you must enclose the name in double quotes for the spaces to
+be accepted. Names may contain up to 127 characters. Currently, a name may
+contain any ASCII character. Within a quoted string, any character following a
+backslash (\textbackslash{}) is taken as itself (handy for inserting
+backslashes and double quotes (")).
+
+Please note, however, that Bacula resource names as well as certain other
+names (e.g. Volume names) must contain only letters (including ISO accented
+letters), numbers, and a few special characters (space, underscore, ...).
+All other characters and punctuation are invalid.
+
+\label{Includes}
+\subsection{Including other Configuration Files}
+\index[general]{Including other Configuration Files }
+\index[general]{Files!Including other Configuration }
+\index[general]{Using @ to include other files}
+\index[general]{@{\bf filename}}
+
+If you wish to break your configuration file into smaller pieces, you can do
+so by including other files using the syntax @{\bf filename} where {\bf
+filename} is the full path and filename of another file. The @filename
+specification can be given anywhere a primitive token would appear.
+
+\label{DataTypes}
+\subsection{Recognized Primitive Data Types}
+\index[general]{Types!Recognized Primitive Data }
+\index[general]{Recognized Primitive Data Types }
+
+When parsing the resource directives, Bacula classifies the data according to
+the types listed below. The first time you read this, it may appear a bit
+overwhelming, but in reality, it is all pretty logical and straightforward.
+
+\begin{description}
+
+\item [name]
+ \index[fd]{name}
+ A keyword or name consisting of alphanumeric characters, including the
+hyphen, underscore, and dollar characters. The first character of a {\bf
+name} must be a letter. A name has a maximum length currently set to 127
+bytes. Typically keywords appear on the left side of an equal (i.e. they are
+Bacula keywords -- i.e. Resource names or directive names). Keywords may not
+be quoted.
+
+\item [name-string]
+ \index[fd]{name-string}
+ A name-string is similar to a name, except that the name may be quoted and
+can thus contain additional characters including spaces. Name strings are
+limited to 127 characters in length. Name strings are typically used on the
+right side of an equal (i.e. they are values to be associated with a keyword).
+
+
+\item [string]
+ \index[fd]{string}
+ A quoted string containing virtually any character including spaces, or a
+non-quoted string. A string may be of any length. Strings are typically
+values that correspond to filenames, directories, or system command names. A
+backslash (\textbackslash{}) turns the next character into itself, so to
+include a double quote in a string, you precede the double quote with a
+backslash. Likewise to include a backslash.
+
+\item [directory]
+ \index[dir]{directory}
+ A directory is either a quoted or non-quoted string. A directory will be
+passed to your standard shell for expansion when it is scanned. Thus
+constructs such as {\bf \$HOME} are interpreted to be their correct values.
+
+\item [password]
+ \index[dir]{password}
+ This is a Bacula password and it is stored internally in MD5 hashed format.
+
+\item [integer]
+ \index[dir]{integer}
+ A 32 bit integer value. It may be positive or negative.
+
+\item [positive integer]
+ \index[dir]{positive integer }
+ A 32 bit positive integer value.
+
+\item [long integer]
+ \index[dir]{long integer}
+ A 64 bit integer value. Typically these are values such as bytes that can
+exceed 4 billion and thus require a 64 bit value.
+
+\item [yes|no]
+ \index[dir]{yes or no }
+ Either a {\bf yes} or a {\bf no}.
+
+\label{Size1}
+\item [size]
+\index[dir]{size}
+A size specified as bytes. Typically, this is a floating point scientific
+input format followed by an optional modifier. The floating point input is
+stored as a 64 bit integer value. If a modifier is present, it must
+immediately follow the value with no intervening spaces. The following
+modifiers are permitted:
+
+\begin{description}
+\item [k]
+ 1,024 (kilobytes)
+
+\item [kb]
+ 1,000 (kilobytes)
+
+\item [m]
+ 1,048,576 (megabytes)
+
+\item [mb]
+ 1,000,000 (megabytes)
+
+\item [g]
+ 1,073,741,824 (gigabytes)
+
+\item [gb]
+ 1,000,000,000 (gigabytes)
+\end{description}
+
+\label{Time}
+\item [time]
+\index[dir]{time}
+A time or duration specified in seconds. The time is stored internally as
+a 64 bit integer value, but it is specified in two parts: a number part and
+a modifier part. The number can be an integer or a floating point number.
+If it is entered in floating point notation, it will be rounded to the
+nearest integer. The modifier is mandatory and follows the number part,
+either with or without intervening spaces. The following modifiers are
+permitted:
+
+\begin{description}
+
+\item [seconds]
+ \index[dir]{seconds}
+ seconds
+
+\item [minutes]
+ \index[dir]{minutes}
+ minutes (60 seconds)
+
+\item [hours]
+ \index[dir]{hours }
+ hours (3600 seconds)
+
+\item [days]
+ \index[dir]{days}
+ days (3600*24 seconds)
+
+\item [weeks]
+ \index[dir]{weeks}
+ weeks (3600*24*7 seconds)
+
+\item [months]
+ \index[dir]{months }
+ months (3600*24*30 seconds)
+
+\item [quarters]
+ \index[dir]{quarters }
+ quarters (3600*24*91 seconds)
+
+\item [years]
+ \index[dir]{years }
+ years (3600*24*365 seconds)
+\end{description}
+
+Any abbreviation of these modifiers is also permitted (i.e. {\bf seconds}
+may be specified as {\bf sec} or {\bf s}). A specification of {\bf m} will
+be taken as months.
+
+The specification of a time may have as many number/modifier parts as you
+wish. For example:
+
+\footnotesize
+\begin{verbatim}
+1 week 2 days 3 hours 10 mins
+1 month 2 days 30 sec
+
+\end{verbatim}
+\normalsize
+
+are valid date specifications.
+
+\end{description}
+
+\label{ResTypes}
+\section{Resource Types}
+\index[general]{Types!Resource }
+\index[general]{Resource Types }
+
+The following table lists all current Bacula resource types. It shows what
+resources must be defined for each service (daemon). The default configuration
+files will already contain at least one example of each permitted resource, so
+you need not worry about creating all these kinds of resources from scratch.
+
+\addcontentsline{lot}{table}{Resource Types}
+\begin{longtable}{|l|l|l|l|l|}
+ \hline
+\multicolumn{1}{|c| }{\bf Resource } & \multicolumn{1}{c| }{\bf Director } &
+\multicolumn{1}{c| }{\bf Client } & \multicolumn{1}{c| }{\bf Storage } &
+\multicolumn{1}{c| }{\bf Console } \\
+ \hline
+{Autochanger } & {No } & {No } & {Yes } & {No } \\
+\hline
+{Catalog } & {Yes } & {No } & {No } & {No } \\
+ \hline
+{Client } & {Yes } & {Yes } & {No } & {No } \\
+ \hline
+{Console } & {Yes } & {No } & {No } & {Yes } \\
+ \hline
+{Device } & {No } & {No } & {Yes } & {No } \\
+ \hline
+{Director } & {Yes } & {Yes } & {Yes } & {Yes } \\
+ \hline
+{FileSet } & {Yes } & {No } & {No } & {No } \\
+ \hline
+{Job } & {Yes } & {No } & {No } & {No } \\
+ \hline
+{JobDefs } & {Yes } & {No } & {No } & {No } \\
+ \hline
+{Message } & {Yes } & {Yes } & {Yes } & {No } \\
+ \hline
+{Pool } & {Yes } & {No } & {No } & {No } \\
+ \hline
+{Schedule } & {Yes } & {No } & {No } & {No } \\
+ \hline
+{Storage } & {Yes } & {No } & {Yes } & {No }
+\\ \hline
+
+\end{longtable}
+
+\section{Names, Passwords and Authorization}
+\label{Names}
+\index[general]{Authorization!Names Passwords and }
+\index[general]{Names, Passwords and Authorization }
+\index[general]{Passwords}
+
+In order for one daemon to contact another daemon, it must authorize itself
+with a password. In most cases, the password corresponds to a particular name,
+so both the name and the password must match to be authorized. Passwords are
+plain text, any text. They are not generated by any special process; just
+use random text.
+
+The default configuration files are automatically defined for correct
+authorization with random passwords. If you add to or modify these files, you
+will need to take care to keep them consistent.
+
+Here is sort of a picture of what names/passwords in which files/Resources
+must match up:
+
+\includegraphics{./Conf-Diagram.eps}
+
+In the left column, you will find the Director, Storage, and Client resources,
+with their names and passwords -- these are all in {\bf bacula-dir.conf}. In
+the right column are where the corresponding values should be found in the
+Console, Storage daemon (SD), and File daemon (FD) configuration files.
+
+Please note that the Address, {\bf fd-sd}, that appears in the Storage
+resource of the Director, preceded with and asterisk in the above example, is
+passed to the File daemon in symbolic form. The File daemon then resolves it
+to an IP address. For this reason, you must use either an IP address or a
+fully qualified name. A name such as {\bf localhost}, not being a fully
+qualified name, will resolve in the File daemon to the localhost of the File
+daemon, which is most likely not what is desired. The password used for the
+File daemon to authorize with the Storage daemon is a temporary password
+unique to each Job created by the daemons and is not specified in any .conf
+file.
+
+\section{Detailed Information for each Daemon}
+\index[general]{Detailed Information for each Daemon }
+\index[general]{Daemon!Detailed Information for each }
+
+The details of each Resource and the directives permitted therein are
+described in the following chapters.
+
+The following configuration files must be defined:
+
+\begin{itemize}
+\item
+ \ilink{Console}{ConsoleConfChapter} -- to define the resources for
+ the Console program (user interface to the Director). It defines which
+Directors are available so that you may interact with them.
+\item
+ \ilink{Director}{DirectorChapter} -- to define the resources
+ necessary for the Director. You define all the Clients and Storage daemons
+that you use in this configuration file.
+\item
+ \ilink{Client}{FiledConfChapter} -- to define the resources for
+ each client to be backed up. That is, you will have a separate Client
+resource file on each machine that runs a File daemon.
+\item
+ \ilink{Storage}{StoredConfChapter} -- to define the resources to
+ be used by each Storage daemon. Normally, you will have a single Storage
+daemon that controls your tape drive or tape drives. However, if you have
+tape drives on several machines, you will have at least one Storage daemon
+per machine.
+\end{itemize}
--- /dev/null
+%%
+%%
+
+\chapter{Console Configuration}
+\label{ConsoleConfChapter}
+\index[general]{Configuration!Console}
+\index[general]{Console Configuration}
+
+\section{General}
+\index[general]{General}
+
+The Console configuration file is the simplest of all the configuration files,
+and in general, you should not need to change it except for the password. It
+simply contains the information necessary to contact the Director or
+Directors.
+
+For a general discussion of the syntax of configuration files and their
+resources including the data types recognized by {\bf Bacula}, please see
+the \ilink{Configuration}{ConfigureChapter} chapter of this manual.
+
+The following Console Resource definition must be defined:
+
+\section{The Director Resource}
+\label{DirectorResource3}
+\index[general]{Director Resource}
+\index[general]{Resource!Director}
+
+The Director resource defines the attributes of the Director running on the
+network. You may have multiple Director resource specifications in a single
+Console configuration file. If you have more than one, you will be prompted to
+choose one when you start the {\bf Console} program.
+
+\begin{description}
+\item [Director]
+ \index[console]{Director}
+ Start of the Director directives.
+
+\item [Name = \lt{}name\gt{}]
+ \index[console]{Name}
+ The director name used to select among different Directors, otherwise, this
+ name is not used.
+
+\item [DIRPort = \lt{}port-number\gt{}]
+ \index[dir]{DIRPort}
+ Specify the port to use to connect to the Director. This value will most
+ likely already be set to the value you specified on the {\bf
+ \verb:--:with-base-port} option of the {\bf ./configure} command. This port must be
+ identical to the {\bf DIRport} specified in the {\bf Director} resource of
+ the \ilink{Director's configuration}{DirectorChapter} file. The
+ default is 9101 so this directive is not normally specified.
+
+\item [Address = \lt{}address\gt{}]
+ \index[dir]{Address}
+ Where the address is a host name, a fully qualified domain name, or a network
+ address used to connect to the Director.
+
+\item [Password = \lt{}password\gt{}]
+ \index[dir]{Password}
+ Where the password is the password needed for the Director to accept the
+ Console connection. This password must be identical to the {\bf Password}
+ specified in the {\bf Director} resource of the
+ \ilink{Director's configuration}{DirectorChapter} file. This
+ directive is required.
+\end{description}
+
+An actual example might be:
+
+\footnotesize
+\begin{verbatim}
+Director {
+ Name = HeadMan
+ address = rufus.cats.com
+ password = xyz1erploit
+}
+\end{verbatim}
+\normalsize
+
+\section{The ConsoleFont Resource}
+\index[general]{Resource!ConsoleFont}
+\index[general]{ConsoleFont Resource}
+
+The ConsoleFont resource is available only in the GNOME version of the
+console. It permits you to define the font that you want used to display in
+the main listing window.
+
+\begin{description}
+
+\item [ConsoleFont]
+ \index[console]{ConsoleFont}
+ Start of the ConsoleFont directives.
+
+\item [Name = \lt{}name\gt{}]
+ \index[console]{Name}
+ The name of the font.
+
+\item [Font = \lt{}Pango Font Name\gt{}]
+ \index[console]{Font}
+ The string value given here defines the desired font. It is specified in the
+ Pango format. For example, the default specification is:
+
+\footnotesize
+\begin{verbatim}
+Font = "LucidaTypewriter 9"
+\end{verbatim}
+\normalsize
+
+\end{description}
+
+Thanks to Phil Stracchino for providing the code for this feature.
+
+An different example might be:
+
+\footnotesize
+\begin{verbatim}
+ConsoleFont {
+ Name = Default
+ Font = "Monospace 10"
+}
+\end{verbatim}
+\normalsize
+
+\section{The Console Resource}
+\label{ConsoleResource}
+\index[general]{Console Resource}
+\index[general]{Resource!Console}
+
+As of Bacula version 1.33 and higher, there are three different kinds of
+consoles, which the administrator or user can use to interact with the
+Director. These three kinds of consoles comprise three different security
+levels.
+
+\begin{itemize}
+\item The first console type is an {\bf anonymous} or {\bf default} console,
+ which has full privileges. There is no console resource necessary for this
+ type since the password is specified in the Director resource. This is the
+ kind of console that was initially implemented in versions prior to 1.33 and
+ remains valid. Typically you would use it only for administrators.
+
+\item The second type of console, and new to version 1.33 and higher is a
+ "named" or "restricted" console defined within a Console resource in
+ both the Director's configuration file and in the Console's
+ configuration file. Both the names and the passwords in these two
+ entries must match much as is the case for Client programs.
+
+ This second type of console begins with absolutely no privileges except
+ those explicitly specified in the Director's Console resource. Note,
+ the definition of what these restricted consoles can do is determined
+ by the Director's conf file.
+
+ Thus you may define within the Director's conf file multiple Consoles
+ with different names and passwords, sort of like multiple users, each
+ with different privileges. As a default, these consoles can do
+ absolutely nothing -- no commands what so ever. You give them
+ privileges or rather access to commands and resources by specifying
+ access control lists in the Director's Console resource. This gives the
+ administrator fine grained control over what particular consoles (or
+ users) can do.
+
+\item The third type of console is similar to the above mentioned
+ restricted console in that it requires a Console resource definition in
+ both the Director and the Console. In addition, if the console name,
+ provided on the {\bf Name =} directive, is the same as a Client name,
+ the user of that console is permitted to use the {\bf SetIP} command to
+ change the Address directive in the Director's client resource to the IP
+ address of the Console. This permits portables or other machines using
+ DHCP (non-fixed IP addresses) to "notify" the Director of their current
+ IP address.
+
+\end{itemize}
+
+The Console resource is optional and need not be specified. However, if it is
+specified, you can use ACLs (Access Control Lists) in the Director's
+configuration file to restrict the particular console (or user) to see only
+information pertaining to his jobs or client machine.
+
+You may specify as many Console resources in the console's conf file. If
+you do so, generally the first Console resource will be used. However, if
+you have multiple Director resources (i.e. you want to connect to different
+directors), you can bind one of your Console resources to a particular
+Director resource, and thus when you choose a particular Director, the
+appropriate Console configuration resource will be used. See the "Director"
+directive in the Console resource described below for more information.
+
+Note, the Console resource is optional, but can be useful for
+restricted consoles as noted above.
+
+\begin{description}
+\item [Console]
+ \index[console]{Console}
+ Start of the Console resource.
+
+\item [Name = \lt{}name\gt{}]
+ \index[console]{Name}
+ The Console name used to allow a restricted console to change
+ its IP address using the SetIP command. The SetIP command must
+ also be defined in the Director's conf CommandACL list.
+
+
+\item [Password = \lt{}password\gt{}]
+ \index[console]{Password}
+ If this password is supplied, then the password specified in the
+ Director resource of you Console conf will be ignored. See below
+ for more details.
+
+\item [Director = \lt{}director-resource-name\gt{}]
+ If this directive is specified, this Console resource will be
+ used by bconsole when that particular director is selected
+ when first starting bconsole. I.e. it binds a particular console
+ resource with its name and password to a particular director.
+
+\item [Heartbeat Interval = \lt{}time-interval\gt{}]
+ \index[console]{Heartbeat Interval}
+ \index[console]{Directive!Heartbeat}
+ This directive is optional and if specified will cause the Console to
+ set a keepalive interval (heartbeat) in seconds on each of the sockets
+ to communicate with the Director. It is implemented only on systems
+ (Linux, ...) that provide the {\bf setsockopt} TCP\_KEEPIDLE function.
+ The default value is zero, which means no change is made to the socket.
+
+\end{description}
+
+
+The following configuration files were supplied by Phil Stracchino. For
+example, if we define the following in the user's bconsole.conf file (or
+perhaps the bwx-console.conf file):
+
+\footnotesize
+\begin{verbatim}
+Director {
+ Name = MyDirector
+ DIRport = 9101
+ Address = myserver
+ Password = "XXXXXXXXXXX" # no, really. this is not obfuscation.
+}
+
+
+Console {
+ Name = restricted-user
+ Password = "UntrustedUser"
+}
+\end{verbatim}
+\normalsize
+
+Where the Password in the Director section is deliberately incorrect, and the
+Console resource is given a name, in this case {\bf restricted-user}. Then
+in the Director's bacula-dir.conf file (not directly accessible by the user),
+we define:
+
+\footnotesize
+\begin{verbatim}
+Console {
+ Name = restricted-user
+ Password = "UntrustedUser"
+ JobACL = "Restricted Client Save"
+ ClientACL = restricted-client
+ StorageACL = main-storage
+ ScheduleACL = *all*
+ PoolACL = *all*
+ FileSetACL = "Restricted Client's FileSet"
+ CatalogACL = DefaultCatalog
+ CommandACL = run
+}
+\end{verbatim}
+\normalsize
+
+the user logging into the Director from his Console will get logged in as {\bf
+restricted-user}, and he will only be able to see or access a Job with the
+name {\bf Restricted Client Save} a Client with the name {\bf
+restricted-client}, a Storage device {\bf main-storage}, any Schedule or Pool,
+a FileSet named {\bf Restricted Client's FileSet}, a Catalog named {\bf
+DefaultCatalog}, and the only command he can use in the Console is the {\bf
+run} command. In other words, this user is rather limited in what he can see
+and do with Bacula.
+
+The following is an example of a bconsole conf file that can access
+several Directors and has different Consoles depending on the director:
+
+\footnotesize
+\begin{verbatim}
+Director {
+ Name = MyDirector
+ DIRport = 9101
+ Address = myserver
+ Password = "XXXXXXXXXXX" # no, really. this is not obfuscation.
+}
+
+Director {
+ Name = SecondDirector
+ DIRport = 9101
+ Address = secondserver
+ Password = "XXXXXXXXXXX" # no, really. this is not obfuscation.
+}
+
+Console {
+ Name = restricted-user
+ Password = "UntrustedUser"
+ Director = MyDirector
+}
+
+Console {
+ Name = restricted-user
+ Password = "A different UntrustedUser"
+ Director = SecondDirector
+}
+\end{verbatim}
+\normalsize
+
+The second Director referenced at "secondserver" might look
+like the following:
+
+\footnotesize
+\begin{verbatim}
+Console {
+ Name = restricted-user
+ Password = "A different UntrustedUser"
+ JobACL = "Restricted Client Save"
+ ClientACL = restricted-client
+ StorageACL = second-storage
+ ScheduleACL = *all*
+ PoolACL = *all*
+ FileSetACL = "Restricted Client's FileSet"
+ CatalogACL = RestrictedCatalog
+ CommandACL = run, restore
+ WhereACL = "/"
+}
+\end{verbatim}
+\normalsize
+
+
+
+\section{Console Commands}
+\index[general]{Console Commands}
+\index[general]{Commands!Console}
+
+For more details on running the console and its commands, please see the
+\ilink{Bacula Console}{_ConsoleChapter} chapter of this manual.
+
+\section{Sample Console Configuration File}
+\label{SampleConfiguration2}
+\index[general]{File!Sample Console Configuration}
+\index[general]{Sample Console Configuration File}
+
+An example Console configuration file might be the following:
+
+\footnotesize
+\begin{verbatim}
+#
+# Bacula Console Configuration File
+#
+Director {
+ Name = HeadMan
+ address = "my_machine.my_domain.com"
+ Password = Console_password
+}
+\end{verbatim}
+\normalsize
--- /dev/null
+%%
+%%
+
+\chapter{Critical Items to Implement Before Production}
+\label{CriticalChapter}
+\index[general]{Production!Critical Items to Implement Before }
+\index[general]{Critical Items to Implement Before Production }
+
+We recommend you take your time before implementing a production a Bacula
+backup system since Bacula is a rather complex program, and if you make a
+mistake, you may suddenly find that you cannot restore your files in case
+of a disaster. This is especially true if you have not previously used a
+major backup product.
+
+If you follow the instructions in this chapter, you will have covered most of
+the major problems that can occur. It goes without saying that if you ever
+find that we have left out an important point, please inform us, so
+that we can document it to the benefit of everyone.
+
+\label{Critical}
+\section{Critical Items}
+\index[general]{Critical Items }
+\index[general]{Items!Critical }
+
+The following assumes that you have installed Bacula, you more or less
+understand it, you have at least worked through the tutorial or have
+equivalent experience, and that you have set up a basic production
+configuration. If you haven't done the above, please do so and then come back
+here. The following is a sort of checklist that points with perhaps a brief
+explanation of why you should do it. In most cases, you will find the
+details elsewhere in the manual. The order is more or less the order you
+would use in setting up a production system (if you already are in
+production, use the checklist anyway).
+
+\begin{itemize}
+\item Test your tape drive for compatibility with Bacula by using the test
+ command in the \ilink{btape}{btape} program.
+\item Better than doing the above is to walk through the nine steps in the
+ \ilink{Tape Testing}{TapeTestingChapter} chapter of the manual. It
+ may take you a bit of time, but it will eliminate surprises.
+\item Test the end of tape handling of your tape drive by using the
+ fill command in the \ilink{btape}{btape} program.
+\item If you are using a Linux 2.4 kernel, make sure that /lib/tls is disabled. Bacula
+ does not work with this library. See the second point under
+ \ilink{ Supported Operating Systems.}{SupportedOSes}
+\item Do at least one restore of files. If you backup multiple OS types
+ (Linux, Solaris, HP, MacOS, FreeBSD, Win32, ...),
+ restore files from each system type. The
+ \ilink{Restoring Files}{RestoreChapter} chapter shows you how.
+\item Write a bootstrap file to a separate system for each backup job. The
+ Write Bootstrap directive is described in the
+ \ilink{Director Configuration}{writebootstrap} chapter of the
+ manual, and more details are available in the
+ \ilink{Bootstrap File}{BootstrapChapter} chapter. Also, the default
+ bacula-dir.conf comes with a Write Bootstrap directive defined. This allows
+ you to recover the state of your system as of the last backup.
+\item Backup your catalog. An example of this is found in the default
+ bacula-dir.conf file. The backup script is installed by default and
+ should handle any database, though you may want to make your own local
+ modifications. See also \ilink{Backing Up Your Bacula Database -
+ Security Considerations }{BackingUpBaculaSecurityConsiderations} for more
+ information.
+\item Write a bootstrap file for the catalog. An example of this is found in
+ the default bacula-dir.conf file. This will allow you to quickly restore your
+ catalog in the event it is wiped out -- otherwise it is many excruciating
+ hours of work.
+\item Make a copy of the bacula-dir.conf, bacula-sd.conf, and
+ bacula-fd.conf files that you are using on your server. Put it in a safe
+ place (on another machine) as these files can be difficult to
+ reconstruct if your server dies.
+\item Make a Bacula Rescue CDROM! See the
+ \ilink{Disaster Recovery Using a Bacula Rescue
+ CDROM}{RescueChapter} chapter. It is trivial to make such a CDROM,
+ and it can make system recovery in the event of a lost hard disk infinitely
+ easier.
+\item Bacula assumes all filenames are in UTF-8 format. This is important
+ when saving the filenames to the catalog. For Win32 machine, Bacula will
+ automatically convert from Unicode to UTF-8, but on Unix, Linux, *BSD,
+ and MacOS X machines, you must explicitly ensure that your locale is set
+ properly. Typically this means that the {bf LANG} environment variable
+ must end in {\bf .UTF-8}. An full example is {\bf en\_US.UTF-8}. The
+ exact syntax may vary a bit from OS to OS, and exactly how you define it
+ will also vary.
+
+ On most modern Win32 machines, you can edit the conf files with {\bf
+ notebook} and choose output encoding UTF-8.
+\end{itemize}
+
+\section{Recommended Items}
+\index[general]{Items!Recommended }
+\index[general]{Recommended Items }
+
+Although these items may not be critical, they are recommended and will help
+you avoid problems.
+
+\begin{itemize}
+\item Read the \ilink{Quick Start Guide to Bacula}{QuickStartChapter}
+\item After installing and experimenting with Bacula, read and work carefully
+ through the examples in the
+ \ilink{Tutorial}{TutorialChapter} chapter of this manual.
+\item Learn what each of the \ilink{Bacula Utility Programs}{_UtilityChapter}
+ does.
+\item Set up reasonable retention periods so that your catalog does not grow
+ to be too big. See the following three chapters:\\
+ \ilink{Recycling your Volumes}{RecyclingChapter},\\
+ \ilink{Basic Volume Management}{DiskChapter},\\
+ \ilink{Using Pools to Manage Volumes}{PoolsChapter}.
+\item Perform a bare metal recovery using the Bacula Rescue CDROM. See the
+ \ilink{Disaster Recovery Using a Bacula Rescue CDROM}{RescueChapter}
+ chapter.
+\end{itemize}
+
+If you absolutely must implement a system where you write a different
+tape each night and take it offsite in the morning. We recommend that you do
+several things:
+\begin{itemize}
+\item Write a bootstrap file of your backed up data and a bootstrap file
+ of your catalog backup to a floppy disk or a CDROM, and take that with
+ the tape. If this is not possible, try to write those files to another
+ computer or offsite computer, or send them as email to a friend. If none
+ of that is possible, at least print the bootstrap files and take that
+ offsite with the tape. Having the bootstrap files will make recovery
+ much easier.
+\item It is better not to force Bacula to load a particular tape each day.
+ Instead, let Bacula choose the tape. If you need to know what tape to
+ mount, you can print a list of recycled and appendable tapes daily, and
+ select any tape from that list. Bacula may propose a particular tape
+ for use that it considers optimal, but it will accept any valid tape
+ from the correct pool.
+\end{itemize}
--- /dev/null
+%%
+%%
+
+\chapter{Configuring the Director}
+\label{DirectorChapter}
+\index[general]{Director!Configuring the}
+\index[general]{Configuring the Director}
+
+Of all the configuration files needed to run {\bf Bacula}, the Director's is
+the most complicated, and the one that you will need to modify the most often
+as you add clients or modify the FileSets.
+
+For a general discussion of configuration files and resources including the
+data types recognized by {\bf Bacula}. Please see the
+\ilink{Configuration}{ConfigureChapter} chapter of this manual.
+
+\section{Director Resource Types}
+\index[general]{Types!Director Resource}
+\index[general]{Director Resource Types}
+
+Director resource type may be one of the following:
+
+Job, JobDefs, Client, Storage, Catalog, Schedule, FileSet, Pool, Director, or
+Messages. We present them here in the most logical order for defining them:
+
+Note, everything revolves around a job and is tied to a job in one
+way or another.
+
+\begin{itemize}
+\item
+ \ilink{Director}{DirectorResource4} -- to define the Director's
+ name and its access password used for authenticating the Console program.
+ Only a single Director resource definition may appear in the Director's
+ configuration file. If you have either {\bf /dev/random} or {\bf bc} on your
+ machine, Bacula will generate a random password during the configuration
+ process, otherwise it will be left blank.
+\item
+ \ilink{Job}{JobResource} -- to define the backup/restore Jobs
+ and to tie together the Client, FileSet and Schedule resources to be used
+ for each Job. Normally, you will Jobs of different names corresponding
+ to each client (i.e. one Job per client, but a different one with a different name
+ for each client).
+\item
+ \ilink{JobDefs}{JobDefsResource} -- optional resource for
+ providing defaults for Job resources.
+\item
+ \ilink{Schedule}{ScheduleResource} -- to define when a Job is to
+ be automatically run by {\bf Bacula's} internal scheduler. You
+ may have any number of Schedules, but each job will reference only
+ one.
+\item
+ \ilink{FileSet}{FileSetResource} -- to define the set of files
+ to be backed up for each Client. You may have any number of
+ FileSets but each Job will reference only one.
+\item
+ \ilink{Client}{ClientResource2} -- to define what Client is to be
+ backed up. You will generally have multiple Client definitions. Each
+ Job will reference only a single client.
+\item
+ \ilink{Storage}{StorageResource2} -- to define on what physical
+ device the Volumes should be mounted. You may have one or
+ more Storage definitions.
+\item
+ \ilink{Pool}{PoolResource} -- to define the pool of Volumes
+ that can be used for a particular Job. Most people use a
+ single default Pool. However, if you have a large number
+ of clients or volumes, you may want to have multiple Pools.
+ Pools allow you to restrict a Job (or a Client) to use
+ only a particular set of Volumes.
+\item
+ \ilink{Catalog}{CatalogResource} -- to define in what database to
+ keep the list of files and the Volume names where they are backed up.
+ Most people only use a single catalog. However, if you want to
+ scale the Director to many clients, multiple catalogs can be helpful.
+ Multiple catalogs require a bit more management because in general
+ you must know what catalog contains what data. Currently, all
+ Pools are defined in each catalog. This restriction will be removed
+ in a later release.
+\item
+ \ilink{Messages}{MessagesChapter} -- to define where error and
+ information messages are to be sent or logged. You may define
+ multiple different message resources and hence direct particular
+ classes of messages to different users or locations (files, ...).
+\end{itemize}
+
+\section{The Director Resource}
+\label{DirectorResource4}
+\index[general]{Director Resource}
+\index[general]{Resource!Director}
+
+The Director resource defines the attributes of the Directors running on the
+network. In the current implementation, there is only a single Director
+resource, but the final design will contain multiple Directors to maintain
+index and media database redundancy.
+
+\begin{description}
+
+\item [Director]
+ \index[dir]{Director}
+ Start of the Director resource. One and only one director resource must be
+supplied.
+
+\item [Name = \lt{}name\gt{}]
+ \index[dir]{Name}
+ \index[dir]{Directive!Name}
+ The director name used by the system administrator. This directive is
+required.
+
+\item [Description = \lt{}text\gt{}]
+ \index[dir]{Description}
+ \index[dir]{Directive!Description}
+ The text field contains a description of the Director that will be displayed
+in the graphical user interface. This directive is optional.
+
+\item [Password = \lt{}UA-password\gt{}]
+ \index[dir]{Password}
+ \index[dir]{Directive!Password}
+ Specifies the password that must be supplied for the default Bacula
+ Console to be authorized. The same password must appear in the {\bf
+ Director} resource of the Console configuration file. For added
+ security, the password is never passed across the network but instead a
+ challenge response hash code created with the password. This directive
+ is required. If you have either {\bf /dev/random} or {\bf bc} on your
+ machine, Bacula will generate a random password during the configuration
+ process, otherwise it will be left blank and you must manually supply
+ it.
+
+ The password is plain text. It is not generated through any special
+ process but as noted above, it is better to use random text for
+ security reasons.
+
+\item [Messages = \lt{}Messages-resource-name\gt{}]
+ \index[dir]{Messages}
+ \index[dir]{Directive!Messages}
+ The messages resource specifies where to deliver Director messages that are
+ not associated with a specific Job. Most messages are specific to a job and
+ will be directed to the Messages resource specified by the job. However,
+ there are a few messages that can occur when no job is running. This
+ directive is required.
+
+\item [Working Directory = \lt{}Directory\gt{}]
+ \index[dir]{Working Directory}
+ \index[dir]{Directive!Working Directory}
+ This directive is mandatory and specifies a directory in which the Director
+ may put its status files. This directory should be used only by Bacula but
+ may be shared by other Bacula daemons. However, please note, if this
+ directory is shared with other Bacula daemons (the File daemon and Storage
+ daemon), you must ensure that the {\bf Name} given to each daemon is
+ unique so that the temporary filenames used do not collide. By default
+ the Bacula configure process creates unique daemon names by postfixing them
+ with -dir, -fd, and -sd. Standard shell expansion of the {\bf
+ Directory} is done when the configuration file is read so that values such
+ as {\bf \$HOME} will be properly expanded. This directive is required.
+ The working directory specified must already exist and be
+ readable and writable by the Bacula daemon referencing it.
+
+ If you have specified a Director user and/or a Director group on your
+ ./configure line with {\bf {-}{-}with-dir-user} and/or
+ {\bf {-}{-}with-dir-group} the Working Directory owner and group will
+ be set to those values.
+
+\item [Pid Directory = \lt{}Directory\gt{}]
+ \index[dir]{Pid Directory}
+ \index[dir]{Directive!Pid Directory}
+ This directive is mandatory and specifies a directory in which the Director
+ may put its process Id file. The process Id file is used to shutdown
+ Bacula and to prevent multiple copies of Bacula from running simultaneously.
+ Standard shell expansion of the {\bf Directory} is done when the
+ configuration file is read so that values such as {\bf \$HOME} will be
+ properly expanded.
+
+ The PID directory specified must already exist and be
+ readable and writable by the Bacula daemon referencing it
+
+ Typically on Linux systems, you will set this to: {\bf /var/run}. If you are
+ not installing Bacula in the system directories, you can use the {\bf Working
+ Directory} as defined above. This directive is required.
+
+\item [Scripts Directory = \lt{}Directory\gt{}]
+ \index[dir]{Scripts Directory}
+ \index[dir]{Directive!Scripts Directory}
+ This directive is optional and, if defined, specifies a directory in
+ which the Director will look for the Python startup script {\bf
+ DirStartup.py}. This directory may be shared by other Bacula daemons.
+ Standard shell expansion of the directory is done when the configuration
+ file is read so that values such as {\bf \$HOME} will be properly
+ expanded.
+
+\item [QueryFile = \lt{}Path\gt{}]
+ \index[dir]{QueryFile}
+ \index[dir]{Directive!QueryFile}
+ This directive is mandatory and specifies a directory and file in which
+ the Director can find the canned SQL statements for the {\bf Query}
+ command of the Console. Standard shell expansion of the {\bf Path} is
+ done when the configuration file is read so that values such as {\bf
+ \$HOME} will be properly expanded. This directive is required.
+
+\label{DirMaxConJobs}
+\item [Maximum Concurrent Jobs = \lt{}number\gt{}]
+\index[dir]{Maximum Concurrent Jobs}
+\index[dir]{Directive!Maximum Concurrent Jobs}
+\index[general]{Simultaneous Jobs}
+\index[general]{Concurrent Jobs}
+ where \lt{}number\gt{} is the maximum number of total Director Jobs that
+ should run concurrently. The default is set to 1, but you may set it to a
+ larger number.
+
+ Please note that the Volume format becomes much more complicated with
+ multiple simultaneous jobs, consequently, restores can take much longer if
+ Bacula must sort through interleaved volume blocks from multiple simultaneous
+ jobs. This can be avoided by having each simultaneously running job write to
+ a different volume or by using data spooling, which will first spool the data
+ to disk simultaneously, then write each spool file to the volume in
+ sequence.
+
+ There may also still be some cases where directives such as {\bf Maximum
+ Volume Jobs} are not properly synchronized with multiple simultaneous jobs
+ (subtle timing issues can arise), so careful testing is recommended.
+
+ At the current time, there is no configuration parameter set to limit the
+ number of console connections. A maximum of five simultaneous console
+ connections are permitted.
+
+\item [FD Connect Timeout = \lt{}time\gt{}]
+ \index[dir]{FD Connect Timeout}
+ \index[dir]{Directive!FD Connect Timeout}
+ where {\bf time} is the time that the Director should continue
+ attempting to contact the File daemon to start a job, and after which
+ the Director will cancel the job. The default is 30 minutes.
+
+\item [SD Connect Timeout = \lt{}time\gt{}]
+ \index[dir]{SD Connect Timeout}
+ \index[dir]{Directive!SD Connect Timeout}
+ where {\bf time} is the time that the Director should continue
+ attempting to contact the Storage daemon to start a job, and after which
+ the Director will cancel the job. The default is 30 minutes.
+
+\item [DirAddresses = \lt{}IP-address-specification\gt{}]
+ \index[dir]{DirAddresses}
+ \index[dir]{Address}
+ \index[general]{Address}
+ \index[dir]{Directive!DirAddresses}
+ Specify the ports and addresses on which the Director daemon will listen
+ for Bacula Console connections. Probably the simplest way to explain
+ this is to show an example:
+
+\footnotesize
+\begin{verbatim}
+ DirAddresses = {
+ ip = { addr = 1.2.3.4; port = 1205;}
+ ipv4 = {
+ addr = 1.2.3.4; port = http;}
+ ipv6 = {
+ addr = 1.2.3.4;
+ port = 1205;
+ }
+ ip = {
+ addr = 1.2.3.4
+ port = 1205
+ }
+ ip = { addr = 1.2.3.4 }
+ ip = { addr = 201:220:222::2 }
+ ip = {
+ addr = bluedot.thun.net
+ }
+}
+\end{verbatim}
+\normalsize
+
+where ip, ip4, ip6, addr, and port are all keywords. Note, that the address
+can be specified as either a dotted quadruple, or IPv6 colon notation, or as
+a symbolic name (only in the ip specification). Also, port can be specified
+as a number or as the mnemonic value from the /etc/services file. If a port
+is not specified, the default will be used. If an ip section is specified,
+the resolution can be made either by IPv4 or IPv6. If ip4 is specified, then
+only IPv4 resolutions will be permitted, and likewise with ip6.
+
+Please note that if you use the DirAddresses directive, you must
+not use either a DirPort or a DirAddress directive in the same
+resource.
+
+\item [DirPort = \lt{}port-number\gt{}]
+ \index[dir]{DirPort}
+ \index[dir]{Directive!DirPort}
+ Specify the port (a positive integer) on which the Director daemon will
+ listen for Bacula Console connections. This same port number must be
+ specified in the Director resource of the Console configuration file. The
+ default is 9101, so normally this directive need not be specified. This
+ directive should not be used if you specify DirAddresses (not plural)
+ directive.
+
+\item [DirAddress = \lt{}IP-Address\gt{}]
+ \index[dir]{DirAddress}
+ \index[dir]{Directive!DirAddress}
+ This directive is optional, but if it is specified, it will cause the
+ Director server (for the Console program) to bind to the specified {\bf
+ IP-Address}, which is either a domain name or an IP address specified as a
+ dotted quadruple in string or quoted string format. If this directive is not
+ specified, the Director will bind to any available address (the default).
+ Note, unlike the DirAddresses specification noted above, this directive only
+ permits a single address to be specified. This directive should not be used if you
+ specify a DirAddresses (note plural) directive.
+
+
+
+\end{description}
+
+The following is an example of a valid Director resource definition:
+
+\footnotesize
+\begin{verbatim}
+Director {
+ Name = HeadMan
+ WorkingDirectory = "$HOME/bacula/bin/working"
+ Password = UA_password
+ PidDirectory = "$HOME/bacula/bin/working"
+ QueryFile = "$HOME/bacula/bin/query.sql"
+ Messages = Standard
+}
+\end{verbatim}
+\normalsize
+
+\section{The Job Resource}
+\label{JobResource}
+\index[general]{Resource!Job}
+\index[general]{Job Resource}
+
+The Job resource defines a Job (Backup, Restore, ...) that Bacula must
+perform. Each Job resource definition contains the name of a Client and
+a FileSet to backup, the Schedule for the Job, where the data
+are to be stored, and what media Pool can be used. In effect, each Job
+resource must specify What, Where, How, and When or FileSet, Storage,
+Backup/Restore/Level, and Schedule respectively. Note, the FileSet must
+be specified for a restore job for historical reasons, but it is no longer used.
+
+Only a single type ({\bf Backup}, {\bf Restore}, ...) can be specified for any
+job. If you want to backup multiple FileSets on the same Client or multiple
+Clients, you must define a Job for each one.
+
+Note, you define only a single Job to do the Full, Differential, and
+Incremental backups since the different backup levels are tied together by
+a unique Job name. Normally, you will have only one Job per Client, but
+if a client has a really huge number of files (more than several million),
+you might want to split it into to Jobs each with a different FileSet
+covering only part of the total files.
+
+
+\begin{description}
+
+\item [Job]
+ \index[dir]{Job}
+ \index[dir]{Directive!Job}
+ Start of the Job resource. At least one Job resource is required.
+
+\item [Name = \lt{}name\gt{}]
+ \index[dir]{Name}
+ \index[dir]{Directive!Name}
+ The Job name. This name can be specified on the {\bf Run} command in the
+ console program to start a job. If the name contains spaces, it must be
+ specified between quotes. It is generally a good idea to give your job the
+ same name as the Client that it will backup. This permits easy
+ identification of jobs.
+
+ When the job actually runs, the unique Job Name will consist of the name you
+ specify here followed by the date and time the job was scheduled for
+ execution. This directive is required.
+
+\item [Enabled = \lt{}yes|no\gt{}]
+ \index[dir]{Enable}
+ \index[dir]{Directive!Enable}
+ This directive allows you to enable or disable automatic execution
+ via the scheduler of a Job.
+
+\item [Type = \lt{}job-type\gt{}]
+ \index[dir]{Type}
+ \index[dir]{Directive!Type}
+ The {\bf Type} directive specifies the Job type, which may be one of the
+ following: {\bf Backup}, {\bf Restore}, {\bf Verify}, or {\bf Admin}. This
+ directive is required. Within a particular Job Type, there are also Levels
+ as discussed in the next item.
+
+\begin{description}
+
+\item [Backup]
+ \index[dir]{Backup}
+ Run a backup Job. Normally you will have at least one Backup job for each
+ client you want to save. Normally, unless you turn off cataloging, most all
+ the important statistics and data concerning files backed up will be placed
+ in the catalog.
+
+\item [Restore]
+ \index[dir]{Restore}
+ Run a restore Job. Normally, you will specify only one Restore job
+ which acts as a sort of prototype that you will modify using the console
+ program in order to perform restores. Although certain basic
+ information from a Restore job is saved in the catalog, it is very
+ minimal compared to the information stored for a Backup job -- for
+ example, no File database entries are generated since no Files are
+ saved.
+
+ {\bf Restore} jobs cannot be
+ automatically started by the scheduler as is the case for Backup, Verify
+ and Admin jobs. To restore files, you must use the {\bf restore} command
+ in the console.
+
+
+\item [Verify]
+ \index[dir]{Verify}
+ Run a verify Job. In general, {\bf verify} jobs permit you to compare the
+ contents of the catalog to the file system, or to what was backed up. In
+ addition, to verifying that a tape that was written can be read, you can
+ also use {\bf verify} as a sort of tripwire intrusion detection.
+
+\item [Admin]
+ \index[dir]{Admin}
+ Run an admin Job. An {\bf Admin} job can be used to periodically run catalog
+ pruning, if you do not want to do it at the end of each {\bf Backup} Job.
+ Although an Admin job is recorded in the catalog, very little data is saved.
+\end{description}
+
+\label{Level}
+
+\item [Level = \lt{}job-level\gt{}]
+\index[dir]{Level}
+\index[dir]{Directive!Level}
+ The Level directive specifies the default Job level to be run. Each
+ different Job Type (Backup, Restore, ...) has a different set of Levels
+ that can be specified. The Level is normally overridden by a different
+ value that is specified in the {\bf Schedule} resource. This directive
+ is not required, but must be specified either by a {\bf Level} directive
+ or as an override specified in the {\bf Schedule} resource.
+
+For a {\bf Backup} Job, the Level may be one of the following:
+
+\begin{description}
+
+\item [Full]
+\index[dir]{Full}
+ When the Level is set to Full all files in the FileSet whether or not
+ they have changed will be backed up.
+
+\item [Incremental]
+ \index[dir]{Incremental}
+ When the Level is set to Incremental all files specified in the FileSet
+ that have changed since the last successful backup of the the same Job
+ using the same FileSet and Client, will be backed up. If the Director
+ cannot find a previous valid Full backup then the job will be upgraded
+ into a Full backup. When the Director looks for a valid backup record
+ in the catalog database, it looks for a previous Job with:
+
+\begin{itemize}
+\item The same Job name.
+\item The same Client name.
+\item The same FileSet (any change to the definition of the FileSet such as
+ adding or deleting a file in the Include or Exclude sections constitutes a
+ different FileSet.
+\item The Job was a Full, Differential, or Incremental backup.
+\item The Job terminated normally (i.e. did not fail or was not canceled).
+\end{itemize}
+
+ If all the above conditions do not hold, the Director will upgrade the
+ Incremental to a Full save. Otherwise, the Incremental backup will be
+ performed as requested.
+
+ The File daemon (Client) decides which files to backup for an
+ Incremental backup by comparing start time of the prior Job (Full,
+ Differential, or Incremental) against the time each file was last
+ "modified" (st\_mtime) and the time its attributes were last
+ "changed"(st\_ctime). If the file was modified or its attributes
+ changed on or after this start time, it will then be backed up.
+
+ Some virus scanning software may change st\_ctime while
+ doing the scan. For example, if the virus scanning program attempts to
+ reset the access time (st\_atime), which Bacula does not use, it will
+ cause st\_ctime to change and hence Bacula will backup the file during
+ an Incremental or Differential backup. In the case of Sophos virus
+ scanning, you can prevent it from resetting the access time (st\_atime)
+ and hence changing st\_ctime by using the {\bf \verb:--:no-reset-atime}
+ option. For other software, please see their manual.
+
+ When Bacula does an Incremental backup, all modified files that are
+ still on the system are backed up. However, any file that has been
+ deleted since the last Full backup remains in the Bacula catalog, which
+ means that if between a Full save and the time you do a restore, some
+ files are deleted, those deleted files will also be restored. The
+ deleted files will no longer appear in the catalog after doing another
+ Full save. However, to remove deleted files from the catalog during an
+ Incremental backup is quite a time consuming process and not currently
+ implemented in Bacula.
+
+ In addition, if you move a directory rather than copy it, the files in
+ it do not have their modification time (st\_mtime) or their attribute
+ change time (st\_ctime) changed. As a consequence, those files will
+ probably not be backed up by an Incremental or Differential backup which
+ depend solely on these time stamps. If you move a directory, and wish
+ it to be properly backed up, it is generally preferable to copy it, then
+ delete the original.
+
+\item [Differential]
+ \index[dir]{Differential}
+ When the Level is set to Differential
+ all files specified in the FileSet that have changed since the last
+ successful Full backup of the same Job will be backed up.
+ If the Director cannot find a
+ valid previous Full backup for the same Job, FileSet, and Client,
+ backup, then the Differential job will be upgraded into a Full backup.
+ When the Director looks for a valid Full backup record in the catalog
+ database, it looks for a previous Job with:
+
+\begin{itemize}
+\item The same Job name.
+\item The same Client name.
+\item The same FileSet (any change to the definition of the FileSet such as
+ adding or deleting a file in the Include or Exclude sections constitutes a
+ different FileSet.
+\item The Job was a FULL backup.
+\item The Job terminated normally (i.e. did not fail or was not canceled).
+\end{itemize}
+
+ If all the above conditions do not hold, the Director will upgrade the
+ Differential to a Full save. Otherwise, the Differential backup will be
+ performed as requested.
+
+ The File daemon (Client) decides which files to backup for a
+ differential backup by comparing the start time of the prior Full backup
+ Job against the time each file was last "modified" (st\_mtime) and the
+ time its attributes were last "changed" (st\_ctime). If the file was
+ modified or its attributes were changed on or after this start time, it
+ will then be backed up. The start time used is displayed after the {\bf
+ Since} on the Job report. In rare cases, using the start time of the
+ prior backup may cause some files to be backed up twice, but it ensures
+ that no change is missed. As with the Incremental option, you should
+ ensure that the clocks on your server and client are synchronized or as
+ close as possible to avoid the possibility of a file being skipped.
+ Note, on versions 1.33 or greater Bacula automatically makes the
+ necessary adjustments to the time between the server and the client so
+ that the times Bacula uses are synchronized.
+
+ When Bacula does a Differential backup, all modified files that are
+ still on the system are backed up. However, any file that has been
+ deleted since the last Full backup remains in the Bacula catalog, which
+ means that if between a Full save and the time you do a restore, some
+ files are deleted, those deleted files will also be restored. The
+ deleted files will no longer appear in the catalog after doing another
+ Full save. However, to remove deleted files from the catalog during a
+ Differential backup is quite a time consuming process and not currently
+ implemented in Bacula. It is, however, a planned future feature.
+
+ As noted above, if you move a directory rather than copy it, the
+ files in it do not have their modification time (st\_mtime) or
+ their attribute change time (st\_ctime) changed. As a
+ consequence, those files will probably not be backed up by an
+ Incremental or Differential backup which depend solely on these
+ time stamps. If you move a directory, and wish it to be
+ properly backed up, it is generally preferable to copy it, then
+ delete the original. Alternatively, you can move the directory, then
+ use the {\bf touch} program to update the timestamps.
+
+ Every once and a while, someone asks why we need Differential
+ backups as long as Incremental backups pickup all changed files.
+ There are possibly many answers to this question, but the one
+ that is the most important for me is that a Differential backup
+ effectively merges
+ all the Incremental and Differential backups since the last Full backup
+ into a single Differential backup. This has two effects: 1. It gives
+ some redundancy since the old backups could be used if the merged backup
+ cannot be read. 2. More importantly, it reduces the number of Volumes
+ that are needed to do a restore effectively eliminating the need to read
+ all the volumes on which the preceding Incremental and Differential
+ backups since the last Full are done.
+
+\end{description}
+
+For a {\bf Restore} Job, no level needs to be specified.
+
+For a {\bf Verify} Job, the Level may be one of the following:
+
+\begin{description}
+
+\item [InitCatalog]
+\index[dir]{InitCatalog}
+ does a scan of the specified {\bf FileSet} and stores the file
+ attributes in the Catalog database. Since no file data is saved, you
+ might ask why you would want to do this. It turns out to be a very
+ simple and easy way to have a {\bf Tripwire} like feature using {\bf
+ Bacula}. In other words, it allows you to save the state of a set of
+ files defined by the {\bf FileSet} and later check to see if those files
+ have been modified or deleted and if any new files have been added.
+ This can be used to detect system intrusion. Typically you would
+ specify a {\bf FileSet} that contains the set of system files that
+ should not change (e.g. /sbin, /boot, /lib, /bin, ...). Normally, you
+ run the {\bf InitCatalog} level verify one time when your system is
+ first setup, and then once again after each modification (upgrade) to
+ your system. Thereafter, when your want to check the state of your
+ system files, you use a {\bf Verify} {\bf level = Catalog}. This
+ compares the results of your {\bf InitCatalog} with the current state of
+ the files.
+
+\item [Catalog]
+\index[dir]{Catalog}
+ Compares the current state of the files against the state previously
+ saved during an {\bf InitCatalog}. Any discrepancies are reported. The
+ items reported are determined by the {\bf verify} options specified on
+ the {\bf Include} directive in the specified {\bf FileSet} (see the {\bf
+ FileSet} resource below for more details). Typically this command will
+ be run once a day (or night) to check for any changes to your system
+ files.
+
+ Please note! If you run two Verify Catalog jobs on the same client at
+ the same time, the results will certainly be incorrect. This is because
+ Verify Catalog modifies the Catalog database while running in order to
+ track new files.
+
+\item [VolumeToCatalog]
+\index[dir]{VolumeToCatalog}
+ This level causes Bacula to read the file attribute data written to the
+ Volume from the last Job. The file attribute data are compared to the
+ values saved in the Catalog database and any differences are reported.
+ This is similar to the {\bf Catalog} level except that instead of
+ comparing the disk file attributes to the catalog database, the
+ attribute data written to the Volume is read and compared to the catalog
+ database. Although the attribute data including the signatures (MD5 or
+ SHA1) are compared, the actual file data is not compared (it is not in
+ the catalog).
+
+ Please note! If you run two Verify VolumeToCatalog jobs on the same
+ client at the same time, the results will certainly be incorrect. This
+ is because the Verify VolumeToCatalog modifies the Catalog database
+ while running.
+
+\item [DiskToCatalog]
+\index[dir]{DiskToCatalog}
+ This level causes Bacula to read the files as they currently are on
+ disk, and to compare the current file attributes with the attributes
+ saved in the catalog from the last backup for the job specified on the
+ {\bf VerifyJob} directive. This level differs from the {\bf Catalog}
+ level described above by the fact that it doesn't compare against a
+ previous Verify job but against a previous backup. When you run this
+ level, you must supply the verify options on your Include statements.
+ Those options determine what attribute fields are compared.
+
+ This command can be very useful if you have disk problems because it
+ will compare the current state of your disk against the last successful
+ backup, which may be several jobs.
+
+ Note, the current implementation (1.32c) does not identify files that
+ have been deleted.
+\end{description}
+
+\item [Verify Job = \lt{}Job-Resource-Name\gt{}]
+ \index[dir]{Verify Job}
+ \index[dir]{Directive!Verify Job}
+ If you run a verify job without this directive, the last job run will be
+ compared with the catalog, which means that you must immediately follow
+ a backup by a verify command. If you specify a {\bf Verify Job} Bacula
+ will find the last job with that name that ran. This permits you to run
+ all your backups, then run Verify jobs on those that you wish to be
+ verified (most often a {\bf VolumeToCatalog}) so that the tape just
+ written is re-read.
+
+\item [JobDefs = \lt{}JobDefs-Resource-Name\gt{}]
+\index[dir]{JobDefs}
+\index[dir]{Directive!JobDefs}
+ If a JobDefs-Resource-Name is specified, all the values contained in the
+ named JobDefs resource will be used as the defaults for the current Job.
+ Any value that you explicitly define in the current Job resource, will
+ override any defaults specified in the JobDefs resource. The use of
+ this directive permits writing much more compact Job resources where the
+ bulk of the directives are defined in one or more JobDefs. This is
+ particularly useful if you have many similar Jobs but with minor
+ variations such as different Clients. A simple example of the use of
+ JobDefs is provided in the default bacula-dir.conf file.
+
+\item [Bootstrap = \lt{}bootstrap-file\gt{}]
+\index[dir]{Bootstrap}
+\index[dir]{Directive!Bootstrap}
+ The Bootstrap directive specifies a bootstrap file that, if provided,
+ will be used during {\bf Restore} Jobs and is ignored in other Job
+ types. The {\bf bootstrap} file contains the list of tapes to be used
+ in a restore Job as well as which files are to be restored.
+ Specification of this directive is optional, and if specified, it is
+ used only for a restore job. In addition, when running a Restore job
+ from the console, this value can be changed.
+
+ If you use the {\bf Restore} command in the Console program, to start a
+ restore job, the {\bf bootstrap} file will be created automatically from
+ the files you select to be restored.
+
+ For additional details of the {\bf bootstrap} file, please see
+ \ilink{Restoring Files with the Bootstrap File}{BootstrapChapter} chapter
+ of this manual.
+
+\label{writebootstrap}
+\item [Write Bootstrap = \lt{}bootstrap-file-specification\gt{}]
+\index[dir]{Write Bootstrap}
+\index[dir]{Directive!Write Bootstrap}
+ The {\bf writebootstrap} directive specifies a file name where Bacula
+ will write a {\bf bootstrap} file for each Backup job run. This
+ directive applies only to Backup Jobs. If the Backup job is a Full
+ save, Bacula will erase any current contents of the specified file
+ before writing the bootstrap records. If the Job is an Incremental
+ or Differential
+ save, Bacula will append the current bootstrap record to the end of the
+ file.
+
+ Using this feature, permits you to constantly have a bootstrap file that
+ can recover the current state of your system. Normally, the file
+ specified should be a mounted drive on another machine, so that if your
+ hard disk is lost, you will immediately have a bootstrap record
+ available. Alternatively, you should copy the bootstrap file to another
+ machine after it is updated. Note, it is a good idea to write a separate
+ bootstrap file for each Job backed up including the job that backs up
+ your catalog database.
+
+ If the {\bf bootstrap-file-specification} begins with a vertical bar
+ (|), Bacula will use the specification as the name of a program to which
+ it will pipe the bootstrap record. It could for example be a shell
+ script that emails you the bootstrap record.
+
+ On versions 1.39.22 or greater, before opening the file or executing the
+ specified command, Bacula performs
+ \ilink{character substitution}{character substitution} like in RunScript
+ directive. To automatically manage your bootstrap files, you can use
+ this in your {\bf JobDefs} resources:
+\begin{verbatim}
+JobDefs {
+ Write Bootstrap = "%c_%n.bsr"
+ ...
+}
+\end{verbatim}
+
+ For more details on using this file, please see the chapter entitled
+ \ilink{The Bootstrap File}{BootstrapChapter} of this manual.
+
+\item [Client = \lt{}client-resource-name\gt{}]
+\index[dir]{Client}
+\index[dir]{Directive!Client}
+ The Client directive specifies the Client (File daemon) that will be used in
+ the current Job. Only a single Client may be specified in any one Job. The
+ Client runs on the machine to be backed up, and sends the requested files to
+ the Storage daemon for backup, or receives them when restoring. For
+ additional details, see the
+ \ilink{Client Resource section}{ClientResource2} of this chapter.
+ This directive is required.
+
+\item [FileSet = \lt{}FileSet-resource-name\gt{}]
+\index[dir]{FileSet}
+\index[dir]{FileSet}
+ The FileSet directive specifies the FileSet that will be used in the
+ current Job. The FileSet specifies which directories (or files) are to
+ be backed up, and what options to use (e.g. compression, ...). Only a
+ single FileSet resource may be specified in any one Job. For additional
+ details, see the \ilink{FileSet Resource section}{FileSetResource} of
+ this chapter. This directive is required.
+
+\item [Messages = \lt{}messages-resource-name\gt{}]
+\index[dir]{Messages}
+\index[dir]{Directive!Messages}
+ The Messages directive defines what Messages resource should be used for
+ this job, and thus how and where the various messages are to be
+ delivered. For example, you can direct some messages to a log file, and
+ others can be sent by email. For additional details, see the
+ \ilink{Messages Resource}{MessagesChapter} Chapter of this manual. This
+ directive is required.
+
+\item [Pool = \lt{}pool-resource-name\gt{}]
+\index[dir]{Pool}
+\index[dir]{Directive!Pool}
+ The Pool directive defines the pool of Volumes where your data can be
+ backed up. Many Bacula installations will use only the {\bf Default}
+ pool. However, if you want to specify a different set of Volumes for
+ different Clients or different Jobs, you will probably want to use
+ Pools. For additional details, see the \ilink{Pool Resource
+ section}{PoolResource} of this chapter. This directive is required.
+
+\item [Full Backup Pool = \lt{}pool-resource-name\gt{}]
+\index[dir]{Full Backup Pool}
+\index[dir]{Directive!Full Backup Pool}
+ The {\it Full Backup Pool} specifies a Pool to be used for Full backups.
+ It will override any Pool specification during a Full backup. This
+ directive is optional.
+
+\item [Differential Backup Pool = \lt{}pool-resource-name\gt{}]
+\index[dir]{Differential Backup Pool}
+\index[dir]{Directive!Differential Backup Pool}
+ The {\it Differential Backup Pool} specifies a Pool to be used for
+ Differential backups. It will override any Pool specification during a
+ Differential backup. This directive is optional.
+
+\item [Incremental Backup Pool = \lt{}pool-resource-name\gt{}]
+\index[dir]{Incremental Backup Pool}
+\index[dir]{Directive!Incremental Backup Pool}
+ The {\it Incremental Backup Pool} specifies a Pool to be used for
+ Incremental backups. It will override any Pool specification during an
+ Incremental backup. This directive is optional.
+
+\item [Schedule = \lt{}schedule-name\gt{}]
+\index[dir]{Schedule}
+\index[dir]{Directive!Schedule}
+ The Schedule directive defines what schedule is to be used for the Job.
+ The schedule in turn determines when the Job will be automatically
+ started and what Job level (i.e. Full, Incremental, ...) is to be run.
+ This directive is optional, and if left out, the Job can only be started
+ manually using the Console program. Although you may specify only a
+ single Schedule resource for any one job, the Schedule resource may
+ contain multiple {\bf Run} directives, which allow you to run the Job at
+ many different times, and each {\bf run} directive permits overriding
+ the default Job Level Pool, Storage, and Messages resources. This gives
+ considerable flexibility in what can be done with a single Job. For
+ additional details, see the \ilink{Schedule Resource
+ Chapter}{ScheduleResource} of this manual.
+
+
+\item [Storage = \lt{}storage-resource-name\gt{}]
+\index[dir]{Storage}
+\index[dir]{Directive!Storage}
+ The Storage directive defines the name of the storage services where you
+ want to backup the FileSet data. For additional details, see the
+ \ilink{Storage Resource Chapter}{StorageResource2} of this manual.
+ The Storage resource may also be specified in the Job's Pool resource,
+ in which case the value in the Pool resource overrides any value
+ in the Job. This Storage resource definition is not required by either
+ the Job resource or in the Pool, but it must be specified in
+ one or the other, if not an error will result.
+
+\item [Max Start Delay = \lt{}time\gt{}]
+\index[dir]{Max Start Delay}
+\index[dir]{Directive!Max Start Delay}
+ The time specifies the maximum delay between the scheduled time and the
+ actual start time for the Job. For example, a job can be scheduled to
+ run at 1:00am, but because other jobs are running, it may wait to run.
+ If the delay is set to 3600 (one hour) and the job has not begun to run
+ by 2:00am, the job will be canceled. This can be useful, for example,
+ to prevent jobs from running during day time hours. The default is 0
+ which indicates no limit.
+
+\item [Max Run Time = \lt{}time\gt{}]
+\index[dir]{Max Run Time}
+\index[dir]{Directive!Max Run Time}
+ The time specifies the maximum allowed time that a job may run, counted
+ from when the job starts, ({\bf not} necessarily the same as when the
+ job was scheduled). This directive is implemented in version 1.33 and
+ later.
+
+\item [Max Wait Time = \lt{}time\gt{}]
+\index[dir]{Max Wait Time}
+\index[dir]{Directive!Max Wait Time}
+ The time specifies the maximum allowed time that a job may block waiting
+ for a resource (such as waiting for a tape to be mounted, or waiting for
+ the storage or file daemons to perform their duties), counted from the
+ when the job starts, ({\bf not} necessarily the same as when the job was
+ scheduled). This directive is implemented only in version 1.33 and
+ later.
+
+\item [Incremental Max Wait Time = \lt{}time\gt{}]
+\index[dir]{Incremental Max Wait Time}
+\index[dir]{Directive!Incremental Max Wait Time}
+ The time specifies the maximum allowed time that an Incremental backup
+ job may block waiting for a resource (such as waiting for a tape to be
+ mounted, or waiting for the storage or file daemons to perform their
+ duties), counted from the when the job starts, ({\bf not} necessarily
+ the same as when the job was scheduled). Please note that if there is a
+ {\bf Max Wait Time} it may also be applied to the job.
+
+\item [Differential Max Wait Time = \lt{}time\gt{}]
+\index[dir]{Differential Max Wait Time}
+\index[dir]{Directive!Differential Max Wait Time}
+ The time specifies the maximum allowed time that a Differential backup
+ job may block waiting for a resource (such as waiting for a tape to be
+ mounted, or waiting for the storage or file daemons to perform their
+ duties), counted from the when the job starts, ({\bf not} necessarily
+ the same as when the job was scheduled). Please note that if there is a
+ {\bf Max Wait Time} it may also be applied to the job.
+
+\label{PreferMountedVolumes}
+\item [Prefer Mounted Volumes = \lt{}yes|no\gt{}]
+\index[dir]{Prefer Mounted Volumes}
+\index[dir]{Directive!Prefer Mounted Volumes}
+ If the Prefer Mounted Volumes directive is set to {\bf yes} (default
+ yes), the Storage daemon is requested to select either an Autochanger or
+ a drive with a valid Volume already mounted in preference to a drive
+ that is not ready. This means that all jobs will attempt to append
+ to the same Volume (providing the Volume is appropriate -- right Pool,
+ ... for that job). If no drive with a suitable Volume is available, it
+ will select the first available drive. Note, any Volume that has
+ been requested to be mounted, will be considered valid as a mounted
+ volume by another job. This if multiple jobs start at the same time
+ and they all prefer mounted volumes, the first job will request the
+ mount, and the other jobs will use the same volume.
+
+ If the directive is set to {\bf no}, the Storage daemon will prefer
+ finding an unused drive, otherwise, each job started will append to the
+ same Volume (assuming the Pool is the same for all jobs). Setting
+ Prefer Mounted Volumes to no can be useful for those sites
+ with multiple drive autochangers that prefer to maximize backup
+ throughput at the expense of using additional drives and Volumes.
+ This means that the job will prefer to use an unused drive rather
+ than use a drive that is already in use.
+
+\item [Prune Jobs = \lt{}yes|no\gt{}]
+\index[dir]{Prune Jobs}
+\index[dir]{Directive!Prune Jobs}
+ Normally, pruning of Jobs from the Catalog is specified on a Client by
+ Client basis in the Client resource with the {\bf AutoPrune} directive.
+ If this directive is specified (not normally) and the value is {\bf
+ yes}, it will override the value specified in the Client resource. The
+ default is {\bf no}.
+
+
+\item [Prune Files = \lt{}yes|no\gt{}]
+\index[dir]{Prune Files}
+\index[dir]{Directive!Prune Files}
+ Normally, pruning of Files from the Catalog is specified on a Client by
+ Client basis in the Client resource with the {\bf AutoPrune} directive.
+ If this directive is specified (not normally) and the value is {\bf
+ yes}, it will override the value specified in the Client resource. The
+ default is {\bf no}.
+
+\item [Prune Volumes = \lt{}yes|no\gt{}]
+\index[dir]{Prune Volumes}
+\index[dir]{Directive!Prune Volumes}
+ Normally, pruning of Volumes from the Catalog is specified on a Client
+ by Client basis in the Client resource with the {\bf AutoPrune}
+ directive. If this directive is specified (not normally) and the value
+ is {\bf yes}, it will override the value specified in the Client
+ resource. The default is {\bf no}.
+
+\item [RunScript \{\lt{}body-of-runscript\gt{}\}]
+ \index[dir]{RunScript}
+ \index[dir]{Directive!Run Script}
+
+ This directive is implemented in version 1.39.22 and later.
+ The RunScript directive behaves like a resource in that it
+ requires opening and closing braces around a number of directives
+ that make up the body of the runscript.
+
+ The specified {\bf Command} (see below for details) is run as an
+ external program prior or after the current Job. This is optional.
+
+ You can use following options may be specified in the body
+ of the runscript:\\
+
+\begin{tabular}{|c|c|c|l}
+Options & Value & Default & Information \\
+\hline
+\hline
+Runs On Success & Yes/No & {\it Yes} & Run command if JobStatus is successful\\
+\hline
+Runs On Failure & Yes/No & {\it No} & Run command if JobStatus isn't successful\\
+\hline
+Runs On Client & Yes/No & {\it Yes} & Run command on client\\
+\hline
+Runs When & Before|After|Always & {\it Never} & When run commands\\
+\hline
+Fail Job On Error & Yes/No & {\it Yes} & Fail job if script returns
+ something different from 0 \\
+\hline
+Command & & & Path to your script\\
+\hline
+\end{tabular}
+ \\
+
+ Any output sent by the command to standard output will be included in the
+ Bacula job report. The command string must be a valid program name or name
+ of a shell script.
+
+ In addition, the command string is parsed then fed to the OS,
+ which means that the path will be searched to execute your specified
+ command, but there is no shell interpretation, as a consequence, if you
+ invoke complicated commands or want any shell features such as redirection
+ or piping, you must call a shell script and do it inside that script.
+
+ Before submitting the specified command to the operating system, Bacula
+ performs character substitution of the following characters:
+
+\label{character substitution}
+\footnotesize
+\begin{verbatim}
+ %% = %
+ %c = Client's name
+ %d = Director's name
+ %e = Job Exit Status
+ %i = JobId
+ %j = Unique Job id
+ %l = Job Level
+ %n = Job name
+ %s = Since time
+ %t = Job type (Backup, ...)
+ %v = Volume name
+
+\end{verbatim}
+\normalsize
+
+The Job Exit Status code \%e edits the following values:
+
+\index[dir]{Exit Status}
+\begin{itemize}
+\item OK
+\item Error
+\item Fatal Error
+\item Canceled
+\item Differences
+\item Unknown term code
+\end{itemize}
+
+ Thus if you edit it on a command line, you will need to enclose
+ it within some sort of quotes.
+
+
+You can use these following shortcuts:\\
+
+\begin{tabular}{|c|c|c|c|c|c}
+Keyword & RunsOnSuccess & RunsOnFailure & FailJobOnError & Runs On Client & RunsWhen \\
+\hline
+Run Before Job & & & Yes & No & Before \\
+\hline
+Run After Job & Yes & No & & No & After \\
+\hline
+Run After Failed Job & No & Yes & & No & After \\
+\hline
+Client Run Before Job & & & Yes & Yes & Before \\
+\hline
+Client Run After Job & Yes & No & & Yes & After \\
+\end{tabular}
+
+Examples:
+\begin{verbatim}
+RunScript {
+ RunsWhen = Before
+ FailJobOnError = No
+ Command = "/etc/init.d/apache stop"
+}
+
+RunScript {
+ RunsWhen = After
+ RunsOnFailure = yes
+ Command = "/etc/init.d/apache start"
+}
+\end{verbatim}
+
+ {\bf Special Windows Considerations}
+
+ In addition, for a Windows client on version 1.33 and above, please take
+ note that you must ensure a correct path to your script. The script or
+ program can be a .com, .exe or a .bat file. If you just put the program
+ name in then Bacula will search using the same rules that cmd.exe uses
+ (current directory, Bacula bin directory, and PATH). It will even try the
+ different extensions in the same order as cmd.exe.
+ The command can be anything that cmd.exe or command.com will recognize
+ as an executable file.
+
+ However, if you have slashes in the program name then Bacula figures you
+ are fully specifying the name, so you must also explicitly add the three
+ character extension.
+
+ The command is run in a Win32 environment, so Unix like commands will not
+ work unless you have installed and properly configured Cygwin in addition
+ to and separately from Bacula.
+
+ The System \%Path\% will be searched for the command. (under the
+ environment variable dialog you have have both System Environment and
+ User Environment, we believe that only the System environment will be
+ available to bacula-fd, if it is running as a service.)
+
+ System environment variables can be referenced with \%var\% and
+ used as either part of the command name or arguments.
+
+ So if you have a script in the Bacula\\bin directory then the following lines
+ should work fine:
+
+\footnotesize
+\begin{verbatim}
+ Client Run Before Job = systemstate
+or
+ Client Run Before Job = systemstate.bat
+or
+ Client Run Before Job = "systemstate"
+or
+ Client Run Before Job = "systemstate.bat"
+or
+ ClientRunBeforeJob = "\"C:/Program Files/Bacula/systemstate.bat\""
+\end{verbatim}
+\normalsize
+
+The outer set of quotes is removed when the configuration file is parsed.
+You need to escape the inner quotes so that they are there when the code
+that parses the command line for execution runs so it can tell what the
+program name is.
+
+
+\footnotesize
+\begin{verbatim}
+ClientRunBeforeJob = "\"C:/Program Files/Software
+ Vendor/Executable\" /arg1 /arg2 \"foo bar\""
+\end{verbatim}
+\normalsize
+
+ The special characters
+\begin{verbatim}
+&<>()@^|
+\end{verbatim}
+ will need to be quoted,
+ if they are part of a filename or argument.
+
+ If someone is logged in, a blank "command" window running the commands
+ will be present during the execution of the command.
+
+ Some Suggestions from Phil Stracchino for running on Win32 machines with
+ the native Win32 File daemon:
+
+ \begin{enumerate}
+ \item You might want the ClientRunBeforeJob directive to specify a .bat
+ file which runs the actual client-side commands, rather than trying
+ to run (for example) regedit /e directly.
+ \item The batch file should explicitly 'exit 0' on successful completion.
+ \item The path to the batch file should be specified in Unix form:
+
+ ClientRunBeforeJob = "c:/bacula/bin/systemstate.bat"
+
+ rather than DOS/Windows form:
+
+ ClientRunBeforeJob =
+
+"c:\textbackslash{}bacula\textbackslash{}bin\textbackslash{}systemstate.bat"
+ INCORRECT
+ \end{enumerate}
+
+For Win32, please note that there are certain limitations:
+
+ClientRunBeforeJob = "C:/Program Files/Bacula/bin/pre-exec.bat"
+
+Lines like the above do not work because there are limitations of
+cmd.exe that is used to execute the command.
+Bacula prefixes the string you supply with {\bf cmd.exe /c }. To test that
+your command works you should type {\bf cmd /c "C:/Program Files/test.exe"} at a
+cmd prompt and see what happens. Once the command is correct insert a
+backslash (\textbackslash{}) before each double quote ("), and
+then put quotes around the whole thing when putting it in
+the director's .conf file. You either need to have only one set of quotes
+or else use the short name and don't put quotes around the command path.
+
+Below is the output from cmd's help as it relates to the command line
+passed to the /c option.
+
+
+ If /C or /K is specified, then the remainder of the command line after
+ the switch is processed as a command line, where the following logic is
+ used to process quote (") characters:
+
+\begin{enumerate}
+\item
+ If all of the following conditions are met, then quote characters
+ on the command line are preserved:
+ \begin{itemize}
+ \item no /S switch.
+ \item exactly two quote characters.
+ \item no special characters between the two quote characters,
+ where special is one of:
+\begin{verbatim}
+&<>()@^|
+\end{verbatim}
+ \item there are one or more whitespace characters between the
+ the two quote characters.
+ \item the string between the two quote characters is the name
+ of an executable file.
+ \end{itemize}
+
+\item Otherwise, old behavior is to see if the first character is
+ a quote character and if so, strip the leading character and
+ remove the last quote character on the command line, preserving
+ any text after the last quote character.
+
+\end{enumerate}
+
+
+The following example of the use of the Client Run Before Job directive was
+submitted by a user:\\
+You could write a shell script to back up a DB2 database to a FIFO. The shell
+script is:
+
+\footnotesize
+\begin{verbatim}
+ #!/bin/sh
+ # ===== backupdb.sh
+ DIR=/u01/mercuryd
+
+ mkfifo $DIR/dbpipe
+ db2 BACKUP DATABASE mercuryd TO $DIR/dbpipe WITHOUT PROMPTING &
+ sleep 1
+\end{verbatim}
+\normalsize
+
+The following line in the Job resource in the bacula-dir.conf file:
+\footnotesize
+\begin{verbatim}
+ Client Run Before Job = "su - mercuryd -c \"/u01/mercuryd/backupdb.sh '%t'
+'%l'\""
+\end{verbatim}
+\normalsize
+
+When the job is run, you will get messages from the output of the script
+stating that the backup has started. Even though the command being run is
+backgrounded with \&, the job will block until the "db2 BACKUP DATABASE"
+command, thus the backup stalls.
+
+To remedy this situation, the "db2 BACKUP DATABASE" line should be changed to
+the following:
+
+\footnotesize
+\begin{verbatim}
+ db2 BACKUP DATABASE mercuryd TO $DIR/dbpipe WITHOUT PROMPTING > $DIR/backup.log
+2>&1 < /dev/null &
+\end{verbatim}
+\normalsize
+
+It is important to redirect the input and outputs of a backgrounded command to
+/dev/null to prevent the script from blocking.
+
+\item [Run Before Job = \lt{}command\gt{}]
+\index[dir]{Run Before Job}
+\index[dir]{Directive!Run Before Job}
+\index[dir]{Directive!Run Before Job}
+The specified {\bf command} is run as an external program prior to running the
+current Job. This directive is not required, but if it is defined, and if the
+exit code of the program run is non-zero, the current Bacula job will be
+canceled.
+
+\begin{verbatim}
+Run Before Job = "echo test"
+\end{verbatim}
+ it's equivalent to :
+\begin{verbatim}
+RunScript {
+ Command = "echo test"
+ RunsOnClient = No
+ RunsWhen = Before
+}
+\end{verbatim}
+
+ Lutz Kittler has pointed out that using the RunBeforeJob directive can be a
+ simple way to modify your schedules during a holiday. For example, suppose
+ that you normally do Full backups on Fridays, but Thursday and Friday are
+ holidays. To avoid having to change tapes between Thursday and Friday when
+ no one is in the office, you can create a RunBeforeJob that returns a
+ non-zero status on Thursday and zero on all other days. That way, the
+ Thursday job will not run, and on Friday the tape you inserted on Wednesday
+ before leaving will be used.
+
+\item [Run After Job = \lt{}command\gt{}]
+\index[dir]{Run After Job}
+\index[dir]{Directive!Run After Job}
+ The specified {\bf command} is run as an external program if the current
+ job terminates normally (without error or without being canceled). This
+ directive is not required. If the exit code of the program run is
+ non-zero, Bacula will print a warning message. Before submitting the
+ specified command to the operating system, Bacula performs character
+ substitution as described above for the {\bf RunScript} directive.
+
+ An example of the use of this directive is given in the
+ \ilink{Tips Chapter}{JobNotification} of this manual.
+
+ See the {\bf Run After Failed Job} if you
+ want to run a script after the job has terminated with any
+ non-normal status.
+
+\item [Run After Failed Job = \lt{}command\gt{}]
+\index[dir]{Run After Job}
+\index[dir]{Directive!Run After Job}
+ The specified {\bf command} is run as an external program after the current
+ job terminates with any error status. This directive is not required. The
+ command string must be a valid program name or name of a shell script. If
+ the exit code of the program run is non-zero, Bacula will print a
+ warning message. Before submitting the specified command to the
+ operating system, Bacula performs character substitution as described above
+ for the {\bf RunScript} directive. Note, if you wish that your script
+ will run regardless of the exit status of the Job, you can use this :
+\begin{verbatim}
+RunScript {
+ Command = "echo test"
+ RunsWhen = After
+ RunsOnFailure = yes
+ RunsOnClient = no
+ RunsOnSuccess = yes # default, you can drop this line
+}
+\end{verbatim}
+
+ An example of the use of this directive is given in the
+ \ilink{Tips Chapter}{JobNotification} of this manual.
+
+
+\item [Client Run Before Job = \lt{}command\gt{}]
+\index[dir]{Client Run Before Job}
+\index[dir]{Directive!Client Run Before Job}
+ This directive is the same as {\bf Run Before Job} except that the
+ program is run on the client machine. The same restrictions apply to
+ Unix systems as noted above for the {\bf RunScript}.
+
+\item [Client Run After Job = \lt{}command\gt{}]
+ \index[dir]{Client Run After Job}
+ \index[dir]{Directive!Client Run After Job}
+ The specified {\bf command} is run on the client machine as soon
+ as data spooling is complete in order to allow restarting applications
+ on the client as soon as possible. .
+
+ Note, please see the notes above in {\bf RunScript}
+ concerning Windows clients.
+
+\item [Rerun Failed Levels = \lt{}yes|no\gt{}]
+ \index[dir]{Rerun Failed Levels}
+ \index[dir]{Directive!Rerun Failed Levels}
+ If this directive is set to {\bf yes} (default no), and Bacula detects that
+ a previous job at a higher level (i.e. Full or Differential) has failed,
+ the current job level will be upgraded to the higher level. This is
+ particularly useful for Laptops where they may often be unreachable, and if
+ a prior Full save has failed, you wish the very next backup to be a Full
+ save rather than whatever level it is started as.
+
+ There are several points that must be taken into account when using this
+ directive: first, a failed job is defined as one that has not terminated
+ normally, which includes any running job of the same name (you need to
+ ensure that two jobs of the same name do not run simultaneously);
+ secondly, the {\bf Ignore FileSet Changes} directive is not considered
+ when checking for failed levels, which means that any FileSet change will
+ trigger a rerun.
+
+\item [Spool Data = \lt{}yes|no\gt{}]
+ \index[dir]{Spool Data}
+ \index[dir]{Directive!Spool Data}
+
+ If this directive is set to {\bf yes} (default no), the Storage daemon will
+ be requested to spool the data for this Job to disk rather than write it
+ directly to tape. Once all the data arrives or the spool files' maximum sizes
+ are reached, the data will be despooled and written to tape. Spooling data
+ prevents tape shoe-shine (start and stop) during
+ Incremental saves. If you are writing to a disk file using this option
+ will probably just slow down the backup jobs.
+
+ NOTE: When this directive is set to yes, Spool Attributes is also
+ automatically set to yes.
+
+\item [Spool Attributes = \lt{}yes|no\gt{}]
+ \index[dir]{Spool Attributes}
+ \index[dir]{Directive!Spool Attributes}
+ \index[dir]{slow}
+ \index[general]{slow}
+ \index[dir]{Backups!slow}
+ \index[general]{Backups!slow}
+ The default is set to {\bf no}, which means that the File attributes are
+ sent by the Storage daemon to the Director as they are stored on tape.
+ However, if you want to avoid the possibility that database updates will
+ slow down writing to the tape, you may want to set the value to {\bf
+ yes}, in which case the Storage daemon will buffer the File attributes
+ and Storage coordinates to a temporary file in the Working Directory,
+ then when writing the Job data to the tape is completed, the attributes
+ and storage coordinates will be sent to the Director.
+
+ NOTE: When Spool Data is set to yes, Spool Attributes is also
+ automatically set to yes.
+
+\item [Where = \lt{}directory\gt{}]
+ \index[dir]{Where}
+ \index[dir]{Directive!Where}
+ This directive applies only to a Restore job and specifies a prefix to
+ the directory name of all files being restored. This permits files to
+ be restored in a different location from which they were saved. If {\bf
+ Where} is not specified or is set to backslash ({\bf /}), the files will
+ be restored to their original location. By default, we have set {\bf
+ Where} in the example configuration files to be {\bf
+ /tmp/bacula-restores}. This is to prevent accidental overwriting of
+ your files.
+
+\item [Add Prefix = \lt{}directory\gt{}]
+ \label{confaddprefix}
+ \index[dir]{AddPrefix}
+ \index[dir]{Directive!AddPrefix}
+ This directive applies only to a Restore job and specifies a prefix to the
+ directory name of all files being restored. This will use \ilink{File
+ Relocation}{filerelocation} feature implemented in Bacula 2.1.8 or later.
+
+\item [Add Suffix = \lt{}extention\gt{}]
+ \index[dir]{AddSuffix}
+ \index[dir]{Directive!AddSuffix}
+ This directive applies only to a Restore job and specifies a suffix to all
+ files being restored. This will use \ilink{File Relocation}{filerelocation}
+ feature implemented in Bacula 2.1.8 or later.
+
+ Using \texttt{Add Suffix=.old}, \texttt{/etc/passwd} will be restored to
+ \texttt{/etc/passwsd.old}
+
+\item [Strip Prefix = \lt{}directory\gt{}]
+ \index[dir]{StripPrefix}
+ \index[dir]{Directive!StripPrefix}
+ This directive applies only to a Restore job and specifies a prefix to remove
+ from the directory name of all files being restored. This will use the
+ \ilink{File Relocation}{filerelocation} feature implemented in Bacula 2.1.8
+ or later.
+
+ Using \texttt{Strip Prefix=/etc}, \texttt{/etc/passwd} will be restored to
+ \texttt{/passwd}
+
+ Under Windows, if you want to restore \texttt{c:/files} to \texttt{d:/files},
+ you can use :
+
+\begin{verbatim}
+ Strip Prefix = c:
+ Add Prefix = d:
+\end{verbatim}
+
+\item [RegexWhere = \lt{}expressions\gt{}]
+ \index[dir]{RegexWhere}
+ \index[dir]{Directive!RegexWhere}
+ This directive applies only to a Restore job and specifies a regex filename
+ manipulation of all files being restored. This will use \ilink{File
+ Relocation}{filerelocation} feature implemented in Bacula 2.1.8 or later.
+
+ For more informations about how use this option, see
+ \ilink{this}{useregexwhere}.
+
+\item [Replace = \lt{}replace-option\gt{}]
+ \index[dir]{Replace}
+ \index[dir]{Directive!Replace}
+ This directive applies only to a Restore job and specifies what happens
+ when Bacula wants to restore a file or directory that already exists.
+ You have the following options for {\bf replace-option}:
+
+\begin{description}
+
+\item [always]
+ \index[dir]{always}
+ when the file to be restored already exists, it is deleted and then
+ replaced by the copy that was backed up.
+
+\item [ifnewer]
+\index[dir]{ifnewer}
+ if the backed up file (on tape) is newer than the existing file, the
+ existing file is deleted and replaced by the back up.
+
+\item [ifolder]
+ \index[dir]{ifolder}
+ if the backed up file (on tape) is older than the existing file, the
+ existing file is deleted and replaced by the back up.
+
+\item [never]
+ \index[dir]{never}
+ if the backed up file already exists, Bacula skips restoring this file.
+\end{description}
+
+\item [Prefix Links=\lt{}yes|no\gt{}]
+ \index[dir]{Prefix Links}
+ \index[dir]{Directive!Prefix Links}
+ If a {\bf Where} path prefix is specified for a recovery job, apply it
+ to absolute links as well. The default is {\bf No}. When set to {\bf
+ Yes} then while restoring files to an alternate directory, any absolute
+ soft links will also be modified to point to the new alternate
+ directory. Normally this is what is desired -- i.e. everything is self
+ consistent. However, if you wish to later move the files to their
+ original locations, all files linked with absolute names will be broken.
+
+\item [Maximum Concurrent Jobs = \lt{}number\gt{}]
+ \index[dir]{Maximum Concurrent Jobs}
+ \index[dir]{Directive!Maximum Concurrent Jobs}
+ where \lt{}number\gt{} is the maximum number of Jobs from the current
+ Job resource that can run concurrently. Note, this directive limits
+ only Jobs with the same name as the resource in which it appears. Any
+ other restrictions on the maximum concurrent jobs such as in the
+ Director, Client, or Storage resources will also apply in addition to
+ the limit specified here. The default is set to 1, but you may set it
+ to a larger number. We strongly recommend that you read the WARNING
+ documented under \ilink{ Maximum Concurrent Jobs}{DirMaxConJobs} in the
+ Director's resource.
+
+\item [Reschedule On Error = \lt{}yes|no\gt{}]
+ \index[dir]{Reschedule On Error}
+ \index[dir]{Directive!Reschedule On Error}
+ If this directive is enabled, and the job terminates in error, the job
+ will be rescheduled as determined by the {\bf Reschedule Interval} and
+ {\bf Reschedule Times} directives. If you cancel the job, it will not
+ be rescheduled. The default is {\bf no} (i.e. the job will not be
+ rescheduled).
+
+ This specification can be useful for portables, laptops, or other
+ machines that are not always connected to the network or switched on.
+
+\item [Reschedule Interval = \lt{}time-specification\gt{}]
+ \index[dir]{Reschedule Interval}
+ \index[dir]{Directive!Reschedule Interval}
+ If you have specified {\bf Reschedule On Error = yes} and the job
+ terminates in error, it will be rescheduled after the interval of time
+ specified by {\bf time-specification}. See \ilink{the time
+ specification formats}{Time} in the Configure chapter for details of
+ time specifications. If no interval is specified, the job will not be
+ rescheduled on error.
+
+\item [Reschedule Times = \lt{}count\gt{}]
+ \index[dir]{Reschedule Times}
+ \index[dir]{Directive!Reschedule Times}
+ This directive specifies the maximum number of times to reschedule the
+ job. If it is set to zero (the default) the job will be rescheduled an
+ indefinite number of times.
+
+\item [Run = \lt{}job-name\gt{}]
+ \index[dir]{Run}
+ \index[dir]{Directive!Run}
+ \index[dir]{Clone a Job}
+ The Run directive (not to be confused with the Run option in a
+ Schedule) allows you to start other jobs or to clone jobs. By using the
+ cloning keywords (see below), you can backup
+ the same data (or almost the same data) to two or more drives
+ at the same time. The {\bf job-name} is normally the same name
+ as the current Job resource (thus creating a clone). However, it
+ may be any Job name, so one job may start other related jobs.
+
+ The part after the equal sign must be enclosed in double quotes,
+ and can contain any string or set of options (overrides) that you
+ can specify when entering the Run command from the console. For
+ example {\bf storage=DDS-4 ...}. In addition, there are two special
+ keywords that permit you to clone the current job. They are {\bf level=\%l}
+ and {\bf since=\%s}. The \%l in the level keyword permits
+ entering the actual level of the current job and the \%s in the since
+ keyword permits putting the same time for comparison as used on the
+ current job. Note, in the case of the since keyword, the \%s must be
+ enclosed in double quotes, and thus they must be preceded by a backslash
+ since they are already inside quotes. For example:
+
+\begin{verbatim}
+ run = "Nightly-backup level=%l since=\"%s\" storage=DDS-4"
+\end{verbatim}
+
+ A cloned job will not start additional clones, so it is not
+ possible to recurse.
+
+ Please note that all cloned jobs, as specified in the Run directives are
+ submitted for running before the original job is run (while it is being
+ initialized). This means that any clone job will actually start before
+ the original job, and may even block the original job from starting
+ until the original job finishes unless you allow multiple simultaneous
+ jobs. Even if you set a lower priority on the clone job, if no other
+ jobs are running, it will start before the original job.
+
+ If you are trying to prioritize jobs by using the clone feature (Run
+ directive), you will find it much easier to do using a RunScript
+ resource, or a RunBeforeJob directive.
+
+\label{Priority}
+\item [Priority = \lt{}number\gt{}]
+ \index[dir]{Priority}
+ \index[dir]{Directive!Priority}
+ This directive permits you to control the order in which your jobs will
+ be run by specifying a positive non-zero number. The higher the number,
+ the lower the job priority. Assuming you are not running concurrent jobs,
+ all queued jobs of priority 1 will run before queued jobs of priority 2
+ and so on, regardless of the original scheduling order.
+
+ The priority only affects waiting jobs that are queued to run, not jobs
+ that are already running. If one or more jobs of priority 2 are already
+ running, and a new job is scheduled with priority 1, the currently
+ running priority 2 jobs must complete before the priority 1 job is run.
+
+ The default priority is 10.
+
+ If you want to run concurrent jobs you should
+ keep these points in mind:
+
+\begin{itemize}
+\item See \ilink{Running Concurrent Jobs}{ConcurrentJobs} on how to setup
+ concurrent jobs.
+
+\item Bacula concurrently runs jobs of only one priority at a time. It
+ will not simultaneously run a priority 1 and a priority 2 job.
+
+\item If Bacula is running a priority 2 job and a new priority 1 job is
+ scheduled, it will wait until the running priority 2 job terminates even
+ if the Maximum Concurrent Jobs settings would otherwise allow two jobs
+ to run simultaneously.
+
+\item Suppose that bacula is running a priority 2 job and a new priority 1
+ job is scheduled and queued waiting for the running priority 2 job to
+ terminate. If you then start a second priority 2 job, the waiting
+ priority 1 job will prevent the new priority 2 job from running
+ concurrently with the running priority 2 job. That is: as long as there
+ is a higher priority job waiting to run, no new lower priority jobs will
+ start even if the Maximum Concurrent Jobs settings would normally allow
+ them to run. This ensures that higher priority jobs will be run as soon
+ as possible.
+\end{itemize}
+
+If you have several jobs of different priority, it may not best to start
+them at exactly the same time, because Bacula must examine them one at a
+time. If by Bacula starts a lower priority job first, then it will run
+before your high priority jobs. If you experience this problem, you may
+avoid it by starting any higher priority jobs a few seconds before lower
+priority ones. This insures that Bacula will examine the jobs in the
+correct order, and that your priority scheme will be respected.
+
+\label{WritePartAfterJob}
+\item [Write Part After Job = \lt{}yes|no\gt{}]
+\index[dir]{Write Part After Job}
+\index[dir]{Directive!Write Part After Job}
+ This directive is only implemented in version 1.37 and later.
+ If this directive is set to {\bf yes} (default {\bf no}), a new part file
+ will be created after the job is finished.
+
+ It should be set to {\bf yes} when writing to devices that require mount
+ (for example DVD), so you are sure that the current part, containing
+ this job's data, is written to the device, and that no data is left in
+ the temporary file on the hard disk. However, on some media, like DVD+R
+ and DVD-R, a lot of space (about 10Mb) is lost every time a part is
+ written. So, if you run several jobs each after another, you could set
+ this directive to {\bf no} for all jobs, except the last one, to avoid
+ wasting too much space, but to ensure that the data is written to the
+ medium when all jobs are finished.
+
+ This directive is ignored with tape and FIFO devices.
+
+\item [Heartbeat Interval = \lt{}time-interval\gt{}]
+ \index[dir]{Heartbeat Interval}
+ \index[dir]{Directive!Heartbeat}
+ This directive is optional and if specified will cause the Director to
+ set a keepalive interval (heartbeat) in seconds on each of the sockets
+ it opens for the Client resource. This value will override any
+ specified at the Director level. It is implemented only on systems
+ (Linux, ...) that provide the {\bf setsockopt} TCP\_KEEPIDLE function.
+ The default value is zero, which means no change is made to the socket.
+
+\end{description}
+
+The following is an example of a valid Job resource definition:
+
+\footnotesize
+\begin{verbatim}
+Job {
+ Name = "Minou"
+ Type = Backup
+ Level = Incremental # default
+ Client = Minou
+ FileSet="Minou Full Set"
+ Storage = DLTDrive
+ Pool = Default
+ Schedule = "MinouWeeklyCycle"
+ Messages = Standard
+}
+\end{verbatim}
+\normalsize
+
+\section{The JobDefs Resource}
+\label{JobDefsResource}
+\index[general]{JobDefs Resource}
+\index[general]{Resource!JobDefs}
+
+The JobDefs resource permits all the same directives that can appear in a Job
+resource. However, a JobDefs resource does not create a Job, rather it can be
+referenced within a Job to provide defaults for that Job. This permits you to
+concisely define several nearly identical Jobs, each one referencing a JobDefs
+resource which contains the defaults. Only the changes from the defaults need to
+be mentioned in each Job.
+
+\section{The Schedule Resource}
+\label{ScheduleResource}
+\index[general]{Resource!Schedule}
+\index[general]{Schedule Resource}
+
+The Schedule resource provides a means of automatically scheduling a Job as
+well as the ability to override the default Level, Pool, Storage and Messages
+resources. If a Schedule resource is not referenced in a Job, the Job can only
+be run manually. In general, you specify an action to be taken and when.
+
+\begin{description}
+
+\item [Schedule]
+\index[dir]{Schedule}
+\index[dir]{Directive!Schedule}
+ Start of the Schedule directives. No {\bf Schedule} resource is
+ required, but you will need at least one if you want Jobs to be
+ automatically started.
+
+\item [Name = \lt{}name\gt{}]
+ \index[dir]{Name}
+ \index[dir]{Directive!Name}
+ The name of the schedule being defined. The Name directive is required.
+
+\item [Run = \lt{}Job-overrides\gt{} \lt{}Date-time-specification\gt{}]
+ \index[dir]{Run}
+ \index[dir]{Directive!Run}
+ The Run directive defines when a Job is to be run, and what overrides if
+ any to apply. You may specify multiple {\bf run} directives within a
+ {\bf Schedule} resource. If you do, they will all be applied (i.e.
+ multiple schedules). If you have two {\bf Run} directives that start at
+ the same time, two Jobs will start at the same time (well, within one
+ second of each other).
+
+ The {\bf Job-overrides} permit overriding the Level, the Storage, the
+ Messages, and the Pool specifications provided in the Job resource. In
+ addition, the FullPool, the IncrementalPool, and the DifferentialPool
+ specifications permit overriding the Pool specification according to
+ what backup Job Level is in effect.
+
+ By the use of overrides, you may customize a particular Job. For
+ example, you may specify a Messages override for your Incremental
+ backups that outputs messages to a log file, but for your weekly or
+ monthly Full backups, you may send the output by email by using a
+ different Messages override.
+
+ {\bf Job-overrides} are specified as: {\bf keyword=value} where the
+ keyword is Level, Storage, Messages, Pool, FullPool, DifferentialPool,
+ or IncrementalPool, and the {\bf value} is as defined on the respective
+ directive formats for the Job resource. You may specify multiple {\bf
+ Job-overrides} on one {\bf Run} directive by separating them with one or
+ more spaces or by separating them with a trailing comma. For example:
+
+\begin{description}
+
+\item [Level=Full]
+ \index[dir]{Level}
+ \index[dir]{Directive!Level}
+ is all files in the FileSet whether or not they have changed.
+
+\item [Level=Incremental]
+ \index[dir]{Level}
+ \index[dir]{Directive!Level}
+ is all files that have changed since the last backup.
+
+\item [Pool=Weekly]
+ \index[dir]{Pool}
+ \index[dir]{Directive!Pool}
+ specifies to use the Pool named {\bf Weekly}.
+
+\item [Storage=DLT\_Drive]
+ \index[dir]{Storage}
+ \index[dir]{Directive!Storage}
+ specifies to use {\bf DLT\_Drive} for the storage device.
+
+\item [Messages=Verbose]
+ \index[dir]{Messages}
+ \index[dir]{Directive!Messages}
+ specifies to use the {\bf Verbose} message resource for the Job.
+
+\item [FullPool=Full]
+ \index[dir]{FullPool}
+ \index[dir]{Directive!FullPool}
+ specifies to use the Pool named {\bf Full} if the job is a full backup, or
+is
+upgraded from another type to a full backup.
+
+\item [DifferentialPool=Differential]
+ \index[dir]{DifferentialPool}
+ \index[dir]{Directive!DifferentialPool}
+ specifies to use the Pool named {\bf Differential} if the job is a
+ differential backup.
+
+\item [IncrementalPool=Incremental]
+ \index[dir]{IncrementalPool}
+ \index[dir]{Directive!IncrementalPool}
+ specifies to use the Pool named {\bf Incremental} if the job is an
+incremental backup.
+
+\item [SpoolData=yes|no]
+ \index[dir]{SpoolData}
+ \index[dir]{Directive!SpoolData}
+ tells Bacula to request the Storage daemon to spool data to a disk file
+ before writing it to the Volume (normally a tape). Thus the data is
+ written in large blocks to the Volume rather than small blocks. This
+ directive is particularly useful when running multiple simultaneous
+ backups to tape. It prevents interleaving of the job data and reduces
+ or eliminates tape drive stop and start commonly known as "shoe-shine".
+
+\item [SpoolSize={\it bytes}]
+ \index[dir]{SpoolSize}
+ \index[dir]{Directive!SpoolSize}
+ where the bytes specify the maximum spool size for this job.
+ The default is take from Device Maximum Spool Size limit.
+ This directive is available only in Bacula version 2.3.5 or
+ later.
+
+\item [WritePartAfterJob=yes|no]
+ \index[dir]{WritePartAfterJob}
+ \index[dir]{Directive!WritePartAfterJob}
+ tells Bacula to request the Storage daemon to write the current part
+ file to the device when the job is finished (see \ilink{Write Part After
+ Job directive in the Job resource}{WritePartAfterJob}). Please note,
+ this directive is implemented only in version 1.37 and later. The
+ default is yes. We strongly recommend that you keep this set to yes
+ otherwise, when the last job has finished one part will remain in the
+ spool file and restore may or may not work.
+
+\end{description}
+
+{\bf Date-time-specification} determines when the Job is to be run. The
+specification is a repetition, and as a default Bacula is set to run a job at
+the beginning of the hour of every hour of every day of every week of every
+month of every year. This is not normally what you want, so you must specify
+or limit when you want the job to run. Any specification given is assumed to
+be repetitive in nature and will serve to override or limit the default
+repetition. This is done by specifying masks or times for the hour, day of the
+month, day of the week, week of the month, week of the year, and month when
+you want the job to run. By specifying one or more of the above, you can
+define a schedule to repeat at almost any frequency you want.
+
+Basically, you must supply a {\bf month}, {\bf day}, {\bf hour}, and {\bf
+minute} the Job is to be run. Of these four items to be specified, {\bf day}
+is special in that you may either specify a day of the month such as 1, 2,
+... 31, or you may specify a day of the week such as Monday, Tuesday, ...
+Sunday. Finally, you may also specify a week qualifier to restrict the
+schedule to the first, second, third, fourth, or fifth week of the month.
+
+For example, if you specify only a day of the week, such as {\bf Tuesday} the
+Job will be run every hour of every Tuesday of every Month. That is the {\bf
+month} and {\bf hour} remain set to the defaults of every month and all
+hours.
+
+Note, by default with no other specification, your job will run at the
+beginning of every hour. If you wish your job to run more than once in any
+given hour, you will need to specify multiple {\bf run} specifications each
+with a different minute.
+
+The date/time to run the Job can be specified in the following way in
+pseudo-BNF:
+
+\footnotesize
+\begin{verbatim}
+<void-keyword> = on
+<at-keyword> = at
+<week-keyword> = 1st | 2nd | 3rd | 4th | 5th | first |
+ second | third | fourth | fifth
+<wday-keyword> = sun | mon | tue | wed | thu | fri | sat |
+ sunday | monday | tuesday | wednesday |
+ thursday | friday | saturday
+<week-of-year-keyword> = w00 | w01 | ... w52 | w53
+<month-keyword> = jan | feb | mar | apr | may | jun | jul |
+ aug | sep | oct | nov | dec | january |
+ february | ... | december
+<daily-keyword> = daily
+<weekly-keyword> = weekly
+<monthly-keyword> = monthly
+<hourly-keyword> = hourly
+<digit> = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 0
+<number> = <digit> | <digit><number>
+<12hour> = 0 | 1 | 2 | ... 12
+<hour> = 0 | 1 | 2 | ... 23
+<minute> = 0 | 1 | 2 | ... 59
+<day> = 1 | 2 | ... 31
+<time> = <hour>:<minute> |
+ <12hour>:<minute>am |
+ <12hour>:<minute>pm
+<time-spec> = <at-keyword> <time> |
+ <hourly-keyword>
+<date-keyword> = <void-keyword> <weekly-keyword>
+<day-range> = <day>-<day>
+<month-range> = <month-keyword>-<month-keyword>
+<wday-range> = <wday-keyword>-<wday-keyword>
+<range> = <day-range> | <month-range> |
+ <wday-range>
+<date> = <date-keyword> | <day> | <range>
+<date-spec> = <date> | <date-spec>
+<day-spec> = <day> | <wday-keyword> |
+ <day-range> | <wday-range> |
+ <daily-keyword>
+<day-spec> = <day> | <wday-keyword> |
+ <day> | <wday-range> |
+ <week-keyword> <wday-keyword> |
+ <week-keyword> <wday-range>
+<month-spec> = <month-keyword> | <month-range> |
+ <monthly-keyword>
+<date-time-spec> = <month-spec> <day-spec> <time-spec>
+\end{verbatim}
+\normalsize
+
+\end{description}
+
+Note, the Week of Year specification wnn follows the ISO standard definition
+of the week of the year, where Week 1 is the week in which the first Thursday
+of the year occurs, or alternatively, the week which contains the 4th of
+January. Weeks are numbered w01 to w53. w00 for Bacula is the week that
+precedes the first ISO week (i.e. has the first few days of the year if any
+occur before Thursday). w00 is not defined by the ISO specification. A week
+starts with Monday and ends with Sunday.
+
+According to the NIST (US National Institute of Standards and Technology),
+12am and 12pm are ambiguous and can be defined to anything. However,
+12:01am is the same as 00:01 and 12:01pm is the same as 12:01, so Bacula
+defines 12am as 00:00 (midnight) and 12pm as 12:00 (noon). You can avoid
+this abiguity (confusion) by using 24 hour time specifications (i.e. no
+am/pm). This is the definition in Bacula version 2.0.3 and later.
+
+An example schedule resource that is named {\bf WeeklyCycle} and runs a job
+with level full each Sunday at 2:05am and an incremental job Monday through
+Saturday at 2:05am is:
+
+\footnotesize
+\begin{verbatim}
+Schedule {
+ Name = "WeeklyCycle"
+ Run = Level=Full sun at 2:05
+ Run = Level=Incremental mon-sat at 2:05
+}
+\end{verbatim}
+\normalsize
+
+An example of a possible monthly cycle is as follows:
+
+\footnotesize
+\begin{verbatim}
+Schedule {
+ Name = "MonthlyCycle"
+ Run = Level=Full Pool=Monthly 1st sun at 2:05
+ Run = Level=Differential 2nd-5th sun at 2:05
+ Run = Level=Incremental Pool=Daily mon-sat at 2:05
+}
+\end{verbatim}
+\normalsize
+
+The first of every month:
+
+\footnotesize
+\begin{verbatim}
+Schedule {
+ Name = "First"
+ Run = Level=Full on 1 at 2:05
+ Run = Level=Incremental on 2-31 at 2:05
+}
+\end{verbatim}
+\normalsize
+
+Every 10 minutes:
+
+\footnotesize
+\begin{verbatim}
+Schedule {
+ Name = "TenMinutes"
+ Run = Level=Full hourly at 0:05
+ Run = Level=Full hourly at 0:15
+ Run = Level=Full hourly at 0:25
+ Run = Level=Full hourly at 0:35
+ Run = Level=Full hourly at 0:45
+ Run = Level=Full hourly at 0:55
+}
+\end{verbatim}
+\normalsize
+
+\section{Technical Notes on Schedules}
+\index[general]{Schedules!Technical Notes on}
+\index[general]{Technical Notes on Schedules}
+
+Internally Bacula keeps a schedule as a bit mask. There are six masks and a
+minute field to each schedule. The masks are hour, day of the month (mday),
+month, day of the week (wday), week of the month (wom), and week of the year
+(woy). The schedule is initialized to have the bits of each of these masks
+set, which means that at the beginning of every hour, the job will run. When
+you specify a month for the first time, the mask will be cleared and the bit
+corresponding to your selected month will be selected. If you specify a second
+month, the bit corresponding to it will also be added to the mask. Thus when
+Bacula checks the masks to see if the bits are set corresponding to the
+current time, your job will run only in the two months you have set. Likewise,
+if you set a time (hour), the hour mask will be cleared, and the hour you
+specify will be set in the bit mask and the minutes will be stored in the
+minute field.
+
+For any schedule you have defined, you can see how these bits are set by doing
+a {\bf show schedules} command in the Console program. Please note that the
+bit mask is zero based, and Sunday is the first day of the week (bit zero).
+
+\input{fileset}
+
+\section{The Client Resource}
+\label{ClientResource2}
+\index[general]{Resource!Client}
+\index[general]{Client Resource}
+
+The Client resource defines the attributes of the Clients that are served by
+this Director; that is the machines that are to be backed up. You will need
+one Client resource definition for each machine to be backed up.
+
+\begin{description}
+
+\item [Client (or FileDaemon)]
+ \index[dir]{Client (or FileDaemon)}
+ \index[dir]{Directive!Client (or FileDaemon)}
+ Start of the Client directives.
+
+\item [Name = \lt{}name\gt{}]
+ \index[dir]{Name}
+ \index[dir]{Directive!Name}
+ The client name which will be used in the Job resource directive or in the
+console run command. This directive is required.
+
+\item [Address = \lt{}address\gt{}]
+ \index[dir]{Address}
+ \index[dir]{Directive!FD Address}
+ \index[dir]{File Daemon Address}
+ \index[dir]{Client Address}
+ Where the address is a host name, a fully qualified domain name, or a
+ network address in dotted quad notation for a Bacula File server daemon.
+ This directive is required.
+
+\item [FD Port = \lt{}port-number\gt{}]
+ \index[dir]{FD Port}
+ \index[dir]{Directive!FD Port}
+ Where the port is a port number at which the Bacula File server daemon can
+ be contacted. The default is 9102.
+
+\item [Catalog = \lt{}Catalog-resource-name\gt{}]
+ \index[dir]{Catalog}
+ \index[dir]{Directive!Catalog}
+ This specifies the name of the catalog resource to be used for this Client.
+ This directive is required.
+
+\item [Password = \lt{}password\gt{}]
+ \index[dir]{Password}
+ \index[dir]{Directive!Password}
+ This is the password to be used when establishing a connection with the File
+ services, so the Client configuration file on the machine to be backed up
+ must have the same password defined for this Director. This directive is
+ required. If you have either {\bf /dev/random} {\bf bc} on your machine,
+ Bacula will generate a random password during the configuration process,
+ otherwise it will be left blank.
+
+ The password is plain text. It is not generated through any special
+ process, but it is preferable for security reasons to make the text
+ random.
+
+\label{FileRetention}
+\item [File Retention = \lt{}time-period-specification\gt{}]
+ \index[dir]{File Retention}
+ \index[dir]{Directive!File Retention}
+ The File Retention directive defines the length of time that Bacula will
+ keep File records in the Catalog database after the End time of the
+ Job corresponding to the File records.
+ 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. Note, this affects
+ only records in the catalog database. It does not affect your archive
+ backups.
+
+ File records may actually be retained for a shorter period than you specify
+ on this directive if you specify either a shorter {\bf Job Retention} or a
+ shorter {\bf Volume Retention} period. The shortest retention period of the
+ three takes precedence. The time may be expressed in seconds, minutes,
+ hours, days, weeks, months, quarters, or years. See the
+ \ilink{ Configuration chapter}{Time} of this manual for
+ additional details of time specification.
+
+ The default is 60 days.
+
+\label{JobRetention}
+\item [Job Retention = \lt{}time-period-specification\gt{}]
+ \index[dir]{Job Retention}
+ \index[dir]{Directive!Job Retention}
+ The Job Retention directive defines the length of time that Bacula will keep
+ Job records in the Catalog database after the Job End time. 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
+ File Retention period. As with the other retention periods, this
+ affects only records in the catalog and not data in your archive backup.
+
+ 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. The Job retention period can actually
+ be less than the value you specify here if you set the {\bf Volume
+ Retention} directive in the Pool resource to a smaller duration. This is
+ because the Job retention period and the Volume retention period are
+ independently applied, so the smaller of the two takes precedence.
+
+ The Job retention period is specified as seconds, minutes, hours, days,
+ weeks, months, quarters, or years. See the
+ \ilink{ Configuration chapter}{Time} of this manual for
+ additional details of time specification.
+
+ The default is 180 days.
+
+\label{AutoPrune}
+\item [AutoPrune = \lt{}yes|no\gt{}]
+ \index[dir]{AutoPrune}
+ \index[dir]{Directive!AutoPrune}
+ If AutoPrune is set to {\bf yes} (default), Bacula (version 1.20 or greater)
+ will automatically apply the File retention period and the Job retention
+ period for the Client at the end of the Job. If you set {\bf AutoPrune = no},
+ pruning will not be done, and your Catalog will grow in size each time you
+ run a Job. Pruning affects only information in the catalog and not data
+ stored in the backup archives (on Volumes).
+
+\item [Maximum Concurrent Jobs = \lt{}number\gt{}]
+ \index[dir]{Maximum Concurrent Jobs}
+ \index[dir]{Directive!Maximum Concurrent Jobs}
+ where \lt{}number\gt{} is the maximum number of Jobs with the current Client
+ that can run concurrently. Note, this directive limits only Jobs for Clients
+ with the same name as the resource in which it appears. Any other
+ restrictions on the maximum concurrent jobs such as in the Director, Job, or
+ Storage resources will also apply in addition to any limit specified here.
+ The default is set to 1, but you may set it to a larger number. We strongly
+ recommend that you read the WARNING documented under
+ \ilink{ Maximum Concurrent Jobs}{DirMaxConJobs} in the Director's
+ resource.
+
+\item [Priority = \lt{}number\gt{}]
+ \index[dir]{Priority}
+ \index[dir]{Directive!Priority}
+ The number specifies the priority of this client relative to other clients
+ that the Director is processing simultaneously. The priority can range from
+ 1 to 1000. The clients are ordered such that the smaller number priorities
+ are performed first (not currently implemented).
+\end{description}
+
+ The following is an example of a valid Client resource definition:
+
+\footnotesize
+\begin{verbatim}
+Client {
+ Name = Minimatou
+ FDAddress = minimatou
+ Catalog = MySQL
+ Password = very_good
+}
+\end{verbatim}
+\normalsize
+
+\section{The Storage Resource}
+\label{StorageResource2}
+\index[general]{Resource!Storage}
+\index[general]{Storage Resource}
+
+The Storage resource defines which Storage daemons are available for use by
+the Director.
+
+\begin{description}
+
+\item [Storage]
+ \index[dir]{Storage}
+ \index[dir]{Directive!Storage}
+ Start of the Storage resources. At least one storage resource must be
+ specified.
+
+\item [Name = \lt{}name\gt{}]
+ \index[dir]{Name}
+ \index[dir]{Directive!Name}
+ The name of the storage resource. This name appears on the Storage directive
+ specified in the Job resource and is required.
+
+\item [Address = \lt{}address\gt{}]
+ \index[dir]{Address}
+ \index[dir]{Directive!SD Address}
+ \index[dir]{Storage daemon Address}
+ Where the address is a host name, a {\bf fully qualified domain name}, or an
+ {\bf IP address}. Please note that the \lt{}address\gt{} as specified here
+ will be transmitted to the File daemon who will then use it to contact the
+ Storage daemon. Hence, it is {\bf not}, a good idea to use {\bf localhost} as
+ the name but rather a fully qualified machine name or an IP address. This
+ directive is required.
+
+\item [SD Port = \lt{}port\gt{}]
+ \index[dir]{SD Port}
+ \index[dir]{Directive!SD Port}
+ Where port is the port to use to contact the storage daemon for information
+ and to start jobs. This same port number must appear in the Storage resource
+ of the Storage daemon's configuration file. The default is 9103.
+
+\item [Password = \lt{}password\gt{}]
+ \index[dir]{Password}
+ \index[dir]{Directive!Password}
+ This is the password to be used when establishing a connection with the
+ Storage services. This same password also must appear in the Director
+ resource of the Storage daemon's configuration file. This directive is
+ required. If you have either {\bf /dev/random} {\bf bc} on your machine,
+ Bacula will generate a random password during the configuration process,
+ otherwise it will be left blank.
+
+ The password is plain text. It is not generated through any special
+ process, but it is preferable for security reasons to use random text.
+
+\item [Device = \lt{}device-name\gt{}]
+ \index[dir]{Device}
+ \index[dir]{Directive!Device}
+ This directive specifies the Storage daemon's name of the device
+ resource to be used for the storage. If you are using an Autochanger,
+ the name specified here should be the name of the Storage daemon's
+ Autochanger resource rather than the name of an individual device. This
+ name is not the physical device name, but the logical device name as
+ defined on the {\bf Name} directive contained in the {\bf Device} or the
+ {\bf Autochanger} resource definition of the {\bf Storage daemon}
+ configuration file. You can specify any name you would like (even the
+ device name if you prefer) up to a maximum of 127 characters in length.
+ The physical device name associated with this device is specified in the
+ {\bf Storage daemon} configuration file (as {\bf Archive Device}).
+ Please take care not to define two different Storage resource directives
+ in the Director that point to the same Device in the Storage daemon.
+ Doing so may cause the Storage daemon to block (or hang) attempting to
+ open the same device that is already open. This directive is required.
+
+\label{MediaType}
+\item [Media Type = \lt{}MediaType\gt{}]
+ \index[dir]{Media Type}
+ \index[dir]{Directive!Media Type}
+ This directive specifies the Media Type to be used to store the data.
+ This is an arbitrary string of characters up to 127 maximum that you
+ define. It can be anything you want. However, it is best to make it
+ descriptive of the storage media (e.g. File, DAT, "HP DLT8000", 8mm,
+ ...). In addition, it is essential that you make the {\bf Media Type}
+ specification unique for each storage media type. If you have two DDS-4
+ drives that have incompatible formats, or if you have a DDS-4 drive and
+ a DDS-4 autochanger, you almost certainly should specify different {\bf
+ Media Types}. During a restore, assuming a {\bf DDS-4} Media Type is
+ associated with the Job, Bacula can decide to use any Storage daemon
+ that supports Media Type {\bf DDS-4} and on any drive that supports it.
+
+ If you are writing to disk Volumes, you must make doubly sure that each
+ Device resource defined in the Storage daemon (and hence in the
+ Director's conf file) has a unique media type. Otherwise for Bacula
+ versions 1.38 and older, your restores may not work because Bacula
+ will assume that you can mount any Media Type with the same name on
+ any Device associated with that Media Type. This is possible with
+ tape drives, but with disk drives, unless you are very clever you
+ cannot mount a Volume in any directory -- this can be done by creating
+ an appropriate soft link.
+
+ Currently Bacula permits only a single Media Type per Storage
+ and Device definition. Consequently, if
+ you have a drive that supports more than one Media Type, you can
+ give a unique string to Volumes with different intrinsic Media
+ Type (Media Type = DDS-3-4 for DDS-3 and DDS-4 types), but then
+ those volumes will only be mounted on drives indicated with the
+ dual type (DDS-3-4).
+
+ If you want to tie Bacula to using a single Storage daemon or drive, you
+ must specify a unique Media Type for that drive. This is an important
+ point that should be carefully understood. Note, this applies equally
+ to Disk Volumes. If you define more than one disk Device resource in
+ your Storage daemon's conf file, the Volumes on those two devices are in
+ fact incompatible because one can not be mounted on the other device
+ since they are found in different directories. For this reason, you
+ probably should use two different Media Types for your two disk Devices
+ (even though you might think of them as both being File types). You can
+ find more on this subject in the \ilink{Basic Volume
+ Management}{DiskChapter} chapter of this manual.
+
+ The {\bf MediaType} specified in the Director's Storage resource, {\bf
+ must} correspond to the {\bf Media Type} specified in the {\bf Device}
+ resource of the {\bf Storage daemon} configuration file. This directive
+ is required, and it is used by the Director and the Storage daemon to
+ ensure that a Volume automatically selected from the Pool corresponds to
+ the physical device. If a Storage daemon handles multiple devices (e.g.
+ will write to various file Volumes on different partitions), this
+ directive allows you to specify exactly which device.
+
+ As mentioned above, the value specified in the Director's Storage
+ resource must agree with the value specified in the Device resource in
+ the {\bf Storage daemon's} configuration file. It is also an additional
+ check so that you don't try to write data for a DLT onto an 8mm device.
+
+\label{Autochanger1}
+\item [Autochanger = \lt{}yes|no\gt{}]
+ \index[dir]{Autochanger}
+ \index[dir]{Directive!Autochanger}
+ If you specify {\bf yes} for this command (the default is {\bf no}),
+ when you use the {\bf label} command or the {\bf add} command to create
+ a new Volume, {\bf Bacula} will also request the Autochanger Slot
+ number. This simplifies creating database entries for Volumes in an
+ autochanger. If you forget to specify the Slot, the autochanger will
+ not be used. However, you may modify the Slot associated with a Volume
+ at any time by using the {\bf update volume} or {\bf update slots}
+ command in the console program. When {\bf autochanger} is enabled, the
+ algorithm used by Bacula to search for available volumes will be
+ modified to consider only Volumes that are known to be in the
+ autochanger's magazine. If no {\bf in changer} volume is found, Bacula
+ will attempt recycling, pruning, ..., and if still no volume is found,
+ Bacula will search for any volume whether or not in the magazine. By
+ privileging in changer volumes, this procedure minimizes operator
+ intervention. The default is {\bf no}.
+
+ For the autochanger to be used, you must also specify {\bf Autochanger =
+ yes} in the \ilink{Device Resource}{Autochanger} in the Storage daemon's
+ configuration file as well as other important Storage daemon
+ configuration information. Please consult the \ilink{Using
+ Autochangers}{AutochangersChapter} manual of this chapter for the
+ details of using autochangers.
+
+\item [Maximum Concurrent Jobs = \lt{}number\gt{}]
+ \index[dir]{Maximum Concurrent Jobs}
+ \index[dir]{Directive!Maximum Concurrent Jobs}
+ where \lt{}number\gt{} is the maximum number of Jobs with the current
+ Storage resource that can run concurrently. Note, this directive limits
+ only Jobs for Jobs using this Storage daemon. Any other restrictions on
+ the maximum concurrent jobs such as in the Director, Job, or Client
+ resources will also apply in addition to any limit specified here. The
+ default is set to 1, but you may set it to a larger number. However, if
+ you set the Storage daemon's number of concurrent jobs greater than one,
+ we recommend that you read the waring documented under \ilink{Maximum
+ Concurrent Jobs}{DirMaxConJobs} in the Director's resource or simply
+ turn data spooling on as documented in the \ilink{Data
+ Spooling}{SpoolingChapter} chapter of this manual.
+
+\item [Heartbeat Interval = \lt{}time-interval\gt{}]
+ \index[dir]{Heartbeat Interval}
+ \index[dir]{Directive!Heartbeat}
+ This directive is optional and if specified will cause the Director to
+ set a keepalive interval (heartbeat) in seconds on each of the sockets
+ it opens for the Storage resource. This value will override any
+ specified at the Director level. It is implemented only on systems
+ (Linux, ...) that provide the {\bf setsockopt} TCP\_KEEPIDLE function.
+ The default value is zero, which means no change is made to the socket.
+
+\end{description}
+
+The following is an example of a valid Storage resource definition:
+
+\footnotesize
+\begin{verbatim}
+# Definition of tape storage device
+Storage {
+ Name = DLTDrive
+ Address = lpmatou
+ Password = storage_password # password for Storage daemon
+ Device = "HP DLT 80" # same as Device in Storage daemon
+ Media Type = DLT8000 # same as MediaType in Storage daemon
+}
+\end{verbatim}
+\normalsize
+
+\section{The Pool Resource}
+\label{PoolResource}
+\index[general]{Resource!Pool}
+\index[general]{Pool Resource}
+
+The Pool resource defines the set of storage Volumes (tapes or files) to be
+used by Bacula to write the data. By configuring different Pools, you can
+determine which set of Volumes (media) receives the backup data. This permits,
+for example, to store all full backup data on one set of Volumes and all
+incremental backups on another set of Volumes. Alternatively, you could assign
+a different set of Volumes to each machine that you backup. This is most
+easily done by defining multiple Pools.
+
+Another important aspect of a Pool is that it contains the default attributes
+(Maximum Jobs, Retention Period, Recycle flag, ...) that will be given to a
+Volume when it is created. This avoids the need for you to answer a large
+number of questions when labeling a new Volume. Each of these attributes can
+later be changed on a Volume by Volume basis using the {\bf update} command in
+the console program. Note that you must explicitly specify which Pool Bacula
+is to use with each Job. Bacula will not automatically search for the correct
+Pool.
+
+Most often in Bacula installations all backups for all machines (Clients) go
+to a single set of Volumes. In this case, you will probably only use the {\bf
+Default} Pool. If your backup strategy calls for you to mount a different tape
+each day, you will probably want to define a separate Pool for each day. For
+more information on this subject, please see the
+\ilink{Backup Strategies}{StrategiesChapter} chapter of this
+manual.
+
+
+To use a Pool, there are three distinct steps. First the Pool must be defined
+in the Director's configuration file. Then the Pool must be written to the
+Catalog database. This is done automatically by the Director each time that it
+starts, or alternatively can be done using the {\bf create} command in the
+console program. Finally, if you change the Pool definition in the Director's
+configuration file and restart Bacula, the pool will be updated alternatively
+you can use the {\bf update pool} console command to refresh the database
+image. It is this database image rather than the Director's resource image
+that is used for the default Volume attributes. Note, for the pool to be
+automatically created or updated, it must be explicitly referenced by a Job
+resource.
+
+Next the physical media must be labeled. The labeling can either be done with
+the {\bf label} command in the {\bf console} program or using the {\bf btape}
+program. The preferred method is to use the {\bf label} command in the {\bf
+console} program.
+
+Finally, you must add Volume names (and their attributes) to the Pool. For
+Volumes to be used by Bacula they must be of the same {\bf Media Type} as the
+archive device specified for the job (i.e. if you are going to back up to a
+DLT device, the Pool must have DLT volumes defined since 8mm volumes cannot be
+mounted on a DLT drive). The {\bf Media Type} has particular importance if you
+are backing up to files. When running a Job, you must explicitly specify which
+Pool to use. Bacula will then automatically select the next Volume to use from
+the Pool, but it will ensure that the {\bf Media Type} of any Volume selected
+from the Pool is identical to that required by the Storage resource you have
+specified for the Job.
+
+If you use the {\bf label} command in the console program to label the
+Volumes, they will automatically be added to the Pool, so this last step is
+not normally required.
+
+It is also possible to add Volumes to the database without explicitly labeling
+the physical volume. This is done with the {\bf add} console command.
+
+As previously mentioned, each time Bacula starts, it scans all the Pools
+associated with each Catalog, and if the database record does not already
+exist, it will be created from the Pool Resource definition. {\bf Bacula}
+probably should do an {\bf update pool} if you change the Pool definition, but
+currently, you must do this manually using the {\bf update pool} command in
+the Console program.
+
+The Pool Resource defined in the Director's configuration file
+(bacula-dir.conf) may contain the following directives:
+
+\begin{description}
+
+\item [Pool]
+ \index[dir]{Pool}
+ \index[dir]{Directive!Pool}
+ Start of the Pool resource. There must be at least one Pool resource
+ defined.
+
+
+\item [Name = \lt{}name\gt{}]
+ \index[dir]{Name}
+ \index[dir]{Directive!Name}
+ The name of the pool. For most applications, you will use the default
+ pool name {\bf Default}. This directive is required.
+
+\label{MaxVolumes}
+\item [Maximum Volumes = \lt{}number\gt{}]
+ \index[dir]{Maximum Volumes}
+ \index[dir]{Directive!Maximum Volumes}
+ This directive specifies the maximum number of volumes (tapes or files)
+ contained in the pool. This directive is optional, if omitted or set to
+ zero, any number of volumes will be permitted. In general, this
+ directive is useful for Autochangers where there is a fixed number of
+ Volumes, or for File storage where you wish to ensure that the backups
+ made to disk files do not become too numerous or consume too much space.
+
+\item [Pool Type = \lt{}type\gt{}]
+ \index[dir]{Pool Type}
+ \index[dir]{Directive!Pool Type}
+ This directive defines the pool type, which corresponds to the type of
+ Job being run. It is required and may be one of the following:
+
+\begin{itemize}
+ \item [Backup]
+ \item [*Archive]
+ \item [*Cloned]
+ \item [*Migration]
+ \item [*Copy]
+ \item [*Save]
+\end{itemize}
+ Note, only Backup is current implemented.
+
+\item [Storage = \lt{}storage-resource-name\gt{}]
+\index[dir]{Storage}
+\index[dir]{Directive!Storage}
+ The Storage directive defines the name of the storage services where you
+ want to backup the FileSet data. For additional details, see the
+ \ilink{Storage Resource Chapter}{StorageResource2} of this manual.
+ The Storage resource may also be specified in the Job resource,
+ but the value, if any, in the Pool resource overrides any value
+ in the Job. This Storage resource definition is not required by either
+ the Job resource or in the Pool, but it must be specified in
+ one or the other. If not configuration error will result.
+
+\item [Use Volume Once = \lt{}yes|no\gt{}]
+ \index[dir]{Use Volume Once}
+ \index[dir]{Directive!Use Volume Once}
+ This directive if set to {\bf yes} specifies that each volume is to be
+ used only once. This is most useful when the Media is a file and you
+ want a new file for each backup that is done. The default is {\bf no}
+ (i.e. use volume any number of times). This directive will most likely
+ be phased out (deprecated), so you are recommended to use {\bf Maximum
+ Volume Jobs = 1} instead.
+
+ The value defined by this directive in the bacula-dir.conf file is the
+ default value used when a Volume is created. Once the volume is
+ created, changing the value in the bacula-dir.conf file will not change
+ what is stored for the Volume. To change the value for an existing
+ Volume you must use the {\bf update} command in the Console.
+
+ Please see the notes below under {\bf Maximum Volume Jobs} concerning
+ using this directive with multiple simultaneous jobs.
+
+\item [Maximum Volume Jobs = \lt{}positive-integer\gt{}]
+ \index[dir]{Maximum Volume Jobs}
+ \index[dir]{Directive!Maximum Volume Jobs}
+ This directive specifies the maximum number of Jobs that can be written
+ to the Volume. If you specify zero (the default), there is no limit.
+ Otherwise, when the number of Jobs backed up to the Volume equals {\bf
+ positive-integer} the Volume will be marked {\bf Used}. When the Volume
+ is marked {\bf Used} it can no longer be used for appending Jobs, much
+ like the {\bf Full} status but it can be recycled if recycling is
+ enabled, and thus used again. By setting {\bf MaximumVolumeJobs} to
+ one, you get the same effect as setting {\bf UseVolumeOnce = yes}.
+
+ The value defined by this directive in the bacula-dir.conf
+ file is the default value used when a Volume is created. Once the volume is
+ created, changing the value in the bacula-dir.conf file will not change what
+ is stored for the Volume. To change the value for an existing Volume you
+ must use the {\bf update} command in the Console.
+
+ If you are running multiple simultaneous jobs, this directive may not
+ work correctly because when a drive is reserved for a job, this
+ directive is not taken into account, so multiple jobs may try to
+ start writing to the Volume. At some point, when the Media record is
+ updated, multiple simultaneous jobs may fail since the Volume can no
+ longer be written.
+
+\item [Maximum Volume Files = \lt{}positive-integer\gt{}]
+ \index[dir]{Maximum Volume Files}
+ \index[dir]{Directive!Maximum Volume Files}
+ This directive specifies the maximum number of files that can be written
+ to the Volume. If you specify zero (the default), there is no limit.
+ Otherwise, when the number of files written to the Volume equals {\bf
+ positive-integer} the Volume will be marked {\bf Used}. When the Volume
+ is marked {\bf Used} it can no longer be used for appending Jobs, much
+ like the {\bf Full} status but it can be recycled if recycling is
+ enabled and thus used again. This value is checked and the {\bf Used}
+ status is set only at the end of a job that writes to the particular
+ volume.
+
+ The value defined by this directive in the bacula-dir.conf file is the
+ default value used when a Volume is created. Once the volume is
+ created, changing the value in the bacula-dir.conf file will not change
+ what is stored for the Volume. To change the value for an existing
+ Volume you must use the {\bf update} command in the Console.
+
+\item [Maximum Volume Bytes = \lt{}size\gt{}]
+ \index[dir]{Maximum Volume Bytes}
+ \index[dir]{Directive!Maximum Volume Bytes}
+ This directive specifies the maximum number of bytes that can be written
+ to the Volume. If you specify zero (the default), there is no limit
+ except the physical size of the Volume. Otherwise, when the number of
+ bytes written to the Volume equals {\bf size} the Volume will be marked
+ {\bf Used}. When the Volume is marked {\bf Used} it can no longer be
+ used for appending Jobs, much like the {\bf Full} status but it can be
+ recycled if recycling is enabled, and thus the Volume can be re-used
+ after recycling. This value is checked and the {\bf Used} status set
+ while the job is writing to the particular volume.
+
+ This directive is particularly useful for restricting the size
+ of disk volumes, and will work correctly even in the case of
+ multiple simultaneous jobs writing to the volume.
+
+ The value defined by this directive in the bacula-dir.conf file is the
+ default value used when a Volume is created. Once the volume is
+ created, changing the value in the bacula-dir.conf file will not change
+ what is stored for the Volume. To change the value for an existing
+ Volume you must use the {\bf update} command in the Console.
+
+\item [Volume Use Duration = \lt{}time-period-specification\gt{}]
+ \index[dir]{Volume Use Duration}
+ \index[dir]{Directive!Volume Use Duration}
+ The Volume Use Duration directive defines the time period that the
+ Volume can be written beginning from the time of first data write to the
+ Volume. If the time-period specified is zero (the default), the Volume
+ can be written indefinitely. Otherwise, the next time a job
+ runs that wants to access this Volume, and the time period from the
+ first write to the volume (the first Job written) exceeds the
+ time-period-specification, the Volume will be marked {\bf Used}, which
+ means that no more Jobs can be appended to the Volume, but it may be
+ recycled if recycling is enabled. Using the command {\bf
+ status dir} applies algorithms similar to running jobs, so
+ during such a command, the Volume status may also be changed.
+ Once the Volume is
+ recycled, it will be available for use again.
+
+ You might use this directive, for example, if you have a Volume used for
+ Incremental backups, and Volumes used for Weekly Full backups. Once the
+ Full backup is done, you will want to use a different Incremental
+ Volume. This can be accomplished by setting the Volume Use Duration for
+ the Incremental Volume to six days. I.e. it will be used for the 6
+ days following a Full save, then a different Incremental volume will be
+ used. Be careful about setting the duration to short periods such as 23
+ hours, or you might experience problems of Bacula waiting for a tape
+ over the weekend only to complete the backups Monday morning when an
+ operator mounts a new tape.
+
+ The use duration is checked and the {\bf Used} status is set only at the
+ end of a job that writes to the particular volume, which means that even
+ though the use duration may have expired, the catalog entry will not be
+ updated until the next job that uses this volume is run. This
+ directive is not intended to be used to limit volume sizes
+ and will not work correctly (i.e. will fail jobs) if the use
+ duration expires while multiple simultaneous jobs are writing
+ to the volume.
+
+ Please note that the value defined by this directive in the bacula-dir.conf
+ file is the default value used when a Volume is created. Once the volume is
+ created, changing the value in the bacula-dir.conf file will not change what
+ is stored for the Volume. To change the value for an existing Volume you
+ must use the
+ \ilink{\bf update volume}{UpdateCommand} command in the Console.
+
+\item [Catalog Files = \lt{}yes|no\gt{}]
+ \index[dir]{Catalog Files}
+ \index[dir]{Directive!Catalog Files}
+ This directive defines whether or not you want the names of the files
+ that were saved to be put into the catalog. The default is {\bf yes}.
+ The advantage of specifying {\bf Catalog Files = No} is that you will
+ have a significantly smaller Catalog database. The disadvantage is that
+ you will not be able to produce a Catalog listing of the files backed up
+ for each Job (this is often called Browsing). Also, without the File
+ entries in the catalog, you will not be able to use the Console {\bf
+ restore} command nor any other command that references File entries.
+
+\label{PoolAutoPrune}
+\item [AutoPrune = \lt{}yes|no\gt{}]
+ \index[dir]{AutoPrune}
+ \index[dir]{Directive!AutoPrune}
+ If AutoPrune is set to {\bf yes} (default), Bacula (version 1.20 or
+ greater) will automatically apply the Volume Retention period when new
+ Volume is needed and no appendable Volumes exist in the Pool. Volume
+ pruning causes expired Jobs (older than the {\bf Volume Retention}
+ period) to be deleted from the Catalog and permits possible recycling of
+ the Volume.
+
+\label{VolRetention}
+\item [Volume Retention = \lt{}time-period-specification\gt{}]
+ \index[dir]{Volume Retention}
+ \index[dir]{Directive!Volume Retention}
+ The Volume Retention directive defines the length of time that {\bf
+ Bacula} will keep records associated with the Volume in
+ the Catalog database after the End time of each Job written to the
+ Volume. When this time period expires, and if {\bf AutoPrune} is set to
+ {\bf yes} Bacula may prune (remove) Job records that are older than the
+ specified Volume Retention period if it is necessary to free up a
+ Volume. Recycling will not occur until it is absolutely necessary to
+ free up a volume (i.e. no other writable volume exists).
+ All File records associated with pruned Jobs are also
+ pruned. The time may be specified as seconds, minutes, hours, days,
+ weeks, months, quarters, or years. The {\bf Volume Retention} is
+ applied independently of the {\bf Job Retention} and the {\bf File
+ Retention} periods defined in the Client resource. This means that all
+ the retentions periods are applied in turn and that the shorter period
+ is the one that effectively takes precedence. Note, that when the {\bf
+ Volume Retention} period has been reached, and it is necessary to obtain
+ a new volume, Bacula will prune both the Job and the File records. This
+ pruning could also occur during a {\bf status dir} command because it
+ uses similar algorithms for finding the next available Volume.
+
+ It is important to know that when the Volume Retention period expires,
+ Bacula does not automatically recycle a Volume. It attempts to keep the
+ Volume data intact as long as possible before over writing the Volume.
+
+
+ By defining multiple Pools with different Volume Retention periods, you
+ may effectively have a set of tapes that is recycled weekly, another
+ Pool of tapes that is recycled monthly and so on. However, one must
+ keep in mind that if your {\bf Volume Retention} period is too short, it
+ may prune the last valid Full backup, and hence until the next Full
+ backup is done, you will not have a complete backup of your system, and
+ in addition, the next Incremental or Differential backup will be
+ promoted to a Full backup. As a consequence, the minimum {\bf Volume
+ Retention} period should be at twice the interval of your Full backups.
+ This means that if you do a Full backup once a month, the minimum Volume
+ retention period should be two months.
+
+ The default Volume retention period is 365 days, and either the default
+ or the value defined by this directive in the bacula-dir.conf file is
+ the default value used when a Volume is created. Once the volume is
+ created, changing the value in the bacula-dir.conf file will not change
+ what is stored for the Volume. To change the value for an existing
+ Volume you must use the {\bf update} command in the Console.
+
+\label{PoolRecyclePool}
+\item [RecyclePool = \lt{}pool-resource-name\gt{}]
+ \index[dir]{RecyclePool}
+ \index[dir]{Directive!RecyclePool}
+ On versions 2.1.4 or greater, this directive defines to which pool
+ the Volume will be placed (moved) when it is recycled. Without
+ this directive, a Volume will remain in the same pool when it is
+ recycled. With this directive, it can be moved automatically to any
+ existing pool during a recycle. This directive is probably most
+ useful when defined in the Scratch pool, so that volumes will
+ be recycled back into the Scratch pool. For more on the see the
+ \ilink{Scratch Pool}{TheScratchPool} section of this manual.
+
+ Although this directive is called RecyclePool, the Volume in
+ question is actually moved from its current pool to the one
+ you specify on this directive when Bacula prunes the Volume and
+ discovers that there are no records left in the catalog and hence
+ marks it as {\bf Purged}.
+
+
+\label{PoolRecycle}
+\item [Recycle = \lt{}yes|no\gt{}]
+ \index[dir]{Recycle}
+ \index[dir]{Directive!Recycle}
+ This directive specifies whether or not Purged Volumes may be recycled.
+ If it is set to {\bf yes} (default) and Bacula needs a volume but finds
+ none that are appendable, it will search for and recycle (reuse) Purged
+ Volumes (i.e. volumes with all the Jobs and Files expired and thus
+ deleted from the Catalog). If the Volume is recycled, all previous data
+ written to that Volume will be overwritten. If Recycle is set to {\bf
+ no}, the Volume will not be recycled, and hence, the data will remain
+ valid. If you want to reuse (re-write) the Volume, and the recycle flag
+ is no (0 in the catalog), you may manually set the recycle flag (update
+ command) for a Volume to be reused.
+
+ Please note that the value defined by this directive in the
+ bacula-dir.conf file is the default value used when a Volume is created.
+ Once the volume is created, changing the value in the bacula-dir.conf
+ file will not change what is stored for the Volume. To change the value
+ for an existing Volume you must use the {\bf update} command in the
+ Console.
+
+ When all Job and File records have been pruned or purged from the
+ catalog for a particular Volume, if that Volume is marked as
+ Append, Full, Used, or Error, it will then be marked as Purged. Only
+ Volumes marked as Purged will be considered to be converted to the
+ Recycled state if the {\bf Recycle} directive is set to {\bf yes}.
+
+
+\label{RecycleOldest}
+\item [Recycle Oldest Volume = \lt{}yes|no\gt{}]
+ \index[dir]{Recycle Oldest Volume}
+ \index[dir]{Directive!Recycle Oldest Volume}
+ This directive instructs the Director to search for the oldest used
+ Volume in the Pool when another Volume is requested by the Storage
+ daemon and none are available. The catalog is then {\bf pruned}
+ respecting the retention periods of all Files and Jobs written to this
+ Volume. If all Jobs are pruned (i.e. the volume is Purged), then the
+ Volume is recycled and will be used as the next Volume to be written.
+ This directive respects any Job, File, or Volume retention periods that
+ you may have specified, and as such it is {\bf much} better to use this
+ directive than the Purge Oldest Volume.
+
+ This directive can be useful if you have a fixed number of Volumes in the
+ Pool and you want to cycle through them and you have specified the correct
+ retention periods.
+
+ However, if you use this directive and have only one
+ Volume in the Pool, you will immediately recycle your Volume if you fill
+ it and Bacula needs another one. Thus your backup will be totally invalid.
+ Please use this directive with care. The default is {\bf no}.
+
+\label{RecycleCurrent}
+
+\item [Recycle Current Volume = \lt{}yes|no\gt{}]
+ \index[dir]{Recycle Current Volume}
+ \index[dir]{Directive!Recycle Current Volume}
+ If Bacula needs a new Volume, this directive instructs Bacula to Prune
+ the volume respecting the Job and File retention periods. If all Jobs
+ are pruned (i.e. the volume is Purged), then the Volume is recycled and
+ will be used as the next Volume to be written. This directive respects
+ any Job, File, or Volume retention periods that you may have specified,
+ and thus it is {\bf much} better to use it rather than the Purge Oldest
+ Volume directive.
+
+ This directive can be useful if you have: a fixed number of Volumes in
+ the Pool, you want to cycle through them, and you have specified
+ retention periods that prune Volumes before you have cycled through the
+ Volume in the Pool.
+
+ However, if you use this directive and have only one Volume in the Pool,
+ you will immediately recycle your Volume if you fill it and Bacula needs
+ another one. Thus your backup will be totally invalid. Please use this
+ directive with care. The default is {\bf no}.
+
+\label{PurgeOldest}
+
+\item [Purge Oldest Volume = \lt{}yes|no\gt{}]
+ \index[dir]{Purge Oldest Volume}
+ \index[dir]{Directive!Purge Oldest Volume}
+ This directive instructs the Director to search for the oldest used
+ Volume in the Pool when another Volume is requested by the Storage
+ daemon and none are available. The catalog is then {\bf purged}
+ irrespective of retention periods of all Files and Jobs written to this
+ Volume. The Volume is then recycled and will be used as the next Volume
+ to be written. This directive overrides any Job, File, or Volume
+ retention periods that you may have specified.
+
+ This directive can be useful if you have a fixed number of Volumes in
+ the Pool and you want to cycle through them and reusing the oldest one
+ when all Volumes are full, but you don't want to worry about setting
+ proper retention periods. However, by using this option you risk losing
+ valuable data.
+
+ Please be aware that {\bf Purge Oldest Volume} disregards all retention
+ periods. If you have only a single Volume defined and you turn this
+ variable on, that Volume will always be immediately overwritten when it
+ fills! So at a minimum, ensure that you have a decent number of Volumes
+ in your Pool before running any jobs. If you want retention periods to
+ apply do not use this directive. To specify a retention period, use the
+ {\bf Volume Retention} directive (see above).
+
+ We {\bf highly} recommend against using this directive, because it is
+ sure that some day, Bacula will recycle a Volume that contains current
+ data. The default is {\bf no}.
+
+\item [Cleaning Prefix = \lt{}string\gt{}]
+ \index[dir]{Cleaning Prefix}
+ \index[dir]{Directive!Cleaning Prefix}
+ This directive defines a prefix string, which if it matches the
+ beginning of a Volume name during labeling of a Volume, the Volume will
+ be defined with the VolStatus set to {\bf Cleaning} and thus Bacula will
+ never attempt to use this tape. This is primarily for use with
+ autochangers that accept barcodes where the convention is that barcodes
+ beginning with {\bf CLN} are treated as cleaning tapes.
+
+\label{Label}
+\item [Label Format = \lt{}format\gt{}]
+ \index[dir]{Label Format}
+ \index[dir]{Directive!Label Format}
+ This directive specifies the format of the labels contained in this
+ pool. The format directive is used as a sort of template to create new
+ Volume names during automatic Volume labeling.
+
+ The {\bf format} should be specified in double quotes, and consists of
+ letters, numbers and the special characters hyphen ({\bf -}), underscore
+ ({\bf \_}), colon ({\bf :}), and period ({\bf .}), which are the legal
+ characters for a Volume name. The {\bf format} should be enclosed in
+ double quotes (").
+
+ In addition, the format may contain a number of variable expansion
+ characters which will be expanded by a complex algorithm allowing you to
+ create Volume names of many different formats. In all cases, the
+ expansion process must resolve to the set of characters noted above that
+ are legal Volume names. Generally, these variable expansion characters
+ begin with a dollar sign ({\bf \$}) or a left bracket ({\bf [}). If you
+ specify variable expansion characters, you should always enclose the
+ format with double quote characters ({\bf "}). For more details on
+ variable expansion, please see the \ilink{Variable
+ Expansion}{VarsChapter} Chapter of this manual.
+
+ If no variable expansion characters are found in the string, the Volume
+ name will be formed from the {\bf format} string appended with the
+ number of volumes in the pool plus one, which will be edited as four
+ digits with leading zeros. For example, with a {\bf Label Format =
+ "File-"}, the first volumes will be named {\bf File-0001}, {\bf
+ File-0002}, ...
+
+ With the exception of Job specific variables, you can test your {\bf
+ LabelFormat} by using the \ilink{ var command}{var} the Console Chapter
+ of this manual.
+
+ In almost all cases, you should enclose the format specification (part
+ after the equal sign) in double quotes. Please note that this directive
+ is deprecated and is replaced in version 1.37 and greater with a Python
+ script for creating volume names.
+
+\end{description}
+
+In order for a Pool to be used during a Backup Job, the Pool must have at
+least one Volume associated with it. Volumes are created for a Pool using
+the {\bf label} or the {\bf add} commands in the {\bf Bacula Console},
+program. In addition to adding Volumes to the Pool (i.e. putting the
+Volume names in the Catalog database), the physical Volume must be labeled
+with a valid Bacula software volume label before {\bf Bacula} will accept
+the Volume. This will be automatically done if you use the {\bf label}
+command. Bacula can automatically label Volumes if instructed to do so,
+but this feature is not yet fully implemented.
+
+The following is an example of a valid Pool resource definition:
+
+\footnotesize
+\begin{verbatim}
+
+Pool {
+ Name = Default
+ Pool Type = Backup
+}
+\end{verbatim}
+\normalsize
+
+\subsection{The Scratch Pool}
+\label{TheScratchPool}
+\index[general]{Scratch Pool}
+In general, you can give your Pools any name you wish, but there is one
+important restriction: the Pool named {\bf Scratch}, if it exists behaves
+like a scratch pool of Volumes in that when Bacula needs a new Volume for
+writing and it cannot find one, it will look in the Scratch pool, and if
+it finds an available Volume, it will move it out of the Scratch pool into
+the Pool currently being used by the job.
+
+
+\section{The Catalog Resource}
+\label{CatalogResource}
+\index[general]{Resource!Catalog}
+\index[general]{Catalog Resource}
+
+The Catalog Resource defines what catalog to use for the current job.
+Currently, Bacula can only handle a single database server (SQLite, MySQL,
+PostgreSQL) that is defined when configuring {\bf Bacula}. However, there
+may be as many Catalogs (databases) defined as you wish. For example, you
+may want each Client to have its own Catalog database, or you may want
+backup jobs to use one database and verify or restore jobs to use another
+database.
+
+Since SQLite is compiled in, it always runs on the same machine
+as the Director and the database must be directly accessible (mounted) from
+the Director. However, since both MySQL and PostgreSQL are networked
+databases, they may reside either on the same machine as the Director
+or on a different machine on the network. See below for more details.
+
+\begin{description}
+
+\item [Catalog]
+ \index[dir]{Catalog}
+ \index[dir]{Directive!Catalog}
+ Start of the Catalog resource. At least one Catalog resource must be
+defined.
+
+
+\item [Name = \lt{}name\gt{}]
+ \index[dir]{Name}
+ \index[dir]{Directive!Name}
+ The name of the Catalog. No necessary relation to the database server
+ name. This name will be specified in the Client resource directive
+ indicating that all catalog data for that Client is maintained in this
+ Catalog. This directive is required.
+
+\item [password = \lt{}password\gt{}]
+ \index[dir]{password}
+ \index[dir]{Directive!password}
+ This specifies the password to use when logging into the database. This
+ directive is required.
+
+\item [DB Name = \lt{}name\gt{}]
+ \index[dir]{DB Name}
+ \index[dir]{Directive!DB Name}
+ This specifies the name of the database. If you use multiple catalogs
+ (databases), you specify which one here. If you are using an external
+ database server rather than the internal one, you must specify a name
+ that is known to the server (i.e. you explicitly created the Bacula
+ tables using this name. This directive is required.
+
+\item [user = \lt{}user\gt{}]
+ \index[dir]{user}
+ \index[dir]{Directive!user}
+ This specifies what user name to use to log into the database. This
+ directive is required.
+
+\item [DB Socket = \lt{}socket-name\gt{}]
+ \index[dir]{DB Socket}
+ \index[dir]{Directive!DB Socket}
+ This is the name of a socket to use on the local host to connect to the
+ database. This directive is used only by MySQL and is ignored by SQLite.
+ Normally, if neither {\bf DB Socket} or {\bf DB Address} are specified, MySQL
+ will use the default socket. If the DB Socket is specified, the
+ MySQL server must reside on the same machine as the Director.
+
+\item [DB Address = \lt{}address\gt{}]
+ \index[dir]{DB Address}
+ \index[dir]{Directive!DB Address}
+ This is the host address of the database server. Normally, you would specify
+ this instead of {\bf DB Socket} if the database server is on another machine.
+ In that case, you will also specify {\bf DB Port}. This directive is used
+ only by MySQL and PostgreSQL and is ignored by SQLite if provided.
+ This directive is optional.
+
+\item [DB Port = \lt{}port\gt{}]
+ \index[dir]{DB Port}
+ \index[dir]{Directive!DB Port}
+ This defines the port to be used in conjunction with {\bf DB Address} to
+ access the database if it is on another machine. This directive is used only
+ by MySQL and PostgreSQL and is ignored by SQLite if provided. This
+ directive is optional.
+
+%% \item [Multiple Connections = \lt{}yes|no\gt{}]
+%% \index[dir]{Multiple Connections}
+%% \index[dir]{Directive!Multiple Connections}
+%% By default, this directive is set to no. In that case, each job that uses
+the
+%% same Catalog will use a single connection to the catalog. It will be shared,
+%% and Bacula will allow only one Job at a time to communicate. If you set this
+%% directive to yes, Bacula will permit multiple connections to the database,
+%% and the database must be multi-thread capable. For SQLite and PostgreSQL,
+%% this is no problem. For MySQL, you must be *very* careful to have the
+%% multi-thread version of the client library loaded on your system. When this
+%% directive is set yes, each Job will have a separate connection to the
+%% database, and the database will control the interaction between the
+different
+%% Jobs. This can significantly speed up the database operations if you are
+%% running multiple simultaneous jobs. In addition, for SQLite and PostgreSQL,
+%% Bacula will automatically enable transactions. This can significantly speed
+%% up insertion of attributes in the database either for a single Job or
+%% multiple simultaneous Jobs.
+
+%% This directive has not been tested. Please test carefully before running it
+%% in production and report back your results.
+
+\end{description}
+
+The following is an example of a valid Catalog resource definition:
+
+\footnotesize
+\begin{verbatim}
+Catalog
+{
+ Name = SQLite
+ dbname = bacula;
+ user = bacula;
+ password = "" # no password = no security
+}
+\end{verbatim}
+\normalsize
+
+or for a Catalog on another machine:
+
+\footnotesize
+\begin{verbatim}
+Catalog
+{
+ Name = MySQL
+ dbname = bacula
+ user = bacula
+ password = ""
+ DB Address = remote.acme.com
+ DB Port = 1234
+}
+\end{verbatim}
+\normalsize
+
+\section{The Messages Resource}
+\label{MessagesResource2}
+\index[general]{Resource!Messages}
+\index[general]{Messages Resource}
+
+For the details of the Messages Resource, please see the
+\ilink{Messages Resource Chapter}{MessagesChapter} of this
+manual.
+
+\section{The Console Resource}
+\label{ConsoleResource1}
+\index[general]{Console Resource}
+\index[general]{Resource!Console}
+
+As of Bacula version 1.33 and higher, there are three different kinds of
+consoles, which the administrator or user can use to interact with the
+Director. These three kinds of consoles comprise three different security
+levels.
+
+\begin{itemize}
+\item The first console type is an {\bf anonymous} or {\bf default} console,
+ which has full privileges. There is no console resource necessary for
+ this type since the password is specified in the Director's resource and
+ consequently such consoles do not have a name as defined on a {\bf Name
+ =} directive. This is the kind of console that was initially
+ implemented in versions prior to 1.33 and remains valid. Typically you
+ would use it only for administrators.
+
+\item The second type of console, and new to version 1.33 and higher is a
+ "named" console defined within a Console resource in both the Director's
+ configuration file and in the Console's configuration file. Both the
+ names and the passwords in these two entries must match much as is the
+ case for Client programs.
+
+ This second type of console begins with absolutely no privileges except
+ those explicitly specified in the Director's Console resource. Thus you
+ can have multiple Consoles with different names and passwords, sort of
+ like multiple users, each with different privileges. As a default,
+ these consoles can do absolutely nothing -- no commands whatsoever. You
+ give them privileges or rather access to commands and resources by
+ specifying access control lists in the Director's Console resource. The
+ ACLs are specified by a directive followed by a list of access names.
+ Examples of this are shown below.
+
+\item The third type of console is similar to the above mentioned one in that
+ it requires a Console resource definition in both the Director and the
+ Console. In addition, if the console name, provided on the {\bf Name =}
+ directive, is the same as a Client name, that console is permitted to
+ use the {\bf SetIP} command to change the Address directive in the
+ Director's client resource to the IP address of the Console. This
+ permits portables or other machines using DHCP (non-fixed IP addresses)
+ to "notify" the Director of their current IP address.
+\end{itemize}
+
+The Console resource is optional and need not be specified. The following
+directives are permitted within the Director's configuration resource:
+
+\begin{description}
+
+\item [Name = \lt{}name\gt{}]
+ \index[dir]{Name}
+ \index[dir]{Directive!Name}
+ The name of the console. This name must match the name specified in the
+Console's configuration resource (much as is the case with Client
+definitions).
+
+\item [Password = \lt{}password\gt{}]
+ \index[dir]{Password}
+ \index[dir]{Directive!Password}
+ Specifies the password that must be supplied for a named Bacula Console
+ to be authorized. The same password must appear in the {\bf Console}
+ resource of the Console configuration file. For added security, the
+ password is never actually passed across the network but rather a
+ challenge response hash code created with the password. This directive
+ is required. If you have either {\bf /dev/random} {\bf bc} on your
+ machine, Bacula will generate a random password during the configuration
+ process, otherwise it will be left blank.
+
+ The password is plain text. It is not generated through any special
+ process. However, it is preferable for security reasons to choose
+ random text.
+
+\item [JobACL = \lt{}name-list\gt{}]
+ \index[dir]{JobACL}
+ \index[dir]{Directive!JobACL}
+ This directive is used to specify a list of Job resource names that can
+ be accessed by the console. Without this directive, the console cannot
+ access any of the Director's Job resources. Multiple Job resource names
+ may be specified by separating them with commas, and/or by specifying
+ multiple JobACL directives. For example, the directive may be specified
+ as:
+
+\footnotesize
+\begin{verbatim}
+ JobACL = kernsave, "Backup client 1", "Backup client 2"
+ JobACL = "RestoreFiles"
+
+\end{verbatim}
+\normalsize
+
+With the above specification, the console can access the Director's resources
+for the four jobs named on the JobACL directives, but for no others.
+
+\item [ClientACL = \lt{}name-list\gt{}]
+ \index[dir]{ClientACL}
+ \index[dir]{Directive!ClientACL}
+ This directive is used to specify a list of Client resource names that can
+be
+accessed by the console.
+
+\item [StorageACL = \lt{}name-list\gt{}]
+ \index[dir]{StorageACL}
+ \index[dir]{Directive!StorageACL}
+ This directive is used to specify a list of Storage resource names that can
+be accessed by the console.
+
+\item [ScheduleACL = \lt{}name-list\gt{}]
+ \index[dir]{ScheduleACL}
+ \index[dir]{Directive!ScheduleACL}
+ This directive is used to specify a list of Schedule resource names that can
+ be accessed by the console.
+
+\item [PoolACL = \lt{}name-list\gt{}]
+ \index[dir]{PoolACL}
+ \index[dir]{Directive!PoolACL}
+ This directive is used to specify a list of Pool resource names that can be
+ accessed by the console.
+
+\item [FileSetACL = \lt{}name-list\gt{}]
+ \index[dir]{FileSetACL}
+ \index[dir]{Directive!FileSetACL}
+ This directive is used to specify a list of FileSet resource names that
+ can be accessed by the console.
+
+\item [CatalogACL = \lt{}name-list\gt{}]
+ \index[dir]{CatalogACL}
+ \index[dir]{Directive!CatalogACL}
+ This directive is used to specify a list of Catalog resource names that
+ can be accessed by the console.
+
+\item [CommandACL = \lt{}name-list\gt{}]
+ \index[dir]{CommandACL}
+ \index[dir]{Directive!CommandACL}
+ This directive is used to specify a list of of console commands that can
+ be executed by the console.
+
+\item [WhereACL = \lt{}string\gt{}]
+ \index[dir]{WhereACL}
+ \index[dir]{Directive!WhereACL}
+ This directive permits you to specify where a restricted console
+ can restore files. If this directive is not specified, only the
+ default restore location is permitted (normally {\bf
+ /tmp/bacula-restores}. If {\bf *all*} is specified any path the
+ user enters will be accepted (not very secure), any other
+ value specified (there may be multiple WhereACL directives) will
+ restrict the user to use that path. For example, on a Unix system,
+ if you specify "/", the file will be restored to the original
+ location. This directive is untested.
+
+\end{description}
+
+Aside from Director resource names and console command names, the special
+keyword {\bf *all*} can be specified in any of the above access control lists.
+When this keyword is present, any resource or command name (which ever is
+appropriate) will be accepted. For an example configuration file, please see
+the
+\ilink{Console Configuration}{ConsoleConfChapter} chapter of this
+manual.
+
+\section{The Counter Resource}
+\label{CounterResource}
+\index[general]{Resource!Counter}
+\index[general]{Counter Resource}
+
+The Counter Resource defines a counter variable that can be accessed by
+variable expansion used for creating Volume labels with the {\bf LabelFormat}
+directive. See the
+\ilink{LabelFormat}{Label} directive in this chapter for more
+details.
+
+\begin{description}
+
+\item [Counter]
+ \index[dir]{Counter}
+ \index[dir]{Directive!Counter}
+ Start of the Counter resource. Counter directives are optional.
+
+\item [Name = \lt{}name\gt{}]
+ \index[dir]{Name}
+ \index[dir]{Directive!Name}
+ The name of the Counter. This is the name you will use in the variable
+expansion to reference the counter value.
+
+\item [Minimum = \lt{}integer\gt{}]
+ \index[dir]{Minimum}
+ \index[dir]{Directive!Minimum}
+ This specifies the minimum value that the counter can have. It also becomes
+the default. If not supplied, zero is assumed.
+
+\item [Maximum = \lt{}integer\gt{}]
+ \index[dir]{Maximum}
+ \index[dir]{Directive!Maximum}
+ \index[dir]{Directive!Maximum}
+ This is the maximum value value that the counter can have. If not specified
+or set to zero, the counter can have a maximum value of 2,147,483,648 (2 to
+the 31 power). When the counter is incremented past this value, it is reset
+to the Minimum.
+
+\item [*WrapCounter = \lt{}counter-name\gt{}]
+ \index[dir]{*WrapCounter}
+ \index[dir]{Directive!*WrapCounter}
+ If this value is specified, when the counter is incremented past the
+maximum
+and thus reset to the minimum, the counter specified on the {\bf WrapCounter}
+is incremented. (This is not currently implemented).
+
+\item [Catalog = \lt{}catalog-name\gt{}]
+ \index[dir]{Catalog}
+ \index[dir]{Directive!Catalog}
+ If this directive is specified, the counter and its values will be saved in
+the specified catalog. If this directive is not present, the counter will be
+redefined each time that Bacula is started.
+\end{description}
+
+\section{Example Director Configuration File}
+\label{SampleDirectorConfiguration}
+\index[general]{File!Example Director Configuration}
+\index[general]{Example Director Configuration File}
+
+An example Director configuration file might be the following:
+
+\footnotesize
+\begin{verbatim}
+#
+# Default Bacula Director Configuration file
+#
+# The only thing that MUST be changed is to add one or more
+# file or directory names in the Include directive of the
+# FileSet resource.
+#
+# For Bacula release 1.15 (5 March 2002) -- redhat
+#
+# You might also want to change the default email address
+# from root to your address. See the "mail" and "operator"
+# directives in the Messages resource.
+#
+Director { # define myself
+ Name = rufus-dir
+ QueryFile = "/home/kern/bacula/bin/query.sql"
+ WorkingDirectory = "/home/kern/bacula/bin/working"
+ PidDirectory = "/home/kern/bacula/bin/working"
+ Password = "XkSfzu/Cf/wX4L8Zh4G4/yhCbpLcz3YVdmVoQvU3EyF/"
+}
+# Define the backup Job
+Job {
+ Name = "NightlySave"
+ Type = Backup
+ Level = Incremental # default
+ Client=rufus-fd
+ FileSet="Full Set"
+ Schedule = "WeeklyCycle"
+ Storage = DLTDrive
+ Messages = Standard
+ Pool = Default
+}
+Job {
+ Name = "Restore"
+ Type = Restore
+ Client=rufus-fd
+ FileSet="Full Set"
+ Where = /tmp/bacula-restores
+ Storage = DLTDrive
+ Messages = Standard
+ Pool = Default
+}
+
+# List of files to be backed up
+FileSet {
+ Name = "Full Set"
+ Include {
+ Options { signature=SHA1}
+#
+# Put your list of files here, one per line or include an
+# external list with:
+#
+# @file-name
+#
+# Note: / backs up everything
+ File = /
+}
+ Exclude {}
+}
+# When to do the backups
+Schedule {
+ Name = "WeeklyCycle"
+ Run = level=Full sun at 2:05
+ Run = level=Incremental mon-sat at 2:05
+}
+# Client (File Services) to backup
+Client {
+ Name = rufus-fd
+ Address = rufus
+ Catalog = MyCatalog
+ Password = "MQk6lVinz4GG2hdIZk1dsKE/LxMZGo6znMHiD7t7vzF+"
+ File Retention = 60d # sixty day file retention
+ Job Retention = 1y # 1 year Job retention
+ AutoPrune = yes # Auto apply retention periods
+}
+# Definition of DLT tape storage device
+Storage {
+ Name = DLTDrive
+ Address = rufus
+ Password = "jMeWZvfikUHvt3kzKVVPpQ0ccmV6emPnF2cPYFdhLApQ"
+ Device = "HP DLT 80" # same as Device in Storage daemon
+ Media Type = DLT8000 # same as MediaType in Storage daemon
+}
+# Definition for a DLT autochanger device
+Storage {
+ Name = Autochanger
+ Address = rufus
+ Password = "jMeWZvfikUHvt3kzKVVPpQ0ccmV6emPnF2cPYFdhLApQ"
+ Device = "Autochanger" # same as Device in Storage daemon
+ Media Type = DLT-8000 # Different from DLTDrive
+ Autochanger = yes
+}
+# Definition of DDS tape storage device
+Storage {
+ Name = SDT-10000
+ Address = rufus
+ Password = "jMeWZvfikUHvt3kzKVVPpQ0ccmV6emPnF2cPYFdhLApQ"
+ Device = SDT-10000 # same as Device in Storage daemon
+ Media Type = DDS-4 # same as MediaType in Storage daemon
+}
+# Definition of 8mm tape storage device
+Storage {
+ Name = "8mmDrive"
+ Address = rufus
+ Password = "jMeWZvfikUHvt3kzKVVPpQ0ccmV6emPnF2cPYFdhLApQ"
+ Device = "Exabyte 8mm"
+ MediaType = "8mm"
+}
+# Definition of file storage device
+Storage {
+ Name = File
+ Address = rufus
+ Password = "jMeWZvfikUHvt3kzKVVPpQ0ccmV6emPnF2cPYFdhLApQ"
+ Device = FileStorage
+ Media Type = File
+}
+# Generic catalog service
+Catalog {
+ Name = MyCatalog
+ dbname = bacula; user = bacula; password = ""
+}
+# Reasonable message delivery -- send most everything to
+# the email address and to the console
+Messages {
+ Name = Standard
+ mail = root@localhost = all, !skipped, !terminate
+ operator = root@localhost = mount
+ console = all, !skipped, !saved
+}
+
+# Default pool definition
+Pool {
+ Name = Default
+ Pool Type = Backup
+ AutoPrune = yes
+ Recycle = yes
+}
+#
+# Restricted console used by tray-monitor to get the status of the director
+#
+Console {
+ Name = Monitor
+ Password = "GN0uRo7PTUmlMbqrJ2Gr1p0fk0HQJTxwnFyE4WSST3MWZseR"
+ CommandACL = status, .status
+}
+\end{verbatim}
+\normalsize
--- /dev/null
+#
+# Avoid that @VERSION@ and @DATE@ are changed by configure
+# This file is sourced by update_version
+#
+echo "s%@VERSION@%${VERSION}%g" >${out}
+echo "s%@DATE@%${DATE}%g" >>${out}
--- /dev/null
+%%
+%%
+
+\chapter{Client/File daemon Configuration}
+\label{FiledConfChapter}
+\index[general]{Configuration!Client/File daemon }
+\index[general]{Client/File daemon Configuration }
+
+The Client (or File Daemon) Configuration is one of the simpler ones to
+specify. Generally, other than changing the Client name so that error messages
+are easily identified, you will not need to modify the default Client
+configuration file.
+
+For a general discussion of configuration file and resources including the
+data types recognized by {\bf Bacula}, please see the
+\ilink{Configuration}{ConfigureChapter} chapter of this manual. The
+following Client Resource definitions must be defined:
+
+\begin{itemize}
+\item
+ \ilink{Client}{ClientResource} -- to define what Clients are to
+ be backed up.
+\item
+ \ilink{Director}{DirectorResource} -- to define the Director's
+ name and its access password.
+\item
+ \ilink{Messages}{MessagesChapter} -- to define where error and
+ information messages are to be sent.
+\end{itemize}
+
+\section{The Client Resource}
+\label{ClientResource}
+\index[general]{Resource!Client }
+\index[general]{Client Resource }
+
+The Client Resource (or FileDaemon) resource defines the name of the Client
+(as used by the Director) as well as the port on which the Client listens for
+Director connections.
+
+\begin{description}
+
+\item [Client (or FileDaemon)]
+ \index[fd]{Client (or FileDaemon)}
+ \index[fd]{Directive!Client (or FileDaemon)}
+ Start of the Client records. There must be one and only one Client resource
+ in the configuration file, since it defines the properties of the current
+ client program.
+
+\item [Name = \lt{}name\gt{}]
+ \index[fd]{Name}
+ \index[fd]{Directive!Name}
+ The client name that must be used by the Director when connecting. Generally,
+ it is a good idea to use a name related to the machine so that error messages
+ can be easily identified if you have multiple Clients. This directive is
+ required.
+
+\item [Working Directory = \lt{}Directory\gt{}]
+ \index[fd]{Working Directory}
+ \index[fd]{Directive!Working Directory}
+ This directive is mandatory and specifies a directory in which the File
+ daemon may put its status files. This directory should be used only by {\bf
+ Bacula}, but may be shared by other Bacula daemons provided the daemon
+ names on the {\bf Name} definition are unique for each daemon. This directive
+ is required.
+
+ On Win32 systems, in some circumstances you may need to specify a drive
+ letter in the specified working directory path. Also, please be sure
+ that this directory is writable by the SYSTEM user otherwise restores
+ may fail (the bootstrap file that is transferred to the File daemon from
+ the Director is temporarily put in this directory before being passed
+ to the Storage daemon).
+
+\item [Pid Directory = \lt{}Directory\gt{}]
+ \index[fd]{Pid Directory}
+ \index[fd]{Directive!Pid Directory}
+ This directive is mandatory and specifies a directory in which the Director
+ may put its process Id file files. The process Id file is used to shutdown
+ Bacula and to prevent multiple copies of Bacula from running simultaneously.
+ This record is required. Standard shell expansion of the {\bf Directory} is
+ done when the configuration file is read so that values such as {\bf \$HOME}
+ will be properly expanded.
+
+ Typically on Linux systems, you will set this to: {\bf /var/run}. If you are
+ not installing Bacula in the system directories, you can use the {\bf Working
+ Directory} as defined above.
+
+\item [Heartbeat Interval = \lt{}time-interval\gt{}]
+ \index[fd]{Heartbeat Interval}
+ \index[fd]{Directive!Heartbeat Interval}
+ \index[general]{Heartbeat Interval}
+ \index[general]{Broken pipe}
+ \index[general]{slow}
+ \index[general]{Backups!slow}
+ This record defines an interval of time. For each heartbeat that the
+ File daemon receives from the Storage daemon, it will forward it to the
+ Director. In addition, if no heartbeat has been received from the
+ Storage daemon and thus forwarded the File daemon will send a heartbeat
+ signal to the Director and to the Storage daemon to keep the channels
+ active. The default interval is zero which disables the heartbeat.
+ This feature is particularly useful if you have a router such as 3Com
+ that does not follow Internet standards and times out a valid
+ connection after a short duration despite the fact that keepalive is
+ set. This usually results in a broken pipe error message.
+
+ If you continue getting broken pipe error messages despite using the
+ Heartbeat Interval, and you are using Windows, you should consider
+ upgrading your ethernet driver. This is a known problem with NVidia
+ NForce 3 drivers (4.4.2 17/05/2004), or try the following workaround
+ suggested by Thomas Simmons for Win32 machines:
+
+ Browse to:
+ Start \gt{} Control Panel \gt{} Network Connections
+
+ Right click the connection for the nvidia adapter and select properties.
+ Under the General tab, click "Configure...". Under the Advanced tab set
+ "Checksum Offload" to disabled and click OK to save the change.
+
+ Lack of communications, or communications that get interrupted can
+ also be caused by Linux firewalls where you have a rule that throttles
+ connections or traffic.
+
+
+\item [Maximum Concurrent Jobs = \lt{}number\gt{}]
+ \index[fd]{Maximum Concurrent Jobs}
+ \index[fd]{Directive!Maximum Concurrent Jobs}
+ where \lt{}number\gt{} is the maximum number of Jobs that should run
+ concurrently. The default is set to 2, but you may set it to a larger
+ number. Each contact from the Director (e.g. status request, job start
+ request) is considered as a Job, so if you want to be able to do a {\bf
+ status} request in the console at the same time as a Job is running, you
+ will need to set this value greater than 1.
+
+\item [FDAddresses = \lt{}IP-address-specification\gt{}]
+ \index[fd]{FDAddresses}
+ \index[fd]{Directive!FDAddresses}
+ Specify the ports and addresses on which the File daemon listens for
+ Director connections. Probably the simplest way to explain is to show
+ an example:
+
+\footnotesize
+\begin{verbatim}
+ FDAddresses = {
+ ip = { addr = 1.2.3.4; port = 1205; }
+ ipv4 = {
+ addr = 1.2.3.4; port = http; }
+ ipv6 = {
+ addr = 1.2.3.4;
+ port = 1205;
+ }
+ ip = {
+ addr = 1.2.3.4
+ port = 1205
+ }
+ ip = { addr = 1.2.3.4 }
+ ip = {
+ addr = 201:220:222::2
+ }
+ ip = {
+ addr = bluedot.thun.net
+ }
+ }
+\end{verbatim}
+\normalsize
+
+where ip, ip4, ip6, addr, and port are all keywords. Note, that the address
+can be specified as either a dotted quadruple, or IPv6 colon notation, or as
+a symbolic name (only in the ip specification). Also, port can be specified
+as a number or as the mnemonic value from the /etc/services file. If a port
+is not specified, the default will be used. If an ip section is specified,
+the resolution can be made either by IPv4 or IPv6. If ip4 is specified, then
+only IPv4 resolutions will be permitted, and likewise with ip6.
+
+\item [FDPort = \lt{}port-number\gt{}]
+ \index[fd]{FDPort}
+ \index[fd]{Directive!FDPort}
+ This specifies the port number on which the Client listens for Director
+ connections. It must agree with the FDPort specified in the Client resource
+ of the Director's configuration file. The default is 9102.
+
+\item [FDAddress = \lt{}IP-Address\gt{}]
+ \index[fd]{FDAddress}
+ \index[fd]{Directive!FDAddress}
+ This record is optional, and if it is specified, it will cause the File
+ daemon server (for Director connections) to bind to the specified {\bf
+ IP-Address}, which is either a domain name or an IP address specified as a
+ dotted quadruple. If this record is not specified, the File daemon will bind
+ to any available address (the default).
+
+\item [SDConnectTimeout = \lt{}time-interval\gt{}]
+ \index[fd]{SDConnectTimeout}
+ \index[fd]{Directive!SDConnectTimeout}
+ This record defines an interval of time that the File daemon will try to
+ connect to the Storage daemon. The default is 30 minutes. If no connection
+ is made in the specified time interval, the File daemon cancels the Job.
+
+\item [Maximum Network Buffer Size = \lt{}bytes\gt{}]
+ \index[fd]{Maximum Network Buffer Size}
+ \index[fd]{Directive!Maximum Network Buffer Size}
+ where \lt{}bytes\gt{} specifies the initial network buffer size to use with
+ the File daemon. This size will be adjusted down if it is too large until it
+ is accepted by the OS. Please use care in setting this value since if it is
+ too large, it will be trimmed by 512 bytes until the OS is happy, which may
+ require a large number of system calls. The default value is 65,536 bytes.
+
+ Note, on certain Windows machines, there are reports that the
+ transfer rates are very slow and this seems to be related to
+ the default 65,536 size. On systems where the transfer rates
+ seem abnormally slow compared to other systems, you might try
+ setting the Maximum Network Buffer Size to 32,768 in both the
+ File daemon and in the Storage daemon.
+
+\item [Heartbeat Interval = \lt{}time-interval\gt{}]
+ \index[console]{Heartbeat Interval}
+ \index[console]{Directive!Heartbeat}
+ This directive is optional and if specified will cause the File daemon to
+ set a keepalive interval (heartbeat) in seconds on each of the sockets
+ to communicate with the Storage daemon. It is implemented only on systems
+ (Linux, ...) that provide the {\bf setsockopt} TCP\_KEEPIDLE function.
+ The default value is zero, which means no change is made to the socket.
+
+
+\item [PKI Encryption]
+ See the \ilink{Data Encryption}{DataEncryption} chapter of this manual.
+
+\item [PKI Signatures]
+ See the \ilink{Data Encryption}{DataEncryption} chapter of this manual.
+
+\item [PKI Keypair]
+ See the \ilink{Data Encryption}{DataEncryption} chapter of this manual.
+
+\item [PKI Master Key]
+ See the \ilink{Data Encryption}{DataEncryption} chapter of this manual.
+
+\end{description}
+
+The following is an example of a valid Client resource definition:
+
+\footnotesize
+\begin{verbatim}
+Client { # this is me
+ Name = rufus-fd
+ WorkingDirectory = $HOME/bacula/bin/working
+ Pid Directory = $HOME/bacula/bin/working
+}
+\end{verbatim}
+\normalsize
+
+\section{The Director Resource}
+\label{DirectorResource}
+\index[general]{Director Resource }
+\index[general]{Resource!Director }
+
+The Director resource defines the name and password of the Directors that are
+permitted to contact this Client.
+
+\begin{description}
+
+\item [Director]
+ \index[fd]{Director}
+ \index[fd]{Directive!Director}
+ Start of the Director records. There may be any number of Director resources
+ in the Client configuration file. Each one specifies a Director that is
+ allowed to connect to this Client.
+
+\item [Name = \lt{}name\gt{}]
+ \index[fd]{Name}
+ \index[fd]{Directive!Name}
+ The name of the Director that may contact this Client. This name must be the
+ same as the name specified on the Director resource in the Director's
+ configuration file. Note, the case (upper/lower) of the characters in
+ the name are significant (i.e. S is not the same as s). This directive
+ is required.
+
+\item [Password = \lt{}password\gt{}]
+ \index[fd]{Password}
+ \index[fd]{Directive!Password}
+ Specifies the password that must be supplied for a Director to be authorized.
+This password must be the same as the password specified in the Client
+resource in the Director's configuration file. This directive is required.
+
+\item [Monitor = \lt{}yes|no\gt{}]
+ \index[fd]{Monitor}
+ \index[fd]{Directive!Monitor}
+ If Monitor is set to {\bf no} (default), this director will have full access
+ to this Client. If Monitor is set to {\bf yes}, this director will only be
+ able to fetch the current status of this Client.
+
+ Please note that if this director is being used by a Monitor, we highly
+ recommend to set this directive to {\bf yes} to avoid serious security
+ problems.
+\end{description}
+
+Thus multiple Directors may be authorized to use this Client's services. Each
+Director will have a different name, and normally a different password as
+well.
+
+The following is an example of a valid Director resource definition:
+
+\footnotesize
+\begin{verbatim}
+#
+# List Directors who are permitted to contact the File daemon
+#
+Director {
+ Name = HeadMan
+ Password = very_good # password HeadMan must supply
+}
+Director {
+ Name = Worker
+ Password = not_as_good
+ Monitor = Yes
+}
+\end{verbatim}
+\normalsize
+
+\section{The Message Resource}
+\label{MessagesResource3}
+\index[general]{Message Resource}
+\index[general]{Resource!Message }
+
+Please see the
+\ilink{Messages Resource}{MessagesChapter} Chapter of this
+manual for the details of the Messages Resource.
+
+There must be at least one Message resource in the Client configuration file.
+
+\section{Example Client Configuration File}
+\label{SampleClientConfiguration}
+\index[general]{Example Client Configuration File }
+\index[general]{File!Example Client Configuration }
+
+An example File Daemon configuration file might be the following:
+
+\footnotesize
+\begin{verbatim}
+#
+# Default Bacula File Daemon Configuration file
+#
+# For Bacula release 1.35.2 (16 August 2004) -- gentoo 1.4.16
+#
+# There is not much to change here except perhaps to
+# set the Director's name and File daemon's name
+# to something more appropriate for your site.
+#
+#
+# List Directors who are permitted to contact this File daemon
+#
+Director {
+ Name = rufus-dir
+ Password = "/LqPRkX++saVyQE7w7mmiFg/qxYc1kufww6FEyY/47jU"
+}
+#
+# Restricted Director, used by tray-monitor to get the
+# status of the file daemon
+#
+Director {
+ Name = rufus-mon
+ Password = "FYpq4yyI1y562EMS35bA0J0QC0M2L3t5cZObxT3XQxgxppTn"
+ Monitor = yes
+}
+#
+# "Global" File daemon configuration specifications
+#
+FileDaemon { # this is me
+ Name = rufus-fd
+ WorkingDirectory = $HOME/bacula/bin/working
+ Pid Directory = $HOME/bacula/bin/working
+}
+# Send all messages except skipped files back to Director
+Messages {
+ Name = Standard
+ director = rufus-dir = all, !skipped
+}
+\end{verbatim}
+\normalsize
--- /dev/null
+-%
+%%
+
+\section{The FileSet Resource}
+\label{FileSetResource}
+\index[general]{Resource!FileSet}
+\index[general]{FileSet Resource}
+
+The FileSet resource defines what files are to be included or excluded in a
+backup job. A {\bf FileSet} resource is required for each backup Job. It
+consists of a list of files or directories to be included, a list of files
+or directories to be excluded and the various backup options such as
+compression, encryption, and signatures that are to be applied to each
+file.
+
+Any change to the list of the included files will cause Bacula to
+automatically create a new FileSet (defined by the name and an MD5 checksum
+of the Include/Exclude contents). Each time a new FileSet is created,
+Bacula will ensure that the next backup is always a Full save.
+
+Bacula is designed to handle most character sets of the world,
+US ASCII, German, French, Chinese, ... However, it does this by
+encoding everything in UTF-8, and it expects all configuration files
+(including those read on Win32 machines) to be in UTF-8 format.
+UTF-8 is typically the default on Linux machines, but not on all
+Unix machines, nor on Windows, so you must take some care to ensure
+that your locale is set properly before starting Bacula.
+On most modern Win32 machines, you can edit the conf files with {\bf
+notebook} and choose output encoding UTF-8.
+
+To ensure that Bacula configuration files can be correctly read including
+foreign characters the {bf LANG} environment variable
+must end in {\bf .UTF-8}. An full example is {\bf en\_US.UTF-8}. The
+exact syntax may vary a bit from OS to OS, and exactly how you define
+it will also vary.
+
+Bacula assumes that all filenames are in UTF-8 format on Linux and
+Unix machines. On Win32 they are in Unicode (UTF-16), and will
+be automatically converted to UTF-8 format.
+
+
+\begin{description}
+
+\item [FileSet]
+\index[dir]{FileSet}
+\index[dir]{Directive!FileSet}
+Start of the FileSet resource. One {\bf FileSet} resource must be
+defined for each Backup job.
+
+\item [Name = \lt{}name\gt{}]
+\index[dir]{Name}
+\index[dir]{Directive!Name}
+ The name of the FileSet resource. This directive is required.
+
+\item [Ignore FileSet Changes = \lt{}yes|no\gt{}]
+\index[dir]{Ignore FileSet Changes}
+\index[dir]{Directive!Ignore FileSet Changes}
+ Normally, if you modify the FileSet Include or Exclude lists,
+ the next backup will be forced to a Full so that Bacula can
+ guarantee that any additions or deletions are properly saved.
+
+ We strongly recommend against setting this directive to yes,
+ since doing so may cause you to have an incomplete set of backups.
+
+ If this directive is set to {\bf yes}, any changes you make to the
+ FileSet Include or Exclude lists, will not force a Full during
+ subsequent backups.
+
+ The default is {\bf no}, in which case, if you change the Include or
+ Exclude, Bacula will force a Full backup to ensure that everything is
+ properly backed up.
+
+\item [Enable VSS = \lt{}yes|no\gt{}]
+\index[dir]{Enable VSS}
+\index[dir]{Directive!Enable VSS}
+ If this directive is set to {\bf yes} the File daemon will be notified
+ that the user wants to use a Volume Shadow Copy Service (VSS) backup
+ for this job. The default is {\bf yes}. This directive is effective
+ only for VSS enabled Win32 File daemons. It permits a consistent copy
+ of open files to be made for cooperating writer applications, and for
+ applications that are not VSS away, Bacula can at least copy open files.
+ For more information, please see the
+ \ilink{Windows}{VSS} chapter of this manual.
+
+\item [Include \{ Options \{\lt{}file-options\gt{}\} ...;
+ \lt{}file-list\gt{} \} ]
+\index[dir]{Include \{ [ Options \{\lt{}file-options\gt{}\} ...]
+ \lt{}file-list\gt{} \} }
+\index[dir]{Directive!Include}
+
+\item [Options \{ \lt{}file-options\gt{} \} ]
+\index[dir]{Options \{ \lt{}file-options\gt{} \} }
+
+\item [Exclude \{ \lt{}file-list\gt{} \}]
+\index[dir]{Exclude \{ \lt{}file-list\gt{} \} }
+\index[dir]{Directive!Exclude}
+
+\end{description}
+
+The Include resource must contain a list of directories and/or files to be
+processed in the backup job. Normally, all files found in all
+subdirectories of any directory in the Include File list will be backed up.
+Note, see below for the definition of \lt{}file-list\gt{}.
+The Include resource may also contain one or more Options resources that
+specify options such as compression to be applied to all or any subset of
+the files found when processing the file-list for backup. Please see
+below for more details concerning Options resources.
+
+There can be any number of {\bf Include} resources within the FileSet, each
+having its own list of directories or files to be backed up and the backup
+options defined by one or more Options resources. The {\bf file-list}
+consists of one file or directory name per line. Directory names should be
+specified without a trailing slash with Unix path notation.
+
+Windows users, please take note to specify directories (even c:/...) in
+Unix path notation. If you use Windows conventions, you will most likely
+not be able to restore your files due to the fact that the Windows
+path separator was defined as an escape character long before Windows
+existed, and Bacula adheres to that convention (i.e. \\ means the next character
+appears as itself).
+
+You should always specify a full path for every directory and file that you
+list in the FileSet. In addition, on Windows machines, you should {\bf
+always} prefix the directory or filename with the drive specification in
+lower case (e.g. {\bf c:/xxx}) using Unix directory name separators
+(forward slash).
+
+Bacula's default for processing directories is to recursively descend in
+the directory saving all files and subdirectories. Bacula will not by
+default cross filesystems (or mount points in Unix parlance). This means
+that if you specify the root partition (e.g. {\bf /}), Bacula will save
+only the root partition and not any of the other mounted filesystems.
+Similarly on Windows systems, you must explicitly specify each of the
+drives you want saved (e.g.
+{\bf c:/} and {\bf d:/} ...). In addition, at least for Windows systems, you
+will most likely want to enclose each specification within double quotes
+particularly if the directory (or file) name contains spaces. The {\bf df}
+command on Unix systems will show you which mount points you must specify to
+save everything. See below for an example.
+
+Take special care not to include a directory twice or Bacula will backup
+the same files two times wasting a lot of space on your archive device.
+Including a directory twice is very easy to do. For example:
+
+\footnotesize
+\begin{verbatim}
+ Include {
+ File = /
+ File = /usr
+ Options { compression=GZIP }
+ }
+\end{verbatim}
+\normalsize
+
+on a Unix system where /usr is a subdirectory (rather than a mounted
+filesystem) will cause /usr to be backed up twice. In this case, on Bacula
+versions prior to 1.32f-5-09Mar04 due to a bug, you will not be able to
+restore hard linked files that were backed up twice.
+
+If you have used Bacula prior to version 1.36.3, you will note three things in
+the new FileSet syntax:
+
+\begin{enumerate}
+\item There is no equal sign (=) after the Include and before the opening
+ brace (\{). The same is true for the Exclude.
+\item Each directory (or filename) to be included or excluded is preceded by a {\bf File
+ =}. Previously they were simply listed on separate lines.
+\item The options that previously appeared on the Include line now must be
+ specified within their own Options resource.
+\item The Exclude resource does not accept Options.
+\item When using wild-cards or regular expressions, directory names are
+ always terminated with a slash (/) and filenames have no trailing slash.
+\end{enumerate}
+
+The Options resource is optional, but when specified, it will contain a
+list of {\bf keyword=value} options to be applied to the file-list.
+See below for the definition of file-list.
+Multiple Options resources may be specified one after another. As the
+files are found in the specified directories, the Options will applied to
+the filenames to determine if and how the file should be backed up. The
+wildcard and regular expression pattern matching parts of the
+Options resources are checked in the order they are specified in the
+FileSet until the first one that matches. Once one matches, the
+compression and other flags within the Options specification will
+apply to the pattern matched.
+
+A key point is that in the absence of an Option or no other Option is
+matched, every file is accepted for backing up. This means that if
+you want to exclude something, you must explicitly specify an Option
+with an {\bf exclude = yes} and some pattern matching.
+
+Once Bacula determines that the Options resource matches the file under
+consideration, that file will be saved without looking at any other Options
+resources that may be present. This means that any wild cards must appear
+before an Options resource without wild cards.
+
+If for some reason, Bacula checks all the Options resources to a file under
+consideration for backup, but there are no matches (generally because of wild
+cards that don't match), Bacula as a default will then backup the file. This
+is quite logical if you consider the case of no Options clause is specified,
+where you want everything to be backed up, and it is important to keep in mind
+when excluding as mentioned above.
+
+However, one additional point is that in the case that no match was found,
+Bacula will use the options found in the last Options resource. As a
+consequence, if you want a particular set of "default" options, you should put
+them in an Options resource after any other Options.
+
+It is a good idea to put all your wild-card and regex expressions inside
+double quotes to prevent conf file scanning problems.
+
+This is perhaps a bit overwhelming, so there are a number of examples included
+below to illustrate how this works.
+
+The directives within an Options resource may be one of the following:
+
+\begin{description}
+
+\item [compression=GZIP]
+\index[dir]{compression}
+\index[dir]{Directive!compression}
+ All files saved will be software compressed using the GNU ZIP
+ compression format. The compression is done on a file by file basis by
+ the File daemon. If there is a problem reading the tape in a single
+ record of a file, it will at most affect that file and none of the other
+ files on the tape. Normally this option is {\bf not} needed if you have
+ a modern tape drive as the drive will do its own compression. In fact,
+ if you specify software compression at the same time you have hardware
+ compression turned on, your files may actually take more space on the
+ volume.
+
+ Software compression is very important if you are writing your Volumes
+ to a file, and it can also be helpful if you have a fast computer but a
+ slow network, otherwise it is generally better to rely your tape drive's
+ hardware compression. As noted above, it is not generally a good idea
+ to do both software and hardware compression.
+
+ Specifying {\bf GZIP} uses the default compression level 6 (i.e. {\bf
+ GZIP} is identical to {\bf GZIP6}). If you want a different compression
+ level (1 through 9), you can specify it by appending the level number
+ with no intervening spaces to {\bf GZIP}. Thus {\bf compression=GZIP1}
+ would give minimum compression but the fastest algorithm, and {\bf
+ compression=GZIP9} would give the highest level of compression, but
+ requires more computation. According to the GZIP documentation,
+ compression levels greater than six generally give very little extra
+ compression and are rather CPU intensive.
+
+\item [signature=SHA1]
+\index[dir]{signature}
+\index[dir]{SHA1}
+\index[dir]{Directive!signature}
+ An SHA1 signature will be computed for all The SHA1 algorithm is
+ purported to be some what slower than the MD5 algorithm, but at the same
+ time is significantly better from a cryptographic point of view (i.e.
+ much fewer collisions, much lower probability of being hacked.) It adds
+ four more bytes than the MD5 signature. We strongly recommend that
+ either this option or MD5 be specified as a default for all files.
+ Note, only one of the two options MD5 or SHA1 can be computed for any
+ file.
+
+\item [signature=MD5]
+\index[dir]{signature}
+\index[dir]{MD5}
+\index[dir]{Directive!signature}
+ An MD5 signature will be computed for all files saved. Adding this
+ option generates about 5\% extra overhead for each file saved. In
+ addition to the additional CPU time, the MD5 signature adds 16 more
+ bytes per file to your catalog. We strongly recommend that this option
+ or the SHA1 option be specified as a default for all files.
+
+\item [verify=\lt{}options\gt{}]
+\index[dir]{verify}
+\index[dir]{Directive!verify}
+ The options letters specified are used when running a {\bf Verify
+ Level=Catalog} as well as the {\bf DiskToCatalog} level job. The options
+ letters may be any combination of the following:
+
+ \begin{description}
+
+ \item {\bf i}
+ compare the inodes
+
+ \item {\bf p}
+ compare the permission bits
+
+ \item {\bf n}
+ compare the number of links
+
+ \item {\bf u}
+ compare the user id
+
+ \item {\bf g}
+ compare the group id
+
+ \item {\bf s}
+ compare the size
+
+ \item {\bf a}
+ compare the access time
+
+ \item {\bf m}
+ compare the modification time (st\_mtime)
+
+ \item {\bf c}
+ compare the change time (st\_ctime)
+
+ \item {\bf d}
+ report file size decreases
+
+ \item {\bf 5}
+ compare the MD5 signature
+
+ \item {\bf 1}
+ compare the SHA1 signature
+ \end{description}
+
+ A useful set of general options on the {\bf Level=Catalog} or {\bf
+ Level=DiskToCatalog} verify is {\bf pins5} i.e. compare permission bits,
+ inodes, number of links, size, and MD5 changes.
+
+\item [onefs=yes|no]
+\index[dir]{onefs}
+\index[dir]{Directive!onefs}
+ If set to {\bf yes} (the default), {\bf Bacula} will remain on a single
+ file system. That is it will not backup file systems that are mounted
+ on a subdirectory. If you are using a *nix system, you may not even be
+ aware that there are several different filesystems as they are often
+ automatically mounted by the OS (e.g. /dev, /net, /sys, /proc, ...).
+ With Bacula 1.38.0 or later, it will inform you when it decides not to
+ traverse into another filesystem. This can be very useful if you forgot
+ to backup a particular partition. An example of the informational
+ message in the job report is:
+
+\footnotesize
+\begin{verbatim}
+rufus-fd: /misc is a different filesystem. Will not descend from / into /misc
+rufus-fd: /net is a different filesystem. Will not descend from / into /net
+rufus-fd: /var/lib/nfs/rpc_pipefs is a different filesystem. Will not descend from /var/lib/nfs into /var/lib/nfs/rpc_pipefs
+rufus-fd: /selinux is a different filesystem. Will not descend from / into /selinux
+rufus-fd: /sys is a different filesystem. Will not descend from / into /sys
+rufus-fd: /dev is a different filesystem. Will not descend from / into /dev
+rufus-fd: /home is a different filesystem. Will not descend from / into /home
+\end{verbatim}
+\normalsize
+
+ Note: in previous versions of Bacula, the above message was of the form:
+
+\footnotesize
+\begin{verbatim}
+Filesystem change prohibited. Will not descend into /misc
+\end{verbatim}
+\normalsize
+
+ If you wish to backup multiple filesystems, you can explicitly
+ list each filesystem you want saved. Otherwise, if you set the onefs option
+ to {\bf no}, Bacula will backup all mounted file systems (i.e. traverse mount
+ points) that are found within the {\bf FileSet}. Thus if you have NFS or
+ Samba file systems mounted on a directory listed in your FileSet, they will
+ also be backed up. Normally, it is preferable to set {\bf onefs=yes} and to
+ explicitly name each filesystem you want backed up. Explicitly naming the
+ filesystems you want backed up avoids the possibility of getting into a
+ infinite loop recursing filesystems. Another possibility is to
+ use {\bf onefs=no} and to set {\bf fstype=ext2, ...}.
+ See the example below for more details.
+
+ If you think that Bacula should be backing up a particular directory
+ and it is not, and you have {\bf onefs=no} set, before you complain,
+ please do:
+
+\footnotesize
+\begin{verbatim}
+ stat /
+ stat <filesystem>
+\end{verbatim}
+\normalsize
+
+where you replace {\bf filesystem} with the one in question. If the
+{\bf Device:} number is different for / and for your filesystem, then they
+are on different filesystems. E.g.
+\footnotesize
+\begin{verbatim}
+stat /
+ File: `/'
+ Size: 4096 Blocks: 16 IO Block: 4096 directory
+Device: 302h/770d Inode: 2 Links: 26
+Access: (0755/drwxr-xr-x) Uid: ( 0/ root) Gid: ( 0/ root)
+Access: 2005-11-10 12:28:01.000000000 +0100
+Modify: 2005-09-27 17:52:32.000000000 +0200
+Change: 2005-09-27 17:52:32.000000000 +0200
+
+stat /net
+ File: `/home'
+ Size: 4096 Blocks: 16 IO Block: 4096 directory
+Device: 308h/776d Inode: 2 Links: 7
+Access: (0755/drwxr-xr-x) Uid: ( 0/ root) Gid: ( 0/ root)
+Access: 2005-11-10 12:28:02.000000000 +0100
+Modify: 2005-11-06 12:36:48.000000000 +0100
+Change: 2005-11-06 12:36:48.000000000 +0100
+\end{verbatim}
+\normalsize
+
+ Also be aware that even if you include {\bf /home} in your list
+ of files to backup, as you most likely should, you will get the
+ informational message that "/home is a different filesystem" when
+ Bacula is processing the {\bf /} directory. This message does not
+ indicate an error. This message means that while examining the
+ {\bf File =} referred to in the second part of the message, Bacula will
+ not descend into the directory mentioned in the first part of the message.
+ However, it is possible that the separate filesystem will be backed up
+ despite the message. For example, consider the following FileSet:
+
+\footnotesize
+\begin{verbatim}
+ File = /
+ File = /var
+\end{verbatim}
+\normalsize
+
+ where {\bf /var} is a separate filesystem. In this example, you will get a
+ message saying that Bacula will not decend from {\bf /} into {\bf /var}. But
+ it is important to realise that Bacula will descend into {\bf /var} from the
+ second File directive shown above. In effect, the warning is bogus,
+ but it is supplied to alert you to possible omissions from your FileSet. In
+ this example, {\bf /var} will be backed up. If you changed the FileSet such
+ that it did not specify {\bf /var}, then {\bf /var} will not be backed up.
+
+
+
+
+\label{portable}
+\item [portable=yes|no]
+\index[dir]{portable}
+\index[dir]{Directive!portable}
+ If set to {\bf yes} (default is {\bf no}), the Bacula File daemon will
+ backup Win32 files in a portable format, but not all Win32 file
+ attributes will be saved and restored. By default, this option is set
+ to {\bf no}, which means that on Win32 systems, the data will be backed
+ up using Windows API calls and on WinNT/2K/XP, all the security and
+ ownership attributes will be properly backed up (and restored). However
+ this format is not portable to other systems -- e.g. Unix, Win95/98/Me.
+ When backing up Unix systems, this option is ignored, and unless you
+ have a specific need to have portable backups, we recommend accept the
+ default ({\bf no}) so that the maximum information concerning your files
+ is saved.
+
+\item [recurse=yes|no]
+\index[dir]{recurse}
+\index[dir]{Directive!recurse}
+ If set to {\bf yes} (the default), Bacula will recurse (or descend) into
+ all subdirectories found unless the directory is explicitly excluded
+ using an {\bf exclude} definition. If you set {\bf recurse=no}, Bacula
+ will save the subdirectory entries, but not descend into the
+ subdirectories, and thus will not save the files or directories
+ contained in the subdirectories. Normally, you will want the default
+ ({\bf yes}).
+
+\item [sparse=yes|no]
+\index[dir]{sparse}
+\index[dir]{Directive!sparse}
+ Enable special code that checks for sparse files such as created by
+ ndbm. The default is {\bf no}, so no checks are made for sparse files.
+ You may specify {\bf sparse=yes} even on files that are not sparse file.
+ No harm will be done, but there will be a small additional overhead to
+ check for buffers of all zero, and a small additional amount of space on
+ the output archive will be used to save the seek address of each
+ non-zero record read.
+
+ {\bf Restrictions:} Bacula reads files in 32K buffers. If the whole
+ buffer is zero, it will be treated as a sparse block and not written to
+ tape. However, if any part of the buffer is non-zero, the whole buffer
+ will be written to tape, possibly including some disk sectors (generally
+ 4098 bytes) that are all zero. As a consequence, Bacula's detection of
+ sparse blocks is in 32K increments rather than the system block size.
+ If anyone considers this to be a real problem, please send in a request
+ for change with the reason.
+
+ If you are not familiar with sparse files, an example is say a file
+ where you wrote 512 bytes at address zero, then 512 bytes at address 1
+ million. The operating system will allocate only two blocks, and the
+ empty space or hole will have nothing allocated. However, when you read
+ the sparse file and read the addresses where nothing was written, the OS
+ will return all zeros as if the space were allocated, and if you backup
+ such a file, a lot of space will be used to write zeros to the volume.
+ Worse yet, when you restore the file, all the previously empty space
+ will now be allocated using much more disk space. By turning on the
+ {\bf sparse} option, Bacula will specifically look for empty space in
+ the file, and any empty space will not be written to the Volume, nor
+ will it be restored. The price to pay for this is that Bacula must
+ search each block it reads before writing it. On a slow system, this
+ may be important. If you suspect you have sparse files, you should
+ benchmark the difference or set sparse for only those files that are
+ really sparse.
+
+\label{readfifo}
+\item [readfifo=yes|no]
+\index[dir]{readfifo}
+\index[dir]{Directive!readfifo}
+ If enabled, tells the Client to read the data on a backup and write the
+ data on a restore to any FIFO (pipe) that is explicitly mentioned in the
+ FileSet. In this case, you must have a program already running that
+ writes into the FIFO for a backup or reads from the FIFO on a restore.
+ This can be accomplished with the {\bf RunBeforeJob} directive. If this
+ is not the case, Bacula will hang indefinitely on reading/writing the
+ FIFO. When this is not enabled (default), the Client simply saves the
+ directory entry for the FIFO.
+
+ Unfortunately, when Bacula runs a RunBeforeJob, it waits until that
+ script terminates, and if the script accesses the FIFO to write
+ into the it, the Bacula job will block and everything will stall.
+ However, Vladimir Stavrinov as supplied tip that allows this feature
+ to work correctly. He simply adds the following to the beginning
+ of the RunBeforeJob script:
+
+\begin{verbatim}
+ exec > /dev/null
+\end{verbatim}
+
+\item [noatime=yes|no]
+\index[dir]{noatime}
+\index[dir]{Directive!noatime}
+ If enabled, and if your Operating System supports the O\_NOATIME file
+ open flag, Bacula will open all files to be backed up with this option.
+ It makes it possible to read a file without updating the inode atime
+ (and also without the inode ctime update which happens if you try to set
+ the atime back to its previous value). It also prevents a race
+ condition when two programs are reading the same file, but only one does
+ not want to change the atime. It's most useful for backup programs and
+ file integrity checkers (and bacula can fit on both categories).
+
+ This option is particularly useful for sites where users are sensitive
+ to their MailBox file access time. It replaces both the {\bf keepatime}
+ option without the inconveniences of that option (see below).
+
+ If your Operating System does not support this option, it will be
+ silently ignored by Bacula.
+
+
+\item [mtimeonly=yes|no]
+\index[dir]{mtimeonly}
+\index[dir]{Directive!mtimeonly}
+ If enabled, tells the Client that the selection of files during
+ Incremental and Differential backups should based only on the st\_mtime
+ value in the stat() packet. The default is {\bf no} which means that
+ the selection of files to be backed up will be based on both the
+ st\_mtime and the st\_ctime values. In general, it is not recommended
+ to use this option.
+
+\item [keepatime=yes|no]
+\index[dir]{keepatime}
+\index[dir]{Directive!keepatime}
+ The default is {\bf no}. When enabled, Bacula will reset the st\_atime
+ (access time) field of files that it backs up to their value prior to
+ the backup. This option is not generally recommended as there are very
+ few programs that use st\_atime, and the backup overhead is increased
+ because of the additional system call necessary to reset the times.
+ However, for some files, such as mailboxes, when Bacula backs up the
+ file, the user will notice that someone (Bacula) has accessed the
+ file. In this, case keepatime can be useful.
+ (I'm not sure this works on Win32).
+
+ Note, if you use this feature, when Bacula resets the access time, the
+ change time (st\_ctime) will automatically be modified by the system,
+ so on the next incremental job, the file will be backed up even if
+ it has not changed. As a consequence, you will probably also want
+ to use {\bf mtimeonly = yes} as well as keepatime (thanks to
+ Rudolf Cejka for this tip).
+
+\item [checkfilechanges=yes|no]
+\index[dir]{checkfilechanges}
+\index[dir]{Directive!checkfilechanges}
+ On versions 2.0.4 or greater,
+ if enabled, the Client will checks size, age of each file after
+ their backup to see if they have changed during backup. If time
+ or size mismatch, an error will raise.
+
+\begin{verbatim}
+ zog-fd: Client1.2007-03-31_09.46.21 Error: /tmp/test mtime changed during backup.
+\end{verbatim}
+
+ In general, it is recommended to use this option.
+
+\item [hardlinks=yes|no]
+\index[dir]{hardlinks}
+\index[dir]{Directive!hardlinks}
+ When enabled (default), this directive will cause hard links to be
+ backed up. However, the File daemon keeps track of hard linked files and
+ will backup the data only once. The process of keeping track of the
+ hard links can be quite expensive if you have lots of them (tens of
+ thousands or more). This doesn't occur on normal Unix systems, but if
+ you use a program like BackupPC, it can create hundreds of thousands, or
+ even millions of hard links. Backups become very long and the File daemon
+ will consume a lot of CPU power checking hard links. In such a case,
+ set {\bf hardlinks=no} and hard links will not be backed up. Note, using
+ this option will most likely backup more data and on a restore the file
+ system will not be restored identically to the original.
+
+\item [wild=\lt{}string\gt{}]
+\index[dir]{wild}
+\index[dir]{Directive!wild}
+ Specifies a wild-card string to be applied to the filenames and
+ directory names. Note, if {\bf Exclude} is not enabled, the wild-card
+ will select which files are to be included. If {\bf Exclude=yes} is
+ specified, the wild-card will select which files are to be excluded.
+ Multiple wild-card directives may be specified, and they will be applied
+ in turn until the first one that matches. Note, if you exclude a
+ directory, no files or directories below it will be matched.
+
+ You may want to test your expressions prior to running your
+ backup by using the bwild program. Please see the
+ \ilink{Utilities}{bwild} chapter of this manual for
+ more. You can also test your full FileSet definition by using
+ the \ilink{estimate}{estimate} command in the Console
+ chapter of this manual.
+ It is recommended to enclose the string in double quotes.
+
+\item [wilddir=\lt{}string\gt{}]
+\index[dir]{wilddir}
+\index[dir]{Directive!wilddir}
+ Specifies a wild-card string to be applied to directory names only. No
+ filenames will be matched by this directive. Note, if {\bf Exclude} is
+ not enabled, the wild-card will select directories to be
+ included. If {\bf Exclude=yes} is specified, the wild-card will select
+ which directories are to be excluded. Multiple wild-card directives may be
+ specified, and they will be applied in turn until the first one that
+ matches. Note, if you exclude a directory, no files or directories
+ below it will be matched.
+
+ It is recommended to enclose the string in double quotes.
+
+ You may want to test your expressions prior to running your
+ backup by using the bwild program. Please see the
+ \ilink{Utilities}{bwild} chapter of this manual for
+ more. You can also test your full FileSet definition by using
+ the \ilink{estimate}{estimate} command in the Console
+ chapter of this manual.
+ An example of excluding with the WildDir option on Win32 machines is
+ presented below.
+
+\item [wildfile=\lt{}string\gt{}]
+\index[dir]{wildfile}
+\index[dir]{Directive!wildfile}
+ Specifies a wild-card string to be applied to non-directories. That
+ is no directory entries will be matched by this directive.
+ However, note that the match is done against the full path and filename,
+ so your wild-card string must take into account that filenames
+ are preceded by the full path.
+ If {\bf Exclude}
+ is not enabled, the wild-card will select which files are to be
+ included. If {\bf Exclude=yes} is specified, the wild-card will select
+ which files are to be excluded. Multiple wild-card directives may be
+ specified, and they will be applied in turn until the first one that
+ matches.
+
+ It is recommended to enclose the string in double quotes.
+
+ You may want to test your expressions prior to running your
+ backup by using the bwild program. Please see the
+ \ilink{Utilities}{bwild} chapter of this manual for
+ more. You can also test your full FileSet definition by using
+ the \ilink{estimate}{estimate} command in the Console
+ chapter of this manual.
+ An example of excluding with the WildFile option on Win32 machines is
+ presented below.
+
+
+\item [regex=\lt{}string\gt{}]
+\index[dir]{regex}
+\index[dir]{Directive!regex}
+ Specifies a POSIX extended regular expression to be applied to the
+ filenames and directory names, which include the full path. If {\bf
+ Exclude} is not enabled, the regex will select which files are to be
+ included. If {\bf Exclude=yes} is specified, the regex will select
+ which files are to be excluded. Multiple regex directives may be
+ specified within an Options resource, and they will be applied in turn
+ until the first one that matches. Note, if you exclude a directory, no
+ files or directories below it will be matched.
+
+ It is recommended to enclose the string in double quotes.
+
+ The regex libraries differ from one operating system to
+ another, and in addition, regular expressions are complicated,
+ so you may want to test your expressions prior to running your
+ backup by using the bregex program. Please see the
+ \ilink{Utilities}{bwild} chapter of this manual for
+ more. You can also test your full FileSet definition by using
+ the \ilink{estimate}{estimate} command in the Console
+ chapter of this manual.
+
+
+\item [regexfile=\lt{}string\gt{}]
+\index[dir]{regexfile}
+\index[dir]{Directive!regexfile}
+ Specifies a POSIX extended regular expression to be applied to
+ non-directories. No directories will be matched by this directive.
+ However, note that the match is done against the full path and
+ filename, so your regex string must take into account that filenames
+ are preceded by the full path.
+ If {\bf Exclude} is not enabled, the regex will select which files are
+ to be included. If {\bf Exclude=yes} is specified, the regex will
+ select which files are to be excluded. Multiple regex directives may be
+ specified, and they will be applied in turn until the first one that
+ matches.
+
+ It is recommended to enclose the string in double quotes.
+
+ The regex libraries differ from one operating system to
+ another, and in addition, regular expressions are complicated,
+ so you may want to test your expressions prior to running your
+ backup by using the bregex program. Please see the
+ \ilink{Utilities}{bregex} chapter of this manual for
+ more.
+
+
+\item [regexdir=\lt{}string\gt{}]
+\index[dir]{regexdir}
+\index[dir]{Directive!regexdir}
+ Specifies a POSIX extended regular expression to be applied to directory
+ names only. No filenames will be matched by this directive. Note, if
+ {\bf Exclude} is not enabled, the regex will select directories
+ files are to be included. If {\bf Exclude=yes} is specified, the
+ regex will select which files are to be excluded. Multiple
+ regex directives may be specified, and they will be applied in turn
+ until the first one that matches. Note, if you exclude a directory, no
+ files or directories below it will be matched.
+
+ It is recommended to enclose the string in double quotes.
+
+ The regex libraries differ from one operating system to
+ another, and in addition, regular expressions are complicated,
+ so you may want to test your expressions prior to running your
+ backup by using the bregex program. Please see the
+ \ilink{Utilities}{bregex} chapter of this manual for
+ more.
+
+
+\item [exclude=yes|no]
+\index[dir]{exclude}
+\index[dir]{Directive!exclude}
+ The default is {\bf no}. When enabled, any files matched within the
+ Options will be excluded from the backup.
+
+\label{ACLSupport}
+\item [aclsupport=yes|no]
+\index[dir]{aclsupport}
+\index[dir]{Directive!aclsupport}
+ The default is {\bf no}. If this option is set to yes, and you have the
+ POSIX {\bf libacl} installed on your system, Bacula will backup the file
+ and directory UNIX Access Control Lists (ACL) as defined in IEEE Std
+ 1003.1e draft 17 and "POSIX.1e" (abandoned). This feature is
+ available on UNIX only and depends on the ACL library. Bacula is
+ automatically compiled with ACL support if the {\bf libacl} library is
+ installed on your system (shown in config.out). While restoring the
+ files Bacula will try to restore the ACLs, if there is no ACL support
+ available on the system, Bacula restores the files and directories but
+ not the ACL information. Please note, if you backup an EXT3 or XFS
+ filesystem with ACLs, then you restore them to a different filesystem
+ (perhaps reiserfs) that does not have ACLs, the ACLs will be ignored.
+
+\item [ignore case=yes|no]
+\index[dir]{ignore case}
+\index[dir]{Directive!ignore case}
+ The default is {\bf no}. On Windows systems, you will almost surely
+ want to set this to {\bf yes}. When this directive is set to {\bf yes}
+ all the case of character will be ignored in wild-card and regex
+ comparisons. That is an uppercase A will match a lowercase a.
+
+\item [fstype=filesystem-type]
+\index[dir]{fstype}
+\index[dir]{Directive!fstype}
+ This option allows you to select files and directories by the
+ filesystem type. The permitted filesystem-type names are:
+
+ ext2, jfs, ntfs, proc, reiserfs, xfs, usbdevfs, sysfs, smbfs,
+ iso9660. For ext3 systems, use ext2.
+
+ You may have multiple Fstype directives, and thus permit matching
+ of multiple filesystem types within a single Options resource. If
+ the type specified on the fstype directive does not match the
+ filesystem for a particular directive, that directory will not be
+ backed up. This directive can be used to prevent backing up
+ non-local filesystems. Normally, when you use this directive, you
+ would also set {\bf onefs=no} so that Bacula will traverse filesystems.
+
+ This option is not implemented in Win32 systems.
+
+
+\item [hfsplussupport=yes|no]
+\index[dir]{hfsplussupport}
+\index[dir]{Directive!hfsplussupport}
+ This option allows you to turn on support for Mac OSX HFS plus
+ finder information.
+
+\item [strippath=\lt{}integer\gt{}]
+\index[dir]{strippath}
+\index[dir]{Directive!strippath}
+ This option will cause {\bf integer} paths to be stripped from
+ the front of the full path/filename being backed up. This can
+ be useful if you are migrating data from another vendor or if
+ you have taken a snapshot into some subdirectory. This directive
+ can cause your filenames to be overlayed with regular backup data,
+ so should be used only by experts and with great care.
+\end{description}
+
+{\bf \lt{}file-list\gt{}} is a list of directory and/or filename names
+specified with a {\bf File =} directive. To include names containing spaces,
+enclose the name between double-quotes. Wild-cards are not interpreted
+in file-lists. They can only be specified in Options resources.
+
+There are a number of special cases when specifying directories and files in a
+{\bf file-list}. They are:
+
+\begin{itemize}
+\item Any name preceded by an at-sign (@) is assumed to be the name of a
+ file, which contains a list of files each preceded by a "File =". The
+ named file is read once when the configuration file is parsed during the
+ Director startup. Note, that the file is read on the Director's machine
+ and not on the Client's. In fact, the @filename can appear anywhere
+ within the conf file where a token would be read, and the contents of
+ the named file will be logically inserted in the place of the @filename.
+ What must be in the file depends on the location the @filename is
+ specified in the conf file. For example:
+
+\footnotesize
+\begin{verbatim}
+Include {
+ Options { compression=GZIP }
+ @/home/files/my-files
+}
+\end{verbatim}
+\normalsize
+
+\item Any name beginning with a vertical bar (|) is assumed to be the name of
+ a program. This program will be executed on the Director's machine at
+ the time the Job starts (not when the Director reads the configuration
+ file), and any output from that program will be assumed to be a list of
+ files or directories, one per line, to be included.
+
+ This allows you to have a job that, for example, includes all the local
+ partitions even if you change the partitioning by adding a disk. The
+ examples below show you how to do this. However, please note two
+ things: \\
+ 1. if you want the local filesystems, you probably should be
+ using the new {\bf fstype} directive, which was added in version 1.36.3
+ and set {\bf onefs=no}.
+ \\
+
+ 2. the exact syntax of the command needed in the examples below is very
+ system dependent. For example, on recent Linux systems, you may need to
+ add the -P option, on FreeBSD systems, the options will be different as
+ well.
+
+ In general, you will need to prefix your command or commands with a {\bf
+ sh -c} so that they are invoked by a shell. This will not be the case
+ if you are invoking a script as in the second example below. Also, you
+ must take care to escape (precede with a \textbackslash{}) wild-cards,
+ shell character, and to ensure that any spaces in your command are
+ escaped as well. If you use a single quotes (') within a double quote
+ ("), Bacula will treat everything between the single quotes as one field
+ so it will not be necessary to escape the spaces. In general, getting
+ all the quotes and escapes correct is a real pain as you can see by the
+ next example. As a consequence, it is often easier to put everything in
+ a file and simply use the file name within Bacula. In that case the
+ {\bf sh -c} will not be necessary providing the first line of the file
+ is {\bf \#!/bin/sh}.
+
+ As an example:
+
+\footnotesize
+\begin{verbatim}
+
+Include {
+ Options { signature = SHA1 }
+ File = "|sh -c 'df -l | grep \"^/dev/hd[ab]\" | grep -v \".*/tmp\" \
+ | awk \"{print \\$6}\"'"
+}
+\end{verbatim}
+\normalsize
+
+ will produce a list of all the local partitions on a Red Hat Linux system.
+ Note, the above line was split, but should normally be written on one line.
+ Quoting is a real problem because you must quote for Bacula which consists of
+ preceding every \textbackslash{} and every " with a \textbackslash{}, and
+ you must also quote for the shell command. In the end, it is probably easier
+ just to execute a small file with:
+
+
+\footnotesize
+\begin{verbatim}
+Include {
+ Options {
+ signature=MD5
+ }
+ File = "|my_partitions"
+}
+\end{verbatim}
+\normalsize
+
+ where my\_partitions has:
+
+\footnotesize
+\begin{verbatim}
+#!/bin/sh
+df -l | grep "^/dev/hd[ab]" | grep -v ".*/tmp" \
+ | awk "{print \$6}"
+\end{verbatim}
+\normalsize
+
+ If the vertical bar (|) in front of my\_partitions is preceded by a
+ backslash as in \textbackslash{}|, the program will be executed on the
+ Client's machine instead of on the Director's machine.
+ Please note that if the filename is given within quotes, you
+ will need to use two slashes. An example, provided by John Donagher,
+ that backs up all the local UFS partitions on a remote system is:
+
+\footnotesize
+\begin{verbatim}
+FileSet {
+ Name = "All local partitions"
+ Include {
+ Options { signature=SHA1; onefs=yes; }
+ File = "\\|bash -c \"df -klF ufs | tail +2 | awk '{print \$6}'\""
+ }
+}
+\end{verbatim}
+\normalsize
+
+ The above requires two backslash characters after the double quote (one
+ preserves the next one). If you are a Linux user, just change the {\bf ufs}
+ to {\bf ext3} (or your preferred filesystem type), and you will be in
+ business.
+
+ If you know what filesystems you have mounted on your system, e.g.
+ for Red Hat Linux normally only ext2 and ext3, you can backup
+ all local filesystems using something like:
+
+\footnotesize
+\begin{verbatim}
+
+Include {
+ Options { signature = SHA1; onfs=no; fstype=ext2 }
+ File = /
+}
+\end{verbatim}
+\normalsize
+
+
+\item Any file-list item preceded by a less-than sign (\lt{}) will be taken
+ to be a file. This file will be read on the Director's machine (see
+ below for doing it on the Client machine) at the time
+ the Job starts, and the data will be assumed to be a list of directories or
+ files, one per line, to be included. The names should start in column 1 and
+ should not be quoted even if they contain spaces. This feature allows you to
+ modify the external file and change what will be saved without stopping and
+ restarting Bacula as would be necessary if using the @ modifier noted above.
+ For example:
+
+\footnotesize
+\begin{verbatim}
+Include {
+ Options { signature = SHA1 }
+ File = "</home/files/local-filelist"
+}
+\end{verbatim}
+\normalsize
+
+ If you precede the less-than sign (\lt{}) with a backslash as in
+ \textbackslash{}\lt{}, the file-list will be read on the Client machine
+ instead of on the Director's machine. Please note that if the filename
+ is given within quotes, you will need to use two slashes.
+
+\footnotesize
+\begin{verbatim}
+Include {
+ Options { signature = SHA1 }
+ File = "\\</home/xxx/filelist-on-client"
+}
+\end{verbatim}
+\normalsize
+
+\item If you explicitly specify a block device such as {\bf /dev/hda1}, then
+ Bacula (starting with version 1.28) will assume that this is a raw partition
+ to be backed up. In this case, you are strongly urged to specify a {\bf
+ sparse=yes} include option, otherwise, you will save the whole partition
+ rather than just the actual data that the partition contains. For example:
+
+\footnotesize
+\begin{verbatim}
+Include {
+ Options { signature=MD5; sparse=yes }
+ File = /dev/hd6
+}
+\end{verbatim}
+\normalsize
+
+ will backup the data in device /dev/hd6.
+
+ Ludovic Strappazon has pointed out that this feature can be used to backup a
+ full Microsoft Windows disk. Simply boot into the system using a Linux Rescue
+ disk, then load a statically linked Bacula as described in the
+ \ilink{ Disaster Recovery Using Bacula}{RescueChapter} chapter of
+ this manual. Then save the whole disk partition. In the case of a disaster,
+ you can then restore the desired partition by again booting with the rescue
+ disk and doing a restore of the partition.
+ \item If you explicitly specify a FIFO device name (created with mkfifo), and
+ you add the option {\bf readfifo=yes} as an option, Bacula will read the FIFO
+ and back its data up to the Volume. For example:
+
+\footnotesize
+\begin{verbatim}
+Include {
+ Options {
+ signature=SHA1
+ readfifo=yes
+ }
+ File = /home/abc/fifo
+}
+\end{verbatim}
+\normalsize
+
+ if {\bf /home/abc/fifo} is a fifo device, Bacula will open the fifo,
+ read it, and store all data thus obtained on the Volume. Please note,
+ you must have a process on the system that is writing into the fifo, or
+ Bacula will hang, and after one minute of waiting, Bacula will give up
+ and go on to the next file. The data read can be anything since Bacula
+ treats it as a stream.
+
+ This feature can be an excellent way to do a "hot" backup of a very
+ large database. You can use the {\bf RunBeforeJob} to create the fifo
+ and to start a program that dynamically reads your database and writes
+ it to the fifo. Bacula will then write it to the Volume. Be sure to
+ read the \ilink{readfifo section}{readfifo} that gives a
+ tip to ensure that the RunBeforeJob does not block Bacula.
+
+ During the restore operation, the inverse is true, after Bacula creates
+ the fifo if there was any data stored with it (no need to explicitly
+ list it or add any options), that data will be written back to the fifo.
+ As a consequence, if any such FIFOs exist in the fileset to be restored,
+ you must ensure that there is a reader program or Bacula will block, and
+ after one minute, Bacula will time out the write to the fifo and move on
+ to the next file.
+
+\item A file-list may not contain wild-cards. Use directives in the
+ Options resource if you wish to specify wild-cards or regular expression
+ matching.
+\end{itemize}
+
+\section{FileSet Examples}
+\index[general]{Examples!FileSet }
+\index[general]{FileSet Examples}
+
+The following is an example of a valid FileSet resource definition. Note,
+the first Include pulls in the contents of the file {\bf /etc/backup.list}
+when Bacula is started (i.e. the @), and that file must have each filename
+to be backed up preceded by a {\bf File =} and on a separate line.
+
+\footnotesize
+\begin{verbatim}
+FileSet {
+ Name = "Full Set"
+ Include {
+ Options {
+ Compression=GZIP
+ signature=SHA1
+ Sparse = yes
+ }
+ @/etc/backup.list
+ }
+ Include {
+ Options {
+ wildfile = "*.o"
+ wildfile = "*.exe"
+ Exclude = yes
+ }
+ File = /root/myfile
+ File = /usr/lib/another_file
+ }
+}
+\end{verbatim}
+\normalsize
+
+In the above example, all the files contained in /etc/backup.list will
+be compressed with GZIP compression, an SHA1 signature will be computed on the
+file's contents (its data), and sparse file handling will apply.
+
+The two directories /root/myfile and /usr/lib/another\_file will also be saved
+without any options, but all files in those directories with the extensions
+{\bf .o} and {\bf .exe} will be excluded.
+
+Let's say that you now want to exclude the directory /tmp. The simplest way
+to do so is to add an exclude directive that lists /tmp. The example
+above would then become:
+
+\footnotesize
+\begin{verbatim}
+FileSet {
+ Name = "Full Set"
+ Include {
+ Options {
+ Compression=GZIP
+ signature=SHA1
+ Sparse = yes
+ }
+ @/etc/backup.list
+ }
+ Include {
+ Options {
+ wildfile = "*.o"
+ wildfile = "*.exe"
+ Exclude = yes
+ }
+ File = /root/myfile
+ File = /usr/lib/another_file
+ }
+ Exclude {
+ File = /tmp
+ }
+}
+\end{verbatim}
+\normalsize
+
+
+You can add wild-cards to the File directives listed in the Exclude
+directory, but you need to take care because if you exclude a directory,
+it and all files and directories below it will also be excluded.
+
+Now lets take a slight variation on the above and suppose
+you want to save all your whole filesystem except {\bf /tmp}.
+The problem that comes up is that Bacula will not normally
+cross from one filesystem to another.
+Doing a {\bf df} command, you get the following output:
+
+\footnotesize
+\begin{verbatim}
+[kern@rufus k]$ df
+Filesystem 1k-blocks Used Available Use% Mounted on
+/dev/hda5 5044156 439232 4348692 10% /
+/dev/hda1 62193 4935 54047 9% /boot
+/dev/hda9 20161172 5524660 13612372 29% /home
+/dev/hda2 62217 6843 52161 12% /rescue
+/dev/hda8 5044156 42548 4745376 1% /tmp
+/dev/hda6 5044156 2613132 2174792 55% /usr
+none 127708 0 127708 0% /dev/shm
+//minimatou/c$ 14099200 9895424 4203776 71% /mnt/mmatou
+lmatou:/ 1554264 215884 1258056 15% /mnt/matou
+lmatou:/home 2478140 1589952 760072 68% /mnt/matou/home
+lmatou:/usr 1981000 1199960 678628 64% /mnt/matou/usr
+lpmatou:/ 995116 484112 459596 52% /mnt/pmatou
+lpmatou:/home 19222656 2787880 15458228 16% /mnt/pmatou/home
+lpmatou:/usr 2478140 2038764 311260 87% /mnt/pmatou/usr
+deuter:/ 4806936 97684 4465064 3% /mnt/deuter
+deuter:/home 4806904 280100 4282620 7% /mnt/deuter/home
+deuter:/files 44133352 27652876 14238608 67% /mnt/deuter/files
+\end{verbatim}
+\normalsize
+
+And we see that there are a number of separate filesystems (/ /boot
+/home /rescue /tmp and /usr not to mention mounted systems).
+If you specify only {\bf /} in your Include list, Bacula will only save the
+Filesystem {\bf /dev/hda5}. To save all filesystems except {\bf /tmp} with
+out including any of the Samba or NFS mounted systems, and explicitly
+excluding a /tmp, /proc, .journal, and .autofsck, which you will not want to
+be saved and restored, you can use the following:
+
+\footnotesize
+\begin{verbatim}
+FileSet {
+ Name = Include_example
+ Include {
+ Options {
+ wilddir = /proc
+ wilddir = /tmp
+ wildfile = "/.journal"
+ wildfile = "/.autofsck"
+ exclude = yes
+ }
+ File = /
+ File = /boot
+ File = /home
+ File = /rescue
+ File = /usr
+ }
+}
+\end{verbatim}
+\normalsize
+
+Since /tmp is on its own filesystem and it was not explicitly named in the
+Include list, it is not really needed in the exclude list. It is better to
+list it in the Exclude list for clarity, and in case the disks are changed so
+that it is no longer in its own partition.
+
+Now, lets assume you only want to backup .Z and .gz files and nothing
+else. This is a bit trickier because Bacula by default will select
+everything to backup, so we must exclude everything but .Z and .gz files.
+If we take the first example above and make the obvious modifications
+to it, we might come up with a FileSet that looks like this:
+
+\footnotesize
+\begin{verbatim}
+FileSet {
+ Name = "Full Set"
+ Include { !!!!!!!!!!!!
+ Options { This
+ wildfile = "*.Z" example
+ wildfile = "*.gz" doesn't
+ work
+ } !!!!!!!!!!!!
+ File = /myfile
+ }
+}
+\end{verbatim}
+\normalsize
+
+The *.Z and *.gz files will indeed be backed up, but all other files
+that are not matched by the Options directives will automatically
+be backed up too (i.e. that is the default rule).
+
+To accomplish what we want, we must explicitly exclude all other files.
+We do this with the following:
+
+\footnotesize
+\begin{verbatim}
+FileSet {
+ Name = "Full Set"
+ Include {
+ Options {
+ wildfile = "*.Z"
+ wildfile = "*.gz"
+ }
+ Options {
+ Exclude = yes
+ RegexFile = ".*"
+ }
+ File = /myfile
+ }
+}
+\end{verbatim}
+\normalsize
+
+The "trick" here was to add a RegexFile expression that matches
+all files. It does not match directory names, so all directories in
+/myfile will be backed up (the directory entry) and any *.Z and *.gz
+files contained in them. If you know that certain directories do
+not contain any *.Z or *.gz files and you do not want the directory
+entries backed up, you will need to explicitly exclude those directories.
+Backing up a directory entries is not very expensive.
+
+Bacula uses the system regex library and some of them are
+different on different OSes. The above has been reported not to work
+on FreeBSD. This can be tested by using the {\bf estimate job=job-name
+listing} command in the console and adapting the RegexFile expression
+appropriately. In a future version of Bacula, we will supply our own
+Regex code to avoid such system dependencies.
+
+Please be aware that allowing Bacula to traverse or change file systems can be
+{\bf very} dangerous. For example, with the following:
+
+\footnotesize
+\begin{verbatim}
+FileSet {
+ Name = "Bad example"
+ Include {
+ Options { onefs=no }
+ File = /mnt/matou
+ }
+}
+\end{verbatim}
+\normalsize
+
+you will be backing up an NFS mounted partition ({\bf /mnt/matou}), and since
+{\bf onefs} is set to {\bf no}, Bacula will traverse file systems. Now if {\bf
+/mnt/matou} has the current machine's file systems mounted, as is often the
+case, you will get yourself into a recursive loop and the backup will never
+end.
+
+As a final example, let's say that you have only one or two
+subdirectories of /home that you want to backup. For example,
+you want to backup only subdirectories beginning with the letter
+a and the letter b -- i.e. /home/a* and /home/b*. Now, you might first
+try:
+\footnotesize
+\begin{verbatim}
+FileSet {
+ Name = "Full Set"
+ Include {
+ Options {
+ wilddir = "/home/a*"
+ wilddir = "/home/b*"
+ }
+ File = /home
+ }
+}
+\end{verbatim}
+\normalsize
+
+The problem is that the above will include everything in /home. To get
+things to work correctly, you need to start with the idea of exclusion
+instead of inclusion. So, you could simply exclude all directories
+except the two you want to use:
+\footnotesize
+\begin{verbatim}
+FileSet {
+ Name = "Full Set"
+ Include {
+ Options {
+ RegexDir = "^/home/[c-z]"
+ exclude = yes
+ }
+ File = /home
+ }
+}
+\end{verbatim}
+\normalsize
+
+And assuming that all subdirectories start with a lowercase letter, this
+would work.
+
+An alternative would be to include the two subdirectories desired and
+exclude everything else:
+\footnotesize
+\begin{verbatim}
+FileSet {
+ Name = "Full Set"
+ Include {
+ Options {
+ wilddir = "/home/a*"
+ wilddir = "/home/b*"
+ }
+ Options {
+ RegexDir = ".*"
+ exclude = yes
+ }
+ File = /home
+ }
+}
+\end{verbatim}
+\normalsize
+
+\section{Backing up Raw Partitions}
+\index[general]{Backing up!Partitions }
+\index[general]{Backing up Raw Partitions }
+
+The following FileSet definition will backup a raw partition:
+
+\footnotesize
+\begin{verbatim}
+FileSet {
+ Name = "RawPartition"
+ Include {
+ Options { sparse=yes }
+ File = /dev/hda2
+ }
+}
+\end{verbatim}
+\normalsize
+
+While backing up and restoring a raw partition, you should ensure that no
+other process including the system is writing to that partition. As a
+precaution, you are strongly urged to ensure that the raw partition is not
+mounted or is mounted read-only. If necessary, this can be done using the {\bf
+RunBeforeJob} directive.
+
+
+\section{Excluding Files and Directories}
+\index[general]{Directories!Excluding Files and }
+\index[general]{Excluding Files and Directories }
+
+You may also include full filenames or directory names in addition to using
+wild-cards and {\bf Exclude=yes} in the Options resource as specified above by
+simply including the files to be excluded in an Exclude resource within the
+FileSet. For example:
+
+\footnotesize
+\begin{verbatim}
+FileSet {
+ Name = Exclusion_example
+ Include {
+ Options {
+ Signature = SHA1
+ }
+ File = /
+ File = /boot
+ File = /home
+ File = /rescue
+ File = /usr
+ }
+ Exclude {
+ File = /proc
+ File = /tmp
+ File = .journal
+ File = .autofsck
+ }
+}
+\end{verbatim}
+\normalsize
+
+\label{win32}
+\section{Windows FileSets}
+\index[general]{Windows FileSets }
+\index[general]{FileSets!Windows }
+If you are entering Windows file names, the directory path may be preceded by
+the drive and a colon (as in c:). However, the path separators must be
+specified in Unix convention (i.e. forward slash (/)). If you wish to include
+a quote in a file name, precede the quote with a backslash
+(\textbackslash{}). For example you might use the following
+for a Windows machine to backup the "My Documents" directory:
+
+\footnotesize
+\begin{verbatim}
+FileSet {
+ Name = "Windows Set"
+ Include {
+ Options {
+ WildFile = "*.obj"
+ WildFile = "*.exe"
+ exclude = yes
+ }
+ File = "c:/My Documents"
+ }
+}
+\end{verbatim}
+\normalsize
+
+For exclude lists to work correctly on Windows, you must observe the following
+rules:
+
+\begin{itemize}
+\item Filenames are case sensitive, so you must use the correct case.
+\item To 2~exclude a directory, you must not have a trailing slash on the
+ directory name.
+\item I2~f you have spaces in your filename, you must enclose the entire name
+ in double-quote characters ("). Trying to use a backslash before the space
+ will not work.
+\item If you are using the old Exclude syntax (noted below), you may not
+ specify a drive letter in the exclude. The new syntax noted above
+ should work fine including driver letters.
+\end{itemize}
+
+Thanks to Thiago Lima for summarizing the above items for us. If you are
+having difficulties getting includes or excludes to work, you might want to
+try using the {\bf estimate job=xxx listing} command documented in the
+\ilink{Console chapter}{estimate} of this manual.
+
+On Win32 systems, if you move a directory or file or rename a file into the
+set of files being backed up, and a Full backup has already been made, Bacula
+will not know there are new files to be saved during an Incremental or
+Differential backup (blame Microsoft, not me). To avoid this problem, please
+{\bf copy} any new directory or files into the backup area. If you do not have
+enough disk to copy the directory or files, move them, but then initiate a
+Full backup.
+
+
+\paragraph*{A Windows Example FileSet}
+\index[general]{FileSet!Windows Example }
+\index[general]{Windows Example FileSet }
+
+The following example was contributed by Russell Howe. Please note that
+for presentation purposes, the lines beginning with Data and Internet
+have been wrapped and should included on the previous line with one
+space.
+
+\footnotesize
+\begin{verbatim}
+This is my Windows 2000 fileset:
+FileSet {
+ Name = "Windows 2000"
+ Include {
+ Options {
+ signature = MD5
+ Exclude = yes
+ IgnoreCase = yes
+ # Exclude Mozilla-based programs' file caches
+ WildDir = "[A-Z]:/Documents and Settings/*/Application
+Data/*/Profiles/*/*/Cache"
+ WildDir = "[A-Z]:/Documents and Settings/*/Application
+Data/*/Profiles/*/*/Cache.Trash"
+ WildDir = "[A-Z]:/Documents and Settings/*/Application
+Data/*/Profiles/*/*/ImapMail"
+
+ # Exclude user's registry files - they're always in use anyway.
+ WildFile = "[A-Z]:/Documents and Settings/*/Local Settings/Application
+Data/Microsoft/Windows/usrclass.*"
+ WildFile = "[A-Z]:/Documents and Settings/*/ntuser.*"
+
+ # Exclude directories full of lots and lots of useless little files
+ WildDir = "[A-Z]:/Documents and Settings/*/Cookies"
+ WildDir = "[A-Z]:/Documents and Settings/*/Recent"
+ WildDir = "[A-Z]:/Documents and Settings/*/Local Settings/History"
+ WildDir = "[A-Z]:/Documents and Settings/*/Local Settings/Temp"
+ WildDir = "[A-Z]:/Documents and Settings/*/Local Settings/Temporary
+Internet Files"
+
+ # These are always open and unable to be backed up
+ WildFile = "[A-Z]:/Documents and Settings/All Users/Application
+Data/Microsoft/Network/Downloader/qmgr[01].dat"
+
+ # Some random bits of Windows we want to ignore
+ WildFile = "[A-Z]:/WINNT/security/logs/scepol.log"
+ WildDir = "[A-Z]:/WINNT/system32/config"
+ WildDir = "[A-Z]:/WINNT/msdownld.tmp"
+ WildDir = "[A-Z]:/WINNT/Internet Logs"
+ WildDir = "[A-Z]:/WINNT/$Nt*Uninstall*"
+ WildDir = "[A-Z]:/WINNT/sysvol"
+ WildFile = "[A-Z]:/WINNT/cluster/CLUSDB"
+ WildFile = "[A-Z]:/WINNT/cluster/CLUSDB.LOG"
+ WildFile = "[A-Z]:/WINNT/NTDS/edb.log"
+ WildFile = "[A-Z]:/WINNT/NTDS/ntds.dit"
+ WildFile = "[A-Z]:/WINNT/NTDS/temp.edb"
+ WildFile = "[A-Z]:/WINNT/ntfrs/jet/log/edb.log"
+ WildFile = "[A-Z]:/WINNT/ntfrs/jet/ntfrs.jdb"
+ WildFile = "[A-Z]:/WINNT/ntfrs/jet/temp/tmp.edb"
+ WildFile = "[A-Z]:/WINNT/system32/CPL.CFG"
+ WildFile = "[A-Z]:/WINNT/system32/dhcp/dhcp.mdb"
+ WildFile = "[A-Z]:/WINNT/system32/dhcp/j50.log"
+ WildFile = "[A-Z]:/WINNT/system32/dhcp/tmp.edb"
+ WildFile = "[A-Z]:/WINNT/system32/LServer/edb.log"
+ WildFile = "[A-Z]:/WINNT/system32/LServer/TLSLic.edb"
+ WildFile = "[A-Z]:/WINNT/system32/LServer/tmp.edb"
+ WildFile = "[A-Z]:/WINNT/system32/wins/j50.log"
+ WildFile = "[A-Z]:/WINNT/system32/wins/wins.mdb"
+ WildFile = "[A-Z]:/WINNT/system32/wins/winstmp.mdb"
+
+ # Temporary directories & files
+ WildDir = "[A-Z]:/WINNT/Temp"
+ WildDir = "[A-Z]:/temp"
+ WildFile = "*.tmp"
+ WildDir = "[A-Z]:/tmp"
+ WildDir = "[A-Z]:/var/tmp"
+
+ # Recycle bins
+ WildDir = "[A-Z]:/RECYCLER"
+
+ # Swap files
+ WildFile = "[A-Z]:/pagefile.sys"
+
+ # These are programs and are easier to reinstall than restore from
+ # backup
+ WildDir = "[A-Z]:/cygwin"
+ WildDir = "[A-Z]:/Program Files/Grisoft"
+ WildDir = "[A-Z]:/Program Files/Java"
+ WildDir = "[A-Z]:/Program Files/Java Web Start"
+ WildDir = "[A-Z]:/Program Files/JavaSoft"
+ WildDir = "[A-Z]:/Program Files/Microsoft Office"
+ WildDir = "[A-Z]:/Program Files/Mozilla Firefox"
+ WildDir = "[A-Z]:/Program Files/Mozilla Thunderbird"
+ WildDir = "[A-Z]:/Program Files/mozilla.org"
+ WildDir = "[A-Z]:/Program Files/OpenOffice*"
+ }
+
+ # Our Win2k boxen all have C: and D: as the main hard drives.
+ File = "C:/"
+ File = "D:/"
+ }
+}
+\end{verbatim}
+\normalsize
+
+Note, the three line of the above Exclude were split to fit on the document
+page, they should be written on a single line in real use.
+
+\paragraph*{Windows NTFS Naming Considerations}
+\index[general]{Windows NTFS Naming Considerations }
+\index[general]{Considerations!Windows NTFS Naming }
+
+NTFS filenames containing Unicode characters should now be supported
+as of version 1.37.30 or later.
+
+\section{Testing Your FileSet}
+\index[general]{FileSet!Testing Your }
+\index[general]{Testing Your FileSet }
+
+If you wish to get an idea of what your FileSet will really backup or if your
+exclusion rules will work correctly, you can test it by using the {\bf
+estimate} command in the Console program. See the
+\ilink{estimate}{estimate} in the Console chapter of this
+manual.
+
+As an example, suppose you add the following test FileSet:
+
+\footnotesize
+\begin{verbatim}
+FileSet {
+ Name = Test
+ Include {
+ File = /home/xxx/test
+ Options {
+ regex = ".*\.c$"
+ }
+ }
+}
+\end{verbatim}
+\normalsize
+
+You could then add some test files to the directory {\bf /home/xxx/test}
+and use the following command in the console:
+
+\footnotesize
+\begin{verbatim}
+estimate job=<any-job-name> listing client=<desired-client> fileset=Test
+\end{verbatim}
+\normalsize
+
+to give you a listing of all files that match.
--- /dev/null
+#!/usr/bin/perl -w
+# Fixes various things within tex files.
+
+use strict;
+
+my %args;
+
+
+sub get_includes {
+ # Get a list of include files from the top-level tex file.
+ my (@list,$file);
+
+ foreach my $filename (@_) {
+ $filename or next;
+ # Start with the top-level latex file so it gets checked too.
+ push (@list,$filename);
+
+ # Get a list of all the html files in the directory.
+ open IF,"<$filename" or die "Cannot open input file $filename";
+ while (<IF>) {
+ chomp;
+ push @list,"$1.tex" if (/\\include\{(.*?)\}/);
+ }
+
+ close IF;
+ }
+ return @list;
+}
+
+sub convert_files {
+ my (@files) = @_;
+ my ($linecnt,$filedata,$output,$itemcnt,$indentcnt,$cnt);
+
+ $cnt = 0;
+ foreach my $file (@files) {
+ # Open the file and load the whole thing into $filedata. A bit wasteful but
+ # easier to deal with, and we don't have a problem with speed here.
+ $filedata = "";
+ open IF,"<$file" or die "Cannot open input file $file";
+ while (<IF>) {
+ $filedata .= $_;
+ }
+ close IF;
+
+ # We look for a line that starts with \item, and indent the two next lines (if not blank)
+ # by three spaces.
+ my $linecnt = 3;
+ $indentcnt = 0;
+ $output = "";
+ # Process a line at a time.
+ foreach (split(/\n/,$filedata)) {
+ $_ .= "\n"; # Put back the return.
+ # If this line is less than the third line past the \item command,
+ # and the line isn't blank and doesn't start with whitespace
+ # add three spaces to the start of the line. Keep track of the number
+ # of lines changed.
+ if ($linecnt < 3 and !/^\\item/) {
+ if (/^[^\n\s]/) {
+ $output .= " " . $_;
+ $indentcnt++;
+ } else {
+ $output .= $_;
+ }
+ $linecnt++;
+ } else {
+ $linecnt = 3;
+ $output .= $_;
+ }
+ /^\\item / and $linecnt = 1;
+ }
+
+
+ # This is an item line. We need to process it too. If inside a \begin{description} environment, convert
+ # \item {\bf xxx} to \item [xxx] or \item [{xxx}] (if xxx contains '[' or ']'.
+ $itemcnt = 0;
+ $filedata = $output;
+ $output = "";
+ my ($before,$descrip,$this,$between);
+
+ # Find any \begin{description} environment
+ while ($filedata =~ /(\\begin[\s\n]*\{[\s\n]*description[\s\n]*\})(.*?)(\\end[\s\n]*\{[\s\n]*description[\s\n]*\})/s) {
+ $output .= $` . $1;
+ $filedata = $3 . $';
+ $descrip = $2;
+
+ # Search for \item {\bf xxx}
+ while ($descrip =~ /\\item[\s\n]*\{[\s\n]*\\bf[\s\n]*/s) {
+ $descrip = $';
+ $output .= $`;
+ ($between,$descrip) = find_matching_brace($descrip);
+ if (!$descrip) {
+ $linecnt = $output =~ tr/\n/\n/;
+ print STDERR "Missing matching curly brace at line $linecnt in $file\n" if (!$descrip);
+ }
+
+ # Now do the replacement.
+ $between = '{' . $between . '}' if ($between =~ /\[|\]/);
+ $output .= "\\item \[$between\]";
+ $itemcnt++;
+ }
+ $output .= $descrip;
+ }
+ $output .= $filedata;
+
+ # If any hyphens or \item commnads were converted, save the file.
+ if ($indentcnt or $itemcnt) {
+ open OF,">$file" or die "Cannot open output file $file";
+ print OF $output;
+ close OF;
+ print "$indentcnt indent", ($indentcnt == 1) ? "" : "s"," added in $file\n";
+ print "$itemcnt item", ($itemcnt == 1) ? "" : "s"," Changed in $file\n";
+ }
+
+ $cnt += $indentcnt + $itemcnt;
+ }
+ return $cnt;
+}
+
+sub find_matching_brace {
+ # Finds text up to the next matching brace. Assumes that the input text doesn't contain
+ # the opening brace, but we want to find text up to a matching closing one.
+ # Returns the text between the matching braces, followed by the rest of the text following
+ # (which does not include the matching brace).
+ #
+ my $str = shift;
+ my ($this,$temp);
+ my $cnt = 1;
+
+ while ($cnt) {
+ # Ignore verbatim constructs involving curly braces, or if the character preceding
+ # the curly brace is a backslash.
+ if ($str =~ /\\verb\*?\{.*?\{|\\verb\*?\}.*?\}|\{|\}/s) {
+ $this .= $`;
+ $str = $';
+ $temp = $&;
+
+ if ((substr($this,-1,1) eq '\\') or
+ $temp =~ /^\\verb/) {
+ $this .= $temp;
+ next;
+ }
+
+ $cnt += ($temp eq '{') ? 1 : -1;
+ # If this isn't the matching curly brace ($cnt > 0), include the brace.
+ $this .= $temp if ($cnt);
+ } else {
+ # No matching curly brace found.
+ return ($this . $str,'');
+ }
+ }
+ return ($this,$str);
+}
+
+sub check_arguments {
+ # Checks command-line arguments for ones starting with -- puts them into
+ # a hash called %args and removes them from @ARGV.
+ my $args = shift;
+ my $i;
+
+ for ($i = 0; $i < $#ARGV; $i++) {
+ $ARGV[$i] =~ /^\-+/ or next;
+ $ARGV[$i] =~ s/^\-+//;
+ $args{$ARGV[$i]} = "";
+ delete ($ARGV[$i]);
+
+ }
+}
+
+##################################################################
+# MAIN ####
+##################################################################
+
+my @includes;
+my $cnt;
+
+check_arguments(\%args);
+die "No Files given to Check\n" if ($#ARGV < 0);
+
+# Examine the file pointed to by the first argument to get a list of
+# includes to test.
+@includes = get_includes(@ARGV);
+
+$cnt = convert_files(@includes);
+print "No lines changed\n" unless $cnt;
--- /dev/null
+# This module does multiple indices, supporting the style of the LaTex 'index'
+# package.
+
+# Version Information:
+# 16-Feb-2005 -- Original Creation. Karl E. Cunningham
+# 14-Mar-2005 -- Clarified and Consolodated some of the code.
+# Changed to smoothly handle single and multiple indices.
+
+# Two LaTeX index formats are supported...
+# --- SINGLE INDEX ---
+# \usepackage{makeidx}
+# \makeindex
+# \index{entry1}
+# \index{entry2}
+# \index{entry3}
+# ...
+# \printindex
+#
+# --- MULTIPLE INDICES ---
+#
+# \usepackage{makeidx}
+# \usepackage{index}
+# \makeindex -- latex2html doesn't care but LaTeX does.
+# \newindex{ref1}{ext1}{ext2}{title1}
+# \newindex{ref2}{ext1}{ext2}{title2}
+# \newindex{ref3}{ext1}{ext2}{title3}
+# \index[ref1]{entry1}
+# \index[ref1]{entry2}
+# \index[ref3]{entry3}
+# \index[ref2]{entry4}
+# \index{entry5}
+# \index[ref3]{entry6}
+# ...
+# \printindex[ref1]
+# \printindex[ref2]
+# \printindex[ref3]
+# \printindex
+# ___________________
+#
+# For the multiple-index style, each index is identified by the ref argument to \newindex, \index,
+# and \printindex. A default index is allowed, which is indicated by omitting the optional
+# argument. The default index does not require a \newindex command. As \index commands
+# are encountered, their entries are stored according
+# to the ref argument. When the \printindex command is encountered, the stored index
+# entries for that argument are retrieved and printed. The title for each index is taken
+# from the last argument in the \newindex command.
+# While processing \index and \printindex commands, if no argument is given the index entries
+# are built into a default index. The title of the default index is simply "Index".
+# This makes the difference between single- and multiple-index processing trivial.
+#
+# Another method can be used by omitting the \printindex command and just using \include to
+# pull in index files created by the makeindex program. These files will start with
+# \begin{theindex}. This command is used to determine where to print the index. Using this
+# approach, the indices will be output in the same order as the newindex commands were
+# originally found (see below). Using a combination of \printindex and \include{indexfile} has not
+# been tested and may produce undesireable results.
+#
+# The index data are stored in a hash for later sorting and output. As \printindex
+# commands are handled, the order in which they were found in the tex filea is saved,
+# associated with the ref argument to \printindex.
+#
+# We use the original %index hash to store the index data into. We append a \002 followed by the
+# name of the index to isolate the entries in different indices from each other. This is necessary
+# so that different indices can have entries with the same name. For the default index, the \002 is
+# appended without the name.
+#
+# Since the index order in the output cannot be determined if the \include{indexfile}
+# command is used, the order will be assumed from the order in which the \newindex
+# commands were originally seen in the TeX files. This order is saved as well as the
+# order determined from any printindex{ref} commands. If \printindex commnads are used
+# to specify the index output, that order will be used. If the \include{idxfile} command
+# is used, the order of the original newindex commands will be used. In this case the
+# default index will be printed last since it doesn't have a corresponding \newindex
+# command and its order cannot be determined. Mixing \printindex and \include{idxfile}
+# commands in the same file is likely to produce less than satisfactory results.
+#
+#
+# The hash containing index data is named %indices. It contains the following data:
+#{
+# 'title' => {
+# $ref1 => $indextitle ,
+# $ref2 => $indextitle ,
+# ...
+# },
+# 'newcmdorder' => [ ref1, ref2, ..., * ], # asterisk indicates the position of the default index.
+# 'printindorder' => [ ref1, ref2, ..., * ], # asterisk indicates the position of the default index.
+#}
+
+
+# Globals to handle multiple indices.
+my %indices;
+
+# This tells the system to use up to 7 words in index entries.
+$WORDS_IN_INDEX = 10;
+
+# KEC 2-18-05
+# Handles the \newindex command. This is called if the \newindex command is
+# encountered in the LaTex source. Gets the index ref and title from the arguments.
+# Saves the index ref and title.
+# Note that we are called once to handle multiple \newindex commands that are
+# newline-separated.
+sub do_cmd_newindex {
+ my $data = shift;
+ # The data is sent to us as fields delimited by their ID #'s. We extract the
+ # fields.
+ foreach my $line (split("\n",$data)) {
+ my @fields = split (/(?:\<\#\d+?\#\>)+/,$line);
+
+ # The index name and title are the second and fourth fields in the data.
+ if ($line =~ /^</ or $line =~ /^\\newindex/) {
+ my ($indexref,$indextitle) = ($fields[1],$fields[4]);
+ $indices{'title'}{$indexref} = $indextitle;
+ push (@{$indices{'newcmdorder'}},$indexref);
+ }
+ }
+}
+
+
+# KEC -- Copied from makeidx.perl and modified to do multiple indices.
+# Processes an \index entry from the LaTex file.
+# Gets the optional argument from the index command, which is the name of the index
+# into which to place the entry.
+# Drops the brackets from the index_name
+# Puts the index entry into the html stream
+# Creates the tokenized index entry (which also saves the index entry info
+sub do_real_index {
+ local($_) = @_;
+ local($pat,$idx_entry,$index_name);
+ # catches opt-arg from \index commands for index.sty
+ $index_name = &get_next_optional_argument;
+ $index_name = "" unless defined $index_name;
+ # Drop leading and trailing brackets from the index name.
+ $index_name =~ s/^\[|\]$//g;
+
+ $idx_entry = &missing_braces unless (
+ (s/$next_pair_pr_rx/$pat=$1;$idx_entry=$2;''/e)
+ ||(s/$next_pair_rx/$pat=$1;$idx_entry=$2;''/e));
+
+ if ($index_name and defined $idx_entry and
+ !defined $indices{'title'}{$index_name}) {
+ print STDERR "\nInvalid Index Name: \\index \[$index_name\]\{$idx_entry\}\n";
+ }
+
+ $idx_entry = &named_index_entry($pat, $idx_entry,$index_name);
+ $idx_entry.$_;
+}
+
+# Creates and saves an index entry in the index hashes.
+# Modified to do multiple indices.
+# Creates an index_key that allows index entries to have the same characteristics but be in
+# different indices. This index_key is the regular key with the index name appended.
+# Save the index order for the entry in the %index_order hash.
+sub named_index_entry {
+ local($br_id, $str, $index_name) = @_;
+ my ($index_key);
+ # escape the quoting etc characters
+ # ! -> \001
+ # @ -> \002
+ # | -> \003
+ $* = 1; $str =~ s/\n\s*/ /g; $* = 0; # remove any newlines
+ # protect \001 occurring with images
+ $str =~ s/\001/\016/g; # 0x1 to 0xF
+ $str =~ s/\\\\/\011/g; # Double backslash -> 0xB
+ $str =~ s/\\;SPMquot;/\012/g; # \;SPMquot; -> 0xC
+ $str =~ s/;SPMquot;!/\013/g; # ;SPMquot; -> 0xD
+ $str =~ s/!/\001/g; # Exclamation point -> 0x1
+ $str =~ s/\013/!/g; # 0xD -> Exclaimation point
+ $str =~ s/;SPMquot;@/\015/g; # ;SPMquot;@ to 0xF
+ $str =~ s/@/\002/g; # At sign -> 0x2
+ $str =~ s/\015/@/g; # 0xF to At sign
+ $str =~ s/;SPMquot;\|/\017/g; # ;SMPquot;| to 0x11
+ $str =~ s/\|/\003/g; # Vertical line to 0x3
+ $str =~ s/\017/|/g; # 0x11 to vertical line
+ $str =~ s/;SPMquot;(.)/\1/g; # ;SPMquot; -> whatever the next character is
+ $str =~ s/\012/;SPMquot;/g; # 0x12 to ;SPMquot;
+ $str =~ s/\011/\\\\/g; # 0x11 to double backslash
+ local($key_part, $pageref) = split("\003", $str, 2);
+
+ # For any keys of the form: blablabla!blablabla, which want to be split at the
+ # exclamation point, replace the ! with a comma and a space. We don't do it
+ # that way for this index.
+ $key_part =~ s/\001/, /g;
+ local(@keys) = split("\001", $key_part);
+ # If TITLE is not yet available use $before.
+ $TITLE = $saved_title if (($saved_title)&&(!($TITLE)||($TITLE eq $default_title)));
+ $TITLE = $before unless $TITLE;
+ # Save the reference
+ local($words) = '';
+ if ($SHOW_SECTION_NUMBERS) { $words = &make_idxnum; }
+ elsif ($SHORT_INDEX) { $words = &make_shortidxname; }
+ else { $words = &make_idxname; }
+ local($super_key) = '';
+ local($sort_key, $printable_key, $cur_key);
+ foreach $key (@keys) {
+ $key =~ s/\016/\001/g; # revert protected \001s
+ ($sort_key, $printable_key) = split("\002", $key);
+ #
+ # RRM: 16 May 1996
+ # any \label in the printable-key will have already
+ # created a label where the \index occurred.
+ # This has to be removed, so that the desired label
+ # will be found on the Index page instead.
+ #
+ if ($printable_key =~ /tex2html_anchor_mark/ ) {
+ $printable_key =~ s/><tex2html_anchor_mark><\/A><A//g;
+ local($tmpA,$tmpB) = split("NAME=\"", $printable_key);
+ ($tmpA,$tmpB) = split("\"", $tmpB);
+ $ref_files{$tmpA}='';
+ $index_labels{$tmpA} = 1;
+ }
+ #
+ # resolve and clean-up the hyperlink index-entries
+ # so they can be saved in an index.pl file
+ #
+ if ($printable_key =~ /$cross_ref_mark/ ) {
+ local($label,$id,$ref_label);
+ # $printable_key =~ s/$cross_ref_mark#(\w+)#(\w+)>$cross_ref_mark/
+ $printable_key =~ s/$cross_ref_mark#([^#]+)#([^>]+)>$cross_ref_mark/
+ do { ($label,$id) = ($1,$2);
+ $ref_label = $external_labels{$label} unless
+ ($ref_label = $ref_files{$label});
+ '"' . "$ref_label#$label" . '">' .
+ &get_ref_mark($label,$id)}
+ /geo;
+ }
+ $printable_key =~ s/<\#[^\#>]*\#>//go;
+ #RRM
+ # recognise \char combinations, for a \backslash
+ #
+ $printable_key =~ s/\&\#;\'134/\\/g; # restore \\s
+ $printable_key =~ s/\&\#;\`<BR> /\\/g; # ditto
+ $printable_key =~ s/\&\#;*SPMquot;92/\\/g; # ditto
+ #
+ # $sort_key .= "@$printable_key" if !($printable_key); # RRM
+ $sort_key .= "@$printable_key" if !($sort_key); # RRM
+ $sort_key =~ tr/A-Z/a-z/;
+ if ($super_key) {
+ $cur_key = $super_key . "\001" . $sort_key;
+ $sub_index{$super_key} .= $cur_key . "\004";
+ } else {
+ $cur_key = $sort_key;
+ }
+
+ # Append the $index_name to the current key with a \002 delimiter. This will
+ # allow the same index entry to appear in more than one index.
+ $index_key = $cur_key . "\002$index_name";
+
+ $index{$index_key} .= "";
+
+ #
+ # RRM, 15 June 1996
+ # if there is no printable key, but one is known from
+ # a previous index-entry, then use it.
+ #
+ if (!($printable_key) && ($printable_key{$index_key}))
+ { $printable_key = $printable_key{$index_key}; }
+# if (!($printable_key) && ($printable_key{$cur_key}))
+# { $printable_key = $printable_key{$cur_key}; }
+ #
+ # do not overwrite the printable_key if it contains an anchor
+ #
+ if (!($printable_key{$index_key} =~ /tex2html_anchor_mark/ ))
+ { $printable_key{$index_key} = $printable_key || $key; }
+# if (!($printable_key{$cur_key} =~ /tex2html_anchor_mark/ ))
+# { $printable_key{$cur_key} = $printable_key || $key; }
+
+ $super_key = $cur_key;
+ }
+ #
+ # RRM
+ # page-ranges, from |( and |) and |see
+ #
+ if ($pageref) {
+ if ($pageref eq "\(" ) {
+ $pageref = '';
+ $next .= " from ";
+ } elsif ($pageref eq "\)" ) {
+ $pageref = '';
+ local($next) = $index{$index_key};
+# local($next) = $index{$cur_key};
+ # $next =~ s/[\|] *$//;
+ $next =~ s/(\n )?\| $//;
+ $index{$index_key} = "$next to ";
+# $index{$cur_key} = "$next to ";
+ }
+ }
+
+ if ($pageref) {
+ $pageref =~ s/\s*$//g; # remove trailing spaces
+ if (!$pageref) { $pageref = ' ' }
+ $pageref =~ s/see/<i>see <\/i> /g;
+ #
+ # RRM: 27 Dec 1996
+ # check if $pageref corresponds to a style command.
+ # If so, apply it to the $words.
+ #
+ local($tmp) = "do_cmd_$pageref";
+ if (defined &$tmp) {
+ $words = &$tmp("<#0#>$words<#0#>");
+ $words =~ s/<\#[^\#]*\#>//go;
+ $pageref = '';
+ }
+ }
+ #
+ # RRM: 25 May 1996
+ # any \label in the pageref section will have already
+ # created a label where the \index occurred.
+ # This has to be removed, so that the desired label
+ # will be found on the Index page instead.
+ #
+ if ($pageref) {
+ if ($pageref =~ /tex2html_anchor_mark/ ) {
+ $pageref =~ s/><tex2html_anchor_mark><\/A><A//g;
+ local($tmpA,$tmpB) = split("NAME=\"", $pageref);
+ ($tmpA,$tmpB) = split("\"", $tmpB);
+ $ref_files{$tmpA}='';
+ $index_labels{$tmpA} = 1;
+ }
+ #
+ # resolve and clean-up any hyperlinks in the page-ref,
+ # so they can be saved in an index.pl file
+ #
+ if ($pageref =~ /$cross_ref_mark/ ) {
+ local($label,$id,$ref_label);
+ # $pageref =~ s/$cross_ref_mark#(\w+)#(\w+)>$cross_ref_mark/
+ $pageref =~ s/$cross_ref_mark#([^#]+)#([^>]+)>$cross_ref_mark/
+ do { ($label,$id) = ($1,$2);
+ $ref_files{$label} = ''; # ???? RRM
+ if ($index_labels{$label}) { $ref_label = ''; }
+ else { $ref_label = $external_labels{$label}
+ unless ($ref_label = $ref_files{$label});
+ }
+ '"' . "$ref_label#$label" . '">' . &get_ref_mark($label,$id)}/geo;
+ }
+ $pageref =~ s/<\#[^\#>]*\#>//go;
+
+ if ($pageref eq ' ') { $index{$index_key}='@'; }
+ else { $index{$index_key} .= $pageref . "\n | "; }
+ } else {
+ local($thisref) = &make_named_href('',"$CURRENT_FILE#$br_id",$words);
+ $thisref =~ s/\n//g;
+ $index{$index_key} .= $thisref."\n | ";
+ }
+ #print "\nREF: $sort_key : $index_key :$index{$index_key}";
+
+ #join('',"<A NAME=$br_id>$anchor_invisible_mark<\/A>",$_);
+
+ "<A NAME=\"$br_id\">$anchor_invisible_mark<\/A>";
+}
+
+
+# KEC. -- Copied from makeidx.perl, then modified to do multiple indices.
+# Feeds the index entries to the output. This is called for each index to be built.
+#
+# Generates a list of lookup keys for index entries, from both %printable_keys
+# and %index keys.
+# Sorts the keys according to index-sorting rules.
+# Removes keys with a 0x01 token. (duplicates?)
+# Builds a string to go to the index file.
+# Adds the index entries to the string if they belong in this index.
+# Keeps track of which index is being worked on, so only the proper entries
+# are included.
+# Places the index just built in to the output at the proper place.
+{ my $index_number = 0;
+sub add_real_idx {
+ print "\nDoing the index ... Index Number $index_number\n";
+ local($key, @keys, $next, $index, $old_key, $old_html);
+ my ($idx_ref,$keyref);
+ # RRM, 15.6.96: index constructed from %printable_key, not %index
+ @keys = keys %printable_key;
+
+ while (/$idx_mark/) {
+ # Get the index reference from what follows the $idx_mark and
+ # remove it from the string.
+ s/$idxmark\002(.*?)\002/$idxmark/;
+ $idx_ref = $1;
+ $index = '';
+ # include non- makeidx index-entries
+ foreach $key (keys %index) {
+ next if $printable_key{$key};
+ $old_key = $key;
+ if ($key =~ s/###(.*)$//) {
+ next if $printable_key{$key};
+ push (@keys, $key);
+ $printable_key{$key} = $key;
+ if ($index{$old_key} =~ /HREF="([^"]*)"/i) {
+ $old_html = $1;
+ $old_html =~ /$dd?([^#\Q$dd\E]*)#/;
+ $old_html = $1;
+ } else { $old_html = '' }
+ $index{$key} = $index{$old_key} . $old_html."</A>\n | ";
+ };
+ }
+ @keys = sort makeidx_keysort @keys;
+ @keys = grep(!/\001/, @keys);
+ my $cnt = 0;
+ foreach $key (@keys) {
+ my ($keyref) = $key =~ /.*\002(.*)/;
+ next unless ($idx_ref eq $keyref); # KEC.
+ $index .= &add_idx_key($key);
+ $cnt++;
+ }
+ print "$cnt Index Entries Added\n";
+ $index = '<DD>'.$index unless ($index =~ /^\s*<D(D|T)>/);
+ $index_number++; # KEC.
+ if ($SHORT_INDEX) {
+ print "(compact version with Legend)";
+ local($num) = ( $index =~ s/\<D/<D/g );
+ if ($num > 50 ) {
+ s/$idx_mark/$preindex<HR><DL>\n$index\n<\/DL>$preindex/o;
+ } else {
+ s/$idx_mark/$preindex<HR><DL>\n$index\n<\/DL>/o;
+ }
+ } else {
+ s/$idx_mark/<DL COMPACT>\n$index\n<\/DL>/o; }
+ }
+}
+}
+
+# KEC. Copied from latex2html.pl and modified to support multiple indices.
+# The bibliography and the index should be treated as separate sections
+# in their own HTML files. The \bibliography{} command acts as a sectioning command
+# that has the desired effect. But when the bibliography is constructed
+# manually using the thebibliography environment, or when using the
+# theindex environment it is not possible to use the normal sectioning
+# mechanism. This subroutine inserts a \bibliography{} or a dummy
+# \textohtmlindex command just before the appropriate environments
+# to force sectioning.
+sub add_bbl_and_idx_dummy_commands {
+ local($id) = $global{'max_id'};
+
+ s/([\\]begin\s*$O\d+$C\s*thebibliography)/$bbl_cnt++; $1/eg;
+ ## if ($bbl_cnt == 1) {
+ s/([\\]begin\s*$O\d+$C\s*thebibliography)/$id++; "\\bibliography$O$id$C$O$id$C $1"/geo;
+ #}
+ $global{'max_id'} = $id;
+ # KEC. Modified to global substitution to place multiple index tokens.
+ s/[\\]begin\s*($O\d+$C)\s*theindex/\\textohtmlindex$1/go;
+ # KEC. Modified to pick up the optional argument to \printindex
+ s/[\\]printindex\s*(\[.*?\])?/
+ do { (defined $1) ? "\\textohtmlindex $1" : "\\textohtmlindex []"; } /ego;
+ &lib_add_bbl_and_idx_dummy_commands() if defined(&lib_add_bbl_and_idx_dummy_commands);
+}
+
+# KEC. Copied from latex2html.pl and modified to support multiple indices.
+# For each textohtmlindex mark found, determine the index titles and headers.
+# We place the index ref in the header so the proper index can be generated later.
+# For the default index, the index ref is blank.
+#
+# One problem is that this routine is called twice.. Once for processing the
+# command as originally seen, and once for processing the command when
+# doing the name for the index file. We can detect that by looking at the
+# id numbers (or ref) surrounding the \theindex command, and not incrementing
+# index_number unless a new id (or ref) is seen. This has the side effect of
+# having to unconventionally start the index_number at -1. But it works.
+#
+# Gets the title from the list of indices.
+# If this is the first index, save the title in $first_idx_file. This is what's referenced
+# in the navigation buttons.
+# Increment the index_number for next time.
+# If the indexname command is defined or a newcommand defined for indexname, do it.
+# Save the index TITLE in the toc
+# Save the first_idx_file into the idxfile. This goes into the nav buttons.
+# Build index_labels if needed.
+# Create the index headings and put them in the output stream.
+
+{ my $index_number = 0; # Will be incremented before use.
+ my $first_idx_file; # Static
+ my $no_increment = 0;
+
+sub do_cmd_textohtmlindex {
+ local($_) = @_;
+ my ($idxref,$idxnum,$index_name);
+
+ # We get called from make_name with the first argument = "\001noincrement". This is a sign
+ # to not increment $index_number the next time we are called. We get called twice, once
+ # my make_name and once by process_command. Unfortunately, make_name calls us just to set the name
+ # but doesn't use the result so we get called a second time by process_command. This works fine
+ # except for cases where there are multiple indices except if they aren't named, which is the case
+ # when the index is inserted by an include command in latex. In these cases we are only able to use
+ # the index number to decide which index to draw from, and we don't know how to increment that index
+ # number if we get called a variable number of times for the same index, as is the case between
+ # making html (one output file) and web (multiple output files) output formats.
+ if (/\001noincrement/) {
+ $no_increment = 1;
+ return;
+ }
+
+ # Remove (but save) the index reference
+ s/^\s*\[(.*?)\]/{$idxref = $1; "";}/e;
+
+ # If we have an $idxref, the index name was specified. In this case, we have all the
+ # information we need to carry on. Otherwise, we need to get the idxref
+ # from the $index_number and set the name to "Index".
+ if ($idxref) {
+ $index_name = $indices{'title'}{$idxref};
+ } else {
+ if (defined ($idxref = $indices{'newcmdorder'}->[$index_number])) {
+ $index_name = $indices{'title'}{$idxref};
+ } else {
+ $idxref = '';
+ $index_name = "Index";
+ }
+ }
+
+ $idx_title = "Index"; # The name displayed in the nav bar text.
+
+ # Only set $idxfile if we are at the first index. This will point the
+ # navigation panel to the first index file rather than the last.
+ $first_idx_file = $CURRENT_FILE if ($index_number == 0);
+ $idxfile = $first_idx_file; # Pointer for the Index button in the nav bar.
+ $toc_sec_title = $index_name; # Index link text in the toc.
+ $TITLE = $toc_sec_title; # Title for this index, from which its filename is built.
+ if (%index_labels) { &make_index_labels(); }
+ if (($SHORT_INDEX) && (%index_segment)) { &make_preindex(); }
+ else { $preindex = ''; }
+ local $idx_head = $section_headings{'textohtmlindex'};
+ local($heading) = join(''
+ , &make_section_heading($TITLE, $idx_head)
+ , $idx_mark, "\002", $idxref, "\002" );
+ local($pre,$post) = &minimize_open_tags($heading);
+ $index_number++ unless ($no_increment);
+ $no_increment = 0;
+ join('',"<BR>\n" , $pre, $_);
+}
+}
+
+# Returns an index key, given the key passed as the first argument.
+# Not modified for multiple indices.
+sub add_idx_key {
+ local($key) = @_;
+ local($index, $next);
+ if (($index{$key} eq '@' )&&(!($index_printed{$key}))) {
+ if ($SHORT_INDEX) { $index .= "<DD><BR>\n<DT>".&print_key."\n<DD>"; }
+ else { $index .= "<DT><DD><BR>\n<DT>".&print_key."\n<DD>"; }
+ } elsif (($index{$key})&&(!($index_printed{$key}))) {
+ if ($SHORT_INDEX) {
+ $next = "<DD>".&print_key."\n : ". &print_idx_links;
+ } else {
+ $next = "<DT>".&print_key."\n<DD>". &print_idx_links;
+ }
+ $index .= $next."\n";
+ $index_printed{$key} = 1;
+ }
+
+ if ($sub_index{$key}) {
+ local($subkey, @subkeys, $subnext, $subindex);
+ @subkeys = sort(split("\004", $sub_index{$key}));
+ if ($SHORT_INDEX) {
+ $index .= "<DD>".&print_key unless $index_printed{$key};
+ $index .= "<DL>\n";
+ } else {
+ $index .= "<DT>".&print_key."\n<DD>" unless $index_printed{$key};
+ $index .= "<DL COMPACT>\n";
+ }
+ foreach $subkey (@subkeys) {
+ $index .= &add_sub_idx_key($subkey) unless ($index_printed{$subkey});
+ }
+ $index .= "</DL>\n";
+ }
+ return $index;
+}
+
+1; # Must be present as the last line.
--- /dev/null
+/* Century Schoolbook font is very similar to Computer Modern Math: cmmi */
+.MATH { font-family: "Century Schoolbook", serif; }
+.MATH I { font-family: "Century Schoolbook", serif; font-style: italic }
+.BOLDMATH { font-family: "Century Schoolbook", serif; font-weight: bold }
+
+/* implement both fixed-size and relative sizes */
+SMALL.XTINY { font-size : xx-small }
+SMALL.TINY { font-size : x-small }
+SMALL.SCRIPTSIZE { font-size : smaller }
+SMALL.FOOTNOTESIZE { font-size : small }
+SMALL.SMALL { }
+BIG.LARGE { }
+BIG.XLARGE { font-size : large }
+BIG.XXLARGE { font-size : x-large }
+BIG.HUGE { font-size : larger }
+BIG.XHUGE { font-size : xx-large }
+
+/* heading styles */
+H1 { }
+H2 { }
+H3 { }
+H4 { }
+H5 { }
+
+/* mathematics styles */
+DIV.displaymath { } /* math displays */
+TD.eqno { } /* equation-number cells */
+
+
+/* document-specific styles come next */
--- /dev/null
+%%
+%%
+%% The following characters must be preceded by a backslash
+%% to be entered as printable characters:
+%%
+%% # $ % & ~ _ ^ \ { }
+%%
+
+\documentclass[11pt,a4paper]{book}
+\usepackage{html}
+\usepackage{float}
+\usepackage{graphicx}
+\usepackage{bacula}
+\usepackage{longtable}
+\usepackage{makeidx}
+\usepackage{index}
+\usepackage{setspace}
+\usepackage{hyperref}
+\usepackage{url}
+
+
+\makeindex
+\newindex{dir}{ddx}{dnd}{Director Index}
+\newindex{fd}{fdx}{fnd}{File Daemon Index}
+\newindex{sd}{sdx}{snd}{Storage Daemon Index}
+\newindex{console}{cdx}{cnd}{Console Index}
+\newindex{general}{idx}{ind}{General Index}
+
+\sloppy
+
+\begin{document}
+\sloppy
+
+\newfont{\bighead}{cmr17 at 36pt}
+\parskip 10pt
+\parindent 0pt
+
+\title{\includegraphics{./bacula-logo.eps} \\ \bigskip
+ \Huge{Bacula Installation and Configuration Guide}
+ \begin{center}
+ \large{It comes in the night and sucks
+ the essence from your computers. }
+ \end{center}
+}
+
+
+\author{Kern Sibbald}
+\date{\vspace{1.0in}\today \\
+ This manual documents Bacula version \input{version} \\
+ \vspace{0.2in}
+ Copyright \copyright 1999-2007, Free Software Foundation Europe
+ e.V. \\
+ \vspace{0.2in}
+ Permission is granted to copy, distribute and/or modify this document under the terms of the
+ GNU Free Documentation License, Version 1.2 published by the Free Software Foundation;
+ with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+ A copy of the license is included in the section entitled "GNU Free Documentation License".
+}
+
+\maketitle
+
+\clearpage
+\tableofcontents
+\clearpage
+\listoffigures
+\clearpage
+\listoftables
+\clearpage
+
+\include{quickstart}
+\include{installation}
+\include{critical}
+\include{configure}
+\include{dirdconf}
+\include{filedconf}
+\include{storedconf}
+\include{messagesres}
+\include{consoleconf}
+\include{monitorconf}
+\include{security}
+\include{fdl}
+
+
+% The following line tells link_resolver.pl to not include these files:
+% nolinks developersi baculai-dir baculai-fd baculai-sd baculai-console baculai-main
+
+% pull in the index
+\clearpage
+\printindex[general]
+\printindex[dir]
+\printindex[fd]
+\printindex[sd]
+\printindex[console]
+
+\end{document}
--- /dev/null
+%%
+%%
+
+\chapter{Installer Bacula}
+\label{_ChapterStart17}
+\index[general]{Installer Bacula }
+\index[general]{Bacula!Installer }
+\addcontentsline{toc}{section}{Installer Bacula}
+
+\section{Pr\'erequis}
+\index[general]{Pr\'erequis }
+\addcontentsline{toc}{section}{Pr\'erequis}
+
+En g\'en\'eral, il vous faudra les sources de la version courante de Bacula,
+et si vous souhaitez ex\'ecuter un client Windows, vous aurez besoin de la
+version binaire du client Bacula pour Windows. Par ailleurs, Bacula a besoin
+de certains paquetages externes (tels {\bf SQLite}, {\bf MySQL} ou {\bf
+PostgreSQL}) pour compiler correctement en accord avec les options que vous
+aurez choisies. Pour vous simplifier la t\^ache, nous avons combin\'e
+plusieurs de ces programmes dans deux paquetages {\bf depkgs} (paquetages de
+d\'ependances). Ceci peut vous simplifier la vie en vous fournissant tous les
+paquets n\'ecessaires plut\^ot que de vous contraindre \`a les trouver sur la
+Toile, les charger et installer.
+
+\section{Distribution des fichiers source}
+\index[general]{fichiers source}
+\index[general]{distrribution fichiers}
+\addcontentsline{toc}{section}{Distribution des fichiers source}
+A partir de la version 1.38.0, le code source est \'eclat\'e en quatre
+fichiers tar correspondant \`a quatre modules diff\'erents dans le CVS
+Bacula. Ces fichiers sont :
+
+\begin{description}
+\item [bacula-1.38.0.tar.gz]
+ Il s'agit de la distribution primaire de Bacula. Pour chaque nouvelle
+ version, le num\'ero de version (ici, 1.38.0) sera mise \`a jour.
+
+\item [bacula-docs-1.38.0.tar.gz]
+ Ce fichier contient une copie du r\'epertoire docs, avec les documents
+ pr\'e-construits : R\'epertoire html anglais, fichier html unique et
+ fichier pdf. Les traductions allemande et fran\c {c}aise sont en cours mais
+ ne sont pas pr\'e-construites.
+
+\item [bacula-gui-1.38.0.tar.gz]
+ Ce fichier contient les programmes graphique en dehors du coeur
+ de l'application. Actuellement, il contient bacula-web, un programme
+ PHP pour produire une vue d'ensemble des statuts de vos jobs
+ Bacula consultable dans un navigateur ; et bimagemgr, un programme
+ qui permet de graver des images de CDROMS depuis un navigateur avec
+ les volumes Bacula.
+
+\item [bacula-rescue-1.8.1.tar.gz]
+ Ce fichier contient le code du CDROM de secours Bacula. Notez
+ que le num\'ero de version de ce paquetage n'est pas li\'e \`a celui
+ de Bacula. En utilisant ce code, vous pouvez graver un CDROM contenant
+ la configuration de votre syst\`eme et une version statiquement li\'ee du
+ File Daemon. Ceci peut vous permettre de repartitionner et reformater
+ ais\'ement vos disques durs et de recharger votre syst\`eme avec Bacula
+ en cas de d\'efaillance du disque dur.
+
+\item [winbacula-1.38.0.exe]
+ Ce fichier est l'installeur 32 bits Windows pour l'installation du
+ client Windows (File Daemon) sur une machine Windows.
+ A partir de la version 1.39.20, cet exécutable contiendra aussi
+ le Director Win32 et le Storage Daemon Win32.
+\end{description}
+
+\label{upgrading1}
+
+\section{Mettre Bacula \`a jour}
+\index[general]{Mettre Bacula \`a jour }
+\index[general]{Jour!Mettre Bacula \`a }
+\addcontentsline{toc}{section}{Mettre Bacula \`a jour}
+
+Si vous faites une mise \`a jour de Bacula, vous devriez d'abord lire
+attentivement les ReleaseNotes de toutes les versions entre votre version
+install\'ee et celle vers laquelle vous souhaitez mettre \`a jour. Si la base
+de donn\'ees du catalogue a \'et\'e mise \`a jour (c'est presque toujours le cas
+à chaque nouvelle version majeure), vous devrez soit
+r\'einitialiser votre base de donn\'ees et repartir de z\'ero, soit en
+sauvegarder une copie au format ASCII avant de proc\'eder \`a sa mise \`a
+jour. Ceci est normalement fait lorsque Bacula est compil\'e et install\'e par :
+
+\begin{verbatim}
+cd <installed-scripts-dir> (default /etc/bacula)
+./update_bacula_tables
+\end{verbatim}
+
+Ce script de mise \`a jour peut aussi \^etre trouv\'e dans le r\'epertoire
+src/cats des sources de Bacula.
+
+S'il y a eu plusieurs mises \`a jour de la base de donn\'ees entre votre
+version et celle vers laquelle vous souhaitez \'evoluer, il faudra appliquer
+chaque script de mise \`a jour de base de donn\'ees. Vous pouvez trouver tous
+les anciens scripts de mise \`a jour dans le r\'epertoire {\bf upgradedb} des
+sources de Bacula. Il vous faudra \'editer ces scripts pour qu'ils
+correspondent \`a votre configuration. Le script final, s'il y en a un, sera
+dans le r\'epertoire {\bf src/cats} comme indiqu\'e dans la ReleaseNote.
+
+Si vous migrez d'une version majeure vers une autre, vous devrez remplacer
+tous vos composants ({\it daemons}) en m\^eme temps car, g\'en\'eralement, le
+protocole inter-{\it daemons} aura chang\'e. Par contre, entre deux versions
+mineures d'une m\^eme majeure (par exemple les versions 1.32.x), \`a moins
+d'un bug, le protocole inter-{\it daemons} ne changera pas. Si cela vous
+semble confus, lisez simplement les ReleaseNotes tr\`es attentivement, elles
+signaleront si les {\it daemons} doivent \^etre mis \`a jour simultan\'ement.
+
+Enfin, notez qu'il n'est g\'en\'eralement pas n\'ecessaire d'utiliser
+{\bf make uninstall} avant de proc\'eder \`a une mise \`a jour. En fait, si vous le
+faites vous effacerez probablement vos fichiers de configuration, ce qui
+pourrait \^etre d\'esastreux. La proc\'edure normale de mise \`a jour est simplement :
+\begin{verbatim}
+./configure (your options)
+make
+make install
+\end{verbatim}
+
+ En principe, aucun de vos fichiers .conf ou .sql ne devrait \^etre \'ecras\'e,
+ et vous devez exécuter les deux commandes {\bf make} et {\bf make install}.
+ {\bf make install} sans un {\bf make} préalable ne fonctionnera pas.
+
+Pour plus d'informations sur les mises \`a jour, veuillez consulter la partie
+\ilink{Upgrading Bacula Versions}{upgrading} du chapitre Astuces de ce manuel
+
+\section{Paquetage de D\'ependences}
+\label{Dependency}
+\index[general]{Paquetage de D\'ependences}
+\index[general]{Paquetage!D\'ependences}
+\addcontentsline{toc}{section}{Paquetage de D\'ependences}
+
+Comme nous l'\'evoquions plus haut, nous avons combin\'e une s\'erie de
+programmes dont Bacula peut avoir besoin dans les paquets {\bf depkgs} et {\bf
+depkgs1}. Vous pouvez, bien sur, obtenir les paquets les plus r\'ecents
+directement des auteurs. Le fichier README dans chaque paquet indique o\`u les
+trouver. Pourtant, il faut noter que nous avons test\'e la compatibilit\'e des
+paquets contenus dans les fichiers depkgs avec Bacula.
+
+Vous pouvez, bien sur, obtenir les dernieres versions de ces paquetages de
+leurs auteurs. Les r\'ef\'erences n\'ecessaires figurent dans le README de
+chaque paquet. Quoi qu'il en soit, soyez conscient du fait que nous avons
+test\'e la compatibilit\'e des paquetages des fichiers depkgs.
+
+Typiquement, un paquetage de d\'ependances sera nomm\'e {\bf
+depkgs-ddMMMyy.tar.gz} et {\bf depkgs1-ddMMMyy.tar.gz} o\`u {\bf dd} est le
+jour o\`u n'ous l'avons publi\'e, {\bf MMM} l'abbr\'eviation du mois et {\bf
+yy} l'ann\'ee. Par exemple: {\bf depkgs-07Apr02.tar.gz}. Pour installer et
+construire ce paquetage (s'il est requis), vous devez:
+
+\begin{enumerate}
+\item Cr\'eer un r\'epertoire {\bf bacula}, dans lequel vous placerez les
+ sources de Bacula et le paquetage de d\'ependances.
+\item D\'esarchiver le {\bf depkg} dans le r\'epertoire {\bf bacula}.
+\item vous d\'eplacer dans le r\'epertoire obtenu: cd bacula/depkgs
+\item ex\'ecuter make
+ \end{enumerate}
+
+La composition exacte des paquetages de d\'ependance est susceptible de
+changer de temps en temps, voici sa composition actuelle :
+
+\begin{longtable}{|l|l|l|}
+ \hline
+\multicolumn{1}{|c| }{\bf Paquets externes } & \multicolumn{1}{c| }{\bf depkgs
+} & \multicolumn{1}{c| }{\bf depkgs1 } \\
+ \hline
+{SQLite } & \multicolumn{1}{c| }{X } & \multicolumn{1}{c| }{- } \\
+ \hline
+{SQLite3 } & \multicolumn{1}{c| }{X } & \multicolumn{1}{c| }{- } \\
+ \hline
+{mtx } & \multicolumn{1}{c| }{X } & \multicolumn{1}{c| }{- } \\
+ \hline
+{readline } & \multicolumn{1}{c| }{- } & \multicolumn{1}{c| }{X } \\
+ \hline
+{pthreads } & \multicolumn{1}{c| }{- } & \multicolumn{1}{c| }{- } \\
+ \hline
+{zlib } & \multicolumn{1}{c| }{- } & \multicolumn{1}{c| }{- } \\
+ \hline
+{wxWidgets } & \multicolumn{1}{c| }{- } & \multicolumn{1}{c| }{- } \\
+\hline
+
+\end{longtable}
+
+Notez que certains de ces paquets sont de taille respectable, si bien que
+l'\'etape de compilation peut prendre un certain temps. Les instructions
+ci-dessous construiront tous les paquets contenus dans le r\'epertoire.
+Cependant, la compilation de Bacula, ne prendra que les morceaux dont Bacula a
+effectivement besoin.
+
+Une alternative consiste \`a ne construire que les paquets n\'ecessaires. Par
+exemple,
+
+\footnotesize
+\begin{verbatim}
+cd bacula/depkgs
+make sqlite
+\end{verbatim}
+\normalsize
+
+configurera et construira SQLite et seulement SQLite.
+
+Vous devriez construire les paquets requis parmi {\bf depkgs} et/ou {\bf
+depkgs1} avant de configurer et compiler Bacula car Bacula en aura besoin
+d\`es la compilation.
+
+M\^eme si vous n'utilisez pas SQLite, vous pourriez trouver le paquet {\bf
+depkgs} pratique pour construire {\bf mtx} car le programme {\bf tapeinfo} qui
+vient avec peut souvent vous fournir de pr\'ecieuses informations sur vos
+lecteurs de bandes SCSI (e.g. compression, taille min/max des blocks,...).
+
+Le paquet {\bf depkgs-win32} est obsolète à partir de la version 1.39 de Bacula.
+Il était autrefois utilisé pour compiler le client natif Win32 qui est
+désormais construit sur Linux grâce à un mécanisme de compilation croisée.
+Tous les outils et librairies tierces sont automatiquement téléchargées
+par l'exécution de scripts apropriés. Lisez le fichier src/win32/README.mingw32
+pour plus de détails.
+
+\section{Syst\`emes Support\'es}
+\label{Systems}
+\index[general]{Syst\`emes Support\'es }
+\addcontentsline{toc}{section}{Syst\`emes Support\'es}
+
+Veuillez consulter la section
+\ilink{ Syst\`emes support\'es}{SupportedOSes} du chapitre
+D\'emarrer avec Bacula de ce manuel.
+
+\section{Construire Bacula \`a partir des sources}
+\label{Building}
+\index[general]{Construire Bacula \`a partir des sources }
+\index[general]{Sources!Construire Bacula \`a partir des }
+\addcontentsline{toc}{section}{Construire Bacula \`a partir des sources}
+
+L'installation basique est plut\^ot simple.
+
+\begin{enumerate}
+\item Installez et construisez chaque {\bf depkgs} comme indiqu\'e plus haut.
+
+
+\item Configurez et installez MySQL ou PostgreSQL (si vous le souhaitez):
+ \ilink{Installer et configurer MySQL Phase I}{_ChapterStart} ou
+ \ilink{Installer et configurer PostgreSQL Phase
+I}{_ChapterStart10}. Si vous installez depuis des rpms, et
+utilisez MySQL, veillez \`a installer {\bf mysql-devel}, afin que les
+fichiers d'en-t\^etes de MySQL soient disponibles pour la compilation de
+Bacula. De plus, la librairie client MySQL requi\`ert la librairie de
+compression gzip {\bf libz.a} ou {\bf libz.so}. Ces librairies sont dans le
+paquet {\bf libz-devel}. Sur Debian, vous devrez charger le paquet {\bf
+zlib1g-dev}. Si vous n'utilisez ni rpms, ni debs, il vous faudra trouver le
+paquetage adapt\'e \`a votre syst\`eme.
+
+Notez que si vous avez dej\`a MySQL
+ou PostgreSQL sur votre syst\`eme vous pouvez sauter cette phase pourvu que
+vous ayez construit "the thread safe libraries'' et que vous ayez d\'ej\`a
+install\'e les rpms additionnels sus-mentionn\'es.
+
+\item En alternative \`a MySQL et PostgreSQL, configurez et installez SQLite,
+ qui fait partie du paquetage {\bf depkgs}.
+ \ilink{Installer et configurer SQLite}{_ChapterStart33}.
+ SQLite n'est probablement pas adapt\'e \`a un environnement de production
+ de taille respectable, en raison de sa lenteur par rapport \`a MySQL, et de la
+ pauvret\'e de ses outils de reconstruction de base de donn\'ees endommag\'ee.
+
+\item D\'esarchivez les sources de Bacula, de pr\'ef\'erence dans le
+ r\'epertoire {\bf bacula} \'evoqu\'e ci-dessus.
+
+\item D\'eplacez-vous dans ce r\'epertoire.
+
+\item Ex\'ecutez ./configure (avec les options appropri\'ees comme d\'ecrit
+ ci-dessus)
+
+\item Examinez tr\`es attentivement la sortie de ./configure,
+ particuli\`erement les r\'epertoires d'installation des binaires et des
+ fichiers de configuration. La sortie de ./configure est stock\'ee dans le
+fichier {\bf config.out} et peut \^etre affich\'ee \`a volont\'e sans
+relancer ./configure par la commande {\bf cat config.out}.
+
+\item Vous pouvez relancer ./configure avec des options diff\'erentes apr\`es
+ une premi\`ere ex\'ecution, cela ne pose aucun probl\`eme, mais vous devriez
+ d'abord ex\'ecuter:
+
+\footnotesize
+\begin{verbatim}
+ make distclean
+\end{verbatim}
+\normalsize
+
+afin d'\^etre certain de repartir de z\'ero et d'\'eviter d'avoir un m\'elange
+avec vos premi\`eres options. C'est n\'ecessaire parce que ./configure met
+en cache une bonne partie des informations. {\bf make distclean} est aussi
+recommand\'e si vous d\'eplacez vos fichiers source d'une machine \`a une
+autre. Si {\bf make distclean} \'echoue, ignorez-le et continuez.
+
+\item make
+
+ Si vous obtenez des erreurs durant le {\it linking} dans le r\'epertoire du
+Storage Daemon (/etc/stored), c'est probablement parce que vous avez charg\'e
+la librairie statique sur votre syst\`eme. J'ai remarqu\'e ce probl\`eme sur
+un Solaris. Pour le corriger, assurez-vous de ne pas avoir ajout\'e l'option
+{\bf \verb{--{enable-static-tools} \`a la commande {\bf ./configure}.
+
+Si vous ignorez cette \'etape ({\bf make}) et poursuivez imm\'ediatement avec
+{\bf make install}, vous commettez deux erreurs s\'erieuses : d'abord, votre
+installation va \'echouer car Bacula a besoin d'un {\bf make} avant un
+{\bf make install} ; ensuite, vous vous privez de la possibilit\'e de vous
+assurer qu'il n'y a aucune erreur avant de commencer \`a \'ecrire les fichiers dans
+vos r\'epertoires syst\`eme.
+
+\item make install
+Avant de lancer cette commande, v\'erifiez consciencieusement que vous avez bien
+ex\'ecut\'e la commande {\bf make} et que tout a \'et\'e compil\'e proprement et li\'e
+sans erreur.
+
+\item Si vous \^etes un nouvel utilisateur de Bacula, nous vous recommandons
+ {\bf fortement} de sauter l'\'etape suivante et d'utiliser le fichier de
+ configuration par d\'efaut, puis d'ex\'ecuter le jeu d'exemples du prochain
+chapitre avant de revenir modifier vos fichier de configuration pour qu'ils
+satisfassent vos besoins.
+
+\item Modifiez les fichiers de configuration de chacun des trois {\it daemons}
+ (Directory, File, Storage) et celui de la Console. Pour plus de d\'etails,
+ consultez le chapitre
+\ilink{Fichiers de Configuration de Bacula}{_ChapterStart16} Nous
+vous recommandons de commencer par modifier les fichiers de configuration
+fournis par d\'efaut, en faisant les changements minima indispensables. Vous
+pourrez proc\'eder \`a une adaptation compl\`ete une fois que Bacula
+fonctionnera correctement. Veuillez prendre garde \`a modifier les mots de
+passe qui sont g\'en\'er\'es al\'eatoirement, ainsi que les noms car ils
+doivent s'accorder entre les fichiers de configuration pour des raisons de
+s\'ecurit\'e.
+
+\item Cr\'eez la base de donn\'ees Bacula MySQL et ses tables (si vous
+ utilisez MySQL)
+ \ilink{Installer et configurer MySQL Phase II}{mysql_phase2} ou
+cr\'eez la base de donn\'ees Bacula PostgreSQL et ses tables
+\ilink{Installer et configurer PostgreSQL Phase
+II}{PostgreSQL_phase2} (si vous utilisez PostgreSQL) ou
+encore
+\ilink{Installer et configurer SQLite Phase II}{phase2} (si vous
+utilisez SQLite)
+
+\item D\'emarrez Bacula ({\bf ./bacula start}) Notez: Le prochain chapitre
+ expose ces \'etapes en d\'etail.
+
+\item Lancez la Console pour communiquer avec Bacula.
+
+\item Pour les deux \'el\'ements pr\'ec\'edents, veuillez suivre les
+ instructions du chapitre
+ \ilink{Ex\'ecuter Bacula}{_ChapterStart1} o\`u vous ferez une
+simple sauvegarde et une restauration. Faites ceci avant de faire de lourdes
+modifications aux fichiers de configuration, ainsi vous serez certain que
+Bacula fonctionne, et il vous sera plus familier. Apr\`es quoi il vous sera
+plus facile de changer les fichiers de configuration.
+\item Si apr\`es l'installation de Bacula, vous d\'ecidez de le d\'eplacer,
+ c'est \`a dire de l'installer dans un jeu de r\'epertoires diff\'erents,
+ proc\'edez comme suit :
+
+\footnotesize
+\begin{verbatim}
+ make uninstall
+ make distclean
+ ./configure (vos-nouvelles-options)
+ make
+ make install
+
+\end{verbatim}
+\normalsize
+
+\end{enumerate}
+
+Si tout se passe bien, {\bf ./configure} d\'eterminera correctement votre
+syst\`eme et configurera correctement le code source. Actuellement, FreeBSD,
+Linux (RedHat), et Solaris sont support\'es. Des utilisateurs rapportent que
+le client Bacula fonctionne sur MacOS X 10.3 tant que le support readline est
+d\'esactiv\'e.
+
+Si vous installez Bacula sur plusieurs syst\`emes identiques, vous pouvez
+simplement transf\'erer le r\'epertoire des sources vers ces autres syst\`emes
+et faire un "make install''. Cependant s'il y a des diff\'erences dans les
+librairies, ou les versions de syst\`emes, ou si vous voulez installer sur un
+syst\`eme diff\'erent, vous devriez recommencer \`a partir de l'archive tar
+compress\'ee originale. Si vous transf\'erez un r\'epertoire de sources o\`u
+vous avez d\'ej\`a ex\'ecut\'e la commande ./configure, vous DEVEZ faire:
+
+\footnotesize
+\begin{verbatim}
+make distclean
+\end{verbatim}
+\normalsize
+
+avant d'ex\'ecuter \`a nouveau ./configure. Ceci est rendu n\'ecessaire par
+l'outil GNU autoconf qui met la configuration en cache, de sorte que si vous
+r\'eutilisez la configuration d'une machine Linux sur un Solaris, vous pouvez
+\^etre certain que votre compilation \'echouera. Pour l'\'eviter, comme
+mentionn\'e plus haut, recommencez depuis l'archive tar, ou faites un "make
+distclean''.
+
+En g\'en\'eral, vous voudrez probablement sophistiquer votre {\bf configure}
+pour vous assurer que tous les modules que vous souhaitez soient construits et
+que tout soit plac\'e dans les bons r\'epertoires.
+
+Par exemple, sur Fedora, RedHat ou SuSE, on pourrait utiliser ceci:
+
+\footnotesize
+\begin{verbatim}
+CFLAGS="-g -Wall" \
+ ./configure \
+ --sbindir=$HOME/bacula/bin \
+ --sysconfdir=$HOME/bacula/bin \
+ --with-pid-dir=$HOME/bacula/bin/working \
+ --with-subsys-dir=$HOME/bacula/bin/working \
+ --with-mysql \
+ --with-working-dir=$HOME/bacula/bin/working \
+ --with-dump-email=$USER
+\end{verbatim}
+\normalsize
+
+Notez: l'avantage de cette configuration pour commencer, est que tout sera mis
+dans un seul r\'epertoire, que vous pourrez ensuite supprimer une fois que
+vous aurez ex\'ecut\'e les exemples du prochain chapitre, et appris comment
+fonctionne Bacula. De plus, ceci peut \^etre install\'e et ex\'ecut\'e sans
+\^etre root.
+
+Pour le confort des d\'eveloppeurs, j'ai ajout\'e un script {\bf
+defaultconfig} au r\'epertoire {\bf examples}. Il contient les r\'eglages que
+vous devriez normalement utiliser, et chaque d\'eveloppeur/utilisateur devrait
+le modifier pour l'accorder \`a ses besoins. Vous trouverez d'autres exemples
+dans ce r\'epertoire.
+
+Les options {\bf \verb{--{enable-conio} ou {\bf \verb{--{enable-readline} sont utiles car
+elles conf\`erent un historique de lignes de commandes et des capacit\'es
+d'\'edition \`a la Console. Si vous avez inclus l'une ou l'autre option, l'un
+des deux paquets {\bf termcap} ou {\bf ncurses} sera n\'ecessaire pour
+compiler. Sur la plupart des syst\`emes, y compris RedHat et SuSE, vous
+devriez inclure le paquet ncurses. Si Le processus de configuration de
+Bacula le d\'etecte, il l'utilisera plut\^ot que la librairie termcap.
+Sur certains syst\`emes, tels que SUSE, la librairie termcap n'est
+pas dans le r\'epertoire standard des librairies par cons\'equent, l'option
+devrait \^etre d\'esactiv\'ee ou vous aurez un message tel que:
+
+\footnotesize
+\begin{verbatim}
+/usr/lib/gcc-lib/i586-suse-linux/3.3.1/.../ld:
+cannot find -ltermcap
+collect2: ld returned 1 exit status
+\end{verbatim}
+\normalsize
+
+lors de la compilation de la Console Bacula. Dans ce cas, il vous faudra
+placer la variable d'environnement {\bf LDFLAGS} avant de compiler.
+
+\footnotesize
+\begin{verbatim}
+export LDFLAGS="-L/usr/lib/termcap"
+\end{verbatim}
+\normalsize
+
+Les m\^emes contraintes de librairies s'appliquent si vous souhaitez utiliser
+les sous-programmes readlines pour l'\'edition des lignes de commande et
+l'historique, ou si vous utilisez une librairie MySQL qui requiert le
+chiffrement. Dans ce dernier cas, vous pouvez exporter les librairies
+additionnelles comme indiqu\'e ci-dessus ou, alternativement, les inclure
+directement en param\`etres de la commande ./configure comme ci-dessous :
+
+ \footnotesize
+ \begin{verbatim}
+ LDFLAGS="-lssl -lcyrpto" \
+ ./configure <vos-options>
+ \end{verbatim}
+\normalsize
+
+
+Veuillez noter que sur certains syst\`emes tels que Mandriva, readline tend
+\`a "avaler'' l'invite de commandes, ce qui le rend totalement inutile. Si
+cela vous arrive, utilisez l'option "disable'', ou si vous utilisez une
+version post\'erieure \`a 1.33 essayez {\bf \verb{--{enable-conio} pour utiliser une
+alternative \`a readline int\'egr\'ee. Il vous faudra tout de m\^eme termcap
+ou ncurses, mais il est peu probable que le paquetage {\bf conio} gobe vos
+invites de commandes.
+
+Readline n'est plus support\'e depuis la version 1.34. Le code reste
+disponible, et si des utilisateurs soumettent des patches, je serai heureux de
+les appliquer. Cependant, \'etant donn\'e que chaque version de readline
+semble incompatible avec les pr\'ec\'edentes, et qu'il y a des diff\'erences
+significatives entre les syst\`emes, je ne puis plus me permettre de le
+supporter.
+
+\section{Quelle base de donn\'ees utiliser ?}
+\label{DB}
+\index[general]{Utiliser!Quelle base de donn\'ees }
+\index[general]{Quelle base de donn\'ees utiliser ? }
+\addcontentsline{toc}{section}{Quelle base de donn\'ees utiliser ?}
+
+Avant de construire Bacula, vous devez d\'ecider si vous voulez utiliser
+SQLite, MySQL ou PostgreSQL. Si vous n'avez pas d\'ej\`a MySQL ou PostgreSQL
+sur votre machine, nous vous recommandons de d\'emarrer avec SQLite. Ceci vous
+facilitera beaucoup l'installation car SQLite est compil\'e dans Bacula et ne
+requiert aucune administration. SQLite fonctionne bien et sied bien aux
+petites et moyennes configurations (maximum 10-20 machines). Cependant, il nous
+faut signaler que plusieurs utilisateurs ont subi des corruptions inexpliqu\'ees
+de leur catalogue SQLite. C'est pourquoi nous recommandons de choisir MySQL
+ou PostgreSQL pour une utilisation en production.
+
+Si vous souhaitez utiliser MySQL pour votre catalogue Bacula, consultez le
+chapitre
+\ilink{Installer et Configurer MySQL}{_ChapterStart} de ce manuel.
+Vous devrez installer MySQL avant de poursuivre avec la configuration de
+Bacula. MySQL est une base de donn\'ees de haute qualit\'e tr\`es efficace et
+qui convient pour des configurations de toutes tailles. MySQL est
+l\'eg\`erement plus complexe \`a installer et administrer que SQLite en raison
+de ses nombreuses fonctions sophistiqu\'ees telles que userids et mots de
+passe. MySQL fonctionne en tant que processus distinct, est r\'eellement une
+solution professionnelle et peut prendre en charge des bases de donn\'ees de
+dimension quelconque.
+
+Si vous souhaitez utiliser PostgreSQL pour votre catalogue Bacula, consultez
+le chapitre
+\ilink{Installer et Configurer PostgreSQL}{_ChapterStart10} de ce
+manuel. Vous devrez installer PostgreSQL avant de poursuivre avec la
+configuration de Bacula. PostgreSQL est tr\`es similaire \`a MySQL bien que
+tendant \`a \^etre un peu plus conforme \`a SQL92. PostgreSQL poss\`ede
+beaucoup plus de fonctions avanc\'ees telles que les transactions, les
+proc\'edures stock\'ees, etc. PostgreSQL requiert une certaine connaissance
+pour son installation et sa maintenance.
+
+Si vous souhaitez utiliser SQLite pour votre catalogue Bacula, consultez le
+chapitre
+\ilink{Installer et Configurer SQLite}{_ChapterStart33} de ce manuel.
+
+\section{D\'emarrage rapide}
+\index[general]{D\'emarrage rapide }
+\index[general]{Rapide!D\'emarrage }
+\addcontentsline{toc}{section}{D\'emarrage rapide}
+
+Il y a de nombreuses options et d'importantes consid\'erations donn\'ees
+ci-dessous que vous pouvez passer pour le moment si vous n'avez eu aucun
+probl\`eme lors de la compilation de Bacula avec une configuration
+simplifi\'ee comme celles montr\'ees plus haut.
+
+Si le processus ./configure ne parvient pas \`a trouver les librairies
+sp\'ecifiques (par exemple libintl), assurez vous que le paquetage appropri\'e
+est install\'e sur votre syst\`eme. S'il est install\'e dans un r\'epertoire non
+standard (au moins pour Bacula), il existe dans la plupart des cas une
+option parmi celles \'enum\'er\'ees ci-dessous (ou avec "./configure {-}{-}help")
+qui vous permettra de sp\'ecifier un r\'epertoire de recherche. D'autres options
+vous permettent de d\'esactiver certaines fonctionnalit\'es (par exemple
+{-}{-}disable-nls).
+
+Si vous souhaitez vous jeter \`a l'eau, nous vous conseillons de passer
+directement au chapitre suivant, et d'ex\'ecuter le jeu d'exemples. Il vous
+apprendra beaucoup sur Bacula, et un Bacula de test peut \^etre install\'e
+dans un unique r\'epertoire (pour une destruction ais\'ee) et ex\'ecut\'e sans
+\^etre root. Revenez lire les d\'etails de ce chapitre si vous avez un
+quelconque probl\`eme avec les exemples, ou lorsque vous voudrez effectuer une
+installation r\'eelle.
+
+TAQUET MISE A JOUR
+
+\section{Options de la commande {\bf configure}}
+\label{Options}
+\index[general]{Options de la commande configure }
+\index[general]{Configure!Options de la commande }
+\addcontentsline{toc}{section}{Options de la commande configure}
+
+Les options en ligne de commande suivantes sont disponibles pour {\bf
+configure} afin d'adapter votre installation \`a vos besoins.
+
+\begin{description}
+
+\item [{-}{-}sysbindir=\lt{}binary-path\gt{}]
+ \index[dir]{{-}{-}sysbindir }
+ D\'efinit l'emplacement des binaires Bacula.
+
+\item [{-}{-}sysconfdir=\lt{}config-path\gt{}]
+ \index[dir]{{-}{-}sysconfdir }
+ D\'efinit l'emplacement des fichiers de configuration de Bacula.
+
+\item [ {-}{-}mandir=\lt{}path\gt{}]
+ \index[general]{{-}{-}mandir}
+ Notez qu'\`a partir de la version 1.39.14, tout chemin sp\'ecifi\'e
+ est d\'esormais compris comme le niveau le plus \'elev\'e du
+ r\'epertoire man. Pr\'ec\'edemment, le {\bf mandir} sp\'ecifiait le
+ chemin absolu o\`u vous souhaitiez instaler les pages de manuel.
+ Les fichiers man sont install\'es au format gzipp\'e sous
+ mandir/man1 et mandir/man8 comme il convient.
+ Pour que l'installation se d\'eroule normalement, vous devez
+ disposer de {\bf gzip} sur votre syst\`eme
+
+ Par d\'efaut, Bacula installe une simple page de manuel dans
+ /usr/share/man. Si vous voulez qu'elle soit install\'ee ailleurs,
+ utilisez cette options pour sp\'ecifier le chemin voulu. Notez
+ que les principaux documents Bacula en HTML et PDF sont dans une
+ archive tar distincte des sources de distribution de Bacula.
+
+\item [ {-}{-}datadir=\lt{}path\gt{}]
+ \index[general]{{-}{-}datadir}
+ Si vous traduisez Bacula ou des parties de Bacula dans une autre
+ langue, vous pouvez sp\'ecifier l'emplacement des fichiers .po avec
+ l'option {\bf {-}{-}datadir}. Vous devez installer manuellement tout
+ fichier .po qui n'est pas (encore) install\'e automatiquement.
+
+\item [{-}{-}enable-smartalloc ]
+ \index[dir]{{-}{-}enable-smartalloc }
+ Permet l'inclusion du code Smartalloc de d\'etection de tampons orphelins
+(NDT : orphaned buffer). Cette option est vivement recommand\'ee. Nous n'avons
+jamais compil\'e sans elle, aussi vous pourriez subir des d\'esagr\'ements si
+vous ne l'activez pas. Dans ce cas, r\'eactivez simplement cette option. Nous
+la recommandons car elle aide \`a d\'etecter les fuites de m\'emoire. Ce
+param\`etre est utilis\'e lors de la compilation de Bacula.
+
+\item [{-}{-}enable-gnome ]
+ \index[dir]{{-}{-}enable-gnome }
+ Si vous avez install\'e GNOME sur votre ordinateur, vous devez sp\'ecifier
+cette option pour utiliser la Console graphique GNOME. Vous trouverez les
+binaires dans le r\'epertoire {\bf src/gnome-console}.
+
+\item [{-}{-}enable-bwx-console ]
+ \index[general]{{-}{-}enable-bwx-console }
+ Si vous avez install\'e wxWidgets sur votre ordinateur, vous devez
+sp\'ecifier cette option pour utiliser la Console graphique bwx-console. Vous
+trouverez les binaires dans le r\'epertoire {\bf src/wx-console}. Ceci peut
+\^etre utile aux utilisateurs qui veulent une Console graphique, mais ne
+souhaitent pas installer Gnome, car wxWidgets peut fonctionner avec les
+librairies GTK+, Motif ou m\^eme X11.
+
+\item [{-}{-}enable-tray-monitor ]
+ \index[general]{{-}{-}enable-tray-monitor }
+ Si vous avez install\'e GTK sur votre ordinateur et utilisez un gestionnaire
+de fen\^etre compatible avec le syst\`eme de notification standard FreeDesktop
+(tels KDE et GNOME), vous pouvez utiliser une interface graphique pour
+surveiller les {\it daemons} Bacula en activant cette option. Les binaires
+seront plac\'es dans le r\'epertoire {\bf src/tray-monitor}.
+
+\item [{-}{-}enable-static-tools]
+ \index[general]{{-}{-}enable-static-tools }
+ Avec cette option, les utilitaires relatifs au Storage Daemon ({\bf bls},
+{\bf bextract}, et {\bf bscan}) seront li\'es statiquement, ce qui vous permet
+de les utiliser m\^eme si les librairies partag\'ees ne sont pas charg\'ees.
+Si vous avez des difficult\'es de type "linking'' \`a la compilation du
+r\'epertoire {\bf src/stored}, assurez-vous d'avoir d\'esactiv\'e cette
+option, en ajoutant \'eventuellement {\bf \verb{--{disable-static-tools}.
+
+\item [{-}{-}enable-static-fd]
+ \index[fd]{{-}{-}enable-static-fd }
+ Avec cette option, la compilation produira un {\bf static-bacula-fd} en plus
+du File Daemon standard. Cette version qui inclut les librairies statiquement
+li\'ees est requise pour la reconstruction compl\`ete d'une machine apr\`es
+un d\'esastre. Cette option est largement surpass\'ee par l'usage de {\bf
+make static-bacula-fd} du r\'epertoire {\bf src/filed}. L'option {\bf
+\verb:--:enable-client-only} d\'ecrite plus loin est aussi int\'eressante
+pour compiler un simple client sans les autres parties du programme.
+
+Pour lier un binaire statique, l'\'editeur de liens a besoin des versions
+statiques de toutes les librairies utilis\'ees, aussi les utilisateurs
+rencontrent fr\'equemment des erreurs d'\'edition de liens \`a l'utilisation
+de cette option. La premi\`ere chose \`a faire est de s'assurer d'avoir la
+librairie glibc statiquement li\'ee sur votre syst\`eme. Ensuite, il faut
+s'assurer de ne pas utiliser les options {\bf {-}{-}openssl} ou
+{\bf {-}{-}with-python} de la commande configure, car elle requierent des
+librairies suppl\'ementaires. Vous devriez pouvoir activer ces options, mais
+il vous faudra charger les librairies statiques additionnelles correspondantes.
+
+\item [{-}{-}enable-static-sd]
+ \index[sd]{{-}{-}enable-static-sd }
+ Avec cette option, la compilation produira un {\bf static-bacula-sd} en plus
+du Storage Daemon standard. Cette version qui inclut les librairies
+statiquement li\'ees peut se r\'ev\'eler utile pour la reconstruction
+compl\`ete d'une machine apr\`es un d\'esastre.
+
+Pour lier un binaire statique, l'\'editeur de liens a besoin des versions
+statiques de toutes les librairies utilis\'ees, aussi les utilisateurs
+rencontrent fr\'equemment des erreurs d'\'edition de liens \`a l'utilisation
+de cette option. La premi\`ere chose \`a faire est de s'assurer d'avoir la
+librairie glibc statiquement li\'ee sur votre syst\`eme. Ensuite, il faut
+s'assurer de ne pas utiliser les options {\bf {-}{-}openssl} ou
+{\bf {-}{-}with-python} de la commande configure, car elle requierent des
+librairies suppl\'ementaires. Vous devriez pouvoir activer ces options, mais
+il vous faudra charger les librairies statiques additionnelles correspondantes.
+
+\item [{-}{-}enable-static-dir]
+ \index[dir]{{-}{-}enable-static-dir }
+ Avec cette option, la compilation produira un {\bf static-bacula-dir} en plus
+du Director Daemon standard. Cette version qui inclut les librairies
+statiquement li\'ees peut se r\'ev\'eler utile pour la reconstruction
+compl\`ete d'une machine apr\`es un d\'esastre.
+
+Pour lier un binaire statique, l'\'editeur de liens a besoin des versions
+statiques de toutes les librairies utilis\'ees, aussi les utilisateurs
+rencontrent fr\'equemment des erreurs d'\'edition de liens \`a l'utilisation
+de cette option. La premi\`ere chose \`a faire est de s'assurer d'avoir la
+librairie glibc statiquement li\'ee sur votre syst\`eme. Ensuite, il faut
+s'assurer de ne pas utiliser les options {\bf {-}{-}openssl} ou
+{\bf {-}{-}with-python} de la commande configure, car elle requierent des
+librairies suppl\'ementaires. Vous devriez pouvoir activer ces options, mais
+il vous faudra charger les librairies statiques additionnelles correspondantes.
+
+\item [{-}{-}enable-static-cons]
+ \index[dir]{{-}{-}enable-static-cons }
+ Avec cette option, la compilation produira une {\bf static-console} et une
+{\bf static-gnome-console} en plus de la Console standard standard. Cette
+version qui inclut les librairies statiquement li\'ees peut se r\'ev\'eler
+utile pour la reconstruction compl\`ete d'une machine apr\`es un d\'esastre.
+
+Pour lier un binaire statique, l'\'editeur de liens a besoin des versions
+statiques de toutes les librairies utilis\'ees, aussi les utilisateurs
+rencontrent fr\'equemment des erreurs d'\'edition de liens \`a l'utilisation
+de cette option. La premi\`ere chose \`a faire est de s'assurer d'avoir la
+librairie glibc statiquement li\'ee sur votre syst\`eme. Ensuite, il faut
+s'assurer de ne pas utiliser les options {\bf {-}{-}openssl} ou
+{\bf {-}{-}with-python} de la commande configure, car elle requierent des
+librairies suppl\'ementaires. Vous devriez pouvoir activer ces options, mais
+il vous faudra charger les librairies statiques additionnelles correspondantes.
+
+\item [{-}{-}enable-client-only]
+ \index[general]{{-}{-}enable-client-only }
+ Avec cette option, la compilation produira seulement le File Daemon et les
+librairies qui lui sont n\'ecessaires. Aucun des autres {\it daemons}, outils
+de stockage, ni la console ne sera compil\'e. De m\^eme, un {\bf make
+install} installera seulement le File Daemon. Pour obtenir tous les {\it
+daemons}, vous devez la d\'esactiver. Cette option facilite grandement la
+compilation sur les simples clients.
+
+Pour lier un binaire statique, l'\'editeur de liens a besoin des versions
+statiques de toutes les librairies utilis\'ees, aussi les utilisateurs
+rencontrent fr\'equemment des erreurs d'\'edition de liens \`a l'utilisation
+de cette option. La premi\`ere chose \`a faire est de s'assurer d'avoir la
+librairie glibc statiquement li\'ee sur votre syst\`eme. Ensuite, il faut
+s'assurer de ne pas utiliser les options {\bf {-}{-}openssl} ou
+{\bf {-}{-}with-python} de la commande configure, car elle requierent des
+librairies suppl\'ementaires. Vous devriez pouvoir activer ces options, mais
+il vous faudra charger les librairies statiques additionnelles correspondantes.
+
+\item [ {-}{-}enable-build-dird]
+ \index[general]{{-}{-}enable-build-dird}
+Avec cette option activ\'ee (ce qui est le cas par d\'efaut), le processus make
+compile le Director ainsi que les outils du Director. Vous pouvez d\'esactiver
+la compilation du Director en utilisant {\bf {-}{-}disable-build-dird}.
+
+\item [ {-}{-}enable-build-stored]
+ \index[general]{{-}{-}enable-build-stored}
+Avec cette option activ\'ee (ce qui est le cas par d\'efaut), le processus make
+compile le Storage Daemon. Vous pouvez d\'esactiver
+la compilation du Storage Daemon en utilisant {\bf {-}{-}disable-build-stored}.
+
+\item [{-}{-}enable-largefile]
+ \index[general]{{-}{-}enable-largefile }
+ Cette option (activ\'ee par d\'efaut) provoque la compilation de Bacula avec
+le support d'adressage de fichiers 64 bits s'il est disponible sur votre
+syst\`eme. Ainsi Bacula peut lire et \'ecrire des fichiers de plus de 2
+GBytes. Vous pouvez d\'esactiver cette option et revenir \`a un adressage de
+fichiers 32 bits en utilisant {\bf \verb{--{disable-largefile}.
+
+\item [ {-}{-}disable-nls]
+ \index[general]{{-}{-}disable-nls}
+ Bacula utilise par d\'efaut les librairies {\it GNU Native Language Support} (NLS).
+ Sur certaines machines, ces librairies peuvent \^etre inexistante, ou ne pas
+ fonctionner correctement (particuli\`erement sur les impl\'ementations non Linux).
+ dans ce genre de situations, vous pouvez neutraliser l'utilisation de ces librairies
+ avec l'option {\bf {-}{-}disable-nls}. Dans ce cas, Bacula reviendra \`a l'usage de l'anglais.
+
+\item [{-}{-}with-sqlite=\lt{}sqlite-path\gt{}]
+ \index[general]{{-}{-}with-sqlite }
+ Cette option permet l'utilisation de la base de donn\'ees SQLite versions 2.8.x. Il n'est,
+en principe, pas n\'ecessaire de sp\'ecifier le chemin {\bf sqlite-path} car
+Bacula recherche les composants requis dans les r\'epertoires standards ({\bf
+depkgs/sqlite}). voyez
+\ilink{Installer et Configurer SQLite}{_ChapterStart33} pour plus de
+d\'etails.
+
+Voyez aussi la note ci-dessous, apr\`es le paragraphe --with-postgreSQL
+
+\item [{-}{-}with-sqlite3=\lt{}sqlite3-path\gt{}]
+ \index[general]{{-}{-}with-sqlite3 }
+ Cette option permet l'utilisation de la base de donn\'ees SQLite versions 3.x. Il n'est,
+en principe, pas n\'ecessaire de sp\'ecifier le chemin {\bf sqlite3-path} car
+Bacula recherche les composants requis dans les r\'epertoires standards ({\bf
+depkgs/sqlite3}). voyez
+\ilink{Installer et Configurer SQLite}{_ChapterStart33} pour plus de
+d\'etails.
+
+Voyez aussi la note ci-dessous, apr\`es le paragraphe --with-postgreSQL
+
+\item [{-}{-}with-mysql=\lt{}mysql-path\gt{}]
+ \index[general]{{-}{-}with-mysql }
+ Cette option permet la compilation des services de Catalogue de Bacula. Elle
+implique que MySQL tourne d\'ej\`a sur votre syst\`eme, et qu'il soit
+install\'e dans le chemin {\bf mysql-path} que vous avez sp\'ecifi\'e. Si
+cette option est absente, Bacula sera compil\'e automatiquement avec le code
+de la base Bacula interne. Nous recommandons d'utiliser cette option si
+possible. Si vous souhaitez utilisez cette option, veuillez proc\'eder \`a
+l'installation de MySQL (
+\ilink{Installer and Configurer MySQL}{_ChapterStart}) avant de
+proc\'eder \`a la configuration.
+
+Voyez aussi la note ci-dessous, apr\`es le paragraphe --with-postgreSQL
+
+\item [{-}{-}with-postgresql=\lt{}postgresql-path\gt{}]
+ \index[general]{{-}{-}with-postgresql }
+ Cette option d\'eclare un chemin explicite pour les librairies PostgreSQL si
+Bacula ne les trouve pas dans le r\'epertoire par d\'efaut.
+
+Notez que pour que Bacula soit configur\'e correctement, vous devez sp\'ecifier l'une des
+quatre options de bases de donn\'ees support\'ees : {-}{-}with-sqlite, {-}{-}with-sqlite3,
+{-}{-}with-mysql, ou {-}{-}with-postgresql, faute de quoi ./configure \'echouera.
+
+\item [ {-}{-}with-openssl=\lt{}path\gt{}]
+ Cette option est requise si vous souhaitez activer TLS (ssl) qui chiffre les
+ communications entre les daemons Bacula ou si vous voulez utiliser le chiffrement
+ PKI des données du File Daemon.Normalement, la sp\'ecification du chemin {\bf path}
+ n'est pas n\'ecessaire car le processus de
+ configuration recherche les librairies OpenSSL dans les emplacements standard du
+ syst\`eme. L'activation d'OpenSSL dans Bacula permet des communications s\'ecuris\'ees
+ entre les {\it daemons}. Pour plus d'informations sur l'usage de TLS, consultez le
+ chapitre \ilink{Bacula TLS}{_ChapterStart61} de ce manuel. Pour plus d'informations
+ sur l'usage du chiffrement des données PKI, veuillez consulter le chapitre
+ \ilink{Bacula PKI -- Data Encryption}{Chiffrement des données} de ce manuel.
+
+\item [ {-}{-}with-python=\lt{}path\gt{}]
+ \index[general]{{-}{-}with-python }
+ Cette option active le support Python dans Bacula. Si le chemin n'est pas
+ sp\'ecifi\'e, le processus de configuration recherchera les librairies Python
+ dans leurs emplacements standard. S'il ne peut trouver les librairies , il vous faudra
+ fournir le chemin vers votre r\'epertoire de librairies Python. Voyez le
+ \ilink{chapitre Python}{_ChapterStart60} pour plus de d\'etails sur l'utilisation de
+ scripts Python.
+
+\item [ {-}{-}with-libintl-prefix=\lt{}DIR\gt{}]
+ \index[general]{{-}{-}with-libintl-prefix}
+ Cette option peut \^etre utilis\'ee pour indiquer \`a Bacula de rechercher dans DIR/include
+ et DIR/lib les fichiers d'en t\^ete libintl et les librairies requises pour
+ Native Language Support (NLS).
+
+\item [{-}{-}enable-conio]
+ \index[general]{{-}{-}enable-conio }
+ Cette option permet la compilation d'une petite et l\'eg\`ere routine en
+alternative \`a readline, beaucoup plus facile \`a configurer, m\^eme si elle
+n\'ecessite aussi les librairies termcap ou ncurses.
+
+\item [{-}{-}with-readline=\lt{}readline-path\gt{}]
+ \index[general]{{-}{-}with-readline }
+ Sp\'ecifie l'emplacement de {\bf readline}. En principe, Bacula devrait le
+trouver s'il est dans une librairie standard. Sinon, et si l'option
+\verb{--{with-readline n'est pas renseign\'ee, readline sera d\'esactiv\'e. Cette
+option affecte la compilation de Bacula. Readline fournit le programme
+Console avec un historique des lignes de commandes et des capacit\'es
+d'\'edition. Readline n'est d\'esormais plus support\'e, ce qui signifie que
+vous l'utilisez \`a vos risques et p\'erils
+
+\item [{-}{-}enable-readline]
+ \index[general]{{-}{-}enable-readline }
+ Active le support readline. D\'esactiv\'e par d\'efaut en raison de nombreux
+probl\`emes de configuration, et parce que le paquetage semble devenir
+incompatible.
+
+\item [{-}{-}with-tcp-wrappers=\lt{}path\gt{}]
+ \index[general]{{-}{-}with-tcp-wrappers}
+ \index[general]{TCP Wrappers}
+ \index[general]{Wrappers!TCP}
+ \index[general]{libwrappers}
+ Cette option pr\'ecise que vous voulez TCP wrappers (man hosts\_access(5))
+compil\'e dans Bacula. Le chemin est facultatif puisque Bacula devrait, en
+principe, trouver les librairies dans les r\'epertoires standards. Cette
+option affecte la compilation. Lorsque vous sp\'ecifierez vos restrictions
+dans les fichiers {\bf /etc/hosts.allow} ou {\bf /etc/hosts.deny}, n'utilisez
+pas l'option {\bf twist} (man hosts\_options(5)) ou le processus Bacula sera
+stopp\'e.
+
+Pour plus d'informations sur la configuration et les tests de TCP wrappers,
+consultez la section
+\ilink{Configurer et Tester TCP Wrappers}{wrappers} du chapitre
+sur la s\'ecurit\'e.
+
+Sur SuSE, les librairies libwrappers requises pour lier Bacula appartiennent
+au paquet tcpd-devel. Sur RedHat, le paquet se nomme tcp\_wrappers.
+
+\item [{-}{-}with-working-dir=\lt{}working-directory-path\gt{}]
+ \index[dir]{{-}{-}with-working-dir }
+ Cette option est obligatoire et sp\'ecifie un r\'epertoire dans lequel Bacula
+peut placer en toute s\'ecurit\'e les fichiers qui resteront d'une
+ex\'ecution \`a l'autre. Par exemple, si la base de donn\'ees interne est
+utilis\'ee, Bacula stockera ces fichiers dans ce r\'epertoire. Cette option
+n'est utilis\'ee que pour modifier les fichiers de configuration de Bacula.
+Vous pourrez \'eventuellement effectuer cette modification directement en les
+\'editant plus tard. Le r\'epertoire sp\'ecifi\'e ici n'est pas
+automatiquement cr\'e\'e par le processus d'installation, aussi vous devez
+veiller \`a ce qu'il existe avant votre premi\`ere utilisation de Bacula.
+
+\item [{-}{-}with-base-port=\lt{}port=number\gt{}]
+ \index[dir]{{-}{-}with-base-port }
+ Bacula a besoin de trois ports TCP/IP pour fonctionner (un pour la Console,
+un pour le Storage Daemon et un pour le File Daemon). L'option {\bf
+\verb{--{with-baseport} permet d'assigner automatiquement trois ports cons\'ecutifs
+\`a partir du port de base sp\'ecifi\'e. Vous pouvez aussi changer les
+num\'eros de ports dans les fichiers de configuration. Cependant, vous devez
+prendre garde \`a ce que les num\'eros de ports se correspondent fid\`element
+dans chacun des trois fichiers de configuration. Le port de base par d\'efaut
+est 9101, ce qui assigne les ports 9101 \`a 9103. Ces ports (9101, 9102 et
+9103) ont \'et\'e officiellement assign\'e \`a Bacula par l'IANA. Cette
+option n'est utilis\'ee que pour modifier les fichiers de configuration de
+Bacula. Vous pouvez \`a tout moment faire cette modification en \'editant
+directement ces fichiers.
+
+\item [{-}{-}with-dump-email=\lt{}email-address\gt{}]
+ \index[dir]{{-}{-}with-dump-email }
+ Cette option sp\'ecifie l'adresse e-mail qui recevra tous les {\it core dump}.
+ Cette option n'est en principe utilis\'ee que par les d\'eveloppeurs.
+
+\item [{-}{-}with-pid-dir=\lt{}PATH\gt{} ]
+ \index[dir]{{-}{-}with-pid-dir }
+ Ceci pr\'ecise le r\'epertoire de stockage du fichier d'id de processus lors
+de l'ex\'ecution. La valeur par d\'efaut est : {\bf /var/run}. Le r\'epertoire
+sp\'ecifi\'e ici n'est pas automatiquement cr\'e\'e par le processus
+d'installation, aussi vous devez veiller \`a ce qu'il existe avant votre
+premi\`ere utilisation de Bacula.
+
+\item [{-}{-}with-subsys-dir=\lt{}PATH\gt{} ]
+ \index[dir]{{-}{-}with-subsys-dir }
+ Cette option pr\'ecise le r\'epertoire de stockage des fichiers verrous du
+sous-syst\`eme lors de l'ex\'ecution. Le r\'epertoire par d\'efaut est {\bf
+/var/run/subsys}. Veillez \`a ne pas sp\'ecifier le m\^eme r\'epertoire que
+pour l'option {\bf sbindir}. Ce r\'epertoire n'est utilis\'e que par les
+scripts de d\'emarrage automatique. Le r\'epertoire sp\'ecifi\'e ici n'est
+pas automatiquement cr\'e\'e par le processus d'installation, aussi vous devez
+veiller \`a ce qu'il existe avant votre premi\`ere utilisation de Bacula.
+
+\item [{-}{-}with-dir-password=\lt{}Password\gt{} ]
+ \index[dir]{{-}{-}with-dir-password }
+ Cette option vous permet de pr\'eciser le mot de passe d'acc\`es au Director
+(contact\'e, en principe, depuis la console). S'il n'est pas pr\'ecis\'e,
+configure en cr\'e\'e un al\'eatoirement.
+
+\item [{-}{-}with-fd-password=\lt{}Password\gt{} ]
+ \index[fd]{{-}{-}with-fd-password }
+ Cette option vous permet de pr\'eciser le mot de passe d'acc\`es au File
+Daemon (contact\'e, en principe, depuis le Director). S'il n'est pas
+pr\'ecis\'e, configure en cr\'e\'e un al\'eatoirement.
+
+\item [{-}{-}with-sd-password=\lt{}Password\gt{} ]
+ \index[sd]{{-}{-}with-sd-password }
+ Cette option vous permet de pr\'eciser le mot de passe d'acc\`es au Storage
+Daemon (contact\'e, en principe, depuis le File Daemon). S'il n'est pas
+pr\'ecis\'e, configure en cr\'e\'e un al\'eatoirement.
+
+\item [{-}{-}with-dir-user=\lt{}User\gt{} ]
+ \index[dir]{{-}{-}with-dir-user }
+ Cette option vous permet de sp\'ecifier l'UserId utilis\'e pour l'ex\'ecution
+du Director. Le Director doit \^etre d\'emarr\'e en tant que root, mais n'a
+pas besoin d'\^etre ex\'ecut\'e en tant que root. Apr\`es avoir effectu\'e les
+op\'erations d'initialisation pr\'eliminaires, il peut redescendre au niveau
+de l'UserId sp\'ecifi\'e dans cette option. Si vous utilisez cette option, vous
+devez cr\'eer l'utilisateur User avant d'ex\'ecuter {\bf make install}, car le
+r\'epertoire de travail de Bacula appartiendra \`a cet utilisateur.
+
+\item [{-}{-}with-dir-group=\lt{}Group\gt{} ]
+ \index[dir]{{-}{-}with-dir-group }
+ Cette option vous permet de sp\'ecifier le GroupId utilis\'e pour
+l'ex\'ecution du Director. Le Director doit \^etre d\'emarr\'e en tant que
+root, mais n'a pas besoin d'\^etre ex\'ecut\'e en tant que root. Apr\`es avoir
+effectu\'e les op\'erations d'initialisation pr\'eliminaires, il peut
+redescendre au niveau du GroupId sp\'ecifi\'e dans cette option.
+Si vous utilisez cette option, vous
+devez cr\'eer le groupe Group avant d'ex\'ecuter {\bf make install}, car le
+r\'epertoire de travail de Bacula appartiendra \`a ce groupe.
+
+\item [{-}{-}with-sd-user=\lt{}User\gt{} ]
+ \index[sd]{{-}{-}with-sd-user }
+ Cette option vous permet de sp\'ecifier l'UserId utilis\'e pour ex\'ecuter le
+Storage Daemon. Le Storage Daemon doit \^etre d\'emarr\'e en tant que root,
+mais n'a pas besoin d'\^etre ex\'ecut\'e en tant que root. Apr\`es avoir
+effectu\'e les op\'erations d'initialisation pr\'eliminaires, il peut
+redescendre au niveau de l'UserId sp\'ecifi\'e dans cette option. Si vous
+utilisez cette option, veillez \`a ce que le Storage Daemon ait acc\`es \`a
+tous les p\'eriph\'eriques de stockage dont il a besoin.
+
+\item [{-}{-}with-sd-group=\lt{}Group\gt{} ]
+ \index[sd]{{-}{-}with-sd-group }
+ Cette option vous permet de sp\'ecifier le GroupId utilis\'e pour ex\'ecuter
+le Storage Daemon. Le Storage Daemon doit \^etre d\'emarr\'e en tant que
+root, mais n'a pas besoin d'\^etre ex\'ecut\'e en tant que root. Apr\`es avoir
+effectu\'e les op\'erations d'initialisation pr\'eliminaires, il peut
+redescendre au niveau du GroupId sp\'ecifi\'e dans cette option.
+
+\item [{-}{-}with-fd-user=\lt{}User\gt{} ]
+ \index[fd]{{-}{-}with-fd-user }
+ Cette option vous permet de sp\'ecifier l'UserId utilis\'e pour ex\'ecuter le
+File Daemon. Le File Daemon doit \^etre d\'emarr\'e et, dans la plupart des
+cas, ex\'ecut\'e en tant que root, de sorte que cette option n'est utilis\'ee
+que dans des cas bien particuliers. Malgr\'e tout, apr\`es avoir effectu\'e
+les op\'erations d'initialisation pr\'eliminaires, il peut redescendre au
+niveau de l'UserId sp\'ecifi\'e dans cette option.
+
+\item [{-}{-}with-fd-group=\lt{}Group\gt{} ]
+ \index[fd]{{-}{-}with-fd-group }
+ Cette option vous permet de sp\'ecifier le GroupId utilis\'e pour ex\'ecuter
+le File Daemon. Le File Daemon doit \^etre d\'emarr\'e et, dans la plupart
+des cas, ex\'ecut\'e en tant que root, de sorte que cette option n'est
+utilis\'ee que dans des cas bien particuliers. Malgr\'e tout, apr\`es avoir
+effectu\'e les op\'erations d'initialisation pr\'eliminaires, il peut
+redescendre au niveau du GroupId sp\'ecifi\'e dans cette option.
+\end{description}
+
+Notez: de nombreuses options suppl\'ementaires vous sont pr\'esent\'ees
+lorsque vous entrez {\bf ./configure \verb{--{help}, mais elles ne sont pas
+impl\'ement\'ees.
+
+\section{Options recommand\'ees pour la plupart des syst\`emes}
+\index[general]{Options recommand\'ees pour la plupart des syst\`emes }
+\addcontentsline{toc}{section}{Options recommand\'ees pour la plupart des
+syst\`emes}
+
+Pour la plupart des syst\`emes, nous recommandons de commencer avec les
+options suivantes :
+
+\footnotesize
+\begin{verbatim}
+./configure \
+ --enable-smartalloc \
+ --sbindir=$HOME/bacula/bin \
+ --sysconfdir=$HOME/bacula/bin \
+ --with-pid-dir=$HOME/bacula/bin/working \
+ --with-subsys-dir=$HOME/bacula/bin/working \
+ --with-mysql=$HOME/mysql \
+ --with-working-dir=$HOME/bacula/working
+\end{verbatim}
+\normalsize
+
+Si vous souhaitez installer Bacula dans un r\'epertoire d'installation
+plut\^ot que de l'ex\'ecuter depuis le r\'epertoire de compilation, (comme le
+feront les d\'eveloppeurs la plupart du temps), vous devriez aussi inclure les
+options \verb{--{sbindir et \verb{--{sysconfdir avec les chemins appropri\'es. Aucune n'est
+n\'ecessaire si vous ne vous servez pas de "make install'', comme c'est le
+cas pour la plupart des travaux de d\'eveloppement. Le processus
+d'installation va cr\'eer les r\'epertoires sbindir et sysconfdir s'ils
+n'existent pas, mais il ne cr\'eera pas les r\'epertoires pid-dir, subsys-dir
+ni working-dir, aussi assurez vous qu'ils existent avant de lancer Bacula.
+L'exemple ci-dessous montre la fa\c{c}on de proc\'eder de Kern.
+
+\section{RedHat}
+\index[general]{RedHat }
+\addcontentsline{toc}{section}{RedHat}
+
+Avec SQLite:
+
+\footnotesize
+\begin{verbatim}
+
+CFLAGS="-g -Wall" ./configure \
+ --sbindir=$HOME/bacula/bin \
+ --sysconfdir=$HOME/bacula/bin \
+ --enable-smartalloc \
+ --with-sqlite=$HOME/bacula/depkgs/sqlite \
+ --with-working-dir=$HOME/bacula/working \
+ --with-pid-dir=$HOME/bacula/bin/working \
+ --with-subsys-dir=$HOME/bacula/bin/working \
+ --enable-gnome \
+ --enable-conio
+\end{verbatim}
+\normalsize
+
+ou
+
+\footnotesize
+\begin{verbatim}
+
+CFLAGS="-g -Wall" ./configure \
+ --sbindir=$HOME/bacula/bin \
+ --sysconfdir=$HOME/bacula/bin \
+ --enable-smartalloc \
+ --with-mysql=$HOME/mysql \
+ --with-working-dir=$HOME/bacula/working
+ --with-pid-dir=$HOME/bacula/bin/working \
+ --with-subsys-dir=$HOME/bacula/bin/working
+ --enable-gnome \
+ --enable-conio
+\end{verbatim}
+\normalsize
+
+ou une installation RedHat compl\`etement traditionnelle :
+
+\footnotesize
+\begin{verbatim}
+CFLAGS="-g -Wall" ./configure \
+ --prefix=/usr \
+ --sbindir=/usr/sbin \
+ --sysconfdir=/etc/bacula \
+ --with-scriptdir=/etc/bacula \
+ --enable-smartalloc \
+ --enable-gnome \
+ --with-mysql \
+ --with-working-dir=/var/bacula \
+ --with-pid-dir=$HOME/var/run \
+ --enable-conio
+\end{verbatim}
+\normalsize
+
+Notez que Bacula suppose que les r\'epertoires /var/bacula, /var/run et
+/var/lock/subsys existent, ils ne seront pas cr\'ees par le processus
+d'installation.
+
+D'autre part, avec gcc 4.0.1 20050727 (Red Hat 4.0.1-5) sur processeur AMD64
+et sous CentOS4 64 bits, un bug du compilateur g\'en\`ere du code erron\'e qui
+conduit Bacula \`a des erreurs de segmentation. Typiquement, vous le rencontrerez
+d'abord avec le Storage Daemon. La solution consiste \`a s'assurer que Bacula est
+compil\'e sans optimisation (normalement -O2)
+
+\section{Solaris}
+\index[general]{Solaris }
+\addcontentsline{toc}{section}{Solaris}
+
+Pour installer Bacula depuis les sources, il vous faudra les paquetages suivants
+sur votre syst\`eme (ils ne sont pas install\'es par d\'efaut) : libiconv, gcc 3.3.2, stdc++, libgcc
+( pour les librairies stdc++ and gcc\_s ), make 3.8 ou plus r\'ecent.
+
+Il vous faudra probablement aussi ajouter /usr/local/bin et /usr/css/bin \`a PATH pour ar.
+
+\footnotesize
+\begin{verbatim}
+#!/bin/sh
+CFLAGS="-g" ./configure \
+ --sbindir=$HOME/bacula/bin \
+ --sysconfdir=$HOME/bacula/bin \
+ --with-mysql=$HOME/mysql \
+ --enable-smartalloc \
+ --with-pid-dir=$HOME/bacula/bin/working \
+ --with-subsys-dir=$HOME/bacula/bin/working \
+ --with-working-dir=$HOME/bacula/working
+\end{verbatim}
+\normalsize
+
+Comme mentionn\'e ci-dessus, le processus d'installation va cr\'eer les
+r\'epertoires sbindir et sysconfdir s'ils n'existent pas, mais il ne cr\'eera
+pas les r\'epertoires pid-dir, subsys-dir ni working-dir, aussi assurez vous
+qu'ils existent avant de lancer Bacula.
+
+Notez que vous pouvez aussi avoir besoin des paquetages suivants pour installer Bacula
+depuis les sources :
+\footnotesize
+\begin{verbatim}
+SUNWbinutils,
+SUNWarc,
+SUNWhea,
+SUNWGcc,
+SUNWGnutls
+SUNWGnutls-devel
+SUNWGmake
+SUNWgccruntime
+SUNWlibgcrypt
+SUNWzlib
+SUNWzlibs
+SUNWbinutilsS
+SUNWGmakeS
+SUNWlibm
+
+export
+PATH=/usr/bin::/usr/ccs/bin:/etc:/usr/openwin/bin:/usr/local/bin:/usr/sfw/bin:/opt/sfw/bin:/usr/ucb:/usr/sbin
+\end{verbatim}
+\normalsize
+
+
+\section{FreeBSD}
+\index[general]{FreeBSD }
+\addcontentsline{toc}{section}{FreeBSD}
+
+Veuillez consulter:
+\elink{The FreeBSD Diary}{http://www.freebsddiary.org/bacula.php} pour une
+description d\'etaill\'ee de la m\'ethode pour faire fonctionner Bacula sur
+votre syst\`eme. De plus, les utilisateurs de versions de FreeBSD
+ant\'erieures \`a la 4.9-STABLE du lundi 29 d\'ecembre 2003 15:18:01 qui
+envisagent d'utiliser des lecteurs de bandes doivent consulter le chapitre
+\ilink{Tester son lecteur de bandes}{FreeBSDTapes} de ce
+manuel pour d'{\bf importantes} informations sur la configuration des lecteurs
+pour qu'ils soient compatibles avec Bacula.
+
+Si vous utilisez Bacula avec MySQL, vous devriez prendre garde \`a compiler
+MySQL avec les threads natifs de FreeBSD plut\^ot qu'avec ceux de Linux, car
+c'est avec ceux l\`a qu'est compil\'e Bacula et le m\'elange des deux ne
+fonctionnera probablement pas.
+
+\section{Win32}
+\index[general]{Win32 }
+\addcontentsline{toc}{section}{Win32}
+
+Pour installer la version binaire Win32 du File Daemon, consultez le chapitre
+\ilink{ Installation sur syst\`emes Win32}{_ChapterStart7} de ce
+document.
+
+\section{Syst\`emes Windows avec CYGWIN install\'e}
+\label{Win32}
+\index[general]{Syst\`emes Windows avec CYGWIN install\'e }
+\addcontentsline{toc}{section}{Syst\`emes Windows avec CYGWIN install\'e}
+
+A partir de la version 1.34, Bacula n'utilise plus CYGWIN pour le client
+Win32. Il est cependant encore compil\'e sous un environnement CYGWIN -- Bien
+que vous puissiez probablement le faire avec seulement VC Studio. Si vous
+souhaitez compiler le client Win32 depuis les sources, il vous faudra
+Microsoft C++ version 6.0 ou sup\'erieur. Dans les versions de Bacula
+ant\'erieures \`a la 1.33, CYGWIN \'etait utilis\'e.
+
+Notez qu'en d\'epit du fait que la plupart des \'el\'ements de Bacula puissent
+compiler sur les syst\`emes Windows, la seule partie que nous avons test\'ee
+et utilis\'ee est le File Daemon.
+
+Finalement, vous devriez suivre les instructions d'installation de la section
+\ilink{Win32 Installation sur syst\`emes Win32}{_ChapterStart7} de ce
+document en occultant la partie qui d\'ecrit la d\'ecompression de la version
+binaire.
+
+\section{Le script Configure de Kern}
+\index[general]{Le script Configure de Kern }
+\index[general]{Kern!Le script Configure de }
+\addcontentsline{toc}{section}{Le script Configure de Kern}
+
+Voici le script que j'utilise pour compiler sur mes machines Linux de
+"production'':
+
+\footnotesize
+\begin{verbatim}
+#!/bin/sh
+# This is Kern's configure script for Bacula
+CFLAGS="-g -Wall" \
+ ./configure \
+ --sbindir=$HOME/bacula/bin \
+ --sysconfdir=$HOME/bacula/bin \
+ --enable-smartalloc \
+ --enable-gnome \
+ --with-pid-dir=$HOME/bacula/bin/working \
+ --with-subsys-dir=$HOME/bacula/bin/working \
+ --with-mysql=$HOME/mysql \
+ --with-working-dir=$HOME/bacula/bin/working \
+ --with-dump-email=$USER \
+ --with-smtp-host=mail.your-site.com \
+ --with-baseport=9101
+exit 0
+\end{verbatim}
+\normalsize
+
+Notez que je fixe le port de base \`a 9101, ce qui signifie que Bacula
+utilisera le port 9101 pour la console Director, le port 9102 pour le File
+Daemon, et le 9103 pour le Storage Daemon. Ces ports devraient \^etre
+disponibles sur tous les syst\`emes \'etant donn\'e qu'ils ont \'et\'e
+officiellement attribu\'es \`a Bacula par l'IANA (Internet Assigned Numbers
+Authority). Nous recommandons fortement de n'utiliser que ces ports pour
+\'eviter tout conflit avec d'autres programmes. Ceci est en fait la
+configuration par d\'efaut si vous n'utilisez pas l'option {\bf
+\verb{--{with-baseport}.
+
+Vous pouvez aussi ins\'erer les entr\'ees suivantes dans votre fichier {\bf
+/etc/services} de fa\c{c}on \`a rendre les connections de Bacula plus
+ais\'ees \`a rep\'erer (i.e. netstat -a):
+
+\footnotesize
+\begin{verbatim}
+bacula-dir 9101/tcp
+bacula-fd 9102/tcp
+bacula-sd 9103/tcp
+\end{verbatim}
+\normalsize
+
+\section{Installer Bacula}
+\index[general]{Installer Bacula }
+\index[general]{Bacula!Installer }
+\addcontentsline{toc}{section}{Installer Bacula}
+
+Avant de personnaliser vos fichiers de configuration, vous voudrez installer
+Bacula dans son r\'epertoire d\'efinitif. tapez simplement:
+
+\footnotesize
+\begin{verbatim}
+make install
+\end{verbatim}
+\normalsize
+
+Si vous avez pr\'ec\'edemment install\'e Bacula, les anciens binaires seront
+\'ecras\'es, mais les anciens fichiers de configuration resteront inchang\'es,
+et les "nouveaux'' recevront l'extension {\bf .new}. G\'en\'eralement, si
+vous avez d\'ej\`a install\'e et ex\'ecut\'e Bacula, vous pr\'ef\`ererez
+supprimer ou ignorer les fichiers de configuration avec l'extension {\bf .new}
+
+
+\section{Compiler un File Daemon (ou Client)}
+\index[general]{Compiler un File Daemon (ou Client) }
+\index[general]{Client!Compiler un File Daemon ou }
+\addcontentsline{toc}{section}{Compiler un File Daemon (ou Client)}
+
+Si vous ex\'ecutez le Director et le Storage Daemon sur une machine et si vous
+voulez sauvegarder une autre machine, vous devez avoir un File Daemon sur
+cette machine. Si la machine et le syst\`eme sont identiques, vous pouvez
+simplement copier le binaire du File Daemon {\bf bacula-fd} ainsi que son
+fichier de configuration {\bf bacula-fd.conf}, puis modifier le nom et le mot
+de passe dans {\bf bacula-fd.conf} de fa\c{c}on \`a rendre ce fichier unique.
+Veillez \`a faire les modifications correspondantes dans le fichier de
+configuration du Director ({\bf bacula-dir.conf}).
+
+Si les architectures, les syst\`emes, ou les versions de syst\`emes
+diff\`erent, il vous faudra compiler un File Daemon sur la machine cliente.
+Pour ce faire, vous pouvez utiliser la m\^eme commande {\bf ./configure} que
+celle utilis\'ee pour construire le programme principal, soit en partant d'une
+copie fraiche du r\'epertoire des sources, soit en utilisant {\bf make\
+distclean} avant de lancer {\bf ./configure}.
+
+Le File Daemon n'ayant pas d'acc\`es au catalogue, vous pouvez supprimer les
+option {\bf \verb{--{with-mysql} ou {\bf \verb{--{with-sqlite}. Ajoutez l'option {\bf
+\verb{--{enable-client-only}. Ceci va compiler seulement les librairies et programmes
+clients, et donc \'eviter d'avoir \`a installer telle ou telle base de
+donn\'ees. Lancez make avec cette configuration, et seul le client sera
+compil\'e.
+\label{autostart}
+
+\section{D\'emarrage automatique des Daemons}
+\index[general]{Daemons!D\'emarrage automatique des }
+\index[general]{D\'emarrage automatique des Daemons }
+\addcontentsline{toc}{section}{D\'emarrage automatique des Daemons}
+
+Si vous souhaitez que vos {\it daemons} soient lanc\'es automatiquement au
+d\'emarrage de votre syst\`eme (une bonne id\'ee !), une \'etape
+suppl\'ementaire est requise. D'abord, le processus ./configure doit
+reconna{\^\i}tre votre syst\`eme -- ce qui signifie que ce doit \^etre une
+plate-forme support\'ee et non {\bf inconnue}, puis vous devez installer les
+fichiers d\'ependants de la plate-forme comme suit :
+
+\footnotesize
+\begin{verbatim}
+(devenez root)
+make install-autostart
+\end{verbatim}
+\normalsize
+
+Notez que la fonction d'autod\'emarrage n'est impl\'ement\'ee que pour les
+syst\`emes que nous supportons officiellement (actuellement FreeBSD, RedHat
+Linux, et Solaris), et n'a \'et\'e pleinement test\'ee que sur RedHat Linux.
+
+{\bf make install-autostart} installe les scripts de d\'emarrage apropri\'es
+ainsi que les liens symboliques n\'ecessaires. Sur RedHat Linux, Ces scripts
+r\'esident dans {\bf /etc/rc.d/init.d/bacula-dir} {\bf
+/etc/rc.d/init.d/bacula-fd}, et {\bf /etc/rc.d/init.d/bacula-sd}. Toutefois,
+leur localisation exacte d\'epend de votre syst\`eme d'exploitation.
+
+Si vous n'installez que le File Daemon, tapez:
+
+\footnotesize
+\begin{verbatim}
+make install-autostart-fd
+\end{verbatim}
+\normalsize
+
+\section{Autres notes concernant la compilation}
+\index[general]{Autres notes concernant la compilation }
+\index[general]{Compilation!Autres notes concernant la }
+\addcontentsline{toc}{section}{Autres notes concernant la compilation}
+
+Pour recompiler tout ex\'ecutable, tapez
+
+\footnotesize
+\begin{verbatim}
+make
+\end{verbatim}
+\normalsize
+
+dans le r\'epertoire correspondant.. Afin d'\'eliminer tous les objets et
+binaires (y compris les fichiers temporaires nomm\'es 1,2 ou 3 qu'utilise
+Kern), tapez
+
+\footnotesize
+\begin{verbatim}
+make clean
+\end{verbatim}
+\normalsize
+
+Pour un nettoyage exhaustif en vue de distribution, entrez:
+
+\footnotesize
+\begin{verbatim}
+make distclean
+\end{verbatim}
+\normalsize
+
+Notez que cette commande supprime les Makefiles. Elle est en principe
+lanc\'ee depuis la racine du r\'epertoire des sources pour les pr\'eparer \`a
+la distribution. Pour revenir de cet \'etat, vous devez r\'eex\'ecuter la
+commande {\bf ./configure} \`a la racine des sources puisque tous les
+Makefiles ont \'et\'e d\'etruits.
+
+Pour ajouter un nouveau fichier dans un sous-r\'epertoire, \'editez
+Makefile.in dans ce sous-r\'epertoire, puis faites un simple {\bf make}. Dans
+la plupart des cas, le make reconstruira le Makefile \`a partir du nouveau
+Makefile.in. Dans certains cas, il peut \^etre n\'ecessaire d'ex\'ecuter {\bf
+make} une deuxi\`eme fois. Dans les cas extr\`emes, remontez \`a la racine des
+sources et entrez {\bf make Makefiles}.
+
+Pour ajouter des d\'ependances:
+
+\footnotesize
+\begin{verbatim}
+make depend
+\end{verbatim}
+\normalsize
+
+La commande {\bf make depend} ins\`ere les fichiers d'en-t\^etes de
+d\'ependances aux Makefile et Makefile.in pour chaque fichier objet. Cette
+commande devrait \^etre lanc\'ee dans chaque r\'epertoire o\`u vous modifiez
+les d\'ependances. En principe, il suffit de l'ex\'ecuter lorsque vous ajoutez
+ou supprimez des sources ou fichiers d'en-t\^etes. {\bf make depend} est
+invoqu\'e automatiquement durant le processus de configuration.
+
+Pour installer:
+
+\footnotesize
+\begin{verbatim}
+make install
+\end{verbatim}
+\normalsize
+
+En principe, vous n'utilisez pas cette commande si vous \^etes en train de
+d\'evelopper Bacula, mais si vous vous appr\'etez \`a l'ex\'ecuter pour
+sauvegarder vos syst\`emes.
+
+Apr\`es avoir lanc\'e {\bf make install}, les fichiers suivants seront
+install\'es sur votre syst\`eme (\`a peu de choses pr\`es). La liste exacte
+des fichiers install\'es et leur localisation d\'epend de votre commande {\bf
+c./configure} (e.g. gnome-console et gnome-console.conf ne sont pas
+install\'es si vous ne configurez pas GNOME. De m\^eme, si vous utilisez
+SQLite plut\^ot que MySQL, certains fichiers seront diff\'erents.
+
+\footnotesize
+\begin{verbatim}
+bacula
+bacula-dir
+bacula-dir.conf
+bacula-fd
+bacula-fd.conf
+bacula-sd
+bacula-sd.conf
+bacula-tray-monitor
+tray-monitor.conf
+bextract
+bls
+bscan
+btape
+btraceback
+btraceback.gdb
+bconsole
+bconsole.conf
+create_mysql_database
+dbcheck
+delete_catalog_backup
+drop_bacula_tables
+drop_mysql_tables
+fd
+gnome-console
+gnome-console.conf
+make_bacula_tables
+make_catalog_backup
+make_mysql_tables
+mtx-changer
+query.sql
+bsmtp
+startmysql
+stopmysql
+bwx-console
+bwx-console.conf
+\end{verbatim}
+\normalsize
+
+\label{monitor}
+
+\section{Installer Tray Monitor}
+\index[general]{Monitor!Installer Tray }
+\index[general]{Installer Tray Monitor }
+\addcontentsline{toc}{section}{Installer Tray Monitor}
+
+Le Tray Monitor est d\'ej\`a install\'e si vous avez utilis\'e l'option {\bf
+\verb{--{enable-tray-monitor} de la commande configure et ex\'ecut\'e {\bf make
+install}.
+
+Comme vous n'ex\'ecutez pas votre environnement graphique en tant que root (si
+vous le faites, vous devriez changer cette mauvaise habitude), n'oubliez pas
+d'autoriser votre utilisateur \`a lire {\bf tray-monitor.conf}, et ex\'ecuter
+{\bf bacula-tray-monitor} (ceci ne constitue pas une faille de s\'ecurit\'e).
+
+Puis, connectez vous \`a votre environnement graphique (KDE, Gnome, ou autre),
+lancez {\bf bacula-tray-monitor} avec votre utilisateur et observez si l'icone
+d'une cartouche appara{\^\i}t quelque part sur l'\'ecran, usuellement dans la
+barre des t\^aches.
+Sinon, suivez les instructions suivantes relatives \`a votre gestionnaire de
+fen\^etres.
+
+\subsection{GNOME}
+\index[general]{GNOME }
+\addcontentsline{toc}{subsection}{GNOME}
+
+System tray, ou zone de notification si vous utilisez la terminologie GNOME,
+est support\'e par GNOME depuis la version 2.2. Pour l'activer, faites un
+click droit sur un de vos espaces de travail, ouvrez le menu {\bf Ajouter \`a
+ce bureau}, puis {\bf Utilitaire} et enfin, cliquez sur {\bf Zone de
+notification}. (NDT: A valider)
+
+\subsection{KDE}
+\index[general]{KDE }
+\addcontentsline{toc}{subsection}{KDE}
+
+System tray est support\'e par KDE depuis la version 3.1. Pour l'activer,
+faites un click droit sur la barre de t\^aches, ouvrez le menu {\bf Ajouter},
+puis {\bf Applet}, enfin cliquez sur {\bf System Tray}.
+
+\subsection{Autres gestionnaires de fen\^etres}
+\index[general]{Autres gestionnaires de fen\^etres }
+\addcontentsline{toc}{subsection}{Autres gestionnaires de fen\^etres}
+
+Lisez la documentation pour savoir si votre gestionnaire de fen\^etres
+supporte le standard {\it systemtray} de FreeDesktop, et comment l'activer le
+cas \'ech\'eant.
+
+\section{Modifier les fichiers de configuration de Bacula}
+\index[general]{Modifier les fichiers de configuration de Bacula }
+\index[general]{Bacula!Modifier les fichiers de configuration de }
+\addcontentsline{toc}{section}{Modifier les fichiers de configuration de
+Bacula}
+
+Consultez le chapitre
+\ilink{Configurer Bacula}{_ChapterStart16} de ce manuel pour les
+instructions de configuration de Bacula.
--- /dev/null
+# This file serves as a place to put initialization code and constants to
+# affect the behavior of latex2html for generating the bacula manuals.
+
+# $LINKPOINT specifies what filename to use to link to when creating
+# index.html. Not that this is a hard link.
+$LINKPOINT='"$OVERALL_TITLE"';
+
+
+# The following must be the last line of this file.
+1;
--- /dev/null
+%%
+%%
+
+\chapter{La ressource Messages}
+\label{_ChapterStart15}
+\index[general]{Ressource!Messages}
+\index[general]{Messages Ressource}
+\addcontentsline{toc}{section}{Ressource Messages}
+
+\section{La ressource Messages}
+\label{MessageResource}
+\index[general]{Ressource!Messages}
+\index[general]{Messages Ressource}
+\addcontentsline{toc}{section}{La ressource Messages}
+
+La ressource Messages d\'efinit la fa\c{c}on dont les messages doivent \^etre construits
+et vers quelles destinations ils doivent \^etre transmis.
+
+Bien que chaque {\it daemon} int\`egre un gestionnaire de messages pleinement
+fonctionnel, vous choisirez certainement de centraliser les messages appropri\'es
+des File Daemons et du Storage Daemon vers le Director. Ainsi, tous les messages
+associ\'es \`a un job donn\'e peuvent \^etre combin\'es et envoy\'es en un simple courrier
+\'electronique vers l'utilisateur, ou enregistr\'e dans quelque fichier de logs.
+
+Chaque message g\'en\'er\'e par un {\it daemon} Bacula poss\`ede un type associ\'e tel
+que INFO, WARNING, ERROR, FATAL, etc. La ressource Messages vous permet de
+stipuler les types de messages que vous voulez voir, et o\`u les envoyer. De plus,
+un message peut \^etre exp\'edi\'e vers plusieurs destinations. Par exemple, vous
+pouvez faire en sorte quque tous les messages d'erreur soient consign\'es dans un
+fichier de logs tout en vous \'etant envoy\'es par courrier \'elecronique. En
+d\'efinissant plusieurs ressources Messages, vous pouvez profiter de diff\'erents
+modes de prise en charge pour chaque type de job (par exemple, selon qu'il
+s'agit d'une full ou d'un incr\'ementale).
+
+En g\'en\'eral, les messages sont attach\'es \`a un job et sont inclus dans le rapport de job.
+Il existe de rares situations o\`u ce n'est pas possible, par exemple lorsqu'aucun
+job n'est en cours d'ex\'ecution, ou si une erreur de communication se produit
+entre un daemon et le Director. Dans ce genre de situations, le message demeure
+dans le syst\`eme et devrait \^etre purg\'e \`a la fin job suivant. Cependant, comme de tels
+messages ne sont pas attach\'es \`a un job, tous ceux qui sont envoy\'es par courrier
+\'electronique sont envoy\'es \`a {\bf /usr/lib/sendmail}. Si sur votre syst\`eme, comme c'est
+le cas de FreeBSD, sendmail r\'eside en un autre emplacement, veillez \`a le lier
+depuis l'emplacement ci-dessus.
+
+Les enregistrements contenus dans une ressource Messages consistent en une
+sp\'ecification de {\bf destination} suivie d'une liste de types de messages
+{\bf message-types} au format :
+
+\begin{description}
+
+\item [destination = message-type1, message-type2, message-type3, ... ]
+ \index[dir]{destination}
+ \end{description}
+
+ou, pour ces destinations qui n\'ecessitent de sp\'ecifier une adresse (e-mail, par exemple) :
+
+\begin{description}
+
+\item [destination = address = message-type1, message-type2,
+ message-type3, ... ]
+ \index[dir]{destination}
+
+o\`u {\bf destination} est l'un des mots-clef pr\'ed\'efinis qui pr\'ecise o\`u le message
+doit \^etre exp\'edi\'e ({\bf stdout}, {\bf file}, ...), {\bf message-type} est l'un des
+mots-clef pr\'ed\'efinis qui pr\'ecise le type de messages g\'en\'er\'e par Bacula ({\bf ERROR},
+{\bf WARNING}, {\bf FATAL}, ...) et {\bf address} varie selon le mot clef {\bf destination}
+mais peut typiquement \^etre une adresse de courrier \'electronique ou un nom de fichier.
+
+\end{description}
+
+Voici la liste des directives disponibles pour d\'efinir des ressources Messages :
+
+
+\begin{description}
+
+\item [Messages]
+ \index[dir]{Messages}
+ D\'ebut des enregistrements de Messages
+
+\item [Name = \lt{}name\gt{}]
+ \index[dir]{Name}
+ Le nom de la ressource Message. Ce nom sera utilis\'e pour lier cette ressource
+Message \`a un job et/ou au un daemon.
+
+\label{mailcommand}
+
+\item [MailCommand = \lt{}command\gt{}]
+ \index[dir]{MailCommand}
+En l'absence de cette directive, Bacula enverra tous ses messages avec la
+commande suivante :
+
+{\bf mail -s "Bacula Message" \lt{}recipients\gt{}}
+Dans de nombreusx cas, selon votre machine, cette commande peut ne pas fonctionner.
+La directive {\bf MailCommand} vous permet de stipuler pr\'ecis\'ement la fa\c{c}on
+d'envoyer vos courrier \'electroniques. Lors de l'ex\'ecution de la commande
+{\bf command}, sp\'ecifi\'ee entre guillemets, les substitutions suivantes sont
+effectu\'ees :
+
+\begin{itemize}
+ \item \%\% = \%
+ \item \%c = Le nom du client
+ \item \%d = Le nom du Director
+ \item \%e = Le code de sortie du job (OK, Error, ...)
+ \item \%i = L'Id du Job
+ \item \%j = Le nom unique du job
+ \item \%l = Le niveau (Full, differential, ...) du job
+ \item \%n = Le om du job
+ \item \%r = Les destinataires
+ \item \%t = Le type du job (Backup, verify, ...)
+\end{itemize}
+
+Voici la commande que j'utilise (Kern) :
+
+{\bf mailcommand = "/home/kern/bacula/bin/bsmtp -h mail.example.com -f
+\textbackslash{}"\textbackslash{}(Bacula\textbackslash{})
+\%r\textbackslash{}" -s \textbackslash{}"Bacula: \%t \%e of \%c
+\%l\textbackslash{}" \%r"}
+
+Notez que la commande enti\`ere devrait appara\^itre sur une seulle ligne plut\^ot
+que d\'ecoup\'ee comme ici pour des raisons de pr\'esentation.
+
+Le programme {\bf bsmtp} est fourni en tant que partie de Bacula. Pour plus
+de d\'etails, consultez la section \ilink{ bsmtp -- Personnaliser l'envoi
+de vos message par courrier \'electronique}{bsmtp}. Testez soigneusement
+toute commande {\bf mailcommand} pour vous assurer que votre passerelle
+bsmtp accepte le format d'adressage que vous utilisez. Certains programmes
+tels Exim peut se montrer tr\`es s\'electif en ce qui concerne les format
+autoris\'es, particuli\`erement en ce qui concerne le champ "from".
+
+\item [OperatorCommand = \lt{}command\gt{}]
+ \index[fd]{OperatorCommand}
+ Cette directive est analogue \`a {\bf MailCommand}, mais elle est utilis\'ee pour
+ les messages destin\'es \`a l'op\'erateur. Les substitutions effectu\'ees pour la
+ directive {\bf MailCommand} sont aussi effectu\'ees pour celle-ci. Normalement,
+ vous mettrez ici la m\^eme valeur que pour {\bf MailCommand}.
+
+\item [Debug = \lt{}debug-level\gt{}]
+ \index[fd]{Debug}
+ Cette directive r\`egle le niveau de d\'ebogage des messages. C'est un entier.
+ Plus sa valeur est grande, plus grande est la quantit\'e d'informations de
+ d\'ebogages produites. Nous vous conseillons de ne pas utiliser cette directive
+ car elle sera bient\^ot obsol\`ete.
+
+\item [\lt{}destination\gt{} = \lt{}message-type1\gt{},
+ \lt{}message-type2\gt{}, ...]
+ \index[fd]{\lt{}destination\gt{}}
+
+O\`u la {\bf destination} peut \^etre l'une des suivantes :
+
+\begin{description}
+
+\item [stdout]
+ \index[fd]{stdout}
+ Envoie le message vers la sortie standard.
+
+\item [stderr]
+ \index[fd]{stderr}
+ Envoie le message vers l'erreur standard
+
+\item [console]
+ \index[console]{console}
+ Envoie le message vers la console Bacula. Ces messages sont gard\'es en attente
+ jusqu'\`a ce que la console contacte le Director.
+\end{description}
+
+\item {\bf \lt{}destination\gt{} = \lt{}address\gt{} =
+ \lt{}message-type1\gt{}, \lt{}message-type2\gt{}, ...}
+ \index[console]{\lt{}destination\gt{}}
+
+O\`u {\bf address} d\'epend de la {\bf destination}, qui peut \^etre l'une des suivantes :
+
+\begin{description}
+
+\item [director]
+ \index[dir]{director}
+ Envoie le message vers le Director dont le nom est sp\'ecifi\'e dans le champ
+ {\bf address}. Notez que dans l'impl\'ementation actuelle, le nom du Director
+ est ignor\'e, le message \'etant envoy\'e au Directr qui a lanc\'e le job.
+
+\item [file]
+ \index[dir]{file}
+ Envoie le message vers le fichier d\'esign\'e dans le champ {\bf address}. Si le
+ fichier existe, il est \'ecras\'e.
+
+\item [append]
+ \index[dir]{append}
+ Ajoute le message \`a la suite du fichier d\'esign\'e dans le champ {\bf address}.
+ Si le fichier n'existe pas encore, il est cr\'e\'e.
+
+\item [syslog]
+ \index[fd]{syslog}
+ Envoie le message vers le syst\`eme de journalisation (syslog) en utilisant le
+ service d\'esign\'e par le champ {\bf address} Notez que, pour le moment, le champ
+ {\bf address} est ignor\'e, et que le message est toujours envoy\'e au service
+ LOG\_DAEMON avec le niveau LOG\_ERR. Consultez la page {\bf man 3 syslog}
+ pour plus de d\'etails. Exemple :
+
+\begin{verbatim}
+ syslog = all, !skipped, !saved
+\end{verbatim}
+
+\item [mail]
+ \index[fd]{mail}
+ Exp\'edie le message vers les adresses \'electroniques
+ sp\'ecifi\'ees dans le champ {\bf address} (s\'epar\'ees par des points-virgule).
+ Les messages sont rassembl\'es au cours du job, puis exp\'edi\'es lorsqu'il prend
+ fin en un seul courrier \'electronique. L'avantage de cette Destination est
+ que vous recevez une notification de chaque job ex\'ecut\'e. Toutefois, si vous
+ sauvegardez cinq ou dix machines chaque nuit, la quantit\'e de courrier
+ \'electronique peut devenir importante. Certains utilisateurs mettent en oeuvre
+ des filtres de courrier tels {\bf procmail} pour classer automatiquement ces
+ courriers en fonction des codes de fin de job (voyez la commande {\bf mailcommand}
+
+\item [mail on error]
+ \index[fd]{mail on error}
+ Exp\'edie le message vers les adresses \'electroniques
+ sp\'ecifi\'ees dans le champ {\bf address} (s\'epar\'ees par des points-virgule)
+ si le job se termine avec un code d'erreur. Les messages MailOnError sont
+ rassembl\'es au cours du job, puis exp\'edi\'es lorsqu'il prend fin en un seul
+ courrier \'electronique. Cette Destination diff\`ere de la Destination {\bf mail}
+ en ce que si le job s'ach\`eve normalement, le message est compl\`etement
+ abandonn\'e (pour cette Destination). En utilisant d'autres Destinations, telles
+ que {\bf append}, vous pouvez vous assurer que les informations de sorties
+ ne seront pas perdues m\^eme si le job se termine normalement.
+
+\item [operator]
+ \index[fd]{operator}
+ Exp\'edie le message vers les adresses \'electroniques
+ sp\'ecifi\'ees dans le champ {\bf address} (s\'epar\'ees par des points virgule).
+ Cette directive est similaire \`a {\bf mail} d\'ecrite plus haut, sauf que
+ chaque message est envoy\'e aussit\^ot re\c{c}u, de sorte qu'il y a un courrier
+ \'electronique par message . Ceci est surtout utile pour les messages de
+ type {\bf mount} (voir ci-dessous).
+
+\end{description}
+ Pour toutes les Destinations, le champ "type de message" {\bf message-type} est
+ une liste des types (ou classes) de messages suivants s\'epar\'es par des
+ points-virgule :
+
+\begin{description}
+
+\item [info]
+ \index[fd]{info}
+ Messages d'information g\'en\'erale.
+
+\item [warning]
+ \index[fd]{warning}
+ Messages d'avertissement. En g\'en\'eral, il s'agit de quelque situation inhabituelle
+ sans toutefois \^etre tr\`es s\'erieuse.
+
+\item [error]
+ \index[fd]{error}
+ Messages d'erreur non-fatale. Le job se poursuit. Tout message d'erreur devrait
+ \^etre suivi d'investigations, car il signifie que quelque chose est all\'e de travers.
+
+\item [fatal]
+ \index[fd]{fatal}
+ Messages d'erreur fatale. Ces erreurs pr\'ecipitent la fin du job.
+
+\item [terminate]
+ \index[fd]{terminate}
+ Messages g\'en\'er\'es lorsque le daemon s'arr\`ete.
+
+\item [saved]
+ \index[fd]{saved}
+ Fichiers sauvegard\'es normalement.
+
+\item [notsaved]
+ \index[fd]{notsaved}
+ Fichiers non sauvegard\'es en raison d'une erreur, en g\'en\'eral, parce que le
+ fichier n'a pu \^etre acc\'ed\'e (il n'existait pas ou n'\'etait pas mont\'e).
+
+\item [skipped]
+ \index[fd]{skipped}
+ Fichiers qui ont \'et\'e laiss\'es de cot\'e en raison d'une option pos\'ee par un
+ utilisateur (par exemple le niveau d'une sauvegarde ou une option
+ d'exclusion. Ceci n'est pas consid\'er\'e comme une condition d'erreur au m\^eme
+ titre que pour le type {\bf notsaved} puisque le fichier de configuration
+ stipule explicitement que ces fichiers ne doivent pas \^etre sauvegard\'es.
+ Des cas typiques de fichiers de type {\bf skipped} : fichiers inchang\'es
+ lors d'une incr\'ementale, sous-r\'epertoires si l'option {\bf no recursion}
+ est activ\'ee...
+
+\item [mount]
+ \index[dir]{mount}
+ Montage d'un volume ou intervention d'un op\'erateur requis par le Storage Daemon.
+ Ces requ\^etes n\'ecessitent une intervention sp\'ecifique de l'op\'erateur pour que le
+ job puisse se poursuivre.
+
+\item [restored]
+ \index[dir]{restored}
+ La liste, fa\c{c}on {\bf ls}, de tous les fichiers restaur\'es est envoy\'ee vers
+ cette classe de messages.
+
+\item [all]
+ \index[fd]{all}
+ Tous les types de messages.
+
+\item [*security]
+ \index[fd]{*security}
+ Messages d'information ou d'avertissement relatifs \`a la s\'ecurit\'e,
+ essentiellement les tentatives de connection non-autoris\'ees.
+\end{description}
+
+\end{description}
+
+Voici un exemple d'une d\'efinition de ressource Messages valide, o\`u tous les
+messages sont envoy\'es par courrier \'electronique \`a enforcement@sec.com \`a
+l'exception de ceux concernant les fichiers explicitement exclus (skipped),
+et des messages d'arr\^et de daemon (terminate). De plus, tous les messages
+de type mount sont envoy\'es \`a l'op\'erateur (courrier \`a enforcement@sec.com).
+Enfin, tous les messages autres que ceux relatifs aux fichiers explicitement
+exclus et aux fichiers sauvegard\'es sont envoy\'es vers la console :
+
+\footnotesize
+\begin{verbatim}
+Messages {
+ Name = Standard
+ mail = enforcement@sec.com = all, !skipped, !terminate
+ operator = enforcement@sec.com = mount
+ console = all, !skipped, !saved
+}
+\end{verbatim}
+\normalsize
+
+A l'exception de l'adresse \'electronique (modifi\'ee pour \'eviter le spam),
+voici la ressource Message du Director de Kern. Notez que les commandes
+{\bf mailcommand} et {\bf operatorcommand} sont sur une seule ligne et
+non coup\'ees comme ici pour des besoins de mise en page.
+
+\footnotesize
+\begin{verbatim}
+Messages {
+ Name = Standard
+ mailcommand = "bacula/bin/bsmtp -h mail.example.com \
+ -f \"\(Bacula\) %r\" -s \"Bacula: %t %e of %c %l\" %r"
+ operatorcommand = "bacula/bin/bsmtp -h mail.example.com \
+ -f \"\(Bacula\) %r\" -s \"Bacula: Intervention needed \
+ for %j\" %r"
+ MailOnError = security@example.com = all, !skipped, \
+ !terminate
+ append = "bacula/bin/log" = all, !skipped, !terminate
+ operator = security@example.com = mount
+ console = all, !skipped, !saved
+}
+\end{verbatim}
+\normalsize
--- /dev/null
+%%
+%%
+
+\chapter{Monitor Configuration}
+\label{_MonitorChapter}
+\index[general]{Monitor Configuration }
+\index[general]{Configuration!Monitor }
+
+The Monitor configuration file is a stripped down version of the Director
+configuration file, mixed with a Console configuration file. It simply
+contains the information necessary to contact Directors, Clients, and Storage
+daemons you want to monitor.
+
+For a general discussion of configuration file and resources including the
+data types recognized by {\bf Bacula}, please see the
+\ilink{Configuration}{ConfigureChapter} chapter of this manual.
+
+The following Monitor Resource definition must be defined:
+
+\begin{itemize}
+\item
+ \ilink{Monitor}{MonitorResource} -- to define the Monitor's
+ name used to connect to all the daemons and the password used to connect to
+the Directors. Note, you must not define more than one Monitor resource in
+the Monitor configuration file.
+\item At least one
+ \ilink{Client}{ClientResource1},
+ \ilink{Storage}{StorageResource1} or
+\ilink{Director}{DirectorResource2} resource, to define the
+daemons to monitor.
+\end{itemize}
+
+\section{The Monitor Resource}
+\label{MonitorResource}
+\index[general]{Monitor Resource }
+\index[general]{Resource!Monitor }
+
+The Monitor resource defines the attributes of the Monitor running on the
+network. The parameters you define here must be configured as a Director
+resource in Clients and Storages configuration files, and as a Console
+resource in Directors configuration files.
+
+\begin{description}
+
+\item [Monitor]
+ \index[fd]{Monitor }
+ Start of the Monitor records.
+
+\item [Name = \lt{}name\gt{}]
+ \index[fd]{Name }
+ Specify the Director name used to connect to Client and Storage, and the
+Console name used to connect to Director. This record is required.
+
+\item [Password = \lt{}password\gt{}]
+ \index[fd]{Password }
+ Where the password is the password needed for Directors to accept the Console
+connection. This password must be identical to the {\bf Password} specified
+in the {\bf Console} resource of the
+\ilink{Director's configuration}{DirectorChapter} file. This
+record is required if you wish to monitor Directors.
+
+\item [Refresh Interval = \lt{}time\gt{}]
+ \index[fd]{Refresh Interval }
+ Specifies the time to wait between status requests to each daemon. It can't
+be set to less than 1 second, or more than 10 minutes, and the default value
+is 5 seconds.
+% TODO: what is format of the time?
+% TODO: should the digits in this definition be spelled out? should
+% TODO: this say "time-period-specification" above??)
+\end{description}
+
+\section{The Director Resource}
+\label{DirectorResource2}
+\index[general]{Director Resource }
+\index[general]{Resource!Director }
+
+The Director resource defines the attributes of the Directors that are
+monitored by this Monitor.
+
+As you are not permitted to define a Password in this resource, to avoid
+obtaining full Director privileges, you must create a Console resource in the
+\ilink{Director's configuration}{DirectorChapter} file, using the
+Console Name and Password defined in the Monitor resource. To avoid security
+problems, you should configure this Console resource to allow access to no
+other daemons, and permit the use of only two commands: {\bf status} and {\bf
+.status} (see below for an example).
+
+You may have multiple Director resource specifications in a single Monitor
+configuration file.
+
+\begin{description}
+
+\item [Director]
+ \index[fd]{Director }
+ Start of the Director records.
+
+\item [Name = \lt{}name\gt{}]
+ \index[fd]{Name }
+ The Director name used to identify the Director in the list of monitored
+daemons. It is not required to be the same as the one defined in the Director's
+configuration file. This record is required.
+
+\item [DIRPort = \lt{}port-number\gt{}]
+ \index[fd]{DIRPort }
+ Specify the port to use to connect to the Director. This value will most
+likely already be set to the value you specified on the {\bf
+\verb:--:with-base-port} option of the {\bf ./configure} command. This port must be
+identical to the {\bf DIRport} specified in the {\bf Director} resource of
+the
+\ilink{Director's configuration}{DirectorChapter} file. The
+default is 9101 so this record is not normally specified.
+
+\item [Address = \lt{}address\gt{}]
+ \index[fd]{Address }
+ Where the address is a host name, a fully qualified domain name, or a network
+address used to connect to the Director. This record is required.
+\end{description}
+
+\section{The Client Resource}
+\label{ClientResource1}
+\index[general]{Resource!Client }
+\index[general]{Client Resource }
+
+The Client resource defines the attributes of the Clients that are monitored
+by this Monitor.
+
+You must create a Director resource in the
+\ilink{Client's configuration}{FiledConfChapter} file, using the
+Director Name defined in the Monitor resource. To avoid security problems, you
+should set the {\bf Monitor} directive to {\bf Yes} in this Director resource.
+
+
+You may have multiple Director resource specifications in a single Monitor
+configuration file.
+
+\begin{description}
+
+\item [Client (or FileDaemon)]
+ \index[fd]{Client (or FileDaemon) }
+ Start of the Client records.
+
+\item [Name = \lt{}name\gt{}]
+ \index[fd]{Name }
+ The Client name used to identify the Director in the list of monitored
+daemons. It is not required to be the same as the one defined in the Client's
+configuration file. This record is required.
+
+\item [Address = \lt{}address\gt{}]
+ \index[fd]{Address }
+ Where the address is a host name, a fully qualified domain name, or a network
+address in dotted quad notation for a Bacula File daemon. This record is
+required.
+
+\item [FD Port = \lt{}port-number\gt{}]
+ \index[fd]{FD Port }
+ Where the port is a port number at which the Bacula File daemon can be
+contacted. The default is 9102.
+
+\item [Password = \lt{}password\gt{}]
+ \index[fd]{Password }
+ This is the password to be used when establishing a connection with the File
+services, so the Client configuration file on the machine to be backed up
+must have the same password defined for this Director. This record is
+required.
+\end{description}
+
+\section{The Storage Resource}
+\label{StorageResource1}
+\index[general]{Resource!Storage }
+\index[general]{Storage Resource }
+
+The Storage resource defines the attributes of the Storages that are monitored
+by this Monitor.
+
+You must create a Director resource in the
+\ilink{Storage's configuration}{StoredConfChapter} file, using the
+Director Name defined in the Monitor resource. To avoid security problems, you
+should set the {\bf Monitor} directive to {\bf Yes} in this Director resource.
+
+
+You may have multiple Director resource specifications in a single Monitor
+configuration file.
+
+\begin{description}
+
+\item [Storage]
+ \index[fd]{Storage }
+ Start of the Storage records.
+
+\item [Name = \lt{}name\gt{}]
+ \index[fd]{Name }
+ The Storage name used to identify the Director in the list of monitored
+daemons. It is not required to be the same as the one defined in the Storage's
+configuration file. This record is required.
+
+\item [Address = \lt{}address\gt{}]
+ \index[fd]{Address }
+ Where the address is a host name, a fully qualified domain name, or a network
+address in dotted quad notation for a Bacula Storage daemon. This record is
+required.
+
+\item [SD Port = \lt{}port\gt{}]
+ \index[fd]{SD Port }
+ Where port is the port to use to contact the storage daemon for information
+and to start jobs. This same port number must appear in the Storage resource
+of the Storage daemon's configuration file. The default is 9103.
+
+\item [Password = \lt{}password\gt{}]
+ \index[sd]{Password }
+ This is the password to be used when establishing a connection with the
+Storage services. This same password also must appear in the Director
+resource of the Storage daemon's configuration file. This record is required.
+
+\end{description}
+
+\section{Tray Monitor Security}
+\index[general]{Tray Monitor Security}
+
+There is no security problem in relaxing the permissions on
+tray-monitor.conf as long as FD, SD and DIR are configured properly, so
+the passwords contained in this file only gives access to the status of
+the daemons. It could be a security problem if you consider the status
+information as potentially dangerous (I don't think it is the case).
+
+Concerning Director's configuration: \\
+In tray-monitor.conf, the password in the Monitor resource must point to
+a restricted console in bacula-dir.conf (see the documentation). So, if
+you use this password with bconsole, you'll only have access to the
+status of the director (commands status and .status).
+It could be a security problem if there is a bug in the ACL code of the
+director.
+
+Concerning File and Storage Daemons' configuration:\\
+In tray-monitor.conf, the Name in the Monitor resource must point to a
+Director resource in bacula-fd/sd.conf, with the Monitor directive set
+to Yes (once again, see the documentation).
+It could be a security problem if there is a bug in the code which check
+if a command is valid for a Monitor (this is very unlikely as the code
+is pretty simple).
+
+
+\section{Sample Tray Monitor configuration}
+\label{SampleConfiguration1}
+\index[general]{Sample Tray Monitor configuration}
+
+An example Tray Monitor configuration file might be the following:
+
+\footnotesize
+\begin{verbatim}
+#
+# Bacula Tray Monitor Configuration File
+#
+Monitor {
+ Name = rufus-mon # password for Directors
+ Password = "GN0uRo7PTUmlMbqrJ2Gr1p0fk0HQJTxwnFyE4WSST3MWZseR"
+ RefreshInterval = 10 seconds
+}
+
+Client {
+ Name = rufus-fd
+ Address = rufus
+ FDPort = 9102 # password for FileDaemon
+ Password = "FYpq4yyI1y562EMS35bA0J0QC0M2L3t5cZObxT3XQxgxppTn"
+}
+Storage {
+ Name = rufus-sd
+ Address = rufus
+ SDPort = 9103 # password for StorageDaemon
+ Password = "9usxgc307dMbe7jbD16v0PXlhD64UVasIDD0DH2WAujcDsc6"
+}
+Director {
+ Name = rufus-dir
+ DIRport = 9101
+ address = rufus
+}
+\end{verbatim}
+\normalsize
+
+\subsection{Sample File daemon's Director record.}
+\index[general]{Sample File daemon's Director record. }
+\index[general]{Record!Sample File daemon's Director }
+
+Click
+\ilink{here to see the full example.}{SampleClientConfiguration}
+
+
+\footnotesize
+\begin{verbatim}
+#
+# Restricted Director, used by tray-monitor to get the
+# status of the file daemon
+#
+Director {
+ Name = rufus-mon
+ Password = "FYpq4yyI1y562EMS35bA0J0QC0M2L3t5cZObxT3XQxgxppTn"
+ Monitor = yes
+}
+\end{verbatim}
+\normalsize
+
+\subsection{Sample Storage daemon's Director record.}
+\index[general]{Record!Sample Storage daemon's Director }
+\index[general]{Sample Storage daemon's Director record. }
+
+Click
+\ilink{here to see the full example.}{SampleConfiguration}
+
+\footnotesize
+\begin{verbatim}
+#
+# Restricted Director, used by tray-monitor to get the
+# status of the storage daemon
+#
+Director {
+ Name = rufus-mon
+ Password = "9usxgc307dMbe7jbD16v0PXlhD64UVasIDD0DH2WAujcDsc6"
+ Monitor = yes
+}
+\end{verbatim}
+\normalsize
+
+\subsection{Sample Director's Console record.}
+\index[general]{Record!Sample Director's Console }
+\index[general]{Sample Director's Console record. }
+
+Click
+\ilink{here to see the full
+example.}{SampleDirectorConfiguration}
+
+\footnotesize
+\begin{verbatim}
+#
+# Restricted console used by tray-monitor to get the status of the director
+#
+Console {
+ Name = Monitor
+ Password = "GN0uRo7PTUmlMbqrJ2Gr1p0fk0HQJTxwnFyE4WSST3MWZseR"
+ CommandACL = status, .status
+}
+\end{verbatim}
+\normalsize
--- /dev/null
+%%
+%%
+
+\chapter{D\'emarrer avec Bacula}
+\label{_ChapterStart37}
+\index[general]{Bacula!D\'emarrer avec }
+\index[general]{D\'emarrer avec Bacula }
+
+Si vous \^etes comme moi, vous voulez faire fonctionner Bacula imm\'ediatement
+pour en avoir un aper\c{c}u, puis, plus tard, vous reviendrez en arri\`ere
+pour lire et conna{\^\i}tre tous les d\'etails. C'est exactement ce que ce
+chapitre se propose d'accomplir : vous faire avancer rapidement sans tous les
+d\'etails. Si vous voulez sauter la section sur les Pools, Volumes et Labels,
+vous pourrez toujours y revenir, mais s'il vous pla\^it, veuillez lire ce
+chapitre jusqu'\`a la fin, et en particulier suivre les instructions pour
+tester votre lecteur de bandes.
+
+Nous supposons que vous \^etes parvenus \`a construire et installer Bacula,
+sinon, vous devriez d'abord jeter un oeil aux
+\ilink{Pr\'erequis (syst\`eme)}{SysReqs} puis au chapitre
+\ilink{Compiler et installer Bacula}{_ChapterStart17} de ce manuel.
+
+\label{JobsandSchedules}
+\section{Comprendre les Jobs et Schedules}
+\index[general]{Jobs!Comprendre}
+\index[general]{Schedules!Comprendre}
+\addcontentsline{toc}{section}{Comprendre les Jobs et Schedules}
+
+Afin de rendre Bacula aussi flexible que possible, les directives lui sont
+donn\'ees en plusieurs endroits. L'instruction principale est la ressource Job,
+qui d\'efinit un job. Un job de type sauvegarde consiste en g\'en\'eral en un
+FileSet, un client, un Schedule pour un ou plusieurs niveaux ou horaires de sauvegardes,
+un Pool, ainsi que des instructions additionnelles. Un autre point de vue
+est de consid\'erer le FileSet comme "Que sauvegarder ?", le Client comme
+"Qui sauvegarder ?", le Schedule comme "Quand sauvegarder ?" et le Pool
+comme "O\`u sauvegarder ?" (c'est \`a dire, "Sur quel volume ?)
+
+Typiquement, une combinaison FileSet/Client aura un job correspondant. La plupart
+des directives, telles que les FileSets, Pools, Schedules, peuvent \^etre
+m\'elang\'ees et partag\'ees entre les jobs. Ainsi, vous pouvez avoir deux d\'efinitions
+(ressources) de jobs sauvegardant diff\'erents serveurs et utilisant les m\^emes
+Schedule, FileSet (sauvegardant donc les m\^emes r\'epertoires sur les deux
+machines) et peut-\^etre m\^eme les m\^emes Pools. Le Schedule d\'efinira quel
+type de sauvegarde sera ex\'ecut\'e et \`a quel moment (par exemple les Full le
+mercredi, les incr\'ementales le reste de la semaine), et lorsque plus d'un job
+utilise le m\^eme Schedule la priorit\'e du job d\'etermine lequel d\'emarre en premier.
+Si vous avez de nombreux jobs, vous devriez utiliser la directive JobDefs,
+qui vous permet de d\'efinir des param\`etres par d\'efaut pour vos jobs, qui peuvent \^etre
+chang\'es au sein de la ressource Job, mais qui vous \'evitent de r\'e\'ecrire les m\^emes
+param\`etres pour chaque job. En plus des FileSets que vous voulez sauvegarder,
+vous devriez aussi avoir un job qui sauvegarde votre catalogue.
+
+Enfin, sachez qu'en plus des jobs de type Backup, vous pouvez aussi utiliser
+des jobs de type restore, verify, admin, qui ont chacun des exigences
+diff\'erentes.
+
+\label{PoolsVolsLabels}
+
+\section{Comprendre les Pools, Volumes et Labels}
+\index[general]{Comprendre les Pools, Volumes et Labels }
+\index[general]{Labels!Comprendre les Pools Volumes et }
+\addcontentsline{toc}{section}{Comprendre les Pools, Volumes et Labels}
+
+Si vous avez utilis\'e un programme tel que {\bf tar} pour sauvegarder votre
+syst\`eme, les notions de Pools, Volumes et labels peuvent vous sembler un peu
+confuses au premier abord. Un Volume est un simple support physique
+(cartouche, ou simple fichier) sur lequel Bacula \'ecrit vos donn\'ees de
+sauvegarde. Les Pools regroupent les Volumes de sorte qu'une sauvegarde n'est
+pas restreinte \`a la capacit\'e d'un unique Volume. Par cons\'equent,
+plut\^ot que de nommer explicitement les Volumes dans votre Job, vous
+sp\'ecifiez un Pool, et Bacula se chargera de s\'electionner le prochain
+Volume utilisable du Pool et vous demandera de le monter.
+
+Bien que les options de base soient sp\'ecifi\'ees dans la ressource Pool du
+fichier de configuration du Director, le Pool {\bf r\'eel} est g\'er\'e par le
+Catalogue Bacula. Il contient les informations de la ressource Pool
+(bacula-dir.conf) ainsi que les informations concernant tous les Volumes qui
+ont \'et\'e ajout\'es au Pool. L'ajout de Volumes se fait en principe
+manuellement depuis la Console gr\^ace \`a la commande {\bf label}.
+
+Pour chaque Volume, Bacula g\`ere une quantit\'e d'informations consid\'erable
+telles que les premi\`ere et derni\`ere date et heure d'\'ecriture, le nombre
+de fichiers sur le Volume, le nombre de bytes sur le Volume, le nombre de
+montages, etc.
+
+Pour que Bacula puisse lire ou \'ecrire sur un Volume physique, celui-ci doit
+avoir re\c{c}u un \'etiquettage logiciel afin que Bacula soit assur\'e que le
+bon Volume est mont\'e. Ceci s'effectue en principe manuellement depuis la
+Console gr\^ace \`a la commande {\bf label}.
+
+Les \'etapes de cr\'eation de Pool, ajout de Volumes \`a ce Pool, et
+\'ecriture d'\'etiquettes logicielles sur les Volumes, peuvent sembler
+p\'enibles au premier abord, mais en fait, elles sont tout \`a fait simples
+\`a franchir, et elles vous permettent d'utiliser plusieurs Volumes (plut\^ot
+que d'\^etre limit\'e \`a la capacit\'e d'un seul). Les Pools vous procurent
+aussi une flexibilit\'e importante pour votre politique de sauvegarde. Par
+exemple, vous pouvez avoir un Pool de Volumes "Daily" pour vos sauvegardes
+Incr\'ementales et un Pool de Volumes "Weekly" pour vos sauvegardes
+compl\`etes (Full). En sp\'ecifiant le Pool appropri\'e dans les Jobs de
+sauvegarde quotidiens et hebdomadaires, vous garantissez qu'aucun Job
+quotidien n'\'ecrira jamais sur un Volume du Pool r\'eserv\'e aux sauvegardes
+hebdomadaire et vice versa, et Bacula vous dira quelle cartouche est requise,
+et quand.
+
+Pour plus de d\'etails concernant les Pools, consultez la section
+\ilink{Ressource Pool}{PoolResource} du chapitre sur la
+configuration du Director, ou poursuivez votre lecture, nous reviendrons plus
+tard sur ce sujet.
+
+\section{Param\'etrage des fichiers de configuration de Bacula}
+\label{config}
+\index[general]{Param\'etrage des fichiers de configuration de Bacula }
+\index[general]{Bacula!Param\'etrage des fichiers de configuration de }
+\addcontentsline{toc}{section}{Param\'etrage des fichiers de configuration
+de Bacula}
+
+Apr\`es avoir ex\'ecut\'e la commande {\bf ./configure} {\it ad hoc}, {\bf
+make} et {\bf make install}, si c'est la premi\`ere fois que vous ex\'ecutez
+Bacula, vous devez cr\'eer des fichiers de configuration valides pour le
+Director, le File Daemon, le Storage Daemon et le programme Console. Si vous
+avez suivi nos recommandations, des fichiers de configuration par d\'efaut
+ainsi que les binaires des {\it daemons} seront situ\'es dans votre
+r\'epertoire d'installation. Dans tous les cas les binaires se trouvent dans
+le r\'epertoire que vous avez sp\'ecifi\'e au niveau de l'option {\bf
+\verb{--{sbindir} de la commande {\bf ./configure}, et les fichiers de configuration
+se trouvent dans le r\'epertoire que vous avez sp\'ecifi\'e au niveau de
+l'option {\bf \verb{--{sysconfdir}.
+
+Lors des param\'etrages initiaux de Bacula, il vous faudra investir un peu de
+temps pour modifier les fichiers de configuration par d\'efaut afin de
+les adapter \`a votre environnement. Ceci peut n\'ecessiter de red\'emarrer
+Bacula plusieurs fois jusqu'\`a ce que tout fonctionne correctement. Ne
+c\'edez pas au d\'esespoir. Une fois que vous aurez cr\'e\'e vos fichiers de
+configuration, vous n'aurez que rarement besoin de les changer et de
+red\'emarrer Bacula. Le gros du travail consistera \`a changer la cartouche
+quand elle est pleine.
+
+\subsection{
+\ilink{Configurer le programme Console}{_ChapterStart36}}
+\index[general]{Console!Configurer le programme }
+\index[general]{Configurer le programme Console }
+\addcontentsline{toc}{subsection}{Configurer le programme Console}
+
+Le programme console est utilis\'e par l'administrateur pour interagir avec le
+Director et pour arr\^eter et d\'emarrer manuellement des jobs, ou encore pour
+obtenir des informations sur les jobs en cours d'ex\'ecution ou programm\'es.
+
+Le fichier de configuration de la Console se trouve dans le r\'epertoire que
+vous avez sp\'ecifi\'e au niveau de l'option {\bf \verb{--{sysconfdir} de la commande
+{\bf ./configure} et par d\'efaut se nomme {\bf console.conf}.
+
+Si vous avez choisi de construire la Console GNOME avec l'option {\bf
+\verb{--{enable-gnome}, vous y trouverez \'egalement son fichier de configuration par
+d\'efaut, nomm\'e {\bf gnome-console.conf}.
+
+Il en va de m\^eme pour la console wxWidgets, qui est construite par l'option
+{\bf \verb{--{enable-bwx-console}, et le nom du fichier de configuration par d\'efaut
+est, dans ce cas, {\bf bwx-console.conf}.
+
+Normalement, pour les nouveaux
+utilisateurs, aucune modification n'est requise pour ces fichiers. Les
+r\'eglages par d\'efaut sont raisonnables.
+
+\subsection{
+\ilink{Configurer le programme Monitor}{_ChapterStart35}}
+\index[general]{Monitor!Configurer le programme }
+\index[general]{Configurer le programme Monitor }
+\addcontentsline{toc}{subsection}{Configurer le programme Monitor}
+
+Le programme Monitor est typiquement une ic\^one dans la barre des t\^aches.
+Cependant, lorsque l'ic\^one est \'etendue en une fen\`etre, l'administrateur ou
+l'utilisateur peut obtenir des informations concernant le Director ou l'\'etat
+des sauvegardes sur la machine locale ou n'importe quelle autre {\it daemon}
+Bacula configur\'e.
+
+\includegraphics{./Bacula-tray-monitor.eps}
+
+L'image montre le tray-monitor configur\'e pour trois {\it daemons}. En
+cliquant sur les boutons radio dans le coin en haut \`a gauche de l'image,
+vous pouvez voir l'\'etat de chacun des {\it daemons}. L'image montre l'\'etat
+du Storage Daemon (MainSD) s\'electionn\'e.
+
+Le fichier de configuration du Monitor se trouve dans le r\'epertoire
+sp\'ecifi\'e au niveau de l'option {\bf \verb{--{sysconfdir} de la commande {\bf
+./configure} et se nomme par d\'efaut {\bf tray-monitor.conf}. En principe,
+pour les nouveaux utilisateurs, il suffit de changer les permissions de ce
+fichier pour permettre aux utilisateurs non-root d'ex\'ecuter le Monitor, en
+effet cette application doit \^etre ex\'ecut\'e par le m\^eme utilisateur que
+l'environnement graphique (n'oubliez pas de donner aux non-root le droit
+d'ex\'ecuter {\bf bacula-tray-monitor}). Ceci ne constitue pas une faille de
+s\'ecurit\'e tant que vous utilisez les r\'eglages par d\'efaut.
+
+\subsection{
+\ilink{Configurer le File Daemon}{_ChapterStart25}}
+\index[general]{Configurer le File Daemon }
+\index[general]{Daemon!Configurer le File }
+\addcontentsline{toc}{subsection}{Configurer le File Daemon}
+
+Le File Daemon, est le programme qui s'ex\'ecute sur chaque machine cliente. A
+la demande du Director, il d\'etermine les fichiers \`a sauvegarder et les
+exp\'edie au Storage Daemon.
+
+Le fichier de configuration du File Daemon se trouve dans le r\'epertoire
+sp\'ecifi\'e au niveau de l'option {\bf \verb{--{sysconfdir} de la commande {\bf
+./configure} et se nomme par d\'efaut {\bf bacula-fd.conf}. Normalement, pour
+les nouveaux utilisateurs, aucune modification n'est requise pour ce fichier.
+Les r\'eglages par d\'efaut sont raisonnables. Cependant, si vous envisagez de
+sauvegarder plus d'une machine, il vous faudra installer le File Daemon avec
+un fichier de configuration sp\'ecifique sur chaque machine \`a sauvegarder.
+Les informations concernant chaque File Daemon doivent appara{\^\i}tre dans le
+fichier de configuration du Director.
+
+\subsection{
+\ilink{Configurer le Director}{_ChapterStart40}}
+\index[general]{Director!Configurer le }
+\index[general]{Configurer le Director }
+\addcontentsline{toc}{subsection}{Configurer le Director}
+
+Le director est le programme central qui contr\^ole tous les autres {\it
+daemons}. Il planifie et surveille les jobs \`a ex\'ecuter.
+
+Le fichier de configuration du Director se trouve dans le r\'epertoire
+sp\'ecifi\'e au niveau de l'option {\bf \verb{--{sysconfdir} de la commande {\bf
+./configure} et se nomme par d\'efaut {\bf bacula-dir.conf}.
+
+En g\'en\'eral, la seule modification n\'ecessaire consiste \`a faire en sorte
+que la directive {\bf Include} de la Ressource FileSet contienne au moins une
+ligne avec un nom de fichier ou de r\'epertoire valide \`a sauvegarder.
+
+Si vous ne poss\'edez pas de lecteur DLT, vous voudrez probablement modifier
+la ressource Storage pour donner un nom plus repr\'esentatif de votre
+p\'eriph\'erique de stockage. Vous pouvez toujours utiliser les noms existants
+puisque vous \^etes libre de les assigner arbitrairement, mais ils doivent
+s'accorder avec les noms correspondants dans le fichier de configuration du
+Storage Daemon.
+
+Vous pouvez aussi changer l'adresse \'electronique pour les notifications vers
+votre propre adresse e-mail plut\^ot que vers celle de {\bf root}
+(configuration par d\'efaut).
+
+Enfin, si vous avez plusieurs syst\`emes \`a sauvegarder, il vous faudra
+sp\'ecifier un File Daemon (ou client) pour chaque syst\`eme sauvegard\'e,
+pr\'ecisant ses nom, adresse et mot de passe. Nous estimons que baptiser vos
+{\it daemons} du nom de vos syst\`emes suffix\'es avec {\bf -fd} aide beaucoup
+\`a corriger les erreurs. Ainsi, si votre syst\`eme est {\bf foobaz}, vous
+nommerez le {\it daemon} {\bf foobaz-fd}. Pour le Director, vous pourriez
+utiliser {\bf foobaz-dir}, et {\bf foobaz-sd} pour le Storage Daemon.
+Chacun de vos composants de Bacula {\bf doit} avoir un nom unique
+Si vous les nommez tous \`a l'identique, en plus de ne jamais savoir
+quel {\it daemon} envoie quel message, s'ils partagent le m\^eme r\'epertoire
+de travail (working directory), les noms de fichiers temporaires des {\it daemons}
+ne seront pas uniques et vous aurez d'\'etranges erreurs.
+
+\subsection{
+\ilink{Configurer le Storage Daemon}{_ChapterStart31}}
+\index[general]{Daemon!Configurer le Storage }
+\index[general]{Configurer le Storage Daemon }
+\addcontentsline{toc}{subsection}{Configurer le Storage Daemon}
+
+Le Storage Daemon est responsable, sur demande du Director, de la r\'eception
+des donn\'ees en provenance des File Daemons, et de leur \'ecriture sur le
+medium de stockage, ou, dans le cas d'une restauration, de trouver les
+donn\'ees pour les envoyer vers le File Daemon.
+
+Le fichier de configuration du Storage Daemon se trouve dans le r\'epertoire
+sp\'ecifi\'e au niveau de l'option {\bf \verb{--{sysconfdir} de la commande {\bf
+./configure} et se nomme par d\'efaut {\bf bacula-sd.conf}. Modifiez ce
+fichier pour accorder les noms de p\'eriph\'eriques de stockage \`a ceux que
+vous poss\'edez. Si le processus d'installation a convenablement d\'etect\'e
+votre syst\`eme, elles seront d\'ej\`a correctement r\'egl\'ees. Ces
+ressources de stockage "Name" et "Media Type" doivent \^etre les m\^emes
+que leurs correspondantes du fichier de configuration du Director {\bf
+bacula-dir.conf}. Si vous souhaitez sauvegarder vers un fichier plut\^ot que
+sur des bandes, la ressource Device doit pointer vers un r\'epertoire o\`u des
+fichiers seront cr\'e\'es en guise de Volumes lorque vous \'etiquetterez
+(label) vos Volumes.
+\label{ConfigTesting}
+
+\section{Tester vos Fichiers de Configuration}
+\index[general]{Configuration!Tester vos Fichiers de }
+\index[general]{Tester vos Fichiers de Configuration }
+\addcontentsline{toc}{section}{Tester vos Fichiers de Configuration}
+
+Vous pouvez tester la validit\'e syntaxique de vos fichiers de configuration,
+afficher tout message d'erreur et terminer. Par exemple, en supposant que vous
+avez install\'e vos binaires et fichiers de configuration dans le m\^eme
+r\'epertoire,
+
+\footnotesize
+\begin{verbatim}
+cd <installation-directory>
+./bacula-dir -t -c bacula-dir.conf
+./bacula-fd -t -c bacula-fd.conf
+./bacula-sd -t -c bacula-sd.conf
+./bconsole -t -c bconsole.conf
+./gnome-console -t -c gnome-console.conf
+./bwx-console -t -c wx-console.conf
+su <normal user> -c "./bacula-tray-monitor -t -c tray-monitor.conf"
+\end{verbatim}
+\normalsize
+
+testera le fichier de configuration de chacun des principaux programmes. Si le
+fichier de configuration est correct, le programme se termine
+sans rien afficher. Veuillez noter que selon les options de configuration que
+vous avez choisies, il se peut qu'aucune des commandes ci-dessus ne soit
+valable sur votre syst\`eme. Si vous avez install\'e les binaires dans les
+r\'epertoires traditionnels d'Unix plut\^ot que dans un simple r\'epertoire,
+il vous faudra modifier les commandes ci-dessus en cons\'equence (pas de
+"./" devant les commandes, et un chemin devant les fichiers de
+configuration).
+\label{TapeTesting}
+
+\section{Tester la compatibilit\'e de Bacula avec votre lecteur de bandes}
+\index[general]{Tester la compatibilit\'e de Bacula avec votre lecteur de
+bandes }
+\index[general]{Bandes!Tester la compatibilit\'e de Bacula avec votre lecteur
+de }
+\addcontentsline{toc}{section}{Tester la compatibilit\'e de Bacula avec
+votre lecteur de bandes}
+
+Avant de gaspiller votre temps avec Bacula pour finalement constater qu'il ne
+fonctionne pas avec votre lecteur de bandes, veuillez s'il vous pla\^it lire le
+chapitre
+\ilink{btape -- Tester votre lecteur de bandes}{_ChapterStart27}
+de ce manuel. Si vous poss\'edez un lecteur standard SCSI moderne sur un Linux
+ou un Solaris, fort probablement, il fonctionnera, mais mieux vaut tester que
+d'\^etre d\'e\c{c}u. Pour FreeBSD (et probablement les autres xBSD), la
+lecture du chapitre mentionn\'e ci-dessus est un devoir. Pour FreeBSD,
+consultez aussi
+\elink{The FreeBSD Diary}{http://www.freebsddiary.org/bacula.php} pour une
+description d\'etaill\'ee de la m\'ethode pour faire fonctionner Bacula sur
+votre syst\`eme. De plus, les utilisateurs de versions de FreeBSD
+ant\'erieures \`a 4.9-STABLE dat\'ee du lundi 29 d\'ecembre 2003 15:18:01 UTC
+qui pr\'evoient d'utiliser des lecteurs de bandes sont invit\'es \`a lire le
+fichier {\bf platforms/freebsd/pthreads-fix.txt} du r\'epertoire principal de
+Bacula, qui contient d'importantes informations sur la compatibilit\'e de
+Bacula avec leur syst\`eme.
+\label{notls}
+
+\section{D\'ebarrassez-vous du r\'epertoire /lib/tls}
+\index[general]{D\'ebarrassez-vous du r\'epertoire /lib/tls }
+\addcontentsline{toc}{section}{D\'ebarrassez-vous du r\'epertoire /lib/tls}
+
+La nouvelle librairie pthreads {\bf /lib/tls} install\'ee par d\'efaut sur les
+syst\`emes Red Hat r\'ecents (kernels 2.4.x) est d\'efectueuse. Vous devez la
+supprimer ou la renommer, puis rebooter votre syst\`eme avant d'ex\'ecuter
+Bacula, faute de quoi, apr\`es environ une semaine de fonctionnement, Bacula
+se bloquera pour de longues p\'eriodes, voire d\'efinitivement. Veuillez consulter
+le chapitre \ilink{Syst\`emes support\'es}{SupportedOSes} pour plus
+d'informations sur ce probl\`eme.
+
+Ce probl\`eme n'existe plus avec les noyaux 2.6.
+
+\label{Running1}
+
+\section{Ex\'ecuter Bacula}
+\index[general]{Bacula!Ex\'ecuter }
+\index[general]{Ex\'ecuter Bacula }
+\addcontentsline{toc}{section}{Ex\'ecuter Bacula}
+
+La partie la plus importante de l'ex\'ecution de Bacula est probablement la
+capacit\'e de restaurer les fichiers. Si vous n'avez pas essay\'e de
+r\'ecup\'erer des fichiers au moins une fois, vous subirez une bien plus forte
+pression le jour o\`u vous devrez r\'eellement le faire, et serez enclin \`a
+commettre des erreurs que vous n'auriez pas commises si vous aviez d\'ej\`a
+essay\'e.
+
+Pour avoir rapidement une bonne id\'ee de la fa\c{c}on d'utiliser Bacula,
+nous vous recommandons {\bf fortement} de suivre les exemples du
+\ilink{chapitre ex\'ecuter Bacula}{_ChapterStart1} de ce manuel,
+o\`u vous trouverez des informations d\'etaill\'ees sur l'ex\'ecution de
+Bacula.
+
+\section{Rotation des logs}
+\index[general]{Logs!Rotation des }
+\index[general]{Rotation des logs }
+\addcontentsline{toc}{section}{Rotation des logs}
+
+Si vous utilisez le {\bf bacula-dir.conf} par d\'efaut ou une variante, vous
+constaterez qu'il r\'ecup\`ere toutes les sorties de Bacula dans un fichier.
+Pour \'eviter que ce fichier ne croisse sans limites, nous vous recommandons
+de copier le fichier {\bf logrotate} depuis {\bf scripts/logrotate} vers {\bf
+/etc/logrotate.d/bacula}. Ainsi les fichiers de logs subiront une rotation
+mensuelle et seront conserv\'es pour une dur\'ee maximum de cinq mois. Vous
+pouvez \'editer ce fichier pour adapter la rotation \`a votre convenance.
+
+\section{Log Watch}
+\index[general]{Watch!Log}
+\index[general]{Log Watch}
+\addcontentsline{toc}{section}{Log Watch}
+Certains syst\`emes tels que RedHat et Fedora ex\'ecutent le programme
+logwatch chaque nuit pour analyser vos fichiers de log et vous
+envoyer un rapport par mail. Si vous souhaitez inclure la sortie
+de vos jobs Bacula dans ce rapport, veuillez regarder dans le r\'epertoire
+{\bf scripts/logwatch}. Le fichier {\bf README} fournit une br\`eve
+explication sur la fa\c {c}on d'installer le script, et quelle genre
+de r\'esultats en attendre.
+
+\section{Reprise d'activit\'e apr\`es un d\'esastre (disaster recovery)}
+\index[general]{Recovery!Reprise d'activit\'e apr\`es un d\'esastre disaster }
+\index[general]{Reprise d'activit\'e apr\`es un d\'esastre (disaster recovery)
+}
+\addcontentsline{toc}{section}{Reprise d'activit\'e apr\`es un d\'esastre
+(disaster recovery)}
+
+Si vous avez l'intention d'utiliser Bacula en tant qu'outil de disaster
+recovery plut\^ot que comme un simple programme pour restaurer les fichiers
+perdus, vous serez int\'eress\'e par le
+\ilink{chapitre Plan de reprise d'activit\'e avec
+Bacula}{_ChapterStart38} de ce manuel.
+
+De toute fa\c{c}on, vous \^etes fortement invit\'e \`a tester soigneusement
+la restauration de quelques fichiers que vous aurez pr\'ealablement
+sauvegard\'es, plut\^ot que d'attendre qu'un d\'esastre ne frappe. Ainsi, vous
+serez pr\'epar\'e.
--- /dev/null
+%%
+%%
+
+\chapter{Consid\'erations sur la s\'ecurit\'e de Bacula}
+\label{_ChapterStart14}
+\index[general]{Bacula!Consid\'erations sur la s\'ecurit\'e de}
+\index[general]{Consid\'erations sur la s\'ecurit\'e de Bacula}
+\index[general]{S\'ecurit\'e}
+
+\begin{itemize}
+\item La s\'ecurit\'e, c'est de pouvoir restaurer vos fichiers, aussi, lisez
+ attentivement le chapitre \ilink{Critical Items Chapter}{Critical} de
+ ce manuel.
+\item Le client ({\bf bacula-fd}) doit \^etre ex\'ecut\'e en tant que root
+ afin d'avoir l'acc\`es \`a tous les fichiers du syst\`eme.
+\item Il n'est pas n\'ecessaire d'ex\'ecuter le Director en tant que root.
+\item Il n'est pas n\'ecessaire d'ex\'ecuter le Storage Daemon en tant que
+ root, mais vous devez vous assurer qu'l peut utiliser le lecteur de bandes,
+ dont l'acc\`es est presque toujours r\'eserv\'e \`a root par d\'efaut.
+ De plus, si vous n'ex\'ecutez pas le Storage Daemon en tant que root, il sera
+ dans l'incapacit\'e de r\'egler automatiquement les param\`etres de votre lecteur
+ de bandes. En effet, ces fonctions requi\`erent les droits root sur la plupart
+ des syst\`emes d'exploitation.
+\item Vous devriez restreindre l'acc\`es au fichiers de configuration de
+ Bacula, de sorte que les mots de passe ne soient pas lisibles par tous. Les
+ {\it daemons} {\bf Bacula} sont prot\'eg\'es par des mots de passe et CRAM-MD5
+(i.e. les mots de passe ne sont pas envoy\'es sur le r\'eseau). Ceci assure
+que tout le monde ne peut acc\'eder aux {\it daemons}. C'est une protection
+raisonnablement bonne, mais qui peut \^etre craqu\'ee par un expert.
+\item Si vous utilisez les ports recommand\'es 9101,9102 et 9103, vous voudrez
+ probablement prot\'eger ces ports des acc\`es externes \`a l'aide d'un
+ firewall et/ou en utilisant tcp wrappers ({\bf etc/hosts.allow}).
+\item Actuellement, toutes les donn\'ees sont envoy\'ees sur le r\'eseau sans
+ chiffrement. Par cons\'equent, \`a moins que vous n'utilisiez {\bf ssh} ou {\bf
+ stunnel} pour la transmission de port (NDT: port forwarding), il n'est pas
+recommand\'e de faire des sauvegardes \`a travers un r\'eseau non
+s\'ecuris\'e (par exemple, Internet). Nous pr\'evoyons d'int\'egrer le
+chiffrage {\bf ssl} dans une version future.
+\item Vous devriez vous assurer que seuls les {\it daemons} de Bacula ont
+ acc\`es en lecture et \'ecriture aux r\'epertoires de travail de Bacula.
+\item Si vous utilisez {\bf MySQL}, il n'est pas n\'ecessaire de l'ex\'ecuter
+ en tant que root
+\item Le script par d\'efaut de Bacula {\bf grant-mysql-permissions} accorde
+ toutes les permissions d'utilisation de la base de donn\'ees MySQL sans mot
+ de passe. Si vous voulez la s\'ecurit\'e, affinez ceci !
+\item N'oubliez pas que Bacula est un programme r\'eseau, ainsi quiconque sur
+ le r\'eseau dispose du programme console et du mot de passe du Director peut
+ acc\'eder \`a Bacula et aux donn\'ees sauvegard\'ees.
+\item Vous pouvez restreindre les adresses IP avec auxquelles Bacula se
+ connectera en utilisant les enregistrements appropri\'es {\bf DirAddress},
+ {\bf FDAddress}, ou {\bf SDAddress} dans les fichiers de configurations
+respectifs des {\it daemons}
+\item Soyez conscient que si vous sauvegardez votre catalogue avec le script
+ par d\'efaut, et si l'acc\`es \`a votre catalogue est prot\'eg\'e par un mot de passe,
+ ce dernier est transmis en tant qu'option de ligne de commande \`a ce script,
+ ce qui le rend visible \`a tout utilisateur du syst\`eme. Si vous voulez
+ s\'ecuriser ce point, vous devez le passer via une variable d'environnement
+ ou un fichier s\'ecuris\'e.
+\end{itemize}
+
+\section{Compatibilit\'e ascendante}
+\index[general]{Compatibilit\'e ascendante}
+\addcontentsline{toc}{section}{Compatibilit\'e ascendante}
+L'un des principaux objectifs de Bacula est de garantir que vous pouvez
+restaurer depuis des cartouches (ou depuis des volumes disque) \'ecrites des ann\'ees
+auparavant. Ceci implique que chaque nouvelle version de Bacula devrait \^etre
+capable de relire les anciens formats de cartouches. Le premier probl\`eme est de
+s'assurer que le mat\'eriel fonctionne encore malgr\'e les ann\'ees, et que les supports
+sont encore valides. Ensuite, votre syst\`eme d'exploitation doit \^etre capable
+de s'interfacer avec le p\'eriph\'erique et finalement, Bacula doit \^etre capable
+de reconna\^itre les anciens formats. De tous ces probl\`emes, nous ne pouvons
+prendre en charge que le dernier, pour les autres, vous devez vous pr\'eparer
+consciencieusement.
+
+Depuis les tous premiers stades de Bacula (janvier 2000) jusqu'\`a aujourd'hui
+(D\'ecembre 2005), Bacula a connu deux formats majeurs d'\'ecriture sur les
+cartouches. Le second format a \'et\'e introduit dans la version 1.27 en
+novembre 2002, et n'a pas chang\'e depuis. En principe, Bacula devrait encore pouvoir
+lire le format d'origine, mais j'avoue ne pas avoir essay\'e depuis longtemps...
+
+Bien que le format des cartouches soit fix\'e, les types de donn\'ees qui peuvent \^etre
+\'ecrites sur les cartouches sont extensibles, ce qui nous a permis d'ajouter de
+nouvelles fonctionnalit\'es telles que les ACLs, les donn\'ees Win32, les donn\'ees
+chiffr\'ees... Naturellement, une ancienne version de Bacula ne saurait lire des
+nouveaux flux de donn\'ees, mais chaque nouvelle version de Bacula est en principe
+capable de lire les anciens flux.
+
+Si vous voulez \^etre absolument certain de pouvoir lire vos vieilles cartouches,
+vous devriez :
+
+1. Essayer de lire les vieilles cartouches de temps en temps, une fois par an
+par exemple.
+
+2. Conserver une copie statiquement li\'ee de chaque version de Bacula que vous
+avez utilis\'ee en production. Ainsi, si pour quelque raison nous venions \`a
+abandonner la compatibilit\'e avec les anciens formats de cartouches, vous pourriez
+toujours remettre en service une vieille copie de Bacula...
+
+Le second point est probablement excessif, en toute rigueur, il pourrait vous
+sauver un jour.
+
+\label{wrappers}
+
+\section{Configurer et tester TCP Wrappers}
+\index[general]{Configurer et tester TCP Wrappers}
+\index[general]{Bacula!Configurer et tester TCP Wrappers}
+\index[general]{TCP Wrappers}
+\index[general]{Wrappers!TCP}
+\index[general]{libwrappers}
+\addcontentsline{toc}{section}{Configurer et tester TCP Wrappers}
+
+Les TCP Wrappers sont impl\'ement\'es si vous les activez lors de la
+configuration ({\bf ./configure \verb{:--:{with-tcp-wrappers}). Avec ce code activ\'e, vous
+pourrez contr\^oler qui peut acc\'eder \`a vos {\it daemons}. Ce contr\^ole
+est obtenu par la modification du fichier {\bf /etc/hosts.allow}. Le nom de
+programme qu'utilise {\bf Bacula} pour appliquer ces restrictions est celui
+que vous avez sp\'ecifi\'e dans le fichier de configuration du {\it daemon}.
+Vous ne devez pas utiliser l'option {\bf twist} dans votre {\bf
+/etc/hosts.allow} car elle stopperait les {\it daemons} Bacula lorsqu'une
+connection est refus\'ee.
+
+Le nom exact du paquet requis pour compiler avec le support TCP wrappers
+d\'epend du syst\`eme. Il s'agit, par exemple, de tcpd-devel sur SuSE, et de
+tcp\_wrappers sur RedHat.
+
+Dan Langille a fourni les informations suivantes concernant la configuration
+et les tests de TCP Wrappers avec Bacula.
+
+Si vous lisez hosts\_options(5), vous verrez une option nomm\'ee twist. Cette
+option remplace le processus courant par une instance de la commande shell
+sp\'ecifi\'ee. Voici un exemple typique de son utilisation :
+
+\footnotesize
+\begin{verbatim}
+ALL : ALL \
+ : severity auth.info \
+ : twist /bin/echo "Vous n'\^etes pas autoris\'e \`a utiliser %d depuis %h."
+\end{verbatim}
+\normalsize
+
+\label{question-1}
+Le code libwrap tente d'\'eviter {\bf twist} s'il est
+ex\'ecut\'e dans un processus r\'esident. Il en r\'esulte que le processus (e.g.
+bacula-fd, bacula-sd, bacula-dir) sera stopp\'e si la premi\`ere connection
+\`a son port provoque l'invocation de l'option twist. Le risque est qu'une
+attaque provoque l'arr\^et des {\it daemons}. Cette situation est \'evit\'ee si votre
+fichier /etc/hosts.allow contient un jeu de r\`egles appropri\'e. L'exemple
+suivant est suffisant :
+
+\footnotesize
+\begin{verbatim}
+undef-fd : localhost : allow
+undef-sd : localhost : allow
+undef-dir : localhost : allow
+undef-fd : ALL : deny
+undef-sd : ALL : deny
+undef-dir : ALL : deny
+\end{verbatim}
+\normalsize
+
+Vous devez accorder les noms des {\it daemons} \`a ceux sp\'ecifi\'es dans leurs
+fichiers de configuration respectifs. Ce ne sont, en g\'en\'eral, pas les noms
+des fichiers binaires des {\it daemons}. Il n'est pas possible d'utiliser
+les noms des binaires car plusieurs {\it daemons} peuvent \^etre ex\'ecut\'es
+sur une machine avec des fichiers de configuration distincts.
+
+Dans ces exemples, le Director est undef-dir, le
+Storage Daemon est undef-sd, et le File Daemon est undef-fd. Ajustez ces noms pour
+qu'ils conviennent \`a votre configuration. L'exemple de r\`egles ci-dessus suppose que
+SD, FD et DIR sont tous sur la m\^eme machine. Si vous avez un client FD
+distant, il vous suffira de placer le jeu de r\`egles suivant sur ce client :
+
+\footnotesize
+\begin{verbatim}
+undef-fd : director.example.org : allow
+undef-fd : ALL : deny
+\end{verbatim}
+\normalsize
+
+O\`u director.example.org est l'h\^ote qui contactera le client (i.e. la
+machine sur laquelle le Bacula Director tourne). L'usage de "ALL : deny"
+assure que l'option twist (si pr\'esente) n'est pas invoqu\'ee. Pour tester
+correctement votre configuration, d\'emarrez le(s) {\it daemon(s)}, puis
+essayez de vous y connecter depuis une adresse IP qui devrait \^etre capable
+de le faire. Vous devriez voir quelque chose comme :
+
+\footnotesize
+\begin{verbatim}
+$ telnet undef 9103
+Trying 192.168.0.56...
+Connected to undef.example.org.
+Escape character is '^]'.
+Connection closed by foreign host.
+$
+\end{verbatim}
+\normalsize
+
+C'est la r\'eponse correcte. Si vous voyez ceci :
+
+\footnotesize
+\begin{verbatim}
+$ telnet undef 9103
+Trying 192.168.0.56...
+Connected to undef.example.org.
+Escape character is '^]'.
+You are not welcome to use undef-sd from xeon.example.org.
+Connection closed by foreign host.
+$
+\end{verbatim}
+\normalsize
+
+Alors, twist a \'et\'e invoqu\'ee, et votre configuration est incorrecte. vous
+devez ajouter la directive "deny". Il est important de noter que vos tests
+doivent inclure le red\'emarrage des {\it daemons} apr\`es chaque tentative de
+connexion. Vous pouvez aussi tcpdchk(8) et tcpdmatch(8) pour valider jeu de
+r\`egles /etc/hosts.allow. Voici un test simple avec tcpdmatch :
+
+\footnotesize
+\begin{verbatim}
+$ tcpdmatch undef-dir xeon.example.org
+warning: undef-dir: no such process name in /etc/inetd.conf
+client: hostname xeon.example.org
+client: address 192.168.0.18
+server: process undef-dir
+matched: /etc/hosts.allow line 40
+option: allow
+access: granted
+\end{verbatim}
+\normalsize
+
+Si vous ex\'ecutez Bacula en tant que {\it standalone daemon}, les
+avertissements ci-dessus peuvent \^etre ignor\'es sans scrupules. Voici un
+exemple qui r\'ev\`ele que "deny" fait defaut \`a vos r\`egles, et que
+l'option twist a \'et\'e invoqu\'ee.
+
+\footnotesize
+\begin{verbatim}
+$ tcpdmatch undef-dir 10.0.0.1
+warning: undef-dir: no such process name in /etc/inetd.conf
+client: address 10.0.0.1
+server: process undef-dir
+matched: /etc/hosts.allow line 91
+option: severity auth.info
+option: twist /bin/echo "You are not welcome to use
+ undef-dir from 10.0.0.1."
+access: delegated
+\end{verbatim}
+\normalsize
+
+\section{Ex\'ecuter Bacula sans \^etre root}
+\index[general]{Root!Ex\'ecuter Bacula sans \^etre }
+\index[general]{Ex\'ecuter Bacula sans \^etre root }
+\addcontentsline{toc}{section}{Ex\'ecuter Bacula sans \^etre root}
+
+Voici quelques recommandations de Dan Languille :
+
+C'est une bonne id\'ee d'ex\'ecuter vos {\it daemons} avec des privil\`eges
+aussi faibles que possible. En d'autres termes, si vous pouvez, n'ex\'ecutez
+pas d'applications en tant que root si elle n'ont pas besoin d'\^etre
+ex\'ecut\'ees en tant que root. Le Storage Daemon et le Director Daemon n'ont
+pas besoin d'\^etre ex\'ecut\'es en tant que root. Le File Daemon en a besoin
+pour acc\'eder \`a l'ensemble des fichiers du syst\`eme. Pour vous passer des
+privil\`eges root, il vous faut cr\'eer un utilisateur et un groupe. Choisir
+{\tt bacula} pour l'un et l'autre me semble une bonne id\'ee.
+
+Le port FreeBSD cr\'ee cet utilisateur et ce groupe pour vous. (En fait, au
+moment ou j'\'ecris ces lignes, ce n'est pas encore le cas, mais \c{c}a le
+sera bient\^ot). Voici \`a quoi ressemblent ces entr\'ees sur mon portable
+FreeBSD :
+
+\footnotesize
+\begin{verbatim}
+bacula:*:1002:1002::0:0:Bacul Daemon:/var/db/bacula:/sbin/nologin
+\end{verbatim}
+\normalsize
+
+J'ai utilis\'e vipw pour cr\'eer ces entr\'ees. J'ai utilis\'e un User ID et
+un Group ID disponibles sur mon syst\`eme : 1002.
+
+J'ai aussi cr\'e\'e un groupe dans /etc/group:
+
+\footnotesize
+\begin{verbatim}
+bacula:*:1002:
+\end{verbatim}
+\normalsize
+
+L'utilisateur bacula, contrairement au {\it daemon} Bacula, aura un
+r\'epertoire d\'edi\'e (home directory) : {\tt /var/db/bacula} qui est le
+r\'epertoire standard pour le catalogue de Bacula.
+
+A pr\'esent, vous avez un utilisateur et un groupe bacula, et vous pouvez
+s\'ecuriser le r\'epertoire d\'edi\'e de bacula en utilisant cette commande :
+
+\footnotesize
+\begin{verbatim}
+chown -R bacula:bacula /var/db/bacula/
+\end{verbatim}
+\normalsize
+
+Celle-ci assure que seul l'utilisateur bacula peut acc\'eder \`a ce
+r\'epertoire. Elle signifie aussi que si nous ex\'ecutons le Director et le
+Storage Daemon en tant que bacula, ces {\it daemons} auront aussi des acc\`es
+restreints. Ce ne serait pas le cas s'ils \'etaient ex\'ecut\'es en tant que
+root.
+
+Il est important de noter que le Storage Daemon a vraiment besoin
+d'appartenir au groupe operator pour un acc\`es normal aux lecteurs de bandes.
+(au moins sur FreeBSD, c'est ainsi que les choses sont configur\'ees par
+d\'efaut). De tels p\'eriph\'eriques sont en principe attribu\'es \`a
+root:operator. Il est plus facile et moins dangereux de faire de bacula un
+membre de ce groupe que de jouer avec les permissions du syst\`eme.
+
+D\'emarrer les {\it daemons} bacula
+
+Pour d\'emarrer les {\it daemons} bacula sur FreeBSD, utilisez la commande :
+
+\footnotesize
+\begin{verbatim}
+/usr/local/etc/rc.d/bacula.sh start
+\end{verbatim}
+\normalsize
+
+Pour vous assurer que tous fonctionnent :
+
+\footnotesize
+\begin{verbatim}
+$ ps auwx | grep bacula
+root\ 63416\ 0.0\ 0.3\ 2040 1172\ ??\ Ss\ 4:09PM 0:00.01
+ /usr/local/sbin/bacula-sd -v -c /usr/local/etc/bacula-sd.conf
+root\ 63418\ 0.0\ 0.3\ 1856 1036\ ??\ Ss\ 4:09PM 0:00.00
+ /usr/local/sbin/bacula-fd -v -c /usr/local/etc/bacula-fd.conf
+root\ 63422\ 0.0\ 0.4\ 2360 1440\ ??\ Ss\ 4:09PM 0:00.00
+ /usr/local/sbin/bacula-dir -v -c /usr/local/etc/bacula-dir.conf
+\end{verbatim}
+\normalsize
--- /dev/null
+/*
+ * html2latex
+ */
+
+available {
+ sun4_sunos.4
+ sun4_solaris.2
+ rs_aix.3
+ rs_aix.4
+ sgi_irix
+}
+
+description {
+ From Jeffrey Schaefer, Geometry Center. Translates HTML document to LaTeX
+}
+
+install {
+ bin/html2latex /afs/rpi.edu/dept/acs/rpinfo/filters/GChtml2latex/html2latex
+ bin/html2latex.tag /afs/rpi.edu/dept/acs/rpinfo/filters/GChtml2latex/html2latex.tag
+ bin/html2latex-local.tag /afs/rpi.edu/dept/acs/rpinfo/filters/GChtml2latex/html2latex-local.tag
+ bin/webtex2latex.tag /afs/rpi.edu/dept/acs/rpinfo/filters/GChtml2latex/webtex2latex.tag
+ man/man1/html2latex.1 /afs/rpi.edu/dept/acs/rpinfo/filters/GChtml2latex/html2latex.1
+}
--- /dev/null
+%%
+%%
+
+\chapter{Configuration du Storage Daemon}
+\label{_ChapterStart31}
+\index[general]{Configuration du Storage Daemon}
+\index[general]{Configuration!Storage Daemon}
+
+\section{General}
+\index[general]{General}
+\addcontentsline{toc}{section}{General}
+Le fichier de configuration du Storage Daemon a relativement peu de d\'efinitions
+de resources. Cependant, en raison du nombre pl\'ethorique de media et de syst\`emes,
+il doit \^etre hautement param\'etrable. Par cons\'equent, il existe un nombre assez important
+de directives dans la d\'efinition de ressource Devices qui vous permettent de d\'efinir
+toutes les caract\'eristiques de votre p\'eriph\'erique de stockage. Heureusement, avec les
+mat\'eriels modernes, les valeurs par d\'efaut sont g\'en\'eralement suffisantes, et tr\`es
+peu de directives sont r\'eellement indispensables.
+
+Des exemples de directives de ressources device connues pour fonctionner pour
+beaucoup de lecteurs de bandes communs peuvent \^etre trouv\'es dans le r\'epertoire :
+\lt{}bacula-src\gt{}/examples/devices. La plupart seront \'enum\'er\'es ici.
+
+Pour une discussion g\'en\'erale concernant les fichiers de configuration de Bacula,
+les ressources et les types de donn\'ees reconnus, veuillez consulter le
+chapitre \ilink{Configuration}{_ChapterStart16} de ce manuel. Les d\'efinitions de
+ressources Storage suivantes doivent \^etre d\'efinies :
+
+\begin{itemize}
+\item
+ \ilink{Storage}{StorageResource} -- Pour d\'efinir le nom du Storage Daemon.
+\item
+ \ilink{Director}{DirectorResource1} -- Pour d\'efinir le nom du Director et le mot
+ de passe permettant d'y acc\'eder.
+\item
+ \ilink{Device}{DeviceResource} -- Pour d\'efinir les caract\'eristiques de votre
+ p\'eriph\'erique de stockage.
+\item
+ \ilink{Messages}{_ChapterStart15} -- Pour d\'efinir o\`u les messages d'erreurs
+ et d'information doivent \^etre exp\'edi\'es.
+\end{itemize}
+
+\section{Ressource Storage}
+\label{StorageResource}
+\index[general]{Ressource!Storage}
+\index[general]{Ressource Sorage}
+\addcontentsline{toc}{section}{Ressource Storage}
+
+En g\'en\'eral, les propri\'et\'es sp\'ecifi\'ees au niveau de la ressource Storage d\'efinissent
+des propri\'et\'es globales du Storage Daemon. Chaque fichier de configuration de
+Storage Daemon doit avoir sa propre d\'efinition de ressource Storage.
+
+\begin{description}
+
+\item [Name = \lt{}Storage-Daemon-Name\gt{}]
+ \index[sd]{Name}
+ \index[sd]{Directive!Name}
+ Sp\'ecifie le nom du Storage Daemon. Cette directive est requise.
+\item [Working Directory = \lt{}R\'epertoire\gt{}]
+ \index[sd]{Working Directory}
+ \index[sd]{Directive!Working Directory}
+ Cette directive sp\'ecifie un r\'epertoire o\`u le Storage Daemon peut placer ses fichiers
+ d'\'etat. Ce r\'epertoire ne devrait \^etre utilis\'e que par Bacula, mais peut \^etre
+ partag\'e par d'autres daemons Bacula, pourvu que les noms donn\'es \`a chaque daemon
+ soient uniques. Cette directive est requise.
+
+\item [Pid Directory = \lt{}R\'epertoire\gt{}]
+ \index[sd]{Pid Directory}
+ \index[sd]{Directive!Pid Directory}
+ Cette directive sp\'ecifie un r\'epertoire o\`u le Storage Daemon peut d\'eposer son fichier
+d'Id de processus. Ce fichier est utilis\'e pour stopper Bacula et pr\'evenir l'ex\'ecution
+simultan\'ee de plusieurs copies de Bacula. Les substitutions shell standard sont
+effectu\'ees \`a la lecture du fichier de configuration, de sorte que des valeurs
+telles que {\bf \$HOME} seront correctement substitu\'ees.
+
+Typiquement, sur les syst\`emes Linux, vous utiliserez ici {\bf /var/run}. Si vous
+n'installez pas Bacula dans les r\'epertoires syst\`eme, vous pouvez utiliser le
+r\'epertoire de travail {\bf Working Directory} d\'efini plus haut.
+Cette directive est requise.
+
+\item [Heartbeat Interval = \lt{}P\'eriode\gt{}]
+ \index[sd]{Heartbeat Interval}
+ \index[sd]{Directive!Heartbeat Interval}
+ \index[general]{Heartbeat Interval}
+ \index[general]{Broken pipe}
+ Cette directive d\'efinit la p\'eriode des pulsations \'emises par le Storage Daemon
+ vers le File Daemon lorqu'il (le SD) se trouve en situation d'attente du montage
+ d'une cartouche par l'op\'erateur. La valeur par d\'efaut est z\'ero, ce qui d\'esactive
+ les pulsations. Cette fonctionnalit\'e est particuli\`erement utile si vous avez un
+ routeur (tel que les 3Com) qui ne suit pas les standards Internet et expire une
+ connection valide apr\`es une courte dur\'ee, bien que {\it keepalive} soit activ\'e.
+ Ceci produit habituellement un message d'erreur du type {\it broken pipe}.
+
+\item [Maximum Concurrent Jobs = \lt{}nombre\gt{}]
+ \index[sd]{Maximum Concurrent Jobs}
+ \index[sd]{Directive!Maximum Concurrent Jobs}
+ O\`u \lt{}nombre\gt{} est nombre maximal de jobs qui peuvent \^etre ex\'ecut\'es
+ simultan\'ement. La valeur par d\'efaut est fix\'ee \`a 10, mais vous pouvez d\'efinir
+ une valeur plus grande. Chaque connexion depuis le Director (par exemple
+ une requ\^ete de statut, le lancement d'un job...) est consid\'er\'ee comme un job,
+ aussi, si vous voulez conserver la possibilit\'e d'utiliser la commande
+ {\bf status} dans la console alors qu'un job est en cours d'ex\'ecution, vous
+ devez utiliser une valeur strictement sup\'erieure \`a 1. Pour ex\'ecuter plusieurs
+ jobs simultan\'ement, vous devez param\'etrer plusieurs autres directives dans le
+ fichier de configuration du Director. Selon ce que vous voulez faire, il faudra
+ intervenir sur l'un ou l'autre param\`etre, mais vous devrez presque surement
+ r\'egler le param\`etre {\bf Maximum Concurrent Jobs} de la ressource Storage du
+ fichier de configuration du Director, et peut-\^etre aussi ceux des ressources
+ Job et Client.
+
+\item [SDAddresses = \lt{}Adresse IP\gt{}]
+ \index[sd]{SDAddresses}
+ \index[sd]{Directive!SDAddresses}
+ Pr\'ecise les ports et adresses sur lesquels le Storage Daemon est \`a
+ l'\'ecoute de connections du Director. En principe, les valeurs par d\'efaut sont
+ suffisantes, et vous n'avez pas besoin d'utiliser cette directive. La meilleure
+ explication du fonctionnement de cette directive est certainement un exemple :
+
+\footnotesize
+\begin{verbatim}
+ SDAddresses = { ip = {
+ addr = 1.2.3.4; port = 1205; }
+ ipv4 = {
+ addr = 1.2.3.4; port = http; }
+ ipv6 = {
+ addr = 1.2.3.4;
+ port = 1205;
+ }
+ ip = {
+ addr = 1.2.3.4
+ port = 1205
+ }
+ ip = {
+ addr = 1.2.3.4
+ }
+ ip = {
+ addr = 201:220:222::2
+ }
+ ip = {
+ addr = bluedot.thun.net
+ }
+}
+\end{verbatim}
+\normalsize
+
+o\`u "ip", "ip4", "ip6", "addr", et "port" sont des mots-clef. Notez que les adresses
+peuvent \^etre sp\'ecifi\'ees sous forme de quadruplets point\'es, de nom symboliques
+(uniquement dans la sp\'ecification "ip") ou en notation IPv6 \`a double points. Le port
+peut quand \`a lui \^etre sp\'ecifi\'e par son num\'ero, ou par sa valeur mn\'emonique du
+fichier /etc/services. Si un port n'est pas sp\'ecifi\'e, la valeur par d\'efaut est
+utilis\'ee. Si une section ip est sp\'ecifi\'ee, la r\'esolution peut \^etre r\'ealis\'ee
+par ipv4 ou ipv6. En revanche, si ip4 ou ip6 est sp\'ecifi\'ee, seule la r\'esolution
+correspondante fonctionne.
+
+Vous pouvez, avec ces directives, remplacer les valeurs des directives SDPort et
+SDAddress montr\'ees ci-dessous.
+
+\item [SDPort = \lt{}Num\'ero de port\gt{}]
+ \index[sd]{SDPort}
+ \index[sd]{Directive!SDPort}
+ Sp\'ecifie le num\'ero de port sur lequel le Storage Daemon \'ecoute les connexions
+ en provenance du Director. La valeur par d\'efaut est 9103.
+
+\item [SDAddress = \lt{}Adresse IP\gt{}]
+ \index[sd]{SDAddress}
+ \index[sd]{Directive!SDAddress}
+ Cette directive est optionnelle. Lorsqu'elle est sp\'ecifi\'ee, le Storage Daemon n'accepte
+ de connections (de Director(s) ou de File(s) Daemon(s)) que de l'adresse sp\'ecifi\'ee
+ {\bf Adresse-IP}, qui peut \^etre
+ soit un nom de domaine, soit une adresse IP au format quadruplet point\'e.
+ Si cette directive n'est pas sp\'ecifi\'ee, le Storage Daemon acceptera des connections de
+ de toute adresse valide.
+
+\end{description}
+
+Voici une d\'efinition typique d'une ressource Storage du Storage Daemon :
+
+
+\footnotesize
+\begin{verbatim}
+#
+# "Global" Storage daemon configuration specifications appear
+# under the Storage resource.
+#
+Storage {
+ Name = "Storage daemon"
+ Address = localhost
+ WorkingDirectory = "~/bacula/working"
+ Pid Directory = "~/bacula/working"
+}
+\end{verbatim}
+\normalsize
+
+\section{La ressource Director}
+\label{DirectorResource1}
+\index[general]{Ressource Director}
+\index[general]{Resource!Director}
+\addcontentsline{toc}{section}{La ressource Director}
+
+La ressource Director sp\'ecifie le nom du Director qui est autoris\'e
+\`a utiliser les services du Storage Daemon. Il peut exister plusieurs
+ressources Director. Le nom et le mot de passe du Director doivent
+s'accorder avec leurs homologues dans le fichier de configuration
+du Storage Daemon.
+
+\begin{description}
+
+\item [Name = \lt{}Nom-du-Director\gt{}]
+ \index[sd]{Name}
+ \index[sd]{Directive!Name}
+ Sp\'ecifie le nom du Director autoris\'e \`a se connecter au Storage Daemon.
+ Cette directive est requise.
+
+\item [Password = \lt{}Mot-de-passe-du-Director\gt{}]
+ \index[sd]{Password}
+ \index[sd]{Directive!Password}
+ Sp\'ecifie le mot de passe qui doit \^etre soumis par le Director susnomm\'e.
+ Cette directive est requise.
+
+\item [Monitor = \lt{}yes|no\gt{}]
+ \index[sd]{Monitor}
+ \index[sd]{Directive!Monitor}
+ Si cette directive est d\'esactiv\'ee ({\bf no}), ce qui est le cas par d\'efaut,
+ ce Director dispose d'un acc\`es illimit\'e \`a ce Storage Daemon. Dans le cas
+ contraire, ce Director est brid\'e de fa\c {c}on \`a pouvoir seulement r\'ecup\'erer le
+ statut courant de ce Storage Daemon.
+
+ Si ce Director est utilis\'e par un superviseur, nous vous recommandons
+ fortement d'activer cette directive pour \'eviter de s\'erieux probl\`emes de
+ s\'ecurit\'e.
+
+\end{description}
+
+Voici un exemple d'une d\'efinition de ressource Director valide :
+
+\footnotesize
+\begin{verbatim}
+Director {
+ Name = MainDirector
+ Password = my_secret_password
+}
+\end{verbatim}
+\normalsize
+
+\label{DeviceResource}
+\section{La Ressource Device}
+\index[general]{Resource!Device}
+\index[general]{Ressource Device}
+\addcontentsline{toc}{section}{Ressource Device}
+
+La ressource Device sp\'ecifie les d\'etails de chaque p\'eriph\'erique (en g\'en\'eral,
+un lecteur de bandes) qui peut \^etre utilis\'e par le Storage Daemon. Un
+Storage Daemon peut disposer de plusieurs ressources Device. En g\'en\'eral,
+les propri\'et\'es sp\'ecifi\'ees dans la ressource Device sont sp\'ecifiques
+au p\'eriph\'erique.
+
+\begin{description}
+
+\item [Name = {\it Nom-de-p\'eriph\'erique}]
+ \index[sd]{Name}
+ \index[sd]{Directive!Name}
+ Sp\'ecifie le nom que le Director devra utiliser pour d\'esigner ce p\'eriph\'erique.
+ Il s'agit d'un nom logique, c'est une cha\^ine qui peut comporter jusqu'\`a 127
+ caract\`eres. C'est en g\'en\'eral une bonne id\'ee d'utiliser un nom qui corresponde
+ au nom "humain" du p\'eriph\'erique (NDT: la vo dit "the english name"). Le nom
+ physique du p\'eriph\'erique est sp\'ecifi\'e au niveau de la directive {\bf Archive Device}
+ d\'ecrite ci-dessous. Le nom que vous sp\'ecifiez ici est aussi utilis\'e dans le
+ fichier de configuration de votre Director au niveau de la
+ \ilink{directive Device}{StorageResource2} de sa ressource Storage.
+
+\item [Archive Device = {\it cha\^ine-nom}]
+ \index[sd]{Archive Device}
+ \index[sd]{Directive!Archive Device}
+ La {\bf cha\^ine-nom} (NDT : name-string dans la vo) sp\'ecifie le nom de fichier syst\`eme
+ du p\'eriph\'erique de stockage g\'er\'e par ce daemon. Il s'agit en g\'en\'eral d'un nom
+ de p\'eriph\'erique amovible, par exemple un lecteur de bande d\'esign\'e par "{\bf /dev/nst0}"
+ ou "{\bf /dev/rmt/0mbn}". Dans le cas d'un graveur de DVD, ce sera par exemple
+ {\bf /dev/hdc}. Ce peut \^etre aussi un un nom de r\'epertoire si vous sauvegardez
+ sur disque. Dans ce cas, vous devez soumettre le chemin absolu vers ce
+ r\'epertoire. Lorsque vous utilisez un lecteur de bandes, il est pr\'ef\'erable
+ d'utiliser la variante "non-rewind" du fichier de p\'eriph\'erique. De plus, sur les
+ syst\`emes tels que Sun, qui disposent de plusieurs m\'ethodes d'acc\`es aux cartouches,
+ prenez soin de sp\'ecifier l'usage de la convention I/O Berkeley avec les p\'eriph\'eriques.
+ le {\bf b} de la sp\'ecification {\bf /dev/rmt/0mbn} Solaris (Sun) est ce qui est
+ requis dans ce cas. Bacula ne supporte pas le comportement SysV des lecteurs de bandes.
+
+ Comme mentionn\'e plus haut,Archive Device est, en principe, le nom d'un lecteur de bandes,
+ mais vous pouvez tout aussi bien sp\'ecifier le chemin absolu vers un r\'epertoire
+ existant. Dans ce cas, Bacula utilisera un fichier pour stocker les donn\'ees dans
+ le r\'epertoire sp\'ecifi\'e, le nom de fichier utilis\'e sera celui du volume tel que
+ sp\'ecifi\'e dans le catalogue. Si vous souhaitez \'ecrire dans plusieurs r\'epertoires
+ (dans le but de r\'epartir la charge sur plusieurs disques), vous devez d\'efinir deux ressources
+ Device, chacune comportant une Archive Device avec un r\'epertoire diff\'erent.
+
+ Une troisi\`eme possibilit\'e consiste \`a sp\'ecifier le nom d'un FIFO. Un FIFO est un
+ fichier sp\'ecial qui connecte deux programmes via la m\'emoire du noyau. Si vous
+ sp\'ecifiez un FIFO en guise d'Archive Device, vous devez avoir un programme qui
+ lit ce que Bacula \'ecrit dans le FIFO. Lorsque le Storage Daemon d\'emarre le job,
+ il attend que le programme lecteur commence \`a lire pendant un d\'elai maximal de
+ de {\bf MaximumOpenWait} secondes, au del\`a duquel le job est termin\'e. Par cons\'equent,
+ il est pr\'ef\'erable de lancer le programme lecteur au d\'ebut du job, par exemple
+ gr\^ace \`a la directive {\bf RunBeforeJob}. Pour ce type de p\'eriph\'erique, vous ne devez
+ jamais sp\'ecifier {\bf AlwaysOpen}, puisque vous voulez que le Storage Daemon
+ ne l'ouvre que lorsqu'un job d\'emarre, aussi veuillez attribuer explicitement
+ la valeur {\bf No} \`a cette directive. Puisqu'un FIFO est un p\'eriph\'erique \`a sens
+ unique, Bacula ne tente pas d'en lire le label, il se contente d'y \'ecrire. Pour
+ cr\'eer un volume FIFO dans le catalogue, utilisez la commande {\bf add} plut\^ot
+ que la commande {\bf label} afin d'\'eviter de tenter d'\'ecrire un label.
+
+ Lors d'une op\'eration de restauration, si l'Archive Device est un FIFO, Bacula
+ tente de lire le FIFO, aussi vous devez avoir un programme externe qui \'ecrit dans
+ le FIFO. Bacula attend que ce programme commence \`a \'ecrire pendant un d\'elai
+ maximal de {\bf MaximumOpenWait} secondes apr\`es quoi il termine le job. Comme
+ mentionn\'e ci-dessus, vous pouvez utiliser la directive {\bf RunBeforeJob} pour
+ lancer ce programme auteur d\`es le d\'ebut du job.
+
+ La directive Archive Device est requise.
+
+\item [Device Type = {\it Sp\'ecification-de-type}]
+ \index[sd]{Device Type}
+ \index[sd]{Directive!Device Type}
+ La sp\'ecification Device Type de d\'eclarer explicitement \`a Bacula quel type
+ de p\'eriph\'erique vous d\'efinissez. La valeur de {\it Sp\'ecification-de-type} peut
+ \^etre l'une des suivantes :
+ \begin{description}
+ \item [File]
+ Indique \`a Bacula que le p\'eriph\'erique est un fichier. Ce peut \^etre
+ un fichier d\'efini sur un m\'edium fixe ou au contraire amovible (par exemple, un
+ p\'eriph\'erique USB). Tous les fichiers doivent \^etre des p\'eriph\'eriques en acc\`es
+ s\'electif (NDT : traduction Google sans doute \`a revoir de "random access")
+ \item[tape]
+ Indique \`a Bacula que le p\'eriph\'erique est un lecteur de bandes, donc \`a
+ acc\`es s\'equentiel. Ces p\'eriph\'eriques sont control\'e par les appels
+ ioctl().
+ \item[Fifo]
+ Indique \`a Bacula que le p\'eriph\'erique est un p\'eriph\'erique \`a acc\`es
+ s\'equentiel "first-in-first-out" (premier entr\'e, premier sorti) en
+ lecture seule ou en \'ecriture seule.
+ \item[DVD]
+ Indique \`a Bacula que le p\'eriph\'erique est un DVD. Les DVDs sont \`a acc\`es
+ s\'equentiel en \'ecriture et \`a acc\`es s\'electif (NDT : traduction Google sans
+ doute \`a revoir de "random access") en lecture.
+ \end{description}
+
+ La directive Device Type n'est pas requise, et si elle n'est pas sp\'ecifi\'ee,
+ Bacula tentera de deviner cette information selon la sp\'ecification Archive
+ Device fournie. Il existe plusieurs avantages \`a sp\'ecifier explicitement
+ le type de p\'eriph\'erique. D'abord, sur certains syst\`emes, les p\'eriph\'eriques
+ bloc et caract\`ere ont le m\^eme type, ce qui signifie que sur ces syst\`emes,
+ Bacula est probablement incapable de deviner qu'un p\'eriph\'erique est un DVD.
+ Ensuite, si vous sp\'ecifiez explicitement le type de p\'eriph\'erique, le point de
+ montage n'a pas besoin d'\^etre d\'efini jusqu'\`a ce que le p\'eriph\'erique soit ouvert.
+ C'est le cas de la plupart des p\'eriph\'eriques amovibles tels que les USB mont\'es
+ par le daemon HAL. Au contraire, si le type de p\'eriph\'erique n'est pas
+ sp\'ecifi\'e explicitement, le point de montage doit exister d\`es le
+ d\'emarrage du Storage Daemon.
+
+ Cette directive est apparue avec la version 1.38.6 de Bacula.
+
+\item [Media Type = {\it name-string}]
+ \index[sd]{Media Type}
+ \index[sd]{Directive!Media Type}
+ La cha\^ine {\bf name-string} sp\'ecifi\'ee baptise le type de m\'edia support\'e par
+ ce p\'eriph\'erique, par exemple, "DLT7000". Les noms de type de m\'edia sont
+ arbitraires, vous pouvez utiliser le nom de votre choix, mais ils doivent
+ \^etre connus du catalogue pour qu'il puisse garder trace de quel daemon
+ peut lire quel type de m\'edia. En g\'en\'eral, chaque type de stockage devrait
+ avoir un type de m\'edia unique associ\'e. Le m\^eme nom {\bf name-string} doit
+ appara\^itre dans la d\'efinition de ressource Storage appropri\'ee du fichier
+ de configuration du Director.
+
+ M\^eme si les noms que vous assignez sont arbitraires, vous devriez les choisir
+ avec circonspection, car le Media Type est utilis\'e pour d\'eterminer le
+ p\'eriph\'erique de stockage \`a s\'electionner lors d'une restauration. Ainsi, vous
+ devriez certainement utiliser le m\^eme Media Type pour tous les lecteurs
+ dont les cartouches sont interchangeables. Ce n'est g\'en\'eralement pas un
+ probl\`eme si vous n'avez qu'un Storage Daemon, mais c'en est un avec plusieurs
+ Storage Daemon, surtout s'ils utilisent des m\'edia incompatibles.
+
+ Si, par exemple, vous sp\'ecifiez le Media Type "DDS-4", Bacula pourra lors de
+ restaurations s\'electionner tout Storage Daemon qui supporte les "DDS-4".
+ Si vous avez une librairie, vous voudrez peut-\^etre baptiser son Media Type
+ d'un nom qui lui soit unique, \`a moins que vous souhaitiez pouvoir utiliser
+ ses volumes dans d'autres lecteurs. Vous devriez aussi vous assurer d'avoir
+ des noms de Media Type uniques si les media ne sont pas compatibles d'un
+ lecteur \`a l'autre. Cette sp\'ecification est requise pour tous les
+ p\'eriph\'eriques.
+
+ Enfin, si vous utilisez le stockage sur disque, sachez que chaque ressource
+ Device a g\'en\'eralement un point de montage (ou r\'epertoire) diff\'erent. Afin
+ que Bacula puisse s\'electionner correctement la ressource Device \`a utiliser,
+ chacun doit avoir un Media Type distinct.
+
+\label{Autochanger}
+\item [Autochanger = {\it Yes|No}]
+ \index[sd]{Autochanger}
+ \index[sd]{Directive!Autochanger}
+ Si cette directive est \`a {\bf yes}, alors Bacula consid\`ere que le p\'eriph\'erique
+ concern\'e est dans une librairie, et il vous faut sp\'ecifier une ressource
+ {\bf Autochanger} qui pointe vers les ressources {\bf Device}. Vous devez
+ aussi renseigner la directive {\bf Changer Device}. Si la directive est \`a {\bf No}
+ (valeur par d\'efaut), les volumes doivent \^etre chang\'es manuellement. Vous devriez
+ aussi avoir une directive identique \`a la \ilink{Storage resource}{Autochanger1} dans
+ le fichier de configuration du Director, de sorte que Bacula vous demande le slot
+ lors de l'\'etiquetage des cartouches.
+
+\item [Changer Device = {\it cha\^ine-nom}]
+ \index[sd]{Changer Device}
+ \index[sd]{Directive!Changer Device}
+ La {\bf cha\^ine-nom} sp\'ecifi\'ee doit \^etre le nom de p\'eriph\'erique {\bf SCSI g\'en\'erique}
+ associ\'e \`a l'{\bf Archive Device} sp\'ecifi\'ee dans la ressource Device. Ce nom de
+ p\'eriph\'erique SCSI g\'en\'erique devrait \^etre sp\'ecifi\'e si vous avez une librairie
+ ou si vous n'avez qu'un lecteur standard mais souhaitez utiliser la {\bf commande
+ Alert} (voir ci-dessous). Par exemple, sur les syst\`emes Linux, vous sp\'ecifierez
+ certainement {\bf /dev/nst0} pour le nom d'Archive Device, et {\bf /den/sg0} pour
+ le nom de Changer Device. Selon votre configuration, le nombre de librairies dont
+ vous disposez et leurs types, le nom que vous serez amen\'e \`a sp\'ecifier ici peut varier.
+ Cette directive est optionnelle. Consultez le chapitre
+ \ilink{Utiliser une librairie}{_ChapterStart18} de ce manuel pour plus de d\'etails
+ concernant les directives relatives aux librairies.
+
+\item [Changer Command = {\it cha\^ine nom}]
+ \index[sd]{Changer Command}
+ \index[sd]{Directive!Changer Command}
+ La {\bf cha\^ine-nom} d\'esigne un programme externe qui aura pour t\^ache le
+ changement des volumes \`a la demande de Bacula. En principe, cette directive
+ n'est sp\'ecifi\'ee qu'au niveau de la ressource {\bf AutoChanger}, qui est alors
+ utilis\'ee pour tous les p\'eriph\'eriques. Cependant, vous pouvez parfaitement
+ utiliser une commande {\bf Changer Command} diff\'erente pour chaque ressource Device.
+ La plupart du temps, vous sp\'ecifierez le script {\bf mtx-changer} fourni avec
+ Bacula de la fa\c {c}on suivante :
+
+\footnotesize
+\begin{verbatim}
+Changer Command = "/path/mtx-changer %c %o %S %a %d"
+\end{verbatim}
+\normalsize
+
+ Et vous installerez le programme {\bf mtx} sur votre syst\`eme (paquetage tiers).
+ Un exemple de cette commande figure dans le fichier de configuration par d\'efaut
+ du Storage Daemon, bacula-sd.conf. Pour plus de d\'etails concernant les
+ substitutions de caract\`eres qui peuvent \^etre utilis\'ees pour configurer
+ votre librairie, veuillez consulter le chapitre sur
+ l'\ilink{utilisation des Librairies}{_ChapterStart18}. Les utilisateurs
+ de FreeBSD voudront probablement jeter un oeil aux quelques scripts
+ fournis dans le r\'epertoire {\bf examples/autochangers}.
+
+\item [Alert Command = {\it name-string}]
+ \index[sd]{Alert Command}
+ La {\bf cha\^ine-nom} d\'esigne un programme externe \`a appeler au terme
+ de chaque job apr\`es que le p\'eriph\'erique ait \'et\'e lib\'er\'e. Le but de cette
+ commande est de r\'ecup\'erer d'\'eventuels messages d'alerte du lecteur pour
+ vous pr\'evenir si quelque chose ne fonctionne pas correctement (ces messages
+ existent au moins sur la plupart des lecteurs modernes). Les m\^emes
+ substitutions que celles d\'ecrites au niveau de la {\bf Changer command}
+ peuvent \^etre utilis\'ees ici. Pour plus d'informations, veuillez consulter
+ le chapitre sur les \ilink{Librairies}{_ChapterStart18} de ce manuel.
+
+ Notez que vous pouvez trouver un usage \`a cette commande sans n\'ecessairement
+ poss\'eder une librairie. L'exemple ci-dessous utilise le programme {\bf tapeinfo}
+ qui vient avec le paquet {\bf mtx} mais peut \^etre utilis\'e avec n'importe quel
+ lecteur. Vous devrez tout de m\^eme sp\'ecifier une directive {\bf Changer Device}
+ dans votre ressource Device (voir ci-dessus) afin que le p\'eriph\'erique SCSI
+ g\'en\'erique puisse \^etre \'edit\'e dans la commande (avec \%c).
+
+ Voici un exemple qui affiche les alertes en provenance du lecteur dans les
+ rapports de jobs :
+
+\footnotesize
+\begin{verbatim}
+Alert Command = "sh -c 'tapeinfo -f %c | grep TapeAlert'"
+
+\end{verbatim}
+\normalsize
+
+Et un exemple de ce qui peut en sortir lorqu'il y a un probl\`eme :
+
+\footnotesize
+\begin{verbatim}
+bacula-sd Alert: TapeAlert[32]: Interface: Problem with SCSI interface
+ between tape drive and initiator.
+
+\end{verbatim}
+\normalsize
+
+\item [Drive Index = {\it number}]
+ \index[sd]{Drive Index}
+ \index[sd]{Directive!Drive Index}
+ Le num\'ero de lecteur, ou {\bf Drive Index}, que vous sp\'ecifiez ici est
+ pass\'e au script {\bf mtx-changer} et donc au programe {\bf mtx}.
+ Par d\'efaut, le Drive Index vaut z\'ero, aussi, si vous n'avez qu'un
+ lecteur dans votre librairie, tout fonctionnera correctement.
+ Si en revanche vous avez plusieurs lecteurs, vous devez sp\'ecifier
+ plusieurs ressources Device (une par lecteur).
+ Il n'est pas n\'ecessaire de sp\'ecifier la valeur z\'ero pour la directive
+ Drive Index dans la premi\`ere de ces ressources (valeur par d\'efaut). Par
+ contre, la seconde devrait contenir une directive Drive Index \'egale \`a 1,
+ la troisi\`eme une directive Drive Index \'egale \`a 2, et ainsi de suite.
+ A partir de la version 1.38.0, en utilisant la ressource {\bf Autochanger},
+ Bacula s'assure qu'un seul lecteur \`a la fois utilise le script d'autochargement
+ (script mtx-changer), aussi vous n'avez plus besoin de scripts de verrouillage
+ comme ce fut le cas dans le pass\'e -- Le script mtx-change fourni avec Bacula
+ fonctionne avec un nombre quelconque de lecteurs.
+
+\item [Autoselect = {\it Yes|No}]
+ \index[sd]{Autoselect}
+ \index[sd]{Directive!Autoselect}
+ Si cette directive vaut {\bf yes} (valeur par d\'efaut), et si le p\'eriph\'erique
+ appartient \`a une librairie, alors lorsque la librairie est r\'ef\'erenc\'ee par
+ le Director, ce p\'eriph\'erique peut \^etre automatiquement s\'electionn\'e.
+ Si cette directive vaut {\bf no}, alors le p\'eriph\'erique peut seulement
+ \^etre d\'esign\'e par son nom de p\'eriph\'erique (Device Name) dans le
+ Director. Ceci permet de r\'eserver un lecteur pour une t\^ache particuli\`ere,
+ comme une sauvegarde hautement prioritaire, ou des op\'erations de restaurations.
+
+\item [Maximum Changer Wait = {\it time}]
+ \index[sd]{Maximum Changer Wait}
+ \index[sd]{Directive!Maximum Changer Wait}
+ Cette directive sp\'ecifie le d\'elai maximum, en secondes, pendant lequel Bacula
+ peut attendre d'une librairie qu'elle change de volume. Au del\`a de ce d\'elai,
+ Bacula invalide le num\'ero de slot r\'ef\'erenc\'e dans le catalogue et essaye \`a
+ nouveau. Si aucun autre volume n'est disponible dans la librairie, Bacula
+ r\'eclame l'intervention d'un op\'erateur. La valeur par d\'efaut est 5 minutes.
+
+\item [Maximum Rewind Wait = {\it time}]
+ \index[sd]{Maximum Rewind Wait}
+ \index[sd]{Directive!Maximum Rewind Wait}
+ Cette directive sp\'ecifie le d\'elai maximum, en secondes, pendant lequel Bacula
+ peut attendre d'un lecteur qu'il rembobine une cartouche. Au del\`a de ce d\'elai,
+ le job est effac\'e. La valeur par d\'efaut est 5 minutes.
+
+\item [Maximum Open Wait = {\it time}]
+ \index[sd]{Maximum Open Wait}
+ \index[sd]{Directive!Maximum Open Wait}
+ Cette directive sp\'ecifie le d\'elai maximum, en secondes, pendant lequel Bacula
+ peut attendre apr\`es une commande Open.Au del\`a de ce d\'elai,
+ le job est effac\'e. La valeur par d\'efaut est 5 minutes.
+
+\item [Always Open = {\it Yes|No}]
+ \index[sd]{Always Open}
+ \index[sd]{Directive!Always Open}
+ Si la valeur sp\'ecifi\'ee ici est {\bf Yes} (valeur par d\'efaut), Bacula garde le
+ p\'eriph\'erique ouvert, \`a moins qu'il ne soit explicitement d\'emont\'e ({\bf unmounted})
+ depuis la console Bacula. Ceci permet \`a Bacula de s'assurer que le lecteur est
+ toujours disponible. Si vous r\'eglez {\bf AlwaysOpen} \`a {\bf no} {\bf Bacula},
+ Bacula ouvre le lecteur seulement lorsque n\'ecessaire, et le lib\`ere \`a la fin du
+ job, si aucun autre job ne l'utilise. Lors de l'utilisation suivante, Bacula
+ doit rembobiner la cartouche et se repositionner au bon endroit. Pour \'eviter
+ ces rembnobinages inutiles et les interventions de l'op\'erateur, il est
+ hautement recommand\'e de garder la valeur {\bf Always Open = yes}. Ceci assure
+ aussi que le lecteur est disponible lorsque Bacula en a besoin.
+
+ Si vous avez sp\'ecifi\'e {\bf Always Open = yes} (comme recommand\'e) et si vous
+ voulez utiliser le lecteur pour autre chose, lib\'erez-le simplement avec la
+ commande {\bf unmount} dans la console Bacula. N'oubliez-pas ensuite de
+ remonter le lecteur avec la commande {\bf mount} afin que Bacula soit pr\`et
+ \`a prendre en charge le prochain job planifi\'e.
+
+ Pour le stockage sur disque (File Storage), cette directive est ignor\'ee. Dans le
+ cas d'un stockage FIFO, vous devez mettre cette directive \`a {\bf No}.
+
+ Notez bien que si vous mettez cette directive \`a {\bf No}, Bacula lib\`ere le
+ lecteur entre chaque job, obligeant le lecteur \`a rembobiner la cartouche, et
+ \`a replacer la bande \`a la fin de la zone de donn\'ees, ce qui peut prendre
+ beaucoup de temps.
+
+\item [Volume Poll Interval = {\it p\'eriode}]
+ \index[sd]{Volume Poll Interval}
+ \index[sd]{Directive!Volume Poll Interval}
+ Si la p\'eriode sp\'ecifi\'ee pour cette directive est non nulle alors, apr\`es avoir
+ demand\'e \`a l'op\'erateur de monter un nouveau volume, Bacula retentera
+ p\'eriodiquement de lire le lecteur selon la p\'eriode sp\'ecifi\'ee au cas o\`u un
+ nouveau volume aurait \'et\'e mont\'e. Si la valeur sp\'ecifi\'ee est z\'ero, ces
+ tentatives de lecture n'ont pas lieu. Cette directive est utile lorsque
+ vous souhaitez \'eviter l'intervention d'un op\'erateur \`a la console. Au lieu de
+ quoi l'op\'erateur se contente de sortir la cartouche pr\'ec\'edente et de monter la
+ nouvelle qui sera reconnue \`a la prochaine tentative. Soyez conscient que si vous
+ sp\'ecifiez une p\'eriode trop courte, vous risquez de solliciter excessivement
+ votre lecteur si la cartouche pr\'ec\'edente demeure dans le lecteur, puisque Bacula
+ la lira \`a chaque tentative. Vous pouvez \'eviter ceci en \'ejectant la cartouche avec
+ les directives {\bf Offline On Unmount} et {\bf Close on Poll}.
+ Cependant, si vous utilisez un noyau Linux 2.6 ou un autre syst\`eme d'exploitation tel
+ FreeBSD ou Solaris, les commandes Offline ou Unmount laisseront le lecteur sans cartouche,
+ et Bacula, incapable de d'ouvrir correctement le lecteur, pourrait \'echouer ses jobs.
+ Pour plus d'informations sur ce probl\`eme, veuillez consulter la section
+ \ilink{description of Offline On Unmount}{NoTapeInDrive} du chapitre relatif
+ aux tests des lecteurs de bandes.
+
+\item [Close on Poll= {\it Yes|No}]
+ \index[sd]{Close on Poll}
+ \index[sd]{Directive!Close on Poll}
+ Si cette directive est \`a {\bf Yes}, Bacula ferme le p\'eriph\'erique et le r\'eouvre
+ \`a chaque tentative (ce qui est \'equivalent \`a unmount, sauf qu'il n'est pas
+ n\'ecessaire d'utiliser mount ensuite). En principe, cette directive n'est
+ pas tr\`es utile \`a moins que vous ayez activ\'e la directive {\bf Offline on Unmount},
+ auquel cas le lecteur sera consid\'er\'e hors-ligne (NDT : offline) pr\'evenant ainsi
+ de nombreux mouvements inutiles de la bande lors de chaque tentative de lecture.
+ Une fois que l'op\'erateur aura charg\'e une nouvelle cartouche, Bacula
+ sera en mesure de s'en rendre compte \`a la prochaine tentative et poursuivra
+ automatiquement la sauvegarde. Voyez ci-dessus pour plus de d\'etails.
+
+\item [Maximum Open Wait = {\it time}]
+ \index[sd]{Maximum Open Wait}
+ \index[sd]{Directive!Maximum Open Wait}
+ Cette directive sp\'ecifie le d\'elai maximum, en secondes que Bacula
+ accorde \`a un p\'eriph\'erique occup\'e. La valeur par d\'efaut est 5 minutes.
+ Si le p\'eriph\'erique ne peut \^etre obtenu, le job en cours est termin\'e en erreur.
+ Bacula tentera \`a nouveau d'ouvrir le lecteur lorsqu'un nouveau job le
+ r\'eclamera.
+
+\item [Removable media = {\it Yes|No}]
+ \index[sd]{Removable media}
+ \index[sd]{Directive!Removable media}
+ R\'eglez cette directive \`a {\bf Yes} si le p\'eriph\'erique concern\'e supporte des
+ m\'edia amovibles (par exemple des cartouches ou des CDROMs). Dans le cas de
+ m\'edia inamovibles (par exemple, une zone de sauvegardes interm\'ediaires sur un
+ disque dur), mettez {\bf Removable media = No}
+
+\item [Random access = {\it Yes|No}]
+ \index[sd]{Random access}
+ \index[sd]{Directive!Random access}
+ Si cette directive est \`a {\bf Yes}, le p\'eriph\'erique de stockage est consid\'er\'e
+ comme \'etant un m\'edium \`a acc\`es al\'eatoire (NDT : random access medium) qui
+ supporte les commodit\'es {\bf lseek} (ou {\bf lseek64} si l'option Largefile
+ a \'et\'e activ\'ee lors de la compilation).
+
+\item [Minimum block size = {\it size-in-bytes}]
+ \index[sd]{Minimum block size}
+ \index[sd]{Directive!Minimum block size}
+ Sur la plupart des lecteurs modernes, vous n'aurez pas besoin de cette
+ directive, dont le but est d'utiliser des blocs de taille fixe. Cette
+ directive ne s'applique qu'aux p\'eriph\'eriques \`a acc\`es s\'equentiel (NDT :
+ non-random access devices) comme, par exemple, les lecteurs de bandes.
+ Les blocs \'ecrits par le Storage Daemon sur un p\'eriph\'erique \`a acc\`es
+ s\'equentiel ne seront jamais de taille inf\'erieure \`a la taille sp\'ecifi\'ee
+ {\bf size-in-bytes}. Le Storage Daemon tente de remplir au mieux les blocs
+ avec les donn\'ees re\c {c}ues, mais il compl\`ete si n\'ecessaire pour atteindre
+ la taille minimum requise {\bf Minimum block size} .
+
+ Pour contraindre la taille des blocs \`a \^etre fixe, comme c'est le cas de
+ certains p\'eriph\'eriques \`a acc\`es s\'equentiel, stipulez des tailles de blocs
+ minimum {\bf Minimum block size} et maximum {\bf Maximum block size}
+ identiques. Le param\'etrage par d\'efaut est 0 pour les deux directives
+ et la taille de bloc par d\'efaut est de 64 512 octets.
+
+ Par exemple, si vous souhaitez fixer la taille des blocs \`a 100K octets, sp\'ecifiez :
+
+\footnotesize
+\begin{verbatim}
+
+ Minimum block size = 100K
+ Maximum block size = 100K
+
+\end{verbatim}
+\normalsize
+ Notez que si vous sp\'ecifiez une taille de blocs fixe comme ci-dessus, le
+ lecteur doit \^etre r\'egl\'e soit en mode "taille de blocs variable", soit en
+ mode "taille de blocs fixe" avec imp\'erativement la m\^eme taille de blocs
+ fixe que celle sp\'ecifi\'ee dans Bacula (ce param\`etre se r\`egle g\'en\'eralement
+ au niveau du lecteur avec {\bf mt}), faute de quoi vous aurez des erreurs \`a
+ la relecture de vos cartouches.
+
+ Si vous voulez que votre taille de blocs soit variable mais comprise entre
+ 64 Ko et 200 Ko, sp\'ecifiez :
+
+\footnotesize
+\begin{verbatim}
+
+ Minimum block size = 64K
+ Maximum blocksize = 200K
+
+\end{verbatim}
+\normalsize
+
+\item [Maximum block size = {\it size-in-bytes}]
+ \index[sd]{Maximum block size}
+ \index[sd]{Directive!Maximum block size}
+ Sur la plupart des lecteurs modernes, vous n'aurez pas besoin de cette
+ directive. Dans le cas contraire, ce sera probablement pour utiliser
+ des blocs de taille fixe (voir la directive Minimum block size ci dessus).
+ Le Storage Daemon tente d'\'ecrire des blocs de la taille sp\'ecifi\'ee
+ {\bf size-in-bytes} sur le p\'eriph\'erique. Par cons\'equent cette
+ directive fixe \`a la fois la taille maximale et la taille par d\'efaut
+ des blocs. La taille \'ecrite n'exc\`ede jamais la taille sp\'ecifi\'ee ici.
+ Lorsque l'ajout de donn\'ees provoquerait un d\'epassement, le bloc est
+ \'ecrit sur le p\'eriph\'erique, et un nouveau bloc est entam\'e.
+ avec les donn\'ees re\c {c}ues, mais il compl\`ete si n\'ecessaire pour atteindre
+
+ Si aucune valeur n'est sp\'ecifi\'ee (ou si la valeur sp\'ecifi\'ee est 0), le
+ Storage Daemon utilise la valeur par d\'efaut de 64 512 octets.
+
+\item [Hardware End of Medium = {\it Yes|No}]
+ \index[sd]{Hardware End of Medium}
+ \index[sd]{Directive!Hardware End of Medium}
+ Si la valeur attribu\'ee \`a cette directive est {\bf No}, le p\'eriph\'erique de
+ stockage n'a pas besoin de supporter les requ\^etes ioctl "fin de m\'edium",
+ le Storage Daemon utilisant la fonction d'avance jusqu'au prochain espace
+ pour trouver la fin du m\'edium. Si la valeur est {\bf Yes}, le p\'eriph\'erique
+ doit supporter l'appel {\tt ioctl} {\tt MTEOM} qui positionne la cartouche
+ \`a la fin des donn\'ees enregistr\'ees. De plus, votre driver SCSI doit garder trace
+ du nombre de fichiers enregistr\'es sur la cartouche, et le retourner correctement
+ \`a l'appel {\bf MTIOCGET} ioctl. Notez que certains pilotes SCSI savent se
+ positionner correctement \`a la fin de la zone de donn\'ees enregistr\'ees sur la cartouche,
+ mais ne gardent pas trace du nombre de fichiers. Sur les machines Linux, le
+ driver SCSI a une option {\bf fast-eod} qui, si elle est utilis\'ee
+ provoque la perte du nombre de fichiers. assurez-vous toujours que cette
+ option est bien d\'esactiv\'ee (\`a l'aide du programme {\bf mt}).
+
+ Le r\'eglage par d\'efaut de cette directive est {\bf Yes}. Cette option est utilis\'ee
+ lors de l'\'ecriture \`a la suite d'une cartouche, pour s'assurer que les donn\'ees
+ pr\'ec\'edemment \'ecrites ne seront pas corrompues. Nous vous recommandons, si vous
+ avez un lecteur non-standard ou inhabituel, de le tester avec le programme
+ {\bf btape} pour v\'erifier s'il supporte ou non cette fonction. Tous les lecteurs
+ modernes (au del\`a de 1998) la supportent.
+
+\item [Fast Forward Space File = {\it Yes|No}]
+ \index[sd]{Fast Forward Space File}
+ \index[sd]{Directive!Fast Forward Space File}
+ Si la valeur attribu\'ee \`a cette directive est {\bf No}, le p\'eriph\'erique de
+ stockage n'a pas besoin de supporter les requ\^etes ioctl {\bf MTIOCGET}
+ "nombre de fichiers" lors du d\'eplacement sur la bande jusqu'au prochain espace. Si au contraire
+ vous sp\'ecifiez {\bf yes}, le lecteur doit supporter l'appel {\tt ioctl} {\tt MTFSF},
+ que presque tous les pilotes supportent, mais de plus votre pilote SCSI doit
+ garder trace et retourner correctement le nombre de fichiers \`a l'appel
+ ioctl {\bf MTIOCGET} . Notez que certains pilotes SCSI ex\'ecutent correctement
+ les d\'eplacements sur bande "jusqu'au prochain espace" sans toutefois garder trace
+ du nombre de fichiers enregistr\'es, et m\^eme plus grave pour certains : sans
+ signaler la fin du support.
+
+ La valeur par d\'efaut de cette directive est {\bf Yes}.
+
+\item [Use MTIOCGET = {\it Yes|No}]
+ \index[sd]{Use MTIOCGET}
+ \index[sd]{Directive!Use MTIOCGET}
+ Si la valeur attribu\'ee \`a cette directive est {\bf No}, le syst\`eme d'exploitation
+ n'a pas besoin de garder trace du nombre de fichiers sur la cartouche, ni de
+ le retourner \`a l'appel ioctl {\bf MTIOCGET}. La valeur par d\'efaut est {\bf Yes}.
+ Si vous devez mettre No ici, Bacula prendra en charge la d\'etermination des
+ positions de fichiers, mais cela implique des mouvements tr\`es inefficaces de la
+ bande. Heureusement, cette d\'eficience du syst\`eme d'exploitation semble n'\^etre
+ l'apanage que de quelques *BSD. Solaris, Linux et FreeBSD sont connus pour
+ fonctionner correctement.
+
+\item [BSF at EOM = {\it Yes|No}]
+ \index[sd]{BSF at EOM}
+ \index[sd]{Directive!BSF at EOM}
+ Si cette directive est \`a {\bf No} (valeur par d\'efaut), Bacula n'entreprend
+ aucune action particuli\`ere lorsque la fin du m\'edium est atteinte car
+ la cartouche est positionn\'ee apr\`es la derni\`ere marque de fin de fichier EOF,
+ et Bacula peut \'ecrire \`a la suite. Cependant, sur certains syst\`emes tels que
+ FreeBSD, lorsque Bacula lit la marque de fin de cartouche, la cartouche est
+ positionn\'ee apr\`es la seconde marque de fin de fichier EOF (deux marques EOF
+ successives indiquent la fin du support). Si Bacula \'ecrit au del\`a de cette
+ marque, toutes les donn\'ees ajout\'ees seront perdues. La solutions pour ces syst\`emes
+ consiste \`a sp\'ecifier {\bf BSF at EOM}, ainsi Bacula recule en \'ecrasant la
+ seconde marque de fin de fichier. Pour savoir si vous avez besoin de cette
+ directive, utilisez la commande {\bf test} du programme {\bf btape}.
+
+(NDT : Paragraphe \`a revoir VO ci dessous)
+ If {\bf No}, the default, no special action is taken by Bacula with the End
+ of Medium (end of tape) is reached because the tape will be positioned after
+ the last EOF tape mark, and Bacula can append to the tape as desired.
+ However, on some systems, such as FreeBSD, when Bacula reads the End of
+ Medium (end of tape), the tape will be positioned after the second EOF tape
+ mark (two successive EOF marks indicated End of Medium). If Bacula appends
+ from that point, all the appended data will be lost. The solution for such
+ systems is to specify {\bf BSF at EOM} which causes Bacula to backspace over
+ the second EOF mark. Determination of whether or not you need this directive
+ is done using the {\bf test} command in the {\bf btape} program.
+
+\item [TWO EOF = {\it Yes|No}]
+ \index[sd]{TWO EOF}
+ \index[sd]{Directive!TWO EOF}
+ Si cette directive est \`a {\bf Yes}, Bacula \'ecrit deux marques de fin de fichier EOF
+ lorsqu'il a fini d'utiliser une cartouche -- c'est \`a dire apr\`es le dernier
+ job, ou \`a la fin de la cartouche. Dans le cas contraire (la valeur par d\'efaut),
+ Bacula n'\'ecrit qu'une marque de fin de fichier pour terminer une cartouche.
+
+\item [Backward Space Record = {\it Yes|No}]
+ \index[sd]{Backward Space Record}
+ \index[sd]{Directive!Backward Space Record}
+ Si cette directive est \`a {\bf Yes}, le p\'eriph\'erique supporte {\tt MTBSR ioctl}
+ pour reculer dans les enregistrements. Sinon, cet appel n'est pas utilis\'e
+ et la bande doit \^etre rembobin\'ee puis avanc\'ee de fichier en fichier jusqu'\`a
+ la position d\'esir\'ee. La valeur par d\'efaut est {\bf Yes} pour un p\'eriph\'erique
+ \`a acc\`es s\'equentiel. Cette fonction, si activ\'ee, est utilis\'ee \`a la fin des
+ volumes apr\`es \'ecriture d'une marque fin de fichier et de toute \'etiquette
+ ANSI/IBM pour d\'eterminer si oui ou non le dernier bloc a \'et\'e \'ecrit
+ correctement. Si vous d\'esactivez cette fonction, le test ne sera pas fait.
+ Ce n'est pas un probl\`eme car le processus de relecture est une
+ pr\'ecaution plut\^ot qu'une n\'ecessit\'e.
+
+\item [Backward Space File = {\it Yes|No}]
+ \index[sd]{Backward Space File}
+ \index[sd]{Directive!Backward Space File}
+ Si cette directive est \`a {\bf Yes}, le p\'eriph\'erique supporte les appels
+ {\bf MTBSF} et {\bf ioctl MTBSF} pour reculer en-de\c{c}a d'un marque de fin de fichier
+ et se replacer au d\'ebut du fichier. Si cette directive est \`a {\bf No}, ces appels
+ ne sont pas utilis\'es et le lecteur doit rembobiner la cartouche, puis avancer
+ de fichier en fichier jusqu'\`a la position d\'esir\'ee. La valeur par d\'efaut est
+ {\bf Yes} pour les p\'eriph\'eriques \`a acc\`es s\'equentiel.
+
+\item [Forward Space Record = {\it Yes|No}]
+ \index[sd]{Forward Space Record}
+ \index[sd]{Directive!Forward Space Record}
+ Si cette directive est \`a {\bf Yes}, le p\'eriph\'erique doit supporter les appels
+ {\bf MTFSR ioctl} pour avancer \`a travers les
+ enregistrements. Si la valeur est {\bf No}, les donn\'ees doivent \^etre lues dans l'ordre
+ pour positionner la cartouche. La valeur par d\'efaut est
+ {\bf Yes} pour les p\'eriph\'eriques \`a acc\`es s\'equentiel.
+
+\item [Forward Space File = {\it Yes|No}]
+ \index[sd]{Forward Space File}
+ \index[sd]{Directive!Forward Space File}
+ Si cette directive est \`a {\bf Yes}, le p\'eriph\'erique doit supporter les appels
+ {\tt MTFSF ioctl} pour d\'eplacer la bande en se rep\'erant aux marques de fichiers.
+ Si la valeur est {\bf No}, les donn\'ees doivent \^etre lues pour positionner la
+ bande. La valeur par d\'efaut est
+ {\bf Yes} pour les p\'eriph\'eriques \`a acc\`es s\'equentiel.
+
+\item [Offline On Unmount = {\it Yes|No}]
+ \index[sd]{Offline On Unmount}
+ \index[sd]{Directive!Offline On Unmount}
+ Si cette directive est \`a {\bf Yes}, le p\'eriph\'erique doit supporter les appels
+ {\tt MTOFFL ioctl} pour rembobiner et placer le volume \`a l'\'etat {\it offline}.
+ Dans ce cas, Bacula lance requ\^ete {\it eject} avant de fermer le lecteur lors
+ de la commande {\bf unmount}. Si la valeur est {\bf No} (valeur par d\'efaut),
+ Bacula ne tente pas de mettre la cartouche \`a l'\'etat {\it offline} avant de
+ la d\'emonter. Apr\`es que la cartouche ait \'et\'e mise hors ligne, elle est \'eject\'ee
+ requ\'erant ainsi {\bf l'intervention d'un op\'erateur} pour poursuivre. Certains
+ syst\`emes exigent que la commande de chargement {\bf mt -f /dev/xxx load}
+ soit lanc\'ee avant de pouvoir reconna\^itre la cartouche. Si vous utilisez une
+ librairie, sachez que certaines requi\`erent de passer le lecteur \`a l'\'etat
+ {\it offline} pour pouvoir changer de cartouche. Cependant, la plupart n'en
+ on pas besoin et pourraient \^etre d\'erout\'es si cette directive est \`a {\bf Yes}.
+
+ Si vous utilisez un noyau Linux 2.6, ou un syst\`eme tel que FreeBSD ou Solaris,
+ la directive Offline On Unmount abandonnera votre lecteur sans cartouche, et Bacula
+ incapable de l'utiliser. Pour plus d'informations sur ce probl\`eme,
+ consultez la section \ilink{description de Offline On Unmount}{NoTapeInDrive} dans le
+ chapitre sur les tests de lecteurs.
+
+\item [Maximum Volume Size = {\it size}]
+ \index[sd]{Maximum Volume Size}
+ \index[sd]{Directive!Maximum Volume Size}
+ Avec cette directive, vous pouvez imposer une limite au poids de donn\'ees
+ \`a \'ecrire sur chaque volume. La valeur {\bf size} repr\'esente le nombre d'octets
+ autoris\'es. Cette directive est surtout utilis\'ee \`a des fins de tests pour
+ simuler des petits volumes, mais elle peut aussi se r\'ev\'eler utile si voulez
+ limiter la taille de vos volumes, par exemple \`a 2 Go. Certains rares lecteurs
+ vraiment anciens ne signalent pas correctement lorsque la fin de la
+ cartouche est atteinte lors d'une op\'eration d'\'ecriture (Bien que j'aie lu des
+ choses au sujet de tels lecteurs, je n'en n'ai jamais rencontr\'e moi-m\^eme). Notez
+ que cette directive est obsol\`ete, rendue inutile par la
+ directive {\bf Maximum Volume Bytes} d\'efinie dans le fichier de configuration
+ du Director.
+
+\item [Maximum File Size = {\it size}]
+ \index[sd]{Maximum File Size}
+ \index[sd]{Directive!Maximum File Size}
+ Cette directive vous permet d'imposer une limite au poids des fichiers logiques
+ sur le volume. La valeur {\bf size} repr\'esente le nombre d'octets autoris\'es
+ par fichier. Une fois cette valeur atteinte, une marque de fin de fichier est
+ plac\'ee sur le volume et les donn\'ees suivantes sont plac\'ees dans un nouveau
+ fichier. Ce d\'ecoupage des longues s\'equences de donn\'ees en blocs plus petits
+ permet un positionnement plus rapide du lecteur au d\'ebut d'un flux de donn\'ees
+ et peut contribuer \`a pr\'evenir les erreurs de lecture sur la cartouche lors des
+ restaurations. La valeur par d\'efaut est 1 Go.
+
+\item [Block Positioning = {\it yes|no}]
+ \index[sd]{Block Positioning}
+ \index[sd]{Directive!Block Positioning}
+ Cette directive n'est pas utilis\'ee en fonctionnement normal (et n'a pas encore
+ \'et\'e test\'ee). Son r\^ole est d'enjoindre Bacula \`a ne plus utiliser le
+ positionnement par blocs lors de la lecture des cartouches. Ceci peut rendre
+ les op\'erations de restauration {\bf extr\`emement} lentes. Vous utiliserez cette
+ directive si vous avez \'ecrit vos cartouches avec Bacula en mode "taille de blocs
+ variable" tandis que votre lecteur \'etait en taille de blocs fixe. Si tout
+ fonctionne comme je l'esp\`ere, Bacula sera capable de relire vos cartouches.
+
+\item [Maximum Network Buffer Size = {\it bytes}]
+ \index[sd]{Maximum Network Buffer Size}
+ \index[sd]{Directive!Maximum Network Buffer Size}
+ Cette directive permet de sp\'ecifier la taille initiale du tampon r\'eseau \`a
+ utiliser avec le File Daemon. La valeur {\bf bytes} est la taille exprim\'ee
+ en octets. Cette valeur es appel\'ee \`a \^etre ajust\'ee \`a la baisse si elle est
+ trop importante, jusqu'\`a ce qu'elle soit accep\'ee par le syst\`eme d'exploitation.
+ Soyez circonspect dans l'usage de cette directive, car si vous utilisez une
+ valeur trop grande, elle sera diminu\'ee par incr\'ements de 521 octets jusqu'\`a
+ satisfaction du syst\`eme d'exploitation, ce qui peut n\'ecessiter un grand nombre
+ d'appels syst\`eme. La valeur par d\'efaut est 32 768 octets.
+
+ La valeur par d\'efaut a \'et\'e choisie relativement importante, mais pas trop,
+ au cas ou vous transmettriez vos donn\'ees via Internet. Il est clair que sur
+ un r\'eseau local rapide, vous pouvez augmenter cette valeur et am\'eliorer les
+ performances. Par exemple, certains utilisateurs ont obtenu des facteurs
+ d'acc\'el\'eration de l'ordre de 5 \`a 10 en utilisant un tampon r\'eseau initial de
+ 65 536 octets. La plupart des utilisateurs indiquent que des valeurs plus
+ grandes ne semblent pas am\'eliorer les performances. Si vous voulez am\'eliorer
+ la viteese de vos sauvegardes, cette directive est probablement le meilleur
+ endroit pour exp\'erimenter. Vous voudrez probablement effectuer les
+ modifications correspondantes dans les fichiers de configuration de chacun
+ des File Daemons.
+
+\item [Maximum Spool Size = {\it bytes}]
+ \index[sd]{Maximum Spool Size}
+ \index[sd]{Directive!Maximum Spool Size}
+ Cette directive limite \`a la valeur sp\'ecifi\'ee (en octets) le volume occup\'e par
+ le tampon (NDT : spool) disque pour tous les jobs en ex\'ecution. Par d\'efaut, il n'y a
+ pas de limite.
+
+\item [Maximum Job Spool Size = {\it bytes}]
+ \index[sd]{Maximum Job Spool Size}
+ \index[sd]{Directive!Maximum Job Spool Size}
+ Cette directive limite \`a la valeur sp\'ecifi\'ee (en octets) le volume occup\'e par
+ le tampon disque pour chaque job. Par d\'efaut, il n'y a pas de limite. Cette
+ directive est apparue avel la version 1.37.
+
+\item [Spool Directory = {\it directory}]
+ \index[sd]{Spool Directory}
+ \index[sd]{Directive!Spool Directory}
+ Cette directive sp\'ecifie le nom du r\'epertoire \`a utiliser en tant que tampon
+ disque pour ce p\'eriph\'erique. Ce r\'epertoire est aussi utilis\'e pour stocker
+ les fichiers partiels lors de l'\'ecriture sur des supports qui requi\`erent
+ un montage (DVD). Le comportement par d\'efaut est d'utiliser le r\'epertoire
+ de travail de Bacula (working directory).
+
+\item [Maximum Part Size = {\it bytes}]
+ \index[sd]{Maximum Part Size}
+ \index[sd]{Directive!Maximum Part Size}
+ Cette directive pr\'ecise la taille maximale (en octets) d'un fichier partiel. Par d\'efaut,
+ il n'y a pas de limite. Cette directive est apparue avec la version 1.37.
+
+ Si le p\'eriph\'erique requiert un montage, l'ordre de montage est transmis lorsque
+ cette valeur est atteinte. Dans ce cas, vous devez vous assurer d'avor suffisament
+ d'espace dans votre r\'epertoire tampon, faute de quoi vos donn\'ees resteront dans le
+ r\'epertoire tampon.
+
+ Cette directive est ignor\'ee pour les lecteurs de bandes et les FIFO.
+
+\end{description}
+
+\section{P\'eriph\'eriques qui requi\`erent un montage (DVD)}
+\index[general]{P\'eriph\'eriques qui requi\`erent un montage (DVD)}
+\index[general]{DVD!P\'eriph\'eriques qui requi\`erent un montage}
+\addcontentsline{toc}{section}{P\'eriph\'eriques qui requi\`erent un montage (DVD)}
+
+Toutes les directives d\'ecrites dans cette section sont impl\'ement\'ees dans Bacula
+\`a partir de la version 1.37.
+
+A partir de la version 1.39.5, les directives "Requires Mount", "Mount Point",
+"Mount Command", et "Unmount Command" s'appliquent aux syst\`emes de fichiers
+amovibles tels que les p\'erih\'eriques USB, et plus seulement aux DVDs.
+
+\begin{description}
+
+\item [Requires Mount = {\it Yes|No}]
+ \index[sd]{Requires Mount}
+ \index[sd]{Directive!Requires Mount}
+ Cette directive doit \^etre \`a {\bf yes} pour les graveurs de DVDs, et \`a {\bf no}
+ pour tous les autres p\'eriph\'eriques (cartouches/fichiers). Elle indique si
+ le p\'eriph\'erique n\'ecessite d'\^etre mont\'e pour \^etre lu, et si un moyen particulier
+ doit \^etre employ\'e pour y \'ecrire. Si vous activez cette directive, vous devez aussi
+ d\'efinir les directives {\bf Mount Point}, {\bf Mount Command}, {\bf Unmount Command}
+ et {\bf Write Part Command}.
+
+\item [Mount Point = {\it directory}]
+ \index[sd]{Mount Point}
+ \index[sd]{Directive!Mount Point}
+ Cette directive sp\'ecifie le r\'epertoire o\`u le p\'eriph\'erique peut \^etre mont\'e.
+ (le point de montage)
+
+\item [Mount Command = {\it name-string}]
+ \index[sd]{Mount Command}
+ \index[sd]{Directive!Mount Command}
+ Cette directive sp\'ecifie la commande \`a ex\'ecuter pour monter le p\'eriph\'erique.
+ Avant l'ex\'ecution de la commande, \%a est remplac\'e par le p\'eriph\'erique de
+ stockage, et \%m par le point de montage (Mount Point).
+
+ La plupart du temps, vous le d\'efinirez ainsi :
+
+\footnotesize
+\begin{verbatim}
+ Mount Command = "/bin/mount -t iso9660 -o ro %a %m"
+\end{verbatim}
+\normalsize
+
+\item [Unmount Command = {\it name-string}]
+ \index[sd]{Unmount Command}
+ \index[sd]{Directive!Unmount Command}
+ Cette directive sp\'ecifie la commande \`a ex\'ecuter pour d\'emonter le p\'eriph\'erique.
+ Avant l'ex\'ecution de la commande, \%a est remplac\'e par le p\'eriph\'erique de
+ stockage, et \%m par le point de montage (Mount Point).
+
+ La plupart du temps, vous le d\'efinirez ainsi :
+
+\footnotesize
+\begin{verbatim}
+ Unmount Command = "/bin/umount %m"
+\end{verbatim}
+\normalsize
+
+\item [Write Part Command = {\it name-string}]
+ \index[sd]{Write Part Command}
+ \index[sd]{Directive!Write Part Command}
+ Cette directive sp\'ecifie la commande \`a ex\'ecuter pour \'ecrire une partition (NDT : Revoir cette partie, VO ci-dessous)
+ sur le p\'eriph\'erique. Avant l'ex\'ecution de la commande, \%a est remplac\'e par le p\'eriph\'erique de
+ stockage, \%m par le point de montage, \%e par 1 s'il s'agit de la premi\`ere
+ partition, 0 sinon, et \%v avec le nom de fichier de la partition courante.
+
+ Pour un DVD, vous utiliserez la plupart du temps le script fourni {\bf dvd-handler}
+ comme suit :
+
+Command that must be executed to write a part to the device. Before the
+ command is executed, \%a is replaced with the Archive Device, \%m with the
+ Mount Point, \%e is replaced with 1 if we are writing the first part,
+ and with 0 otherwise, and \%v with the current part filename.
+
+ For a DVD, you will most frequently specify the Bacula supplied {\bf
+ dvd-handler} script as follows:
+
+\footnotesize
+\begin{verbatim}
+ Write Part Command = "/path/dvd-handler %a write %e %v"
+\end{verbatim}
+\normalsize
+
+ O\`u {\bf /path} est le chemin vers votre r\'epertoire de scripts, et
+ dvd-handler est le script fourni avec Bacula. Cette commande est d\'ej\`a pr\'esente
+ quoique comment\'ee dans le fichier de configuration du Storage Daemon. Pour l'utiliser,
+ il vous suffit de supprimer le caract\`ere \#.
+
+\item [Free Space Command = {\it name-string}]
+ \index[sd]{Free Space Command}
+ \index[sd]{Directive!Free Space Command}
+ Cette directive sp\'ecifie la commande \`a ex\'ecuter pour contr\^oler l'espace disponible
+ sur le p\'eriph\'erique. Avant l'ex\'ecution de la commande, \%a est remplac\'e par le p\'eriph\'erique de
+ stockage, \%m par le point de montage, \%e par 1 s'il s'agit de la premi\`ere
+ partition, 0 sinon, et \%v avec le nom de fichier de la partition courante.
+
+ Pour un DVD, vous utiliserez la plupart du temps le script fourni {\bf dvd-handler}
+ comme suit :
+
+\footnotesize
+\begin{verbatim}
+ Free Space Command = "/path/dvd-handler %a free"
+\end{verbatim}
+\normalsize
+
+ O\`u {\bf /path} est le chemin vers votre r\'epertoire de scripts, et
+ dvd-handler est le script fourni avec Bacula. Si vous voulez
+ sp\'ecifier votre propre commande, examinez le code de dvd-handler afin de
+ voir le type de retour attendu par Bacula. Cette commande est d\'ej\`a pr\'esente
+ quoique comment\'ee dans le fichier de configuration du Storage Daemon. Pour l'utiliser,
+ il vous suffit de supprimer le caract\`ere \#.
+
+ Si vous n'utilisez pas cette directive, Bacula s'attendra \`a ce qu'il y ait
+ toujours de la place dur le p\'eriph\'erique.
+
+\end{description}
+
+%% This pulls in the Autochanger resource from another file.
+\label{AutochangerRes}
+\label{AutochangerResource1}
+\input{autochangerres}
+
+
+\section{Possibilit\'es}
+\index[general]{Possibilit\'es}
+\addcontentsline{toc}{section}{Possibilit\'es}
+
+\begin{description}
+
+\item [Label media = {\it Yes|No}]
+ \index[sd]{Label media}
+ \index[sd]{Directive!Label media}
+ Si cette directive est activ\'ee ({\bf Yes}), alors ce p\'eriph\'erique est
+ habilit\'e \`a \'etiqueter les media libres sans ordre explicite de l'op\'erateur.
+ Ceci est r\'ealis\'e selon un algorithme interne et suivant le format
+ d\'efini par l'enregistrement \ilink{Label Format}{Label} de chaque
+ ressource Pool. Si cette directive est \`a {\bf No} (valeur par d\'efaut),
+ Bacula n'\'etiquette les cartouches que sur instruction expresse de
+ l'op\'erateur (commande {\bf label} de la Console) ou lorsqu'une cartouche
+ a \'et\'e recycl\'ee. Cette fonctionnalit\'e est plus utile dans le cas de sauvegardes
+ sur disque qu'avec des cartouches.
+
+\item [Automatic mount = {\it Yes|No}]
+ \index[sd]{Automatic mount}
+ \index[sd]{Directive!Automatic mount}
+ Si cette directive est activ\'ee (c'est le cas par d\'efaut), le Storage Daemon
+ est autoris\'e \`a examiner le p\'eriph\'erique afin de d\'eterminer s'il contient
+ un volume \'etiquet\'e Bacula. Ceci est alors fait au d\'emarrage du {\it daemon},
+ et au d\'ebut de chaque job. Cette directive est particuli\`erement importante
+ si vous avez sp\'ecifi\'e {\bf Always Open = no} car elle permet \`a
+ Bacula de tenter de lire le p\'eriph\'erique avant de demander \`a l'op\'erateur
+ de monter une cartouche. Notez cependant que la cartouche doit \^etre
+ mont\'ee avant le lancement du job.
+
+\end{description}
+
+\section{La ressource Messages}
+\label{MessagesResource1}
+\index[general]{Ressource!Messages}
+\index[general]{Ressource Messages}
+\addcontentsline{toc}{section}{Resource Messages}
+
+Pour une description de la ressource Messages, veuillez consulter
+le chapitre \ilink{La ressource Messages}{_ChapterStart15} de ce
+manuel.
+
+\section{Un exemple de fichier de configuration du Storage Daemon}
+\label{SampleConfiguration}
+\index[general]{Fichier!Exemple configuration Storage Daemon}
+\index[general]{Exemple fichier configuration Storage Daemon}
+\addcontentsline{toc}{section}{Exemple fichier configuration Storage Daemon}
+
+Voici un exemple de fichier de configuration du Storage Daemon :
+
+\footnotesize
+\begin{verbatim}
+#
+# Default Bacula Storage Daemon Configuration file
+#
+# For Bacula release 1.37.2 (07 July 2005) -- gentoo 1.4.16
+#
+# You may need to change the name of your tape drive
+# on the "Archive Device" directive in the Device
+# resource. If you change the Name and/or the
+# "Media Type" in the Device resource, please ensure
+# that bacula-dir.conf has corresponding changes.
+#
+Storage { # definition of myself
+ Name = rufus-sd
+ Address = rufus
+ WorkingDirectory = "$HOME/bacula/bin/working"
+ Pid Directory = "$HOME/bacula/bin/working"
+ Maximum Concurrent Jobs = 20
+}
+#
+# List Directors who are permitted to contact Storage daemon
+#
+Director {
+ Name = rufus-dir
+ Password = "ZF9Ctf5PQoWCPkmR3s4atCB0usUPg+vWWyIo2VS5ti6k"
+}
+#
+# Restricted Director, used by tray-monitor to get the
+# status of the storage daemon
+#
+Director {
+ Name = rufus-mon
+ Password = "9usxgc307dMbe7jbD16v0PXlhD64UVasIDD0DH2WAujcDsc6"
+ Monitor = yes
+}
+#
+# Devices supported by this Storage daemon
+# To connect, the Director's bacula-dir.conf must have the
+# same Name and MediaType.
+#
+Autochanger {
+ Name = Autochanger
+ Device = Drive-1
+ Device = Drive-2
+ Changer Command = "/home/kern/bacula/bin/mtx-changer %c %o %S %a %d"
+ Changer Device = /dev/sg0
+}
+
+Device {
+ Name = Drive-1 #
+ Drive Index = 0
+ Media Type = DLT-8000
+ Archive Device = /dev/nst0
+ AutomaticMount = yes; # when device opened, read it
+ AlwaysOpen = yes;
+ RemovableMedia = yes;
+ RandomAccess = no;
+ AutoChanger = yes
+ Alert Command = "sh -c 'tapeinfo -f %c |grep TapeAlert|cat'"
+}
+
+Device {
+ Name = Drive-2 #
+ Drive Index = 1
+ Media Type = DLT-8000
+ Archive Device = /dev/nst1
+ AutomaticMount = yes; # when device opened, read it
+ AlwaysOpen = yes;
+ RemovableMedia = yes;
+ RandomAccess = no;
+ AutoChanger = yes
+ Alert Command = "sh -c 'tapeinfo -f %c |grep TapeAlert|cat'"
+}
+
+Device {
+ Name = "HP DLT 80"
+ Media Type = DLT8000
+ Archive Device = /dev/nst0
+ AutomaticMount = yes; # when device opened, read it
+ AlwaysOpen = yes;
+ RemovableMedia = yes;
+}
+#Device {
+# Name = SDT-7000 #
+# Media Type = DDS-2
+# Archive Device = /dev/nst0
+# AutomaticMount = yes; # when device opened, read it
+# AlwaysOpen = yes;
+# RemovableMedia = yes;
+#}
+#Device {
+# Name = Floppy
+# Media Type = Floppy
+# Archive Device = /mnt/floppy
+# RemovableMedia = yes;
+# Random Access = Yes;
+# AutomaticMount = yes; # when device opened, read it
+# AlwaysOpen = no;
+#}
+#Device {
+# Name = FileStorage
+# Media Type = File
+# Archive Device = /tmp
+# LabelMedia = yes; # lets Bacula label unlabeled media
+# Random Access = Yes;
+# AutomaticMount = yes; # when device opened, read it
+# RemovableMedia = no;
+# AlwaysOpen = no;
+#}
+#Device {
+# Name = "NEC ND-1300A"
+# Media Type = DVD
+# Archive Device = /dev/hda
+# LabelMedia = yes; # lets Bacula label unlabeled media
+# Random Access = Yes;
+# AutomaticMount = yes; # when device opened, read it
+# RemovableMedia = yes;
+# AlwaysOpen = no;
+# MaximumPartSize = 800M;
+# RequiresMount = yes;
+# MountPoint = /mnt/cdrom;
+# MountCommand = "/bin/mount -t iso9660 -o ro %a %m";
+# UnmountCommand = "/bin/umount %m";
+# SpoolDirectory = /tmp/backup;
+# WritePartCommand = "/etc/bacula/dvd-handler %a write %e %v"
+# FreeSpaceCommand = "/etc/bacula/dvd-handler %a free"
+#}
+#
+# A very old Exabyte with no end of media detection
+#
+#Device {
+# Name = "Exabyte 8mm"
+# Media Type = "8mm"
+# Archive Device = /dev/nst0
+# Hardware end of medium = No;
+# AutomaticMount = yes; # when device opened, read it
+# AlwaysOpen = Yes;
+# RemovableMedia = yes;
+#}
+#
+# Send all messages to the Director,
+# mount messages also are sent to the email address
+#
+Messages {
+ Name = Standard
+ director = rufus-dir = all
+ operator = root = mount
+}
+\end{verbatim}
+\normalsize
--- /dev/null
+#!/usr/bin/perl -w
+#
+use strict;
+
+# Used to change the names of the image files generated by latex2html from imgxx.png
+# to meaningful names. Provision is made to go either from or to the meaningful names.
+# The meaningful names are obtained from a file called imagename_translations, which
+# is generated by extensions to latex2html in the make_image_file subroutine in
+# bacula.perl.
+
+# Opens the file imagename_translations and reads the contents into a hash.
+# The hash is creaed with the imgxx.png files as the key if processing TO
+# meaningful filenames, and with the meaningful filenames as the key if
+# processing FROM meaningful filenames.
+# Then opens the html file(s) indicated in the command-line arguments and
+# changes all image references according to the translations described in the
+# above file. Finally, it renames the image files.
+#
+# Original creation: 3-27-05 by Karl Cunningham.
+# Modified 5-21-05 to go FROM and TO meaningful filenames.
+#
+my $TRANSFILE = "imagename_translations";
+my $path;
+
+# Loads the contents of $TRANSFILE file into the hash referenced in the first
+# argument. The hash is loaded to translate old to new if $direction is 0,
+# otherwise it is loaded to translate new to old. In this context, the
+# 'old' filename is the meaningful name, and the 'new' filename is the
+# imgxx.png filename. It is assumed that the old image is the one that
+# latex2html has used as the source to create the imgxx.png filename.
+# The filename extension is taken from the file
+sub read_transfile {
+ my ($trans,$direction) = @_;
+
+ if (!open IN,"<$path$TRANSFILE") {
+ print "WARNING: Cannot open image translation file $path$TRANSFILE for reading\n";
+ print " Image filename translation aborted\n\n";
+ exit 0;
+ }
+
+ while (<IN>) {
+ chomp;
+ my ($new,$old) = split(/\001/);
+
+ # Old filenames will usually have a leading ./ which we don't need.
+ $old =~ s/^\.\///;
+
+ # The filename extension of the old filename must be made to match
+ # the new filename because it indicates the encoding format of the image.
+ my ($ext) = $new =~ /(\.[^\.]*)$/;
+ $old =~ s/\.[^\.]*$/$ext/;
+ if ($direction == 0) {
+ $trans->{$new} = $old;
+ } else {
+ $trans->{$old} = $new;
+ }
+ }
+ close IN;
+}
+
+# Translates the image names in the file given as the first argument, according to
+# the translations in the hash that is given as the second argument.
+# The file contents are read in entirely into a string, the string is processed, and
+# the file contents are then written. No particular care is taken to ensure that the
+# file is not lost if a system failure occurs at an inopportune time. It is assumed
+# that the html files being processed here can be recreated on demand.
+#
+# Links to other files are added to the %filelist for processing. That way,
+# all linked files will be processed (assuming they are local).
+sub translate_html {
+ my ($filename,$trans,$filelist) = @_;
+ my ($contents,$out,$this,$img,$dest);
+ my $cnt = 0;
+
+ # If the filename is an external link ignore it. And drop any file:// from
+ # the filename.
+ $filename =~ /^(http|ftp|mailto)\:/ and return 0;
+ $filename =~ s/^file\:\/\///;
+ # Load the contents of the html file.
+ if (!open IF,"<$path$filename") {
+ print "WARNING: Cannot open $path$filename for reading\n";
+ print " Image Filename Translation aborted\n\n";
+ exit 0;
+ }
+
+ while (<IF>) {
+ $contents .= $_;
+ }
+ close IF;
+
+ # Now do the translation...
+ # First, search for an image filename.
+ while ($contents =~ /\<\s*IMG[^\>]*SRC=\"/si) {
+ $contents = $';
+ $out .= $` . $&;
+
+ # The next thing is an image name. Get it and translate it.
+ $contents =~ /^(.*?)\"/s;
+ $contents = $';
+ $this = $&;
+ $img = $1;
+ # If the image is in our list of ones to be translated, do it
+ # and feed the result to the output.
+ $cnt += $this =~ s/$img/$trans->{$img}/ if (defined($trans->{$img}));
+ $out .= $this;
+ }
+ $out .= $contents;
+
+ # Now send the translated text to the html file, overwriting what's there.
+ open OF,">$path$filename" or die "Cannot open $path$filename for writing\n";
+ print OF $out;
+ close OF;
+
+ # Now look for any links to other files and add them to the list of files to do.
+ while ($out =~ /\<\s*A[^\>]*HREF=\"(.*?)\"/si) {
+ $out = $';
+ $dest = $1;
+ # Drop an # and anything after it.
+ $dest =~ s/\#.*//;
+ $filelist->{$dest} = '' if $dest;
+ }
+ return $cnt;
+}
+
+# REnames the image files spefified in the %translate hash.
+sub rename_images {
+ my $translate = shift;
+ my ($response);
+
+ foreach (keys(%$translate)) {
+ if (! $translate->{$_}) {
+ print " WARNING: No destination Filename for $_\n";
+ } else {
+ $response = `mv -f $path$_ $path$translate->{$_} 2>&1`;
+ $response and print "ERROR from system $response\n";
+ }
+ }
+}
+
+#################################################
+############# MAIN #############################
+################################################
+
+# %filelist starts out with keys from the @ARGV list. As files are processed,
+# any links to other files are added to the %filelist. A hash of processed
+# files is kept so we don't do any twice.
+
+# The first argument must be either --to_meaningful_names or --from_meaningful_names
+
+my (%translate,$search_regex,%filelist,%completed,$thisfile);
+my ($cnt,$direction);
+
+my $arg0 = shift(@ARGV);
+$arg0 =~ /^(--to_meaningful_names|--from_meaningful_names)$/ or
+ die "ERROR: First argument must be either \'--to_meaningful_names\' or \'--from_meaningful_names\'\n";
+
+$direction = ($arg0 eq '--to_meaningful_names') ? 0 : 1;
+
+(@ARGV) or die "ERROR: Filename(s) to process must be given as arguments\n";
+
+# Use the first argument to get the path to the file of translations.
+my $tmp = $ARGV[0];
+($path) = $tmp =~ /(.*\/)/;
+$path = '' unless $path;
+
+read_transfile(\%translate,$direction);
+
+foreach (@ARGV) {
+ # Strip the path from the filename, and use it later on.
+ if (s/(.*\/)//) {
+ $path = $1;
+ } else {
+ $path = '';
+ }
+ $filelist{$_} = '';
+
+ while ($thisfile = (keys(%filelist))[0]) {
+ $cnt += translate_html($thisfile,\%translate,\%filelist) if (!exists($completed{$thisfile}));
+ delete($filelist{$thisfile});
+ $completed{$thisfile} = '';
+ }
+ print "translate_images.pl: $cnt image filenames translated ",($direction)?"from":"to"," meaningful names\n";
+}
+
+rename_images(\%translate);
--- /dev/null
+#!/bin/sh
+#
+# Script file to update the Bacula version
+#
+out=/tmp/$$
+VERSION=`sed -n -e 's/^.*VERSION.*"\(.*\)"$/\1/p' /home/kern/bacula/k/src/version.h`
+DATE=`sed -n -e 's/^.*[ \t]*BDATE.*"\(.*\)"$/\1/p' /home/kern/bacula/k/src/version.h`
+. ./do_echo
+sed -f ${out} version.tex.in >version.tex
+rm -f ${out}
--- /dev/null
+#!/bin/sh
+#
+# Script file to update the Bacula version
+#
+out=/tmp/$$
+VERSION=`sed -n -e 's/^.*VERSION.*"\(.*\)"$/\1/p' @bacula@/src/version.h`
+DATE=`sed -n -e 's/^.*[ \t]*BDATE.*"\(.*\)"$/\1/p' @bacula@/src/version.h`
+. ./do_echo
+sed -f ${out} version.tex.in >version.tex
+rm -f ${out}
--- /dev/null
+2.3.6 (04 November 2007)
--- /dev/null
+@VERSION@ (@DATE@)
--- /dev/null
+#
+#
+# Makefile for LaTeX
+#
+# To build everything do
+# make tex
+# make web
+# make html
+# make dvipdf
+#
+# or simply
+#
+# make
+#
+# for rapid development do:
+# make tex
+# make show
+#
+#
+# If you are having problems getting "make" to work, debugging it is
+# easier if can see the output from latex, which is normally redirected
+# to /dev/null. To see it, do the following:
+#
+# cd docs/manual
+# make tex
+# latex bacula.tex
+#
+# typically the latex command will stop indicating the error (e.g. a
+# missing \ in front of a _ or a missing { or ] ...
+#
+# The following characters must be preceded by a backslash
+# to be entered as printable characters:
+#
+# # $ % & ~ _ ^ \ { }
+#
+
+IMAGES=../../../images
+
+DOC=problems
+
+first_rule: all
+
+all: tex web dvipdf mini-clean
+
+.SUFFIXES: .tex .html
+.PHONY:
+.DONTCARE:
+
+
+tex:
+ @./update_version
+ @echo "Making version `cat version.tex`"
+ @cp -fp ${IMAGES}/hires/*.eps .
+ @touch ${DOC}i-dir.tex ${DOC}i-fd.tex ${DOC}i-sd.tex \
+ ${DOC}i-console.tex ${DOC}i-general.tex
+ latex -interaction=batchmode ${DOC}.tex
+ makeindex ${DOC}.idx -o ${DOC}.ind 2>/dev/null
+ latex -interaction=batchmode ${DOC}.tex
+
+pdf:
+ @echo "Making pdfm"
+ @cp -fp ${IMAGES}/hires/*.eps .
+ dvipdfm -p a4 ${DOC}.dvi
+
+dvipdf:
+ @echo "Making dvi to pdf"
+ @cp -fp ${IMAGES}/hires/*.eps .
+ dvipdf ${DOC}.dvi ${DOC}.pdf
+
+html:
+ @echo " "
+ @echo "Making html"
+ @cp -fp ${IMAGES}/*.eps .
+ @rm -f next.eps next.png prev.eps prev.png up.eps up.png
+ @(if [ -f imagename_translations ] ; then \
+ ./translate_images.pl --from_meaningful_names ${DOC}.html; \
+ fi)
+ latex2html -white -no_subdir -split 0 -toc_stars -white -notransparent \
+ -init_file latex2html-init.pl ${DOC} >tex.out 2>&1
+ ./translate_images.pl --to_meaningful_names ${DOC}.html
+ @echo "Done making html"
+
+web:
+ @echo "Making web"
+ @mkdir -p ${DOC}
+ @cp -fp ${IMAGES}/*.eps .
+ @rm -f next.eps next.png prev.eps prev.png up.eps up.png
+ @cp -fp ${IMAGES}/*.eps ${DOC}/
+ @cp -fp ${IMAGES}/*.eps ${IMAGES}/*.png ${DOC}/
+ @rm -f ${DOC}/xp-*.png
+ @rm -f ${DOC}/next.eps ${DOC}/next.png ${DOC}/prev.eps ${DOC}/prev.png ${DOC}/up.eps ${DOC}/up.png
+ @rm -rf ${DOC}/*.html
+ latex2html -split 3 -local_icons -t "Bacula Problem Resolution Guide" -long_titles 4 \
+ -toc_stars -contents_in_nav -init_file latex2html-init.pl -white -notransparent ${DOC} >tex.out 2>&1
+ ./translate_images.pl --to_meaningful_names ${DOC}/Bacula_Proble*.html
+ @echo "Done making web"
+show:
+ xdvi ${DOC}
+
+texcheck:
+ ./check_tex.pl ${DOC}.tex
+
+main_configs:
+ pic2graph -density 100 <main_configs.pic >main_configs.png
+
+mini-clean:
+ @rm -f 1 2 3 *.tex~
+ @rm -f *.gif *.jpg *.eps
+ @rm -f *.aux *.cp *.fn *.ky *.log *.pg
+ @rm -f *.backup *.ilg *.lof *.lot
+ @rm -f *.cdx *.cnd *.ddx *.ddn *.fdx *.fnd *.ind *.sdx *.snd
+ @rm -f *.dnd *.old *.out
+ @rm -f ${DOC}/*.gif ${DOC}/*.jpg ${DOC}/*.eps
+ @rm -f ${DOC}/*.aux ${DOC}/*.cp ${DOC}/*.fn ${DOC}/*.ky ${DOC}/*.log ${DOC}/*.pg
+ @rm -f ${DOC}/*.backup ${DOC}/*.ilg ${DOC}/*.lof ${DOC}/*.lot
+ @rm -f ${DOC}/*.cdx ${DOC}/*.cnd ${DOC}/*.ddx ${DOC}/*.ddn ${DOC}/*.fdx ${DOC}/*.fnd ${DOC}/*.ind ${DOC}/*.sdx ${DOC}/*.snd
+ @rm -f ${DOC}/*.dnd ${DOC}/*.old ${DOC}/*.out
+ @rm -f ${DOC}/WARNINGS
+ @rm -f ${DOC}i-*.tex
+
+
+clean:
+ @rm -f 1 2 3 *.tex~
+ @rm -f *.png *.gif *.jpg *.eps
+ @rm -f *.pdf *.aux *.cp *.fn *.ky *.log *.pg
+ @rm -f *.html *.backup *.ps *.dvi *.ilg *.lof *.lot
+ @rm -f *.cdx *.cnd *.ddx *.ddn *.fdx *.fnd *.ind *.sdx *.snd
+ @rm -f *.dnd imagename_translations
+ @rm -f *.old WARNINGS *.out *.toc *.idx
+ @rm -f ${DOC}i-*.tex
+ @rm -rf ${DOC}
+
+
+distclean: clean
+ @rm -f images.pl labels.pl internals.pl
+ @rm -f Makefile version.tex
--- /dev/null
+#
+#
+# Makefile for LaTeX
+#
+# To build everything do
+# make tex
+# make web
+# make html
+# make dvipdf
+#
+# or simply
+#
+# make
+#
+# for rapid development do:
+# make tex
+# make show
+#
+#
+# If you are having problems getting "make" to work, debugging it is
+# easier if can see the output from latex, which is normally redirected
+# to /dev/null. To see it, do the following:
+#
+# cd docs/manual
+# make tex
+# latex bacula.tex
+#
+# typically the latex command will stop indicating the error (e.g. a
+# missing \ in front of a _ or a missing { or ] ...
+#
+# The following characters must be preceded by a backslash
+# to be entered as printable characters:
+#
+# # $ % & ~ _ ^ \ { }
+#
+
+IMAGES=../../../images
+
+DOC=problems
+
+first_rule: all
+
+all: tex web dvipdf mini-clean
+
+.SUFFIXES: .tex .html
+.PHONY:
+.DONTCARE:
+
+
+tex:
+ @./update_version
+ @echo "Making version `cat version.tex`"
+ @cp -fp ${IMAGES}/hires/*.eps .
+ @touch ${DOC}i-dir.tex ${DOC}i-fd.tex ${DOC}i-sd.tex \
+ ${DOC}i-console.tex ${DOC}i-general.tex
+ latex -interaction=batchmode ${DOC}.tex
+ makeindex ${DOC}.idx -o ${DOC}.ind 2>/dev/null
+ latex -interaction=batchmode ${DOC}.tex
+
+pdf:
+ @echo "Making pdfm"
+ @cp -fp ${IMAGES}/hires/*.eps .
+ dvipdfm -p a4 ${DOC}.dvi
+
+dvipdf:
+ @echo "Making dvi to pdf"
+ @cp -fp ${IMAGES}/hires/*.eps .
+ dvipdf ${DOC}.dvi ${DOC}.pdf
+
+html:
+ @echo " "
+ @echo "Making html"
+ @cp -fp ${IMAGES}/*.eps .
+ @rm -f next.eps next.png prev.eps prev.png up.eps up.png
+ @(if [ -f imagename_translations ] ; then \
+ ./translate_images.pl --from_meaningful_names ${DOC}.html; \
+ fi)
+ latex2html -white -no_subdir -split 0 -toc_stars -white -notransparent \
+ -init_file latex2html-init.pl ${DOC} >tex.out 2>&1
+ ./translate_images.pl --to_meaningful_names ${DOC}.html
+ @echo "Done making html"
+
+web:
+ @echo "Making web"
+ @mkdir -p ${DOC}
+ @cp -fp ${IMAGES}/*.eps .
+ @rm -f next.eps next.png prev.eps prev.png up.eps up.png
+ @cp -fp ${IMAGES}/*.eps ${DOC}/
+ @cp -fp ${IMAGES}/*.eps ${IMAGES}/*.png ${DOC}/
+ @rm -f ${DOC}/xp-*.png
+ @rm -f ${DOC}/next.eps ${DOC}/next.png ${DOC}/prev.eps ${DOC}/prev.png ${DOC}/up.eps ${DOC}/up.png
+ @rm -rf ${DOC}/*.html
+ latex2html -split 3 -local_icons -t "Bacula Problem Resolution Guide" -long_titles 4 \
+ -toc_stars -contents_in_nav -init_file latex2html-init.pl -white -notransparent ${DOC} >tex.out 2>&1
+ ./translate_images.pl --to_meaningful_names ${DOC}/Bacula_Proble*.html
+ @echo "Done making web"
+show:
+ xdvi ${DOC}
+
+texcheck:
+ ./check_tex.pl ${DOC}.tex
+
+main_configs:
+ pic2graph -density 100 <main_configs.pic >main_configs.png
+
+mini-clean:
+ @rm -f 1 2 3 *.tex~
+ @rm -f *.gif *.jpg *.eps
+ @rm -f *.aux *.cp *.fn *.ky *.log *.pg
+ @rm -f *.backup *.ilg *.lof *.lot
+ @rm -f *.cdx *.cnd *.ddx *.ddn *.fdx *.fnd *.ind *.sdx *.snd
+ @rm -f *.dnd *.old *.out
+ @rm -f ${DOC}/*.gif ${DOC}/*.jpg ${DOC}/*.eps
+ @rm -f ${DOC}/*.aux ${DOC}/*.cp ${DOC}/*.fn ${DOC}/*.ky ${DOC}/*.log ${DOC}/*.pg
+ @rm -f ${DOC}/*.backup ${DOC}/*.ilg ${DOC}/*.lof ${DOC}/*.lot
+ @rm -f ${DOC}/*.cdx ${DOC}/*.cnd ${DOC}/*.ddx ${DOC}/*.ddn ${DOC}/*.fdx ${DOC}/*.fnd ${DOC}/*.ind ${DOC}/*.sdx ${DOC}/*.snd
+ @rm -f ${DOC}/*.dnd ${DOC}/*.old ${DOC}/*.out
+ @rm -f ${DOC}/WARNINGS
+ @rm -f ${DOC}i-*.tex
+
+
+clean:
+ @rm -f 1 2 3 *.tex~
+ @rm -f *.png *.gif *.jpg *.eps
+ @rm -f *.pdf *.aux *.cp *.fn *.ky *.log *.pg
+ @rm -f *.html *.backup *.ps *.dvi *.ilg *.lof *.lot
+ @rm -f *.cdx *.cnd *.ddx *.ddn *.fdx *.fnd *.ind *.sdx *.snd
+ @rm -f *.dnd imagename_translations
+ @rm -f *.old WARNINGS *.out *.toc *.idx
+ @rm -f ${DOC}i-*.tex
+ @rm -rf ${DOC}
+
+
+distclean: clean
+ @rm -f images.pl labels.pl internals.pl
+ @rm -f Makefile version.tex
--- /dev/null
+#!/usr/bin/perl -w
+# Finds potential problems in tex files, and issues warnings to the console
+# about what it finds. Takes a list of files as its only arguments,
+# and does checks on all the files listed. The assumption is that these are
+# valid (or close to valid) LaTeX files. It follows \include statements
+# recursively to pick up any included tex files.
+#
+#
+#
+# Currently the following checks are made:
+#
+# -- Multiple hyphens not inside a verbatim environment (or \verb). These
+# should be placed inside a \verb{} contruct so they will not be converted
+# to single hyphen by latex and latex2html.
+
+
+# Original creation 3-8-05 by Karl Cunningham karlc -at- keckec -dot- com
+#
+#
+
+use strict;
+
+# The following builds the test string to identify and change multiple
+# hyphens in the tex files. Several constructs are identified but only
+# multiple hyphens are changed; the others are fed to the output
+# unchanged.
+my $b = '\\\\begin\\*?\\s*\\{\\s*'; # \begin{
+my $e = '\\\\end\\*?\\s*\\{\\s*'; # \end{
+my $c = '\\s*\\}'; # closing curly brace
+
+# This captures entire verbatim environments. These are passed to the output
+# file unchanged.
+my $verbatimenv = $b . "verbatim" . $c . ".*?" . $e . "verbatim" . $c;
+
+# This captures \verb{..{ constructs. They are passed to the output unchanged.
+my $verb = '\\\\verb\\*?(.).*?\\1';
+
+# This captures multiple hyphens with a leading and trailing space. These are not changed.
+my $hyphsp = '\\s\\-{2,}\\s';
+
+# This identifies other multiple hyphens.
+my $hyphens = '\\-{2,}';
+
+# This identifies \hyperpage{..} commands, which should be ignored.
+my $hyperpage = '\\\\hyperpage\\*?\\{.*?\\}';
+
+# This builds the actual test string from the above strings.
+#my $teststr = "$verbatimenv|$verb|$tocentry|$hyphens";
+my $teststr = "$verbatimenv|$verb|$hyphsp|$hyperpage|$hyphens";
+
+
+sub get_includes {
+ # Get a list of include files from the top-level tex file. The first
+ # argument is a pointer to the list of files found. The rest of the
+ # arguments is a list of filenames to check for includes.
+ my $files = shift;
+ my ($fileline,$includefile,$includes);
+
+ while (my $filename = shift) {
+ # Get a list of all the html files in the directory.
+ open my $if,"<$filename" or die "Cannot open input file $filename\n";
+ $fileline = 0;
+ $includes = 0;
+ while (<$if>) {
+ chomp;
+ $fileline++;
+ # If a file is found in an include, process it.
+ if (($includefile) = /\\include\s*\{(.*?)\}/) {
+ $includes++;
+ # Append .tex to the filename
+ $includefile .= '.tex';
+
+ # If the include file has already been processed, issue a warning
+ # and don't do it again.
+ my $found = 0;
+ foreach (@$files) {
+ if ($_ eq $includefile) {
+ $found = 1;
+ last;
+ }
+ }
+ if ($found) {
+ print "$includefile found at line $fileline in $filename was previously included\n";
+ } else {
+ # The file has not been previously found. Save it and
+ # recursively process it.
+ push (@$files,$includefile);
+ get_includes($files,$includefile);
+ }
+ }
+ }
+ close IF;
+ }
+}
+
+
+sub check_hyphens {
+ my (@files) = @_;
+ my ($filedata,$this,$linecnt,$before);
+
+ # Build the test string to check for the various environments.
+ # We only do the conversion if the multiple hyphens are outside of a
+ # verbatim environment (either \begin{verbatim}...\end{verbatim} or
+ # \verb{--}). Capture those environments and pass them to the output
+ # unchanged.
+
+ foreach my $file (@files) {
+ # Open the file and load the whole thing into $filedata. A bit wasteful but
+ # easier to deal with, and we don't have a problem with speed here.
+ $filedata = "";
+ open IF,"<$file" or die "Cannot open input file $file";
+ while (<IF>) {
+ $filedata .= $_;
+ }
+ close IF;
+
+ # Set up to process the file data.
+ $linecnt = 1;
+
+ # Go through the file data from beginning to end. For each match, save what
+ # came before it and what matched. $filedata now becomes only what came
+ # after the match.
+ # Chech the match to see if it starts with a multiple-hyphen. If so
+ # warn the user. Keep track of line numbers so they can be output
+ # with the warning message.
+ while ($filedata =~ /$teststr/os) {
+ $this = $&;
+ $before = $`;
+ $filedata = $';
+ $linecnt += $before =~ tr/\n/\n/;
+
+ # Check if the multiple hyphen is present outside of one of the
+ # acceptable constructs.
+ if ($this =~ /^\-+/) {
+ print "Possible unwanted multiple hyphen found in line ",
+ "$linecnt of file $file\n";
+ }
+ $linecnt += $this =~ tr/\n/\n/;
+ }
+ }
+}
+##################################################################
+# MAIN ####
+##################################################################
+
+my (@includes,$cnt);
+
+# Examine the file pointed to by the first argument to get a list of
+# includes to test.
+get_includes(\@includes,@ARGV);
+
+check_hyphens(@includes);
--- /dev/null
+#
+# Avoid that @VERSION@ and @DATE@ are changed by configure
+# This file is sourced by update_version
+#
+echo "s%@VERSION@%${VERSION}%g" >${out}
+echo "s%@DATE@%${DATE}%g" >>${out}
--- /dev/null
+%%
+%%
+% TODO: maybe merge all this FAQ in with the appropriate section?
+% TODO: and use detailed indexing to help reader
+
+\chapter{Bacula Frequently Asked Questions}
+\label{FaqChapter}
+\index[general]{Questions!Bacula Frequently Asked }
+\index[general]{Bacula Frequently Asked Questions }
+
+These are questions that have been submitted over time by the
+Bacula users. The following
+FAQ is very useful, but it is not always up to date
+with newer information, so after reading it, if you don't find what you
+want, you might try the Bacula wiki maintained by Frank Sweetser, which
+contains more than just a FAQ:
+\elink{http://wiki.bacula.org}{\url{http://wiki.bacula.org}}
+or go directly to the FAQ at:
+\elink{http://wiki.bacula.org/doku.php?id=faq}
+{\url{http://wiki.bacula.org/doku.php?id=faq}}.
+
+Please also see
+\ilink{the bugs section}{BugsChapter} of this document for a list
+of known bugs and solutions.
+
+\begin{description}
+\label{what}
+\section{What is Bacula?}
+\item [What is {\bf Bacula}? ]
+ \index[general]{What is Bacula? }
+ {\bf Bacula} is a network backup and restore program.
+
+\section{Does Bacula support Windows?}
+\item [Does Bacula support Windows?]
+\index[general]{Does Bacula support Windows? }
+ Yes, Bacula compiles and runs on Windows machines (Win98, WinMe, WinXP,
+ WinNT, Win2003, and Win2000). We provide a binary version of the Client
+ (bacula-fd), but have not tested the Director nor the Storage daemon.
+ Note, Win95 is no longer supported because it doesn't have the
+ GetFileAttributesExA API call.
+
+
+\label{lang}
+\section{What language is Bacula written in?}
+\item [What language is Bacula written in?]
+\index[general]{What language is Bacula written in? }
+ It is written in C++, but it is mostly C code using only a limited set of
+ the C++ extensions over C. Thus Bacula is completely compiled using the
+ C++ compiler. There are several modules, including the Win32 interface, that
+ are written using the object oriented C++ features. Over time, we are slowly
+ adding a larger subset of C++.
+
+\label{run}
+\section{On what machines does Bacula run?}
+\item [On what machines does Bacula run? ]
+ \index[general]{On what machines does Bacula run? }
+ {\bf Bacula} builds and executes on Red Hat Linux (versions RH7.1-RHEL
+ 4.0, Fedora, SuSE, Gentoo, Debian, Mandriva, ...), FreeBSD, Solaris,
+ Alpha, SGI (client), NetBSD, OpenBSD, Mac OS X (client), and Win32.
+
+ Bacula has been my only backup tool for over seven years backing up 8
+ machines nightly (6 Linux boxes running SuSE, previously
+ Red Hat and Fedora, a WinXP machine, and a WinNT machine).
+
+
+\label{stable}
+\section{Is Bacula Stable?}
+\item [Is Bacula Stable? ]
+\index[general]{Is Bacula Stable? }
+ Yes, it is remarkably stable, but remember, there are still a lot of
+ unimplemented or partially implemented features. With a program of this
+ size (150,000+ lines of C++ code not including the SQL programs) there
+ are bound to be bugs. The current test environment (a twisted pair
+ local network and a HP DLT backup tape) is not exactly ideal, so
+ additional testing on other sites is necessary. The File daemon has
+ never crashed -- running months at a time with no intervention. The
+ Storage daemon is remarkably stable with most of the problems arising
+ during labeling or switching tapes. Storage daemon crashes are rare
+ but running multiple drives and simultaneous jobs sometimes (rarely)
+ problems.
+ The Director, given the multitude of functions it fulfills is also
+ relatively stable. In a production environment, it rarely if ever
+ crashes. Of the three daemons, the Director is the most prone to having
+ problems. Still, it frequently runs several months with no problems.
+
+ There are a number of reasons for this stability.
+
+ \begin{enumerate}
+ \item The program is constantly checking the chain of allocated
+ memory buffers to ensure that no overruns have occurred. \\
+ \item All memory leaks (orphaned buffers) are reported each time the
+ program terminates.\\
+ \item Any signal (segmentation fault, ...) generates a
+ traceback that is emailed to the developer. This permits quick
+ resolution of bugs even if they only show up rarely in a production
+ system.\\
+ \item There is a reasonably comprehensive set of regression tests
+ that avoids re-creating the most common errors in new versions of
+ Bacula.
+ \end{enumerate}
+
+\label{AuthorizationErrors}
+\section{I'm Getting Authorization Errors. What is Going On? }
+\item [I'm Getting Authorization Errors. What is Going On? ]
+\index[general]{Authorization Errors}
+\index[general]{Concurrent Jobs}
+ For security reasons, Bacula requires that both the File daemon and the
+ Storage daemon know the name of the Director as well as its password. As a
+ consequence, if you change the Director's name or password, you must make
+ the corresponding change in the Storage daemon's and in the File daemon's
+ configuration files.
+
+ During the authorization process, the Storage daemon and File daemon
+ also require that the Director authenticates itself, so both ends
+ require the other to have the correct name and password.
+
+ If you have edited the conf files and modified any name or any password,
+ and you are getting authentication errors, then your best bet is to go
+ back to the original conf files generated by the Bacula installation
+ process. Make only the absolutely necessary modifications to these
+ files -- e.g. add the correct email address. Then follow the
+ instructions in the \ilink{ Running Bacula}{TutorialChapter} chapter of
+ this manual. You will run a backup to disk and a restore. Only when
+ that works, should you begin customization of the conf files.
+
+ Another reason that you can get authentication errors is if you are
+ running Multiple Concurrent Jobs in the Director, but you have not set
+ them in the File daemon or the Storage daemon. Once you reach their
+ limit, they will reject the connection producing authentication (or
+ connection) errors.
+
+ If you are having problems connecting to a Windows machine that
+ previously worked, you might try restarting the Bacula service since
+ Windows frequently encounters networking connection problems.
+
+ Some users report that authentication fails if there is not a proper
+ reverse DNS lookup entry for the machine. This seems to be a
+ requirement of gethostbyname(), which is what Bacula uses to translate
+ names into IP addresses. If you cannot add a reverse DNS entry, or you
+ don't know how to do so, you can avoid the problem by specifying an IP
+ address rather than a machine name in the appropriate Bacula conf file.
+
+ Here is a picture that indicates what names/passwords in which
+ files/Resources must match up:
+
+ \includegraphics{./Conf-Diagram.eps}
+
+ In the left column, you will find the Director, Storage, and Client
+ resources, with their names and passwords -- these are all in {\bf
+ bacula-dir.conf}. The right column is where the corresponding values
+ should be found in the Console, Storage daemon (SD), and File daemon (FD)
+ configuration files.
+
+ Another thing to check is to ensure that the Bacula component you are
+ trying to access has {\bf Maximum Concurrent Jobs} set large enough to
+ handle each of the Jobs and the Console that want to connect
+ simultaneously. Once the maximum connections has been reached, each
+ Bacula component will reject all new connections.
+
+ Finally, make sure you have no {\bf hosts.allow} or {\bf hosts.deny}
+ file that is not permitting access to the site trying to connect.
+
+\label{AccessProblems}
+\section{Bacula Runs Fine but Cannot Access a Client on a Different Machine.
+ Why? }
+\item [Bacula Runs Fine but Cannot Access a Client on a Different Machine.
+ Why? ]
+\index[general]{Cannot Access a Client}
+ There are several reasons why Bacula could not contact a client on a
+ different machine. They are:
+
+\begin{itemize}
+\item It is a Windows Client, and the client died because of an improper
+ configuration file. Check that the Bacula icon is in the system tray and the
+ the menu items work. If the client has died, the icon will disappear only
+ when you move the mouse over the icon.
+\item The Client address or port is incorrect or not resolved by DNS. See if
+ you can ping the client machine using the same address as in the Client
+ record.
+\item You have a firewall, and it is blocking traffic on port 9102 between
+ the Director's machine and the Client's machine (or on port 9103 between the
+ Client and the Storage daemon machines).
+\item Your password or names are not correct in both the Director and the
+ Client machine. Try configuring everything identical to how you run the
+ client on the same machine as the Director, but just change the Address. If
+ that works, make the other changes one step at a time until it works.
+\item You may also be having problems between your File daemon and your
+ Storage daemon. The name you use in the Storage resource of your
+ Director's conf file must be known (resolvable) by the File daemon,
+ because it is passed symbolically to the File daemon, which then
+ resolves it to get an IP address used to contact the Storage daemon.
+\item You may have a {\bf hosts.allow} or {\bf hosts.deny} file that is
+ not permitting access.
+\end{itemize}
+
+\label{startover}
+\section{My Catalog is Full of Test Runs, How Can I Start Over?}
+\item [My Catalog is Full of Test Runs, How Can I Start Over? ]
+ \index[general]{My Catalog is Full of Test Runs, How Can I Start Over? }
+ If you are using MySQL do the following:
+
+\footnotesize
+\begin{verbatim}
+ cd <bacula-source>/src/cats
+ ./drop_mysql_tables
+ ./make_mysql_tables
+
+\end{verbatim}
+\normalsize
+
+If you are using SQLite, do the following:
+
+\footnotesize
+\begin{verbatim}
+ Delete bacula.db from your working directory.
+ cd <bacula-source>/src/cats
+ ./drop_sqlite_tables
+ ./make_sqlite_tables
+
+\end{verbatim}
+\normalsize
+
+Then write an EOF on each tape you used with {\bf Bacula} using:
+
+\footnotesize
+\begin{verbatim}
+mt -f /dev/st0 rewind
+mt -f /dev/st0 weof
+\end{verbatim}
+\normalsize
+
+where you need to adjust the device name for your system.
+
+\label{restorehang}
+\section{I Run a Restore Job and Bacula Hangs. What do I do?}
+\item [I Run a Restore Job and Bacula Hangs. What do I do?]
+\index[general]{I Run a Restore Job and Bacula Hangs. What do I do? }
+ On Bacula version 1.25 and prior, it expects you to have the correct
+ tape mounted prior to a restore. On Bacula version 1.26 and higher, it
+ will ask you for the tape, and if the wrong one is mounted, it will
+ inform you.
+
+ If you have previously done an {\bf unmount} command, all Storage daemon
+ sessions (jobs) will be completely blocked from using the drive
+ unmounted, so be sure to do a {\bf mount} after your unmount. If in
+ doubt, do a second {\bf mount}, it won't cause any harm.
+
+\label{windowstart}
+\section{I Cannot Get My Windows Client to Start Automatically? }
+\item [I Cannot Get My Windows Client to Start Automatically? ]
+\index[general]{Windows Auto Start}
+ You are probably having one of two problems: either the Client is dying
+ due to an incorrect configuration file, or you didn't do the
+ Installation commands necessary to install it as a Windows Service.
+
+ For the first problem, see the next FAQ question. For the second
+ problem, please review the \ilink{ Windows Installation
+ instructions}{Win32Chapter} in this manual.
+
+\label{windowsdie}
+\section{My Windows Client Immediately Dies When I Start It}
+\item [My Windows Client Immediately Dies When I Start It]
+\index[general]{Windows Client Dies}
+The most common problem is either that the configuration file is not where
+it expects it to be, or that there is an error in the configuration file.
+You must have the configuration file in {\bf
+c:\textbackslash{}bacula\textbackslash{}bin\textbackslash{}bacula-fd.conf}.
+
+To {\bf see} what is going on when the File daemon starts on Windows, do the
+following:
+
+\footnotesize
+\begin{verbatim}
+ Start a DOS shell Window.
+ cd c:\bacula\bin
+ bacula-fd -d100 -c c:\bacula\bin\bacula-fd.conf
+
+\end{verbatim}
+\normalsize
+
+This will cause the FD to write a file {\bf bacula.trace} in the current
+directory, which you can examine and thereby determine the problem.
+
+\label{scroll}
+\item [When I Start the Console, the Error Messages Fly By. How can I see
+ them? ]
+\index[general]{Error Messages}
+ Either use a shell window with a scroll bar, or use the gnome-console.
+ In any case, you probably should be logging all output to a file, and
+ then you can simply view the file using an editor or the {\bf less}
+ program. To log all output, I have the following in my Director's
+ Message resource definition:
+
+\footnotesize
+\begin{verbatim}
+ append = "/home/kern/bacula/bin/log" = all, !skipped
+
+\end{verbatim}
+\normalsize
+
+Obviously you will want to change the filename to be appropriate for your
+system.
+
+\label{nobackup}
+\section{My backups are not working on my Windows
+ Client. What should I do?}
+\item [I didn't realize that the backups were not working on my Windows
+ Client. What should I do? ]
+\index[general]{Backups Failing}
+You should be sending yourself an email message for each job. This will avoid
+the possibility of not knowing about a failed backup. To do so put something
+like:
+
+\footnotesize
+\begin{verbatim}
+ Mail = yourname@yourdomain = all, !skipped
+
+\end{verbatim}
+\normalsize
+
+in your Director's message resource. You should then receive one email for
+each Job that ran. When you are comfortable with what is going on (it took
+me 9 months), you might change that to:
+
+\footnotesize
+\begin{verbatim}
+ MailOnError = yourname@yourdomain = all, !skipped
+
+\end{verbatim}
+\normalsize
+
+then you only get email messages when a Job errors as is the case for your
+Windows machine.
+
+You should also be logging the Director's messages, please see the previous
+FAQ for how to do so.
+
+\label{sched}
+\section{All my Jobs are scheduled for the same time. Will this cause
+ problems?}
+\item [All my Jobs are scheduled for the same time. Will this cause
+ problems? ]
+\index[general]{Schedule problems}
+ No, not at all. Bacula will schedule all the Jobs at the same time, but
+ will run them one after another unless you have increased the number of
+ simultaneous jobs in the configuration files for the Director, the File
+ daemon, and the Storage daemon. The appropriate configuration record is
+ {\bf Maximum Concurrent Jobs = nn}. At the current time, we recommend
+ that you leave this set to {\bf 1} for the Director.
+
+\label{disk}
+\section{Can Bacula Backup My System To Files instead of Tape?}
+\item [Can Bacula Backup My System To Files instead of Tape? ]
+\index[general]{Backup to Disk}
+ Yes, in principle, Bacula can backup to any storage medium as long as
+ you have correctly defined that medium in the Storage daemon's Device
+ resource. For an example of how to backup to files, please see the
+ \ilink{Pruning Example}{PruningExample} in the Recycling chapter of this
+ manual. Also, there is a whole chapter devoted to \ilink{Basic Volume
+ Management}{DiskChapter}. This chapter was originally written to
+ explain how to write to disk, but was expanded to include volume
+ management. It is, however, still quite a good chapter to read.
+
+\label{testbackup}
+\section{Can I use a dummy device to test the backup?}
+ Yes, to have a {\sl Virtual} device which just consumes data, you can use a
+ FIFO device (see \ilink{Stored configuration}{SetupFifo}).
+ It's useful to test a backup.
+\footnotesize
+\begin{verbatim}
+Device {
+ Name = NULL
+ Media Type = NULL
+ Device Type = Fifo
+ Archive Device = /dev/null
+ LabelMedia = yes
+ Random Access = no
+ AutomaticMount = no
+ RemovableMedia = no
+ MaximumOpenWait = 60
+ AlwaysOpen = no
+}
+\end{verbatim}
+\normalsize
+
+\label{bigfiles}
+\section{Can Bacula Backup and Restore Files Bigger than 2 Gigabytes?}
+\item [Can Bacula Backup and Restore Files Bigger than 2 Gigabytes?]
+\index[general]{Large file support}
+If your operating system permits it, and you are running Bacula version
+1.26 or later, the answer is yes. To the best of our knowledge all client
+system supported by Bacula can handle files bigger 2 Gigabytes.
+
+\label{cancel}
+\section{I want to stop a job.}
+%% Is there a better way than "./bacula stop" to stop it?}
+\item [I Started A Job then Decided I Really Did Not Want to Run It. Is
+ there a better way than {\bf ./bacula stop} to stop it?]
+\index[general]{Cancelling jobs}
+ Yes, you normally should use the Console command {\bf cancel} to cancel
+ a Job that is either scheduled or running. If the Job is scheduled, it
+ will be marked for cancellation and will be canceled when it is
+ scheduled to start. If it is running, it will normally terminate after
+ a few minutes. If the Job is waiting on a tape mount, you may need to
+ do a {\bf mount} command before it will be canceled.
+
+\label{trademark}
+\section{Why have You Trademarked the Name Bacula?}
+\item [Why have You Trademarked the Name
+ Bacula\raisebox{.6ex}{{\footnotesize \textsuperscript{\textregistered}}}?]
+\index[general]{Bacula Trademark}
+We have trademarked the name Bacula to ensure that all media written by any
+program named Bacula will always be compatible. Anyone may use the name
+Bacula, even in a derivative product as long as it remains totally compatible
+in all respects with the program defined here.
+
+\label{docversion}
+\section{Why is the Online Document for Version 1.39 but the Released Version is 1.38?}
+\item [Why is the Online Document for Version 1.39 of Bacula when the
+ Current Version is 1.38?]
+\index[general]{Multiple manuals}
+As Bacula is being developed, the document is also being enhanced, more
+often than not it has clarifications of existing features that can be very
+useful to our users, so we publish the very latest document. Fortunately
+it is rare that there are confusions with new features.
+
+If you want to read a document that pertains only to a specific version,
+please use the one distributed in the source code. The web site also has
+online versions of both the released manual and the current development
+manual.
+
+\label{sure}
+\section{Does Bacula really save and restore all files?}
+\item [How Can I Be Sure that Bacula Really Saves and Restores All Files? ]
+\index[general]{Checking Restores}
+ It is really quite simple, but took me a while to figure
+ out how to "prove" it. First make a Bacula Rescue disk, see the
+ \ilink{Disaster Recovery Using Bacula}{RescueChapter} chapter
+ of this manual.
+ Second, you run a full backup of all your files on all partitions.
+ Third, you run an Verify InitCatalog Job on the same FileSet, which
+ effectively makes a record of all the files on your system. Fourth, you
+ run a Verify Catalog job and assure yourself that nothing has changed
+ (well, between an InitCatalog and Catalog one doesn't expect anything).
+ Then do the unthinkable, write zeros on your MBR (master boot record)
+ wiping out your hard disk. Now, restore your whole system using your
+ Bacula Rescue disk and the Full backup you made, and finally re-run the
+ Verify Catalog job. You will see that with the exception of the
+ directory modification and access dates and the files changed during the
+ boot, your system is identical to what it was before you wiped your hard
+ disk.
+ Alternatively you could do the wiping and restoring to another computer
+ of the same type.
+
+\label{upgrade}
+\section{I want an Incremental but Bacula runs it as a Full backup. Why?}
+\item [I did a Full backup last week, but now in running an Incremental,
+ Bacula says it did not find a FULL backup, so it did a FULL backup. Why?]
+\index[general]{FULL backup not found}
+ Before doing an Incremental or a Differential
+ backup, Bacula checks to see if there was a prior Full backup of the
+ same Job that terminated successfully. If so, it uses the date that
+ full backup started as the time for comparing if files have changed. If
+ Bacula does not find a successful full backup, it proceeds to do one.
+ Perhaps you canceled the full backup, or it terminated in error. In
+ such cases, the full backup will not be successful. You can check by
+ entering {\bf list jobs} and look to see if there is a prior Job with
+ the same Name that has Level F and JobStatus T (normal termination).
+
+ Another reason why Bacula may not find a suitable Full backup is that
+ every time you change the FileSet, Bacula will require a new Full
+ backup. This is necessary to ensure that all files are properly backed
+ up in the case where you have added more files to the FileSet.
+ Beginning with version 1.31, the FileSets are also dated when they are
+ created, and this date is displayed with the name when you are listing
+ or selecting a FileSet. For more on backup levels see below.
+
+ See also {\bf Ignore FileSet Changes} in the
+ \ilink{FileSet Resource definition}{FileSetResource} in the Director
+ chapter of this document.
+
+\label{filenamelengths}
+\section{Do you really handle unlimited path lengths?}
+\item [How Can You Claim to Handle Unlimited Path and Filename Lengths
+ when All Other Programs Have Fixed Limits?]
+\index[general]{Path and Filename Lengths}
+ Most of those other programs have been around for a long time, in fact
+ since the beginning of Unix, which means that they were designed for
+ rather small fixed length path and filename lengths. Over the years,
+ these restrictions have been relaxed allowing longer names. Bacula on
+ the other hand was designed in 2000, and so from the start, Path and
+ Filenames have been kept in buffers that start at 256 bytes in length,
+ but can grow as needed to handle any length. Most of the work is
+ carried out by lower level routines making the coding rather easy.
+
+ Note that due to limitations Win32 path and filenames cannot exceed
+ 260 characters. By using Win32 Unicode functions, we will remove this
+ restriction in later versions of Bacula.
+
+\label{unique}
+\section{What Is the Really Unique Feature of Bacula?}
+\item [What Is the Really Unique Feature of Bacula?]
+\index[general]{Unique Feature of Bacula}
+ Well, it is hard to come up with unique features when backup programs
+ for Unix machines have been around since the 1960s. That said, I
+ believe that Bacula is the first and only program to use a standard SQL
+ interface to catalog its database. Although this adds a bit of
+ complexity and possibly overhead, it provides an amazingly rich set of
+ features that are easy to program and enhance. The current code has
+ barely scratched the surface in this regard (version 1.38).
+
+ The second feature, which gives a lot of power and flexibility to Bacula
+ is the Bootstrap record definition.
+
+ The third unique feature, which is currently (1.30) unimplemented, and
+ thus can be called vaporware :-), is Base level saves. When
+ implemented, this will enormously reduce tape usage.
+
+\label{sequence}
+\section{How can I force one job to run after another?}
+\item [If I Run Multiple Simultaneous Jobs, How Can I Force One
+ Particular Job to Run After Another Job? ]
+\index[general]{Multiple Simultaneous Jobs}
+Yes, you can set Priorities on your jobs so that they run in the order you
+specify. Please see:
+\ilink{the Priority record}{Priority} in the Job resource.
+
+\label{nomail}
+\section{I Am Not Getting Email Notification, What Can I Do? }
+\item [I Am Not Getting Email Notification, What Can I Do? ]
+\index[general]{No Email Notification}
+ The most common problem is that you have not specified a fully qualified
+ email address and your bsmtp server is rejecting the mail. The next
+ most common problem is that your bsmtp server doesn't like the syntax on
+ the From part of the message. For more details on this and other
+ problems, please see the \ilink{ Getting Email Notification to
+ Work}{email} section of the Tips chapter of this manual. The section
+ \ilink{ Getting Notified of Job Completion}{notification} of the Tips
+ chapter may also be useful. For more information on the {\bf bsmtp}
+ mail program, please see \ilink{bsmtp in the Volume Utility Tools
+ chapter}{bsmtp} of this manual.
+
+\label{periods}
+\section{My retention periods don't work}
+\item [I Change Recycling, Retention Periods, or File Sizes in my Pool
+ Resource and they Still Don't Work.]
+\index[general]{Recycling}
+\index[general]{Retention Periods}
+\index[general]{Pool changes}
+ The different variables associated with a Pool are defined in the Pool
+ Resource, but are actually read by Bacula from the Catalog database. On
+ Bacula versions prior to 1.30, after changing your Pool Resource, you must
+ manually update the corresponding values in the Catalog by using the {\bf
+ update pool} command in the Console program. In Bacula version 1.30, Bacula
+ does this for you automatically every time it starts.
+
+ When Bacula creates a Media record (Volume), it uses many default values from
+ the Pool record. If you subsequently change the Pool record, the new values
+ will be used as a default for the next Volume that is created, but if you
+ want the new values to apply to existing Volumes, you must manually update
+ the Volume Catalog entry using the {\bf update volume} command in the Console
+ program.
+
+\label{CompressionNotWorking}
+\section{Why aren't my files compressed?}
+\item [I Have Configured Compression On, But None of My Files Are
+ Compressed. Why?]
+\index[general]{Compression}
+ There are two kinds of compression. One is tape compression. This is done by
+ the tape drive hardware, and you either enable or disable it with system
+ tools such as {\bf mt}. This compression works independently of Bacula,
+ and when it is enabled, you should not use the Bacula software
+ compression.
+
+ Bacula also has software compression code in the File daemons, which you
+ normally need to enable only when backing up to file Volumes. There are
+ two conditions necessary to enable the Bacula software compression.
+
+\begin{enumerate}
+\item You must have the zip development libraries loaded on your system
+ when building Bacula and Bacula must find this library, normally {\bf
+ /usr/lib/libz.a}. On Red Hat systems, this library is provided by the
+ {\bf zlib-devel} rpm.
+
+ If the library is found by Bacula during the {\bf ./configure} it will
+ be mentioned in the {\bf config.out} line by:
+
+\footnotesize
+\begin{verbatim}
+ ZLIB support: yes
+
+\end{verbatim}
+\normalsize
+
+\item You must add the {\bf compression=gzip} option on your Include
+ statement in the Director's configuration file.
+\end{enumerate}
+
+\label{NewTape}
+\item [Bacula is Asking for a New Tape After 2 GB of Data but My Tape
+ holds 33 GB. Why?]
+\index[general]{Tape capacity}
+There are several reasons why Bacula will request a new tape.
+
+\begin{itemize}
+\item There is an I/O error on the tape. Bacula prints an error message and
+ requests a new tape. Bacula does not attempt to continue writing after an
+ I/O error.
+\item Bacula encounters and end of medium on the tape. This is not always
+ distinguishable from an I/O error.
+\item You have specifically set some size limitation on the tape. For example
+ the {\bf Maximum Volume Bytes} or {\bf Maximum Volume Files} in the
+ Director's Pool resource, or {\bf Maximum Volume Size} in the Storage
+ daemon's Device resource.
+\end{itemize}
+
+\label{LevelChanging}
+\section{Incremental backups are not working}
+\item [Bacula is Not Doing the Right Thing When I Request an Incremental
+ Backup. Why?]
+\index[general]{Incremental backups}
+ As explained in one of the previous questions, Bacula will automatically
+ upgrade an Incremental or Differential job to a Full backup if it cannot
+ find a prior Full backup or a suitable Full backup. For the gory
+ details on how/when Bacula decides to upgrade levels please see the
+ \ilink{Level record}{Level} in the Director's configuration chapter of
+ this manual.
+
+ If after reading the above mentioned section, you believe that Bacula is not
+ correctly handling the level (Differential/Incremental), please send us the
+ following information for analysis:
+
+\begin{itemize}
+\item Your Director's configuration file.
+\item The output from {\bf list jobs} covering the period where you are
+ having the problem.
+\item The Job report output from the prior Full save (not critical).
+\item An {\bf llist jobid=nnn} where nnn is the JobId of the prior Full save.
+
+\item The Job report output from the save that is doing the wrong thing (not
+ critical).
+\item An {\bf llist jobid=nnn} where nnn is the JobId of the job that was not
+ correct.
+\item An explanation of what job went wrong and why you think it did.
+ \end{itemize}
+
+The above information can allow us to analyze what happened, without it,
+there is not much we can do.
+
+\label{WaitForever}
+\section{I am waiting forever for a backup of an offsite machine}
+\item [I am Backing Up an Offsite Machine with an Unreliable Connection.
+ The Director Waits Forever for the Client to Contact the SD. What Can I
+ Do?]
+\index[general]{Backing Up Offsite Machines}
+ Bacula was written on the assumption that it will have a good TCP/IP
+ connection between all the daemons. As a consequence, the current
+ Bacula doesn't deal with faulty connections very well. This situation
+ is slowly being corrected over time.
+
+ There are several things you can do to improve the situation.
+
+\begin{itemize}
+\item Upgrade to version 1.32 and use the new SDConnectTimeout record. For
+ example, set:
+
+\footnotesize
+\begin{verbatim}
+ SD Connect Timeout = 5 min
+
+\end{verbatim}
+\normalsize
+
+in the FileDaemon resource.
+\item Run these kinds of jobs after all other jobs.
+ \end{itemize}
+
+\label{sshHanging}
+\section{SSH hangs forever after starting Bacula}
+\item [When I ssh into a machine and start Bacula then attempt to exit,
+ ssh hangs forever.]
+\index[general]{ssh hangs}
+ This happens because Bacula leaves stdin, stdout, and stderr open for
+ debug purposes. To avoid it, the simplest thing to do is to redirect
+ the output of those files to {\bf /dev/null} or another file in your
+ startup script (the Red Hat autostart scripts do this automatically).
+ For example, you start the Director with:
+
+\footnotesize
+\begin{verbatim}
+ bacula-dir -c bacula-dir.conf ... 0>\&1 2>\&1 >/dev/null
+
+\end{verbatim}
+\normalsize
+
+and likewise for the other daemons.
+
+\label{RetentionPeriods}
+\section{I'm confused by retention periods}
+\item [I'm confused by the different Retention periods: File Retention,
+ Job Retention, Volume Retention. Why are there so many?]
+\index[general]{Retention Periods}
+ Yes, this certainly can be confusing. The basic reason for so many is
+ to allow flexibility. The File records take quite a lot of space in the
+ catalog, so they are typically records you want to remove rather
+ quickly. The Job records, take very little space, and they can be
+ useful even without the File records to see what Jobs actually ran and
+ when. One must understand that if the File records are removed from the
+ catalog, you cannot use the {\bf restore} command to restore an
+ individual file since Bacula no longer knows where it is. However, as
+ long as the Volume Retention period has not expired, the data will still
+ be on the tape, and can be recovered from the tape.
+
+ For example, I keep a 30 day retention period for my Files to keep my
+ catalog from getting too big, but I keep my tapes for a minimum of one
+ year, just in case.
+
+\label{MaxVolumeSize}
+\section{MaxVolumeSize is ignored}
+\item [Why Does Bacula Ignore the MaxVolumeSize Set in my Pool?]
+\index[general]{MaxVolumeSize}
+ The MaxVolumeSize that Bacula uses comes from the Media record, so most
+ likely you changed your Pool, which is used as the default for creating
+ Media records, {\bf after} you created your Volume. Check what is in
+ the Media record by doing:
+
+\footnotesize
+\begin{verbatim}
+llist Volume=xxx
+\end{verbatim}
+\normalsize
+
+If it doesn't have the right value, you can use:
+
+\footnotesize
+\begin{verbatim}
+update Volume=xxx
+\end{verbatim}
+\normalsize
+
+to change it.
+
+\label{ConnectionRefused}
+\section{I get a Connection refused when connecting to my Client}
+\item [In connecting to my Client, I get "ERR:Connection Refused. Packet
+ Size too big from File daemon:192.168.1.4:9102" Why?]
+\index[general]{ERR:Connection Refused}
+ This is typically a communications error resulting from one of the
+ following:
+
+
+\begin{itemize}
+\item Old versions of Bacula, usually a Win32 client, where two threads were
+ using the same I/O packet. Fixed in more recent versions. Please upgrade.
+\item Some other program such as an HP Printer using the same port (9102 in
+ this case).
+\end{itemize}
+
+If it is neither of the above, please submit a bug report at
+\elink{bugs.bacula.org}{http://bugs.bacula.org}.
+
+Another solution might be to run the daemon with the debug option by:
+
+\footnotesize
+\begin{verbatim}
+ Start a DOS shell Window.
+ cd c:\bacula\bin
+ bacula-fd -d100 -c c:\bacula\bin\bacula-fd.conf
+
+\end{verbatim}
+\normalsize
+
+This will cause the FD to write a file {\bf bacula.trace} in the current
+directory, which you can examine to determine the problem.
+
+\section{Long running jobs die with Pipe Error}
+\item [During long running jobs my File daemon dies with Pipe Error, or
+ some other communications error. Why?]
+\index[general]{Communications Errors}
+\index[general]{Pipe Errors}
+\index[general]{slow}
+\index[general]{Backups!slow}
+ There are a number of reasons why a connection might break.
+ Most often, it is a router between your two computers that times out
+ inactive lines (not respecting the keepalive feature that Bacula uses).
+ In that case, you can use the {\bf Heartbeat Interval} directive in
+ both the Storage daemon and the File daemon.
+
+ In at least one case, the problem has been a bad driver for a Win32
+ NVidia NForce 3 ethernet card with driver (4.4.2 17/05/2004).
+ In this case, a good driver is (4.8.2.0 06/04/2005). Moral of
+ the story, make sure you have the latest ethernet drivers
+ loaded, or use the following workaround as suggested by Thomas
+ Simmons for Win32 machines:
+
+ Browse to:
+ Start \gt{} Control Panel \gt{} Network Connections
+
+ Right click the connection for the nvidia adapter and select properties.
+ Under the General tab, click "Configure...". Under the Advanced tab set
+ "Checksum Offload" to disabled and click OK to save the change.
+
+ Lack of communications, or communications that get interrupted can
+ also be caused by Linux firewalls where you have a rule that throttles
+ connections or traffic. For example, if you have:
+
+\footnotesize
+\begin{verbatim}
+iptables -t filter -A INPUT -m limit --limit 3/second --limit-burst 3 -j DROP
+\end{verbatim}
+\normalsize
+
+ you will want to add the following rules {\bf before} the above rule:
+\footnotesize
+\begin{verbatim}
+iptables -t filter -A INPUT --dport 9101 -j ACCEPT
+iptables -t filter -A INPUT --dport 9102 -j ACCEPT
+iptables -t filter -A INPUT --dport 9103 -j ACCEPT
+\end{verbatim}
+\normalsize
+ This will ensure that any Bacula traffic will not get terminated because
+ of high usage rates.
+
+\section{How do I tell the Job which Volume to use?}
+\item[I can't figure out how to tell the job which volume to use]
+ \index[general]{What tape to mount}
+ This is an interesting statement. I now see that a number of people new to
+ Bacula have the same problem as you, probably from using programs like tar.
+
+ In fact, you do not tell Bacula what tapes to use. It is the inverse. Bacula
+ tells you want tapes it wants. You put tapes at its disposition and it
+ chooses.
+
+ Now, if you *really* want to be tricky and try to tell Bacula what to do, it
+ will be reasonable if for example you mount a valid tape that it can use on a
+ drive, it will most likely go ahead and use it. It also has a documented
+ algorithm for choosing tapes -- but you are asking for problems ...
+
+ So, the trick is to invert your concept of things and put Bacula in charge of
+ handling the tapes. Once you do that, you will be fine. If you want to
+ anticipate what it is going to do, you can generally figure it out correctly
+ and get what you want.
+
+ If you start with the idea that you are going to force or tell Bacula to use
+ particular tapes or you insist on trying to run in that kind of mode, you will
+ probably not be too happy.
+
+ I don't want to worry about what tape has what data. That is what Bacula is
+ designed for.
+
+ If you have an application where you *really* need to remove a tape each day
+ and insert a new one, it can be done the directives exist to accomplish that.
+ In such a case, one little "trick" to knowing what tape Bacula will want at
+ 2am while you are asleep is to run a tiny job at 4pm while you are still at
+ work that backs up say one directory, or even one file. You will quickly find
+ out what tape it wants, and you can mount it before you go home ...
+
+\label{Password generation}
+\section{Password generation}
+\item [How do I generate a password?]
+\index[general]{MaxVolumeSize}
+
+ Each daemon needs a password. This password occurs in the configuration
+ file for that daemon and in the bacula-dir.conf file. These passwords are
+ plain text. There is no special generation procedure. Most people just
+ use random text.
+
+ Passwords are never sent over the wire in plain text. They are always
+ encrypted.
+
+ Security surrounding these passwords is best left security to your
+ operating system. Passwords are not encrypted within Bacula
+ configuration files.
+
+\end{description}
+
\ No newline at end of file
--- /dev/null
+% TODO: maybe get rid of centering
+
+\chapter{GNU Free Documentation License}
+\index[general]{GNU Free Documentation License}
+\index[general]{License!GNU Free Documentation}
+
+\label{label_fdl}
+
+ \begin{center}
+
+ Version 1.2, November 2002
+
+
+ Copyright \copyright 2000,2001,2002 Free Software Foundation, Inc.
+
+ \bigskip
+
+ 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
+
+ \bigskip
+
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+\end{center}
+
+
+\begin{center}
+{\bf\large Preamble}
+\end{center}
+
+The purpose of this License is to make a manual, textbook, or other
+functional and useful document "free" in the sense of freedom: to
+assure everyone the effective freedom to copy and redistribute it,
+with or without modifying it, either commercially or noncommercially.
+Secondarily, this License preserves for the author and publisher a way
+to get credit for their work, while not being considered responsible
+for modifications made by others.
+
+This License is a kind of "copyleft", which means that derivative
+works of the document must themselves be free in the same sense. It
+complements the GNU General Public License, which is a copyleft
+license designed for free software.
+
+We have designed this License in order to use it for manuals for free
+software, because free software needs free documentation: a free
+program should come with manuals providing the same freedoms that the
+software does. But this License is not limited to software manuals;
+it can be used for any textual work, regardless of subject matter or
+whether it is published as a printed book. We recommend this License
+principally for works whose purpose is instruction or reference.
+
+
+\begin{center}
+{\Large\bf 1. APPLICABILITY AND DEFINITIONS}
+\end{center}
+
+This License applies to any manual or other work, in any medium, that
+contains a notice placed by the copyright holder saying it can be
+distributed under the terms of this License. Such a notice grants a
+world-wide, royalty-free license, unlimited in duration, to use that
+work under the conditions stated herein. The \textbf{"Document"}, below,
+refers to any such manual or work. Any member of the public is a
+licensee, and is addressed as \textbf{"you"}. You accept the license if you
+copy, modify or distribute the work in a way requiring permission
+under copyright law.
+
+A \textbf{"Modified Version"} of the Document means any work containing the
+Document or a portion of it, either copied verbatim, or with
+modifications and/or translated into another language.
+
+A \textbf{"Secondary Section"} is a named appendix or a front-matter section of
+the Document that deals exclusively with the relationship of the
+publishers or authors of the Document to the Document's overall subject
+(or to related matters) and contains nothing that could fall directly
+within that overall subject. (Thus, if the Document is in part a
+textbook of mathematics, a Secondary Section may not explain any
+mathematics.) The relationship could be a matter of historical
+connection with the subject or with related matters, or of legal,
+commercial, philosophical, ethical or political position regarding
+them.
+
+The \textbf{"Invariant Sections"} are certain Secondary Sections whose titles
+are designated, as being those of Invariant Sections, in the notice
+that says that the Document is released under this License. If a
+section does not fit the above definition of Secondary then it is not
+allowed to be designated as Invariant. The Document may contain zero
+Invariant Sections. If the Document does not identify any Invariant
+Sections then there are none.
+
+The \textbf{"Cover Texts"} are certain short passages of text that are listed,
+as Front-Cover Texts or Back-Cover Texts, in the notice that says that
+the Document is released under this License. A Front-Cover Text may
+be at most 5 words, and a Back-Cover Text may be at most 25 words.
+
+A \textbf{"Transparent"} copy of the Document means a machine-readable copy,
+represented in a format whose specification is available to the
+general public, that is suitable for revising the document
+straightforwardly with generic text editors or (for images composed of
+pixels) generic paint programs or (for drawings) some widely available
+drawing editor, and that is suitable for input to text formatters or
+for automatic translation to a variety of formats suitable for input
+to text formatters. A copy made in an otherwise Transparent file
+format whose markup, or absence of markup, has been arranged to thwart
+or discourage subsequent modification by readers is not Transparent.
+An image format is not Transparent if used for any substantial amount
+of text. A copy that is not "Transparent" is called \textbf{"Opaque"}.
+
+Examples of suitable formats for Transparent copies include plain
+ASCII without markup, Texinfo input format, LaTeX input format, SGML
+or XML using a publicly available DTD, and standard-conforming simple
+HTML, PostScript or PDF designed for human modification. Examples of
+transparent image formats include PNG, XCF and JPG. Opaque formats
+include proprietary formats that can be read and edited only by
+proprietary word processors, SGML or XML for which the DTD and/or
+processing tools are not generally available, and the
+machine-generated HTML, PostScript or PDF produced by some word
+processors for output purposes only.
+
+The \textbf{"Title Page"} means, for a printed book, the title page itself,
+plus such following pages as are needed to hold, legibly, the material
+this License requires to appear in the title page. For works in
+formats which do not have any title page as such, "Title Page" means
+the text near the most prominent appearance of the work's title,
+preceding the beginning of the body of the text.
+
+A section \textbf{"Entitled XYZ"} means a named subunit of the Document whose
+title either is precisely XYZ or contains XYZ in parentheses following
+text that translates XYZ in another language. (Here XYZ stands for a
+specific section name mentioned below, such as \textbf{"Acknowledgements"},
+\textbf{"Dedications"}, \textbf{"Endorsements"}, or \textbf{"History"}.)
+To \textbf{"Preserve the Title"}
+of such a section when you modify the Document means that it remains a
+section "Entitled XYZ" according to this definition.
+
+The Document may include Warranty Disclaimers next to the notice which
+states that this License applies to the Document. These Warranty
+Disclaimers are considered to be included by reference in this
+License, but only as regards disclaiming warranties: any other
+implication that these Warranty Disclaimers may have is void and has
+no effect on the meaning of this License.
+
+
+\begin{center}
+{\Large\bf 2. VERBATIM COPYING}
+\end{center}
+
+You may copy and distribute the Document in any medium, either
+commercially or noncommercially, provided that this License, the
+copyright notices, and the license notice saying this License applies
+to the Document are reproduced in all copies, and that you add no other
+conditions whatsoever to those of this License. You may not use
+technical measures to obstruct or control the reading or further
+copying of the copies you make or distribute. However, you may accept
+compensation in exchange for copies. If you distribute a large enough
+number of copies you must also follow the conditions in section 3.
+
+You may also lend copies, under the same conditions stated above, and
+you may publicly display copies.
+
+
+\begin{center}
+{\Large\bf 3. COPYING IN QUANTITY}
+\end{center}
+
+
+If you publish printed copies (or copies in media that commonly have
+printed covers) of the Document, numbering more than 100, and the
+Document's license notice requires Cover Texts, you must enclose the
+copies in covers that carry, clearly and legibly, all these Cover
+Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
+the back cover. Both covers must also clearly and legibly identify
+you as the publisher of these copies. The front cover must present
+the full title with all words of the title equally prominent and
+visible. You may add other material on the covers in addition.
+Copying with changes limited to the covers, as long as they preserve
+the title of the Document and satisfy these conditions, can be treated
+as verbatim copying in other respects.
+
+If the required texts for either cover are too voluminous to fit
+legibly, you should put the first ones listed (as many as fit
+reasonably) on the actual cover, and continue the rest onto adjacent
+pages.
+
+If you publish or distribute Opaque copies of the Document numbering
+more than 100, you must either include a machine-readable Transparent
+copy along with each Opaque copy, or state in or with each Opaque copy
+a computer-network location from which the general network-using
+public has access to download using public-standard network protocols
+a complete Transparent copy of the Document, free of added material.
+If you use the latter option, you must take reasonably prudent steps,
+when you begin distribution of Opaque copies in quantity, to ensure
+that this Transparent copy will remain thus accessible at the stated
+location until at least one year after the last time you distribute an
+Opaque copy (directly or through your agents or retailers) of that
+edition to the public.
+
+It is requested, but not required, that you contact the authors of the
+Document well before redistributing any large number of copies, to give
+them a chance to provide you with an updated version of the Document.
+
+
+\begin{center}
+{\Large\bf 4. MODIFICATIONS}
+\end{center}
+
+You may copy and distribute a Modified Version of the Document under
+the conditions of sections 2 and 3 above, provided that you release
+the Modified Version under precisely this License, with the Modified
+Version filling the role of the Document, thus licensing distribution
+and modification of the Modified Version to whoever possesses a copy
+of it. In addition, you must do these things in the Modified Version:
+
+\begin{itemize}
+\item[A.]
+ Use in the Title Page (and on the covers, if any) a title distinct
+ from that of the Document, and from those of previous versions
+ (which should, if there were any, be listed in the History section
+ of the Document). You may use the same title as a previous version
+ if the original publisher of that version gives permission.
+
+\item[B.]
+ List on the Title Page, as authors, one or more persons or entities
+ responsible for authorship of the modifications in the Modified
+ Version, together with at least five of the principal authors of the
+ Document (all of its principal authors, if it has fewer than five),
+ unless they release you from this requirement.
+
+\item[C.]
+ State on the Title page the name of the publisher of the
+ Modified Version, as the publisher.
+
+\item[D.]
+ Preserve all the copyright notices of the Document.
+
+\item[E.]
+ Add an appropriate copyright notice for your modifications
+ adjacent to the other copyright notices.
+
+\item[F.]
+ Include, immediately after the copyright notices, a license notice
+ giving the public permission to use the Modified Version under the
+ terms of this License, in the form shown in the Addendum below.
+
+\item[G.]
+ Preserve in that license notice the full lists of Invariant Sections
+ and required Cover Texts given in the Document's license notice.
+
+\item[H.]
+ Include an unaltered copy of this License.
+
+\item[I.]
+ Preserve the section Entitled "History", Preserve its Title, and add
+ to it an item stating at least the title, year, new authors, and
+ publisher of the Modified Version as given on the Title Page. If
+ there is no section Entitled "History" in the Document, create one
+ stating the title, year, authors, and publisher of the Document as
+ given on its Title Page, then add an item describing the Modified
+ Version as stated in the previous sentence.
+
+\item[J.]
+ Preserve the network location, if any, given in the Document for
+ public access to a Transparent copy of the Document, and likewise
+ the network locations given in the Document for previous versions
+ it was based on. These may be placed in the "History" section.
+ You may omit a network location for a work that was published at
+ least four years before the Document itself, or if the original
+ publisher of the version it refers to gives permission.
+
+\item[K.]
+ For any section Entitled "Acknowledgements" or "Dedications",
+ Preserve the Title of the section, and preserve in the section all
+ the substance and tone of each of the contributor acknowledgements
+ and/or dedications given therein.
+
+\item[L.]
+ Preserve all the Invariant Sections of the Document,
+ unaltered in their text and in their titles. Section numbers
+ or the equivalent are not considered part of the section titles.
+
+\item[M.]
+ Delete any section Entitled "Endorsements". Such a section
+ may not be included in the Modified Version.
+
+\item[N.]
+ Do not retitle any existing section to be Entitled "Endorsements"
+ or to conflict in title with any Invariant Section.
+
+\item[O.]
+ Preserve any Warranty Disclaimers.
+\end{itemize}
+
+If the Modified Version includes new front-matter sections or
+appendices that qualify as Secondary Sections and contain no material
+copied from the Document, you may at your option designate some or all
+of these sections as invariant. To do this, add their titles to the
+list of Invariant Sections in the Modified Version's license notice.
+These titles must be distinct from any other section titles.
+
+You may add a section Entitled "Endorsements", provided it contains
+nothing but endorsements of your Modified Version by various
+parties--for example, statements of peer review or that the text has
+been approved by an organization as the authoritative definition of a
+standard.
+
+You may add a passage of up to five words as a Front-Cover Text, and a
+passage of up to 25 words as a Back-Cover Text, to the end of the list
+of Cover Texts in the Modified Version. Only one passage of
+Front-Cover Text and one of Back-Cover Text may be added by (or
+through arrangements made by) any one entity. If the Document already
+includes a cover text for the same cover, previously added by you or
+by arrangement made by the same entity you are acting on behalf of,
+you may not add another; but you may replace the old one, on explicit
+permission from the previous publisher that added the old one.
+
+The author(s) and publisher(s) of the Document do not by this License
+give permission to use their names for publicity for or to assert or
+imply endorsement of any Modified Version.
+
+
+\begin{center}
+{\Large\bf 5. COMBINING DOCUMENTS}
+\end{center}
+
+
+You may combine the Document with other documents released under this
+License, under the terms defined in section 4 above for modified
+versions, provided that you include in the combination all of the
+Invariant Sections of all of the original documents, unmodified, and
+list them all as Invariant Sections of your combined work in its
+license notice, and that you preserve all their Warranty Disclaimers.
+
+The combined work need only contain one copy of this License, and
+multiple identical Invariant Sections may be replaced with a single
+copy. If there are multiple Invariant Sections with the same name but
+different contents, make the title of each such section unique by
+adding at the end of it, in parentheses, the name of the original
+author or publisher of that section if known, or else a unique number.
+Make the same adjustment to the section titles in the list of
+Invariant Sections in the license notice of the combined work.
+
+In the combination, you must combine any sections Entitled "History"
+in the various original documents, forming one section Entitled
+"History"; likewise combine any sections Entitled "Acknowledgements",
+and any sections Entitled "Dedications". You must delete all sections
+Entitled "Endorsements".
+
+\begin{center}
+{\Large\bf 6. COLLECTIONS OF DOCUMENTS}
+\end{center}
+
+You may make a collection consisting of the Document and other documents
+released under this License, and replace the individual copies of this
+License in the various documents with a single copy that is included in
+the collection, provided that you follow the rules of this License for
+verbatim copying of each of the documents in all other respects.
+
+You may extract a single document from such a collection, and distribute
+it individually under this License, provided you insert a copy of this
+License into the extracted document, and follow this License in all
+other respects regarding verbatim copying of that document.
+
+
+\begin{center}
+{\Large\bf 7. AGGREGATION WITH INDEPENDENT WORKS}
+\end{center}
+
+
+A compilation of the Document or its derivatives with other separate
+and independent documents or works, in or on a volume of a storage or
+distribution medium, is called an "aggregate" if the copyright
+resulting from the compilation is not used to limit the legal rights
+of the compilation's users beyond what the individual works permit.
+When the Document is included in an aggregate, this License does not
+apply to the other works in the aggregate which are not themselves
+derivative works of the Document.
+
+If the Cover Text requirement of section 3 is applicable to these
+copies of the Document, then if the Document is less than one half of
+the entire aggregate, the Document's Cover Texts may be placed on
+covers that bracket the Document within the aggregate, or the
+electronic equivalent of covers if the Document is in electronic form.
+Otherwise they must appear on printed covers that bracket the whole
+aggregate.
+
+
+\begin{center}
+{\Large\bf 8. TRANSLATION}
+\end{center}
+
+
+Translation is considered a kind of modification, so you may
+distribute translations of the Document under the terms of section 4.
+Replacing Invariant Sections with translations requires special
+permission from their copyright holders, but you may include
+translations of some or all Invariant Sections in addition to the
+original versions of these Invariant Sections. You may include a
+translation of this License, and all the license notices in the
+Document, and any Warranty Disclaimers, provided that you also include
+the original English version of this License and the original versions
+of those notices and disclaimers. In case of a disagreement between
+the translation and the original version of this License or a notice
+or disclaimer, the original version will prevail.
+
+If a section in the Document is Entitled "Acknowledgements",
+"Dedications", or "History", the requirement (section 4) to Preserve
+its Title (section 1) will typically require changing the actual
+title.
+
+
+\begin{center}
+{\Large\bf 9. TERMINATION}
+\end{center}
+
+
+You may not copy, modify, sublicense, or distribute the Document except
+as expressly provided for under this License. Any other attempt to
+copy, modify, sublicense or distribute the Document is void, and will
+automatically terminate your rights under this License. However,
+parties who have received copies, or rights, from you under this
+License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
+
+\begin{center}
+{\Large\bf 10. FUTURE REVISIONS OF THIS LICENSE}
+\end{center}
+
+
+The Free Software Foundation may publish new, revised versions
+of the GNU Free Documentation License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns. See
+http://www.gnu.org/copyleft/.
+
+Each version of the License is given a distinguishing version number.
+If the Document specifies that a particular numbered version of this
+License "or any later version" applies to it, you have the option of
+following the terms and conditions either of that specified version or
+of any later version that has been published (not as a draft) by the
+Free Software Foundation. If the Document does not specify a version
+number of this License, you may choose any version ever published (not
+as a draft) by the Free Software Foundation.
+
+
+\begin{center}
+{\Large\bf ADDENDUM: How to use this License for your documents}
+% TODO: this is too long for table of contents
+\end{center}
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and
+license notices just after the title page:
+
+\bigskip
+\begin{quote}
+ Copyright \copyright YEAR YOUR NAME.
+ Permission is granted to copy, distribute and/or modify this document
+ under the terms of the GNU Free Documentation License, Version 1.2
+ or any later version published by the Free Software Foundation;
+ with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+ A copy of the license is included in the section entitled "GNU
+ Free Documentation License".
+\end{quote}
+\bigskip
+
+If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
+replace the "with...Texts." line with this:
+
+\bigskip
+\begin{quote}
+ with the Invariant Sections being LIST THEIR TITLES, with the
+ Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
+\end{quote}
+\bigskip
+
+If you have Invariant Sections without Cover Texts, or some other
+combination of the three, merge those two alternatives to suit the
+situation.
+
+If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of
+free software license, such as the GNU General Public License,
+to permit their use in free software.
+
+%---------------------------------------------------------------------
--- /dev/null
+%%
+%%
+
+\chapter{Dealing with Firewalls}
+\label{FirewallsChapter}
+\index[general]{Dealing with Firewalls }
+\index[general]{Firewalls!Dealing with }
+
+If you have a firewall or a DMZ installed on your computer, you may experience
+difficulties contacting one or more of the Clients to back them up. This is
+especially true if you are trying to backup a Client across the Internet.
+
+\section{Technical Details}
+\index[general]{Technical Details }
+\index[general]{Details!Technical }
+
+If you are attempting to do this, the sequence of network events in Bacula to
+do a backup are the following:
+
+\footnotesize
+\begin{verbatim}
+Console -> DIR:9101
+DIR -> SD:9103
+DIR -> FD:9102
+FD -> SD:9103
+\end{verbatim}
+\normalsize
+
+Where hopefully it is obvious that DIR represents the Director, FD the File
+daemon or client, and SD the Storage daemon. The numbers that follow those
+names are the standard ports used by Bacula, and the -\gt{} represents the
+left side making a connection to the right side (i.e. the right side is the
+"server" or is listening on the specified port), and the left side is the
+"client" that initiates the conversation.
+
+Note, port 9103 serves both the Director and the File daemon, each having its
+own independent connection.
+
+If you are running {\bf iptables}, you might add something like:
+
+\footnotesize
+\begin{verbatim}
+-A FW-1-INPUT -m state --state NEW -m tcp -p tcp --dport 9101:9103 -j ACCEPT
+\end{verbatim}
+\normalsize
+
+on your server, and
+
+\footnotesize
+\begin{verbatim}
+-A FW-1-INPUT -m state --state NEW -m tcp -p tcp --dport 9102 -j ACCEPT
+\end{verbatim}
+\normalsize
+
+on your client. In both cases, I assume that the machine is allowed to
+initiate connections on any port. If not, you will need to allow outgoing
+connections on ports 9102 and 9103 on your server and 9103 on your client.
+Thanks to Raymond Norton for this tip.
+
+\section{A Concrete Example}
+\index[general]{Example!Concrete }
+\index[general]{Concrete Example }
+
+The following discussion was originally written by
+Jesse Guardiani because he has 'internal' and 'external' requiring the
+Director and the Client to use different IP addresses. His original
+solution was to define two different Storage resources in the Director's
+conf file each pointing to the same Storage daemon but with different
+IP addresses. In Bacula 1.38.x this no longer works, because Bacula makes
+a one-to-one association between a Storage daemon resource and a Device (such
+as an Autochanger). As a consequence, I have modified his original
+text to a method that I believe will work, but is as of yet untested
+(KES - July 2006).
+
+My bacula server is on the 192.168.1.0/24 network at IP address 192.168.1.52.
+For the sake of discussion we will refer to this network as the 'internal'
+network because it connects to the internet through a NAT'd firewall. We will
+call the network on the public (internet) side of the NAT'd firewall the
+'external' network. Also, for the sake of discussion we will call my bacula
+server:
+
+\footnotesize
+\begin{verbatim}
+ server.int.mydomain.tld
+\end{verbatim}
+\normalsize
+
+when a fully qualified domain name is required, or simply:
+
+\footnotesize
+\begin{verbatim}
+ server
+\end{verbatim}
+\normalsize
+
+if a hostname is adequate. We will call the various bacula daemons running on
+the server.int.mydomain.tld machine:
+
+\footnotesize
+\begin{verbatim}
+ server-fd
+ server-sd
+ server-dir
+\end{verbatim}
+\normalsize
+
+In addition, I have two clients that I want to back up with Bacula. The first
+client is on the internal network. Its fully qualified domain name is:
+
+\footnotesize
+\begin{verbatim}
+ private1.int.mydomain.tld
+\end{verbatim}
+\normalsize
+
+And its hostname is:
+
+\footnotesize
+\begin{verbatim}
+ private1
+\end{verbatim}
+\normalsize
+
+This machine is a client and therefore runs just one bacula daemon:
+
+\footnotesize
+\begin{verbatim}
+ private1-fd
+\end{verbatim}
+\normalsize
+
+The second client is on the external network. Its fully qualified domain name
+is:
+
+\footnotesize
+\begin{verbatim}
+ public1.mydomain.tld
+\end{verbatim}
+\normalsize
+
+And its hostname is:
+
+\footnotesize
+\begin{verbatim}
+ public1
+\end{verbatim}
+\normalsize
+
+This machine also runs just one bacula daemon:
+
+\footnotesize
+\begin{verbatim}
+ public1-fd
+\end{verbatim}
+\normalsize
+
+Finally, I have a NAT firewall/gateway with two network interfaces. The first
+interface is on the internal network and serves as a gateway to the internet
+for all the machines attached to the internal network (For example,
+server.int.mydomain.tld and private1.int.mydomain.tld). The second interface
+is on the external (internet) network. The external interface has been
+assigned the name:
+
+\footnotesize
+\begin{verbatim}
+ firewall.mydomain.tld
+\end{verbatim}
+\normalsize
+
+Remember:
+
+\footnotesize
+\begin{verbatim}
+ *.int.mydomain.tld = internal network
+ *.mydomain.tld = external network
+\end{verbatim}
+\normalsize
+
+\subsection{The Bacula Configuration Files for the Above}
+\index[general]{Above!Bacula Configuration Files for the }
+\index[general]{Bacula Configuration Files for the Above }
+
+server-sd manages a 4 tape AIT autoloader. All of my backups are written to
+server-sd. I have just *one* Device resource in my server-sd.conf file:
+
+\footnotesize
+\begin{verbatim}
+Autochanger {
+ Name = "autochanger1";\
+ Device = Drive0
+ Changer Device = /dev/ch0;
+ Changer Command = "/usr/local/sbin/chio-bacula %c %o %S %a";
+}
+Device {
+ Name = Drive0
+ DriveIndex = 0
+ Media Type = AIT-1;
+ Archive Device = /dev/nrsa1;
+ Label Media = yes;
+ AutoChanger = yes;
+ AutomaticMount = yes; # when device opened, read it
+ AlwaysOpen = yes;
+ Hardware End of Medium = No
+ Fast Forward Space File = No
+ BSF at EOM = yes
+}
+\end{verbatim}
+\normalsize
+
+(note, please see
+\ilink{the Tape Testing}{FreeBSDTapes} chapter of this manual
+for important FreeBSD information.) However, unlike previously, there
+is only one Storage definition in my server-dir.conf file:
+
+\footnotesize
+\begin{verbatim}
+Storage {
+ Name = "autochanger1" # Storage device for backing up
+ Address = Storage-server
+ SDPort = 9103
+ Password = "mysecretpassword"
+ Device = "autochanger1"
+ Media Type = AIT-1
+ Autochanger = yes
+}
+\end{verbatim}
+\normalsize
+
+Note that the Storage resource uses neither of the two addresses to
+the Storage daemon -- neither server.int.mydomain.tld nor
+firewall.mydomain.tld, but instead uses the address Storage-server.
+
+What is key is that in the internal net, Storage-server is resolved
+to server.int.mydomain.tld, either with an entry in /etc/hosts, or by
+creating and appropriate DNS entry, and on the external net (the Client
+machine), Storage-server is resolved to firewall.mydomain.tld.
+
+
+In addition to the above, I have two Client resources defined in
+server-dir.conf:
+
+\footnotesize
+\begin{verbatim}
+Client {
+ Name = private1-fd
+ Address = private1.int.mydomain.tld
+ FDPort = 9102
+ Catalog = MyCatalog
+ Password = "mysecretpassword" # password for FileDaemon
+}
+Client {
+ Name = public1-fd
+ Address = public1.mydomain.tld
+ FDPort = 9102
+ Catalog = MyCatalog
+ Password = "mysecretpassword" # password for FileDaemon
+}
+\end{verbatim}
+\normalsize
+
+And finally, to tie it all together, I have two Job resources defined in
+server-dir.conf:
+
+\footnotesize
+\begin{verbatim}
+Job {
+ Name = "Private1-Backup"
+ Type = Backup
+ Client = private1-fd
+ FileSet = "Private1"
+ Schedule = "WeeklyCycle"
+ Storage = "autochanger1-int"
+ Messages = Standard
+ Pool = "Weekly"
+ Write Bootstrap = "/var/db/bacula/Private1-Backup.bsr"
+ Priority = 12
+}
+Job {
+ Name = "Public1-Backup"
+ Type = Backup
+ Client = public1-fd
+ FileSet = "Public1"
+ Schedule = "WeeklyCycle"
+ Storage = "autochanger1-ext"
+ Messages = Standard
+ Pool = "Weekly"
+ Write Bootstrap = "/var/db/bacula/Public1-Backup.bsr"
+ Priority = 13
+}
+\end{verbatim}
+\normalsize
+
+It is important to notice that because the 'Private1-Backup' Job is intended
+to back up a machine on the internal network so it resolves Storage-server
+to contact the Storage daemon via the internal net.
+On the other hand, the 'Public1-Backup' Job is intended to
+back up a machine on the external network, so it resolves Storage-server
+to contact the Storage daemon via the external net.
+
+I have left the Pool, Catalog, Messages, FileSet, Schedule, and Director
+resources out of the above server-dir.conf examples because they are not
+pertinent to the discussion.
+
+\subsection{How Does It Work?}
+\index[general]{How Does It Work? }
+\index[general]{Work!How Does It }
+
+If I want to run a backup of private1.int.mydomain.tld and store that backup
+using server-sd then my understanding of the order of events is this:
+
+\begin{enumerate}
+\item I execute my Bacula 'console' command on server.int.mydomain.tld.
+\item console connects to server-dir.
+\item I tell console to 'run' backup Job 'Private1-Backup'.
+\item console relays this command to server-dir.
+\item server-dir connects to private1-fd at private1.int.mydomain.tld:9102
+\item server-dir tells private1-fd to start sending the files defined in the
+ 'Private1-Backup' Job's FileSet resource to the Storage resource
+ 'autochanger1', which we have defined in server-dir.conf as having the
+address:port of Storage-server, which is mapped by DNS to server.int.mydomain.tld.
+\item private1-fd connects to server.int.mydomain.tld:9103 and begins sending
+ files.
+ \end{enumerate}
+
+Alternatively, if I want to run a backup of public1.mydomain.tld and store
+that backup using server-sd then my understanding of the order of events is
+this:
+
+\begin{enumerate}
+\item I execute my Bacula 'console' command on server.int.mydomain.tld.
+\item console connects to server-dir.
+\item I tell console to 'run' backup Job 'Public1-Backup'.
+\item console relays this command to server-dir.
+\item server-dir connects, through the NAT'd firewall, to public1-fd at
+ public1.mydomain.tld:9102
+\item server-dir tells public1-fd to start sending the files defined in the
+ 'Public1-Backup' Job's FileSet resource to the Storage resource
+ 'autochanger1', which we have defined in server-dir.conf as having the
+ same address:port as above of Storage-server, but which on this machine
+ is resolved to firewall.mydomain.tld:9103.
+\item public1-fd connects to firewall.mydomain.tld:9103 and begins sending
+ files.
+ \end{enumerate}
+
+\subsection{Important Note}
+\index[general]{Important Note }
+\index[general]{Note!Important }
+
+In order for the above 'Public1-Backup' Job to succeed,
+firewall.mydomain.tld:9103 MUST be forwarded using the firewall's
+configuration software to server.int.mydomain.tld:9103. Some firewalls call
+this 'Server Publication'. Others may call it 'Port Forwarding'.
+
+\subsection{Firewall Problems}
+\index[general]{Firewall Problems}
+\index[general]{Problems!Firewalls}
+Either a firewall or a router may decide to timeout and terminate
+open connections if they are not active for a short time. By Internet
+standards the period should be two hours, and should be indefinitely
+extended if KEEPALIVE is set as is the case by Bacula. If your firewall
+or router does not respect these rules, you may find Bacula connections
+terminated. In that case, the first thing to try is turning on the
+{\bf Heart Beat Interval} both in the File daemon and the Storage daemon
+and set an interval of say five minutes.
+
+Also, if you have denial of service rate limiting in your firewall, this
+too can cause Bacula disconnects since Bacula can at times use very high
+access rates. To avoid this, you should implement default accept
+rules for the Bacula ports involved before the rate limiting rules.
+
+Finally, if you have a Windows machine, it will most likely by default
+disallow connections to the Bacula Windows File daemon. See the
+Windows chapter of this manual for additional details.
--- /dev/null
+#!/usr/bin/perl -w
+# Fixes various things within tex files.
+
+use strict;
+
+my %args;
+
+
+sub get_includes {
+ # Get a list of include files from the top-level tex file.
+ my (@list,$file);
+
+ foreach my $filename (@_) {
+ $filename or next;
+ # Start with the top-level latex file so it gets checked too.
+ push (@list,$filename);
+
+ # Get a list of all the html files in the directory.
+ open IF,"<$filename" or die "Cannot open input file $filename";
+ while (<IF>) {
+ chomp;
+ push @list,"$1.tex" if (/\\include\{(.*?)\}/);
+ }
+
+ close IF;
+ }
+ return @list;
+}
+
+sub convert_files {
+ my (@files) = @_;
+ my ($linecnt,$filedata,$output,$itemcnt,$indentcnt,$cnt);
+
+ $cnt = 0;
+ foreach my $file (@files) {
+ # Open the file and load the whole thing into $filedata. A bit wasteful but
+ # easier to deal with, and we don't have a problem with speed here.
+ $filedata = "";
+ open IF,"<$file" or die "Cannot open input file $file";
+ while (<IF>) {
+ $filedata .= $_;
+ }
+ close IF;
+
+ # We look for a line that starts with \item, and indent the two next lines (if not blank)
+ # by three spaces.
+ my $linecnt = 3;
+ $indentcnt = 0;
+ $output = "";
+ # Process a line at a time.
+ foreach (split(/\n/,$filedata)) {
+ $_ .= "\n"; # Put back the return.
+ # If this line is less than the third line past the \item command,
+ # and the line isn't blank and doesn't start with whitespace
+ # add three spaces to the start of the line. Keep track of the number
+ # of lines changed.
+ if ($linecnt < 3 and !/^\\item/) {
+ if (/^[^\n\s]/) {
+ $output .= " " . $_;
+ $indentcnt++;
+ } else {
+ $output .= $_;
+ }
+ $linecnt++;
+ } else {
+ $linecnt = 3;
+ $output .= $_;
+ }
+ /^\\item / and $linecnt = 1;
+ }
+
+
+ # This is an item line. We need to process it too. If inside a \begin{description} environment, convert
+ # \item {\bf xxx} to \item [xxx] or \item [{xxx}] (if xxx contains '[' or ']'.
+ $itemcnt = 0;
+ $filedata = $output;
+ $output = "";
+ my ($before,$descrip,$this,$between);
+
+ # Find any \begin{description} environment
+ while ($filedata =~ /(\\begin[\s\n]*\{[\s\n]*description[\s\n]*\})(.*?)(\\end[\s\n]*\{[\s\n]*description[\s\n]*\})/s) {
+ $output .= $` . $1;
+ $filedata = $3 . $';
+ $descrip = $2;
+
+ # Search for \item {\bf xxx}
+ while ($descrip =~ /\\item[\s\n]*\{[\s\n]*\\bf[\s\n]*/s) {
+ $descrip = $';
+ $output .= $`;
+ ($between,$descrip) = find_matching_brace($descrip);
+ if (!$descrip) {
+ $linecnt = $output =~ tr/\n/\n/;
+ print STDERR "Missing matching curly brace at line $linecnt in $file\n" if (!$descrip);
+ }
+
+ # Now do the replacement.
+ $between = '{' . $between . '}' if ($between =~ /\[|\]/);
+ $output .= "\\item \[$between\]";
+ $itemcnt++;
+ }
+ $output .= $descrip;
+ }
+ $output .= $filedata;
+
+ # If any hyphens or \item commnads were converted, save the file.
+ if ($indentcnt or $itemcnt) {
+ open OF,">$file" or die "Cannot open output file $file";
+ print OF $output;
+ close OF;
+ print "$indentcnt indent", ($indentcnt == 1) ? "" : "s"," added in $file\n";
+ print "$itemcnt item", ($itemcnt == 1) ? "" : "s"," Changed in $file\n";
+ }
+
+ $cnt += $indentcnt + $itemcnt;
+ }
+ return $cnt;
+}
+
+sub find_matching_brace {
+ # Finds text up to the next matching brace. Assumes that the input text doesn't contain
+ # the opening brace, but we want to find text up to a matching closing one.
+ # Returns the text between the matching braces, followed by the rest of the text following
+ # (which does not include the matching brace).
+ #
+ my $str = shift;
+ my ($this,$temp);
+ my $cnt = 1;
+
+ while ($cnt) {
+ # Ignore verbatim constructs involving curly braces, or if the character preceding
+ # the curly brace is a backslash.
+ if ($str =~ /\\verb\*?\{.*?\{|\\verb\*?\}.*?\}|\{|\}/s) {
+ $this .= $`;
+ $str = $';
+ $temp = $&;
+
+ if ((substr($this,-1,1) eq '\\') or
+ $temp =~ /^\\verb/) {
+ $this .= $temp;
+ next;
+ }
+
+ $cnt += ($temp eq '{') ? 1 : -1;
+ # If this isn't the matching curly brace ($cnt > 0), include the brace.
+ $this .= $temp if ($cnt);
+ } else {
+ # No matching curly brace found.
+ return ($this . $str,'');
+ }
+ }
+ return ($this,$str);
+}
+
+sub check_arguments {
+ # Checks command-line arguments for ones starting with -- puts them into
+ # a hash called %args and removes them from @ARGV.
+ my $args = shift;
+ my $i;
+
+ for ($i = 0; $i < $#ARGV; $i++) {
+ $ARGV[$i] =~ /^\-+/ or next;
+ $ARGV[$i] =~ s/^\-+//;
+ $args{$ARGV[$i]} = "";
+ delete ($ARGV[$i]);
+
+ }
+}
+
+##################################################################
+# MAIN ####
+##################################################################
+
+my @includes;
+my $cnt;
+
+check_arguments(\%args);
+die "No Files given to Check\n" if ($#ARGV < 0);
+
+# Examine the file pointed to by the first argument to get a list of
+# includes to test.
+@includes = get_includes(@ARGV);
+
+$cnt = convert_files(@includes);
+print "No lines changed\n" unless $cnt;
--- /dev/null
+# This module does multiple indices, supporting the style of the LaTex 'index'
+# package.
+
+# Version Information:
+# 16-Feb-2005 -- Original Creation. Karl E. Cunningham
+# 14-Mar-2005 -- Clarified and Consolodated some of the code.
+# Changed to smoothly handle single and multiple indices.
+
+# Two LaTeX index formats are supported...
+# --- SINGLE INDEX ---
+# \usepackage{makeidx}
+# \makeindex
+# \index{entry1}
+# \index{entry2}
+# \index{entry3}
+# ...
+# \printindex
+#
+# --- MULTIPLE INDICES ---
+#
+# \usepackage{makeidx}
+# \usepackage{index}
+# \makeindex -- latex2html doesn't care but LaTeX does.
+# \newindex{ref1}{ext1}{ext2}{title1}
+# \newindex{ref2}{ext1}{ext2}{title2}
+# \newindex{ref3}{ext1}{ext2}{title3}
+# \index[ref1]{entry1}
+# \index[ref1]{entry2}
+# \index[ref3]{entry3}
+# \index[ref2]{entry4}
+# \index{entry5}
+# \index[ref3]{entry6}
+# ...
+# \printindex[ref1]
+# \printindex[ref2]
+# \printindex[ref3]
+# \printindex
+# ___________________
+#
+# For the multiple-index style, each index is identified by the ref argument to \newindex, \index,
+# and \printindex. A default index is allowed, which is indicated by omitting the optional
+# argument. The default index does not require a \newindex command. As \index commands
+# are encountered, their entries are stored according
+# to the ref argument. When the \printindex command is encountered, the stored index
+# entries for that argument are retrieved and printed. The title for each index is taken
+# from the last argument in the \newindex command.
+# While processing \index and \printindex commands, if no argument is given the index entries
+# are built into a default index. The title of the default index is simply "Index".
+# This makes the difference between single- and multiple-index processing trivial.
+#
+# Another method can be used by omitting the \printindex command and just using \include to
+# pull in index files created by the makeindex program. These files will start with
+# \begin{theindex}. This command is used to determine where to print the index. Using this
+# approach, the indices will be output in the same order as the newindex commands were
+# originally found (see below). Using a combination of \printindex and \include{indexfile} has not
+# been tested and may produce undesireable results.
+#
+# The index data are stored in a hash for later sorting and output. As \printindex
+# commands are handled, the order in which they were found in the tex filea is saved,
+# associated with the ref argument to \printindex.
+#
+# We use the original %index hash to store the index data into. We append a \002 followed by the
+# name of the index to isolate the entries in different indices from each other. This is necessary
+# so that different indices can have entries with the same name. For the default index, the \002 is
+# appended without the name.
+#
+# Since the index order in the output cannot be determined if the \include{indexfile}
+# command is used, the order will be assumed from the order in which the \newindex
+# commands were originally seen in the TeX files. This order is saved as well as the
+# order determined from any printindex{ref} commands. If \printindex commnads are used
+# to specify the index output, that order will be used. If the \include{idxfile} command
+# is used, the order of the original newindex commands will be used. In this case the
+# default index will be printed last since it doesn't have a corresponding \newindex
+# command and its order cannot be determined. Mixing \printindex and \include{idxfile}
+# commands in the same file is likely to produce less than satisfactory results.
+#
+#
+# The hash containing index data is named %indices. It contains the following data:
+#{
+# 'title' => {
+# $ref1 => $indextitle ,
+# $ref2 => $indextitle ,
+# ...
+# },
+# 'newcmdorder' => [ ref1, ref2, ..., * ], # asterisk indicates the position of the default index.
+# 'printindorder' => [ ref1, ref2, ..., * ], # asterisk indicates the position of the default index.
+#}
+
+
+# Globals to handle multiple indices.
+my %indices;
+
+# This tells the system to use up to 7 words in index entries.
+$WORDS_IN_INDEX = 10;
+
+# KEC 2-18-05
+# Handles the \newindex command. This is called if the \newindex command is
+# encountered in the LaTex source. Gets the index ref and title from the arguments.
+# Saves the index ref and title.
+# Note that we are called once to handle multiple \newindex commands that are
+# newline-separated.
+sub do_cmd_newindex {
+ my $data = shift;
+ # The data is sent to us as fields delimited by their ID #'s. We extract the
+ # fields.
+ foreach my $line (split("\n",$data)) {
+ my @fields = split (/(?:\<\#\d+?\#\>)+/,$line);
+
+ # The index name and title are the second and fourth fields in the data.
+ if ($line =~ /^</ or $line =~ /^\\newindex/) {
+ my ($indexref,$indextitle) = ($fields[1],$fields[4]);
+ $indices{'title'}{$indexref} = $indextitle;
+ push (@{$indices{'newcmdorder'}},$indexref);
+ }
+ }
+}
+
+
+# KEC -- Copied from makeidx.perl and modified to do multiple indices.
+# Processes an \index entry from the LaTex file.
+# Gets the optional argument from the index command, which is the name of the index
+# into which to place the entry.
+# Drops the brackets from the index_name
+# Puts the index entry into the html stream
+# Creates the tokenized index entry (which also saves the index entry info
+sub do_real_index {
+ local($_) = @_;
+ local($pat,$idx_entry,$index_name);
+ # catches opt-arg from \index commands for index.sty
+ $index_name = &get_next_optional_argument;
+ $index_name = "" unless defined $index_name;
+ # Drop leading and trailing brackets from the index name.
+ $index_name =~ s/^\[|\]$//g;
+
+ $idx_entry = &missing_braces unless (
+ (s/$next_pair_pr_rx/$pat=$1;$idx_entry=$2;''/e)
+ ||(s/$next_pair_rx/$pat=$1;$idx_entry=$2;''/e));
+
+ if ($index_name and defined $idx_entry and
+ !defined $indices{'title'}{$index_name}) {
+ print STDERR "\nInvalid Index Name: \\index \[$index_name\]\{$idx_entry\}\n";
+ }
+
+ $idx_entry = &named_index_entry($pat, $idx_entry,$index_name);
+ $idx_entry.$_;
+}
+
+# Creates and saves an index entry in the index hashes.
+# Modified to do multiple indices.
+# Creates an index_key that allows index entries to have the same characteristics but be in
+# different indices. This index_key is the regular key with the index name appended.
+# Save the index order for the entry in the %index_order hash.
+sub named_index_entry {
+ local($br_id, $str, $index_name) = @_;
+ my ($index_key);
+ # escape the quoting etc characters
+ # ! -> \001
+ # @ -> \002
+ # | -> \003
+ $* = 1; $str =~ s/\n\s*/ /g; $* = 0; # remove any newlines
+ # protect \001 occurring with images
+ $str =~ s/\001/\016/g; # 0x1 to 0xF
+ $str =~ s/\\\\/\011/g; # Double backslash -> 0xB
+ $str =~ s/\\;SPMquot;/\012/g; # \;SPMquot; -> 0xC
+ $str =~ s/;SPMquot;!/\013/g; # ;SPMquot; -> 0xD
+ $str =~ s/!/\001/g; # Exclamation point -> 0x1
+ $str =~ s/\013/!/g; # 0xD -> Exclaimation point
+ $str =~ s/;SPMquot;@/\015/g; # ;SPMquot;@ to 0xF
+ $str =~ s/@/\002/g; # At sign -> 0x2
+ $str =~ s/\015/@/g; # 0xF to At sign
+ $str =~ s/;SPMquot;\|/\017/g; # ;SMPquot;| to 0x11
+ $str =~ s/\|/\003/g; # Vertical line to 0x3
+ $str =~ s/\017/|/g; # 0x11 to vertical line
+ $str =~ s/;SPMquot;(.)/\1/g; # ;SPMquot; -> whatever the next character is
+ $str =~ s/\012/;SPMquot;/g; # 0x12 to ;SPMquot;
+ $str =~ s/\011/\\\\/g; # 0x11 to double backslash
+ local($key_part, $pageref) = split("\003", $str, 2);
+
+ # For any keys of the form: blablabla!blablabla, which want to be split at the
+ # exclamation point, replace the ! with a comma and a space. We don't do it
+ # that way for this index.
+ $key_part =~ s/\001/, /g;
+ local(@keys) = split("\001", $key_part);
+ # If TITLE is not yet available use $before.
+ $TITLE = $saved_title if (($saved_title)&&(!($TITLE)||($TITLE eq $default_title)));
+ $TITLE = $before unless $TITLE;
+ # Save the reference
+ local($words) = '';
+ if ($SHOW_SECTION_NUMBERS) { $words = &make_idxnum; }
+ elsif ($SHORT_INDEX) { $words = &make_shortidxname; }
+ else { $words = &make_idxname; }
+ local($super_key) = '';
+ local($sort_key, $printable_key, $cur_key);
+ foreach $key (@keys) {
+ $key =~ s/\016/\001/g; # revert protected \001s
+ ($sort_key, $printable_key) = split("\002", $key);
+ #
+ # RRM: 16 May 1996
+ # any \label in the printable-key will have already
+ # created a label where the \index occurred.
+ # This has to be removed, so that the desired label
+ # will be found on the Index page instead.
+ #
+ if ($printable_key =~ /tex2html_anchor_mark/ ) {
+ $printable_key =~ s/><tex2html_anchor_mark><\/A><A//g;
+ local($tmpA,$tmpB) = split("NAME=\"", $printable_key);
+ ($tmpA,$tmpB) = split("\"", $tmpB);
+ $ref_files{$tmpA}='';
+ $index_labels{$tmpA} = 1;
+ }
+ #
+ # resolve and clean-up the hyperlink index-entries
+ # so they can be saved in an index.pl file
+ #
+ if ($printable_key =~ /$cross_ref_mark/ ) {
+ local($label,$id,$ref_label);
+ # $printable_key =~ s/$cross_ref_mark#(\w+)#(\w+)>$cross_ref_mark/
+ $printable_key =~ s/$cross_ref_mark#([^#]+)#([^>]+)>$cross_ref_mark/
+ do { ($label,$id) = ($1,$2);
+ $ref_label = $external_labels{$label} unless
+ ($ref_label = $ref_files{$label});
+ '"' . "$ref_label#$label" . '">' .
+ &get_ref_mark($label,$id)}
+ /geo;
+ }
+ $printable_key =~ s/<\#[^\#>]*\#>//go;
+ #RRM
+ # recognise \char combinations, for a \backslash
+ #
+ $printable_key =~ s/\&\#;\'134/\\/g; # restore \\s
+ $printable_key =~ s/\&\#;\`<BR> /\\/g; # ditto
+ $printable_key =~ s/\&\#;*SPMquot;92/\\/g; # ditto
+ #
+ # $sort_key .= "@$printable_key" if !($printable_key); # RRM
+ $sort_key .= "@$printable_key" if !($sort_key); # RRM
+ $sort_key =~ tr/A-Z/a-z/;
+ if ($super_key) {
+ $cur_key = $super_key . "\001" . $sort_key;
+ $sub_index{$super_key} .= $cur_key . "\004";
+ } else {
+ $cur_key = $sort_key;
+ }
+
+ # Append the $index_name to the current key with a \002 delimiter. This will
+ # allow the same index entry to appear in more than one index.
+ $index_key = $cur_key . "\002$index_name";
+
+ $index{$index_key} .= "";
+
+ #
+ # RRM, 15 June 1996
+ # if there is no printable key, but one is known from
+ # a previous index-entry, then use it.
+ #
+ if (!($printable_key) && ($printable_key{$index_key}))
+ { $printable_key = $printable_key{$index_key}; }
+# if (!($printable_key) && ($printable_key{$cur_key}))
+# { $printable_key = $printable_key{$cur_key}; }
+ #
+ # do not overwrite the printable_key if it contains an anchor
+ #
+ if (!($printable_key{$index_key} =~ /tex2html_anchor_mark/ ))
+ { $printable_key{$index_key} = $printable_key || $key; }
+# if (!($printable_key{$cur_key} =~ /tex2html_anchor_mark/ ))
+# { $printable_key{$cur_key} = $printable_key || $key; }
+
+ $super_key = $cur_key;
+ }
+ #
+ # RRM
+ # page-ranges, from |( and |) and |see
+ #
+ if ($pageref) {
+ if ($pageref eq "\(" ) {
+ $pageref = '';
+ $next .= " from ";
+ } elsif ($pageref eq "\)" ) {
+ $pageref = '';
+ local($next) = $index{$index_key};
+# local($next) = $index{$cur_key};
+ # $next =~ s/[\|] *$//;
+ $next =~ s/(\n )?\| $//;
+ $index{$index_key} = "$next to ";
+# $index{$cur_key} = "$next to ";
+ }
+ }
+
+ if ($pageref) {
+ $pageref =~ s/\s*$//g; # remove trailing spaces
+ if (!$pageref) { $pageref = ' ' }
+ $pageref =~ s/see/<i>see <\/i> /g;
+ #
+ # RRM: 27 Dec 1996
+ # check if $pageref corresponds to a style command.
+ # If so, apply it to the $words.
+ #
+ local($tmp) = "do_cmd_$pageref";
+ if (defined &$tmp) {
+ $words = &$tmp("<#0#>$words<#0#>");
+ $words =~ s/<\#[^\#]*\#>//go;
+ $pageref = '';
+ }
+ }
+ #
+ # RRM: 25 May 1996
+ # any \label in the pageref section will have already
+ # created a label where the \index occurred.
+ # This has to be removed, so that the desired label
+ # will be found on the Index page instead.
+ #
+ if ($pageref) {
+ if ($pageref =~ /tex2html_anchor_mark/ ) {
+ $pageref =~ s/><tex2html_anchor_mark><\/A><A//g;
+ local($tmpA,$tmpB) = split("NAME=\"", $pageref);
+ ($tmpA,$tmpB) = split("\"", $tmpB);
+ $ref_files{$tmpA}='';
+ $index_labels{$tmpA} = 1;
+ }
+ #
+ # resolve and clean-up any hyperlinks in the page-ref,
+ # so they can be saved in an index.pl file
+ #
+ if ($pageref =~ /$cross_ref_mark/ ) {
+ local($label,$id,$ref_label);
+ # $pageref =~ s/$cross_ref_mark#(\w+)#(\w+)>$cross_ref_mark/
+ $pageref =~ s/$cross_ref_mark#([^#]+)#([^>]+)>$cross_ref_mark/
+ do { ($label,$id) = ($1,$2);
+ $ref_files{$label} = ''; # ???? RRM
+ if ($index_labels{$label}) { $ref_label = ''; }
+ else { $ref_label = $external_labels{$label}
+ unless ($ref_label = $ref_files{$label});
+ }
+ '"' . "$ref_label#$label" . '">' . &get_ref_mark($label,$id)}/geo;
+ }
+ $pageref =~ s/<\#[^\#>]*\#>//go;
+
+ if ($pageref eq ' ') { $index{$index_key}='@'; }
+ else { $index{$index_key} .= $pageref . "\n | "; }
+ } else {
+ local($thisref) = &make_named_href('',"$CURRENT_FILE#$br_id",$words);
+ $thisref =~ s/\n//g;
+ $index{$index_key} .= $thisref."\n | ";
+ }
+ #print "\nREF: $sort_key : $index_key :$index{$index_key}";
+
+ #join('',"<A NAME=$br_id>$anchor_invisible_mark<\/A>",$_);
+
+ "<A NAME=\"$br_id\">$anchor_invisible_mark<\/A>";
+}
+
+
+# KEC. -- Copied from makeidx.perl, then modified to do multiple indices.
+# Feeds the index entries to the output. This is called for each index to be built.
+#
+# Generates a list of lookup keys for index entries, from both %printable_keys
+# and %index keys.
+# Sorts the keys according to index-sorting rules.
+# Removes keys with a 0x01 token. (duplicates?)
+# Builds a string to go to the index file.
+# Adds the index entries to the string if they belong in this index.
+# Keeps track of which index is being worked on, so only the proper entries
+# are included.
+# Places the index just built in to the output at the proper place.
+{ my $index_number = 0;
+sub add_real_idx {
+ print "\nDoing the index ... Index Number $index_number\n";
+ local($key, @keys, $next, $index, $old_key, $old_html);
+ my ($idx_ref,$keyref);
+ # RRM, 15.6.96: index constructed from %printable_key, not %index
+ @keys = keys %printable_key;
+
+ while (/$idx_mark/) {
+ # Get the index reference from what follows the $idx_mark and
+ # remove it from the string.
+ s/$idxmark\002(.*?)\002/$idxmark/;
+ $idx_ref = $1;
+ $index = '';
+ # include non- makeidx index-entries
+ foreach $key (keys %index) {
+ next if $printable_key{$key};
+ $old_key = $key;
+ if ($key =~ s/###(.*)$//) {
+ next if $printable_key{$key};
+ push (@keys, $key);
+ $printable_key{$key} = $key;
+ if ($index{$old_key} =~ /HREF="([^"]*)"/i) {
+ $old_html = $1;
+ $old_html =~ /$dd?([^#\Q$dd\E]*)#/;
+ $old_html = $1;
+ } else { $old_html = '' }
+ $index{$key} = $index{$old_key} . $old_html."</A>\n | ";
+ };
+ }
+ @keys = sort makeidx_keysort @keys;
+ @keys = grep(!/\001/, @keys);
+ my $cnt = 0;
+ foreach $key (@keys) {
+ my ($keyref) = $key =~ /.*\002(.*)/;
+ next unless ($idx_ref eq $keyref); # KEC.
+ $index .= &add_idx_key($key);
+ $cnt++;
+ }
+ print "$cnt Index Entries Added\n";
+ $index = '<DD>'.$index unless ($index =~ /^\s*<D(D|T)>/);
+ $index_number++; # KEC.
+ if ($SHORT_INDEX) {
+ print "(compact version with Legend)";
+ local($num) = ( $index =~ s/\<D/<D/g );
+ if ($num > 50 ) {
+ s/$idx_mark/$preindex<HR><DL>\n$index\n<\/DL>$preindex/o;
+ } else {
+ s/$idx_mark/$preindex<HR><DL>\n$index\n<\/DL>/o;
+ }
+ } else {
+ s/$idx_mark/<DL COMPACT>\n$index\n<\/DL>/o; }
+ }
+}
+}
+
+# KEC. Copied from latex2html.pl and modified to support multiple indices.
+# The bibliography and the index should be treated as separate sections
+# in their own HTML files. The \bibliography{} command acts as a sectioning command
+# that has the desired effect. But when the bibliography is constructed
+# manually using the thebibliography environment, or when using the
+# theindex environment it is not possible to use the normal sectioning
+# mechanism. This subroutine inserts a \bibliography{} or a dummy
+# \textohtmlindex command just before the appropriate environments
+# to force sectioning.
+sub add_bbl_and_idx_dummy_commands {
+ local($id) = $global{'max_id'};
+
+ s/([\\]begin\s*$O\d+$C\s*thebibliography)/$bbl_cnt++; $1/eg;
+ ## if ($bbl_cnt == 1) {
+ s/([\\]begin\s*$O\d+$C\s*thebibliography)/$id++; "\\bibliography$O$id$C$O$id$C $1"/geo;
+ #}
+ $global{'max_id'} = $id;
+ # KEC. Modified to global substitution to place multiple index tokens.
+ s/[\\]begin\s*($O\d+$C)\s*theindex/\\textohtmlindex$1/go;
+ # KEC. Modified to pick up the optional argument to \printindex
+ s/[\\]printindex\s*(\[.*?\])?/
+ do { (defined $1) ? "\\textohtmlindex $1" : "\\textohtmlindex []"; } /ego;
+ &lib_add_bbl_and_idx_dummy_commands() if defined(&lib_add_bbl_and_idx_dummy_commands);
+}
+
+# KEC. Copied from latex2html.pl and modified to support multiple indices.
+# For each textohtmlindex mark found, determine the index titles and headers.
+# We place the index ref in the header so the proper index can be generated later.
+# For the default index, the index ref is blank.
+#
+# One problem is that this routine is called twice.. Once for processing the
+# command as originally seen, and once for processing the command when
+# doing the name for the index file. We can detect that by looking at the
+# id numbers (or ref) surrounding the \theindex command, and not incrementing
+# index_number unless a new id (or ref) is seen. This has the side effect of
+# having to unconventionally start the index_number at -1. But it works.
+#
+# Gets the title from the list of indices.
+# If this is the first index, save the title in $first_idx_file. This is what's referenced
+# in the navigation buttons.
+# Increment the index_number for next time.
+# If the indexname command is defined or a newcommand defined for indexname, do it.
+# Save the index TITLE in the toc
+# Save the first_idx_file into the idxfile. This goes into the nav buttons.
+# Build index_labels if needed.
+# Create the index headings and put them in the output stream.
+
+{ my $index_number = 0; # Will be incremented before use.
+ my $first_idx_file; # Static
+ my $no_increment = 0;
+
+sub do_cmd_textohtmlindex {
+ local($_) = @_;
+ my ($idxref,$idxnum,$index_name);
+
+ # We get called from make_name with the first argument = "\001noincrement". This is a sign
+ # to not increment $index_number the next time we are called. We get called twice, once
+ # my make_name and once by process_command. Unfortunately, make_name calls us just to set the name
+ # but doesn't use the result so we get called a second time by process_command. This works fine
+ # except for cases where there are multiple indices except if they aren't named, which is the case
+ # when the index is inserted by an include command in latex. In these cases we are only able to use
+ # the index number to decide which index to draw from, and we don't know how to increment that index
+ # number if we get called a variable number of times for the same index, as is the case between
+ # making html (one output file) and web (multiple output files) output formats.
+ if (/\001noincrement/) {
+ $no_increment = 1;
+ return;
+ }
+
+ # Remove (but save) the index reference
+ s/^\s*\[(.*?)\]/{$idxref = $1; "";}/e;
+
+ # If we have an $idxref, the index name was specified. In this case, we have all the
+ # information we need to carry on. Otherwise, we need to get the idxref
+ # from the $index_number and set the name to "Index".
+ if ($idxref) {
+ $index_name = $indices{'title'}{$idxref};
+ } else {
+ if (defined ($idxref = $indices{'newcmdorder'}->[$index_number])) {
+ $index_name = $indices{'title'}{$idxref};
+ } else {
+ $idxref = '';
+ $index_name = "Index";
+ }
+ }
+
+ $idx_title = "Index"; # The name displayed in the nav bar text.
+
+ # Only set $idxfile if we are at the first index. This will point the
+ # navigation panel to the first index file rather than the last.
+ $first_idx_file = $CURRENT_FILE if ($index_number == 0);
+ $idxfile = $first_idx_file; # Pointer for the Index button in the nav bar.
+ $toc_sec_title = $index_name; # Index link text in the toc.
+ $TITLE = $toc_sec_title; # Title for this index, from which its filename is built.
+ if (%index_labels) { &make_index_labels(); }
+ if (($SHORT_INDEX) && (%index_segment)) { &make_preindex(); }
+ else { $preindex = ''; }
+ local $idx_head = $section_headings{'textohtmlindex'};
+ local($heading) = join(''
+ , &make_section_heading($TITLE, $idx_head)
+ , $idx_mark, "\002", $idxref, "\002" );
+ local($pre,$post) = &minimize_open_tags($heading);
+ $index_number++ unless ($no_increment);
+ $no_increment = 0;
+ join('',"<BR>\n" , $pre, $_);
+}
+}
+
+# Returns an index key, given the key passed as the first argument.
+# Not modified for multiple indices.
+sub add_idx_key {
+ local($key) = @_;
+ local($index, $next);
+ if (($index{$key} eq '@' )&&(!($index_printed{$key}))) {
+ if ($SHORT_INDEX) { $index .= "<DD><BR>\n<DT>".&print_key."\n<DD>"; }
+ else { $index .= "<DT><DD><BR>\n<DT>".&print_key."\n<DD>"; }
+ } elsif (($index{$key})&&(!($index_printed{$key}))) {
+ if ($SHORT_INDEX) {
+ $next = "<DD>".&print_key."\n : ". &print_idx_links;
+ } else {
+ $next = "<DT>".&print_key."\n<DD>". &print_idx_links;
+ }
+ $index .= $next."\n";
+ $index_printed{$key} = 1;
+ }
+
+ if ($sub_index{$key}) {
+ local($subkey, @subkeys, $subnext, $subindex);
+ @subkeys = sort(split("\004", $sub_index{$key}));
+ if ($SHORT_INDEX) {
+ $index .= "<DD>".&print_key unless $index_printed{$key};
+ $index .= "<DL>\n";
+ } else {
+ $index .= "<DT>".&print_key."\n<DD>" unless $index_printed{$key};
+ $index .= "<DL COMPACT>\n";
+ }
+ foreach $subkey (@subkeys) {
+ $index .= &add_sub_idx_key($subkey) unless ($index_printed{$subkey});
+ }
+ $index .= "</DL>\n";
+ }
+ return $index;
+}
+
+1; # Must be present as the last line.
--- /dev/null
+%%
+%%
+
+\chapter{What To Do When Bacula Crashes (Kaboom)}
+\label{KaboomChapter}
+\index[general]{Kaboom!What To Do When Bacula Crashes }
+\index[general]{What To Do When Bacula Crashes (Kaboom) }
+
+If you are running on a Linux system, and you have a set of working
+configuration files, it is very unlikely that {\bf Bacula} will crash. As with
+all software, however, it is inevitable that someday, it may crash,
+particularly if you are running on another operating system or using a new or
+unusual feature.
+
+This chapter explains what you should do if one of the three {\bf Bacula}
+daemons (Director, File, Storage) crashes. When we speak of crashing, we
+mean that the daemon terminates abnormally because of an error. There are
+many cases where Bacula detects errors (such as PIPE errors) and will fail
+a job. These are not considered crashes. In addition, under certain
+conditions, Bacula will detect a fatal in the configuration, such as
+lack of permission to read/write the working directory. In that case,
+Bacula will force itself to crash with a SEGFAULT. However, before
+crashing, Bacula will normally display a message indicating why.
+For more details, please read on.
+
+
+\section{Traceback}
+\index[general]{Traceback}
+
+Each of the three Bacula daemons has a built-in exception handler which, in
+case of an error, will attempt to produce a traceback. If successful the
+traceback will be emailed to you.
+
+For this to work, you need to ensure that a few things are setup correctly on
+your system:
+
+\begin{enumerate}
+\item You must have a version of Bacula built with debug information turned
+ on and not stripped of debugging symbols.
+
+\item You must have an installed copy of {\bf gdb} (the GNU debugger), and it
+ must be on {\bf Bacula's} path. On some systems such as Solaris, {\bf
+ gdb} may be replaced by {\bf dbx}.
+
+\item The Bacula installed script file {\bf btraceback} must be in the same
+ directory as the daemon which dies, and it must be marked as executable.
+
+\item The script file {\bf btraceback.gdb} must have the correct path to it
+ specified in the {\bf btraceback} file.
+
+\item You must have a {\bf mail} program which is on {\bf Bacula's} path.
+ By default, this {\bf mail} program is set to {\bf bsmtp}, so it must
+ be correctly configured.
+
+\item If you run either the Director or Storage daemon under a non-root
+ userid, you will most likely need to modify the {\bf btraceback} file
+ to do something like {\bf sudo} (raise to root priority) for the
+ call to {\bf gdb} so that it has the proper permissions to debug
+ Bacula.
+\end{enumerate}
+
+If all the above conditions are met, the daemon that crashes will produce a
+traceback report and email it to you. If the above conditions are not true,
+you can either run the debugger by hand as described below, or you may be able
+to correct the problems by editing the {\bf btraceback} file. I recommend not
+spending too much time on trying to get the traceback to work as it can be
+very difficult.
+
+The changes that might be needed are to add a correct path to the {\bf gdb}
+program, correct the path to the {\bf btraceback.gdb} file, change the {\bf
+mail} program or its path, or change your email address. The key line in the
+{\bf btraceback} file is:
+
+\footnotesize
+\begin{verbatim}
+gdb -quiet -batch -x /home/kern/bacula/bin/btraceback.gdb \
+ $1 $2 2>\&1 | bsmtp -s "Bacula traceback" your-address@xxx.com
+\end{verbatim}
+\normalsize
+
+Since each daemon has the same traceback code, a single btraceback file is
+sufficient if you are running more than one daemon on a machine.
+
+\section{Testing The Traceback}
+\index[general]{Traceback!Testing The }
+\index[general]{Testing The Traceback }
+
+To "manually" test the traceback feature, you simply start {\bf Bacula} then
+obtain the {\bf PID} of the main daemon thread (there are multiple threads).
+The output produced here will look different depending on what OS and what
+version of the kernel you are running.
+Unfortunately, the output had to be split to fit on this page:
+
+\footnotesize
+\begin{verbatim}
+[kern@rufus kern]$ ps fax --columns 132 | grep bacula-dir
+ 2103 ? S 0:00 /home/kern/bacula/k/src/dird/bacula-dir -c
+ /home/kern/bacula/k/src/dird/dird.conf
+ 2104 ? S 0:00 \_ /home/kern/bacula/k/src/dird/bacula-dir -c
+ /home/kern/bacula/k/src/dird/dird.conf
+ 2106 ? S 0:00 \_ /home/kern/bacula/k/src/dird/bacula-dir -c
+ /home/kern/bacula/k/src/dird/dird.conf
+ 2105 ? S 0:00 \_ /home/kern/bacula/k/src/dird/bacula-dir -c
+ /home/kern/bacula/k/src/dird/dird.conf
+\end{verbatim}
+\normalsize
+
+which in this case is 2103. Then while Bacula is running, you call the program
+giving it the path to the Bacula executable and the {\bf PID}. In this case,
+it is:
+
+\footnotesize
+\begin{verbatim}
+./btraceback /home/kern/bacula/k/src/dird 2103
+\end{verbatim}
+\normalsize
+
+It should produce an email showing you the current state of the daemon (in
+this case the Director), and then exit leaving {\bf Bacula} running as if
+nothing happened. If this is not the case, you will need to correct the
+problem by modifying the {\bf btraceback} script.
+
+Typical problems might be that {\bf gdb} or {\bf dbx} for Solaris is not on
+the default path. Fix this by specifying the full path to it in the {\bf
+btraceback} file. Another common problem is that you haven't modified the
+script so that the {\bf bsmtp} program has an appropriate smtp server or
+the proper syntax for your smtp server. If you use the {\bf mail} program
+and it is not on the default path, it will also fail. On some systems, it
+is preferable to use {\bf Mail} rather than {\bf mail}.
+
+\section{Getting A Traceback On Other Systems}
+\index[general]{Getting A Traceback On Other Systems}
+\index[general]{Systems!Getting A Traceback On Other}
+
+It should be possible to produce a similar traceback on systems other than
+Linux, either using {\bf gdb} or some other debugger. Solaris with {\bf dbx}
+loaded works quite fine. On other systems, you will need to modify the {\bf
+btraceback} program to invoke the correct debugger, and possibly correct the
+{\bf btraceback.gdb} script to have appropriate commands for your debugger. If
+anyone succeeds in making this work with another debugger, please send us a
+copy of what you modified. Please keep in mind that for any debugger to
+work, it will most likely need to run as root, so you may need to modify
+the {\bf btraceback} script accordingly.
+
+\label{ManuallyDebugging}
+\section{Manually Running Bacula Under The Debugger}
+\index[general]{Manually Running Bacula Under The Debugger}
+\index[general]{Debugger!Manually Running Bacula Under The}
+
+If for some reason you cannot get the automatic traceback, or if you want to
+interactively examine the variable contents after a crash, you can run Bacula
+under the debugger. Assuming you want to run the Storage daemon under the
+debugger (the technique is the same for the other daemons, only the name
+changes), you would do the following:
+
+\begin{enumerate}
+\item Start the Director and the File daemon. If the Storage daemon also
+ starts, you will need to find its PID as shown above (ps fax | grep
+ bacula-sd) and kill it with a command like the following:
+
+\footnotesize
+\begin{verbatim}
+ kill -15 PID
+\end{verbatim}
+\normalsize
+
+where you replace {\bf PID} by the actual value.
+
+\item At this point, the Director and the File daemon should be running but
+ the Storage daemon should not.
+
+\item cd to the directory containing the Storage daemon
+
+\item Start the Storage daemon under the debugger:
+
+ \footnotesize
+\begin{verbatim}
+ gdb ./bacula-sd
+\end{verbatim}
+\normalsize
+
+\item Run the Storage daemon:
+
+ \footnotesize
+\begin{verbatim}
+ run -s -f -c ./bacula-sd.conf
+\end{verbatim}
+\normalsize
+
+You may replace the {\bf ./bacula-sd.conf} with the full path to the Storage
+daemon's configuration file.
+
+\item At this point, Bacula will be fully operational.
+
+\item In another shell command window, start the Console program and do what
+ is necessary to cause Bacula to die.
+
+\item When Bacula crashes, the {\bf gdb} shell window will become active and
+ {\bf gdb} will show you the error that occurred.
+
+\item To get a general traceback of all threads, issue the following command:
+
+
+\footnotesize
+\begin{verbatim}
+ thread apply all bt
+\end{verbatim}
+\normalsize
+
+After that you can issue any debugging command.
+\end{enumerate}
+
+\section{Getting Debug Output from Bacula}
+\index[general]{Getting Debug Output from Bacula }
+Each of the daemons normally has debug compiled into the program, but
+disabled. There are two ways to enable the debug output. One is to add the
+{\bf -d nnn} option on the command line when starting the debugger. The {\bf
+nnn} is the debug level, and generally anything between 50 and 200 is
+reasonable. The higher the number, the more output is produced. The output is
+written to standard output.
+
+The second way of getting debug output is to dynamically turn it on using the
+Console using the {\bf setdebug} command. The full syntax of the command is:
+
+\footnotesize
+\begin{verbatim}
+ setdebug level=nnn client=client-name storage=storage-name dir
+\end{verbatim}
+\normalsize
+
+If none of the options are given, the command will prompt you. You can
+selectively turn on/off debugging in any or all the daemons (i.e. it is not
+necessary to specify all the components of the above command).
--- /dev/null
+# This file serves as a place to put initialization code and constants to
+# affect the behavior of latex2html for generating the bacula manuals.
+
+# $LINKPOINT specifies what filename to use to link to when creating
+# index.html. Not that this is a hard link.
+$LINKPOINT='"$OVERALL_TITLE"';
+
+
+# The following must be the last line of this file.
+1;
--- /dev/null
+%%
+%%
+%% The following characters must be preceded by a backslash
+%% to be entered as printable characters:
+%%
+%% # $ % & ~ _ ^ \ { }
+%%
+
+\documentclass[11pt,a4paper]{book}
+\usepackage{html}
+\usepackage{float}
+\usepackage{graphicx}
+\usepackage{bacula}
+\usepackage{longtable}
+\usepackage{makeidx}
+\usepackage{index}
+\usepackage{setspace}
+\usepackage{hyperref}
+\usepackage{url}
+
+
+\makeindex
+\newindex{general}{idx}{ind}{General Index}
+
+\sloppy
+
+\begin{document}
+\sloppy
+
+\newfont{\bighead}{cmr17 at 36pt}
+\parskip 10pt
+\parindent 0pt
+
+\title{\includegraphics{./bacula-logo.eps} \\ \bigskip
+ \Huge{Bacula Problem Resolution Guide}
+ \begin{center}
+ \large{It comes in the night and sucks
+ the essence from your computers. }
+ \end{center}
+}
+
+
+\author{Kern Sibbald}
+\date{\vspace{1.0in}\today \\
+ This manual documents Bacula version \input{version} \\
+ \vspace{0.2in}
+ Copyright \copyright 1999-2007, Free Software Foundation Europe
+ e.V. \\
+ \vspace{0.2in}
+ Permission is granted to copy, distribute and/or modify this document under the terms of the
+ GNU Free Documentation License, Version 1.2 published by the Free Software Foundation;
+ with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+ A copy of the license is included in the section entitled "GNU Free Documentation License".
+}
+
+\maketitle
+
+\clearpage
+\tableofcontents
+\clearpage
+\listoffigures
+\clearpage
+\listoftables
+\clearpage
+
+\include{faq}
+\include{tips}
+\include{tapetesting}
+\include{firewalls}
+\include{kaboom}
+\include{fdl}
+
+
+% The following line tells link_resolver.pl to not include these files:
+% nolinks developersi baculai-dir baculai-fd baculai-sd baculai-console baculai-main
+
+% pull in the index
+\clearpage
+\printindex[general]
+
+\end{document}
--- /dev/null
+%%
+%%
+
+\chapter{Bacula RPM Packaging FAQ}
+\label{RpmFaqChapter}
+\index[general]{FAQ!Bacula\textsuperscript{\textregistered} - RPM Packaging }
+\index[general]{Bacula\textsuperscript{\textregistered} - RPM Packaging FAQ }
+
+\begin{enumerate}
+\item
+ \ilink{How do I build Bacula for platform xxx?}{faq1}
+\item
+ \ilink{How do I control which database support gets built?}{faq2}
+
+\item
+ \ilink{What other defines are used?}{faq3}
+\item
+ \ilink{I'm getting errors about not having permission when I try to build the
+ packages. Do I need to be root?}{faq4}
+\item
+ \ilink{I'm building my own rpms but on all platforms and compiles I get an
+ unresolved dependency for something called
+ /usr/afsws/bin/pagsh.}{faq5}
+\item
+ \ilink{I'm building my own rpms because you don't publish for my platform.
+ Can I get my packages released to sourceforge for other people to use?}{faq6}
+\item
+ \ilink{Is there an easier way than sorting out all these command line options?}{faq7}
+\item
+ \ilink{I just upgraded from 1.36.x to 1.38.x and now my director daemon won't start. It appears to start but dies silently and I get a "connection refused" error when starting the console. What is wrong?}{faq8}
+\item
+ \ilink{There are a lot of rpm packages. Which packages do I need for what?}{faq9}
+\end{enumerate}
+
+\section{Answers}
+\index[general]{Answers }
+
+\begin{enumerate}
+\item
+ \label{faq1}
+ {\bf How do I build Bacula for platform xxx?}
+ The bacula spec file contains defines to build for several platforms:
+ Red Hat 7.x (rh7), Red Hat 8.0 (rh8), Red Hat 9 (rh9), Fedora Core (fc1,
+ fc3, fc4, fc5, fc6, fc7), Whitebox Enterprise Linux 3.0 (wb3), Red Hat Enterprise Linux
+ (rhel3, rhel4, rhel5), Mandrake 10.x (mdk), Mandriva 2006.x (mdv) CentOS (centos3, centos4, centos5)
+ Scientific Linux (sl3, sl4, sl5) and SuSE (su9, su10, su102, su103). The package build is controlled by a mandatory define set at the beginning of the file. These defines basically just control the dependency information that gets coded into the finished rpm package as well
+ as any special configure options required. The platform define may be edited
+ in the spec file directly (by default all defines are set to 0 or "not set").
+ For example, to build the Red Hat 7.x package find the line in the spec file
+ which reads
+
+\footnotesize
+\begin{verbatim}
+ %define rh7 0
+
+\end{verbatim}
+\normalsize
+
+and edit it to read
+
+\footnotesize
+\begin{verbatim}
+ %define rh7 1
+
+\end{verbatim}
+\normalsize
+
+Alternately you may pass the define on the command line when calling rpmbuild:
+
+
+\footnotesize
+\begin{verbatim}
+ rpmbuild -ba --define "build_rh7 1" bacula.spec
+ rpmbuild --rebuild --define build_rh7 1" bacula-x.x.x-x.src.rpm
+
+\end{verbatim}
+\normalsize
+
+\item
+ \label{faq2}
+ {\bf How do I control which database support gets built?}
+ Another mandatory build define controls which database support is compiled,
+ one of build\_sqlite, build\_mysql or build\_postgresql. To get the MySQL
+ package and support either set the
+
+\footnotesize
+\begin{verbatim}
+ %define mysql 0
+ OR
+ %define mysql4 0
+ OR
+ %define mysql5 0
+
+\end{verbatim}
+\normalsize
+
+to
+
+\footnotesize
+\begin{verbatim}
+ %define mysql 1
+ OR
+ %define mysql4 1
+ OR
+ %define mysql5 1
+
+\end{verbatim}
+\normalsize
+
+in the spec file directly or pass it to rpmbuild on the command line:
+
+\footnotesize
+\begin{verbatim}
+ rpmbuild -ba --define "build_rh7 1" --define "build_mysql 1" bacula.spec
+ rpmbuild -ba --define "build_rh7 1" --define "build_mysql4 1" bacula.spec
+ rpmbuild -ba --define "build_rh7 1" --define "build_mysql5 1" bacula.spec
+
+\end{verbatim}
+\normalsize
+
+\item
+ \label{faq3}
+ {\bf What other defines are used?}
+ Three other building defines of note are the depkgs\_version, docs\_version and
+ \_rescuever identifiers. These two defines are set with each release and must
+ match the version of those sources that are being used to build the packages.
+ You would not ordinarily need to edit these. See also the Build Options section
+ below for other build time options that can be passed on the command line.
+\item
+ \label{faq4}
+ {\bf I'm getting errors about not having permission when I try to build the
+ packages. Do I need to be root?}
+ No, you do not need to be root and, in fact, it is better practice to
+ build rpm packages as a non-root user. Bacula packages are designed to
+ be built by a regular user but you must make a few changes on your
+ system to do this. If you are building on your own system then the
+ simplest method is to add write permissions for all to the build
+ directory (/usr/src/redhat/, /usr/src/RPM or /usr/src/packages).
+ To accomplish this, execute the following command as root:
+
+\footnotesize
+\begin{verbatim}
+ chmod -R 777 /usr/src/redhat
+ chmod -R 777 /usr/src/RPM
+ chmod -R 777 /usr/src/packages
+
+\end{verbatim}
+\normalsize
+
+If you are working on a shared system where you can not use the method
+above then you need to recreate the appropriate above directory tree with all
+of its subdirectories inside your home directory. Then create a file named
+
+{\tt .rpmmacros}
+
+in your home directory (or edit the file if it already exists)
+and add the following line:
+
+\footnotesize
+\begin{verbatim}
+ %_topdir /home/myuser/redhat
+
+\end{verbatim}
+\normalsize
+
+Another handy directive for the .rpmmacros file if you wish to suppress the
+creation of debug rpm packages is:
+
+\footnotesize
+\begin{verbatim}
+ %debug_package %{nil}
+
+\end{verbatim}
+
+\normalsize
+
+\item
+ \label{faq5}
+ {\bf I'm building my own rpms but on all platforms and compiles I get an
+ unresolved dependency for something called /usr/afsws/bin/pagsh.} This
+ is a shell from the OpenAFS (Andrew File System). If you are seeing
+ this then you chose to include the docs/examples directory in your
+ package. One of the example scripts in this directory is a pagsh
+ script. Rpmbuild, when scanning for dependencies, looks at the shebang
+ line of all packaged scripts in addition to checking shared libraries.
+ To avoid this do not package the examples directory. If you are seeing this
+ problem you are building a very old bacula package as the examples have been
+ removed from the doc packaging.
+
+\item
+ \label{faq6}
+ {\bf I'm building my own rpms because you don't publish for my platform.
+ Can I get my packages released to sourceforge for other people to use?} Yes,
+ contributions from users are accepted and appreciated. Please examine the
+ directory platforms/contrib-rpm in the source code for further information.
+
+\item
+ \label{faq7}
+ {\bf Is there an easier way than sorting out all these command line options?} Yes,
+ there is a gui wizard shell script which you can use to rebuild the src rpm package.
+ Look in the source archive for platforms/contrib-rpm/rpm\_wizard.sh. This script will
+ allow you to specify build options using GNOME dialog screens. It requires zenity.
+
+\item
+ \label{faq8}
+ {\bf I just upgraded from 1.36.x to 1.38.x and now my director daemon
+won't start. It appears to start but dies silently and I get a "connection
+refused" error when starting the console. What is wrong?} Beginning with
+1.38 the rpm packages are configured to run the director and storage
+daemons as a non-root user. The file daemon runs as user root and group
+bacula, the storage daemon as user bacula and group disk, and the director
+as user bacula and group bacula. If you are upgrading you will need to
+change some file permissions for things to work. Execute the following
+commands as root:
+
+\footnotesize
+\begin{verbatim}
+ chown bacula.bacula /var/bacula/*
+ chown root.bacula /var/bacula/bacula-fd.9102.state
+ chown bacula.disk /var/bacula/bacula-sd.9103.state
+
+\end{verbatim}
+\normalsize
+
+Further, if you are using File storage volumes rather than tapes those
+files will also need to have ownership set to user bacula and group bacula.
+
+\item
+ \label{faq9}
+ {\bf There are a lot of rpm packages. Which packages do I need for
+what?} For a bacula server you need to select the packsge based upon your
+preferred catalog database: one of bacula-mysql, bacula-postgresql or
+bacula-sqlite. If your system does not provide an mtx package you also
+need bacula-mtx to satisfy that dependancy. For a client machine you need
+only install bacula-client. Optionally, for either server or client
+machines, you may install a graphical console bacula-gconsole and/or
+bacula-wxconsole. The Bacula Administration Tool is installed with the
+bacula-bat package. One last package, bacula-updatedb is required only when
+upgrading a server more than one database revision level.
+
+
+
+\item {\bf Support for RHEL3/4/5, CentOS 3/4/5, Scientific Linux 3/4/5 and x86\_64}
+ The examples below show
+ explicit build support for RHEL4 and CentOS 4. Build support
+ for x86\_64 has also been added.
+\end{enumerate}
+
+\footnotesize
+\begin{verbatim}
+Build with one of these 3 commands:
+
+rpmbuild --rebuild \
+ --define "build_rhel4 1" \
+ --define "build_sqlite 1" \
+ bacula-1.38.3-1.src.rpm
+
+rpmbuild --rebuild \
+ --define "build_rhel4 1" \
+ --define "build_postgresql 1" \
+ bacula-1.38.3-1.src.rpm
+
+rpmbuild --rebuild \
+ --define "build_rhel4 1" \
+ --define "build_mysql4 1" \
+ bacula-1.38.3-1.src.rpm
+
+For CentOS substitute '--define "build_centos4 1"' in place of rhel4.
+For Scientific Linux substitute '--define "build_sl4 1"' in place of rhel4.
+
+For 64 bit support add '--define "build_x86_64 1"'
+\end{verbatim}
+\normalsize
+
+\section{Build Options}
+\index[general]{Build Options}
+The spec file currently supports building on the following platforms:
+\footnotesize
+\begin{verbatim}
+Red Hat builds
+--define "build_rh7 1"
+--define "build_rh8 1"
+--define "build_rh9 1"
+
+Fedora Core build
+--define "build_fc1 1"
+--define "build_fc3 1"
+--define "build_fc4 1"
+--define "build_fc5 1"
+--define "build_fc6 1"
+--define "build_fc7 1"
+
+Whitebox Enterprise build
+--define "build_wb3 1"
+
+Red Hat Enterprise builds
+--define "build_rhel3 1"
+--define "build_rhel4 1"
+--define "build_rhel5 1"
+
+CentOS build
+--define "build_centos3 1"
+--define "build_centos4 1"
+--define "build_centos5 1"
+
+Scientific Linux build
+--define "build_sl3 1"
+--define "build_sl4 1"
+--define "build_sl5 1"
+
+SuSE build
+--define "build_su9 1"
+--define "build_su10 1"
+--define "build_su102 1"
+--define "build_su103 1"
+
+Mandrake 10.x build
+--define "build_mdk 1"
+
+Mandriva build
+--define "build_mdv 1"
+
+MySQL support:
+for mysql 3.23.x support define this
+--define "build_mysql 1"
+if using mysql 4.x define this,
+currently: Mandrake 10.x, Mandriva 2006.0, SuSE 9.x & 10.0, FC4 & RHEL4
+--define "build_mysql4 1"
+if using mysql 5.x define this,
+currently: SuSE 10.1 & FC5
+--define "build_mysql5 1"
+
+PostgreSQL support:
+--define "build_postgresql 1"
+
+Sqlite support:
+--define "build_sqlite 1"
+
+Build the client rpm only in place of one of the above database full builds:
+--define "build_client_only 1"
+
+X86-64 support:
+--define "build_x86_64 1"
+
+Supress build of bgnome-console:
+--define "nobuild_gconsole 1"
+
+Build the WXWindows console:
+requires wxGTK >= 2.6
+--define "build_wxconsole 1"
+
+Build the Bacula Administration Tool:
+requires QT >= 4.2
+--define "build_bat 1"
+
+Build python scripting support:
+--define "build_python 1"
+
+Modify the Packager tag for third party packages:
+--define "contrib_packager Your Name <youremail@site.org>"
+
+\end{verbatim}
+\normalsize
+
+\section{RPM Install Problems}
+\index[general]{RPM Install Problems}
+In general the RPMs, once properly built should install correctly.
+However, when attempting to run the daemons, a number of problems
+can occur:
+\begin{itemize}
+\item [Wrong /var/bacula Permissions]
+ By default, the Director and Storage daemon do not run with
+ root permission. If the /var/bacula is owned by root, then it
+ is possible that the Director and the Storage daemon will not
+ be able to access this directory, which is used as the Working
+ Directory. To fix this, the easiest thing to do is:
+\begin{verbatim}
+ chown bacula:bacula /var/bacula
+\end{verbatim}
+ Note: as of 1.38.8 /var/bacula is installed root:bacula with
+ permissions 770.
+\item [The Storage daemon cannot Access the Tape drive]
+ This can happen in some older RPM releases where the Storage
+ daemon ran under userid bacula, group bacula. There are two
+ ways of fixing this: the best is to modify the /etc/init.d/bacula-sd
+ file so that it starts the Storage daemon with group "disk".
+ The second way to fix the problem is to change the permissions
+ of your tape drive (usually /dev/nst0) so that Bacula can access it.
+ You will probably need to change the permissions of the SCSI control
+ device as well, which is usually /dev/sg0. The exact names depend
+ on your configuration, please see the Tape Testing chapter for
+ more information on devices.
+\end{itemize}
+
--- /dev/null
+/*
+ * html2latex
+ */
+
+available {
+ sun4_sunos.4
+ sun4_solaris.2
+ rs_aix.3
+ rs_aix.4
+ sgi_irix
+}
+
+description {
+ From Jeffrey Schaefer, Geometry Center. Translates HTML document to LaTeX
+}
+
+install {
+ bin/html2latex /afs/rpi.edu/dept/acs/rpinfo/filters/GChtml2latex/html2latex
+ bin/html2latex.tag /afs/rpi.edu/dept/acs/rpinfo/filters/GChtml2latex/html2latex.tag
+ bin/html2latex-local.tag /afs/rpi.edu/dept/acs/rpinfo/filters/GChtml2latex/html2latex-local.tag
+ bin/webtex2latex.tag /afs/rpi.edu/dept/acs/rpinfo/filters/GChtml2latex/webtex2latex.tag
+ man/man1/html2latex.1 /afs/rpi.edu/dept/acs/rpinfo/filters/GChtml2latex/html2latex.1
+}
--- /dev/null
+%%
+%%
+
+\chapter{Testing Your Tape Drive With Bacula}
+\label{TapeTestingChapter}
+\index[general]{Testing Your Tape Drive With Bacula}
+
+This chapter is concerned with testing and configuring your tape drive to make
+sure that it will work properly with Bacula using the {\bf btape} program.
+\label{summary}
+
+\section{Get Your Tape Drive Working}
+
+In general, you should follow the following steps to get your tape drive to
+work with Bacula. Start with a tape mounted in your drive. If you have an
+autochanger, load a tape into the drive. We use {\bf /dev/nst0} as the tape
+drive name, you will need to adapt it according to your system.
+
+Do not proceed to the next item until you have succeeded with the previous
+one.
+
+\begin{enumerate}
+\item Make sure that Bacula (the Storage daemon) is not running
+ or that you have {\bf unmount}ed the drive you will use
+ for testing.
+
+\item Use tar to write to, then read from your drive:
+
+ \footnotesize
+\begin{verbatim}
+ mt -f /dev/nst0 rewind
+ tar cvf /dev/nst0 .
+ mt -f /dev/nst0 rewind
+ tar tvf /dev/nst0
+
+\end{verbatim}
+\normalsize
+
+\item Make sure you have a valid and correct Device resource corresponding
+ to your drive. For Linux users, generally, the default one works. For
+ FreeBSD users, there are two possible Device configurations (see below).
+ For other drives and/or OSes, you will need to first ensure that your
+ system tape modes are properly setup (see below), then possibly modify
+ you Device resource depending on the output from the btape program (next
+ item). When doing this, you should consult the \ilink{Storage Daemon
+ Configuration}{StoredConfChapter} of this manual.
+
+\item If you are using a Fibre Channel to connect your tape drive to
+ Bacula, please be sure to disable any caching in the NSR (network
+ storage router, which is a Fibre Channel to SCSI converter).
+
+\item Run the btape {\bf test} command:
+
+ \footnotesize
+\begin{verbatim}
+ ./btape -c bacula-sd.conf /dev/nst0
+ test
+
+\end{verbatim}
+\normalsize
+
+ It isn't necessary to run the autochanger part of the test at this time,
+ but do not go past this point until the basic test succeeds. If you do
+ have an autochanger, please be sure to read the \ilink{Autochanger
+ chapter}{AutochangersChapter} of this manual.
+
+\item Run the btape {\bf fill} command, preferably with two volumes. This
+ can take a long time. If you have an autochanger and it is configured, Bacula
+ will automatically use it. If you do not have it configured, you can manually
+ issue the appropriate {\bf mtx} command, or press the autochanger buttons to
+ change the tape when requested to do so.
+
+\item FreeBSD users, if you have a pre-5.0 system run the {\bf tapetest}
+ program, and make sure your system is patched if necessary. The tapetest
+ program can be found in the platform/freebsd directory. The instructions
+ for its use are at the top of the file.
+
+\item Run Bacula, and backup a reasonably small directory, say 60
+ Megabytes. Do three successive backups of this directory.
+
+\item Stop Bacula, then restart it. Do another full backup of the same
+ directory. Then stop and restart Bacula.
+
+\item Do a restore of the directory backed up, by entering the following
+ restore command, being careful to restore it to an alternate location:
+
+
+\footnotesize
+\begin{verbatim}
+ restore select all done
+ yes
+
+\end{verbatim}
+\normalsize
+
+ Do a {\bf diff} on the restored directory to ensure it is identical to the
+ original directory. If you are going to backup multiple different systems
+ (Linux, Windows, Mac, Solaris, FreeBSD, ...), be sure you test the restore
+ on each system type.
+
+\item If you have an autochanger, you should now go back to the btape program
+ and run the autochanger test:
+
+\footnotesize
+\begin{verbatim}
+ ./btape -c bacula-sd.conf /dev/nst0
+ auto
+
+\end{verbatim}
+\normalsize
+
+ Adjust your autochanger as necessary to ensure that it works correctly. See
+ the Autochanger chapter of this manual for a complete discussion of testing
+ your autochanger.
+
+\item We strongly recommend that you use a dedicated SCSI
+ controller for your tape drives. Scanners are known to induce
+ serious problems with the SCSI bus, causing it to reset. If the
+ SCSI bus is reset while Bacula has the tape drive open, it will
+ most likely be fatal to your tape since the drive will rewind.
+ These kinds of problems show up in the system log. For example,
+ the following was most likely caused by a scanner:
+
+\footnotesize
+\begin{verbatim}
+Feb 14 17:29:55 epohost kernel: (scsi0:A:2:0): No or incomplete CDB sent to device.
+Feb 14 17:29:55 epohost kernel: scsi0: Issued Channel A Bus Reset. 1 SCBs aborted
+\end{verbatim}
+\normalsize
+
+\end{enumerate}
+
+If you have reached this point, you stand a good chance of having everything
+work. If you get into trouble at any point, {\bf carefully} read the
+documentation given below. If you cannot get past some point, ask the {\bf
+bacula-users} email list, but specify which of the steps you have successfully
+completed. In particular, you may want to look at the
+\ilink{ Tips for Resolving Problems}{problems1} section below.
+
+
+\label{NoTapeInDrive}
+\subsection{Problems When no Tape in Drive}
+\index[general]{Problems When no Tape in Drive}
+When Bacula was first written the Linux 2.4 kernel permitted opening the
+drive whether or not there was a tape in the drive. Thus the Bacula code is
+based on the concept that if the drive cannot be opened, there is a serious
+problem, and the job is failed.
+
+With version 2.6 of the Linux kernel, if there is no tape in the drive, the
+OS will wait two minutes (default) and then return a failure, and consequently,
+Bacula version 1.36 and below will fail the job. This is important to keep
+in mind, because if you use an option such as {\bf Offline on Unmount =
+yes}, there will be a point when there is no tape in the drive, and if
+another job starts or if Bacula asks the operator to mount a tape, when
+Bacula attempts to open the drive (about a 20 minute delay), it will fail
+and Bacula will fail the job.
+
+In version 1.38.x, the Bacula code partially gets around this problem -- at
+least in the initial open of the drive. However, functions like Polling
+the drive do not work correctly if there is no tape in the drive.
+Providing you do not use {\bf Offline on Unmount = yes}, you should not
+experience job failures as mentioned above. If you do experience such
+failures, you can also increase the {\bf Maximum Open Wait} time interval,
+which will give you more time to mount the next tape before the job is
+failed.
+
+\subsection{Specifying the Configuration File}
+\index[general]{File!Specifying the Configuration}
+\index[general]{Specifying the Configuration File}
+
+Starting with version 1.27, each of the tape utility programs including the
+{\bf btape} program requires a valid Storage daemon configuration file
+(actually, the only part of the configuration file that {\bf btape} needs is
+the {\bf Device} resource definitions). This permits {\bf btape} to find the
+configuration parameters for your archive device (generally a tape drive).
+Without those parameters, the testing and utility programs do not know how to
+properly read and write your drive. By default, they use {\bf bacula-sd.conf}
+in the current directory, but you may specify a different configuration file
+using the {\bf -c} option.
+
+\subsection{Specifying a Device Name For a Tape}
+\index[general]{Tape!Specifying a Device Name For a}
+\index[general]{Specifying a Device Name For a Tape}
+
+{\bf btape} {\bf device-name} where the Volume can be found. In the case of a
+tape, this is the physical device name such as {\bf /dev/nst0} or {\bf
+/dev/rmt/0ubn} depending on your system that you specify on the Archive Device
+directive. For the program to work, it must find the identical name in the
+Device resource of the configuration file. If the name is not found in the
+list of physical names, the utility program will compare the name you entered
+to the Device names (rather than the Archive device names).
+
+When specifying a tape device, it is preferable that the "non-rewind"
+variant of the device file name be given. In addition, on systems such as
+Sun, which have multiple tape access methods, you must be sure to specify
+to use Berkeley I/O conventions with the device. The
+{\bf b} in the Solaris (Sun) archive specification {\bf /dev/rmt/0mbn} is
+what is needed in this case. Bacula does not support SysV tape drive
+behavior.
+
+See below for specifying Volume names.
+
+\subsection{Specifying a Device Name For a File}
+\index[general]{File!Specifying a Device Name For a}
+\index[general]{Specifying a Device Name For a File}
+
+If you are attempting to read or write an archive file rather than a tape, the
+{\bf device-name} should be the full path to the archive location including
+the filename. The filename (last part of the specification) will be stripped
+and used as the Volume name, and the path (first part before the filename)
+must have the same entry in the configuration file. So, the path is equivalent
+to the archive device name, and the filename is equivalent to the volume name.
+
+
+\section{btape}
+\label{btape1}
+\index[general]{Btape}
+
+This program permits a number of elementary tape operations via a tty command
+interface. The {\bf test} command, described below, can be very useful for
+testing tape drive compatibility problems. Aside from initial testing of tape
+drive compatibility with {\bf Bacula}, {\bf btape} will be mostly used by
+developers writing new tape drivers.
+
+{\bf btape} can be dangerous to use with existing {\bf Bacula} tapes because
+it will relabel a tape or write on the tape if so requested regardless of
+whether or not the tape contains valuable data, so please be careful and use
+it only on blank tapes.
+
+To work properly, {\bf btape} needs to read the Storage daemon's configuration
+file. As a default, it will look for {\bf bacula-sd.conf} in the current
+directory. If your configuration file is elsewhere, please use the {\bf -c}
+option to specify where.
+
+The physical device name or the Device resource name must be specified on the
+command line, and this same device name must be present in the Storage
+daemon's configuration file read by {\bf btape}
+
+\footnotesize
+\begin{verbatim}
+Usage: btape [options] device_name
+ -b <file> specify bootstrap file
+ -c <file> set configuration file to file
+ -d <nn> set debug level to nn
+ -p proceed inspite of I/O errors
+ -s turn off signals
+ -v be verbose
+ -? print this message.
+\end{verbatim}
+\normalsize
+
+\subsection{Using btape to Verify your Tape Drive}
+\index[general]{Using btape to Verify your Tape Drive}
+\index[general]{Drive!Using btape to Verify your Tape}
+
+An important reason for this program is to ensure that a Storage daemon
+configuration file is defined so that Bacula will correctly read and write
+tapes.
+
+It is highly recommended that you run the {\bf test} command before running
+your first Bacula job to ensure that the parameters you have defined for your
+storage device (tape drive) will permit {\bf Bacula} to function properly. You
+only need to mount a blank tape, enter the command, and the output should be
+reasonably self explanatory. For example:
+
+\footnotesize
+\begin{verbatim}
+(ensure that Bacula is not running)
+./btape -c /usr/bin/bacula/bacula-sd.conf /dev/nst0
+\end{verbatim}
+\normalsize
+
+The output will be:
+
+\footnotesize
+\begin{verbatim}
+Tape block granularity is 1024 bytes.
+btape: btape.c:376 Using device: /dev/nst0
+*
+\end{verbatim}
+\normalsize
+
+Enter the test command:
+
+\footnotesize
+\begin{verbatim}
+test
+\end{verbatim}
+\normalsize
+
+The output produced should be something similar to the following: I've cut the
+listing short because it is frequently updated to have new tests.
+
+\footnotesize
+\begin{verbatim}
+=== Append files test ===
+This test is essential to Bacula.
+I'm going to write one record in file 0,
+ two records in file 1,
+ and three records in file 2
+btape: btape.c:387 Rewound /dev/nst0
+btape: btape.c:855 Wrote one record of 64412 bytes.
+btape: btape.c:857 Wrote block to device.
+btape: btape.c:410 Wrote EOF to /dev/nst0
+btape: btape.c:855 Wrote one record of 64412 bytes.
+btape: btape.c:857 Wrote block to device.
+btape: btape.c:855 Wrote one record of 64412 bytes.
+btape: btape.c:857 Wrote block to device.
+btape: btape.c:410 Wrote EOF to /dev/nst0
+btape: btape.c:855 Wrote one record of 64412 bytes.
+btape: btape.c:857 Wrote block to device.
+btape: btape.c:855 Wrote one record of 64412 bytes.
+btape: btape.c:857 Wrote block to device.
+btape: btape.c:855 Wrote one record of 64412 bytes.
+btape: btape.c:857 Wrote block to device.
+btape: btape.c:410 Wrote EOF to /dev/nst0
+btape: btape.c:387 Rewound /dev/nst0
+btape: btape.c:693 Now moving to end of media.
+btape: btape.c:427 Moved to end of media
+We should be in file 3. I am at file 3. This is correct!
+Now the important part, I am going to attempt to append to the tape.
+...
+=== End Append files test ===
+\end{verbatim}
+\normalsize
+
+If you do not successfully complete the above test, please resolve the
+problem(s) before attempting to use {\bf Bacula}. Depending on your tape
+drive, the test may recommend that you add certain records to your
+configuration. We strongly recommend that you do so and then re-run the above
+test to insure it works the first time.
+
+Some of the suggestions it provides for resolving the problems may or may not
+be useful. If at all possible avoid using fixed blocking. If the test suddenly
+starts to print a long series of:
+
+\footnotesize
+\begin{verbatim}
+Got EOF on tape.
+Got EOF on tape.
+...
+\end{verbatim}
+\normalsize
+
+then almost certainly, you are running your drive in fixed block mode rather
+than variable block mode. See below for more help of resolving fix
+versus variable block problems.
+
+It is also possible that you have your drive
+set in SysV tape drive mode. The drive must use BSD tape conventions.
+See the section above on setting your {\bf Archive device} correctly.
+
+For FreeBSD users, please see the notes below for doing further testing of
+your tape drive.
+
+\label{SCSITricks}
+\subsection{Linux SCSI Tricks}
+\index[general]{Tricks!Linux SCSI}
+\index[general]{Linux SCSI Tricks}
+
+You can find out what SCSI devices you have by doing:
+
+\footnotesize
+\begin{verbatim}
+lsscsi
+\end{verbatim}
+\normalsize
+
+Typical output is:
+
+\footnotesize
+\begin{verbatim}
+[0:0:0:0] disk ATA ST3160812AS 3.AD /dev/sda
+[2:0:4:0] tape HP Ultrium 2-SCSI F6CH /dev/st0
+[2:0:5:0] tape HP Ultrium 2-SCSI F6CH /dev/st1
+[2:0:6:0] mediumx OVERLAND LXB 0107 -
+[2:0:9:0] tape HP Ultrium 1-SCSI E50H /dev/st2
+[2:0:10:0] mediumx OVERLAND LXB 0107 -
+\end{verbatim}
+\normalsize
+
+There are two drives in one autochanger: /dev/st0 and /dev/st1
+and a third tape drive at /dev/st2. For using them with Bacula, one
+would normally reference them as /dev/nst0 ... /dev/nst2. Not also,
+there are two different autochangers identified as "mediumx OVERLAND LXB".
+They can be addressed via their /dev/sgN designation, which can be
+obtained by counting from the beginning as 0 to each changer. In the
+above case, the two changers are located on /dev/sg3 and /dev/sg5. The one
+at /dev/sg3, controls drives /dev/nst0 and /dev/nst1; and the one at
+/dev/sg5 controles drive /dev/nst2.
+
+If you do not have the {\bf lsscsi} command, you can obtain the same
+information as follows:
+
+\footnotesize
+\begin{verbatim}
+cat /proc/scsi/scsi
+\end{verbatim}
+\normalsize
+
+For the above example with the three drives and two autochangers,
+I get:
+
+\footnotesize
+\begin{verbatim}
+Attached devices:
+Host: scsi0 Channel: 00 Id: 00 Lun: 00
+ Vendor: ATA Model: ST3160812AS Rev: 3.AD
+ Type: Direct-Access ANSI SCSI revision: 05
+Host: scsi2 Channel: 00 Id: 04 Lun: 00
+ Vendor: HP Model: Ultrium 2-SCSI Rev: F6CH
+ Type: Sequential-Access ANSI SCSI revision: 03
+Host: scsi2 Channel: 00 Id: 05 Lun: 00
+ Vendor: HP Model: Ultrium 2-SCSI Rev: F6CH
+ Type: Sequential-Access ANSI SCSI revision: 03
+Host: scsi2 Channel: 00 Id: 06 Lun: 00
+ Vendor: OVERLAND Model: LXB Rev: 0107
+ Type: Medium Changer ANSI SCSI revision: 02
+Host: scsi2 Channel: 00 Id: 09 Lun: 00
+ Vendor: HP Model: Ultrium 1-SCSI Rev: E50H
+ Type: Sequential-Access ANSI SCSI revision: 03
+Host: scsi2 Channel: 00 Id: 10 Lun: 00
+ Vendor: OVERLAND Model: LXB Rev: 0107
+ Type: Medium Changer ANSI SCSI revision: 02
+\end{verbatim}
+\normalsize
+
+
+As an additional example, I get the following (on a different machine from the
+above example):
+
+\footnotesize
+\begin{verbatim}
+Attached devices:
+Host: scsi2 Channel: 00 Id: 01 Lun: 00
+ Vendor: HP Model: C5713A Rev: H107
+ Type: Sequential-Access ANSI SCSI revision: 02
+Host: scsi2 Channel: 00 Id: 04 Lun: 00
+ Vendor: SONY Model: SDT-10000 Rev: 0110
+ Type: Sequential-Access ANSI SCSI revision: 02
+\end{verbatim}
+\normalsize
+
+The above represents first an autochanger and second a simple
+tape drive. The HP changer (the first entry) uses the same SCSI channel
+for data and for control, so in Bacula, you would use:
+\footnotesize
+\begin{verbatim}
+Archive Device = /dev/nst0
+Changer Device = /dev/sg0
+\end{verbatim}
+\normalsize
+
+If you want to remove the SDT-10000 device, you can do so as root with:
+
+\footnotesize
+\begin{verbatim}
+echo "scsi remove-single-device 2 0 4 0">/proc/scsi/scsi
+\end{verbatim}
+\normalsize
+
+and you can put add it back with:
+
+\footnotesize
+\begin{verbatim}
+echo "scsi add-single-device 2 0 4 0">/proc/scsi/scsi
+\end{verbatim}
+\normalsize
+
+where the 2 0 4 0 are the Host, Channel, Id, and Lun as seen on the output
+from {\bf cat /proc/scsi/scsi}. Note, the Channel must be specified as
+numeric.
+
+Below is a slightly more complicated output, which is a single autochanger
+with two drives, and which operates the changer on a different channel
+from from the drives:
+
+\footnotesize
+\begin{verbatim}
+Attached devices:
+Host: scsi0 Channel: 00 Id: 00 Lun: 00
+ Vendor: ATA Model: WDC WD1600JD-75H Rev: 08.0
+ Type: Direct-Access ANSI SCSI revision: 05
+Host: scsi2 Channel: 00 Id: 04 Lun: 00
+ Vendor: HP Model: Ultrium 2-SCSI Rev: F6CH
+ Type: Sequential-Access ANSI SCSI revision: 03
+Host: scsi2 Channel: 00 Id: 05 Lun: 00
+ Vendor: HP Model: Ultrium 2-SCSI Rev: F6CH
+ Type: Sequential-Access ANSI SCSI revision: 03
+Host: scsi2 Channel: 00 Id: 06 Lun: 00
+ Vendor: OVERLAND Model: LXB Rev: 0106
+ Type: Medium Changer ANSI SCSI revision: 02
+\end{verbatim}
+\normalsize
+
+The above tape drives are accessed on /dev/nst0 and /dev/nst1, while
+the control channel for those two drives is /dev/sg3.
+
+
+
+\label{problems1}
+\section{Tips for Resolving Problems}
+\index[general]{Problems!Tips for Resolving}
+\index[general]{Tips for Resolving Problems}
+
+\label{CannotRestore}
+\subsection{Bacula Saves But Cannot Restore Files}
+\index[general]{Files!Bacula Saves But Cannot Restore}
+\index[general]{Bacula Saves But Cannot Restore Files}
+
+If you are getting error messages such as:
+
+\footnotesize
+\begin{verbatim}
+Volume data error at 0:1! Wanted block-id: "BB02", got "". Buffer discarded
+\end{verbatim}
+\normalsize
+
+It is very likely that Bacula has tried to do block positioning and ended up
+at an invalid block. This can happen if your tape drive is in fixed block mode
+while Bacula's default is variable blocks. Note that in such cases, Bacula is
+perfectly able to write to your Volumes (tapes), but cannot position to read
+them.
+
+There are two possible solutions.
+
+\begin{enumerate}
+\item The first and best is to always ensure that your drive is in variable
+ block mode. Note, it can switch back to fixed block mode on a reboot or if
+ another program uses the drive. So on such systems you need to modify the
+ Bacula startup files to explicitly set:
+
+\footnotesize
+\begin{verbatim}
+mt -f /dev/nst0 defblksize 0
+\end{verbatim}
+\normalsize
+
+or whatever is appropriate on your system. Note, if you are running a Linux
+system, and the above command does not work, it is most likely because you
+have not loaded the appropriate {\bf mt} package, which is often called
+{\bf mt\_st}, but may differ according to your distribution.
+
+\item The second possibility, especially, if Bacula wrote while the drive was
+ in fixed block mode, is to turn off block positioning in Bacula. This is done
+ by adding:
+
+\footnotesize
+\begin{verbatim}
+Block Positioning = no
+\end{verbatim}
+\normalsize
+
+to the Device resource. This is not the recommended procedure because it can
+enormously slow down recovery of files, but it may help where all else
+fails. This directive is available in version 1.35.5 or later (and not yet
+tested).
+\end{enumerate}
+
+If you are getting error messages such as:
+\footnotesize
+\begin{verbatim}
+Volume data error at 0:0!
+Block checksum mismatch in block=0 len=32625 calc=345678 blk=123456
+\end{verbatim}
+\normalsize
+
+You are getting tape read errors, and this is most likely due to
+one of the following things:
+\begin{enumerate}
+\item An old or bad tape.
+\item A dirty drive that needs cleaning (particularly for DDS drives).
+\item A loose SCSI cable.
+\item Old firmware in your drive. Make sure you have the latest firmware
+ loaded.
+\item Computer memory errors.
+\item Over-clocking your CPU.
+\item A bad SCSI card.
+\end{enumerate}
+
+
+\label{opendevice}
+\subsection{Bacula Cannot Open the Device}
+\index[general]{Device!Bacula Cannot Open the}
+\index[general]{Bacula Cannot Open the Device}
+
+If you get an error message such as:
+
+\footnotesize
+\begin{verbatim}
+dev open failed: dev.c:265 stored: unable to open
+device /dev/nst0:> ERR=No such device or address
+\end{verbatim}
+\normalsize
+
+the first time you run a job, it is most likely due to the fact that you
+specified the incorrect device name on your {\bf Archive Device}.
+
+If Bacula works fine with your drive, then all off a sudden you get error
+messages similar to the one shown above, it is quite possible that your driver
+module is being removed because the kernel deems it idle. This is done via
+{\bf crontab} with the use of {\bf rmmod -a}. To fix the problem, you can
+remove this entry from {\bf crontab}, or you can manually {\bf modprob} your
+driver module (or add it to the local startup script). Thanks to Alan Brown
+for this tip.
+\label{IncorrectFiles}
+
+\subsection{Incorrect File Number}
+\index[general]{Number!Incorrect File}
+\index[general]{Incorrect File Number}
+
+When Bacula moves to the end of the medium, it normally uses the {\bf
+ioctl(MTEOM)} function. Then Bacula uses the {\bf ioctl(MTIOCGET)} function to
+retrieve the current file position from the {\bf mt\_fileno} field. Some SCSI
+tape drivers will use a fast means of seeking to the end of the medium and in
+doing so, they will not know the current file position and hence return a {\bf
+-1}. As a consequence, if you get {\bf "This is NOT correct!"} in the
+positioning tests, this may be the cause. You must correct this condition in
+order for Bacula to work.
+
+There are two possible solutions to the above problem of incorrect file
+number:
+
+\begin{itemize}
+\item Figure out how to configure your SCSI driver to keep track of the file
+ position during the MTEOM request. This is the preferred solution.
+\item Modify the {\bf Device} resource of your {\bf bacula-sd.conf} file to
+ include:
+
+\footnotesize
+\begin{verbatim}
+Hardware End of File = no
+\end{verbatim}
+\normalsize
+
+This will cause Bacula to use the MTFSF request to seek to the end of the
+medium, and Bacula will keep track of the file number itself.
+\end{itemize}
+
+\label{IncorrectBlocks}
+\subsection{Incorrect Number of Blocks or Positioning Errors}
+\index[general]{Testing!Incorrect Number of Blocks or Positioning Errors}
+\index[general]{Incorrect Number of Blocks or Positioning Errors}
+
+{\bf Bacula's} preferred method of working with tape drives (sequential
+devices) is to run in variable block mode, and this is what is set by default.
+You should first ensure that your tape drive is set for variable block mode
+(see below).
+
+If your tape drive is in fixed block mode and you have told Bacula to use
+different fixed block sizes or variable block sizes (default), you will get
+errors when Bacula attempts to forward space to the correct block (the kernel
+driver's idea of tape blocks will not correspond to Bacula's).
+
+All modern tape drives support variable tape blocks, but some older drives (in
+particular the QIC drives) as well as the ATAPI ide-scsi driver run only in
+fixed block mode. The Travan tape drives also apparently must run in fixed
+block mode (to be confirmed).
+
+Even in variable block mode, with the exception of the first record on the
+second or subsequent volume of a multi-volume backup, Bacula will write blocks
+of a fixed size. However, in reading a tape, Bacula will assume that for each
+read request, exactly one block from the tape will be transferred. This the
+most common way that tape drives work and is well supported by {\bf Bacula}.
+
+Drives that run in fixed block mode can cause serious problems for Bacula if
+the drive's block size does not correspond exactly to {\bf Bacula's} block
+size. In fixed block size mode, drivers may transmit a partial block or
+multiple blocks for a single read request. From {\bf Bacula's} point of view,
+this destroys the concept of tape blocks. It is much better to run in variable
+block mode, and almost all modern drives (the OnStream is an exception) run in
+variable block mode. In order for Bacula to run in fixed block mode, you must
+include the following records in the Storage daemon's Device resource
+definition:
+
+\footnotesize
+\begin{verbatim}
+Minimum Block Size = nnn
+Maximum Block Size = nnn
+\end{verbatim}
+\normalsize
+
+where {\bf nnn} must be the same for both records and must be identical to the
+driver's fixed block size.
+
+We recommend that you avoid this configuration if at all possible by using
+variable block sizes.
+
+If you must run with fixed size blocks, make sure they are not 512 bytes. This
+is too small and the overhead that Bacula has with each record will become
+excessive. If at all possible set any fixed block size to something like
+64,512 bytes or possibly 32,768 if 64,512 is too large for your drive. See
+below for the details on checking and setting the default drive block size.
+
+To recover files from tapes written in fixed block mode, see below.
+
+\label{TapeModes}
+\subsection{Ensuring that the Tape Modes Are Properly Set -- {\bf Linux
+Only}}
+\index[general]{Ensuring that the Tape Modes Are Properly Set -- Linux Only}
+
+If you have a modern SCSI tape drive and you are having problems with the {\bf
+test} command as noted above, it may be that some program has set one or more
+of your SCSI driver's options to non-default values. For example, if your
+driver is set to work in SysV manner, Bacula will not work correctly because
+it expects BSD behavior. To reset your tape drive to the default values, you
+can try the following, but {\bf ONLY} if you have a SCSI tape drive on a {\bf
+Linux} system:
+
+\footnotesize
+\begin{verbatim}
+become super user
+mt -f /dev/nst0 rewind
+mt -f /dev/nst0 stoptions buffer-writes async-writes read-ahead
+\end{verbatim}
+\normalsize
+
+The above commands will clear all options and then set those specified. None
+of the specified options are required by Bacula, but a number of other options
+such as SysV behavior must not be set. Bacula does not support SysV tape
+behavior. On systems other than Linux, you will need to consult your {\bf mt}
+man pages or documentation to figure out how to do the same thing. This should
+not really be necessary though -- for example, on both Linux and Solaris
+systems, the default tape driver options are compatible with Bacula.
+On Solaris systems, you must take care to specify the correct device
+name on the {\bf Archive device} directive. See above for more details.
+
+You may also want to ensure that no prior program has set the default block
+size, as happened to one user, by explicitly turning it off with:
+
+\footnotesize
+\begin{verbatim}
+mt -f /dev/nst0 defblksize 0
+\end{verbatim}
+\normalsize
+
+If you are running a Linux
+system, and the above command does not work, it is most likely because you
+have not loaded the appropriate {\bf mt} package, which is often called
+{\bf mt\_st}, but may differ according to your distribution.
+
+If you would like to know what options you have set before making any of the
+changes noted above, you can now view them on Linux systems, thanks to a tip
+provided by Willem Riede. Do the following:
+
+\footnotesize
+\begin{verbatim}
+become super user
+mt -f /dev/nst0 stsetoptions 0
+grep st0 /var/log/messages
+\end{verbatim}
+\normalsize
+
+and you will get output that looks something like the following:
+
+\footnotesize
+\begin{verbatim}
+kernel: st0: Mode 0 options: buffer writes: 1, async writes: 1, read ahead: 1
+kernel: st0: can bsr: 0, two FMs: 0, fast mteom: 0, auto lock: 0,
+kernel: st0: defs for wr: 0, no block limits: 0, partitions: 0, s2 log: 0
+kernel: st0: sysv: 0 nowait: 0
+\end{verbatim}
+\normalsize
+
+Note, I have chopped off the beginning of the line with the date and machine
+name for presentation purposes.
+
+Some people find that the above settings only last until the next reboot, so
+please check this otherwise you may have unexpected problems.
+
+Beginning with Bacula version 1.35.8, if Bacula detects that you are running
+in variable block mode, it will attempt to set your drive appropriately. All
+OSes permit setting variable block mode, but some OSes do not permit setting
+the other modes that Bacula needs to function properly.
+
+\label{compression}
+\subsection{Tape Hardware Compression and Blocking Size}
+\index[general]{Tape Hardware Compression and Blocking Size}
+\index[general]{Size!Tape Hardware Compression and Blocking Size}
+
+As far as I can tell, there is no way with the {\bf mt} program to check if
+your tape hardware compression is turned on or off. You can, however, turn it
+on by using (on Linux):
+
+\footnotesize
+\begin{verbatim}
+become super user
+mt -f /dev/nst0 defcompression 1
+\end{verbatim}
+\normalsize
+
+and of course, if you use a zero instead of the one at the end, you will turn
+it off.
+
+If you have built the {\bf mtx} program in the {\bf depkgs} package, you can
+use tapeinfo to get quite a bit of information about your tape drive even if
+it is not an autochanger. This program is called using the SCSI control
+device. On Linux for tape drive /dev/nst0, this is usually /dev/sg0, while on
+FreeBSD for /dev/nsa0, the control device is often /dev/pass2. For example on
+my DDS-4 drive (/dev/nst0), I get the following:
+
+\footnotesize
+\begin{verbatim}
+tapeinfo -f /dev/sg0
+Product Type: Tape Drive
+Vendor ID: 'HP '
+Product ID: 'C5713A '
+Revision: 'H107'
+Attached Changer: No
+MinBlock:1
+MaxBlock:16777215
+SCSI ID: 5
+SCSI LUN: 0
+Ready: yes
+BufferedMode: yes
+Medium Type: Not Loaded
+Density Code: 0x26
+BlockSize: 0
+\end{verbatim}
+\normalsize
+
+where the {\bf DataCompEnabled: yes} means that tape hardware compression is
+turned on. You can turn it on and off (yes|no) by using the {\bf mt}
+commands given above. Also, this output will tell you if the {\bf BlockSize}
+is non-zero and hence set for a particular block size. Bacula is not likely to
+work in such a situation because it will normally attempt to write blocks of
+64,512 bytes, except the last block of the job which will generally be
+shorter. The first thing to try is setting the default block size to zero
+using the {\bf mt -f /dev/nst0 defblksize 0} command as shown above.
+On FreeBSD, this would be something like: {\bf mt -f /dev/nsa0 blocksize 0}.
+
+On some operating systems with some tape drives, the amount of data that
+can be written to the tape and whether or not compression is enabled is
+determined by the density usually the {\bf mt -f /dev/nst0 setdensity xxx} command.
+Often {\bf mt -f /dev/nst0 status} will print out the current
+density code that is used with the drive. Most systems, but unfortunately
+not all, set the density to the maximum by default. On some systems, you
+can also get a list of all available density codes with:
+{\bf mt -f /dev/nst0 densities} or a similar {\bf mt} command.
+Note, for DLT and SDLT devices, no-compression versus compression is very
+often controlled by the density code. On FreeBSD systems, the compression
+mode is set using {\bf mt -f /dev/nsa0 comp xxx} where xxx is the
+mode you want. In general, see {\bf man mt} for the options available on
+your system.
+
+Note, some of the above {\bf mt} commands may not be persistent depending
+on your system configuration. That is they may be reset if a program
+other than Bacula uses the drive or, as is frequently the case, on reboot
+of your system.
+
+If your tape drive requires fixed block sizes (very unusual), you can use the
+following records:
+
+\footnotesize
+\begin{verbatim}
+Minimum Block Size = nnn
+Maximum Block Size = nnn
+\end{verbatim}
+\normalsize
+
+in your Storage daemon's Device resource to force Bacula to write fixed size
+blocks (where you sent nnn to be the same for both of the above records). This
+should be done only if your drive does not support variable block sizes, or
+you have some other strong reasons for using fixed block sizes. As mentioned
+above, a small fixed block size of 512 or 1024 bytes will be very inefficient.
+Try to set any fixed block size to something like 64,512 bytes or larger if
+your drive will support it.
+
+Also, note that the {\bf Medium Type} field of the output of {\bf tapeinfo}
+reports {\bf Not Loaded}, which is not correct. As a consequence, you should
+ignore that field as well as the {\bf Attached Changer} field.
+
+To recover files from tapes written in fixed block mode, see below.
+\label{FreeBSDTapes}
+
+\subsection{Tape Modes on FreeBSD}
+\index[general]{FreeBSD!Tape Modes on}
+\index[general]{Tape Modes on FreeBSD}
+
+On most FreeBSD systems such as 4.9 and most tape drives, Bacula should run
+with:
+
+\footnotesize
+\begin{verbatim}
+mt -f /dev/nsa0 seteotmodel 2
+mt -f /dev/nsa0 blocksize 0
+mt -f /dev/nsa0 comp enable
+\end{verbatim}
+\normalsize
+
+You might want to put those commands in a startup script to make sure your
+tape driver is properly initialized before running Bacula, because
+depending on your system configuration, these modes may be reset if a
+program other than Bacula uses the drive or when your system is rebooted.
+
+Then according to what the {\bf btape test} command returns, you will probably
+need to set the following (see below for an alternative):
+
+\footnotesize
+\begin{verbatim}
+ Hardware End of Medium = no
+ BSF at EOM = yes
+ Backward Space Record = no
+ Backward Space File = no
+ Fast Forward Space File = no
+ TWO EOF = yes
+\end{verbatim}
+\normalsize
+
+Then be sure to run some append tests with Bacula where you start and stop
+Bacula between appending to the tape, or use {\bf btape} version 1.35.1 or
+greater, which includes simulation of stopping/restarting Bacula.
+
+Please see the file {\bf platforms/freebsd/pthreads-fix.txt} in the main
+Bacula directory concerning {\bf important} information concerning
+compatibility of Bacula and your system. A much more optimal Device
+configuration is shown below, but does not work with all tape drives. Please
+test carefully before putting either into production.
+
+Note, for FreeBSD 4.10-RELEASE, using a Sony TSL11000 L100 DDS4 with an
+autochanger set to variable block size and DCLZ compression, Brian McDonald
+reports that to get Bacula to append correctly between Bacula executions,
+the correct values to use are:
+
+\footnotesize
+\begin{verbatim}
+mt -f /dev/nsa0 seteotmodel 1
+mt -f /dev/nsa0 blocksize 0
+mt -f /dev/nsa0 comp enable
+\end{verbatim}
+\normalsize
+
+and
+
+\footnotesize
+\begin{verbatim}
+ Hardware End of Medium = no
+ BSF at EOM = no
+ Backward Space Record = no
+ Backward Space File = no
+ Fast Forward Space File = yes
+ TWO EOF = no
+\end{verbatim}
+\normalsize
+
+This has been confirmed by several other people using different hardware. This
+configuration is the preferred one because it uses one EOF and no backspacing
+at the end of the tape, which works much more efficiently and reliably with
+modern tape drives.
+
+Finally, here is a Device configuration that Danny Butroyd reports to work
+correctly with the Overland Powerloader tape library using LT0-2 and
+FreeBSD 5.4-Stable:
+
+\footnotesize
+\begin{verbatim}
+# Overland Powerloader LT02 - 17 slots single drive
+Device {
+ Name = Powerloader
+ Media Type = LT0-2
+ Archive Device = /dev/nsa0
+ AutomaticMount = yes;
+ AlwaysOpen = yes;
+ RemovableMedia = yes;
+ RandomAccess = no;
+ Changer Command = "/usr/local/sbin/mtx-changer %c %o %S %a %d"
+ Changer Device = /dev/pass2
+ AutoChanger = yes
+ Alert Command = "sh -c 'tapeinfo -f %c |grep TapeAlert|cat'"
+
+ # FreeBSD Specific Settings
+ Offline On Unmount = no
+ Hardware End of Medium = no
+ BSF at EOM = yes
+ Backward Space Record = no
+ Fast Forward Space File = no
+ TWO EOF = yes
+}
+
+The following Device resource works fine with Dell PowerVault 110T and
+120T devices on both FreeBSD 5.3 and on NetBSD 3.0. It also works
+with Sony AIT-2 drives on FreeBSD.
+\footnotesize
+\begin{verbatim}
+Device {
+ ...
+ # FreeBSD/NetBSD Specific Settings
+ Hardware End of Medium = no
+ BSF at EOM = yes
+ Backward Space Record = no
+ Fast Forward Space File = yes
+ TWO EOF = yes
+}
+\end{verbatim}
+\normalsize
+
+On FreeBSD version 6.0, it is reported that you can even set
+Backward Space Record = yes.
+
+
+
+\subsection{Finding your Tape Drives and Autochangers on FreeBSD}
+\index[general]{FreeBSD!Finding Tape Drives and Autochangers}
+\index[general]{Finding Tape Drives and Autochangers on FreeBSD}
+
+On FreeBSD, you can do a {\bf camcontrol devlist} as root to determine what
+drives and autochangers you have. For example,
+
+\footnotesize
+\begin{verbatim}
+undef# camcontrol devlist
+ at scbus0 target 2 lun 0 (pass0,sa0)
+ at scbus0 target 4 lun 0 (pass1,sa1)
+ at scbus0 target 4 lun 1 (pass2)
+\end{verbatim}
+\normalsize
+
+from the above, you can determine that there is a tape drive on {\bf /dev/sa0}
+and another on {\bf /dev/sa1} in addition since there is a second line for the
+drive on {\bf /dev/sa1}, you know can assume that it is the control device for
+the autochanger (i.e. {\bf /dev/pass2}). It is also the control device name to
+use when invoking the tapeinfo program. E.g.
+
+\footnotesize
+\begin{verbatim}
+tapeinfo -f /dev/pass2
+\end{verbatim}
+\normalsize
+
+\label{onstream}
+
+\subsection{Using the OnStream driver on Linux Systems}
+\index[general]{Using the OnStream driver on Linux Systems}
+\index[general]{Systems!Using the OnStream driver on Linux}
+
+Bacula version 1.33 (not 1.32x) is now working and ready for testing with the
+OnStream kernel osst driver version 0.9.14 or above. Osst is available from:
+\elink{http://sourceforge.net/projects/osst/}
+{http://sourceforge.net/projects/osst/}.
+
+To make Bacula work you must first load the new driver then, as root, do:
+
+\footnotesize
+\begin{verbatim}
+ mt -f /dev/nosst0 defblksize 32768
+\end{verbatim}
+\normalsize
+
+Also you must add the following to your Device resource in your Storage
+daemon's conf file:
+
+\footnotesize
+\begin{verbatim}
+ Minimum Block Size = 32768
+ Maximum Block Size = 32768
+\end{verbatim}
+\normalsize
+
+Here is a Device specification provided by Michel Meyers that is known to
+work:
+
+\footnotesize
+\begin{verbatim}
+Device {
+ Name = "Onstream DI-30"
+ Media Type = "ADR-30"
+ Archive Device = /dev/nosst0
+ Minimum Block Size = 32768
+ Maximum Block Size = 32768
+ Hardware End of Medium = yes
+ BSF at EOM = no
+ Backward Space File = yes
+ Fast Forward Space File = yes
+ Two EOF = no
+ AutomaticMount = yes
+ AlwaysOpen = yes
+ Removable Media = yes
+}
+\end{verbatim}
+\normalsize
+
+\section{Hardware Compression on EXB-8900}
+\index[general]{Hardware Compression on EXB-8900}
+\index[general]{EXB-8900!Hardware Compression}
+
+To active, check, or disable the hardware compression feature
+on an EXB-8900, use the exabyte MammothTool. You can get it here:
+\elink{http://www.exabyte.com/support/online/downloads/index.cfm}
+{http://www.exabyte.com/support/online/downloads/index.cfm}.
+There is a Solaris version of this tool. With option -C 0 or 1 you
+can disable or activate compression. Start this tool without any
+options for a small reference.
+
+\label{fill}
+\subsection{Using btape to Simulate Filling a Tape}
+\index[general]{Using btape to Simulate Filling a Tape}
+\index[general]{Tape!Using btape to Simulate Filling}
+
+Because there are often problems with certain tape drives or systems when end
+of tape conditions occur, {\bf btape} has a special command {\bf fill} that
+causes it to write random data to a tape until the tape fills. It then writes
+at least one more Bacula block to a second tape. Finally, it reads back both
+tapes to ensure that the data has been written in a way that Bacula can
+recover it. Note, there is also a single tape option as noted below, which you
+should use rather than the two tape test. See below for more details.
+
+This can be an extremely time consuming process (here it is about 6 hours) to
+fill a full tape. Note, that btape writes random data to the tape when it is
+filling it. This has two consequences: 1. it takes a bit longer to generate
+the data, especially on slow CPUs. 2. the total amount of data is
+approximately the real physical capacity of your tape, regardless of whether
+or not the tape drive compression is on or off. This is because random data
+does not compress very much.
+
+To begin this test, you enter the {\bf fill} command and follow the
+instructions. There are two options: the simple single tape option and the
+multiple tape option. Please use only the simple single tape option because
+the multiple tape option still doesn't work totally correctly. If the single
+tape option does not succeed, you should correct the problem before using
+Bacula.
+\label{RecoveringFiles}
+
+\section{Recovering Files Written With Fixed Block Sizes}
+\index[general]{Recovering Files Written With Fixed Block Sizes}
+
+If you have been previously running your tape drive in fixed block mode
+(default 512) and Bacula with variable blocks (default), then in version
+1.32f-x and 1.34 and above, Bacula will fail to recover files because it does
+block spacing, and because the block sizes don't agree between your tape drive
+and Bacula it will not work.
+
+The long term solution is to run your drive in variable block mode as
+described above. However, if you have written tapes using fixed block sizes,
+this can be a bit of a pain. The solution to the problem is: while you are
+doing a restore command using a tape written in fixed block size, ensure that
+your drive is set to the fixed block size used while the tape was written.
+Then when doing the {\bf restore} command in the Console program, do not
+answer the prompt {\bf yes/mod/no}. Instead, edit the bootstrap file (the
+location is listed in the prompt) using any ASCII editor. Remove all {\bf
+VolBlock} lines in the file. When the file is re-written, answer the question,
+and Bacula will run without using block positioning, and it should recover
+your files.
+
+\label{BlockModes}
+\section{Tape Blocking Modes}
+\index[general]{Modes!Tape Blocking}
+\index[general]{Tape Blocking Modes}
+
+SCSI tapes may either be written in {\bf variable} or {\bf fixed} block sizes.
+Newer drives support both modes, but some drives such as the QIC devices
+always use fixed block sizes. Bacula attempts to fill and write complete
+blocks (default 65K), so that in normal mode (variable block size), Bacula
+will always write blocks of the same size except the last block of a Job. If
+Bacula is configured to write fixed block sizes, it will pad the last block of
+the Job to the correct size. Bacula expects variable tape block size drives to
+behave as follows: Each write to the drive results in a single record being
+written to the tape. Each read returns a single record. If you request less
+bytes than are in the record, only those number of bytes will be returned, but
+the entire logical record will have been read (the next read will retrieve the
+next record). Thus data from a single write is always returned in a single
+read, and sequentially written records are returned by sequential reads.
+
+Bacula expects fixed block size tape drives to behave as follows: If a write
+length is greater than the physical block size of the drive, the write will be
+written as two blocks each of the fixed physical size. This single write may
+become multiple physical records on the tape. (This is not a good situation).
+According to the documentation, one may never write an amount of data that is
+not the exact multiple of the blocksize (it is not specified if an error
+occurs or if the the last record is padded). When reading, it is my
+understanding that each read request reads one physical record from the tape.
+Due to the complications of fixed block size tape drives, you should avoid
+them if possible with Bacula, or you must be ABSOLUTELY certain that you use
+fixed block sizes within Bacula that correspond to the physical block size of
+the tape drive. This will ensure that Bacula has a one to one correspondence
+between what it writes and the physical record on the tape.
+
+Please note that Bacula will not function correctly if it writes a block and
+that block is split into two or more physical records on the tape. Bacula
+assumes that each write causes a single record to be written, and that it can
+sequentially recover each of the blocks it has written by using the same
+number of sequential reads as it had written.
+
+\section{Details of Tape Modes}
+\index[general]{Modes!Details}
+\index[general]{Details of Tape Modes}
+Rudolf Cejka has provided the following information concerning
+certain tape modes and MTEOM.
+
+\begin{description}
+\item[Tape level]
+ It is always possible to position filemarks or blocks, whereas
+ positioning to the end-of-data is only optional feature, however it is
+ implemented very often. SCSI specification also talks about optional
+ sequential filemarks, setmarks and sequential setmarks, but these are not
+ implemented so often. Modern tape drives keep track of file positions in
+ built-in chip (AIT, LTO) or at the beginning of the tape (SDLT), so there
+ is not any speed difference, if end-of-data or filemarks is used (I have
+ heard, that LTO-1 from all 3 manufacturers do not use its chip for file
+ locations, but a tape as in SDLT case, and I'm not sure about LTO-2 and
+ LTO-3 case). However there is a big difference, that end-of-data ignores
+ file position, whereas filemarks returns the real number of skipped
+ files, so OS can track current file number just in filemarks case.
+
+\item[OS level]
+ Solaris does use just SCSI SPACE Filemarks, it does not support SCSI
+ SPACE End-of-data. When MTEOM is called, Solaris does use SCSI SPACE
+ Filemarks with count = 1048576 for fast mode, and combination of SCSI
+ SPACE Filemarks with count = 1 with SCSI SPACE Blocks with count = 1 for
+ slow mode, so EOD mark on the tape on some older tape drives is not
+ skipped. File number is always tracked for MTEOM.
+
+ Linux does support both SCSI SPACE Filemarks and End-of-data: When MTEOM
+ is called in MT\_ST\_FAST\_MTEOM mode, SCSI SPACE End-of-data is used.
+ In the other case, SCSI SPACE Filemarks with count =
+ 8388607 is used.
+ There is no real slow mode like in Solaris - I just expect, that for
+ older tape drives Filemarks may be slower than End-of-data, but not so
+ much as in Solaris slow mode. File number is tracked for MTEOM just
+ without MT\_ST\_FAST\_MTEOM - when MT\_ST\_FAST\_MTEOM is used, it is not.
+
+ FreeBSD does support both SCSI SPACE Filemarks and End-of-data, but when
+ MTEOD (MTEOM) is called, SCSI SPACE End-of-data is always used. FreeBSD
+ never use SCSI SPACE Filemarks for MTEOD. File number is never tracked
+ for MTEOD.
+
+\item[Bacula level]
+ When {\bf Hardware End of Medium = Yes} is used, MTEOM is called, but it
+ does not mean, that hardware End-of-data must be used. When Hardware End
+ of Medium = No, if Fast Forward Space File = Yes, MTFSF with count =
+ 32767 is used, else Block Read with count = 1 with Forward Space File
+ with count = 1 is used, which is really very slow.
+
+\item [Hardware End of Medium = Yes|No]
+ The name of this option is misleading and is the source of confusion,
+ because it is not the hardware EOM, what is really switched here.
+
+ If I use Yes, OS must not use SCSI SPACE End-of-data, because Bacula
+ expects, that there is tracked file number, which is not supported by
+ SCSI specification. Instead, the OS have to use SCSI SPACE Filemarks.
+
+ If I use No, an action depends on Fast Forward Space File.
+
+ When I set {\bf Hardware End of Medium = no}
+ and {\bf Fast Forward Space File = no}
+ file positioning was very slow
+ on my LTO-3 (about ten to 100 minutes), but
+
+ with {\bf Hardware End of Medium = no} and
+{\bf Fast Forward Space File = yes}, the time is ten to
+100 times faster (about one to two minutes).
+
+\end{description}
+
+\section{Autochanger Errors}
+\index[general]{Errors!Autochanger}
+\index[general]{Autochanger Errors}
+
+If you are getting errors such as:
+
+\footnotesize
+\begin{verbatim}
+3992 Bad autochanger "load slot 1, drive 1": ERR=Child exited with code 1.
+\end{verbatim}
+\normalsize
+
+and you are running your Storage daemon as non-root, then most likely
+you are having permissions problems with the control channel. Running
+as root, set permissions on /dev/sgX so that the userid and group of
+your Storage daemon can access the device. You need to ensure that you
+all access to the proper control device, and if you don't have any
+SCSI disk drives (including SATA drives), you might want to change
+the permissions on /dev/sg*.
+
+\section{Syslog Errors}
+\index[general]{Errors!Syslog}
+\index[general]{Syslog Errors}
+
+If you are getting errors such as:
+
+\footnotesize
+\begin{verbatim}
+: kernel: st0: MTSETDRVBUFFER only allowed for root
+\end{verbatim}
+\normalsize
+
+you are most likely running your Storage daemon as non-root, and
+Bacula is attempting to set the correct OS buffering to correspond
+to your Device resource. Most OSes allow only root to issue this
+ioctl command. In general, the message can be ignored providing
+you are sure that your OS parameters are properly configured as
+described earlier in this manual. If you are running your Storage daemon
+as root, you should not be getting these system log messages, and if
+you are, something is probably wrong.
--- /dev/null
+%%
+%%
+
+\chapter{Tips and Suggestions}
+\label{TipsChapter}
+\index[general]{Tips and Suggestions }
+\index[general]{Suggestions!Tips and }
+\label{examples}
+\index[general]{Examples }
+
+There are a number of example scripts for various things that can be found in
+the {\bf example} subdirectory and its subdirectories of the Bacula source
+distribution.
+
+For additional tips, please see the \elink{Bacula
+wiki}{\url{http://wiki.bacula.org}}.
+
+\section{Upgrading Bacula Versions}
+\label{upgrading}
+\index[general]{Upgrading Bacula Versions }
+\index[general]{Versions!Upgrading Bacula }
+\index[general]{Upgrading}
+
+The first thing to do before upgrading from one version to another is to
+ensure that you don't overwrite or delete your production (current) version
+of Bacula until you have tested that the new version works.
+
+If you have installed Bacula into a single directory, this is simple: simply
+make a copy of your Bacula directory.
+
+If you have done a more typical Unix installation where the binaries are
+placed in one directory and the configuration files are placed in another,
+then the simplest way is to configure your new Bacula to go into a single
+file. Alternatively, make copies of all your binaries and especially your
+conf files.
+
+Whatever your situation may be (one of the two just described), you should
+probably start with the {\bf defaultconf} script that can be found in the {\bf
+examples} subdirectory. Copy this script to the main Bacula directory, modify
+it as necessary (there should not need to be many modifications), configure
+Bacula, build it, install it, then stop your production Bacula, copy all the
+{\bf *.conf} files from your production Bacula directory to the test Bacula
+directory, start the test version, and run a few test backups. If all seems
+good, then you can proceed to install the new Bacula in place of or possibly
+over the old Bacula.
+
+When installing a new Bacula you need not worry about losing the changes you
+made to your configuration files as the installation process will not
+overwrite them providing that you do not do a {\bf make uninstall}.
+
+If the new version of Bacula requires an upgrade to the database,
+you can upgrade it with the script {\bf update\_bacula\_tables}, which
+will be installed in your scripts directory (default {\bf /etc/bacula}),
+or alternatively, you can find it in the
+{\bf \lt{}bacula-source\gt{}/src/cats} directory.
+
+\section{Getting Notified of Job Completion}
+\label{notification}
+\index[general]{Getting Notified of Job Completion }
+\index[general]{Completion!Getting Notified of Job }
+
+One of the first things you should do is to ensure that you are being properly
+notified of the status of each Job run by Bacula, or at a minimum of each Job
+that terminates with an error.
+
+Until you are completely comfortable with {\bf Bacula}, we recommend that you
+send an email to yourself for each Job that is run. This is most easily
+accomplished by adding an email notification address in the {\bf Messages}
+resource of your Director's configuration file. An email is automatically
+configured in the default configuration files, but you must ensure that the
+default {\bf root} address is replaced by your email address.
+
+For additional examples of how to configure a Bacula, please take a look at the
+{\bf .conf} files found in the {\bf examples} sub-directory. We recommend the
+following configuration (where you change the paths and email address to
+correspond to your setup). Note, the {\bf mailcommand} and {\bf
+operatorcommand} should be on a single line. They were split here for
+presentation:
+
+\footnotesize
+\begin{verbatim}
+Messages {
+ Name = Standard
+ mailcommand = "/home/bacula/bin/bsmtp -h localhost
+ -f \"\(Bacula\) %r\"
+ -s \"Bacula: %t %e of %c %l\" %r"
+ operatorcommand = "/home/bacula/bin/bsmtp -h localhost
+ -f \"\(Bacula\) %r\"
+ -s \"Bacula: Intervention needed for %j\" %r"
+ Mail = your-email-address = all, !skipped, !terminate
+ append = "/home/bacula/bin/log" = all, !skipped, !terminate
+ operator = your-email-address = mount
+ console = all, !skipped, !saved
+}
+\end{verbatim}
+\normalsize
+
+You will need to ensure that the {\bf /home/bacula/bin} path on the {\bf
+mailcommand} and the {\bf operatorcommand} lines point to your {\bf Bacula}
+binary directory where the {\bf bsmtp} program will be installed. You will
+also want to ensure that the {\bf your-email-address} is replaced by your
+email address, and finally, you will also need to ensure that the {\bf
+/home/bacula/bin/log} points to the file where you want to log all messages.
+
+With the above Messages resource, you will be notified by email of every Job
+that ran, all the output will be appended to the {\bf log} file you specify,
+all output will be directed to the console program, and all mount messages
+will be emailed to you. Note, some messages will be sent to multiple
+destinations.
+
+The form of the mailcommand is a bit complicated, but it allows you to
+distinguish whether the Job terminated in error or terminated normally. Please
+see the
+\ilink{Mail Command}{mailcommand} section of the Messages
+Resource chapter of this manual for the details of the substitution characters
+used above.
+
+Once you are totally comfortable with Bacula as I am, or if you have a large
+number of nightly Jobs as I do (eight), you will probably want to change the
+{\bf Mail} command to {\bf Mail On Error} which will generate an email message
+only if the Job terminates in error. If the Job terminates normally, no email
+message will be sent, but the output will still be appended to the log file as
+well as sent to the Console program.
+
+\section{Getting Email Notification to Work}
+\label{email}
+\index[general]{Work!Getting Email Notification to }
+\index[general]{Getting Email Notification to Work }
+
+The section above describes how to get email notification of job status.
+Occasionally, however, users have problems receiving any email at all. In that
+case, the things to check are the following:
+
+\begin{itemize}
+\item Ensure that you have a valid email address specified on your {\bf Mail}
+ record in the Director's Messages resource. The email address should be fully
+ qualified. Simply using {\bf root} generally will not work, rather you should
+use {\bf root@localhost} or better yet your full domain.
+\item Ensure that you do not have a {\bf Mail} record in the Storage daemon's
+ or File daemon's configuration files. The only record you should have is {\bf
+ director}:
+
+\footnotesize
+\begin{verbatim}
+ director = director-name = all
+
+\end{verbatim}
+\normalsize
+
+\item If all else fails, try replacing the {\bf mailcommand} with
+
+ \footnotesize
+\begin{verbatim}
+mailcommand = "mail -s test your@domain.com"
+\end{verbatim}
+\normalsize
+
+\item Once the above is working, assuming you want to use {\bf bsmtp}, submit
+ the desired bsmtp command by hand and ensure that the email is delivered,
+ then put that command into {\bf Bacula}. Small differences in things such as
+the parenthesis around the word Bacula can make a big difference to some
+bsmtp programs. For example, you might start simply by using:
+
+\footnotesize
+\begin{verbatim}
+mailcommand = "/home/bacula/bin/bsmtp -f \"root@localhost\" %r"
+\end{verbatim}
+\normalsize
+
+\end{itemize}
+
+\section{Getting Notified that Bacula is Running}
+\label{JobNotification}
+\index[general]{Running!Getting Notified that Bacula is }
+\index[general]{Getting Notified that Bacula is Running }
+
+If like me, you have setup Bacula so that email is sent only when a Job has
+errors, as described in the previous section of this chapter, inevitably, one
+day, something will go wrong and {\bf Bacula} can stall. This could be because
+Bacula crashes, which is vary rare, or more likely the network has caused {\bf
+Bacula} to {\bf hang} for some unknown reason.
+
+To avoid this, you can use the {\bf RunAfterJob} command in the Job resource
+to schedule a Job nightly, or weekly that simply emails you a message saying
+that Bacula is still running. For example, I have setup the following Job in
+my Director's configuration file:
+
+\footnotesize
+\begin{verbatim}
+Schedule {
+ Name = "Watchdog"
+ Run = Level=Full sun-sat at 6:05
+}
+Job {
+ Name = "Watchdog"
+ Type = Admin
+ Client=Watchdog
+ FileSet="Verify Set"
+ Messages = Standard
+ Storage = DLTDrive
+ Pool = Default
+ Schedule = "Watchdog"
+ RunAfterJob = "/home/kern/bacula/bin/watchdog %c %d"
+}
+Client {
+ Name = Watchdog
+ Address = rufus
+ FDPort = 9102
+ Catalog = Verify
+ Password = ""
+ File Retention = 1day
+ Job Retention = 1 month
+ AutoPrune = yes
+}
+\end{verbatim}
+\normalsize
+
+Where I established a schedule to run the Job nightly. The Job itself is type
+{\bf Admin} which means that it doesn't actually do anything, and I've defined
+a FileSet, Pool, Storage, and Client, all of which are not really used (and
+probably don't need to be specified). The key aspect of this Job is the
+command:
+
+\footnotesize
+\begin{verbatim}
+ RunAfterJob = "/home/kern/bacula/bin/watchdog %c %d"
+\end{verbatim}
+\normalsize
+
+which runs my "watchdog" script. As an example, I have added the Job codes
+\%c and \%d which will cause the Client name and the Director's name to be
+passed to the script. For example, if the Client's name is {\bf Watchdog} and
+the Director's name is {\bf main-dir} then referencing \$1 in the script would
+get {\bf Watchdog} and referencing \$2 would get {\bf main-dir}. In this case,
+having the script know the Client and Director's name is not really useful,
+but in other situations it may be.
+
+You can put anything in the watchdog script. In my case, I like to monitor the
+size of my catalog to be sure that {\bf Bacula} is really pruning it. The
+following is my watchdog script:
+
+\footnotesize
+\begin{verbatim}
+#!/bin/sh
+cd /home/kern/mysql/var/bacula
+du . * |
+/home/kern/bacula/bin/bsmtp \
+ -f "\(Bacula\) abuse@whitehouse.com" -h mail.yyyy.com \
+ -s "Bacula running" abuse@whitehouse.com
+\end{verbatim}
+\normalsize
+
+If you just wish to send yourself a message, you can do it with:
+
+\footnotesize
+\begin{verbatim}
+#!/bin/sh
+cd /home/kern/mysql/var/bacula
+/home/kern/bacula/bin/bsmtp \
+ -f "\(Bacula\) abuse@whitehouse.com" -h mail.yyyy.com \
+ -s "Bacula running" abuse@whitehouse.com <<END-OF-DATA
+Bacula is still running!!!
+END-OF-DATA
+\end{verbatim}
+\normalsize
+
+\section{Maintaining a Valid Bootstrap File}
+\label{bootstrap}
+\index[general]{Maintaining a Valid Bootstrap File }
+\index[general]{File!Maintaining a Valid Bootstrap }
+
+By using a
+\ilink{ WriteBootstrap}{writebootstrap} record in each of your
+Director's Job resources, you can constantly maintain a
+\ilink{bootstrap}{BootstrapChapter} file that will enable you to
+recover the state of your system as of the last backup without having the
+Bacula catalog. This permits you to more easily recover from a disaster that
+destroys your Bacula catalog.
+
+When a Job resource has a {\bf WriteBootstrap} record, Bacula will maintain
+the designated file (normally on another system but mounted by NSF) with up to
+date information necessary to restore your system. For example, in my
+Director's configuration file, I have the following record:
+
+\footnotesize
+\begin{verbatim}
+ Write Bootstrap = "/mnt/deuter/files/backup/client-name.bsr"
+\end{verbatim}
+\normalsize
+
+where I replace {\bf client-name} by the actual name of the client that is
+being backed up. Thus, Bacula automatically maintains one file for each of my
+clients. The necessary bootstrap information is appended to this file during
+each {\bf Incremental} backup, and the file is totally rewritten during each
+{\bf Full} backup.
+
+Note, one disadvantage of writing to an NFS mounted volume as I do is
+that if the other machine goes down, the OS will wait forever on the fopen()
+call that Bacula makes. As a consequence, Bacula will completely stall until
+the machine exporting the NFS mounts comes back up. A possible solution to this
+problem was provided by Andrew Hilborne, and consists of using the {\bf soft}
+option instead of the {\bf hard} option when mounting the NFS volume, which is
+typically done in {\bf /etc/fstab}/. The NFS documentation explains these
+options in detail. However, I found that with the {\bf soft} option
+NFS disconnected frequently causing even more problems.
+
+If you are starting off in the middle of a cycle (i.e. with Incremental
+backups) rather than at the beginning (with a Full backup), the {\bf
+bootstrap} file will not be immediately valid as it must always have the
+information from a Full backup as the first record. If you wish to synchronize
+your bootstrap file immediately, you can do so by running a {\bf restore}
+command for the client and selecting a full restore, but when the restore
+command asks for confirmation to run the restore Job, you simply reply no,
+then copy the bootstrap file that was written to the location specified on the
+{\bf Write Bootstrap} record. The restore bootstrap file can be found in {\bf
+restore.bsr} in the working directory that you defined. In the example given
+below for the client {\bf rufus}, my input is shown in bold. Note, the JobId
+output has been partially truncated to fit on the page here:
+
+\footnotesize
+\begin{verbatim}
+(in the Console program)
+*restore
+First you select one or more JobIds that contain files
+to be restored. You will then be presented several methods
+of specifying the JobIds. Then you will be allowed to
+select which files from those JobIds are to be restored.
+To select the JobIds, you have the following choices:
+ 1: List last 20 Jobs run
+ 2: List Jobs where a given File is saved
+ 3: Enter list of JobIds to select
+ 4: Enter SQL list command
+ 5: Select the most recent backup for a client
+ 6: Cancel
+Select item: (1-6): 5
+The defined Client resources are:
+ 1: Minimatou
+ 2: Rufus
+ 3: Timmy
+Select Client (File daemon) resource (1-3): 2
+The defined FileSet resources are:
+ 1: Other Files
+Item 1 selected automatically.
++-------+------+-------+---------+---------+------+-------+------------+
+| JobId | Levl | Files | StrtTim | VolName | File | SesId | VolSesTime |
++-------+------+-------+---------+---------+------+-------+------------+
+| 2 | F | 84 | ... | test1 | 0 | 1 | 1035645259 |
++-------+------+-------+---------+---------+------+-------+------------+
+You have selected the following JobId: 2
+Building directory tree for JobId 2 ...
+The defined Storage resources are:
+ 1: File
+Item 1 selected automatically.
+You are now entering file selection mode where you add and
+remove files to be restored. All files are initially added.
+Enter "done" to leave this mode.
+cwd is: /
+$ done
+84 files selected to restore.
+Run Restore job
+JobName: kernsrestore
+Bootstrap: /home/kern/bacula/working/restore.bsr
+Where: /tmp/bacula-restores
+FileSet: Other Files
+Client: Rufus
+Storage: File
+JobId: *None*
+OK to run? (yes/mod/no): no
+quit
+(in a shell window)
+cp ../working/restore.bsr /mnt/deuter/files/backup/rufus.bsr
+\end{verbatim}
+\normalsize
+
+\section{Rejected Volumes After a Crash}
+\label{RejectedVolumes}
+\index[general]{Crash!Rejected Volumes After a }
+\index[general]{Rejected Volumes After a Crash }
+
+Bacula keeps a count of the number of files on each Volume in its Catalog
+database so that before appending to a tape, it can verify that the number of
+files are correct, and thus prevent overwriting valid data. If the Director or
+the Storage daemon crashes before the job has completed, the tape will contain
+one more file than is noted in the Catalog, and the next time you attempt to
+use the same Volume, Bacula will reject it due to a mismatch between the
+physical tape (Volume) and the catalog.
+
+The easiest solution to this problem is to label a new tape and start fresh.
+If you wish to continue appending to the current tape, you can do so by using
+the {\bf update} command in the console program to change the {\bf Volume
+Files} entry in the catalog. A typical sequence of events would go like the
+following:
+
+\footnotesize
+\begin{verbatim}
+- Bacula crashes
+- You restart Bacula
+\end{verbatim}
+\normalsize
+
+Bacula then prints:
+
+\footnotesize
+\begin{verbatim}
+17-Jan-2003 16:45 rufus-dir: Start Backup JobId 13,
+ Job=kernsave.2003-01-17_16.45.46
+17-Jan-2003 16:45 rufus-sd: Volume test01 previously written,
+ moving to end of data.
+17-Jan-2003 16:46 rufus-sd: kernsave.2003-01-17_16.45.46 Error:
+ I cannot write on this volume because:
+ The number of files mismatch! Volume=11 Catalog=10
+17-Jan-2003 16:46 rufus-sd: Job kernsave.2003-01-17_16.45.46 waiting.
+ Cannot find any appendable volumes.
+Please use the "label" command to create a new Volume for:
+ Storage: SDT-10000
+ Media type: DDS-4
+ Pool: Default
+\end{verbatim}
+\normalsize
+
+(note, lines wrapped for presentation)
+The key here is the line that reads:
+
+\footnotesize
+\begin{verbatim}
+ The number of files mismatch! Volume=11 Catalog=10
+\end{verbatim}
+\normalsize
+
+It says that Bacula found eleven files on the volume, but that the catalog
+says there should be ten. When you see this, you can be reasonably sure that
+the SD was interrupted while writing before it had a chance to update the
+catalog. As a consequence, you can just modify the catalog count to eleven,
+and even if the catalog contains references to files saved in file 11,
+everything will be OK and nothing will be lost. Note that if the SD had
+written several file marks to the volume, the difference between the Volume
+count and the Catalog count could be larger than one, but this is unusual.
+
+If on the other hand the catalog is marked as having more files than Bacula
+found on the tape, you need to consider the possible negative consequences of
+modifying the catalog. Please see below for a more complete discussion of
+this.
+
+Continuing with the example of {\bf Volume = 11 Catalog = 10}, to enable to
+Bacula to append to the tape, you do the following:
+
+\footnotesize
+\begin{verbatim}
+update
+Update choice:
+ 1: Volume parameters
+ 2: Pool from resource
+ 3: Slots from autochanger
+Choose catalog item to update (1-3): 1
+Defined Pools:
+ 1: Default
+ 2: File
+Select the Pool (1-2):
++-------+---------+--------+---------+-----------+------+----------+------+-----+
+| MedId | VolName | MedTyp | VolStat | VolBytes | Last | VolReten | Recy | Slt |
++-------+---------+--------+---------+-----------+------+----------+------+-----+
+| 1 | test01 | DDS-4 | Error | 352427156 | ... | 31536000 | 1 | 0 |
++-------+---------+--------+---------+-----------+------+----------+------+-----+
+Enter MediaId or Volume name: 1
+\end{verbatim}
+\normalsize
+
+(note table output truncated for presentation) First, you chose to update the
+Volume parameters by entering a {\bf 1}. In the volume listing that follows,
+notice how the VolStatus is {\bf Error}. We will correct that after changing
+the Volume Files. Continuing, you respond 1,
+
+\footnotesize
+\begin{verbatim}
+Updating Volume "test01"
+Parameters to modify:
+ 1: Volume Status
+ 2: Volume Retention Period
+ 3: Volume Use Duration
+ 4: Maximum Volume Jobs
+ 5: Maximum Volume Files
+ 6: Maximum Volume Bytes
+ 7: Recycle Flag
+ 8: Slot
+ 9: Volume Files
+ 10: Pool
+ 11: Done
+Select parameter to modify (1-11): 9
+Warning changing Volume Files can result
+in loss of data on your Volume
+Current Volume Files is: 10
+Enter new number of Files for Volume: 11
+New Volume Files is: 11
+Updating Volume "test01"
+Parameters to modify:
+ 1: Volume Status
+ 2: Volume Retention Period
+ 3: Volume Use Duration
+ 4: Maximum Volume Jobs
+ 5: Maximum Volume Files
+ 6: Maximum Volume Bytes
+ 7: Recycle Flag
+ 8: Slot
+ 9: Volume Files
+ 10: Pool
+ 11: Done
+Select parameter to modify (1-10): 1
+\end{verbatim}
+\normalsize
+
+Here, you have selected {\bf 9} in order to update the Volume Files, then you
+changed it from {\bf 10} to {\bf 11}, and you now answer {\bf 1} to change the
+Volume Status.
+
+\footnotesize
+\begin{verbatim}
+Current Volume status is: Error
+Possible Values are:
+ 1: Append
+ 2: Archive
+ 3: Disabled
+ 4: Full
+ 5: Used
+ 6: Read-Only
+Choose new Volume Status (1-6): 1
+New Volume status is: Append
+Updating Volume "test01"
+Parameters to modify:
+ 1: Volume Status
+ 2: Volume Retention Period
+ 3: Volume Use Duration
+ 4: Maximum Volume Jobs
+ 5: Maximum Volume Files
+ 6: Maximum Volume Bytes
+ 7: Recycle Flag
+ 8: Slot
+ 9: Volume Files
+ 10: Pool
+ 11: Done
+Select parameter to modify (1-11): 11
+Selection done.
+\end{verbatim}
+\normalsize
+
+At this point, you have changed the Volume Files from {\bf 10} to {\bf 11} to
+account for the last file that was written but not updated in the database,
+and you changed the Volume Status back to {\bf Append}.
+
+This was a lot of words to describe something quite simple.
+
+The {\bf Volume Files} option exists only in version 1.29 and later, and you
+should be careful using it. Generally, if you set the value to that which
+Bacula said is on the tape, you will be OK, especially if the value is one
+more than what is in the catalog.
+
+Now lets consider the case:
+
+\footnotesize
+\begin{verbatim}
+ The number of files mismatch! Volume=10 Catalog=12
+\end{verbatim}
+\normalsize
+
+Here the Bacula found fewer files on the volume than what is marked in the
+catalog. Now, in this case, you should hesitate a lot before modifying the count
+in the catalog, because if you force the catalog from 12 to 10, Bacula will
+start writing after the file 10 on the tape, possibly overwriting valid data,
+and if you ever try to restore any of the files that the catalog has marked as
+saved on Files 11 and 12, all chaos will break out. In this case, you will
+probably be better off using a new tape. In fact, you might want to see what
+files the catalog claims are actually stored on that Volume, and back them up
+to another tape and recycle this tape.
+
+\section{Security Considerations}
+\label{security}
+\index[general]{Considerations!Security }
+\index[general]{Security Considerations }
+
+Only the File daemon needs to run with root permission (so that it can access
+all files). As a consequence, you may run your Director, Storage daemon, and
+MySQL or PostgreSQL database server as non-root processes. Version 1.30 has
+the {\bf -u} and the {\bf -g} options that allow you to specify a userid and
+groupid on the command line to be used after Bacula starts.
+
+As of version 1.33, thanks to Dan Langille, it is easier to configure the
+Bacula Director and Storage daemon to run as non-root.
+
+You should protect the Bacula port addresses (normally 9101, 9102, and 9103)
+from outside access by a firewall or other means of protection to prevent
+unauthorized use of your daemons.
+
+You should ensure that the configuration files are not world readable since
+they contain passwords that allow access to the daemons. Anyone who can access
+the Director using a console program can restore any file from a backup
+Volume.
+
+You should protect your Catalog database. If you are using SQLite, make sure
+that the working directory is readable only by root (or your Bacula userid),
+and ensure that {\bf bacula.db} has permissions {\bf -rw-r\verb:--:r\verb:--:} (i.e. 640) or
+more strict. If you are using MySQL or PostgreSQL, please note that the Bacula
+setup procedure leaves the database open to anyone. At a minimum, you should
+assign the user {\bf bacula} a userid and add it to your Director's
+configuration file in the appropriate Catalog resource.
+
+If you use the make\_catalog\_backup script provided by Bacula, remember that
+you should take care when supplying passwords on the command line. Read the
+\ilink{Backing Up Your Bacula
+Database - Security Considerations }{BackingUpBaculaSecurityConsiderations}
+section for more information.
+
+\section{Creating Holiday Schedules}
+\label{holiday}
+\index[general]{Schedules!Creating Holiday }
+\index[general]{Creating Holiday Schedules }
+
+If you normally change tapes every day or at least every Friday, but Thursday
+is a holiday, you can use a trick proposed by Lutz Kittler to ensure that no
+job runs on Thursday so that you can insert Friday's tape and be sure it will
+be used on Friday. To do so, define a {\bf RunJobBefore} script that normally
+returns zero, so that the Bacula job will normally continue. You can then
+modify the script to return non-zero on any day when you do not want Bacula to
+run the job.
+
+\section{Automatic Labeling Using Your Autochanger}
+\label{autolabel}
+\index[general]{Automatic Labeling Using Your Autochanger }
+\index[general]{Autochanger!Automatic Labeling Using Your }
+
+If you have an autochanger but it does not support barcodes, using a "trick"
+you can make Bacula automatically label all the volumes in your autochanger's
+magazine.
+
+First create a file containing one line for each slot in your autochanger that
+has a tape to be labeled. The line will contain the slot number a colon (:)
+then the Volume name you want to use. For example, create a file named {\bf
+volume-list}, which contains:
+
+\footnotesize
+\begin{verbatim}
+1:Volume001
+2:TestVolume02
+5:LastVolume
+\end{verbatim}
+\normalsize
+
+The records do not need to be in any order and you don't need to mention all
+the slots. Normally, you will have a consistent set of Volume names and a
+sequential set of numbers for each slot you want labeled. In the example
+above, I've left out slots 3 and 4 just as an example. Now, modify your {\bf
+mtx-changer} script and comment out all the lines in the {\bf list)} case by
+putting a \# in column 1. Then add the following two lines:
+
+\footnotesize
+\begin{verbatim}
+ cat <absolute-path>/volume-list
+ exit 0
+\end{verbatim}
+\normalsize
+
+so that the whole case looks like:
+
+\footnotesize
+\begin{verbatim}
+ list)
+#
+# commented out lines
+ cat <absolute-path>/volume-list
+ exit 0
+ ;;
+\end{verbatim}
+\normalsize
+
+where you replace \lt{}absolute-path\gt{} with the full path to the
+volume-list file. Then using the console, you enter the following command:
+
+\footnotesize
+\begin{verbatim}
+ label barcodes
+\end{verbatim}
+\normalsize
+
+and Bacula will proceed to mount the autochanger Volumes in the list and label
+them with the Volume names you have supplied. Bacula will think that the list
+was provided by the autochanger barcodes, but in reality, it was you who
+supplied the \lt{}barcodes\gt{}.
+
+If it seems to work, when it finishes, enter:
+
+\footnotesize
+\begin{verbatim}
+ list volumes
+\end{verbatim}
+\normalsize
+
+and you should see all the volumes nicely created.
+
+\section{Backing Up Portables Using DHCP}
+\label{DNS}
+\index[general]{DHCP!Backing Up Portables Using }
+\index[general]{Backing Up Portables Using DHCP }
+
+You may want to backup laptops or portables that are not always connected to
+the network. If you are using DHCP to assign an IP address to those machines
+when they connect, you will need to use the Dynamic Update capability of DNS
+to assign a name to those machines that can be used in the Address field of
+the Client resource in the Director's conf file.
+
+\section{Going on Vacation}
+\label{Vacation}
+\index[general]{Vacation!Going on }
+\index[general]{Going on Vacation }
+
+At some point, you may want to be absent for a week or two and you want to
+make sure Bacula has enough tape left so that the backups will complete. You
+start by doing a {\bf list volumes} in the Console program:
+
+\footnotesize
+\begin{verbatim}
+list volumes
+
+Using default Catalog name=BackupDB DB=bacula
+Pool: Default
++---------+---------------+-----------+-----------+----------------+-
+| MediaId | VolumeName | MediaType | VolStatus | VolBytes |
++---------+---------------+-----------+-----------+----------------+-
+| 23 | DLT-30Nov02 | DLT8000 | Full | 54,739,278,128 |
+| 24 | DLT-21Dec02 | DLT8000 | Full | 56,331,524,629 |
+| 25 | DLT-11Jan03 | DLT8000 | Full | 67,863,514,895 |
+| 26 | DLT-02Feb03 | DLT8000 | Full | 63,439,314,216 |
+| 27 | DLT-03Mar03 | DLT8000 | Full | 66,022,754,598 |
+| 28 | DLT-04Apr03 | DLT8000 | Full | 60,792,559,924 |
+| 29 | DLT-28Apr03 | DLT8000 | Full | 62,072,494,063 |
+| 30 | DLT-17May03 | DLT8000 | Full | 65,901,767,839 |
+| 31 | DLT-07Jun03 | DLT8000 | Used | 56,558,490,015 |
+| 32 | DLT-28Jun03 | DLT8000 | Full | 64,274,871,265 |
+| 33 | DLT-19Jul03 | DLT8000 | Full | 64,648,749,480 |
+| 34 | DLT-08Aug03 | DLT8000 | Full | 64,293,941,255 |
+| 35 | DLT-24Aug03 | DLT8000 | Append | 9,999,216,782 |
++---------+---------------+-----------+-----------+----------------+
+\end{verbatim}
+\normalsize
+
+Note, I have truncated the output for presentation purposes. What is
+significant, is that I can see that my current tape has almost 10 Gbytes of
+data, and that the average amount of data I get on my tapes is about 60
+Gbytes. So if I go on vacation now, I don't need to worry about tape capacity
+(at least not for short absences).
+
+Equally significant is the fact that I did go on vacation the 28th of June
+2003, and when I did the {\bf list volumes} command, my current tape at that
+time, DLT-07Jun03 MediaId 31, had 56.5 Gbytes written. I could see that the
+tape would fill shortly. Consequently, I manually marked it as {\bf Used} and
+replaced it with a fresh tape that I labeled as DLT-28Jun03, thus assuring
+myself that the backups would all complete without my intervention.
+
+\section{Exclude Files on Windows Regardless of Case}
+\label{Case}
+\index[general]{Exclude Files on Windows Regardless of Case}
+% TODO: should this be put in the win32 chapter?
+% TODO: should all these tips be placed in other chapters?
+
+This tip was submitted by Marc Brueckner who wasn't sure of the case of some
+of his files on Win32, which is case insensitive. The problem is that Bacula
+thinks that {\bf /UNIMPORTANT FILES} is different from {\bf /Unimportant
+Files}. Marc was aware that the file exclusion permits wild-cards. So, he
+specified:
+
+\footnotesize
+\begin{verbatim}
+"/[Uu][Nn][Ii][Mm][Pp][Oo][Rr][Tt][Aa][Nn][Tt] [Ff][Ii][Ll][Ee][Ss]"
+\end{verbatim}
+\normalsize
+
+As a consequence, the above exclude works for files of any case.
+
+Please note that this works only in Bacula Exclude statement and not in
+Include.
+
+\section{Executing Scripts on a Remote Machine}
+\label{RemoteExecution}
+\index[general]{Machine!Executing Scripts on a Remote }
+\index[general]{Executing Scripts on a Remote Machine }
+
+This tip also comes from Marc Brueckner. (Note, this tip is probably outdated
+by the addition of {\bf ClientRunBeforJob} and {\bf ClientRunAfterJob} Job
+records, but the technique still could be useful.) First I thought the "Run
+Before Job" statement in the Job-resource is for executing a script on the
+remote machine (the machine to be backed up). (Note, this is possible as mentioned
+above by using {\bf ClientRunBeforJob} and {\bf ClientRunAfterJob}).
+It could be useful to execute
+scripts on the remote machine e.g. for stopping databases or other services
+while doing the backup. (Of course I have to start the services again when the
+backup has finished) I found the following solution: Bacula could execute
+scripts on the remote machine by using ssh. The authentication is done
+automatically using a private key. First you have to generate a keypair. I've
+done this by:
+
+\footnotesize
+\begin{verbatim}
+ssh-keygen -b 4096 -t dsa -f Bacula_key
+\end{verbatim}
+\normalsize
+
+This statement may take a little time to run. It creates a public/private key
+pair with no passphrase. You could save the keys in /etc/bacula. Now you have
+two new files : Bacula\_key which contains the private key and Bacula\_key.pub
+which contains the public key.
+
+Now you have to append the Bacula\_key.pub file to the file authorized\_keys
+in the \textbackslash{}root\textbackslash{}.ssh directory of the remote
+machine. Then you have to add (or uncomment) the line
+
+\footnotesize
+\begin{verbatim}
+AuthorizedKeysFile %h/.ssh/authorized_keys
+\end{verbatim}
+\normalsize
+
+to the sshd\_config file on the remote machine. Where the \%h stands for the
+home-directory of the user (root in this case).
+
+Assuming that your sshd is already running on the remote machine, you can now
+enter the following on the machine where Bacula runs:
+
+\footnotesize
+\begin{verbatim}
+ssh -i Bacula_key -l root <machine-name-or-ip-address> "ls -la"
+\end{verbatim}
+\normalsize
+
+This should execute the "ls -la" command on the remote machine.
+
+Now you could add lines like the following to your Director's conf file:
+
+\footnotesize
+\begin{verbatim}
+...
+Run Before Job = ssh -i /etc/bacula/Bacula_key 192.168.1.1 \
+ "/etc/init.d/database stop"
+Run After Job = ssh -i /etc/bacula/Bacula_key 192.168.1.1 \
+ "/etc/init.d/database start"
+...
+\end{verbatim}
+\normalsize
+
+Even though Bacula version 1.32 and later has a ClientRunBeforeJob, the ssh method still
+could be useful for updating all the Bacula clients on several remote machines
+in a single script.
+
+\section{Recycling All Your Volumes}
+\label{recycle}
+\index[general]{Recycling All Your Volumes }
+\index[general]{Volumes!Recycling All Your }
+
+This tip comes from Phil Stracchino.
+
+If you decide to blow away your catalog and start over, the simplest way to
+re-add all your prelabeled tapes with a minimum of fuss (provided you don't
+care about the data on the tapes) is to add the tape labels using the console
+{\bf add} command, then go into the catalog and manually set the VolStatus of
+every tape to {\bf Recycle}.
+
+The SQL command to do this is very simple, either use your vendor's
+command line interface (mysql, postgres, sqlite, ...) or use the sql
+command in the Bacula console:
+
+\footnotesize
+\begin{verbatim}
+update Media set VolStatus='Recycle';
+\end{verbatim}
+\normalsize
+
+Bacula will then ignore the data already stored on the tapes and just re-use
+each tape without further objection.
+
+\section{Backing up ACLs on ext3 or XFS filesystems}
+\label{ACLs}
+\index[general]{Filesystems!Backing up ACLs on ext3 or XFS }
+\index[general]{Backing up ACLs on ext3 or XFS filesystems }
+
+This tip comes from Volker Sauer.
+
+Note, this tip was given prior to implementation of ACLs in Bacula (version
+1.34.5). It is left here because dumping/displaying ACLs can still be useful
+in testing/verifying that Bacula is backing up and restoring your ACLs
+properly. Please see the
+\ilink{aclsupport}{ACLSupport} FileSet option in the
+configuration chapter of this manual.
+
+For example, you could dump the ACLs to a file with a script similar to the
+following:
+
+\footnotesize
+\begin{verbatim}
+#!/bin/sh
+BACKUP_DIRS="/foo /bar"
+STORE_ACL=/root/acl-backup
+umask 077
+for i in $BACKUP_DIRS; do
+ cd $i /usr/bin/getfacl -R --skip-base .>$STORE_ACL/${i//\//_}
+done
+\end{verbatim}
+\normalsize
+
+Then use Bacula to backup {\bf /root/acl-backup}.
+
+The ACLs could be restored using Bacula to the {\bf /root/acl-backup} file,
+then restored to your system using:
+
+\footnotesize
+\begin{verbatim}
+setfacl --restore/root/acl-backup
+\end{verbatim}
+\normalsize
+
+\section{Total Automation of Bacula Tape Handling}
+\label{automate}
+\index[general]{Handling!Total Automation of Bacula Tape }
+\index[general]{Total Automation of Bacula Tape Handling }
+
+This tip was provided by Alexander Kuehn.
+
+\elink{Bacula}{\url{http://www.bacula.org/}} is a really nice backup program except
+that the manual tape changing requires user interaction with the bacula
+console.
+
+Fortunately I can fix this.
+NOTE!!! This suggestion applies for people who do *NOT* have tape autochangers
+and must change tapes manually.!!!!!
+
+Bacula supports a variety of tape changers through the use of mtx-changer
+scripts/programs. This highly flexible approach allowed me to create
+\elink{this shell script}{\url{http://www.bacula.org/rel-manual/mtx-changer.txt}} which does the following:
+% TODO: We need to include this in book appendix and point to it.
+% TODO:
+Whenever a new tape is required it sends a mail to the operator to insert the
+new tape. Then it waits until a tape has been inserted, sends a mail again to
+say thank you and let's bacula continue its backup.
+So you can schedule and run backups without ever having to log on or see the
+console.
+To make the whole thing work you need to create a Device resource which looks
+something like this ("Archive Device", "Maximum Changer Wait", "Media
+Type" and "Label media" may have different values):
+
+\footnotesize
+\begin{verbatim}
+Device {
+ Name=DDS3
+ Archive Device = # use yours not mine! ;)/dev/nsa0
+ Changer Device = # not really required/dev/nsa0
+ Changer Command = "# use this (maybe change the path)!
+ /usr/local/bin/mtx-changer %o %a %S"
+ Maximum Changer Wait = 3d # 3 days in seconds
+ AutomaticMount = yes; # mount on start
+ AlwaysOpen = yes; # keep device locked
+ Media Type = DDS3 # it's just a name
+ RemovableMedia = yes; #
+ Offline On Unmount = Yes; # keep this too
+ Label media = Yes; #
+}
+\end{verbatim}
+\normalsize
+
+As the script has to emulate the complete wisdom of a mtx-changer it has an
+internal "database" containing where which tape is stored, you can see this on
+the following line:
+
+\footnotesize
+\begin{verbatim}
+labels="VOL-0001 VOL-0002 VOL-0003 VOL-0004 VOL-0005 VOL-0006
+VOL-0007 VOL-0008 VOL-0009 VOL-0010 VOL-0011 VOL-0012"
+\end{verbatim}
+\normalsize
+
+The above should be all on one line, and it effectively tells Bacula that
+volume "VOL-0001" is located in slot 1 (which is our lowest slot), that
+volume "VOL-0002" is located in slot 2 and so on..
+The script also maintains a logfile (/var/log/mtx.log) where you can monitor
+its operation.
+
+\section{Running Concurrent Jobs}
+\label{ConcurrentJobs}
+\index[general]{Jobs!Running Concurrent}
+\index[general]{Running Concurrent Jobs}
+\index[general]{Concurrent Jobs}
+
+Bacula can run multiple concurrent jobs, but the default configuration files
+do not enable it. Using the {\bf Maximum Concurrent Jobs} directive, you
+can configure how many and which jobs can be run simultaneously.
+The Director's default value for {\bf Maximum Concurrent Jobs} is "1".
+
+To initially setup concurrent jobs you need to define {\bf Maximum Concurrent Jobs} in
+the Director's configuration file (bacula-dir.conf) in the
+Director, Job, Client, and Storage resources.
+
+Additionally the File daemon, and the Storage daemon each have their own
+{\bf Maximum Concurrent Jobs} directive that sets the overall maximum
+number of concurrent jobs the daemon will run. The default for both the
+File daemon and the Storage daemon is "20".
+
+For example, if you want two different jobs to run simultaneously backing up
+the same Client to the same Storage device, they will run concurrently only if
+you have set {\bf Maximum Concurrent Jobs} greater than one in the Director
+resource, the Client resource, and the Storage resource in bacula-dir.conf.
+
+We recommend that you read the \ilink{Data
+Spooling}{SpoolingChapter} of this manual first, then test your multiple
+concurrent backup including restore testing before you put it into
+production.
+
+Below is a super stripped down bacula-dir.conf file showing you the four
+places where the the file must be modified to allow the same job {\bf
+NightlySave} to run up to four times concurrently. The change to the Job
+resource is not necessary if you want different Jobs to run at the same time,
+which is the normal case.
+
+\footnotesize
+\begin{verbatim}
+#
+# Bacula Director Configuration file -- bacula-dir.conf
+#
+Director {
+ Name = rufus-dir
+ Maximum Concurrent Jobs = 4
+ ...
+}
+Job {
+ Name = "NightlySave"
+ Maximum Concurrent Jobs = 4
+ Client = rufus-fd
+ Storage = File
+ ...
+}
+Client {
+ Name = rufus-fd
+ Maximum Concurrent Jobs = 4
+ ...
+}
+Storage {
+ Name = File
+ Maximum Concurrent Jobs = 4
+ ...
+}
+\end{verbatim}
+\normalsize
--- /dev/null
+#!/usr/bin/perl -w
+#
+use strict;
+
+# Used to change the names of the image files generated by latex2html from imgxx.png
+# to meaningful names. Provision is made to go either from or to the meaningful names.
+# The meaningful names are obtained from a file called imagename_translations, which
+# is generated by extensions to latex2html in the make_image_file subroutine in
+# bacula.perl.
+
+# Opens the file imagename_translations and reads the contents into a hash.
+# The hash is creaed with the imgxx.png files as the key if processing TO
+# meaningful filenames, and with the meaningful filenames as the key if
+# processing FROM meaningful filenames.
+# Then opens the html file(s) indicated in the command-line arguments and
+# changes all image references according to the translations described in the
+# above file. Finally, it renames the image files.
+#
+# Original creation: 3-27-05 by Karl Cunningham.
+# Modified 5-21-05 to go FROM and TO meaningful filenames.
+#
+my $TRANSFILE = "imagename_translations";
+my $path;
+
+# Loads the contents of $TRANSFILE file into the hash referenced in the first
+# argument. The hash is loaded to translate old to new if $direction is 0,
+# otherwise it is loaded to translate new to old. In this context, the
+# 'old' filename is the meaningful name, and the 'new' filename is the
+# imgxx.png filename. It is assumed that the old image is the one that
+# latex2html has used as the source to create the imgxx.png filename.
+# The filename extension is taken from the file
+sub read_transfile {
+ my ($trans,$direction) = @_;
+
+ if (!open IN,"<$path$TRANSFILE") {
+ print "WARNING: Cannot open image translation file $path$TRANSFILE for reading\n";
+ print " Image filename translation aborted\n\n";
+ exit 0;
+ }
+
+ while (<IN>) {
+ chomp;
+ my ($new,$old) = split(/\001/);
+
+ # Old filenames will usually have a leading ./ which we don't need.
+ $old =~ s/^\.\///;
+
+ # The filename extension of the old filename must be made to match
+ # the new filename because it indicates the encoding format of the image.
+ my ($ext) = $new =~ /(\.[^\.]*)$/;
+ $old =~ s/\.[^\.]*$/$ext/;
+ if ($direction == 0) {
+ $trans->{$new} = $old;
+ } else {
+ $trans->{$old} = $new;
+ }
+ }
+ close IN;
+}
+
+# Translates the image names in the file given as the first argument, according to
+# the translations in the hash that is given as the second argument.
+# The file contents are read in entirely into a string, the string is processed, and
+# the file contents are then written. No particular care is taken to ensure that the
+# file is not lost if a system failure occurs at an inopportune time. It is assumed
+# that the html files being processed here can be recreated on demand.
+#
+# Links to other files are added to the %filelist for processing. That way,
+# all linked files will be processed (assuming they are local).
+sub translate_html {
+ my ($filename,$trans,$filelist) = @_;
+ my ($contents,$out,$this,$img,$dest);
+ my $cnt = 0;
+
+ # If the filename is an external link ignore it. And drop any file:// from
+ # the filename.
+ $filename =~ /^(http|ftp|mailto)\:/ and return 0;
+ $filename =~ s/^file\:\/\///;
+ # Load the contents of the html file.
+ if (!open IF,"<$path$filename") {
+ print "WARNING: Cannot open $path$filename for reading\n";
+ print " Image Filename Translation aborted\n\n";
+ exit 0;
+ }
+
+ while (<IF>) {
+ $contents .= $_;
+ }
+ close IF;
+
+ # Now do the translation...
+ # First, search for an image filename.
+ while ($contents =~ /\<\s*IMG[^\>]*SRC=\"/si) {
+ $contents = $';
+ $out .= $` . $&;
+
+ # The next thing is an image name. Get it and translate it.
+ $contents =~ /^(.*?)\"/s;
+ $contents = $';
+ $this = $&;
+ $img = $1;
+ # If the image is in our list of ones to be translated, do it
+ # and feed the result to the output.
+ $cnt += $this =~ s/$img/$trans->{$img}/ if (defined($trans->{$img}));
+ $out .= $this;
+ }
+ $out .= $contents;
+
+ # Now send the translated text to the html file, overwriting what's there.
+ open OF,">$path$filename" or die "Cannot open $path$filename for writing\n";
+ print OF $out;
+ close OF;
+
+ # Now look for any links to other files and add them to the list of files to do.
+ while ($out =~ /\<\s*A[^\>]*HREF=\"(.*?)\"/si) {
+ $out = $';
+ $dest = $1;
+ # Drop an # and anything after it.
+ $dest =~ s/\#.*//;
+ $filelist->{$dest} = '' if $dest;
+ }
+ return $cnt;
+}
+
+# REnames the image files spefified in the %translate hash.
+sub rename_images {
+ my $translate = shift;
+ my ($response);
+
+ foreach (keys(%$translate)) {
+ if (! $translate->{$_}) {
+ print " WARNING: No destination Filename for $_\n";
+ } else {
+ $response = `mv -f $path$_ $path$translate->{$_} 2>&1`;
+ $response and print "ERROR from system $response\n";
+ }
+ }
+}
+
+#################################################
+############# MAIN #############################
+################################################
+
+# %filelist starts out with keys from the @ARGV list. As files are processed,
+# any links to other files are added to the %filelist. A hash of processed
+# files is kept so we don't do any twice.
+
+# The first argument must be either --to_meaningful_names or --from_meaningful_names
+
+my (%translate,$search_regex,%filelist,%completed,$thisfile);
+my ($cnt,$direction);
+
+my $arg0 = shift(@ARGV);
+$arg0 =~ /^(--to_meaningful_names|--from_meaningful_names)$/ or
+ die "ERROR: First argument must be either \'--to_meaningful_names\' or \'--from_meaningful_names\'\n";
+
+$direction = ($arg0 eq '--to_meaningful_names') ? 0 : 1;
+
+(@ARGV) or die "ERROR: Filename(s) to process must be given as arguments\n";
+
+# Use the first argument to get the path to the file of translations.
+my $tmp = $ARGV[0];
+($path) = $tmp =~ /(.*\/)/;
+$path = '' unless $path;
+
+read_transfile(\%translate,$direction);
+
+foreach (@ARGV) {
+ # Strip the path from the filename, and use it later on.
+ if (s/(.*\/)//) {
+ $path = $1;
+ } else {
+ $path = '';
+ }
+ $filelist{$_} = '';
+
+ while ($thisfile = (keys(%filelist))[0]) {
+ $cnt += translate_html($thisfile,\%translate,\%filelist) if (!exists($completed{$thisfile}));
+ delete($filelist{$thisfile});
+ $completed{$thisfile} = '';
+ }
+ print "translate_images.pl: $cnt image filenames translated ",($direction)?"from":"to"," meaningful names\n";
+}
+
+rename_images(\%translate);
--- /dev/null
+#!/bin/sh
+#
+# Script file to update the Bacula version
+#
+out=/tmp/$$
+VERSION=`sed -n -e 's/^.*VERSION.*"\(.*\)"$/\1/p' /home/kern/bacula/k/src/version.h`
+DATE=`sed -n -e 's/^.*[ \t]*BDATE.*"\(.*\)"$/\1/p' /home/kern/bacula/k/src/version.h`
+. ./do_echo
+sed -f ${out} version.tex.in >version.tex
+rm -f ${out}
--- /dev/null
+#!/bin/sh
+#
+# Script file to update the Bacula version
+#
+out=/tmp/$$
+VERSION=`sed -n -e 's/^.*VERSION.*"\(.*\)"$/\1/p' @bacula@/src/version.h`
+DATE=`sed -n -e 's/^.*[ \t]*BDATE.*"\(.*\)"$/\1/p' @bacula@/src/version.h`
+. ./do_echo
+sed -f ${out} version.tex.in >version.tex
+rm -f ${out}
--- /dev/null
+2.3.6 (04 November 2007)
--- /dev/null
+@VERSION@ (@DATE@)
--- /dev/null
+#
+#
+# Makefile for LaTeX
+#
+# To build everything do
+# make tex
+# make web
+# make html
+# make dvipdf
+#
+# or simply
+#
+# make
+#
+# for rapid development do:
+# make tex
+# make show
+#
+#
+# If you are having problems getting "make" to work, debugging it is
+# easier if can see the output from latex, which is normally redirected
+# to /dev/null. To see it, do the following:
+#
+# cd docs/manual
+# make tex
+# latex bacula.tex
+#
+# typically the latex command will stop indicating the error (e.g. a
+# missing \ in front of a _ or a missing { or ] ...
+#
+# The following characters must be preceded by a backslash
+# to be entered as printable characters:
+#
+# # $ % & ~ _ ^ \ { }
+#
+
+IMAGES=../../../images
+
+DOC=utility
+
+first_rule: all
+
+all: tex web dvipdf mini-clean
+
+.SUFFIXES: .tex .html
+.PHONY:
+.DONTCARE:
+
+
+tex:
+ @./update_version
+ @echo "Making version `cat version.tex`"
+ @cp -fp ${IMAGES}/hires/*.eps .
+ @touch ${DOC}i-dir.tex ${DOC}i-fd.tex ${DOC}i-sd.tex \
+ ${DOC}i-console.tex ${DOC}i-general.tex
+ latex -interaction=batchmode ${DOC}.tex
+ makeindex ${DOC}.idx -o ${DOC}.ind 2>/dev/null
+ latex -interaction=batchmode ${DOC}.tex
+
+pdf:
+ @echo "Making pdfm"
+ @cp -fp ${IMAGES}/hires/*.eps .
+ dvipdfm -p a4 ${DOC}.dvi
+
+dvipdf:
+ @echo "Making dvi to pdf"
+ @cp -fp ${IMAGES}/hires/*.eps .
+ dvipdf ${DOC}.dvi ${DOC}.pdf
+
+html:
+ @echo " "
+ @echo "Making html"
+ @cp -fp ${IMAGES}/*.eps .
+ @rm -f next.eps next.png prev.eps prev.png up.eps up.png
+ @(if [ -f imagename_translations ] ; then \
+ ./translate_images.pl --from_meaningful_names ${DOC}.html; \
+ fi)
+ latex2html -white -no_subdir -split 0 -toc_stars -white -notransparent \
+ -init_file latex2html-init.pl ${DOC} >tex.out 2>&1
+ ./translate_images.pl --to_meaningful_names ${DOC}.html
+ @echo "Done making html"
+
+web:
+ @echo "Making web"
+ @mkdir -p ${DOC}
+ @cp -fp ${IMAGES}/*.eps .
+ @rm -f next.eps next.png prev.eps prev.png up.eps up.png
+ @cp -fp ${IMAGES}/*.eps ${DOC}/
+ @cp -fp ${IMAGES}/*.eps ${IMAGES}/*.png ${DOC}/
+ @rm -f ${DOC}/xp-*.png
+ @rm -f ${DOC}/next.eps ${DOC}/next.png ${DOC}/prev.eps ${DOC}/prev.png ${DOC}/up.eps ${DOC}/up.png
+ @rm -rf ${DOC}/*.html
+ latex2html -split 3 -local_icons -t "Bacula Utility Programs" -long_titles 4 \
+ -toc_stars -contents_in_nav -init_file latex2html-init.pl -white -notransparent ${DOC} >tex.out 2>&1
+ ./translate_images.pl --to_meaningful_names ${DOC}/Bacula_Utilit*.html
+ @echo "Done making web"
+show:
+ xdvi ${DOC}
+
+texcheck:
+ ./check_tex.pl ${DOC}.tex
+
+main_configs:
+ pic2graph -density 100 <main_configs.pic >main_configs.png
+
+mini-clean:
+ @rm -f 1 2 3 *.tex~
+ @rm -f *.gif *.jpg *.eps
+ @rm -f *.aux *.cp *.fn *.ky *.log *.pg
+ @rm -f *.backup *.ilg *.lof *.lot
+ @rm -f *.cdx *.cnd *.ddx *.ddn *.fdx *.fnd *.ind *.sdx *.snd
+ @rm -f *.dnd *.old *.out
+ @rm -f ${DOC}/*.gif ${DOC}/*.jpg ${DOC}/*.eps
+ @rm -f ${DOC}/*.aux ${DOC}/*.cp ${DOC}/*.fn ${DOC}/*.ky ${DOC}/*.log ${DOC}/*.pg
+ @rm -f ${DOC}/*.backup ${DOC}/*.ilg ${DOC}/*.lof ${DOC}/*.lot
+ @rm -f ${DOC}/*.cdx ${DOC}/*.cnd ${DOC}/*.ddx ${DOC}/*.ddn ${DOC}/*.fdx ${DOC}/*.fnd ${DOC}/*.ind ${DOC}/*.sdx ${DOC}/*.snd
+ @rm -f ${DOC}/*.dnd ${DOC}/*.old ${DOC}/*.out
+ @rm -f ${DOC}/WARNINGS
+
+
+clean:
+ @rm -f 1 2 3 *.tex~
+ @rm -f *.png *.gif *.jpg *.eps
+ @rm -f *.pdf *.aux *.cp *.fn *.ky *.log *.pg
+ @rm -f *.html *.backup *.ps *.dvi *.ilg *.lof *.lot
+ @rm -f *.cdx *.cnd *.ddx *.ddn *.fdx *.fnd *.ind *.sdx *.snd
+ @rm -f *.dnd imagename_translations
+ @rm -f *.old WARNINGS *.out *.toc *.idx
+ @rm -f ${DOC}i-*.tex
+ @rm -rf ${DOC}
+
+
+distclean: clean
+ @rm -f images.pl labels.pl internals.pl
+ @rm -f Makefile version.tex
--- /dev/null
+#
+#
+# Makefile for LaTeX
+#
+# To build everything do
+# make tex
+# make web
+# make html
+# make dvipdf
+#
+# or simply
+#
+# make
+#
+# for rapid development do:
+# make tex
+# make show
+#
+#
+# If you are having problems getting "make" to work, debugging it is
+# easier if can see the output from latex, which is normally redirected
+# to /dev/null. To see it, do the following:
+#
+# cd docs/manual
+# make tex
+# latex bacula.tex
+#
+# typically the latex command will stop indicating the error (e.g. a
+# missing \ in front of a _ or a missing { or ] ...
+#
+# The following characters must be preceded by a backslash
+# to be entered as printable characters:
+#
+# # $ % & ~ _ ^ \ { }
+#
+
+IMAGES=../../../images
+
+DOC=utility
+
+first_rule: all
+
+all: tex web dvipdf mini-clean
+
+.SUFFIXES: .tex .html
+.PHONY:
+.DONTCARE:
+
+
+tex:
+ @./update_version
+ @echo "Making version `cat version.tex`"
+ @cp -fp ${IMAGES}/hires/*.eps .
+ @touch ${DOC}i-dir.tex ${DOC}i-fd.tex ${DOC}i-sd.tex \
+ ${DOC}i-console.tex ${DOC}i-general.tex
+ latex -interaction=batchmode ${DOC}.tex
+ makeindex ${DOC}.idx -o ${DOC}.ind 2>/dev/null
+ latex -interaction=batchmode ${DOC}.tex
+
+pdf:
+ @echo "Making pdfm"
+ @cp -fp ${IMAGES}/hires/*.eps .
+ dvipdfm -p a4 ${DOC}.dvi
+
+dvipdf:
+ @echo "Making dvi to pdf"
+ @cp -fp ${IMAGES}/hires/*.eps .
+ dvipdf ${DOC}.dvi ${DOC}.pdf
+
+html:
+ @echo " "
+ @echo "Making html"
+ @cp -fp ${IMAGES}/*.eps .
+ @rm -f next.eps next.png prev.eps prev.png up.eps up.png
+ @(if [ -f imagename_translations ] ; then \
+ ./translate_images.pl --from_meaningful_names ${DOC}.html; \
+ fi)
+ latex2html -white -no_subdir -split 0 -toc_stars -white -notransparent \
+ -init_file latex2html-init.pl ${DOC} >tex.out 2>&1
+ ./translate_images.pl --to_meaningful_names ${DOC}.html
+ @echo "Done making html"
+
+web:
+ @echo "Making web"
+ @mkdir -p ${DOC}
+ @cp -fp ${IMAGES}/*.eps .
+ @rm -f next.eps next.png prev.eps prev.png up.eps up.png
+ @cp -fp ${IMAGES}/*.eps ${DOC}/
+ @cp -fp ${IMAGES}/*.eps ${IMAGES}/*.png ${DOC}/
+ @rm -f ${DOC}/xp-*.png
+ @rm -f ${DOC}/next.eps ${DOC}/next.png ${DOC}/prev.eps ${DOC}/prev.png ${DOC}/up.eps ${DOC}/up.png
+ @rm -rf ${DOC}/*.html
+ latex2html -split 3 -local_icons -t "Bacula Utility Programs" -long_titles 4 \
+ -toc_stars -contents_in_nav -init_file latex2html-init.pl -white -notransparent ${DOC} >tex.out 2>&1
+ ./translate_images.pl --to_meaningful_names ${DOC}/Bacula_Utilit*.html
+ @echo "Done making web"
+show:
+ xdvi ${DOC}
+
+texcheck:
+ ./check_tex.pl ${DOC}.tex
+
+main_configs:
+ pic2graph -density 100 <main_configs.pic >main_configs.png
+
+mini-clean:
+ @rm -f 1 2 3 *.tex~
+ @rm -f *.gif *.jpg *.eps
+ @rm -f *.aux *.cp *.fn *.ky *.log *.pg
+ @rm -f *.backup *.ilg *.lof *.lot
+ @rm -f *.cdx *.cnd *.ddx *.ddn *.fdx *.fnd *.ind *.sdx *.snd
+ @rm -f *.dnd *.old *.out
+ @rm -f ${DOC}/*.gif ${DOC}/*.jpg ${DOC}/*.eps
+ @rm -f ${DOC}/*.aux ${DOC}/*.cp ${DOC}/*.fn ${DOC}/*.ky ${DOC}/*.log ${DOC}/*.pg
+ @rm -f ${DOC}/*.backup ${DOC}/*.ilg ${DOC}/*.lof ${DOC}/*.lot
+ @rm -f ${DOC}/*.cdx ${DOC}/*.cnd ${DOC}/*.ddx ${DOC}/*.ddn ${DOC}/*.fdx ${DOC}/*.fnd ${DOC}/*.ind ${DOC}/*.sdx ${DOC}/*.snd
+ @rm -f ${DOC}/*.dnd ${DOC}/*.old ${DOC}/*.out
+ @rm -f ${DOC}/WARNINGS
+
+
+clean:
+ @rm -f 1 2 3 *.tex~
+ @rm -f *.png *.gif *.jpg *.eps
+ @rm -f *.pdf *.aux *.cp *.fn *.ky *.log *.pg
+ @rm -f *.html *.backup *.ps *.dvi *.ilg *.lof *.lot
+ @rm -f *.cdx *.cnd *.ddx *.ddn *.fdx *.fnd *.ind *.sdx *.snd
+ @rm -f *.dnd imagename_translations
+ @rm -f *.old WARNINGS *.out *.toc *.idx
+ @rm -f ${DOC}i-*.tex
+ @rm -rf ${DOC}
+
+
+distclean: clean
+ @rm -f images.pl labels.pl internals.pl
+ @rm -f Makefile version.tex
--- /dev/null
+%%
+%%
+%% The following characters must be preceded by a backslash
+%% to be entered as printable characters:
+%%
+%% # $ % & ~ _ ^ \ { }
+%%
+
+\section{bimagemgr}
+\label{bimagemgr}
+\index[general]{Bimagemgr }
+
+{\bf bimagemgr} is a utility for those who backup to disk volumes in order to
+commit them to CDR disk, rather than tapes. It is a web based interface
+written in Perl and is used to monitor when a volume file needs to be burned to
+disk. It requires:
+
+\begin{itemize}
+\item A web server running on the bacula server
+\item A CD recorder installed and configured on the bacula server
+\item The cdrtools package installed on the bacula server.
+\item perl, perl-DBI module, and either DBD-MySQL DBD-SQLite or DBD-PostgreSQL modules
+ \end{itemize}
+
+DVD burning is not supported by {\bf bimagemgr} at this
+time, but both are planned for future releases.
+
+\subsection{bimagemgr installation}
+\index[general]{bimagemgr!Installation }
+\index[general]{bimagemgr Installation }
+
+Installation from tarball:
+% TODO: use itemized list for this?
+1. Examine the Makefile and adjust it to your configuration if needed.
+2. Edit config.pm to fit your configuration.
+3. Do 'make install' as root.
+4. Edit httpd.conf and change the Timeout value. The web server must not time
+out and close the connection before the burn process is finished. The exact
+value needed may vary depending upon your cd recorder speed and whether you are
+burning on the bacula server on on another machine across your network. In my
+case I set it to 1000 seconds. Restart httpd.
+5. Make sure that cdrecord is setuid root.
+% TODO: I am pretty sure cdrecord can be used without setuid root
+% TODO: as long as devices are setup correctly
+
+Installation from rpm package:
+% TODO: use itemized list for this?
+1. Install the rpm package for your platform.
+2. Edit /cgi-bin/config.pm to fit your configuration.
+3. Edit httpd.conf and change the Timeout value. The web server must not time
+out and close the connection before the burn process is finished. The exact
+value needed may vary depending upon your cd recorder speed and whether you are
+burning on the bacula server on on another machine across your network. In my
+case I set it to 1000 seconds. Restart httpd.
+4. Make sure that cdrecord is setuid root.
+
+For bacula systems less than 1.36:
+% TODO: use itemized list for this?
+1. Edit the configuration section of config.pm to fit your configuration.
+2. Run /etc/bacula/create\_cdimage\_table.pl from a console on your bacula
+server (as root) to add the CDImage table to your bacula database.
+
+Accessing the Volume files:
+The Volume files by default have permissions 640 and can only be read by root.
+The recommended approach to this is as follows (and only works if bimagemgr and
+apache are running on the same host as bacula.
+
+For bacula-1.34 or 1.36 installed from tarball -
+% TODO: use itemized list for this?
+1. Create a new user group bacula and add the user apache to the group for
+Red Hat or Mandrake systems. For SuSE systems add the user wwwrun to the
+bacula group.
+2. Change ownership of all of your Volume files to root.bacula
+3. Edit the /etc/bacula/bacula startup script and set SD\_USER=root and
+SD\_GROUP=bacula. Restart bacula.
+
+Note: step 3 should also be done in /etc/init.d/bacula-sd but released versions
+of this file prior to 1.36 do not support it. In that case it would be necessary after
+a reboot of the server to execute '/etc/bacula/bacula restart'.
+
+For bacula-1.38 installed from tarball -
+% TODO: use itemized list for this?
+1. Your configure statement should include:
+% TODO: fix formatting here
+ --with-dir-user=bacula
+ --with-dir-group=bacula
+ --with-sd-user=bacula
+ --with-sd-group=disk
+ --with-fd-user=root
+ --with-fd-group=bacula
+2. Add the user apache to the bacula group for Red Hat or Mandrake systems.
+For SuSE systems add the user wwwrun to the bacula group.
+3. Check/change ownership of all of your Volume files to root.bacula
+
+For bacula-1.36 or bacula-1.38 installed from rpm -
+% TODO: use itemized list for this?
+1. Add the user apache to the group bacula for Red Hat or Mandrake systems.
+For SuSE systems add the user wwwrun to the bacula group.
+2. Check/change ownership of all of your Volume files to root.bacula
+
+bimagemgr installed from rpm > 1.38.9 will add the web server user to the
+bacula group in a post install script. Be sure to edit the configuration
+information in config.pm after installation of rpm package.
+
+bimagemgr will now be able to read the Volume files but they are still not
+world readable.
+
+If you are running bimagemgr on another host (not recommended) then you will
+need to change the permissions on all of your backup volume files to 644 in
+order to access them via nfs share or other means. This approach should only
+be taken if you are sure of the security of your environment as it exposes
+the backup Volume files to world read.
+
+\subsection{bimagemgr usage}
+\index[general]{bimagemgr!Usage }
+\index[general]{bimagemgr Usage }
+
+Calling the program in your web browser, e.g. {\tt
+http://localhost/cgi-bin/bimagemgr.pl} will produce a display as shown below
+% TODO: use tex to say figure number
+in Figure 1. The program will query the bacula database and display all volume
+files with the date last written and the date last burned to disk. If a volume
+needs to be burned (last written is newer than last burn date) a "Burn"
+button will be displayed in the rightmost column.
+
+\addcontentsline{lof}{figure}{Bacula CD Image Manager}
+\includegraphics{./bimagemgr1.eps} \\Figure 1
+% TODO: use tex to say figure number
+
+Place a blank CDR disk in your recorder and click the "Burn" button. This will
+cause a pop up window as shown in Figure 2 to display the burn progress.
+% TODO: use tex to say figure number
+
+\addcontentsline{lof}{figure}{Bacula CD Image Burn Progress Window}
+\includegraphics{./bimagemgr2.eps} \\Figure 2
+% TODO: use tex to say figure number
+
+When the burn finishes the pop up window will display the results of cdrecord
+% TODO: use tex to say figure number
+as shown in Figure 3. Close the pop up window and refresh the main window. The
+last burn date will be updated and the "Burn" button for that volume will
+disappear. Should you have a failed burn you can reset the last burn date of
+that volume by clicking its "Reset" link.
+
+\addcontentsline{lof}{figure}{Bacula CD Image Burn Results}
+\includegraphics{./bimagemgr3.eps} \\Figure 3
+% TODO: use tex to say figure number
+
+In the bottom row of the main display window are two more buttons labeled
+"Burn Catalog" and "Blank CDRW". "Burn Catalog" will place a copy of
+your bacula catalog on a disk. If you use CDRW disks rather than CDR then
+"Blank CDRW" allows you to erase the disk before re-burning it. Regularly
+committing your backup volume files and your catalog to disk with {\bf
+bimagemgr} ensures that you can rebuild easily in the event of some disaster
+on the bacula server itself.
--- /dev/null
+#!/usr/bin/perl -w
+# Finds potential problems in tex files, and issues warnings to the console
+# about what it finds. Takes a list of files as its only arguments,
+# and does checks on all the files listed. The assumption is that these are
+# valid (or close to valid) LaTeX files. It follows \include statements
+# recursively to pick up any included tex files.
+#
+#
+#
+# Currently the following checks are made:
+#
+# -- Multiple hyphens not inside a verbatim environment (or \verb). These
+# should be placed inside a \verb{} contruct so they will not be converted
+# to single hyphen by latex and latex2html.
+
+
+# Original creation 3-8-05 by Karl Cunningham karlc -at- keckec -dot- com
+#
+#
+
+use strict;
+
+# The following builds the test string to identify and change multiple
+# hyphens in the tex files. Several constructs are identified but only
+# multiple hyphens are changed; the others are fed to the output
+# unchanged.
+my $b = '\\\\begin\\*?\\s*\\{\\s*'; # \begin{
+my $e = '\\\\end\\*?\\s*\\{\\s*'; # \end{
+my $c = '\\s*\\}'; # closing curly brace
+
+# This captures entire verbatim environments. These are passed to the output
+# file unchanged.
+my $verbatimenv = $b . "verbatim" . $c . ".*?" . $e . "verbatim" . $c;
+
+# This captures \verb{..{ constructs. They are passed to the output unchanged.
+my $verb = '\\\\verb\\*?(.).*?\\1';
+
+# This captures multiple hyphens with a leading and trailing space. These are not changed.
+my $hyphsp = '\\s\\-{2,}\\s';
+
+# This identifies other multiple hyphens.
+my $hyphens = '\\-{2,}';
+
+# This identifies \hyperpage{..} commands, which should be ignored.
+my $hyperpage = '\\\\hyperpage\\*?\\{.*?\\}';
+
+# This builds the actual test string from the above strings.
+#my $teststr = "$verbatimenv|$verb|$tocentry|$hyphens";
+my $teststr = "$verbatimenv|$verb|$hyphsp|$hyperpage|$hyphens";
+
+
+sub get_includes {
+ # Get a list of include files from the top-level tex file. The first
+ # argument is a pointer to the list of files found. The rest of the
+ # arguments is a list of filenames to check for includes.
+ my $files = shift;
+ my ($fileline,$includefile,$includes);
+
+ while (my $filename = shift) {
+ # Get a list of all the html files in the directory.
+ open my $if,"<$filename" or die "Cannot open input file $filename\n";
+ $fileline = 0;
+ $includes = 0;
+ while (<$if>) {
+ chomp;
+ $fileline++;
+ # If a file is found in an include, process it.
+ if (($includefile) = /\\include\s*\{(.*?)\}/) {
+ $includes++;
+ # Append .tex to the filename
+ $includefile .= '.tex';
+
+ # If the include file has already been processed, issue a warning
+ # and don't do it again.
+ my $found = 0;
+ foreach (@$files) {
+ if ($_ eq $includefile) {
+ $found = 1;
+ last;
+ }
+ }
+ if ($found) {
+ print "$includefile found at line $fileline in $filename was previously included\n";
+ } else {
+ # The file has not been previously found. Save it and
+ # recursively process it.
+ push (@$files,$includefile);
+ get_includes($files,$includefile);
+ }
+ }
+ }
+ close IF;
+ }
+}
+
+
+sub check_hyphens {
+ my (@files) = @_;
+ my ($filedata,$this,$linecnt,$before);
+
+ # Build the test string to check for the various environments.
+ # We only do the conversion if the multiple hyphens are outside of a
+ # verbatim environment (either \begin{verbatim}...\end{verbatim} or
+ # \verb{--}). Capture those environments and pass them to the output
+ # unchanged.
+
+ foreach my $file (@files) {
+ # Open the file and load the whole thing into $filedata. A bit wasteful but
+ # easier to deal with, and we don't have a problem with speed here.
+ $filedata = "";
+ open IF,"<$file" or die "Cannot open input file $file";
+ while (<IF>) {
+ $filedata .= $_;
+ }
+ close IF;
+
+ # Set up to process the file data.
+ $linecnt = 1;
+
+ # Go through the file data from beginning to end. For each match, save what
+ # came before it and what matched. $filedata now becomes only what came
+ # after the match.
+ # Chech the match to see if it starts with a multiple-hyphen. If so
+ # warn the user. Keep track of line numbers so they can be output
+ # with the warning message.
+ while ($filedata =~ /$teststr/os) {
+ $this = $&;
+ $before = $`;
+ $filedata = $';
+ $linecnt += $before =~ tr/\n/\n/;
+
+ # Check if the multiple hyphen is present outside of one of the
+ # acceptable constructs.
+ if ($this =~ /^\-+/) {
+ print "Possible unwanted multiple hyphen found in line ",
+ "$linecnt of file $file\n";
+ }
+ $linecnt += $this =~ tr/\n/\n/;
+ }
+ }
+}
+##################################################################
+# MAIN ####
+##################################################################
+
+my (@includes,$cnt);
+
+# Examine the file pointed to by the first argument to get a list of
+# includes to test.
+get_includes(\@includes,@ARGV);
+
+check_hyphens(@includes);
--- /dev/null
+#
+# Avoid that @VERSION@ and @DATE@ are changed by configure
+# This file is sourced by update_version
+#
+echo "s%@VERSION@%${VERSION}%g" >${out}
+echo "s%@DATE@%${DATE}%g" >>${out}
--- /dev/null
+% TODO: maybe get rid of centering
+
+\chapter{GNU Free Documentation License}
+\index[general]{GNU Free Documentation License}
+\index[general]{License!GNU Free Documentation}
+
+\label{label_fdl}
+
+ \begin{center}
+
+ Version 1.2, November 2002
+
+
+ Copyright \copyright 2000,2001,2002 Free Software Foundation, Inc.
+
+ \bigskip
+
+ 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
+
+ \bigskip
+
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+\end{center}
+
+
+\begin{center}
+{\bf\large Preamble}
+\end{center}
+
+The purpose of this License is to make a manual, textbook, or other
+functional and useful document "free" in the sense of freedom: to
+assure everyone the effective freedom to copy and redistribute it,
+with or without modifying it, either commercially or noncommercially.
+Secondarily, this License preserves for the author and publisher a way
+to get credit for their work, while not being considered responsible
+for modifications made by others.
+
+This License is a kind of "copyleft", which means that derivative
+works of the document must themselves be free in the same sense. It
+complements the GNU General Public License, which is a copyleft
+license designed for free software.
+
+We have designed this License in order to use it for manuals for free
+software, because free software needs free documentation: a free
+program should come with manuals providing the same freedoms that the
+software does. But this License is not limited to software manuals;
+it can be used for any textual work, regardless of subject matter or
+whether it is published as a printed book. We recommend this License
+principally for works whose purpose is instruction or reference.
+
+
+\begin{center}
+{\Large\bf 1. APPLICABILITY AND DEFINITIONS}
+\end{center}
+
+This License applies to any manual or other work, in any medium, that
+contains a notice placed by the copyright holder saying it can be
+distributed under the terms of this License. Such a notice grants a
+world-wide, royalty-free license, unlimited in duration, to use that
+work under the conditions stated herein. The \textbf{"Document"}, below,
+refers to any such manual or work. Any member of the public is a
+licensee, and is addressed as \textbf{"you"}. You accept the license if you
+copy, modify or distribute the work in a way requiring permission
+under copyright law.
+
+A \textbf{"Modified Version"} of the Document means any work containing the
+Document or a portion of it, either copied verbatim, or with
+modifications and/or translated into another language.
+
+A \textbf{"Secondary Section"} is a named appendix or a front-matter section of
+the Document that deals exclusively with the relationship of the
+publishers or authors of the Document to the Document's overall subject
+(or to related matters) and contains nothing that could fall directly
+within that overall subject. (Thus, if the Document is in part a
+textbook of mathematics, a Secondary Section may not explain any
+mathematics.) The relationship could be a matter of historical
+connection with the subject or with related matters, or of legal,
+commercial, philosophical, ethical or political position regarding
+them.
+
+The \textbf{"Invariant Sections"} are certain Secondary Sections whose titles
+are designated, as being those of Invariant Sections, in the notice
+that says that the Document is released under this License. If a
+section does not fit the above definition of Secondary then it is not
+allowed to be designated as Invariant. The Document may contain zero
+Invariant Sections. If the Document does not identify any Invariant
+Sections then there are none.
+
+The \textbf{"Cover Texts"} are certain short passages of text that are listed,
+as Front-Cover Texts or Back-Cover Texts, in the notice that says that
+the Document is released under this License. A Front-Cover Text may
+be at most 5 words, and a Back-Cover Text may be at most 25 words.
+
+A \textbf{"Transparent"} copy of the Document means a machine-readable copy,
+represented in a format whose specification is available to the
+general public, that is suitable for revising the document
+straightforwardly with generic text editors or (for images composed of
+pixels) generic paint programs or (for drawings) some widely available
+drawing editor, and that is suitable for input to text formatters or
+for automatic translation to a variety of formats suitable for input
+to text formatters. A copy made in an otherwise Transparent file
+format whose markup, or absence of markup, has been arranged to thwart
+or discourage subsequent modification by readers is not Transparent.
+An image format is not Transparent if used for any substantial amount
+of text. A copy that is not "Transparent" is called \textbf{"Opaque"}.
+
+Examples of suitable formats for Transparent copies include plain
+ASCII without markup, Texinfo input format, LaTeX input format, SGML
+or XML using a publicly available DTD, and standard-conforming simple
+HTML, PostScript or PDF designed for human modification. Examples of
+transparent image formats include PNG, XCF and JPG. Opaque formats
+include proprietary formats that can be read and edited only by
+proprietary word processors, SGML or XML for which the DTD and/or
+processing tools are not generally available, and the
+machine-generated HTML, PostScript or PDF produced by some word
+processors for output purposes only.
+
+The \textbf{"Title Page"} means, for a printed book, the title page itself,
+plus such following pages as are needed to hold, legibly, the material
+this License requires to appear in the title page. For works in
+formats which do not have any title page as such, "Title Page" means
+the text near the most prominent appearance of the work's title,
+preceding the beginning of the body of the text.
+
+A section \textbf{"Entitled XYZ"} means a named subunit of the Document whose
+title either is precisely XYZ or contains XYZ in parentheses following
+text that translates XYZ in another language. (Here XYZ stands for a
+specific section name mentioned below, such as \textbf{"Acknowledgements"},
+\textbf{"Dedications"}, \textbf{"Endorsements"}, or \textbf{"History"}.)
+To \textbf{"Preserve the Title"}
+of such a section when you modify the Document means that it remains a
+section "Entitled XYZ" according to this definition.
+
+The Document may include Warranty Disclaimers next to the notice which
+states that this License applies to the Document. These Warranty
+Disclaimers are considered to be included by reference in this
+License, but only as regards disclaiming warranties: any other
+implication that these Warranty Disclaimers may have is void and has
+no effect on the meaning of this License.
+
+
+\begin{center}
+{\Large\bf 2. VERBATIM COPYING}
+\end{center}
+
+You may copy and distribute the Document in any medium, either
+commercially or noncommercially, provided that this License, the
+copyright notices, and the license notice saying this License applies
+to the Document are reproduced in all copies, and that you add no other
+conditions whatsoever to those of this License. You may not use
+technical measures to obstruct or control the reading or further
+copying of the copies you make or distribute. However, you may accept
+compensation in exchange for copies. If you distribute a large enough
+number of copies you must also follow the conditions in section 3.
+
+You may also lend copies, under the same conditions stated above, and
+you may publicly display copies.
+
+
+\begin{center}
+{\Large\bf 3. COPYING IN QUANTITY}
+\end{center}
+
+
+If you publish printed copies (or copies in media that commonly have
+printed covers) of the Document, numbering more than 100, and the
+Document's license notice requires Cover Texts, you must enclose the
+copies in covers that carry, clearly and legibly, all these Cover
+Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
+the back cover. Both covers must also clearly and legibly identify
+you as the publisher of these copies. The front cover must present
+the full title with all words of the title equally prominent and
+visible. You may add other material on the covers in addition.
+Copying with changes limited to the covers, as long as they preserve
+the title of the Document and satisfy these conditions, can be treated
+as verbatim copying in other respects.
+
+If the required texts for either cover are too voluminous to fit
+legibly, you should put the first ones listed (as many as fit
+reasonably) on the actual cover, and continue the rest onto adjacent
+pages.
+
+If you publish or distribute Opaque copies of the Document numbering
+more than 100, you must either include a machine-readable Transparent
+copy along with each Opaque copy, or state in or with each Opaque copy
+a computer-network location from which the general network-using
+public has access to download using public-standard network protocols
+a complete Transparent copy of the Document, free of added material.
+If you use the latter option, you must take reasonably prudent steps,
+when you begin distribution of Opaque copies in quantity, to ensure
+that this Transparent copy will remain thus accessible at the stated
+location until at least one year after the last time you distribute an
+Opaque copy (directly or through your agents or retailers) of that
+edition to the public.
+
+It is requested, but not required, that you contact the authors of the
+Document well before redistributing any large number of copies, to give
+them a chance to provide you with an updated version of the Document.
+
+
+\begin{center}
+{\Large\bf 4. MODIFICATIONS}
+\end{center}
+
+You may copy and distribute a Modified Version of the Document under
+the conditions of sections 2 and 3 above, provided that you release
+the Modified Version under precisely this License, with the Modified
+Version filling the role of the Document, thus licensing distribution
+and modification of the Modified Version to whoever possesses a copy
+of it. In addition, you must do these things in the Modified Version:
+
+\begin{itemize}
+\item[A.]
+ Use in the Title Page (and on the covers, if any) a title distinct
+ from that of the Document, and from those of previous versions
+ (which should, if there were any, be listed in the History section
+ of the Document). You may use the same title as a previous version
+ if the original publisher of that version gives permission.
+
+\item[B.]
+ List on the Title Page, as authors, one or more persons or entities
+ responsible for authorship of the modifications in the Modified
+ Version, together with at least five of the principal authors of the
+ Document (all of its principal authors, if it has fewer than five),
+ unless they release you from this requirement.
+
+\item[C.]
+ State on the Title page the name of the publisher of the
+ Modified Version, as the publisher.
+
+\item[D.]
+ Preserve all the copyright notices of the Document.
+
+\item[E.]
+ Add an appropriate copyright notice for your modifications
+ adjacent to the other copyright notices.
+
+\item[F.]
+ Include, immediately after the copyright notices, a license notice
+ giving the public permission to use the Modified Version under the
+ terms of this License, in the form shown in the Addendum below.
+
+\item[G.]
+ Preserve in that license notice the full lists of Invariant Sections
+ and required Cover Texts given in the Document's license notice.
+
+\item[H.]
+ Include an unaltered copy of this License.
+
+\item[I.]
+ Preserve the section Entitled "History", Preserve its Title, and add
+ to it an item stating at least the title, year, new authors, and
+ publisher of the Modified Version as given on the Title Page. If
+ there is no section Entitled "History" in the Document, create one
+ stating the title, year, authors, and publisher of the Document as
+ given on its Title Page, then add an item describing the Modified
+ Version as stated in the previous sentence.
+
+\item[J.]
+ Preserve the network location, if any, given in the Document for
+ public access to a Transparent copy of the Document, and likewise
+ the network locations given in the Document for previous versions
+ it was based on. These may be placed in the "History" section.
+ You may omit a network location for a work that was published at
+ least four years before the Document itself, or if the original
+ publisher of the version it refers to gives permission.
+
+\item[K.]
+ For any section Entitled "Acknowledgements" or "Dedications",
+ Preserve the Title of the section, and preserve in the section all
+ the substance and tone of each of the contributor acknowledgements
+ and/or dedications given therein.
+
+\item[L.]
+ Preserve all the Invariant Sections of the Document,
+ unaltered in their text and in their titles. Section numbers
+ or the equivalent are not considered part of the section titles.
+
+\item[M.]
+ Delete any section Entitled "Endorsements". Such a section
+ may not be included in the Modified Version.
+
+\item[N.]
+ Do not retitle any existing section to be Entitled "Endorsements"
+ or to conflict in title with any Invariant Section.
+
+\item[O.]
+ Preserve any Warranty Disclaimers.
+\end{itemize}
+
+If the Modified Version includes new front-matter sections or
+appendices that qualify as Secondary Sections and contain no material
+copied from the Document, you may at your option designate some or all
+of these sections as invariant. To do this, add their titles to the
+list of Invariant Sections in the Modified Version's license notice.
+These titles must be distinct from any other section titles.
+
+You may add a section Entitled "Endorsements", provided it contains
+nothing but endorsements of your Modified Version by various
+parties--for example, statements of peer review or that the text has
+been approved by an organization as the authoritative definition of a
+standard.
+
+You may add a passage of up to five words as a Front-Cover Text, and a
+passage of up to 25 words as a Back-Cover Text, to the end of the list
+of Cover Texts in the Modified Version. Only one passage of
+Front-Cover Text and one of Back-Cover Text may be added by (or
+through arrangements made by) any one entity. If the Document already
+includes a cover text for the same cover, previously added by you or
+by arrangement made by the same entity you are acting on behalf of,
+you may not add another; but you may replace the old one, on explicit
+permission from the previous publisher that added the old one.
+
+The author(s) and publisher(s) of the Document do not by this License
+give permission to use their names for publicity for or to assert or
+imply endorsement of any Modified Version.
+
+
+\begin{center}
+{\Large\bf 5. COMBINING DOCUMENTS}
+\end{center}
+
+
+You may combine the Document with other documents released under this
+License, under the terms defined in section 4 above for modified
+versions, provided that you include in the combination all of the
+Invariant Sections of all of the original documents, unmodified, and
+list them all as Invariant Sections of your combined work in its
+license notice, and that you preserve all their Warranty Disclaimers.
+
+The combined work need only contain one copy of this License, and
+multiple identical Invariant Sections may be replaced with a single
+copy. If there are multiple Invariant Sections with the same name but
+different contents, make the title of each such section unique by
+adding at the end of it, in parentheses, the name of the original
+author or publisher of that section if known, or else a unique number.
+Make the same adjustment to the section titles in the list of
+Invariant Sections in the license notice of the combined work.
+
+In the combination, you must combine any sections Entitled "History"
+in the various original documents, forming one section Entitled
+"History"; likewise combine any sections Entitled "Acknowledgements",
+and any sections Entitled "Dedications". You must delete all sections
+Entitled "Endorsements".
+
+\begin{center}
+{\Large\bf 6. COLLECTIONS OF DOCUMENTS}
+\end{center}
+
+You may make a collection consisting of the Document and other documents
+released under this License, and replace the individual copies of this
+License in the various documents with a single copy that is included in
+the collection, provided that you follow the rules of this License for
+verbatim copying of each of the documents in all other respects.
+
+You may extract a single document from such a collection, and distribute
+it individually under this License, provided you insert a copy of this
+License into the extracted document, and follow this License in all
+other respects regarding verbatim copying of that document.
+
+
+\begin{center}
+{\Large\bf 7. AGGREGATION WITH INDEPENDENT WORKS}
+\end{center}
+
+
+A compilation of the Document or its derivatives with other separate
+and independent documents or works, in or on a volume of a storage or
+distribution medium, is called an "aggregate" if the copyright
+resulting from the compilation is not used to limit the legal rights
+of the compilation's users beyond what the individual works permit.
+When the Document is included in an aggregate, this License does not
+apply to the other works in the aggregate which are not themselves
+derivative works of the Document.
+
+If the Cover Text requirement of section 3 is applicable to these
+copies of the Document, then if the Document is less than one half of
+the entire aggregate, the Document's Cover Texts may be placed on
+covers that bracket the Document within the aggregate, or the
+electronic equivalent of covers if the Document is in electronic form.
+Otherwise they must appear on printed covers that bracket the whole
+aggregate.
+
+
+\begin{center}
+{\Large\bf 8. TRANSLATION}
+\end{center}
+
+
+Translation is considered a kind of modification, so you may
+distribute translations of the Document under the terms of section 4.
+Replacing Invariant Sections with translations requires special
+permission from their copyright holders, but you may include
+translations of some or all Invariant Sections in addition to the
+original versions of these Invariant Sections. You may include a
+translation of this License, and all the license notices in the
+Document, and any Warranty Disclaimers, provided that you also include
+the original English version of this License and the original versions
+of those notices and disclaimers. In case of a disagreement between
+the translation and the original version of this License or a notice
+or disclaimer, the original version will prevail.
+
+If a section in the Document is Entitled "Acknowledgements",
+"Dedications", or "History", the requirement (section 4) to Preserve
+its Title (section 1) will typically require changing the actual
+title.
+
+
+\begin{center}
+{\Large\bf 9. TERMINATION}
+\end{center}
+
+
+You may not copy, modify, sublicense, or distribute the Document except
+as expressly provided for under this License. Any other attempt to
+copy, modify, sublicense or distribute the Document is void, and will
+automatically terminate your rights under this License. However,
+parties who have received copies, or rights, from you under this
+License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
+
+\begin{center}
+{\Large\bf 10. FUTURE REVISIONS OF THIS LICENSE}
+\end{center}
+
+
+The Free Software Foundation may publish new, revised versions
+of the GNU Free Documentation License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns. See
+http://www.gnu.org/copyleft/.
+
+Each version of the License is given a distinguishing version number.
+If the Document specifies that a particular numbered version of this
+License "or any later version" applies to it, you have the option of
+following the terms and conditions either of that specified version or
+of any later version that has been published (not as a draft) by the
+Free Software Foundation. If the Document does not specify a version
+number of this License, you may choose any version ever published (not
+as a draft) by the Free Software Foundation.
+
+
+\begin{center}
+{\Large\bf ADDENDUM: How to use this License for your documents}
+% TODO: this is too long for table of contents
+\end{center}
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and
+license notices just after the title page:
+
+\bigskip
+\begin{quote}
+ Copyright \copyright YEAR YOUR NAME.
+ Permission is granted to copy, distribute and/or modify this document
+ under the terms of the GNU Free Documentation License, Version 1.2
+ or any later version published by the Free Software Foundation;
+ with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+ A copy of the license is included in the section entitled "GNU
+ Free Documentation License".
+\end{quote}
+\bigskip
+
+If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
+replace the "with...Texts." line with this:
+
+\bigskip
+\begin{quote}
+ with the Invariant Sections being LIST THEIR TITLES, with the
+ Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
+\end{quote}
+\bigskip
+
+If you have Invariant Sections without Cover Texts, or some other
+combination of the three, merge those two alternatives to suit the
+situation.
+
+If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of
+free software license, such as the GNU General Public License,
+to permit their use in free software.
+
+%---------------------------------------------------------------------
--- /dev/null
+#!/usr/bin/perl -w
+# Fixes various things within tex files.
+
+use strict;
+
+my %args;
+
+
+sub get_includes {
+ # Get a list of include files from the top-level tex file.
+ my (@list,$file);
+
+ foreach my $filename (@_) {
+ $filename or next;
+ # Start with the top-level latex file so it gets checked too.
+ push (@list,$filename);
+
+ # Get a list of all the html files in the directory.
+ open IF,"<$filename" or die "Cannot open input file $filename";
+ while (<IF>) {
+ chomp;
+ push @list,"$1.tex" if (/\\include\{(.*?)\}/);
+ }
+
+ close IF;
+ }
+ return @list;
+}
+
+sub convert_files {
+ my (@files) = @_;
+ my ($linecnt,$filedata,$output,$itemcnt,$indentcnt,$cnt);
+
+ $cnt = 0;
+ foreach my $file (@files) {
+ # Open the file and load the whole thing into $filedata. A bit wasteful but
+ # easier to deal with, and we don't have a problem with speed here.
+ $filedata = "";
+ open IF,"<$file" or die "Cannot open input file $file";
+ while (<IF>) {
+ $filedata .= $_;
+ }
+ close IF;
+
+ # We look for a line that starts with \item, and indent the two next lines (if not blank)
+ # by three spaces.
+ my $linecnt = 3;
+ $indentcnt = 0;
+ $output = "";
+ # Process a line at a time.
+ foreach (split(/\n/,$filedata)) {
+ $_ .= "\n"; # Put back the return.
+ # If this line is less than the third line past the \item command,
+ # and the line isn't blank and doesn't start with whitespace
+ # add three spaces to the start of the line. Keep track of the number
+ # of lines changed.
+ if ($linecnt < 3 and !/^\\item/) {
+ if (/^[^\n\s]/) {
+ $output .= " " . $_;
+ $indentcnt++;
+ } else {
+ $output .= $_;
+ }
+ $linecnt++;
+ } else {
+ $linecnt = 3;
+ $output .= $_;
+ }
+ /^\\item / and $linecnt = 1;
+ }
+
+
+ # This is an item line. We need to process it too. If inside a \begin{description} environment, convert
+ # \item {\bf xxx} to \item [xxx] or \item [{xxx}] (if xxx contains '[' or ']'.
+ $itemcnt = 0;
+ $filedata = $output;
+ $output = "";
+ my ($before,$descrip,$this,$between);
+
+ # Find any \begin{description} environment
+ while ($filedata =~ /(\\begin[\s\n]*\{[\s\n]*description[\s\n]*\})(.*?)(\\end[\s\n]*\{[\s\n]*description[\s\n]*\})/s) {
+ $output .= $` . $1;
+ $filedata = $3 . $';
+ $descrip = $2;
+
+ # Search for \item {\bf xxx}
+ while ($descrip =~ /\\item[\s\n]*\{[\s\n]*\\bf[\s\n]*/s) {
+ $descrip = $';
+ $output .= $`;
+ ($between,$descrip) = find_matching_brace($descrip);
+ if (!$descrip) {
+ $linecnt = $output =~ tr/\n/\n/;
+ print STDERR "Missing matching curly brace at line $linecnt in $file\n" if (!$descrip);
+ }
+
+ # Now do the replacement.
+ $between = '{' . $between . '}' if ($between =~ /\[|\]/);
+ $output .= "\\item \[$between\]";
+ $itemcnt++;
+ }
+ $output .= $descrip;
+ }
+ $output .= $filedata;
+
+ # If any hyphens or \item commnads were converted, save the file.
+ if ($indentcnt or $itemcnt) {
+ open OF,">$file" or die "Cannot open output file $file";
+ print OF $output;
+ close OF;
+ print "$indentcnt indent", ($indentcnt == 1) ? "" : "s"," added in $file\n";
+ print "$itemcnt item", ($itemcnt == 1) ? "" : "s"," Changed in $file\n";
+ }
+
+ $cnt += $indentcnt + $itemcnt;
+ }
+ return $cnt;
+}
+
+sub find_matching_brace {
+ # Finds text up to the next matching brace. Assumes that the input text doesn't contain
+ # the opening brace, but we want to find text up to a matching closing one.
+ # Returns the text between the matching braces, followed by the rest of the text following
+ # (which does not include the matching brace).
+ #
+ my $str = shift;
+ my ($this,$temp);
+ my $cnt = 1;
+
+ while ($cnt) {
+ # Ignore verbatim constructs involving curly braces, or if the character preceding
+ # the curly brace is a backslash.
+ if ($str =~ /\\verb\*?\{.*?\{|\\verb\*?\}.*?\}|\{|\}/s) {
+ $this .= $`;
+ $str = $';
+ $temp = $&;
+
+ if ((substr($this,-1,1) eq '\\') or
+ $temp =~ /^\\verb/) {
+ $this .= $temp;
+ next;
+ }
+
+ $cnt += ($temp eq '{') ? 1 : -1;
+ # If this isn't the matching curly brace ($cnt > 0), include the brace.
+ $this .= $temp if ($cnt);
+ } else {
+ # No matching curly brace found.
+ return ($this . $str,'');
+ }
+ }
+ return ($this,$str);
+}
+
+sub check_arguments {
+ # Checks command-line arguments for ones starting with -- puts them into
+ # a hash called %args and removes them from @ARGV.
+ my $args = shift;
+ my $i;
+
+ for ($i = 0; $i < $#ARGV; $i++) {
+ $ARGV[$i] =~ /^\-+/ or next;
+ $ARGV[$i] =~ s/^\-+//;
+ $args{$ARGV[$i]} = "";
+ delete ($ARGV[$i]);
+
+ }
+}
+
+##################################################################
+# MAIN ####
+##################################################################
+
+my @includes;
+my $cnt;
+
+check_arguments(\%args);
+die "No Files given to Check\n" if ($#ARGV < 0);
+
+# Examine the file pointed to by the first argument to get a list of
+# includes to test.
+@includes = get_includes(@ARGV);
+
+$cnt = convert_files(@includes);
+print "No lines changed\n" unless $cnt;
--- /dev/null
+# This module does multiple indices, supporting the style of the LaTex 'index'
+# package.
+
+# Version Information:
+# 16-Feb-2005 -- Original Creation. Karl E. Cunningham
+# 14-Mar-2005 -- Clarified and Consolodated some of the code.
+# Changed to smoothly handle single and multiple indices.
+
+# Two LaTeX index formats are supported...
+# --- SINGLE INDEX ---
+# \usepackage{makeidx}
+# \makeindex
+# \index{entry1}
+# \index{entry2}
+# \index{entry3}
+# ...
+# \printindex
+#
+# --- MULTIPLE INDICES ---
+#
+# \usepackage{makeidx}
+# \usepackage{index}
+# \makeindex -- latex2html doesn't care but LaTeX does.
+# \newindex{ref1}{ext1}{ext2}{title1}
+# \newindex{ref2}{ext1}{ext2}{title2}
+# \newindex{ref3}{ext1}{ext2}{title3}
+# \index[ref1]{entry1}
+# \index[ref1]{entry2}
+# \index[ref3]{entry3}
+# \index[ref2]{entry4}
+# \index{entry5}
+# \index[ref3]{entry6}
+# ...
+# \printindex[ref1]
+# \printindex[ref2]
+# \printindex[ref3]
+# \printindex
+# ___________________
+#
+# For the multiple-index style, each index is identified by the ref argument to \newindex, \index,
+# and \printindex. A default index is allowed, which is indicated by omitting the optional
+# argument. The default index does not require a \newindex command. As \index commands
+# are encountered, their entries are stored according
+# to the ref argument. When the \printindex command is encountered, the stored index
+# entries for that argument are retrieved and printed. The title for each index is taken
+# from the last argument in the \newindex command.
+# While processing \index and \printindex commands, if no argument is given the index entries
+# are built into a default index. The title of the default index is simply "Index".
+# This makes the difference between single- and multiple-index processing trivial.
+#
+# Another method can be used by omitting the \printindex command and just using \include to
+# pull in index files created by the makeindex program. These files will start with
+# \begin{theindex}. This command is used to determine where to print the index. Using this
+# approach, the indices will be output in the same order as the newindex commands were
+# originally found (see below). Using a combination of \printindex and \include{indexfile} has not
+# been tested and may produce undesireable results.
+#
+# The index data are stored in a hash for later sorting and output. As \printindex
+# commands are handled, the order in which they were found in the tex filea is saved,
+# associated with the ref argument to \printindex.
+#
+# We use the original %index hash to store the index data into. We append a \002 followed by the
+# name of the index to isolate the entries in different indices from each other. This is necessary
+# so that different indices can have entries with the same name. For the default index, the \002 is
+# appended without the name.
+#
+# Since the index order in the output cannot be determined if the \include{indexfile}
+# command is used, the order will be assumed from the order in which the \newindex
+# commands were originally seen in the TeX files. This order is saved as well as the
+# order determined from any printindex{ref} commands. If \printindex commnads are used
+# to specify the index output, that order will be used. If the \include{idxfile} command
+# is used, the order of the original newindex commands will be used. In this case the
+# default index will be printed last since it doesn't have a corresponding \newindex
+# command and its order cannot be determined. Mixing \printindex and \include{idxfile}
+# commands in the same file is likely to produce less than satisfactory results.
+#
+#
+# The hash containing index data is named %indices. It contains the following data:
+#{
+# 'title' => {
+# $ref1 => $indextitle ,
+# $ref2 => $indextitle ,
+# ...
+# },
+# 'newcmdorder' => [ ref1, ref2, ..., * ], # asterisk indicates the position of the default index.
+# 'printindorder' => [ ref1, ref2, ..., * ], # asterisk indicates the position of the default index.
+#}
+
+
+# Globals to handle multiple indices.
+my %indices;
+
+# This tells the system to use up to 7 words in index entries.
+$WORDS_IN_INDEX = 10;
+
+# KEC 2-18-05
+# Handles the \newindex command. This is called if the \newindex command is
+# encountered in the LaTex source. Gets the index ref and title from the arguments.
+# Saves the index ref and title.
+# Note that we are called once to handle multiple \newindex commands that are
+# newline-separated.
+sub do_cmd_newindex {
+ my $data = shift;
+ # The data is sent to us as fields delimited by their ID #'s. We extract the
+ # fields.
+ foreach my $line (split("\n",$data)) {
+ my @fields = split (/(?:\<\#\d+?\#\>)+/,$line);
+
+ # The index name and title are the second and fourth fields in the data.
+ if ($line =~ /^</ or $line =~ /^\\newindex/) {
+ my ($indexref,$indextitle) = ($fields[1],$fields[4]);
+ $indices{'title'}{$indexref} = $indextitle;
+ push (@{$indices{'newcmdorder'}},$indexref);
+ }
+ }
+}
+
+
+# KEC -- Copied from makeidx.perl and modified to do multiple indices.
+# Processes an \index entry from the LaTex file.
+# Gets the optional argument from the index command, which is the name of the index
+# into which to place the entry.
+# Drops the brackets from the index_name
+# Puts the index entry into the html stream
+# Creates the tokenized index entry (which also saves the index entry info
+sub do_real_index {
+ local($_) = @_;
+ local($pat,$idx_entry,$index_name);
+ # catches opt-arg from \index commands for index.sty
+ $index_name = &get_next_optional_argument;
+ $index_name = "" unless defined $index_name;
+ # Drop leading and trailing brackets from the index name.
+ $index_name =~ s/^\[|\]$//g;
+
+ $idx_entry = &missing_braces unless (
+ (s/$next_pair_pr_rx/$pat=$1;$idx_entry=$2;''/e)
+ ||(s/$next_pair_rx/$pat=$1;$idx_entry=$2;''/e));
+
+ if ($index_name and defined $idx_entry and
+ !defined $indices{'title'}{$index_name}) {
+ print STDERR "\nInvalid Index Name: \\index \[$index_name\]\{$idx_entry\}\n";
+ }
+
+ $idx_entry = &named_index_entry($pat, $idx_entry,$index_name);
+ $idx_entry.$_;
+}
+
+# Creates and saves an index entry in the index hashes.
+# Modified to do multiple indices.
+# Creates an index_key that allows index entries to have the same characteristics but be in
+# different indices. This index_key is the regular key with the index name appended.
+# Save the index order for the entry in the %index_order hash.
+sub named_index_entry {
+ local($br_id, $str, $index_name) = @_;
+ my ($index_key);
+ # escape the quoting etc characters
+ # ! -> \001
+ # @ -> \002
+ # | -> \003
+ $* = 1; $str =~ s/\n\s*/ /g; $* = 0; # remove any newlines
+ # protect \001 occurring with images
+ $str =~ s/\001/\016/g; # 0x1 to 0xF
+ $str =~ s/\\\\/\011/g; # Double backslash -> 0xB
+ $str =~ s/\\;SPMquot;/\012/g; # \;SPMquot; -> 0xC
+ $str =~ s/;SPMquot;!/\013/g; # ;SPMquot; -> 0xD
+ $str =~ s/!/\001/g; # Exclamation point -> 0x1
+ $str =~ s/\013/!/g; # 0xD -> Exclaimation point
+ $str =~ s/;SPMquot;@/\015/g; # ;SPMquot;@ to 0xF
+ $str =~ s/@/\002/g; # At sign -> 0x2
+ $str =~ s/\015/@/g; # 0xF to At sign
+ $str =~ s/;SPMquot;\|/\017/g; # ;SMPquot;| to 0x11
+ $str =~ s/\|/\003/g; # Vertical line to 0x3
+ $str =~ s/\017/|/g; # 0x11 to vertical line
+ $str =~ s/;SPMquot;(.)/\1/g; # ;SPMquot; -> whatever the next character is
+ $str =~ s/\012/;SPMquot;/g; # 0x12 to ;SPMquot;
+ $str =~ s/\011/\\\\/g; # 0x11 to double backslash
+ local($key_part, $pageref) = split("\003", $str, 2);
+
+ # For any keys of the form: blablabla!blablabla, which want to be split at the
+ # exclamation point, replace the ! with a comma and a space. We don't do it
+ # that way for this index.
+ $key_part =~ s/\001/, /g;
+ local(@keys) = split("\001", $key_part);
+ # If TITLE is not yet available use $before.
+ $TITLE = $saved_title if (($saved_title)&&(!($TITLE)||($TITLE eq $default_title)));
+ $TITLE = $before unless $TITLE;
+ # Save the reference
+ local($words) = '';
+ if ($SHOW_SECTION_NUMBERS) { $words = &make_idxnum; }
+ elsif ($SHORT_INDEX) { $words = &make_shortidxname; }
+ else { $words = &make_idxname; }
+ local($super_key) = '';
+ local($sort_key, $printable_key, $cur_key);
+ foreach $key (@keys) {
+ $key =~ s/\016/\001/g; # revert protected \001s
+ ($sort_key, $printable_key) = split("\002", $key);
+ #
+ # RRM: 16 May 1996
+ # any \label in the printable-key will have already
+ # created a label where the \index occurred.
+ # This has to be removed, so that the desired label
+ # will be found on the Index page instead.
+ #
+ if ($printable_key =~ /tex2html_anchor_mark/ ) {
+ $printable_key =~ s/><tex2html_anchor_mark><\/A><A//g;
+ local($tmpA,$tmpB) = split("NAME=\"", $printable_key);
+ ($tmpA,$tmpB) = split("\"", $tmpB);
+ $ref_files{$tmpA}='';
+ $index_labels{$tmpA} = 1;
+ }
+ #
+ # resolve and clean-up the hyperlink index-entries
+ # so they can be saved in an index.pl file
+ #
+ if ($printable_key =~ /$cross_ref_mark/ ) {
+ local($label,$id,$ref_label);
+ # $printable_key =~ s/$cross_ref_mark#(\w+)#(\w+)>$cross_ref_mark/
+ $printable_key =~ s/$cross_ref_mark#([^#]+)#([^>]+)>$cross_ref_mark/
+ do { ($label,$id) = ($1,$2);
+ $ref_label = $external_labels{$label} unless
+ ($ref_label = $ref_files{$label});
+ '"' . "$ref_label#$label" . '">' .
+ &get_ref_mark($label,$id)}
+ /geo;
+ }
+ $printable_key =~ s/<\#[^\#>]*\#>//go;
+ #RRM
+ # recognise \char combinations, for a \backslash
+ #
+ $printable_key =~ s/\&\#;\'134/\\/g; # restore \\s
+ $printable_key =~ s/\&\#;\`<BR> /\\/g; # ditto
+ $printable_key =~ s/\&\#;*SPMquot;92/\\/g; # ditto
+ #
+ # $sort_key .= "@$printable_key" if !($printable_key); # RRM
+ $sort_key .= "@$printable_key" if !($sort_key); # RRM
+ $sort_key =~ tr/A-Z/a-z/;
+ if ($super_key) {
+ $cur_key = $super_key . "\001" . $sort_key;
+ $sub_index{$super_key} .= $cur_key . "\004";
+ } else {
+ $cur_key = $sort_key;
+ }
+
+ # Append the $index_name to the current key with a \002 delimiter. This will
+ # allow the same index entry to appear in more than one index.
+ $index_key = $cur_key . "\002$index_name";
+
+ $index{$index_key} .= "";
+
+ #
+ # RRM, 15 June 1996
+ # if there is no printable key, but one is known from
+ # a previous index-entry, then use it.
+ #
+ if (!($printable_key) && ($printable_key{$index_key}))
+ { $printable_key = $printable_key{$index_key}; }
+# if (!($printable_key) && ($printable_key{$cur_key}))
+# { $printable_key = $printable_key{$cur_key}; }
+ #
+ # do not overwrite the printable_key if it contains an anchor
+ #
+ if (!($printable_key{$index_key} =~ /tex2html_anchor_mark/ ))
+ { $printable_key{$index_key} = $printable_key || $key; }
+# if (!($printable_key{$cur_key} =~ /tex2html_anchor_mark/ ))
+# { $printable_key{$cur_key} = $printable_key || $key; }
+
+ $super_key = $cur_key;
+ }
+ #
+ # RRM
+ # page-ranges, from |( and |) and |see
+ #
+ if ($pageref) {
+ if ($pageref eq "\(" ) {
+ $pageref = '';
+ $next .= " from ";
+ } elsif ($pageref eq "\)" ) {
+ $pageref = '';
+ local($next) = $index{$index_key};
+# local($next) = $index{$cur_key};
+ # $next =~ s/[\|] *$//;
+ $next =~ s/(\n )?\| $//;
+ $index{$index_key} = "$next to ";
+# $index{$cur_key} = "$next to ";
+ }
+ }
+
+ if ($pageref) {
+ $pageref =~ s/\s*$//g; # remove trailing spaces
+ if (!$pageref) { $pageref = ' ' }
+ $pageref =~ s/see/<i>see <\/i> /g;
+ #
+ # RRM: 27 Dec 1996
+ # check if $pageref corresponds to a style command.
+ # If so, apply it to the $words.
+ #
+ local($tmp) = "do_cmd_$pageref";
+ if (defined &$tmp) {
+ $words = &$tmp("<#0#>$words<#0#>");
+ $words =~ s/<\#[^\#]*\#>//go;
+ $pageref = '';
+ }
+ }
+ #
+ # RRM: 25 May 1996
+ # any \label in the pageref section will have already
+ # created a label where the \index occurred.
+ # This has to be removed, so that the desired label
+ # will be found on the Index page instead.
+ #
+ if ($pageref) {
+ if ($pageref =~ /tex2html_anchor_mark/ ) {
+ $pageref =~ s/><tex2html_anchor_mark><\/A><A//g;
+ local($tmpA,$tmpB) = split("NAME=\"", $pageref);
+ ($tmpA,$tmpB) = split("\"", $tmpB);
+ $ref_files{$tmpA}='';
+ $index_labels{$tmpA} = 1;
+ }
+ #
+ # resolve and clean-up any hyperlinks in the page-ref,
+ # so they can be saved in an index.pl file
+ #
+ if ($pageref =~ /$cross_ref_mark/ ) {
+ local($label,$id,$ref_label);
+ # $pageref =~ s/$cross_ref_mark#(\w+)#(\w+)>$cross_ref_mark/
+ $pageref =~ s/$cross_ref_mark#([^#]+)#([^>]+)>$cross_ref_mark/
+ do { ($label,$id) = ($1,$2);
+ $ref_files{$label} = ''; # ???? RRM
+ if ($index_labels{$label}) { $ref_label = ''; }
+ else { $ref_label = $external_labels{$label}
+ unless ($ref_label = $ref_files{$label});
+ }
+ '"' . "$ref_label#$label" . '">' . &get_ref_mark($label,$id)}/geo;
+ }
+ $pageref =~ s/<\#[^\#>]*\#>//go;
+
+ if ($pageref eq ' ') { $index{$index_key}='@'; }
+ else { $index{$index_key} .= $pageref . "\n | "; }
+ } else {
+ local($thisref) = &make_named_href('',"$CURRENT_FILE#$br_id",$words);
+ $thisref =~ s/\n//g;
+ $index{$index_key} .= $thisref."\n | ";
+ }
+ #print "\nREF: $sort_key : $index_key :$index{$index_key}";
+
+ #join('',"<A NAME=$br_id>$anchor_invisible_mark<\/A>",$_);
+
+ "<A NAME=\"$br_id\">$anchor_invisible_mark<\/A>";
+}
+
+
+# KEC. -- Copied from makeidx.perl, then modified to do multiple indices.
+# Feeds the index entries to the output. This is called for each index to be built.
+#
+# Generates a list of lookup keys for index entries, from both %printable_keys
+# and %index keys.
+# Sorts the keys according to index-sorting rules.
+# Removes keys with a 0x01 token. (duplicates?)
+# Builds a string to go to the index file.
+# Adds the index entries to the string if they belong in this index.
+# Keeps track of which index is being worked on, so only the proper entries
+# are included.
+# Places the index just built in to the output at the proper place.
+{ my $index_number = 0;
+sub add_real_idx {
+ print "\nDoing the index ... Index Number $index_number\n";
+ local($key, @keys, $next, $index, $old_key, $old_html);
+ my ($idx_ref,$keyref);
+ # RRM, 15.6.96: index constructed from %printable_key, not %index
+ @keys = keys %printable_key;
+
+ while (/$idx_mark/) {
+ # Get the index reference from what follows the $idx_mark and
+ # remove it from the string.
+ s/$idxmark\002(.*?)\002/$idxmark/;
+ $idx_ref = $1;
+ $index = '';
+ # include non- makeidx index-entries
+ foreach $key (keys %index) {
+ next if $printable_key{$key};
+ $old_key = $key;
+ if ($key =~ s/###(.*)$//) {
+ next if $printable_key{$key};
+ push (@keys, $key);
+ $printable_key{$key} = $key;
+ if ($index{$old_key} =~ /HREF="([^"]*)"/i) {
+ $old_html = $1;
+ $old_html =~ /$dd?([^#\Q$dd\E]*)#/;
+ $old_html = $1;
+ } else { $old_html = '' }
+ $index{$key} = $index{$old_key} . $old_html."</A>\n | ";
+ };
+ }
+ @keys = sort makeidx_keysort @keys;
+ @keys = grep(!/\001/, @keys);
+ my $cnt = 0;
+ foreach $key (@keys) {
+ my ($keyref) = $key =~ /.*\002(.*)/;
+ next unless ($idx_ref eq $keyref); # KEC.
+ $index .= &add_idx_key($key);
+ $cnt++;
+ }
+ print "$cnt Index Entries Added\n";
+ $index = '<DD>'.$index unless ($index =~ /^\s*<D(D|T)>/);
+ $index_number++; # KEC.
+ if ($SHORT_INDEX) {
+ print "(compact version with Legend)";
+ local($num) = ( $index =~ s/\<D/<D/g );
+ if ($num > 50 ) {
+ s/$idx_mark/$preindex<HR><DL>\n$index\n<\/DL>$preindex/o;
+ } else {
+ s/$idx_mark/$preindex<HR><DL>\n$index\n<\/DL>/o;
+ }
+ } else {
+ s/$idx_mark/<DL COMPACT>\n$index\n<\/DL>/o; }
+ }
+}
+}
+
+# KEC. Copied from latex2html.pl and modified to support multiple indices.
+# The bibliography and the index should be treated as separate sections
+# in their own HTML files. The \bibliography{} command acts as a sectioning command
+# that has the desired effect. But when the bibliography is constructed
+# manually using the thebibliography environment, or when using the
+# theindex environment it is not possible to use the normal sectioning
+# mechanism. This subroutine inserts a \bibliography{} or a dummy
+# \textohtmlindex command just before the appropriate environments
+# to force sectioning.
+sub add_bbl_and_idx_dummy_commands {
+ local($id) = $global{'max_id'};
+
+ s/([\\]begin\s*$O\d+$C\s*thebibliography)/$bbl_cnt++; $1/eg;
+ ## if ($bbl_cnt == 1) {
+ s/([\\]begin\s*$O\d+$C\s*thebibliography)/$id++; "\\bibliography$O$id$C$O$id$C $1"/geo;
+ #}
+ $global{'max_id'} = $id;
+ # KEC. Modified to global substitution to place multiple index tokens.
+ s/[\\]begin\s*($O\d+$C)\s*theindex/\\textohtmlindex$1/go;
+ # KEC. Modified to pick up the optional argument to \printindex
+ s/[\\]printindex\s*(\[.*?\])?/
+ do { (defined $1) ? "\\textohtmlindex $1" : "\\textohtmlindex []"; } /ego;
+ &lib_add_bbl_and_idx_dummy_commands() if defined(&lib_add_bbl_and_idx_dummy_commands);
+}
+
+# KEC. Copied from latex2html.pl and modified to support multiple indices.
+# For each textohtmlindex mark found, determine the index titles and headers.
+# We place the index ref in the header so the proper index can be generated later.
+# For the default index, the index ref is blank.
+#
+# One problem is that this routine is called twice.. Once for processing the
+# command as originally seen, and once for processing the command when
+# doing the name for the index file. We can detect that by looking at the
+# id numbers (or ref) surrounding the \theindex command, and not incrementing
+# index_number unless a new id (or ref) is seen. This has the side effect of
+# having to unconventionally start the index_number at -1. But it works.
+#
+# Gets the title from the list of indices.
+# If this is the first index, save the title in $first_idx_file. This is what's referenced
+# in the navigation buttons.
+# Increment the index_number for next time.
+# If the indexname command is defined or a newcommand defined for indexname, do it.
+# Save the index TITLE in the toc
+# Save the first_idx_file into the idxfile. This goes into the nav buttons.
+# Build index_labels if needed.
+# Create the index headings and put them in the output stream.
+
+{ my $index_number = 0; # Will be incremented before use.
+ my $first_idx_file; # Static
+ my $no_increment = 0;
+
+sub do_cmd_textohtmlindex {
+ local($_) = @_;
+ my ($idxref,$idxnum,$index_name);
+
+ # We get called from make_name with the first argument = "\001noincrement". This is a sign
+ # to not increment $index_number the next time we are called. We get called twice, once
+ # my make_name and once by process_command. Unfortunately, make_name calls us just to set the name
+ # but doesn't use the result so we get called a second time by process_command. This works fine
+ # except for cases where there are multiple indices except if they aren't named, which is the case
+ # when the index is inserted by an include command in latex. In these cases we are only able to use
+ # the index number to decide which index to draw from, and we don't know how to increment that index
+ # number if we get called a variable number of times for the same index, as is the case between
+ # making html (one output file) and web (multiple output files) output formats.
+ if (/\001noincrement/) {
+ $no_increment = 1;
+ return;
+ }
+
+ # Remove (but save) the index reference
+ s/^\s*\[(.*?)\]/{$idxref = $1; "";}/e;
+
+ # If we have an $idxref, the index name was specified. In this case, we have all the
+ # information we need to carry on. Otherwise, we need to get the idxref
+ # from the $index_number and set the name to "Index".
+ if ($idxref) {
+ $index_name = $indices{'title'}{$idxref};
+ } else {
+ if (defined ($idxref = $indices{'newcmdorder'}->[$index_number])) {
+ $index_name = $indices{'title'}{$idxref};
+ } else {
+ $idxref = '';
+ $index_name = "Index";
+ }
+ }
+
+ $idx_title = "Index"; # The name displayed in the nav bar text.
+
+ # Only set $idxfile if we are at the first index. This will point the
+ # navigation panel to the first index file rather than the last.
+ $first_idx_file = $CURRENT_FILE if ($index_number == 0);
+ $idxfile = $first_idx_file; # Pointer for the Index button in the nav bar.
+ $toc_sec_title = $index_name; # Index link text in the toc.
+ $TITLE = $toc_sec_title; # Title for this index, from which its filename is built.
+ if (%index_labels) { &make_index_labels(); }
+ if (($SHORT_INDEX) && (%index_segment)) { &make_preindex(); }
+ else { $preindex = ''; }
+ local $idx_head = $section_headings{'textohtmlindex'};
+ local($heading) = join(''
+ , &make_section_heading($TITLE, $idx_head)
+ , $idx_mark, "\002", $idxref, "\002" );
+ local($pre,$post) = &minimize_open_tags($heading);
+ $index_number++ unless ($no_increment);
+ $no_increment = 0;
+ join('',"<BR>\n" , $pre, $_);
+}
+}
+
+# Returns an index key, given the key passed as the first argument.
+# Not modified for multiple indices.
+sub add_idx_key {
+ local($key) = @_;
+ local($index, $next);
+ if (($index{$key} eq '@' )&&(!($index_printed{$key}))) {
+ if ($SHORT_INDEX) { $index .= "<DD><BR>\n<DT>".&print_key."\n<DD>"; }
+ else { $index .= "<DT><DD><BR>\n<DT>".&print_key."\n<DD>"; }
+ } elsif (($index{$key})&&(!($index_printed{$key}))) {
+ if ($SHORT_INDEX) {
+ $next = "<DD>".&print_key."\n : ". &print_idx_links;
+ } else {
+ $next = "<DT>".&print_key."\n<DD>". &print_idx_links;
+ }
+ $index .= $next."\n";
+ $index_printed{$key} = 1;
+ }
+
+ if ($sub_index{$key}) {
+ local($subkey, @subkeys, $subnext, $subindex);
+ @subkeys = sort(split("\004", $sub_index{$key}));
+ if ($SHORT_INDEX) {
+ $index .= "<DD>".&print_key unless $index_printed{$key};
+ $index .= "<DL>\n";
+ } else {
+ $index .= "<DT>".&print_key."\n<DD>" unless $index_printed{$key};
+ $index .= "<DL COMPACT>\n";
+ }
+ foreach $subkey (@subkeys) {
+ $index .= &add_sub_idx_key($subkey) unless ($index_printed{$subkey});
+ }
+ $index .= "</DL>\n";
+ }
+ return $index;
+}
+
+1; # Must be present as the last line.
--- /dev/null
+# This file serves as a place to put initialization code and constants to
+# affect the behavior of latex2html for generating the bacula manuals.
+
+# $LINKPOINT specifies what filename to use to link to when creating
+# index.html. Not that this is a hard link.
+$LINKPOINT='"$OVERALL_TITLE"';
+
+
+# The following must be the last line of this file.
+1;
--- /dev/null
+%%
+%%
+
+\chapter{Volume Utility Tools}
+\label{_UtilityChapter}
+\index[general]{Volume Utility Tools}
+\index[general]{Tools!Volume Utility}
+
+This document describes the utility programs written to aid Bacula users and
+developers in dealing with Volumes external to Bacula.
+
+\section{Specifying the Configuration File}
+\index[general]{Specifying the Configuration File}
+
+Starting with version 1.27, each of the following programs requires a valid
+Storage daemon configuration file (actually, the only part of the
+configuration file that these programs need is the {\bf Device} resource
+definitions). This permits the programs to find the configuration parameters
+for your archive device (generally a tape drive). By default, they read {\bf
+bacula-sd.conf} in the current directory, but you may specify a different
+configuration file using the {\bf -c} option.
+
+
+\section{Specifying a Device Name For a Tape}
+\index[general]{Tape!Specifying a Device Name For a}
+\index[general]{Specifying a Device Name For a Tape}
+
+Each of these programs require a {\bf device-name} where the Volume can be
+found. In the case of a tape, this is the physical device name such as {\bf
+/dev/nst0} or {\bf /dev/rmt/0ubn} depending on your system. For the program to
+work, it must find the identical name in the Device resource of the
+configuration file. See below for specifying Volume names.
+
+Please note that if you have Bacula running and you ant to use
+one of these programs, you will either need to stop the Storage daemon, or
+{\bf unmount} any tape drive you want to use, otherwise the drive
+will {\bf busy} because Bacula is using it.
+
+
+\section{Specifying a Device Name For a File}
+\index[general]{File!Specifying a Device Name For a}
+\index[general]{Specifying a Device Name For a File}
+
+If you are attempting to read or write an archive file rather than a tape, the
+{\bf device-name} should be the full path to the archive location including
+the filename. The filename (last part of the specification) will be stripped
+and used as the Volume name, and the path (first part before the filename)
+must have the same entry in the configuration file. So, the path is equivalent
+to the archive device name, and the filename is equivalent to the volume name.
+
+
+\section{Specifying Volumes}
+\index[general]{Volumes!Specifying}
+\index[general]{Specifying Volumes}
+
+In general, you must specify the Volume name to each of the programs below
+(with the exception of {\bf btape}). The best method to do so is to specify a
+{\bf bootstrap} file on the command line with the {\bf -b} option. As part of
+the bootstrap file, you will then specify the Volume name or Volume names if
+more than one volume is needed. For example, suppose you want to read tapes
+{\bf tape1} and {\bf tape2}. First construct a {\bf bootstrap} file named say,
+{\bf list.bsr} which contains:
+
+\footnotesize
+\begin{verbatim}
+Volume=test1|test2
+\end{verbatim}
+\normalsize
+
+where each Volume is separated by a vertical bar. Then simply use:
+
+\footnotesize
+\begin{verbatim}
+./bls -b list.bsr /dev/nst0
+\end{verbatim}
+\normalsize
+
+In the case of Bacula Volumes that are on files, you may simply append volumes
+as follows:
+
+\footnotesize
+\begin{verbatim}
+./bls /tmp/test1\|test2
+\end{verbatim}
+\normalsize
+
+where the backslash (\textbackslash{}) was necessary as a shell escape to
+permit entering the vertical bar (|).
+
+And finally, if you feel that specifying a Volume name is a bit complicated
+with a bootstrap file, you can use the {\bf -V} option (on all programs except
+{\bf bcopy}) to specify one or more Volume names separated by the vertical bar
+(|). For example,
+
+\footnotesize
+\begin{verbatim}
+./bls -V Vol001 /dev/nst0
+\end{verbatim}
+\normalsize
+
+You may also specify an asterisk (*) to indicate that the program should
+accept any volume. For example:
+
+\footnotesize
+\begin{verbatim}
+./bls -V* /dev/nst0
+\end{verbatim}
+\normalsize
+
+\section{bls}
+\label{bls}
+\index[general]{bls}
+\index[general]{program!bls}
+
+{\bf bls} can be used to do an {\bf ls} type listing of a {\bf Bacula} tape or
+file. It is called:
+
+\footnotesize
+\begin{verbatim}
+Usage: bls [options] <device-name>
+ -b <file> specify a bootstrap file
+ -c <file> specify a config file
+ -d <level> specify debug level
+ -e <file> exclude list
+ -i <file> include list
+ -j list jobs
+ -k list blocks
+ (no j or k option) list saved files
+ -L dump label
+ -p proceed inspite of errors
+ -v be verbose
+ -V specify Volume names (separated by |)
+ -? print this message
+\end{verbatim}
+\normalsize
+
+For example, to list the contents of a tape:
+
+\footnotesize
+\begin{verbatim}
+./bls -V Volume-name /dev/nst0
+\end{verbatim}
+\normalsize
+
+Or to list the contents of a file:
+
+\footnotesize
+\begin{verbatim}
+./bls /tmp/Volume-name
+or
+./bls -V Volume-name /tmp
+\end{verbatim}
+\normalsize
+
+Note that, in the case of a file, the Volume name becomes the filename, so in
+the above example, you will replace the {\bf xxx} with the name of the volume
+(file) you wrote.
+
+Normally if no options are specified, {\bf bls} will produce the equivalent
+output to the {\bf ls -l} command for each file on the tape. Using other
+options listed above, it is possible to display only the Job records, only the
+tape blocks, etc. For example:
+
+\footnotesize
+\begin{verbatim}
+
+./bls /tmp/File002
+bls: butil.c:148 Using device: /tmp
+drwxrwxr-x 3 k k 4096 02-10-19 21:08 /home/kern/bacula/k/src/dird/
+drwxrwxr-x 2 k k 4096 02-10-10 18:59 /home/kern/bacula/k/src/dird/CVS/
+-rw-rw-r-- 1 k k 54 02-07-06 18:02 /home/kern/bacula/k/src/dird/CVS/Root
+-rw-rw-r-- 1 k k 16 02-07-06 18:02 /home/kern/bacula/k/src/dird/CVS/Repository
+-rw-rw-r-- 1 k k 1783 02-10-10 18:59 /home/kern/bacula/k/src/dird/CVS/Entries
+-rw-rw-r-- 1 k k 97506 02-10-18 21:07 /home/kern/bacula/k/src/dird/Makefile
+-rw-r--r-- 1 k k 3513 02-10-18 21:02 /home/kern/bacula/k/src/dird/Makefile.in
+-rw-rw-r-- 1 k k 4669 02-07-06 18:02 /home/kern/bacula/k/src/dird/README-config
+-rw-r--r-- 1 k k 4391 02-09-14 16:51 /home/kern/bacula/k/src/dird/authenticate.c
+-rw-r--r-- 1 k k 3609 02-07-07 16:41 /home/kern/bacula/k/src/dird/autoprune.c
+-rw-rw-r-- 1 k k 4418 02-10-18 21:03 /home/kern/bacula/k/src/dird/bacula-dir.conf
+...
+-rw-rw-r-- 1 k k 83 02-08-31 19:19 /home/kern/bacula/k/src/dird/.cvsignore
+bls: Got EOF on device /tmp
+84 files found.
+\end{verbatim}
+\normalsize
+
+\subsection{Listing Jobs}
+\index[general]{Listing Jobs with bls}
+\index[general]{bls!Listing Jobs}
+
+If you are listing a Volume to determine what Jobs to restore, normally the
+{\bf -j} option provides you with most of what you will need as long as you
+don't have multiple clients. For example,
+
+\footnotesize
+\begin{verbatim}
+./bls -j -V Test1 -c stored.conf DDS-4
+bls: butil.c:258 Using device: "DDS-4" for reading.
+11-Jul 11:54 bls: Ready to read from volume "Test1" on device "DDS-4" (/dev/nst0).
+Volume Record: File:blk=0:1 SessId=4 SessTime=1121074625 JobId=0 DataLen=165
+Begin Job Session Record: File:blk=0:2 SessId=4 SessTime=1121074625 JobId=1 Level=F Type=B
+Begin Job Session Record: File:blk=0:3 SessId=5 SessTime=1121074625 JobId=5 Level=F Type=B
+Begin Job Session Record: File:blk=0:6 SessId=3 SessTime=1121074625 JobId=2 Level=F Type=B
+Begin Job Session Record: File:blk=0:13 SessId=2 SessTime=1121074625 JobId=4 Level=F Type=B
+End Job Session Record: File:blk=0:99 SessId=3 SessTime=1121074625 JobId=2 Level=F Type=B
+ Files=168 Bytes=1,732,978 Errors=0 Status=T
+End Job Session Record: File:blk=0:101 SessId=2 SessTime=1121074625 JobId=4 Level=F Type=B
+ Files=168 Bytes=1,732,978 Errors=0 Status=T
+End Job Session Record: File:blk=0:108 SessId=5 SessTime=1121074625 JobId=5 Level=F Type=B
+ Files=168 Bytes=1,732,978 Errors=0 Status=T
+End Job Session Record: File:blk=0:109 SessId=4 SessTime=1121074625 JobId=1 Level=F Type=B
+ Files=168 Bytes=1,732,978 Errors=0 Status=T
+11-Jul 11:54 bls: End of Volume at file 1 on device "DDS-4" (/dev/nst0), Volume "Test1"
+11-Jul 11:54 bls: End of all volumes.
+\end{verbatim}
+\normalsize
+
+shows a full save followed by two incremental saves.
+
+Adding the {\bf -v} option will display virtually all information that is
+available for each record:
+
+\subsection{Listing Blocks}
+\index[general]{Listing Blocks with bls}
+\index[general]{bls!Listing Blocks}
+
+Normally, except for debugging purposes, you will not need to list Bacula
+blocks (the "primitive" unit of Bacula data on the Volume). However, you can
+do so with:
+
+\footnotesize
+\begin{verbatim}
+./bls -k /tmp/File002
+bls: butil.c:148 Using device: /tmp
+Block: 1 size=64512
+Block: 2 size=64512
+...
+Block: 65 size=64512
+Block: 66 size=19195
+bls: Got EOF on device /tmp
+End of File on device
+\end{verbatim}
+\normalsize
+
+By adding the {\bf -v} option, you can get more information, which can be
+useful in knowing what sessions were written to the volume:
+
+\footnotesize
+\begin{verbatim}
+./bls -k -v /tmp/File002
+Volume Label:
+Id : Bacula 0.9 mortal
+VerNo : 10
+VolName : File002
+PrevVolName :
+VolFile : 0
+LabelType : VOL_LABEL
+LabelSize : 147
+PoolName : Default
+MediaType : File
+PoolType : Backup
+HostName :
+Date label written: 2002-10-19 at 21:16
+Block: 1 blen=64512 First rec FI=VOL_LABEL SessId=1 SessTim=1035062102 Strm=0 rlen=147
+Block: 2 blen=64512 First rec FI=6 SessId=1 SessTim=1035062102 Strm=DATA rlen=4087
+Block: 3 blen=64512 First rec FI=12 SessId=1 SessTim=1035062102 Strm=DATA rlen=5902
+Block: 4 blen=64512 First rec FI=19 SessId=1 SessTim=1035062102 Strm=DATA rlen=28382
+...
+Block: 65 blen=64512 First rec FI=83 SessId=1 SessTim=1035062102 Strm=DATA rlen=1873
+Block: 66 blen=19195 First rec FI=83 SessId=1 SessTim=1035062102 Strm=DATA rlen=2973
+bls: Got EOF on device /tmp
+End of File on device
+\end{verbatim}
+\normalsize
+
+Armed with the SessionId and the SessionTime, you can extract just about
+anything.
+
+If you want to know even more, add a second {\bf -v} to the command line to
+get a dump of every record in every block.
+
+\footnotesize
+\begin{verbatim}
+./bls -k -v -v /tmp/File002
+bls: block.c:79 Dump block 80f8ad0: size=64512 BlkNum=1
+ Hdrcksum=b1bdfd6d cksum=b1bdfd6d
+bls: block.c:92 Rec: VId=1 VT=1035062102 FI=VOL_LABEL Strm=0 len=147 p=80f8b40
+bls: block.c:92 Rec: VId=1 VT=1035062102 FI=SOS_LABEL Strm=-7 len=122 p=80f8be7
+bls: block.c:92 Rec: VId=1 VT=1035062102 FI=1 Strm=UATTR len=86 p=80f8c75
+bls: block.c:92 Rec: VId=1 VT=1035062102 FI=2 Strm=UATTR len=90 p=80f8cdf
+bls: block.c:92 Rec: VId=1 VT=1035062102 FI=3 Strm=UATTR len=92 p=80f8d4d
+bls: block.c:92 Rec: VId=1 VT=1035062102 FI=3 Strm=DATA len=54 p=80f8dbd
+bls: block.c:92 Rec: VId=1 VT=1035062102 FI=3 Strm=MD5 len=16 p=80f8e07
+bls: block.c:92 Rec: VId=1 VT=1035062102 FI=4 Strm=UATTR len=98 p=80f8e2b
+bls: block.c:92 Rec: VId=1 VT=1035062102 FI=4 Strm=DATA len=16 p=80f8ea1
+bls: block.c:92 Rec: VId=1 VT=1035062102 FI=4 Strm=MD5 len=16 p=80f8ec5
+bls: block.c:92 Rec: VId=1 VT=1035062102 FI=5 Strm=UATTR len=96 p=80f8ee9
+bls: block.c:92 Rec: VId=1 VT=1035062102 FI=5 Strm=DATA len=1783 p=80f8f5d
+bls: block.c:92 Rec: VId=1 VT=1035062102 FI=5 Strm=MD5 len=16 p=80f9668
+bls: block.c:92 Rec: VId=1 VT=1035062102 FI=6 Strm=UATTR len=95 p=80f968c
+bls: block.c:92 Rec: VId=1 VT=1035062102 FI=6 Strm=DATA len=32768 p=80f96ff
+bls: block.c:92 Rec: VId=1 VT=1035062102 FI=6 Strm=DATA len=32768 p=8101713
+bls: block.c:79 Dump block 80f8ad0: size=64512 BlkNum=2
+ Hdrcksum=9acc1e7f cksum=9acc1e7f
+bls: block.c:92 Rec: VId=1 VT=1035062102 FI=6 Strm=contDATA len=4087 p=80f8b40
+bls: block.c:92 Rec: VId=1 VT=1035062102 FI=6 Strm=DATA len=31970 p=80f9b4b
+bls: block.c:92 Rec: VId=1 VT=1035062102 FI=6 Strm=MD5 len=16 p=8101841
+...
+\end{verbatim}
+\normalsize
+
+\section{bextract}
+\label{bextract}
+\index[general]{Bextract}
+\index[general]{program!bextract}
+
+If you find yourself using {\bf bextract}, you probably have done
+something wrong. For example, if you are trying to recover a file
+but are having problems, please see the \ilink {Restoring When Things Go
+Wrong}{database_restore} section of the Restore chapter of this manual.
+
+Normally, you will restore files by running a {\bf Restore} Job from the {\bf
+Console} program. However, {\bf bextract} can be used to extract a single file
+or a list of files from a Bacula tape or file. In fact, {\bf bextract} can be
+a useful tool to restore files to an empty system assuming you are able to
+boot, you have statically linked {\bf bextract} and you have an appropriate
+{\bf bootstrap} file.
+
+Please note that some of the current limitations of bextract are:
+
+\begin{enumerate}
+\item It cannot restore access control lists (ACL) that have been
+ backed up along with the file data.
+\item It cannot restore Win32 non-portable streams (typically default).
+\item It cannot restore encrypted files.
+\item The command line length is relatively limited,
+ which means that you cannot enter a huge number of volumes. If you need to
+ enter more volumes than the command line supports, please use a bootstrap
+ file (see below).
+\end{enumerate}
+
+
+It is called:
+
+\footnotesize
+\begin{verbatim}
+
+Usage: bextract [-d debug_level] <device-name> <directory-to-store-files>
+ -b <file> specify a bootstrap file
+ -dnn set debug level to nn
+ -e <file> exclude list
+ -i <file> include list
+ -p proceed inspite of I/O errors
+ -V specify Volume names (separated by |)
+ -? print this message
+\end{verbatim}
+\normalsize
+
+where {\bf device-name} is the Archive Device (raw device name or full
+filename) of the device to be read, and {\bf directory-to-store-files} is a
+path prefix to prepend to all the files restored.
+
+NOTE: On Windows systems, if you specify a prefix of say d:/tmp, any file that
+would have been restored to {\bf c:/My Documents} will be restored to {\bf
+d:/tmp/My Documents}. That is, the original drive specification will be
+stripped. If no prefix is specified, the file will be restored to the original
+drive.
+
+\subsection{Extracting with Include or Exclude Lists}
+\index[general]{Lists!Extracting with Include or Exclude}
+\index[general]{Extracting with Include or Exclude Lists}
+
+Using the {\bf -e} option, you can specify a file containing a list of files
+to be excluded. Wildcards can be used in the exclusion list. This option will
+normally be used in conjunction with the {\bf -i} option (see below). Both the
+{\bf -e} and the {\bf -i} options may be specified at the same time as the
+{\bf -b} option. The bootstrap filters will be applied first, then the include
+list, then the exclude list.
+
+Likewise, and probably more importantly, with the {\bf -i} option, you can
+specify a file that contains a list (one file per line) of files and
+directories to include to be restored. The list must contain the full filename
+with the path. If you specify a path name only, all files and subdirectories
+of that path will be restored. If you specify a line containing only the
+filename (e.g. {\bf my-file.txt}) it probably will not be extracted because
+you have not specified the full path.
+
+For example, if the file {\bf include-list} contains:
+
+\footnotesize
+\begin{verbatim}
+/home/kern/bacula
+/usr/local/bin
+\end{verbatim}
+\normalsize
+
+Then the command:
+
+\footnotesize
+\begin{verbatim}
+./bextract -i include-list -V Volume /dev/nst0 /tmp
+\end{verbatim}
+\normalsize
+
+will restore from the Bacula archive {\bf /dev/nst0} all files and directories
+in the backup from {\bf /home/kern/bacula} and from {\bf /usr/local/bin}. The
+restored files will be placed in a file of the original name under the
+directory {\bf /tmp} (i.e. /tmp/home/kern/bacula/... and
+/tmp/usr/local/bin/...).
+
+\subsection{Extracting With a Bootstrap File}
+\index[general]{File!Extracting With a Bootstrap}
+\index[general]{Extracting With a Bootstrap File}
+
+The {\bf -b} option is used to specify a {\bf bootstrap} file containing the
+information needed to restore precisely the files you want. Specifying a {\bf
+bootstrap} file is optional but recommended because it gives you the most
+control over which files will be restored. For more details on the {\bf
+bootstrap} file, please see
+\ilink{Restoring Files with the Bootstrap File}{BootstrapChapter}
+chapter of this document. Note, you may also use a bootstrap file produced by
+the {\bf restore} command. For example:
+
+\footnotesize
+\begin{verbatim}
+./bextract -b bootstrap-file /dev/nst0 /tmp
+\end{verbatim}
+\normalsize
+
+The bootstrap file allows detailed specification of what files you want
+restored (extracted). You may specify a bootstrap file and include and/or
+exclude files at the same time. The bootstrap conditions will first be
+applied, and then each file record seen will be compared to the include and
+exclude lists.
+
+\subsection{Extracting From Multiple Volumes}
+\index[general]{Volumes!Extracting From Multiple}
+\index[general]{Extracting From Multiple Volumes}
+
+If you wish to extract files that span several Volumes, you can specify the
+Volume names in the bootstrap file or you may specify the Volume names on the
+command line by separating them with a vertical bar. See the section above
+under the {\bf bls} program entitled {\bf Listing Multiple Volumes} for more
+information. The same techniques apply equally well to the {\bf bextract}
+program or read the \ilink{Bootstrap}{BootstrapChapter}
+chapter of this document.
+
+\section{bscan}
+\label{bscan}
+\index[general]{bscan}
+\index[general]{program!bscan}
+
+If you find yourself using this program, you have probably done something
+wrong. For example, the best way to recover a lost or damaged Bacula
+database is to reload the database by using the bootstrap file that
+was written when you saved it (default bacula-dir.conf file).
+
+The {\bf bscan} program can be used to re-create a database (catalog)
+records from the backup information written to one or more Volumes.
+This is normally
+needed only if one or more Volumes have been pruned or purged from your
+catalog so that the records on the Volume are no longer in the catalog, or
+for Volumes that you have archived.
+
+With some care, it can also be used to synchronize your existing catalog with
+a Volume. Although we have never seen a case of bscan damaging a
+catalog, since bscan modifies your catalog, we recommend that
+you do a simple ASCII backup of your database before running {\bf bscan} just
+to be sure. See \ilink{Compacting Your Database}{CompactingMySQL} for
+the details of making a copy of your database.
+
+{\bf bscan} can also be useful in a disaster recovery situation, after the
+loss of a hard disk, if you do not have a valid {\bf bootstrap} file for
+reloading your system, or if a Volume has been recycled but not overwritten,
+you can use {\bf bscan} to re-create your database, which can then be used to
+{\bf restore} your system or a file to its previous state.
+
+It is called:
+
+\footnotesize
+\begin{verbatim}
+
+Usage: bscan [options] <bacula-archive>
+ -b bootstrap specify a bootstrap file
+ -c <file> specify configuration file
+ -d <nn> set debug level to nn
+ -m update media info in database
+ -n <name> specify the database name (default bacula)
+ -u <user> specify database user name (default bacula)
+ -P <password> specify database password (default none)
+ -h <host> specify database host (default NULL)
+ -p proceed inspite of I/O errors
+ -r list records
+ -s synchronize or store in database
+ -v verbose
+ -V <Volumes> specify Volume names (separated by |)
+ -w <dir> specify working directory (default from conf file)
+ -? print this message
+\end{verbatim}
+\normalsize
+
+If you are using MySQL or PostgreSQL, there is no need to supply a working
+directory since in that case, bscan knows where the databases are. However, if
+you have provided security on your database, you may need to supply either the
+database name ({\bf -b} option), the user name ({\bf -u} option), and/or the
+password ({\bf -p}) options.
+
+NOTE: before {\bf bscan} can work, it needs at least a bare bones valid
+database. If your database exists but some records are missing because
+they were pruned, then you are all set. If your database was lost or
+destroyed, then you must first ensure that you have the SQL program running
+(MySQL or PostgreSQL), then you must create the Bacula database (normally
+named bacula), and you must create the Bacula tables using the scripts in
+the {\bf cats} directory. This is explained in the
+\ilink{Installation}{CreateDatabase} chapter of the manual. Finally, before
+scanning into an empty database, you must start and stop the Director with
+the appropriate bacula-dir.conf file so that it can create the Client and
+Storage records which are not stored on the Volumes. Without these
+records, scanning is unable to connect the Job records to the proper
+client.
+
+Forgetting for the moment the extra complications of a full rebuild of
+your catalog, let's suppose that you did a backup to Volumes "Vol001"
+and "Vol002", then sometime later all records of one or both those
+Volumes were pruned or purged from the
+database. By using {\bf bscan} you can recreate the catalog entries for
+those Volumes and then use the {\bf restore} command in the Console to restore
+whatever you want. A command something like:
+
+\footnotesize
+\begin{verbatim}
+bscan -c bacula-sd.conf -v -V Vol001\|Vol002 /dev/nst0
+\end{verbatim}
+\normalsize
+
+will give you an idea of what is going to happen without changing
+your catalog. Of course, you may need to change the path to the Storage
+daemon's conf file, the Volume name, and your tape (or disk) device name. This
+command must read the entire tape, so if it has a lot of data, it may take a
+long time, and thus you might want to immediately use the command listed
+below. Note, if you are writing to a disk file, replace the device name with
+the path to the directory that contains the Volumes. This must correspond to
+the Archive Device in the conf file.
+
+Then to actually write or store the records in the catalog, add the {\bf -s}
+option as follows:
+
+\footnotesize
+\begin{verbatim}
+ bscan -s -m -c bacula-sd.conf -v -V Vol001\|Vol002 /dev/nst0
+\end{verbatim}
+\normalsize
+
+When writing to the database, if bscan finds existing records, it will
+generally either update them if something is wrong or leave them alone. Thus
+if the Volumes you are scanning are all or partially in the catalog already, no
+harm will be done to that existing data. Any missing data will simply be
+added.
+
+If you have multiple tapes, you should scan them with:
+
+\footnotesize
+\begin{verbatim}
+ bscan -s -m -c bacula-sd.conf -v -V Vol001\|Vol002\|Vol003 /dev/nst0
+\end{verbatim}
+\normalsize
+
+Since there is a limit on the command line length (511 bytes) accepted
+by {\bf bscan}, if you have too many Volumes, you will need to manually
+create a bootstrap file. See the \ilink{Bootstrap}{BootstrapChapter}
+chapter of this manual for more details, in particular the section
+entitled \ilink{Bootstrap for bscan}{bscanBootstrap}.
+
+You should, always try to specify the tapes in the order they are written.
+However, bscan can handle scanning tapes that are not sequential. Any
+incomplete records at the end of the tape will simply be ignored in that
+case. If you are simply repairing an existing catalog, this may be OK, but
+if you are creating a new catalog from scratch, it will leave your database
+in an incorrect state. If you do not specify all necessary Volumes on a
+single bscan command, bscan will not be able to correctly restore the
+records that span two volumes. In other words, it is much better to
+specify two or three volumes on a single bscan command rather than run
+bscan two or three times, each with a single volume.
+
+
+Note, the restoration process using bscan is not identical to the original
+creation of the catalog data. This is because certain data such as Client
+records and other non-essential data such
+as volume reads, volume mounts, etc is not stored on the Volume, and thus is
+not restored by bscan. The results of bscanning are, however, perfectly valid,
+and will permit restoration of any or all the files in the catalog using the
+normal Bacula console commands. If you are starting with an empty catalog
+and expecting bscan to reconstruct it, you may be a bit disappointed, but
+at a minimum, you must ensure that your bacula-dir.conf file is the same
+as what it previously was -- that is, it must contain all the appropriate
+Client resources so that they will be recreated in your new database {\bf
+before} running bscan. Normally when the Director starts, it will recreate
+any missing Client records in the catalog. Another problem you will have
+is that even if the Volumes (Media records) are recreated in the database,
+they will not have their autochanger status and slots properly set. As a
+result, you will need to repair that by using the {\bf update slots}
+command. There may be other considerations as well. Rather than
+bscanning, you should always attempt to recover you previous catalog
+backup.
+
+
+\subsection{Using bscan to Compare a Volume to an existing Catalog}
+\index[general]{Catalog!Using bscan to Compare a Volume to an existing}
+\index[general]{Using bscan to Compare a Volume to an existing Catalog}
+
+If you wish to compare the contents of a Volume to an existing catalog without
+changing the catalog, you can safely do so if and only if you do {\bf not}
+specify either the {\bf -m} or the {\bf -s} options. However, at this time
+(Bacula version 1.26), the comparison routines are not as good or as thorough
+as they should be, so we don't particularly recommend this mode other than for
+testing.
+
+\subsection{Using bscan to Recreate a Catalog from a Volume}
+\index[general]{Volume!Using bscan to Recreate a Catalog from a Volume}
+\index[general]{Using bscan to Recreate a Catalog from a Volume}
+
+This is the mode for which {\bf bscan} is most useful. You can either {\bf
+bscan} into a freshly created catalog, or directly into your existing catalog
+(after having made an ASCII copy as described above). Normally, you should
+start with a freshly created catalog that contains no data.
+
+Starting with a single Volume named {\bf TestVolume1}, you run a command such
+as:
+
+\footnotesize
+\begin{verbatim}
+./bscan -V TestVolume1 -v -s -m -c bacula-sd.conf /dev/nst0
+\end{verbatim}
+\normalsize
+
+If there is more than one volume, simply append it to the first one separating
+it with a vertical bar. You may need to precede the vertical bar with a
+forward slash escape the shell -- e.g. {\bf
+TestVolume1\textbackslash{}|TestVolume2}. The {\bf -v} option was added for
+verbose output (this can be omitted if desired). The {\bf -s} option that
+tells {\bf bscan} to store information in the database. The physical device
+name {\bf /dev/nst0} is specified after all the options.
+
+{\bf} For example, after having done a full backup of a directory, then two
+incrementals, I reinitialized the SQLite database as described above, and
+using the bootstrap.bsr file noted above, I entered the following command:
+
+\footnotesize
+\begin{verbatim}
+./bscan -b bootstrap.bsr -v -s -c bacula-sd.conf /dev/nst0
+\end{verbatim}
+\normalsize
+
+which produced the following output:
+
+\footnotesize
+\begin{verbatim}
+bscan: bscan.c:182 Using Database: bacula, User: bacula
+bscan: bscan.c:673 Created Pool record for Pool: Default
+bscan: bscan.c:271 Pool type "Backup" is OK.
+bscan: bscan.c:632 Created Media record for Volume: TestVolume1
+bscan: bscan.c:298 Media type "DDS-4" is OK.
+bscan: bscan.c:307 VOL_LABEL: OK for Volume: TestVolume1
+bscan: bscan.c:693 Created Client record for Client: Rufus
+bscan: bscan.c:769 Created new JobId=1 record for original JobId=2
+bscan: bscan.c:717 Created FileSet record "Kerns Files"
+bscan: bscan.c:819 Updated Job termination record for new JobId=1
+bscan: bscan.c:905 Created JobMedia record JobId 1, MediaId 1
+bscan: Got EOF on device /dev/nst0
+bscan: bscan.c:693 Created Client record for Client: Rufus
+bscan: bscan.c:769 Created new JobId=2 record for original JobId=3
+bscan: bscan.c:708 Fileset "Kerns Files" already exists.
+bscan: bscan.c:819 Updated Job termination record for new JobId=2
+bscan: bscan.c:905 Created JobMedia record JobId 2, MediaId 1
+bscan: Got EOF on device /dev/nst0
+bscan: bscan.c:693 Created Client record for Client: Rufus
+bscan: bscan.c:769 Created new JobId=3 record for original JobId=4
+bscan: bscan.c:708 Fileset "Kerns Files" already exists.
+bscan: bscan.c:819 Updated Job termination record for new JobId=3
+bscan: bscan.c:905 Created JobMedia record JobId 3, MediaId 1
+bscan: Got EOF on device /dev/nst0
+bscan: bscan.c:652 Updated Media record at end of Volume: TestVolume1
+bscan: bscan.c:428 End of Volume. VolFiles=3 VolBlocks=57 VolBytes=10,027,437
+\end{verbatim}
+\normalsize
+
+The key points to note are that {\bf bscan} prints a line when each major
+record is created. Due to the volume of output, it does not print a line for
+each file record unless you supply the {\bf -v} option twice or more on the
+command line.
+
+In the case of a Job record, the new JobId will not normally be the same as
+the original Jobid. For example, for the first JobId above, the new JobId is
+1, but the original JobId is 2. This is nothing to be concerned about as it is
+the normal nature of databases. {\bf bscan} will keep everything straight.
+
+Although {\bf bscan} claims that it created a Client record for Client: Rufus
+three times, it was actually only created the first time. This is normal.
+
+You will also notice that it read an end of file after each Job (Got EOF on
+device ...). Finally the last line gives the total statistics for the bscan.
+
+If you had added a second {\bf -v} option to the command line, Bacula would
+have been even more verbose, dumping virtually all the details of each Job
+record it encountered.
+
+Now if you start Bacula and enter a {\bf list jobs} command to the console
+program, you will get:
+
+\footnotesize
+\begin{verbatim}
++-------+----------+------------------+------+-----+----------+----------+---------+
+| JobId | Name | StartTime | Type | Lvl | JobFiles | JobBytes | JobStat |
++-------+----------+------------------+------+-----+----------+----------+---------+
+| 1 | kernsave | 2002-10-07 14:59 | B | F | 84 | 4180207 | T |
+| 2 | kernsave | 2002-10-07 15:00 | B | I | 15 | 2170314 | T |
+| 3 | kernsave | 2002-10-07 15:01 | B | I | 33 | 3662184 | T |
++-------+----------+------------------+------+-----+----------+----------+---------+
+\end{verbatim}
+\normalsize
+
+which corresponds virtually identically with what the database contained
+before it was re-initialized and restored with bscan. All the Jobs and Files
+found on the tape are restored including most of the Media record. The Volume
+(Media) records restored will be marked as {\bf Full} so that they cannot be
+rewritten without operator intervention.
+
+It should be noted that {\bf bscan} cannot restore a database to the exact
+condition it was in previously because a lot of the less important information
+contained in the database is not saved to the tape. Nevertheless, the
+reconstruction is sufficiently complete, that you can run {\bf restore}
+against it and get valid results.
+
+An interesting aspect of restoring a catalog backup using {\bf bscan} is
+that the backup was made while Bacula was running and writing to a tape. At
+the point the backup of the catalog is made, the tape Bacula is writing to
+will have say 10 files on it, but after the catalog backup is made, there
+will be 11 files on the tape Bacula is writing. This there is a difference
+between what is contained in the backed up catalog and what is actually on
+the tape. If after restoring a catalog, you attempt to write on the same
+tape that was used to backup the catalog, Bacula will detect the difference
+in the number of files registered in the catalog compared to what is on the
+tape, and will mark the tape in error.
+
+There are two solutions to this problem. The first is possibly the simplest
+and is to mark the volume as Used before doing any backups. The second is
+to manually correct the number of files listed in the Media record of the
+catalog. This procedure is documented elsewhere in the manual and involves
+using the {\bf update volume} command in {\bf bconsole}.
+
+\subsection{Using bscan to Correct the Volume File Count}
+\index[general]{Using bscan to Correct the Volume File Count}
+\index[general]{Count!Using bscan to Correct the Volume File Count}
+
+If the Storage daemon crashes during a backup Job, the catalog will not be
+properly updated for the Volume being used at the time of the crash. This
+means that the Storage daemon will have written say 20 files on the tape, but
+the catalog record for the Volume indicates only 19 files.
+
+Bacula refuses to write on a tape that contains a different number of files
+from what is in the catalog. To correct this situation, you may run a {\bf
+bscan} with the {\bf -m} option (but {\bf without} the {\bf -s} option) to
+update only the final Media record for the Volumes read.
+
+\subsection{After bscan}
+\index[general]{After bscan}
+\index[general]{Bscan!After}
+
+If you use {\bf bscan} to enter the contents of the Volume into an existing
+catalog, you should be aware that the records you entered may be immediately
+pruned during the next job, particularly if the Volume is very old or had been
+previously purged. To avoid this, after running {\bf bscan}, you can manually
+set the volume status (VolStatus) to {\bf Read-Only} by using the {\bf update}
+command in the catalog. This will allow you to restore from the volume without
+having it immediately purged. When you have restored and backed up the data,
+you can reset the VolStatus to {\bf Used} and the Volume will be purged from
+the catalog.
+
+\section{bcopy}
+\label{bcopy}
+\index[general]{Bcopy}
+\index[general]{program!bcopy}
+
+The {\bf bcopy} program can be used to copy one {\bf Bacula} archive file to
+another. For example, you may copy a tape to a file, a file to a tape, a file
+to a file, or a tape to a tape. For tape to tape, you will need two tape
+drives. (a later version is planned that will buffer it to disk). In the
+process of making the copy, no record of the information written to the new
+Volume is stored in the catalog. This means that the new Volume, though it
+contains valid backup data, cannot be accessed directly from existing catalog
+entries. If you wish to be able to use the Volume with the Console restore
+command, for example, you must first bscan the new Volume into the catalog.
+
+\subsection{bcopy Command Options}
+\index[general]{Options!bcopy Command}
+\index[general]{Bcopy Command Options}
+
+\footnotesize
+\begin{verbatim}
+Usage: bcopy [-d debug_level] <input-archive> <output-archive>
+ -b bootstrap specify a bootstrap file
+ -c <file> specify configuration file
+ -dnn set debug level to nn
+ -i specify input Volume names (separated by |)
+ -o specify output Volume names (separated by |)
+ -p proceed inspite of I/O errors
+ -v verbose
+ -w dir specify working directory (default /tmp)
+ -? print this message
+\end{verbatim}
+\normalsize
+
+By using a {\bf bootstrap} file, you can copy parts of a Bacula archive file
+to another archive.
+
+One of the objectives of this program is to be able to recover as much data as
+possible from a damaged tape. However, the current version does not yet have
+this feature.
+
+As this is a new program, any feedback on its use would be appreciated. In
+addition, I only have a single tape drive, so I have never been able to test
+this program with two tape drives.
+
+\section{btape}
+\label{btape}
+\index[general]{Btape}
+\index[general]{program!btape}
+
+This program permits a number of elementary tape operations via a tty command
+interface. It works only with tapes and not with other kinds of Bacula
+storage media (DVD, File, ...). The {\bf test} command, described below,
+can be very useful for testing older tape drive compatibility problems.
+Aside from initial testing of tape drive compatibility with {\bf Bacula},
+{\bf btape} will be mostly used by developers writing new tape drivers.
+
+{\bf btape} can be dangerous to use with existing {\bf Bacula} tapes because
+it will relabel a tape or write on the tape if so requested regardless that
+the tape may contain valuable data, so please be careful and use it only on
+blank tapes.
+
+To work properly, {\bf btape} needs to read the Storage daemon's configuration
+file. As a default, it will look for {\bf bacula-sd.conf} in the current
+directory. If your configuration file is elsewhere, please use the {\bf -c}
+option to specify where.
+
+The physical device name must be specified on the command line, and this
+same device name must be present in the Storage daemon's configuration file
+read by {\bf btape}
+
+\footnotesize
+\begin{verbatim}
+Usage: btape <options> <device_name>
+ -b <file> specify bootstrap file
+ -c <file> set configuration file to file
+ -d <nn> set debug level to nn
+ -p proceed inspite of I/O errors
+ -s turn off signals
+ -v be verbose
+ -? print this message.
+\end{verbatim}
+\normalsize
+
+\subsection{Using btape to Verify your Tape Drive}
+\index[general]{Using btape to Verify your Tape Drive}
+\index[general]{Drive!Using btape to Verify your Tape}
+
+An important reason for this program is to ensure that a Storage daemon
+configuration file is defined so that Bacula will correctly read and write
+tapes.
+
+It is highly recommended that you run the {\bf test} command before running
+your first Bacula job to ensure that the parameters you have defined for your
+storage device (tape drive) will permit {\bf Bacula} to function properly. You
+only need to mount a blank tape, enter the command, and the output should be
+reasonably self explanatory. Please see the
+\ilink{Tape Testing}{TapeTestingChapter} Chapter of this manual for
+the details.
+
+\subsection{btape Commands}
+\index[general]{Btape Commands}
+\index[general]{Commands!btape}
+
+The full list of commands are:
+
+\footnotesize
+\begin{verbatim}
+ Command Description
+ ======= ===========
+ autochanger test autochanger
+ bsf backspace file
+ bsr backspace record
+ cap list device capabilities
+ clear clear tape errors
+ eod go to end of Bacula data for append
+ eom go to the physical end of medium
+ fill fill tape, write onto second volume
+ unfill read filled tape
+ fsf forward space a file
+ fsr forward space a record
+ help print this command
+ label write a Bacula label to the tape
+ load load a tape
+ quit quit btape
+ rawfill use write() to fill tape
+ readlabel read and print the Bacula tape label
+ rectest test record handling functions
+ rewind rewind the tape
+ scan read() tape block by block to EOT and report
+ scanblocks Bacula read block by block to EOT and report
+ status print tape status
+ test General test Bacula tape functions
+ weof write an EOF on the tape
+ wr write a single Bacula block
+ rr read a single record
+ qfill quick fill command
+\end{verbatim}
+\normalsize
+
+The most useful commands are:
+
+\begin{itemize}
+\item test -- test writing records and EOF marks and reading them back.
+\item fill -- completely fill a volume with records, then write a few records
+ on a second volume, and finally, both volumes will be read back.
+ This command writes blocks containing random data, so your drive will
+ not be able to compress the data, and thus it is a good test of
+ the real physical capacity of your tapes.
+\item readlabel -- read and dump the label on a Bacula tape.
+\item cap -- list the device capabilities as defined in the configuration
+ file and as perceived by the Storage daemon.
+ \end{itemize}
+
+The {\bf readlabel} command can be used to display the details of a Bacula
+tape label. This can be useful if the physical tape label was lost or damaged.
+
+
+In the event that you want to relabel a {\bf Bacula}, you can simply use the
+{\bf label} command which will write over any existing label. However, please
+note for labeling tapes, we recommend that you use the {\bf label} command in
+the {\bf Console} program since it will never overwrite a valid Bacula tape.
+
+\section{Other Programs}
+\index[general]{Programs!Other}
+\index[general]{Other Programs}
+
+The following programs are general utility programs and in general do not need
+a configuration file nor a device name.
+
+\section{bsmtp}
+\label{bsmtp}
+\index[general]{Bsmtp}
+\index[general]{program!bsmtp}
+
+{\bf bsmtp} is a simple mail transport program that permits more flexibility
+than the standard mail programs typically found on Unix systems. It can even
+be used on Windows machines.
+
+It is called:
+
+\footnotesize
+\begin{verbatim}
+Usage: bsmtp [-f from] [-h mailhost] [-s subject] [-c copy] [recipient ...]
+ -c set the Cc: field
+ -dnn set debug level to nn
+ -f set the From: field
+ -h use mailhost:port as the bsmtp server
+ -l limit the lines accepted to nn
+ -s set the Subject: field
+ -? print this message.
+\end{verbatim}
+\normalsize
+
+If the {\bf -f} option is not specified, {\bf bsmtp} will use your userid. If
+the option {\bf -h} is not specified {\bf bsmtp} will use the value in the environment
+variable {\bf bsmtpSERVER} or if there is none {\bf localhost}. By default
+port 25 is used.
+
+If a line count limit is set with the {\bf -l} option, {\bf bsmtp} will
+not send an email with a body text exceeding that number of lines. This
+is especially useful for large restore job reports where the list of
+files restored might produce very long mails your mail-server would
+refuse or crash. However, be aware that you will probably suppress the
+job report and any error messages unless you check the log file written
+by the Director (see the messages resource in this manual for details).
+
+
+{\bf recipients} is a space separated list of email recipients.
+
+The body of the email message is read from standard input.
+
+An example of the use of {\bf bsmtp} would be to put the following statement
+in the {\bf Messages} resource of your {\bf bacula-dir.conf} file. Note, these
+commands should appear on a single line each.
+
+\footnotesize
+\begin{verbatim}
+ mailcommand = "/home/bacula/bin/bsmtp -h mail.domain.com -f \"\(Bacula\) %r\"
+ -s \"Bacula: %t %e of %c %l\" %r"
+ operatorcommand = "/home/bacula/bin/bsmtp -h mail.domain.com -f \"\(Bacula\) %r\"
+ -s \"Bacula: Intervention needed for %j\" %r"
+\end{verbatim}
+\normalsize
+
+Where you replace {\bf /home/bacula/bin} with the path to your {\bf Bacula}
+binary directory, and you replace {\bf mail.domain.com} with the fully
+qualified name of your bsmtp (email) server, which normally listens on port
+25. For more details on the substitution characters (e.g. \%r) used in the
+above line, please see the documentation of the
+\ilink{ MailCommand in the Messages Resource}{mailcommand}
+chapter of this manual.
+
+It is HIGHLY recommended that you test one or two cases by hand to make sure
+that the {\bf mailhost} that you specified is correct and that it will accept
+your email requests. Since {\bf bsmtp} always uses a TCP connection rather
+than writing in the spool file, you may find that your {\bf from} address is
+being rejected because it does not contain a valid domain, or because your
+message is caught in your spam filtering rules. Generally, you should specify
+a fully qualified domain name in the {\bf from} field, and depending on
+whether your bsmtp gateway is Exim or Sendmail, you may need to modify the
+syntax of the from part of the message. Please test.
+
+When running {\bf bsmtp} by hand, you will need to terminate the message by
+entering a ctl-d in column 1 of the last line.
+% TODO: is "column" the correct terminology for this?
+
+If you are getting incorrect dates (e.g. 1970) and you are
+running with a non-English language setting, you might try adding
+a LANG=''en\_US'' immediately before the bsmtp call.
+
+\section{dbcheck}
+\label{dbcheck}
+\index[general]{Dbcheck}
+\index[general]{program!dbcheck}
+{\bf dbcheck} is a simple program that will search for logical
+inconsistencies in the Bacula tables in your database, and optionally fix them.
+It is a database maintenance routine, in the sense that it can
+detect and remove unused rows, but it is not a database repair
+routine. To repair a database, see the tools furnished by the
+database vendor. Normally dbcheck should never need to be run,
+but if Bacula has crashed or you have a lot of Clients, Pools, or
+Jobs that you have removed, it could be useful.
+
+The {\bf dbcheck} program can be found in
+the {\bf \lt{}bacula-source\gt{}/src/tools} directory of the source
+distribution. Though it is built with the make process, it is not normally
+"installed".
+
+It is called:
+
+\footnotesize
+\begin{verbatim}
+Usage: dbcheck [-c config] [-C catalog name] [-d debug_level]
+<working-directory> <bacula-database> <user> <password> [<dbhost>]
+ -b batch mode
+ -C catalog name in the director conf file
+ -c director conf filename
+ -dnn set debug level to nn
+ -f fix inconsistencies
+ -v verbose
+ -? print this message
+\end{verbatim}
+\normalsize
+
+If the {\bf -c} option is given with the Director's conf file, there is no
+need to enter any of the command line arguments, in particular the working
+directory as dbcheck will read them from the file.
+
+If the {\bf -f} option is specified, {\bf dbcheck} will repair ({\bf fix}) the
+inconsistencies it finds. Otherwise, it will report only.
+
+If the {\bf -b} option is specified, {\bf dbcheck} will run in batch mode, and
+it will proceed to examine and fix (if -f is set) all programmed inconsistency
+checks. If the {\bf -b} option is not specified, {\bf dbcheck} will enter
+interactive mode and prompt with the following:
+
+\footnotesize
+\begin{verbatim}
+Hello, this is the database check/correct program.
+Please select the function you want to perform.
+ 1) Toggle modify database flag
+ 2) Toggle verbose flag
+ 3) Repair bad Filename records
+ 4) Repair bad Path records
+ 5) Eliminate duplicate Filename records
+ 6) Eliminate duplicate Path records
+ 7) Eliminate orphaned Jobmedia records
+ 8) Eliminate orphaned File records
+ 9) Eliminate orphaned Path records
+ 10) Eliminate orphaned Filename records
+ 11) Eliminate orphaned FileSet records
+ 12) Eliminate orphaned Client records
+ 13) Eliminate orphaned Job records
+ 14) Eliminate all Admin records
+ 15) Eliminate all Restore records
+ 16) All (3-15)
+ 17) Quit
+Select function number:
+\end{verbatim}
+\normalsize
+
+By entering 1 or 2, you can toggle the modify database flag (-f option) and
+the verbose flag (-v). It can be helpful and reassuring to turn off the modify
+database flag, then select one or more of the consistency checks (items 3
+through 9) to see what will be done, then toggle the modify flag on and re-run
+the check.
+
+The inconsistencies examined are the following:
+
+\begin{itemize}
+\item Duplicate filename records. This can happen if you accidentally run two
+ copies of Bacula at the same time, and they are both adding filenames
+ simultaneously. It is a rare occurrence, but will create an inconsistent
+ database. If this is the case, you will receive error messages during Jobs
+ warning of duplicate database records. If you are not getting these error
+ messages, there is no reason to run this check.
+\item Repair bad Filename records. This checks and corrects filenames that
+ have a trailing slash. They should not.
+\item Repair bad Path records. This checks and corrects path names that do
+ not have a trailing slash. They should.
+\item Duplicate path records. This can happen if you accidentally run two
+ copies of Bacula at the same time, and they are both adding filenames
+ simultaneously. It is a rare occurrence, but will create an inconsistent
+ database. See the item above for why this occurs and how you know it is
+ happening.
+\item Orphaned JobMedia records. This happens when a Job record is deleted
+ (perhaps by a user issued SQL statement), but the corresponding JobMedia
+ record (one for each Volume used in the Job) was not deleted. Normally, this
+ should not happen, and even if it does, these records generally do not take
+ much space in your database. However, by running this check, you can
+ eliminate any such orphans.
+\item Orphaned File records. This happens when a Job record is deleted
+ (perhaps by a user issued SQL statement), but the corresponding File record
+ (one for each Volume used in the Job) was not deleted. Note, searching for
+ these records can be {\bf very} time consuming (i.e. it may take hours) for a
+ large database. Normally this should not happen as Bacula takes care to
+ prevent it. Just the same, this check can remove any orphaned File records.
+ It is recommended that you run this once a year since orphaned File records
+ can take a large amount of space in your database. You might
+ want to ensure that you have indexes on JobId, FilenameId, and
+ PathId for the File table in your catalog before running this
+ command.
+\item Orphaned Path records. This condition happens any time a directory is
+ deleted from your system and all associated Job records have been purged.
+ During standard purging (or pruning) of Job records, Bacula does not check
+ for orphaned Path records. As a consequence, over a period of time, old
+ unused Path records will tend to accumulate and use space in your database.
+ This check will eliminate them. It is recommended that you run this
+ check at least once a year.
+\item Orphaned Filename records. This condition happens any time a file is
+ deleted from your system and all associated Job records have been purged.
+ This can happen quite frequently as there are quite a large number of files
+ that are created and then deleted. In addition, if you do a system update or
+ delete an entire directory, there can be a very large number of Filename
+ records that remain in the catalog but are no longer used.
+
+ During standard purging (or pruning) of Job records, Bacula does not check
+ for orphaned Filename records. As a consequence, over a period of time, old
+ unused Filename records will accumulate and use space in your database. This
+ check will eliminate them. It is strongly recommended that you run this check
+ at least once a year, and for large database (more than 200 Megabytes), it is
+ probably better to run this once every 6 months.
+\item Orphaned Client records. These records can remain in the database long
+ after you have removed a client.
+\item Orphaned Job records. If no client is defined for a job or you do not
+ run a job for a long time, you can accumulate old job records. This option
+ allow you to remove jobs that are not attached to any client (and thus
+ useless).
+\item All Admin records. This command will remove all Admin records,
+ regardless of their age.
+\item All Restore records. This command will remove all Restore records,
+ regardless of their age.
+\end{itemize}
+
+By the way, I personally run dbcheck only where I have messed up
+my database due to a bug in developing Bacula code, so normally
+you should never need to run dbcheck in spite of the
+recommendations given above, which are given so that users don't
+waste their time running dbcheck too often.
+
+\section{bregex}
+\label{bregex}
+\index[general]{bregex}
+\index[general]{program!bregex}
+
+{\bf bregex} is a simple program that will allow you to test
+regular expressions against a file of data. This can be useful
+because the regex libraries on most systems differ, and in
+addition, regex expressions can be complicated.
+
+{\bf bregex} is found in the src/tools directory and it is
+normally installed with your system binaries. To run it, use:
+
+\begin{verbatim}
+Usage: bregex [-d debug_level] -f <data-file>
+ -f specify file of data to be matched
+ -l suppress line numbers
+ -n print lines that do not match
+ -? print this message.
+\end{verbatim}
+
+The \lt{}data-file\gt{} is a filename that contains lines
+of data to be matched (or not) against one or more patterns.
+When the program is run, it will prompt you for a regular
+expression pattern, then apply it one line at a time against
+the data in the file. Each line that matches will be printed
+preceded by its line number. You will then be prompted again
+for another pattern.
+
+Enter an empty line for a pattern to terminate the program. You
+can print only lines that do not match by using the -n option,
+and you can suppress printing of line numbers with the -l option.
+
+This program can be useful for testing regex expressions to be
+applied against a list of filenames.
+
+\section{bwild}
+\label{bwild}
+\index[general]{bwild}
+\index[general]{program!bwild}
+
+{\bf bwild} is a simple program that will allow you to test
+wild-card expressions against a file of data.
+
+{\bf bwild} is found in the src/tools directory and it is
+normally installed with your system binaries. To run it, use:
+
+\begin{verbatim}
+Usage: bwild [-d debug_level] -f <data-file>
+ -f specify file of data to be matched
+ -l suppress line numbers
+ -n print lines that do not match
+ -? print this message.
+\end{verbatim}
+
+The \lt{}data-file\gt{} is a filename that contains lines
+of data to be matched (or not) against one or more patterns.
+When the program is run, it will prompt you for a wild-card
+pattern, then apply it one line at a time against
+the data in the file. Each line that matches will be printed
+preceded by its line number. You will then be prompted again
+for another pattern.
+
+Enter an empty line for a pattern to terminate the program. You
+can print only lines that do not match by using the -n option,
+and you can suppress printing of line numbers with the -l option.
+
+This program can be useful for testing wild expressions to be
+applied against a list of filenames.
+
+\section{testfind}
+\label{testfind}
+\index[general]{Testfind}
+\index[general]{program!testfind}
+
+{\bf testfind} permits listing of files using the same search engine that is
+used for the {\bf Include} resource in Job resources. Note, much of the
+functionality of this program (listing of files to be included) is present in
+the
+\ilink{estimate command}{estimate} in the Console program.
+
+The original use of testfind was to ensure that Bacula's file search engine
+was correct and to print some statistics on file name and path length.
+However, you may find it useful to see what bacula would do with a given {\bf
+Include} resource. The {\bf testfind} program can be found in the {\bf
+\lt{}bacula-source\gt{}/src/tools} directory of the source distribution.
+Though it is built with the make process, it is not normally "installed".
+
+It is called:
+
+\footnotesize
+\begin{verbatim}
+Usage: testfind [-d debug_level] [-] [pattern1 ...]
+ -a print extended attributes (Win32 debug)
+ -dnn set debug level to nn
+ - read pattern(s) from stdin
+ -? print this message.
+Patterns are used for file inclusion -- normally directories.
+Debug level>= 1 prints each file found.
+Debug level>= 10 prints path/file for catalog.
+Errors are always printed.
+Files/paths truncated is a number with len> 255.
+Truncation is only in the catalog.
+\end{verbatim}
+\normalsize
+
+Where a pattern is any filename specification that is valid within an {\bf
+Include} resource definition. If none is specified, {\bf /} (the root
+directory) is assumed. For example:
+
+\footnotesize
+\begin{verbatim}
+./testfind /bin
+\end{verbatim}
+\normalsize
+
+Would print the following:
+
+\footnotesize
+\begin{verbatim}
+Dir: /bin
+Reg: /bin/bash
+Lnk: /bin/bash2 -> bash
+Lnk: /bin/sh -> bash
+Reg: /bin/cpio
+Reg: /bin/ed
+Lnk: /bin/red -> ed
+Reg: /bin/chgrp
+...
+Reg: /bin/ipcalc
+Reg: /bin/usleep
+Reg: /bin/aumix-minimal
+Reg: /bin/mt
+Lnka: /bin/gawk-3.1.0 -> /bin/gawk
+Reg: /bin/pgawk
+Total files : 85
+Max file length: 13
+Max path length: 5
+Files truncated: 0
+Paths truncated: 0
+\end{verbatim}
+\normalsize
+
+Even though {\bf testfind} uses the same search engine as {\bf Bacula}, each
+directory to be listed, must be entered as a separate command line entry or
+entered one line at a time to standard input if the {\bf -} option was
+specified.
+
+Specifying a debug level of one (i.e. {\bf -d1}) on the command line will
+cause {\bf testfind} to print the raw filenames without showing the Bacula
+internal file type, or the link (if any). Debug levels of 10 or greater cause
+the filename and the path to be separated using the same algorithm that is
+used when putting filenames into the Catalog database.
--- /dev/null
+%%
+%%
+
+\chapter{Bacula RPM Packaging FAQ}
+\label{RpmFaqChapter}
+\index[general]{FAQ!Bacula\textsuperscript{\textregistered} - RPM Packaging }
+\index[general]{Bacula\textsuperscript{\textregistered} - RPM Packaging FAQ }
+
+\begin{enumerate}
+\item
+ \ilink{How do I build Bacula for platform xxx?}{faq1}
+\item
+ \ilink{How do I control which database support gets built?}{faq2}
+
+\item
+ \ilink{What other defines are used?}{faq3}
+\item
+ \ilink{I'm getting errors about not having permission when I try to build the
+ packages. Do I need to be root?}{faq4}
+\item
+ \ilink{I'm building my own rpms but on all platforms and compiles I get an
+ unresolved dependency for something called
+ /usr/afsws/bin/pagsh.}{faq5}
+\item
+ \ilink{I'm building my own rpms because you don't publish for my platform.
+ Can I get my packages released to sourceforge for other people to use?}{faq6}
+\item
+ \ilink{Is there an easier way than sorting out all these command line options?}{faq7}
+\item
+ \ilink{I just upgraded from 1.36.x to 1.38.x and now my director daemon won't start. It appears to start but dies silently and I get a "connection refused" error when starting the console. What is wrong?}{faq8}
+\item
+ \ilink{There are a lot of rpm packages. Which packages do I need for what?}{faq9}
+\end{enumerate}
+
+\section{Answers}
+\index[general]{Answers }
+
+\begin{enumerate}
+\item
+ \label{faq1}
+ {\bf How do I build Bacula for platform xxx?}
+ The bacula spec file contains defines to build for several platforms:
+ Red Hat 7.x (rh7), Red Hat 8.0 (rh8), Red Hat 9 (rh9), Fedora Core (fc1,
+ fc3, fc4, fc5, fc6, fc7), Whitebox Enterprise Linux 3.0 (wb3), Red Hat Enterprise Linux
+ (rhel3, rhel4, rhel5), Mandrake 10.x (mdk), Mandriva 2006.x (mdv) CentOS (centos3, centos4, centos5)
+ Scientific Linux (sl3, sl4, sl5) and SuSE (su9, su10, su102, su103). The package build is controlled by a mandatory define set at the beginning of the file. These defines basically just control the dependency information that gets coded into the finished rpm package as well
+ as any special configure options required. The platform define may be edited
+ in the spec file directly (by default all defines are set to 0 or "not set").
+ For example, to build the Red Hat 7.x package find the line in the spec file
+ which reads
+
+\footnotesize
+\begin{verbatim}
+ %define rh7 0
+
+\end{verbatim}
+\normalsize
+
+and edit it to read
+
+\footnotesize
+\begin{verbatim}
+ %define rh7 1
+
+\end{verbatim}
+\normalsize
+
+Alternately you may pass the define on the command line when calling rpmbuild:
+
+
+\footnotesize
+\begin{verbatim}
+ rpmbuild -ba --define "build_rh7 1" bacula.spec
+ rpmbuild --rebuild --define build_rh7 1" bacula-x.x.x-x.src.rpm
+
+\end{verbatim}
+\normalsize
+
+\item
+ \label{faq2}
+ {\bf How do I control which database support gets built?}
+ Another mandatory build define controls which database support is compiled,
+ one of build\_sqlite, build\_mysql or build\_postgresql. To get the MySQL
+ package and support either set the
+
+\footnotesize
+\begin{verbatim}
+ %define mysql 0
+ OR
+ %define mysql4 0
+ OR
+ %define mysql5 0
+
+\end{verbatim}
+\normalsize
+
+to
+
+\footnotesize
+\begin{verbatim}
+ %define mysql 1
+ OR
+ %define mysql4 1
+ OR
+ %define mysql5 1
+
+\end{verbatim}
+\normalsize
+
+in the spec file directly or pass it to rpmbuild on the command line:
+
+\footnotesize
+\begin{verbatim}
+ rpmbuild -ba --define "build_rh7 1" --define "build_mysql 1" bacula.spec
+ rpmbuild -ba --define "build_rh7 1" --define "build_mysql4 1" bacula.spec
+ rpmbuild -ba --define "build_rh7 1" --define "build_mysql5 1" bacula.spec
+
+\end{verbatim}
+\normalsize
+
+\item
+ \label{faq3}
+ {\bf What other defines are used?}
+ Three other building defines of note are the depkgs\_version, docs\_version and
+ \_rescuever identifiers. These two defines are set with each release and must
+ match the version of those sources that are being used to build the packages.
+ You would not ordinarily need to edit these. See also the Build Options section
+ below for other build time options that can be passed on the command line.
+\item
+ \label{faq4}
+ {\bf I'm getting errors about not having permission when I try to build the
+ packages. Do I need to be root?}
+ No, you do not need to be root and, in fact, it is better practice to
+ build rpm packages as a non-root user. Bacula packages are designed to
+ be built by a regular user but you must make a few changes on your
+ system to do this. If you are building on your own system then the
+ simplest method is to add write permissions for all to the build
+ directory (/usr/src/redhat/, /usr/src/RPM or /usr/src/packages).
+ To accomplish this, execute the following command as root:
+
+\footnotesize
+\begin{verbatim}
+ chmod -R 777 /usr/src/redhat
+ chmod -R 777 /usr/src/RPM
+ chmod -R 777 /usr/src/packages
+
+\end{verbatim}
+\normalsize
+
+If you are working on a shared system where you can not use the method
+above then you need to recreate the appropriate above directory tree with all
+of its subdirectories inside your home directory. Then create a file named
+
+{\tt .rpmmacros}
+
+in your home directory (or edit the file if it already exists)
+and add the following line:
+
+\footnotesize
+\begin{verbatim}
+ %_topdir /home/myuser/redhat
+
+\end{verbatim}
+\normalsize
+
+Another handy directive for the .rpmmacros file if you wish to suppress the
+creation of debug rpm packages is:
+
+\footnotesize
+\begin{verbatim}
+ %debug_package %{nil}
+
+\end{verbatim}
+
+\normalsize
+
+\item
+ \label{faq5}
+ {\bf I'm building my own rpms but on all platforms and compiles I get an
+ unresolved dependency for something called /usr/afsws/bin/pagsh.} This
+ is a shell from the OpenAFS (Andrew File System). If you are seeing
+ this then you chose to include the docs/examples directory in your
+ package. One of the example scripts in this directory is a pagsh
+ script. Rpmbuild, when scanning for dependencies, looks at the shebang
+ line of all packaged scripts in addition to checking shared libraries.
+ To avoid this do not package the examples directory. If you are seeing this
+ problem you are building a very old bacula package as the examples have been
+ removed from the doc packaging.
+
+\item
+ \label{faq6}
+ {\bf I'm building my own rpms because you don't publish for my platform.
+ Can I get my packages released to sourceforge for other people to use?} Yes,
+ contributions from users are accepted and appreciated. Please examine the
+ directory platforms/contrib-rpm in the source code for further information.
+
+\item
+ \label{faq7}
+ {\bf Is there an easier way than sorting out all these command line options?} Yes,
+ there is a gui wizard shell script which you can use to rebuild the src rpm package.
+ Look in the source archive for platforms/contrib-rpm/rpm\_wizard.sh. This script will
+ allow you to specify build options using GNOME dialog screens. It requires zenity.
+
+\item
+ \label{faq8}
+ {\bf I just upgraded from 1.36.x to 1.38.x and now my director daemon
+won't start. It appears to start but dies silently and I get a "connection
+refused" error when starting the console. What is wrong?} Beginning with
+1.38 the rpm packages are configured to run the director and storage
+daemons as a non-root user. The file daemon runs as user root and group
+bacula, the storage daemon as user bacula and group disk, and the director
+as user bacula and group bacula. If you are upgrading you will need to
+change some file permissions for things to work. Execute the following
+commands as root:
+
+\footnotesize
+\begin{verbatim}
+ chown bacula.bacula /var/bacula/*
+ chown root.bacula /var/bacula/bacula-fd.9102.state
+ chown bacula.disk /var/bacula/bacula-sd.9103.state
+
+\end{verbatim}
+\normalsize
+
+Further, if you are using File storage volumes rather than tapes those
+files will also need to have ownership set to user bacula and group bacula.
+
+\item
+ \label{faq9}
+ {\bf There are a lot of rpm packages. Which packages do I need for
+what?} For a bacula server you need to select the packsge based upon your
+preferred catalog database: one of bacula-mysql, bacula-postgresql or
+bacula-sqlite. If your system does not provide an mtx package you also
+need bacula-mtx to satisfy that dependancy. For a client machine you need
+only install bacula-client. Optionally, for either server or client
+machines, you may install a graphical console bacula-gconsole and/or
+bacula-wxconsole. The Bacula Administration Tool is installed with the
+bacula-bat package. One last package, bacula-updatedb is required only when
+upgrading a server more than one database revision level.
+
+
+
+\item {\bf Support for RHEL3/4/5, CentOS 3/4/5, Scientific Linux 3/4/5 and x86\_64}
+ The examples below show
+ explicit build support for RHEL4 and CentOS 4. Build support
+ for x86\_64 has also been added.
+\end{enumerate}
+
+\footnotesize
+\begin{verbatim}
+Build with one of these 3 commands:
+
+rpmbuild --rebuild \
+ --define "build_rhel4 1" \
+ --define "build_sqlite 1" \
+ bacula-1.38.3-1.src.rpm
+
+rpmbuild --rebuild \
+ --define "build_rhel4 1" \
+ --define "build_postgresql 1" \
+ bacula-1.38.3-1.src.rpm
+
+rpmbuild --rebuild \
+ --define "build_rhel4 1" \
+ --define "build_mysql4 1" \
+ bacula-1.38.3-1.src.rpm
+
+For CentOS substitute '--define "build_centos4 1"' in place of rhel4.
+For Scientific Linux substitute '--define "build_sl4 1"' in place of rhel4.
+
+For 64 bit support add '--define "build_x86_64 1"'
+\end{verbatim}
+\normalsize
+
+\section{Build Options}
+\index[general]{Build Options}
+The spec file currently supports building on the following platforms:
+\footnotesize
+\begin{verbatim}
+Red Hat builds
+--define "build_rh7 1"
+--define "build_rh8 1"
+--define "build_rh9 1"
+
+Fedora Core build
+--define "build_fc1 1"
+--define "build_fc3 1"
+--define "build_fc4 1"
+--define "build_fc5 1"
+--define "build_fc6 1"
+--define "build_fc7 1"
+
+Whitebox Enterprise build
+--define "build_wb3 1"
+
+Red Hat Enterprise builds
+--define "build_rhel3 1"
+--define "build_rhel4 1"
+--define "build_rhel5 1"
+
+CentOS build
+--define "build_centos3 1"
+--define "build_centos4 1"
+--define "build_centos5 1"
+
+Scientific Linux build
+--define "build_sl3 1"
+--define "build_sl4 1"
+--define "build_sl5 1"
+
+SuSE build
+--define "build_su9 1"
+--define "build_su10 1"
+--define "build_su102 1"
+--define "build_su103 1"
+
+Mandrake 10.x build
+--define "build_mdk 1"
+
+Mandriva build
+--define "build_mdv 1"
+
+MySQL support:
+for mysql 3.23.x support define this
+--define "build_mysql 1"
+if using mysql 4.x define this,
+currently: Mandrake 10.x, Mandriva 2006.0, SuSE 9.x & 10.0, FC4 & RHEL4
+--define "build_mysql4 1"
+if using mysql 5.x define this,
+currently: SuSE 10.1 & FC5
+--define "build_mysql5 1"
+
+PostgreSQL support:
+--define "build_postgresql 1"
+
+Sqlite support:
+--define "build_sqlite 1"
+
+Build the client rpm only in place of one of the above database full builds:
+--define "build_client_only 1"
+
+X86-64 support:
+--define "build_x86_64 1"
+
+Supress build of bgnome-console:
+--define "nobuild_gconsole 1"
+
+Build the WXWindows console:
+requires wxGTK >= 2.6
+--define "build_wxconsole 1"
+
+Build the Bacula Administration Tool:
+requires QT >= 4.2
+--define "build_bat 1"
+
+Build python scripting support:
+--define "build_python 1"
+
+Modify the Packager tag for third party packages:
+--define "contrib_packager Your Name <youremail@site.org>"
+
+\end{verbatim}
+\normalsize
+
+\section{RPM Install Problems}
+\index[general]{RPM Install Problems}
+In general the RPMs, once properly built should install correctly.
+However, when attempting to run the daemons, a number of problems
+can occur:
+\begin{itemize}
+\item [Wrong /var/bacula Permissions]
+ By default, the Director and Storage daemon do not run with
+ root permission. If the /var/bacula is owned by root, then it
+ is possible that the Director and the Storage daemon will not
+ be able to access this directory, which is used as the Working
+ Directory. To fix this, the easiest thing to do is:
+\begin{verbatim}
+ chown bacula:bacula /var/bacula
+\end{verbatim}
+ Note: as of 1.38.8 /var/bacula is installed root:bacula with
+ permissions 770.
+\item [The Storage daemon cannot Access the Tape drive]
+ This can happen in some older RPM releases where the Storage
+ daemon ran under userid bacula, group bacula. There are two
+ ways of fixing this: the best is to modify the /etc/init.d/bacula-sd
+ file so that it starts the Storage daemon with group "disk".
+ The second way to fix the problem is to change the permissions
+ of your tape drive (usually /dev/nst0) so that Bacula can access it.
+ You will probably need to change the permissions of the SCSI control
+ device as well, which is usually /dev/sg0. The exact names depend
+ on your configuration, please see the Tape Testing chapter for
+ more information on devices.
+\end{itemize}
+
--- /dev/null
+/*
+ * html2latex
+ */
+
+available {
+ sun4_sunos.4
+ sun4_solaris.2
+ rs_aix.3
+ rs_aix.4
+ sgi_irix
+}
+
+description {
+ From Jeffrey Schaefer, Geometry Center. Translates HTML document to LaTeX
+}
+
+install {
+ bin/html2latex /afs/rpi.edu/dept/acs/rpinfo/filters/GChtml2latex/html2latex
+ bin/html2latex.tag /afs/rpi.edu/dept/acs/rpinfo/filters/GChtml2latex/html2latex.tag
+ bin/html2latex-local.tag /afs/rpi.edu/dept/acs/rpinfo/filters/GChtml2latex/html2latex-local.tag
+ bin/webtex2latex.tag /afs/rpi.edu/dept/acs/rpinfo/filters/GChtml2latex/webtex2latex.tag
+ man/man1/html2latex.1 /afs/rpi.edu/dept/acs/rpinfo/filters/GChtml2latex/html2latex.1
+}
--- /dev/null
+#!/usr/bin/perl -w
+#
+use strict;
+
+# Used to change the names of the image files generated by latex2html from imgxx.png
+# to meaningful names. Provision is made to go either from or to the meaningful names.
+# The meaningful names are obtained from a file called imagename_translations, which
+# is generated by extensions to latex2html in the make_image_file subroutine in
+# bacula.perl.
+
+# Opens the file imagename_translations and reads the contents into a hash.
+# The hash is creaed with the imgxx.png files as the key if processing TO
+# meaningful filenames, and with the meaningful filenames as the key if
+# processing FROM meaningful filenames.
+# Then opens the html file(s) indicated in the command-line arguments and
+# changes all image references according to the translations described in the
+# above file. Finally, it renames the image files.
+#
+# Original creation: 3-27-05 by Karl Cunningham.
+# Modified 5-21-05 to go FROM and TO meaningful filenames.
+#
+my $TRANSFILE = "imagename_translations";
+my $path;
+
+# Loads the contents of $TRANSFILE file into the hash referenced in the first
+# argument. The hash is loaded to translate old to new if $direction is 0,
+# otherwise it is loaded to translate new to old. In this context, the
+# 'old' filename is the meaningful name, and the 'new' filename is the
+# imgxx.png filename. It is assumed that the old image is the one that
+# latex2html has used as the source to create the imgxx.png filename.
+# The filename extension is taken from the file
+sub read_transfile {
+ my ($trans,$direction) = @_;
+
+ if (!open IN,"<$path$TRANSFILE") {
+ print "WARNING: Cannot open image translation file $path$TRANSFILE for reading\n";
+ print " Image filename translation aborted\n\n";
+ exit 0;
+ }
+
+ while (<IN>) {
+ chomp;
+ my ($new,$old) = split(/\001/);
+
+ # Old filenames will usually have a leading ./ which we don't need.
+ $old =~ s/^\.\///;
+
+ # The filename extension of the old filename must be made to match
+ # the new filename because it indicates the encoding format of the image.
+ my ($ext) = $new =~ /(\.[^\.]*)$/;
+ $old =~ s/\.[^\.]*$/$ext/;
+ if ($direction == 0) {
+ $trans->{$new} = $old;
+ } else {
+ $trans->{$old} = $new;
+ }
+ }
+ close IN;
+}
+
+# Translates the image names in the file given as the first argument, according to
+# the translations in the hash that is given as the second argument.
+# The file contents are read in entirely into a string, the string is processed, and
+# the file contents are then written. No particular care is taken to ensure that the
+# file is not lost if a system failure occurs at an inopportune time. It is assumed
+# that the html files being processed here can be recreated on demand.
+#
+# Links to other files are added to the %filelist for processing. That way,
+# all linked files will be processed (assuming they are local).
+sub translate_html {
+ my ($filename,$trans,$filelist) = @_;
+ my ($contents,$out,$this,$img,$dest);
+ my $cnt = 0;
+
+ # If the filename is an external link ignore it. And drop any file:// from
+ # the filename.
+ $filename =~ /^(http|ftp|mailto)\:/ and return 0;
+ $filename =~ s/^file\:\/\///;
+ # Load the contents of the html file.
+ if (!open IF,"<$path$filename") {
+ print "WARNING: Cannot open $path$filename for reading\n";
+ print " Image Filename Translation aborted\n\n";
+ exit 0;
+ }
+
+ while (<IF>) {
+ $contents .= $_;
+ }
+ close IF;
+
+ # Now do the translation...
+ # First, search for an image filename.
+ while ($contents =~ /\<\s*IMG[^\>]*SRC=\"/si) {
+ $contents = $';
+ $out .= $` . $&;
+
+ # The next thing is an image name. Get it and translate it.
+ $contents =~ /^(.*?)\"/s;
+ $contents = $';
+ $this = $&;
+ $img = $1;
+ # If the image is in our list of ones to be translated, do it
+ # and feed the result to the output.
+ $cnt += $this =~ s/$img/$trans->{$img}/ if (defined($trans->{$img}));
+ $out .= $this;
+ }
+ $out .= $contents;
+
+ # Now send the translated text to the html file, overwriting what's there.
+ open OF,">$path$filename" or die "Cannot open $path$filename for writing\n";
+ print OF $out;
+ close OF;
+
+ # Now look for any links to other files and add them to the list of files to do.
+ while ($out =~ /\<\s*A[^\>]*HREF=\"(.*?)\"/si) {
+ $out = $';
+ $dest = $1;
+ # Drop an # and anything after it.
+ $dest =~ s/\#.*//;
+ $filelist->{$dest} = '' if $dest;
+ }
+ return $cnt;
+}
+
+# REnames the image files spefified in the %translate hash.
+sub rename_images {
+ my $translate = shift;
+ my ($response);
+
+ foreach (keys(%$translate)) {
+ if (! $translate->{$_}) {
+ print " WARNING: No destination Filename for $_\n";
+ } else {
+ $response = `mv -f $path$_ $path$translate->{$_} 2>&1`;
+ $response and print "ERROR from system $response\n";
+ }
+ }
+}
+
+#################################################
+############# MAIN #############################
+################################################
+
+# %filelist starts out with keys from the @ARGV list. As files are processed,
+# any links to other files are added to the %filelist. A hash of processed
+# files is kept so we don't do any twice.
+
+# The first argument must be either --to_meaningful_names or --from_meaningful_names
+
+my (%translate,$search_regex,%filelist,%completed,$thisfile);
+my ($cnt,$direction);
+
+my $arg0 = shift(@ARGV);
+$arg0 =~ /^(--to_meaningful_names|--from_meaningful_names)$/ or
+ die "ERROR: First argument must be either \'--to_meaningful_names\' or \'--from_meaningful_names\'\n";
+
+$direction = ($arg0 eq '--to_meaningful_names') ? 0 : 1;
+
+(@ARGV) or die "ERROR: Filename(s) to process must be given as arguments\n";
+
+# Use the first argument to get the path to the file of translations.
+my $tmp = $ARGV[0];
+($path) = $tmp =~ /(.*\/)/;
+$path = '' unless $path;
+
+read_transfile(\%translate,$direction);
+
+foreach (@ARGV) {
+ # Strip the path from the filename, and use it later on.
+ if (s/(.*\/)//) {
+ $path = $1;
+ } else {
+ $path = '';
+ }
+ $filelist{$_} = '';
+
+ while ($thisfile = (keys(%filelist))[0]) {
+ $cnt += translate_html($thisfile,\%translate,\%filelist) if (!exists($completed{$thisfile}));
+ delete($filelist{$thisfile});
+ $completed{$thisfile} = '';
+ }
+ print "translate_images.pl: $cnt image filenames translated ",($direction)?"from":"to"," meaningful names\n";
+}
+
+rename_images(\%translate);
--- /dev/null
+#!/bin/sh
+#
+# Script file to update the Bacula version
+#
+out=/tmp/$$
+VERSION=`sed -n -e 's/^.*VERSION.*"\(.*\)"$/\1/p' /home/kern/bacula/k/src/version.h`
+DATE=`sed -n -e 's/^.*[ \t]*BDATE.*"\(.*\)"$/\1/p' /home/kern/bacula/k/src/version.h`
+. ./do_echo
+sed -f ${out} version.tex.in >version.tex
+rm -f ${out}
--- /dev/null
+#!/bin/sh
+#
+# Script file to update the Bacula version
+#
+out=/tmp/$$
+VERSION=`sed -n -e 's/^.*VERSION.*"\(.*\)"$/\1/p' @bacula@/src/version.h`
+DATE=`sed -n -e 's/^.*[ \t]*BDATE.*"\(.*\)"$/\1/p' @bacula@/src/version.h`
+. ./do_echo
+sed -f ${out} version.tex.in >version.tex
+rm -f ${out}
--- /dev/null
+%%
+%%
+%% The following characters must be preceded by a backslash
+%% to be entered as printable characters:
+%%
+%% # $ % & ~ _ ^ \ { }
+%%
+
+\documentclass[11pt,a4paper]{book}
+\usepackage{html}
+\usepackage{float}
+\usepackage{graphicx}
+\usepackage{bacula}
+\usepackage{longtable}
+\usepackage{makeidx}
+\usepackage{index}
+\usepackage{setspace}
+\usepackage{hyperref}
+\usepackage{url}
+
+
+\makeindex
+\newindex{general}{idx}{ind}{General Index}
+
+\sloppy
+
+\begin{document}
+\sloppy
+
+\newfont{\bighead}{cmr17 at 36pt}
+\parskip 10pt
+\parindent 0pt
+
+\title{\includegraphics{./bacula-logo.eps} \\ \bigskip
+ \Huge{Bacula Utility Programs}
+ \begin{center}
+ \large{It comes in the night and sucks
+ the essence from your computers. }
+ \end{center}
+}
+
+
+\author{Kern Sibbald}
+\date{\vspace{1.0in}\today \\
+ This manual documents Bacula version \input{version} \\
+ \vspace{0.2in}
+ Copyright \copyright 1999-2007, Free Software Foundation Europe
+ e.V. \\
+ \vspace{0.2in}
+ Permission is granted to copy, distribute and/or modify this document under the terms of the
+ GNU Free Documentation License, Version 1.2 published by the Free Software Foundation;
+ with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+ A copy of the license is included in the section entitled "GNU Free Documentation License".
+}
+
+\maketitle
+
+\clearpage
+\tableofcontents
+\clearpage
+\listoffigures
+\clearpage
+\listoftables
+\clearpage
+
+\include{progs}
+\include{bimagemgr-chapter}
+\include{rpm-faq}
+\include{fdl}
+
+
+% The following line tells link_resolver.pl to not include these files:
+% nolinks developersi baculai-dir baculai-fd baculai-sd baculai-console baculai-main
+
+% pull in the index
+\clearpage
+\printindex[general]
+
+\end{document}
--- /dev/null
+2.3.6 (04 November 2007)
--- /dev/null
+@VERSION@ (@DATE@)
projects / bacula / docs / commitdiff